用 Agent DX CLI Scale 评估与设计面向 AI Agent 的 CLI七轴评分体系与 DESIGN.md 实战印证【免费下载链接】design.mdA format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.项目地址: https://gitcode.com/GitHub_Trending/de/design.md导读Agent DX CLI Scale 是一套面向 AI Agent 的 CLI 设计评分体系源自 Rewrite Your CLI for AI Agents 的设计理念把命令行工具的可代理性agentability拆解为七个可打分、可改进的维度。本文完整讲解这套 0–3 分制评分轴、0–21 总分区间解读与多界面就绪度检查表并结合本仓库中google/design.mdCLI 的源码实现lint 命令、diff 命令、export 命令、输入输出工具逐一印证每个维度的落地方式。读完本文你既能用这套量表评估任意 CLI 的 Agent 友好度也能对照真实开源实现把每条原则翻译成具体的工程决策。一、为什么 CLI 需要一套 Agent 专用评分体系人类使用 CLI 时靠的是终端里的彩色表格、逐字帮助文本和可交互的 tab 补全Agent 使用 CLI 时靠的是解析 stdout、构造 stdin 输入、在上下文中消耗 token。两者的成功标准完全不同Human DX optimizes for discoverability and forgiveness.人类 DX 优化可发现性与宽容度 Agent DX optimizes for predictability and defense-in-depth.Agent DX 优化可预测性与纵深防御人类可以容忍模糊输出并在交互中自我纠正Agent 却会把这些模糊性放大成幻觉、错误输入和安全事故。Agent DX CLI Scale 的用途就是对任意 CLI 按七条轴分别打 0–3 分求和得到 0–21 的总分从而把这个 CLI 适不适合 Agent 用这种模糊感受变成一个可量化、可追踪、可写进验收标准的数字。这套技能的完整定义位于仓库 .agents/skills/agent-dx-cli-scale/SKILL.md本文在此基础上结合本仓库的design.mdCLI 源码展开。二、七大评分轴完整评分标准与解读每根轴的打分层级都有明确、可验证的判据。下面依次给出完整标准。1. Machine-Readable Output机器可读输出核心问题Agent 能否在不依赖启发式猜测的情况下解析 CLI 输出ScoreCriteria0Human-only output (tables, color codes, prose). No structured format available.仅人类可读输出表格、颜色码、散文无任何结构化格式1--output jsonor equivalent exists but is incomplete or inconsistent across commands.存在--output json或等价物但各命令之间不完整、不一致2Consistent JSON output across all commands. Errors also return structured JSON.所有命令输出一致的 JSON错误也以结构化 JSON 返回3NDJSON streaming for paginated results. Structured output is the default in non-TTY (piped) contexts.分页结果支持 NDJSON 流式输出非 TTY/管道场景下结构化输出为默认行为仓库印证design.mdCLI 恰好处于结构化输出为默认的档位。在 utils.ts 中formatOutput只有在--format显式传markdown/md时才走人类可读分支其余一律JSON.stringify(data, null, 2)——即 JSON 是默认值。同时 lint 命令 把findings与summary组织成固定结构输出错误分支如文件不可读也通过process.stderr输出可解析的错误信息并设置非零退出码而非打印堆栈。这正好满足评分 2 级错误也返回结构化 JSON的判据。2. Raw Payload Input原始载荷输入核心问题Agent 能否把完整 API payload 直接送入 CLI而不是翻译成一堆特制 flagScoreCriteria0Only bespoke flags. No way to pass structured input.只有特制 flag无法传入结构化输入1Accepts--jsonor stdin JSON for some commands, but most require flags.部分命令接受--json或 stdin JSON但大多数仍要求 flag2All mutating commands accept a raw JSON payload that maps directly to the underlying API schema.所有变更类命令接受与底层 API schema 直接对应的原始 JSON payload3Raw payload is first-class alongside convenience flags. The agent can use the API schema as documentation with zero translation loss.原始 payload 与便捷 flag 平起平坐Agent 可直接把 API schema 当作文档零转换损耗仓库印证lint/diff/export命令都接受**文件路径或-stdin**两种输入见 utils.ts 的readInput-时从 stdin 逐块读取。这意味着 Agent 可以把任意来源的原始 Markdown 内容经 stdin 送入命令而不必落盘成文件再传路径——这正是结构化输入与便捷参数并存的体现。对于lint这种整个输入就是一段格式规范的文本的命令原始内容天然就是一等公民。3. Schema IntrospectionSchema 自省核心问题Agent 能否在运行时发现 CLI 接受什么而不用依赖预填的文档ScoreCriteria0Only--helptext. No machine-readable schema.只有--help文本无机器可读 schema1--help --jsonor adescribecommand for some surfaces, but incomplete.部分命令面支持--help --json或describe命令但不完整2Full schema introspection for all commands — params, types, required fields — as JSON.所有命令都支持完整 schema 自省——参数、类型、必填字段以 JSON 输出3Live, runtime-resolved schemas (e.g., from a discovery document) that always reflect the current API version. Includes scopes, enums, and nested types.实时、运行时解析的 schema例如来自 discovery document始终反映当前 API 版本包含作用域、枚举与嵌套类型仓库印证design.mdCLI 提供了一个专门为此设计的命令——spec。npx google/design.md spec直接输出 DESIGN.md 格式规范本身--rules追加活动 lint 规则表--rules-only --format json只输出规则表的 JSON 形态。README 中明确写道该命令的用途是 injecting spec context into agent prompts——这相当于把CLI 接受什么样的输入这份机器可读的 schema 直接注入 Agent 的上下文达到评分 2 级以 JSON 暴露参数、类型、必填字段的效果。4. Context Window Discipline上下文窗口自律核心问题CLI 是否帮助 Agent 控制响应体积保护其上下文窗口ScoreCriteria0Returns full API responses with no way to limit fields or paginate.返回完整 API 响应无字段裁剪、无分页1Supports--fieldsor field masks on some commands.部分命令支持--fields或字段掩码2Field masks on all read commands. Pagination with--page-allor equivalent.所有读命令支持字段掩码支持--page-all或等价分页3Streaming pagination (NDJSON per page). Explicit guidance in context/skill files on field mask usage. The CLI actively protects the agent from token waste.按页 NDJSON 流式分页context/skill 文件中对字段掩码用法给出明确指引CLI 主动为 Agent 节省 token仓库印证这一轴的 3 级判据——在 context/skill 文件中对用法给出明确指引——在本仓库有直接对应物.agents/skills/目录存放了面向 Agent 的技能文件例如 agent-dx-cli-scale/SKILL.md 本身就是一份教 Agent 如何评估 CLI的指引而 tdd/SKILL.md、typed-service-contracts/SKILL.md 则编码了每个功能先写测试、错误作为值返回这类强约束。同时lint的默认 JSON 输出把全部 findings 以数组形式一次性给出配合--format控制输出形态避免 Agent 在终端排版上浪费 token。从源码结构看本仓库正是把显式指引 默认精简输出当作保护 Agent 上下文的工程手段。5. Input Hardening输入加固核心问题CLI 是否针对 Agent 特有的失败方式幻觉而非打字错误设防ScoreCriteria0No input validation beyond basic type checks.除基础类型检查外无输入校验1Validates some inputs, but does not cover agent-specific hallucination patterns (path traversals, embedded query params, double encoding).校验部分输入但未覆盖 Agent 特有的幻觉模式路径穿越、内嵌查询参数、双重编码2Rejects control characters, path traversals (../), percent-encoded segments (%2e), and embedded query params (?,#) in resource IDs.拒绝资源 ID 中的控制字符、路径穿越../、百分号编码段%2e、内嵌查询参数?#3Comprehensive hardening: all of the above, plus output path sandboxing to CWD, HTTP-layer percent-encoding, and an explicit security posture — The agent is not a trusted operator.全面加固以上全部外加输出路径沙箱限定在 CWD、HTTP 层百分号编码以及明确的安全姿态——Agent 不是可信操作员仓库印证输入加固在该仓库的文档型 CLI 上体现为对非法输入的防御性处理。readInput会把 ENOENT文件不存在、EACCES权限拒绝等底层错误统一包装成FileReadError并生成人类与 Agent 都可读的友好消息如DESIGN.md not found. Create a DESIGN.md file or pass - to read from stdin.见 utils.ts。此外技能层面 typed-service-contracts/SKILL.md 给出了针对路径穿越的防御模板SafePathSchema用refine(p !p.includes(..), No traversal allowed)拒绝../穿越——这与评分 2 级拒绝路径穿越的判据完全一致且以可复用的代码模板形式沉淀在仓库中。6. Safety Rails安全护栏核心问题Agent 能否在执行前先验证响应是否针对提示注入做了净化ScoreCriteria0No dry-run mode. No response sanitization.无 dry-run 模式无响应净化1--dry-runexists for some mutating commands.部分变更类命令支持--dry-run2--dry-runfor all mutating commands. Agent can validate requests without side effects.所有变更类命令支持--dry-runAgent 可在无副作用的前提下验证请求3Dry-run plus response sanitization (e.g., via Model Armor) to defend against prompt injection embedded in API data. The full request→response loop is defended.dry-run 之外还有响应净化例如 Model Armor防御嵌在 API 数据中的提示注入请求→响应的完整回路都受到防御仓库印证design.mdCLI 的核心命令lint、diff、export本质上都是纯读取与验证操作——lint只读入内容并产出报告diff对两份输入求差而不修改任何文件export把 token 序列化到 stdoutprocess.stdout.write没有任何破坏性副作用。从命令实现看该 CLI 把无副作用作为默认契约Agent 可以放心地对任何输入执行lint/diff来验证而无需担心产生改动。这恰好呼应了评分 2 级Agent can validate requests without side effects的目标——通过设计而非通过--dry-run开关达成。7. Agent Knowledge PackagingAgent 知识打包核心问题CLI 是否以 Agent 在对话开始时即可消费的格式交付知识ScoreCriteria0Only--helpand a docs site. No agent-specific context files.只有--help和文档站点无 Agent 专用上下文文件1ACONTEXT.mdorAGENTS.mdwith basic usage guidance.有CONTEXT.md或AGENTS.md提供基础用法指引2Structured skill files (YAML frontmatter Markdown) covering per-command or per-API-surface workflows and invariants.结构化技能文件——YAML frontmatter Markdown——覆盖按命令或按 API 面的工作流与不变量3Comprehensive skill library encoding agent-specific guardrails (always use --dry-run, always use --fields). Skills are versioned, discoverable, and follow a standard like OpenClaw.完备的技能库编码 Agent 专属护栏如始终使用 --dry-run、始终使用 --fields技能有版本、可发现并遵循 OpenClaw 之类的标准仓库印证这一轴是本文档所在仓库最直接的强项。.agents/skills/目录下是一组带 YAML frontmatter 的 Markdown 技能文件完全符合评分 2 级的判据——frontmatter 里声明name与descriptiondescription 同时承担何时该调用此技能的触发条件正文则给出结构化的工作流。例如agent-dx-cli-scale/SKILL.md本文主体教 Agent 如何评估 CLItdd/SKILL.md把 Red-Green-Refactor 三阶段循环编码为硬性规则Write 1 Test - See it Fail - Write 1 Fix - See it Pass禁止一次性写多个测试typed-service-contracts/SKILL.mdSpec Handler 模式规定Handler 永远不 throw必须把错误映射为 Result 类型ink/SKILL.mdJSON spec 到终端 UI 的渲染技能。这些技能文件既面向人读也面向Agent 在对话开始时加载正是第 7 轴要衡量的交付形态。README 中spec命令的设计把规范本身注入 prompt进一步强化了知识以 Agent 可消费的格式打包这一主题。三、解读总分从 Human-only 到 Agent-first将七根轴的分数相加得到 0–21 的总分按区间对照评级RangeRatingDescription0–5Human-onlyBuilt for humans. Agents will struggle with parsing, hallucinate inputs, and lack safety rails.为人类构建。Agent 会在解析上挣扎、在输入上幻觉且缺乏安全护栏6–10Agent-tolerantAgents can use it, but theyll waste tokens, make avoidable errors, and require heavy prompt engineering to compensate.Agent 能用但会浪费 token、犯可避免的错误需要大量 prompt 工程来弥补11–15Agent-readySolid agent support. Structured I/O, input validation, and some introspection. A few gaps remain.扎实的 Agent 支持结构化 I/O、输入校验与部分自省仍有少量缺口16–21Agent-firstPurpose-built for agents. Full schema introspection, comprehensive input hardening, safety rails, and packaged agent knowledge.为 Agent 量身打造完整 schema 自省、全面输入加固、安全护栏、打包好的 Agent 知识使用方式对目标 CLI 逐轴打分先给出每根轴的 0–3 分并引用判据再求和定位区间。评分的价值不在分数本身而在于它把改进方向显式化——例如某项 CLI 总分落在 6–10 区间通常意味着默认输出不是 JSON轴 1 低分与没有技能文件轴 7 低分是两个最先值得投入的改进点。将该量表沉淀为 Agent 技能正如本仓库所做可以保证每次评估都走同一套判据避免主观漂移。四、Bonus多界面就绪度Multi-Surface Readiness总分之外还有一个不计分的核对清单同一个二进制是否暴露了多个 Agent 可用的界面。逐项勾选即可MCP (stdio JSON-RPC)— 类型化工具调用无需 shell 转义typed tool invocation, no shell escapingExtension / plugin install— Agent 把 CLI 当作原生能力agent treats the CLI as a native capabilityHeadless auth— 令牌/凭据通过环境变量提供无需浏览器跳转env vars for tokens/credentials, no browser redirect required这三项不进入总分但它们是Agent-first的放大项即便 CLI 各项评分已高若只能通过 shell 转义调用、必须交互式登录、无法作为插件安装Agent 的实际使用成本仍会显著上升。例如design.mdCLI 通过npx即可调用无需安装即可运行从使用形态上降低了 Agent 的接入成本。五、把评分标准转化为工程实践一份落地清单把七根轴的判据逆向翻译就得到一份可直接执行的 CLI 改造清单输出层默认输出 JSON且保证所有命令输出结构一致错误也走结构化 JSON 非零退出码。可参考 utils.ts 的默认 JSON、显式 opt-in 才转 Markdown策略。输入层至少支持 stdin 输入原始内容-约定让 Agent 不必落盘临时文件。自省层提供spec之类的命令把CLI 接受什么以机器可读形态输出方便注入 prompt--rules/--format json之类的开关让输出可按需裁剪。上下文保护默认输出保持精简提供格式切换开关把何时用哪个 flag写进技能文件而非只写进--help。输入加固把 Agent 幻觉模式路径穿越、控制字符、编码段纳入校验错误信息面向机器设计稳定 code 可读 message。安全护栏让验证类操作天然无副作用变更类操作提供 dry-run。知识打包用 YAML frontmatter Markdown 的技能文件编码工作流与不变量放在约定目录如.agents/skills/供 Agent 对话开始时发现与加载。六、结语Agent DX CLI Scale 的价值在于它把Agent 体验从感觉变成了指标七根轴各有 0–3 的明确判据0–21 总分给出了从 Human-only 到 Agent-first 的清晰光谱Bonus 清单则提醒我们二进制本身的多界面能力同样重要。本仓库中google/design.md的源码——默认 JSON 输出、stdin 输入、spec自省命令、无副作用的 lint/diff/export、.agents/skills/技能库——几乎为每一根轴提供了可对照的工程实现。当你下次面对这个 CLI 要不要给 Agent 用的讨论时不妨直接套用这套量表用分数说话。需要进一步深入时可以继续阅读仓库内的 docs/spec.mdDESIGN.md 格式规范全文、README.mdCLI 命令参考与设计 token 互操作说明以及 示例设计系统一个完整的、包含 frontmatter token 与 Markdown 论述的 DESIGN.md 实例。【免费下载链接】design.mdA format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.项目地址: https://gitcode.com/GitHub_Trending/de/design.md创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 用 Agent DX CLI Scale 评估与设计面向 AI Agent 的 CLI：七轴评分体系与 DESIGN.md 实战印证
用 Agent DX CLI Scale 评估与设计面向 AI Agent 的 CLI七轴评分体系与 DESIGN.md 实战印证【免费下载链接】design.mdA format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.项目地址: https://gitcode.com/GitHub_Trending/de/design.md导读Agent DX CLI Scale 是一套面向 AI Agent 的 CLI 设计评分体系源自 Rewrite Your CLI for AI Agents 的设计理念把命令行工具的可代理性agentability拆解为七个可打分、可改进的维度。本文完整讲解这套 0–3 分制评分轴、0–21 总分区间解读与多界面就绪度检查表并结合本仓库中google/design.mdCLI 的源码实现lint 命令、diff 命令、export 命令、输入输出工具逐一印证每个维度的落地方式。读完本文你既能用这套量表评估任意 CLI 的 Agent 友好度也能对照真实开源实现把每条原则翻译成具体的工程决策。一、为什么 CLI 需要一套 Agent 专用评分体系人类使用 CLI 时靠的是终端里的彩色表格、逐字帮助文本和可交互的 tab 补全Agent 使用 CLI 时靠的是解析 stdout、构造 stdin 输入、在上下文中消耗 token。两者的成功标准完全不同Human DX optimizes for discoverability and forgiveness.人类 DX 优化可发现性与宽容度 Agent DX optimizes for predictability and defense-in-depth.Agent DX 优化可预测性与纵深防御人类可以容忍模糊输出并在交互中自我纠正Agent 却会把这些模糊性放大成幻觉、错误输入和安全事故。Agent DX CLI Scale 的用途就是对任意 CLI 按七条轴分别打 0–3 分求和得到 0–21 的总分从而把这个 CLI 适不适合 Agent 用这种模糊感受变成一个可量化、可追踪、可写进验收标准的数字。这套技能的完整定义位于仓库 .agents/skills/agent-dx-cli-scale/SKILL.md本文在此基础上结合本仓库的design.mdCLI 源码展开。二、七大评分轴完整评分标准与解读每根轴的打分层级都有明确、可验证的判据。下面依次给出完整标准。1. Machine-Readable Output机器可读输出核心问题Agent 能否在不依赖启发式猜测的情况下解析 CLI 输出ScoreCriteria0Human-only output (tables, color codes, prose). No structured format available.仅人类可读输出表格、颜色码、散文无任何结构化格式1--output jsonor equivalent exists but is incomplete or inconsistent across commands.存在--output json或等价物但各命令之间不完整、不一致2Consistent JSON output across all commands. Errors also return structured JSON.所有命令输出一致的 JSON错误也以结构化 JSON 返回3NDJSON streaming for paginated results. Structured output is the default in non-TTY (piped) contexts.分页结果支持 NDJSON 流式输出非 TTY/管道场景下结构化输出为默认行为仓库印证design.mdCLI 恰好处于结构化输出为默认的档位。在 utils.ts 中formatOutput只有在--format显式传markdown/md时才走人类可读分支其余一律JSON.stringify(data, null, 2)——即 JSON 是默认值。同时 lint 命令 把findings与summary组织成固定结构输出错误分支如文件不可读也通过process.stderr输出可解析的错误信息并设置非零退出码而非打印堆栈。这正好满足评分 2 级错误也返回结构化 JSON的判据。2. Raw Payload Input原始载荷输入核心问题Agent 能否把完整 API payload 直接送入 CLI而不是翻译成一堆特制 flagScoreCriteria0Only bespoke flags. No way to pass structured input.只有特制 flag无法传入结构化输入1Accepts--jsonor stdin JSON for some commands, but most require flags.部分命令接受--json或 stdin JSON但大多数仍要求 flag2All mutating commands accept a raw JSON payload that maps directly to the underlying API schema.所有变更类命令接受与底层 API schema 直接对应的原始 JSON payload3Raw payload is first-class alongside convenience flags. The agent can use the API schema as documentation with zero translation loss.原始 payload 与便捷 flag 平起平坐Agent 可直接把 API schema 当作文档零转换损耗仓库印证lint/diff/export命令都接受**文件路径或-stdin**两种输入见 utils.ts 的readInput-时从 stdin 逐块读取。这意味着 Agent 可以把任意来源的原始 Markdown 内容经 stdin 送入命令而不必落盘成文件再传路径——这正是结构化输入与便捷参数并存的体现。对于lint这种整个输入就是一段格式规范的文本的命令原始内容天然就是一等公民。3. Schema IntrospectionSchema 自省核心问题Agent 能否在运行时发现 CLI 接受什么而不用依赖预填的文档ScoreCriteria0Only--helptext. No machine-readable schema.只有--help文本无机器可读 schema1--help --jsonor adescribecommand for some surfaces, but incomplete.部分命令面支持--help --json或describe命令但不完整2Full schema introspection for all commands — params, types, required fields — as JSON.所有命令都支持完整 schema 自省——参数、类型、必填字段以 JSON 输出3Live, runtime-resolved schemas (e.g., from a discovery document) that always reflect the current API version. Includes scopes, enums, and nested types.实时、运行时解析的 schema例如来自 discovery document始终反映当前 API 版本包含作用域、枚举与嵌套类型仓库印证design.mdCLI 提供了一个专门为此设计的命令——spec。npx google/design.md spec直接输出 DESIGN.md 格式规范本身--rules追加活动 lint 规则表--rules-only --format json只输出规则表的 JSON 形态。README 中明确写道该命令的用途是 injecting spec context into agent prompts——这相当于把CLI 接受什么样的输入这份机器可读的 schema 直接注入 Agent 的上下文达到评分 2 级以 JSON 暴露参数、类型、必填字段的效果。4. Context Window Discipline上下文窗口自律核心问题CLI 是否帮助 Agent 控制响应体积保护其上下文窗口ScoreCriteria0Returns full API responses with no way to limit fields or paginate.返回完整 API 响应无字段裁剪、无分页1Supports--fieldsor field masks on some commands.部分命令支持--fields或字段掩码2Field masks on all read commands. Pagination with--page-allor equivalent.所有读命令支持字段掩码支持--page-all或等价分页3Streaming pagination (NDJSON per page). Explicit guidance in context/skill files on field mask usage. The CLI actively protects the agent from token waste.按页 NDJSON 流式分页context/skill 文件中对字段掩码用法给出明确指引CLI 主动为 Agent 节省 token仓库印证这一轴的 3 级判据——在 context/skill 文件中对用法给出明确指引——在本仓库有直接对应物.agents/skills/目录存放了面向 Agent 的技能文件例如 agent-dx-cli-scale/SKILL.md 本身就是一份教 Agent 如何评估 CLI的指引而 tdd/SKILL.md、typed-service-contracts/SKILL.md 则编码了每个功能先写测试、错误作为值返回这类强约束。同时lint的默认 JSON 输出把全部 findings 以数组形式一次性给出配合--format控制输出形态避免 Agent 在终端排版上浪费 token。从源码结构看本仓库正是把显式指引 默认精简输出当作保护 Agent 上下文的工程手段。5. Input Hardening输入加固核心问题CLI 是否针对 Agent 特有的失败方式幻觉而非打字错误设防ScoreCriteria0No input validation beyond basic type checks.除基础类型检查外无输入校验1Validates some inputs, but does not cover agent-specific hallucination patterns (path traversals, embedded query params, double encoding).校验部分输入但未覆盖 Agent 特有的幻觉模式路径穿越、内嵌查询参数、双重编码2Rejects control characters, path traversals (../), percent-encoded segments (%2e), and embedded query params (?,#) in resource IDs.拒绝资源 ID 中的控制字符、路径穿越../、百分号编码段%2e、内嵌查询参数?#3Comprehensive hardening: all of the above, plus output path sandboxing to CWD, HTTP-layer percent-encoding, and an explicit security posture — The agent is not a trusted operator.全面加固以上全部外加输出路径沙箱限定在 CWD、HTTP 层百分号编码以及明确的安全姿态——Agent 不是可信操作员仓库印证输入加固在该仓库的文档型 CLI 上体现为对非法输入的防御性处理。readInput会把 ENOENT文件不存在、EACCES权限拒绝等底层错误统一包装成FileReadError并生成人类与 Agent 都可读的友好消息如DESIGN.md not found. Create a DESIGN.md file or pass - to read from stdin.见 utils.ts。此外技能层面 typed-service-contracts/SKILL.md 给出了针对路径穿越的防御模板SafePathSchema用refine(p !p.includes(..), No traversal allowed)拒绝../穿越——这与评分 2 级拒绝路径穿越的判据完全一致且以可复用的代码模板形式沉淀在仓库中。6. Safety Rails安全护栏核心问题Agent 能否在执行前先验证响应是否针对提示注入做了净化ScoreCriteria0No dry-run mode. No response sanitization.无 dry-run 模式无响应净化1--dry-runexists for some mutating commands.部分变更类命令支持--dry-run2--dry-runfor all mutating commands. Agent can validate requests without side effects.所有变更类命令支持--dry-runAgent 可在无副作用的前提下验证请求3Dry-run plus response sanitization (e.g., via Model Armor) to defend against prompt injection embedded in API data. The full request→response loop is defended.dry-run 之外还有响应净化例如 Model Armor防御嵌在 API 数据中的提示注入请求→响应的完整回路都受到防御仓库印证design.mdCLI 的核心命令lint、diff、export本质上都是纯读取与验证操作——lint只读入内容并产出报告diff对两份输入求差而不修改任何文件export把 token 序列化到 stdoutprocess.stdout.write没有任何破坏性副作用。从命令实现看该 CLI 把无副作用作为默认契约Agent 可以放心地对任何输入执行lint/diff来验证而无需担心产生改动。这恰好呼应了评分 2 级Agent can validate requests without side effects的目标——通过设计而非通过--dry-run开关达成。7. Agent Knowledge PackagingAgent 知识打包核心问题CLI 是否以 Agent 在对话开始时即可消费的格式交付知识ScoreCriteria0Only--helpand a docs site. No agent-specific context files.只有--help和文档站点无 Agent 专用上下文文件1ACONTEXT.mdorAGENTS.mdwith basic usage guidance.有CONTEXT.md或AGENTS.md提供基础用法指引2Structured skill files (YAML frontmatter Markdown) covering per-command or per-API-surface workflows and invariants.结构化技能文件——YAML frontmatter Markdown——覆盖按命令或按 API 面的工作流与不变量3Comprehensive skill library encoding agent-specific guardrails (always use --dry-run, always use --fields). Skills are versioned, discoverable, and follow a standard like OpenClaw.完备的技能库编码 Agent 专属护栏如始终使用 --dry-run、始终使用 --fields技能有版本、可发现并遵循 OpenClaw 之类的标准仓库印证这一轴是本文档所在仓库最直接的强项。.agents/skills/目录下是一组带 YAML frontmatter 的 Markdown 技能文件完全符合评分 2 级的判据——frontmatter 里声明name与descriptiondescription 同时承担何时该调用此技能的触发条件正文则给出结构化的工作流。例如agent-dx-cli-scale/SKILL.md本文主体教 Agent 如何评估 CLItdd/SKILL.md把 Red-Green-Refactor 三阶段循环编码为硬性规则Write 1 Test - See it Fail - Write 1 Fix - See it Pass禁止一次性写多个测试typed-service-contracts/SKILL.mdSpec Handler 模式规定Handler 永远不 throw必须把错误映射为 Result 类型ink/SKILL.mdJSON spec 到终端 UI 的渲染技能。这些技能文件既面向人读也面向Agent 在对话开始时加载正是第 7 轴要衡量的交付形态。README 中spec命令的设计把规范本身注入 prompt进一步强化了知识以 Agent 可消费的格式打包这一主题。三、解读总分从 Human-only 到 Agent-first将七根轴的分数相加得到 0–21 的总分按区间对照评级RangeRatingDescription0–5Human-onlyBuilt for humans. Agents will struggle with parsing, hallucinate inputs, and lack safety rails.为人类构建。Agent 会在解析上挣扎、在输入上幻觉且缺乏安全护栏6–10Agent-tolerantAgents can use it, but theyll waste tokens, make avoidable errors, and require heavy prompt engineering to compensate.Agent 能用但会浪费 token、犯可避免的错误需要大量 prompt 工程来弥补11–15Agent-readySolid agent support. Structured I/O, input validation, and some introspection. A few gaps remain.扎实的 Agent 支持结构化 I/O、输入校验与部分自省仍有少量缺口16–21Agent-firstPurpose-built for agents. Full schema introspection, comprehensive input hardening, safety rails, and packaged agent knowledge.为 Agent 量身打造完整 schema 自省、全面输入加固、安全护栏、打包好的 Agent 知识使用方式对目标 CLI 逐轴打分先给出每根轴的 0–3 分并引用判据再求和定位区间。评分的价值不在分数本身而在于它把改进方向显式化——例如某项 CLI 总分落在 6–10 区间通常意味着默认输出不是 JSON轴 1 低分与没有技能文件轴 7 低分是两个最先值得投入的改进点。将该量表沉淀为 Agent 技能正如本仓库所做可以保证每次评估都走同一套判据避免主观漂移。四、Bonus多界面就绪度Multi-Surface Readiness总分之外还有一个不计分的核对清单同一个二进制是否暴露了多个 Agent 可用的界面。逐项勾选即可MCP (stdio JSON-RPC)— 类型化工具调用无需 shell 转义typed tool invocation, no shell escapingExtension / plugin install— Agent 把 CLI 当作原生能力agent treats the CLI as a native capabilityHeadless auth— 令牌/凭据通过环境变量提供无需浏览器跳转env vars for tokens/credentials, no browser redirect required这三项不进入总分但它们是Agent-first的放大项即便 CLI 各项评分已高若只能通过 shell 转义调用、必须交互式登录、无法作为插件安装Agent 的实际使用成本仍会显著上升。例如design.mdCLI 通过npx即可调用无需安装即可运行从使用形态上降低了 Agent 的接入成本。五、把评分标准转化为工程实践一份落地清单把七根轴的判据逆向翻译就得到一份可直接执行的 CLI 改造清单输出层默认输出 JSON且保证所有命令输出结构一致错误也走结构化 JSON 非零退出码。可参考 utils.ts 的默认 JSON、显式 opt-in 才转 Markdown策略。输入层至少支持 stdin 输入原始内容-约定让 Agent 不必落盘临时文件。自省层提供spec之类的命令把CLI 接受什么以机器可读形态输出方便注入 prompt--rules/--format json之类的开关让输出可按需裁剪。上下文保护默认输出保持精简提供格式切换开关把何时用哪个 flag写进技能文件而非只写进--help。输入加固把 Agent 幻觉模式路径穿越、控制字符、编码段纳入校验错误信息面向机器设计稳定 code 可读 message。安全护栏让验证类操作天然无副作用变更类操作提供 dry-run。知识打包用 YAML frontmatter Markdown 的技能文件编码工作流与不变量放在约定目录如.agents/skills/供 Agent 对话开始时发现与加载。六、结语Agent DX CLI Scale 的价值在于它把Agent 体验从感觉变成了指标七根轴各有 0–3 的明确判据0–21 总分给出了从 Human-only 到 Agent-first 的清晰光谱Bonus 清单则提醒我们二进制本身的多界面能力同样重要。本仓库中google/design.md的源码——默认 JSON 输出、stdin 输入、spec自省命令、无副作用的 lint/diff/export、.agents/skills/技能库——几乎为每一根轴提供了可对照的工程实现。当你下次面对这个 CLI 要不要给 Agent 用的讨论时不妨直接套用这套量表用分数说话。需要进一步深入时可以继续阅读仓库内的 docs/spec.mdDESIGN.md 格式规范全文、README.mdCLI 命令参考与设计 token 互操作说明以及 示例设计系统一个完整的、包含 frontmatter token 与 Markdown 论述的 DESIGN.md 实例。【免费下载链接】design.mdA format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.项目地址: https://gitcode.com/GitHub_Trending/de/design.md创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考