agent-dx-cli-scale

Agent DX CLI 评分表

使用此技能根据 Agent 优先设计原则评估任意 CLI。每个维度按 0–3 打分,然后求和,总分在 0–21 之间。

人类 DX 优化的是可发现性与容错性。 Agent DX 优化的是可预测性与纵深防御。 — 你需要为 AI Agent 重写你的 CLI

---

评分维度

1. 机器可读输出

Agent 能否在不依赖启发式规则的情况下解析 CLI 的输出?

分值	标准
0	仅面向人类的输出(表格、颜色代码、散文)。没有可用的结构化格式。
1	存在 --output json 或同类选项,但在各命令之间不完整或不一致。
2	所有命令均输出一致的 JSON。错误同样以结构化 JSON 返回。
3	分页结果采用 NDJSON 流式输出。在非 TTY(管道)环境中,结构化输出为默认行为。

2. 原始载荷输入

Agent 能否不经转换、无需专用参数,直接发送完整的 API 载荷?

分值	标准
0	仅有专用参数,无法传入结构化输入。
1	部分命令接受 --json 或 stdin JSON,但多数命令仍需使用参数。
2	所有修改类命令都接受直接映射到底层 API 结构的原始 JSON 载荷。
3	原始载荷与便捷参数并重。Agent 可将 API 结构作为文档使用,且无任何转换损失。

3. 结构自省

Agent 能否在运行时发现 CLI 的接受范围,而无需预先填充的文档?

分值	标准
0	仅有 --help 文本,没有机器可读的结构描述。
1	部分功能面支持 --help --json 或 describe 命令,但不完整。
2	所有命令均以 JSON 形式提供完整的结构自省,包括参数、类型与必填字段。
3	实时、运行时解析的结构(例如来自发现文档),始终反映当前 API 版本。包含权限范围、枚举值与嵌套类型。

4. 上下文窗口管控

该命令行是否帮助 Agent 控制响应体积，以保护其上下文窗口？

分数	标准
0	返回完整的 API 响应，无法限制字段或分页。
1	部分命令支持 --fields 或字段掩码。
2	所有读取命令均支持字段掩码。通过 --page-all 或同等方式实现分页。
3	流式分页（每页输出 NDJSON）。上下文或技能文件中明确说明字段掩码的使用方法。命令行主动防止 Agent 浪费 token。

5. 输入加固

该命令行能否防御 Agent 特有的失败方式（幻觉，而非拼写错误）？

分数	标准
0	除基本类型检查外，没有任何输入校验。
1	对部分输入进行校验，但未覆盖 Agent 特有的幻觉模式（路径遍历、嵌入的查询参数、双重编码）。
2	拒绝资源 ID 中的控制字符、路径遍历（../）、百分号编码段（%2e）以及嵌入的查询参数（?、#）。
3	全面加固：包含以上所有内容，并增加输出路径沙箱限制于当前工作目录（CWD）、HTTP 层百分号编码，以及明确的安全立场——"The agent is not a trusted operator."

6. 安全护栏

Agent 能否在执行前进行校验，响应内容是否经过提示注入清洗？

分数	标准
0	没有 dry-run 模式，也没有响应清洗。
1	部分变更类命令支持 --dry-run。
2	所有变更类命令均支持 --dry-run。Agent 可以在无副作用的情况下校验请求。
3	同时具备 dry-run 与响应清洗（例如通过 Model Armor）以防御嵌入 API 数据中的提示注入。完整的请求→响应闭环均受到防护。

7. Agent 知识打包

该 CLI 是否提供 Agent 能在对话开始时读取的知识格式？

分数	标准
0	仅有 --help 和文档站点，没有面向 Agent 的上下文文件。
1	有一个包含基本用法指导的 CONTEXT.md 或 AGENTS.md。
2	结构化的技能文件（YAML frontmatter + Markdown），涵盖按命令或按 API 层面划分的工作流与不变量。
3	完整的技能库，编码了面向 Agent 的防护规则（"始终使用 --dry-run"、"始终使用 --fields"）。技能有版本号、可被发现，并遵循 OpenClaw 等标准。

---

总分解读

范围	评级	说明
0–5	仅限人类	为人类而构建。Agent 将难以解析，容易臆造输入，且缺乏安全防护。
6–10	Agent 可容忍	Agent 可以使用，但会浪费 token、犯可避免的错误，并需要大量提示词工程来弥补。
11–15	Agent 就绪	对 Agent 支持良好。具备结构化输入输出、输入校验和一定的自省能力，但仍存在一些不足。
16–21	Agent 优先	专为 Agent 构建。具备完整的 schema 自省、全面的输入加固、安全防护以及打包的 Agent 知识。

---

加分项：多入口就绪度

不计分，但请注明该 CLI 是否在同一个二进制文件中提供多种 Agent 入口：

• MCP（stdio JSON-RPC）：类型化的工具调用，无需 shell 转义
• 扩展 / 插件安装：Agent 将该 CLI 视为原生能力
• 无头认证：通过环境变量提供令牌/凭据，无需浏览器重定向