modiqo/cliare

# CLIARE **CLIARE 审计命令行界面的 agent 就绪状态。** Agent 越来越多地将终端作为其操作界面，但大多数 CLI 是为阅读帮助文本的人类设计的。在花费 token 尝试命令之前，agent 框架需要一个不同的契约： - 哪些命令实际存在？ - 哪些 flag 和位置参数可以安全使用？ - 哪些命令具有可解析的 JSON/YAML 输出？ - 哪些路径需要 auth、项目目录、fixtures、网络访问或本地 daemon？ - 哪些“安全”的发现命令会悄悄写入文件？ CLIARE 通过将已发布的 CLI 二进制文件作为黑盒进行测量来回答这些问题。它在有界控制下探测 runtime 行为，记录证据，推断命令表面，检测副作用，并输出命令索引、问题台账、记分卡、单命令摘要、角色报告、CI artifacts 和 agent skills。 CLIARE 代表 **CLI Agent Readiness Evaluation**。 ## 从 CLI 偏移到 Agent 就绪的命令表面 CLIARE 的发音类似于 "Claire"：她关心你的 CLI 是否能被 agent、维护者和安全审查人员可靠地使用。 ### 1. CLI 正在成为 agent 的双手  Agent 越来越多地将 CLI 作为它们的双手：这是连接代码托管平台、云系统、支付服务、内部平台和本地开发者工作流的实用界面。 ``` cargo install cliare cliare metadata --format json ``` ### 2. CLI 表面在增长过程中发生偏移  当 CLI 快速演进时，文档、`--help` 和已发布的二进制文件可能会开始讲述不同的故事。人类可以解决这种偏移。而 agent 往往会以高昂的代价发现它。 ``` cliare measure mycli --out .cliare/mycli --profile standard --refresh ``` ### 3. 偏移变成了 token 消耗  如果没有基于证据的命令索引，agent 框架必须反复重新发现表面：运行 help，尝试 flag，遇到缺少的操作数，回退，然后再次尝试。该循环会消耗 token、延迟和可靠性。 ``` cliare summary --out .cliare/mycli ``` ### 4. CLIARE 像 agent 一样探测 CLI  CLIARE 将已发布的二进制文件作为黑盒进行测试。您可以选择上下文：clean、repository、authenticated、host、fixture-backed 或 CI。CLIARE 记录证据，而不是依赖过时的假设。 ``` cliare measure mycli \ --out .cliare/mycli \ --context authenticated \ --auth-state present \ --execution-mode host \ --profile deep \ --refresh ``` ### 5. 维护者获得发布时的修复队列  对于维护者，CLIARE 将 agent 就绪性差距转化为一个具体的队列：缺失的帮助、令人困惑的诊断、可解析输出差距、不安全的发现副作用、先决条件阻碍以及命令形态偏移。 ``` cliare summary --out .cliare/mycli cliare report maintainer --out .cliare/mycli --format markdown cliare issues list --out .cliare/mycli --format markdown cliare playbook maintainer --target mycli ``` ### 6. 框架获得命令索引  对于 agent 框架，CLIARE 构建了这样一张地图：一个基于证据的命令索引，描述了命令路径、flags、操作数、先决条件、输出契约、置信度、适用性和证据参考。 ``` cliare describe .cliare/mycli --write cliare summary --out .cliare/mycli --format json cliare report harness --out .cliare/mycli --write cliare playbook harness --target mycli ``` 然后框架可以加载： ``` .cliare/mycli/command-index.json .cliare/mycli/AGENT_SKILL.md .cliare/mycli/persona-harness.json ``` ### 7. Skills 教学；索引映射  Skills 很有用，但它们不是命令索引。Skill 可以教授意图、工作流和策略。命令索引告诉框架 CLI 现在实际支持什么。Agent 两者都需要：用于判断的指令，用于导航的证据。 ``` cliare summary --out .cliare/mycli cliare report harness --out .cliare/mycli --format markdown cliare report security --out .cliare/mycli --format markdown cliare issues list --out .cliare/mycli --format human ``` CLIARE 帮助维护者保持 CLI 一致，帮助安全审查人员发现未记录的副作用，并帮助 agent 有目的地使用 CLI，而不是通过反复试验来重新发现语法。 ## 为什么运行 CLIARE？ ### 对于 CLI 维护者 CLIARE 将模糊的“这个 CLI 是否对 agent 友好？”反馈转化为具体的实施队列。 它展示了 agent 在命令发现、帮助覆盖、诊断、输出契约、先决条件和不安全发现行为方面会遇到困难的地方。维护者无需猜测需要改进什么，而是获得基于证据的评估、其对 agent 和框架的意义、相关联的命令、建议的补救措施和验证命令。 收益： - 在发布之前捕获命令形态偏移。 - 根据 agent 影响而不是轶事反馈来确定修复的优先级。 - 为帮助覆盖、诊断、可解析输出和不安全发现行为添加发布门控。 - 为每个发布给下游 agent 框架提供一个经过测量的契约。 ### 对于安全审查人员 CLIARE 捕获二进制文件中未记录的 runtime 行为。 它对每个探针周围的文件系统状态进行快照，并报告来自看似安全的命令（如 help、version、无效 flag 和输出模式探针）的持久副作用。这有助于安全团队在 CLI 暴露给自主 agent 之前发现缓存/配置写入、类凭据路径以及 host/auth 行为。 收益： - 发现看似只读或安全的命令的副作用。 - 将预期的 auth、host、网络、daemon 和 fixture 行为与意外情况区分开来。 - 保留证据参考，用于审查、异常处理和审计跟踪。 - 决定哪些命令可以安全地自主使用，哪些需要策略、沙箱或人工批准。 ### 对于 Agent 框架构建者 CLIARE 创建了一个经过测量的命令表面，框架可以在 agent 探索之前查询它。 框架应使用 `cliare surface query`、`cliare surface explain` 和 `cliare surface list` 来获取紧凑的意图到命令的路由答案。当路由需要审计或调试时，`command-index.json` 仍然是基于证据的事实来源。 收益： - 减少由重复的 `--help`、猜测 flag 和错误恢复循环引起的 token 消耗。 - 通过已知的先决条件、置信度和 agent 适用性进行路由。 - 当 agent 需要机器可读的状态时，优先使用 JSON/YAML 输出。 - 保持 skills 专注于工作流，同时命令索引仍是 runtime 的事实来源。 ## 您会得到什么 一次测量会写入一个 artifact 目录： ``` .cliare// command-index.json # agent-facing command catalog command-index.md # human-readable command catalog condition-dictionary.csv # CSV decoder for report labels and conditions AGENT_SKILL.md # generated guidance agents can read scorecard.json # readiness score, subscores, coverage, findings issues.json # reviewable issue ledger issues.md # human issue report issue-dispositions.json # reviewed decisions, when present persona-maintainer.md # maintainer action packet persona-harness.md # agent harness packet persona-security.md # side-effect and approval packet evidence.jsonl # raw runtime evidence shape.json # inferred command shape findings.sarif # CI/security upload format junit.xml # CI test result format ``` 关键的 artifact 是 `command-index.json`。它记录了命令路径、argv 形式、摘要、置信度、runtime 状态、agent 适用性、flags、位置参数、先决条件、输出契约、差距和证据参考。 ## 阅读测量结果 从单命令摘要开始： ``` cliare summary --out .cliare/mycli ``` `cliare summary` 读取 `scorecard.json`、`issues.json`、`command-index.json` 和 `evidence.jsonl`，并打印出一个简明的评估。每个发现包括： - 评估：CLIARE 发现了什么。 - 意义：为什么它对 agent 或框架的使用很重要。 - 关联命令：附加到该发现的命令路径。 - 证据摘录：来自支持该发现的进程证据的有界 stdout/stderr 片段。 - 建议补救措施：下一步要采取的 CLI 更改或审查操作。 当其他工具或框架需要相同的解释而不必抓取 Markdown 时，请使用 JSON： ``` cliare summary --out .cliare/mycli --format json ``` 然后使用特定角色的命令进行深入分析： | 命令 | 适用场景 | |---|---| | `cliare summary --out .cliare/mycli` | 您需要运行的最短的人类可读评估。 | | `cliare report maintainer --out .cliare/mycli` | 您维护该 CLI 并需要一个优先级的实施队列。 | | `cliare report harness --out .cliare/mycli --write` | 您正在为 agent 准备 command-index 和 harness artifacts。 | | `cliare report security --out .cliare/mycli` | 您需要副作用、auth、host 和批准上下文。 | | `cliare issues list --out .cliare/mycli` | 您需要完整的问题台账或维护者处置。 | | `cliare surface query ... --out .cliare/mycli` | 框架需要紧凑的意图到命令的路由答案。 | | `cliare surface explain ... --out .cliare/mycli` | 框架或审查者需要单个命令的就绪状态、操作数和输出契约。 | | `cliare surface list --out .cliare/mycli` | 您需要已测量命令路径的过滤列表。 | ## 安装 从 crates.io 安装： ``` cargo install cliare cliare metadata --format text ``` 或从 GitHub Releases 安装最新的预编译二进制文件： ``` curl -fsSL https://github.com/modiqo/cliare/releases/latest/download/install.sh | sh cliare metadata --format text ``` 安装程序会检测 macOS/Linux 和 x86_64/aarch64，下载匹配的归档文件，验证 `SHA256SUMS`，并默认将 `cliare` 安装到 `$HOME/.local/bin`。 要安装到其他位置： ``` curl -fsSL https://github.com/modiqo/cliare/releases/latest/download/install.sh | CLIARE_INSTALL_DIR=/usr/local/bin sh ``` 要安装特定版本： ``` curl -fsSL https://github.com/modiqo/cliare/releases/download/v0.1.9/install.sh | CLIARE_VERSION=v0.1.9 sh ``` 或者从源码安装： ``` git clone https://github.com/modiqo/cliare.git cd cliare cargo install --path . cliare metadata --format json ``` 对于本地开发： ``` cargo build --locked --bin cliare ./target/debug/cliare metadata --format json ``` 源码包还包含一个 `justfile`，其中包含用于常见 CLIARE 工作流的可选命令快捷方式。如果您想使用这些方案，请单独安装 [`just`](https://just.systems/)；`cliare` 二进制文件本身并不需要它。 列出可用的方案： ``` just --list ``` 在推送之前运行本地预检门控： ``` just justdev ``` `just justdev` 会运行格式化、workspace 检查、拒绝警告的 clippy、测试、包文件集检查，以及一次快速的 CLIARE-on-CLIARE 测量。 在后台测量大型本地 CLI 表面： ``` just measure-detached supabase just jobs supabase ``` 这会扩展为深度遍历，将 artifacts 写入 `.cliare/supabase` 下： ``` cliare measure supabase --out .cliare/supabase --profile deep --max-depth 12 --max-probes 5000 --concurrency 8 --refresh --detach ``` 当 CLI 需要更多或更少的探索时，覆盖遍历预算： ``` just max_depth=16 max_probes=10000 measure-detached gh just profile=standard max_depth=5 max_probes=256 measure kubectl ``` 对于基于路径的本地二进制文件，传入一个稳定的 artifact id： ``` just measure-detached ./target/release/mycli mycli ``` 查看积累的 artifacts： ``` just review supabase just report supabase security just agent-surface supabase ``` 发布准备工作位于 [RELEASE.md](RELEASE.md) 中。版本历史位于 [CHANGELOG.md](CHANGELOG.md) 中。 ## 快速开始：维护者审计 当您维护一个 CLI 并需要一个修复列表时使用此功能。 ``` cliare measure mycli --out .cliare/mycli --profile standard --refresh cliare summary --out .cliare/mycli cliare report maintainer --out .cliare/mycli --format markdown cliare issues list --out .cliare/mycli --format markdown ``` 用于发布或发布质量审查： ``` cliare measure mycli \ --out .cliare/mycli \ --profile deep \ --max-depth 12 \ --max-probes 5000 \ --concurrency 8 \ --refresh ``` 如果发现是真实的，修复 CLI 并重新运行。如果行为是故意的，记录一个处置，以便 CI 保留证据但不再将其视为未经审查的噪音： ``` cliare issues mark \ --out .cliare/mycli \ --status intentional \ --reason "Direct --help is the canonical help contract." ``` 打印完整的维护者演练指南： ``` cliare playbook maintainer --target mycli ``` ## 快速开始：安全副作用审查 当您需要知道 CLI 在安全发现期间做了什么时使用此功能。 ``` cliare measure mycli --out .cliare/mycli --profile standard --refresh cliare summary --out .cliare/mycli cliare report security --out .cliare/mycli --format markdown cliare issues list --out .cliare/mycli --format markdown ``` CLIARE 的默认执行模式是隔离的。它会清除大多数继承的环境变量，使用沙箱 runtime 目录，限制输出，限制时间，并记录在每个探针周围观察到的文件系统更改。 对于已认证或特定于 host 的审查，请运行显式上下文，这样结果就不会与干净运行混淆： ``` cliare measure mycli \ --out .cliare/mycli \ --context authenticated \ --auth-state present \ --execution-mode host \ --profile deep \ --refresh cliare summary --out .cliare/mycli --context authenticated cliare report security --out .cliare/mycli --context authenticated --format markdown ``` 打印完整的安全演练指南： ``` cliare playbook security --target mycli ``` ## 快速开始：Agent 框架命令索引 当您希望 agent 在调用之前了解 CLI 时使用此功能。 ``` cliare measure mycli --out .cliare/mycli --profile deep --refresh cliare summary --out .cliare/mycli --format json cliare describe .cliare/mycli --write cliare report harness --out .cliare/mycli --write ``` 然后将您的框架指向： ``` .cliare/mycli/AGENT_SKILL.md .cliare/mycli/persona-harness.json .cliare/mycli/command-index.json ``` 解析任务意图： ``` cliare surface query "check job status" --out .cliare/mycli --format json cliare surface query "list issues" --out .cliare/mycli --require-output json --format json cliare surface explain "jobs status" --out .cliare/mycli --format json cliare surface list --out .cliare/mycli --state ready --format json ``` 框架路由应该： 1. 查询 surface 解析器以获取任务意图。 2. 优先匹配 `readiness` 为 `ready` 的项。 3. 将 `conditional` 命令视为需要列出注意事项或先决条件。 4. 当需要读取状态时，优先使用可解析的输出契约。 5. 避免使用 `blocked`、`needs_fixture` 和低置信度路径，除非框架能够满足缺失的上下文。 6. 仅在路由需要完整证据或调试时才打开 `command-index.json`。 打印完整的框架演练指南： ``` cliare playbook harness --target mycli ``` ## 理解 Profiles 大多数用户应该首先选择一个 profile，仅在报告显示存在遍历压力时才调整高级旋钮。 | Profile | 适用场景 | |---|---| | `quick` | 在编辑 help、诊断或单个命令系列时的快速本地冒烟测试。 | | `standard` | 常规的维护者/安全/框架审查循环。 | | `deep` | 发布质量检查、CI 基线、大型命令表面和 agent 表面发布。 | 高级旋钮： | 选项 | 含义 | |---|---| | `--max-depth` | 最大递归命令路径深度。当嵌套命令缺失时增加。 | | `--max-probes` | runtime 探针预算。当出现 `budget_exhausted` 或 `frontier_remaining` 时增加。 | | `--concurrency` | 同时运行的探针。对于不稳定 CLI、共享状态或速率限制应降低。 | | `--timeout-ms` | 每个探针的超时时间。对于缓慢的、基于网络或基于 daemon 的 CLI 应提高。 | | `--execution-mode host` | 使用 host auth/配置/plugins/本地状态。仅在该上下文是故意的时候使用。 | 对于长时间运行： ``` cliare measure mycli --out .cliare/mycli --profile deep --refresh --detach cliare jobs status --out .cliare/mycli ``` ## 特定于上下文的测量 许多 CLI 会根据、项目目录、本地配置、已安装的 plugins、fixtures、网络或 daemons 更改行为。将这些运行分开： ``` cliare measure mycli --out .cliare/mycli --context clean --profile standard --refresh cliare measure mycli \ --out .cliare/mycli \ --context local-context \ --context-workdir /path/to/project \ --profile deep \ --refresh ``` 上下文 artifacts 位于： ``` .cliare/mycli/contexts// ``` 比较上下文： ``` cliare context compare .cliare/mycli/contexts/clean .cliare/mycli/contexts/local-context --write ``` ## CI 用法 CLIARE 在此仓库中提供了一个复合 GitHub Action。 ``` name: CLIARE on: pull_request: push: branches: [main] jobs: cliare: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - uses: dtolnay/rust-toolchain@stable - run: cargo install --git https://github.com/modiqo/cliare.git - uses: modiqo/cliare@main with: target: mycli out: .cliare/mycli profile: standard extra-args: --refresh ``` 该操作会将摘要追加到作业摘要中，上传 artifact 目录，并公开 `scorecard.json`、`summary.md`、`findings.sarif` 和 `junit.xml` 的输出路径。 对于发布门控，保留一个基线并使用 `guard`： ``` cliare guard mycli \ --baseline .cliare-baseline/mycli/scorecard.json \ --policy cliare.policy.json \ --out .cliare/mycli \ --profile deep ``` ## 问题处置 即使发现已被审查，CLIARE 也会让证据保持可见。这意味着 `issues_total` 可以保持非零，而 `action_required` 为零。 有用的状态： | 状态 | 适用场景 | |---|---| | `intentional` | 该行为是故意的并且已记录。 | | `needs-fixture` | 在判断该发现之前，需要安全的操作数或 fixture 数据。 | | `not-applicable` | 该发现不适用于此测量的 profile。 | | `accepted-risk` | 安全/平台所有者已审查并接受剩余风险。 | | `false-positive` | 证据对此 CLI 具有误导性。 | | `deferred` | 该问题是真实的，但已安排在稍后处理。 | 审查队列： ``` cliare issues list --out .cliare/mycli --format markdown cliare issues list --out .cliare/mycli --format json ``` 标记已审查的决定： ``` cliare issues mark \ --out .cliare/mycli \ --status not-applicable \ --reason "This command requires a project fixture and is not part of clean CI." ``` ## Agent Skills CLIARE 可以安装本地 artifact 审查 skills，以便编码 agent 知道如何检查 CLIARE 输出： ``` cliare skills list cliare skills install --agent all --scope project ``` 使用 `--agent claude`、`--agent codex` 或 `--agent cursor` 进行单一集成。使用 `--scope user` 进行用户级别的安装。 ## 命令索引注册表工作流 此仓库包含一个手动工作流，用于构建公共 command-index 条目： ``` Actions -> Extract Command Index PR ``` 输入包括 `artifact_id`、`target`、可选的 `install_command`、`profile`、`max_depth` 和 `max_probes`。 该工作流构建 CLIARE，可选择安装目标 CLI，对其进行测量，将公开审查的 artifacts 复制到 `registry//` 中，并使用测量的命令索引、分数和问题台账打开或更新 pull request。 ## 基准语料库 该仓库包含启动和校准清单： ``` cliare benchmark --manifest benchmarks/local-corpus.json --out .cliare-bench --refresh cliare benchmark --manifest benchmarks/vendor-calibration-corpus.json --out .cliare-vendor-calibration --refresh cliare benchmark --manifest benchmarks/launch-low-pretraining-corpus.json --out .cliare-launch-low-pretraining --refresh cliare benchmark --manifest benchmarks/agent-harness-corpus.json --out .cliare-agent-harness --refresh ``` 低预训练启动语料库侧重于较新且变动较快的 CLI，在这些 CLI 中，生成的命令索引最有可能帮助 agent。 ## 设计文档 设计和实现说明位于 [`docs/`](docs/index.md) 下。从以下内容开始： - [设计索引](docs/index.md) - [用于 agent 就绪 CLI 的 Runtime 证据](docs/papers/runtime-evidence-for-agent-ready-clis.md) - [面向 Agent 框架的 CLI 形态产品简介](docs/papers/cli-shape-product-brief.html) - [角色成果包](docs/guides/persona-outcome-packets.md) - [Agent 就绪 CLI 标准模板](docs/guides/agent-ready-cli-standard-template.md) - [Agent skills 安装](docs/guides/agent-skills-installation.md) - [CLI 基准语料库追踪器](docs/operations/cli-benchmark-corpus-tracker.md) - [维护者手册](docs/guides/maintainer-playbook.md) ## 常见问题 ### CLIARE 是一个二进制 fuzzer 吗？ 不，CLIARE 不是一个二进制 fuzzer。 它是一个用于 CLI agent 就绪状态的黑盒 runtime 审计工具。它以 agent 遇到它的方式测量已发布的 CLI 二进制文件：命令、flags、help 行为、输出格式、先决条件、副作用、auth 假设和失败模式。 fuzzer 试图通过生成大量意外输入来发现崩溃或漏洞。 CLIARE 试图回答一个不同的问题：“自主 agent 能否可靠、安全且低成本地使用此 CLI，而无需通过反复试验重新发现整个命令表面？” 它更像是一个用于 CLI 的基于证据的 OpenAPI/Swagger 生成器和就绪状态记分卡，而不是 fuzzer。 ### 命令索引如何节省 token？ 命令索引允许 agent 在开始试验之前阅读已测量的命令表面。 如果没有索引，agent 必须花费 token 一遍又一遍地重新发现相同的事物：运行 `--help`、猜测子命令、尝试 flags、遇到缺少的操作数、检查错误并回退。该循环非常昂贵，因为每次失败的探针都会消耗 token、延迟和工具调用。 有了 `command-index.json`，框架可以直接通过已知命令进行路由，优先使用可解析的输出模式，遵守先决条件，并避免不安全的发现路径。agent 仍然决定要做什么，但它从证据开始而不是猜测。 ### 为什么命令索引与 skill 文件不同？ skill 文件教授意图、工作流和策略。它可以告诉 agent 如何处理一项任务。 命令索引映射了 CLI 在 runtime 实际支持的内容。它记录了命令路径、flags、位置参数、输出契约、先决条件、置信度、副作用和证据参考。 Agent 两者都需要。Skills 有助于判断。命令索引有助于导航。 ### 当文档、`--help` 和 runtime 行为发生偏移时会发生什么？ CLIARE 将已发布的 CLI 二进制文件视为操作的事实来源。 文档可能已过时。`--help` 可能不完整。二进制文件可以接受未记录的 flags，拒绝文档中出现的示例，需要隐藏的先决条件，或者在看起来安全的命令期间写入文件。 CLIARE 不假设这些表面是一致的。它会探测二进制文件，记录证据，并报告 runtime 契约与 agent 或维护者合理预期不同的地方。 ### 谁应该使用 CLIARE？ CLI 维护者使用 CLIARE 将 agent 就绪性差距转化为发布时的修复队列。 Agent 框架构建者使用 CLIARE 在调用 CLI 之前加载基于证据的命令映射。 安全审查人员使用 CLIARE 在 CLI 暴露给自主 agent 之前发现未记录的副作用、host 假设、auth 行为和不安全的发现路径。 ## 许可证 Apache-2.0。参见 [LICENSE](LICENSE)。

标签：SOC Prime, 代码质量检测, 可视化界面, 开发工具, 通知系统