cli-review-runner

cli-review-runner

自动化执行 cli-for-agents 中的 10 项 Agent 友好度审查。它会针对目标 CLI 运行黑盒探测，并生成结构化报告，将每项发现对应到规则 ID（例如 help-examples-in-help、err-non-zero-exit-codes、safe-dry-run-flag）。默认模式为只读——探测绝不会使用真实参数运行破坏性动词。

适用场景

• 用户要求审查或审核 CLI 的 Agent 友好度、自动化就绪程度或 CI 使用情况
• 用户刚刚构建完 CLI，想在发布前进行健全性检查
• 用户正在根据 cli-for-agents 目录评估自己的 CLI 或第三方 CLI
• 用户在询问为什么 CLI 会让 Agent 挂起、撑爆上下文，或无法在流水线中组合使用
• CLI 变更的 PR 审查——快速回归测试 --help、错误处理和 dry-run 标志

使用方法

该技能由**scripts/review.sh** 编排。将目标 CLI（绝对路径或可通过 PATH 解析的名称）传入，并选择输出格式。

# Default: text table on stdout, exit 0 if all passed, 1 if any failed
bash scripts/review.sh --target /usr/local/bin/mycli

# Machine-readable output
bash scripts/review.sh --target gh --format json
bash scripts/review.sh --target kubectl --format ndjson

# Supply subcommand list when auto-discovery misses them
bash scripts/review.sh --target gh --subcommands pr,issue,repo

# Preview what would run without touching the target CLI
bash scripts/review.sh --target mycli --dry-run

# Include risky probes on destructive verbs (off by default)
bash scripts/review.sh --target mycli --include-destructive

运行 bash scripts/review.sh --help 查看完整的标志列表。

工作流概览

--target <cli>
   │
   ▼
[1] Validate target       fail fast if path missing or not executable
   │
   ▼
[2] Load rule catalog     references/rule-catalog.tsv (45 rules)
   │
   ▼
[3] Discover subcommands  parse top-level --help (gh/kubectl/commander shapes)
   │
   ▼
[4] Run probes P1..P10    each probe emits NDJSON findings to a temp file
   │
   ▼
[5] Render report         scripts/render.sh  ->  text | json | ndjson

如需了解完整的逐项探测说明、失败模式以及如何扩展目录，请阅读 references/workflow.md。

探测覆盖范围

探测项	测试规则	覆盖方式
P1 非交互	interact-no-hang-on-stdin、interact-no-input-flag、interact-flags-first、interact-detect-tty、interact-no-timed-prompts、interact-no-arrow-menus、input-no-prompt-fallback	在 </dev/null 下运行并设置超时；检查帮助信息中是否包含交互式措辞
P2 分层帮助	help-per-subcommand、help-no-flag-required、help-layered-discovery	顶层行数；各子命令的 --help；不带参数调用
P3 帮助示例	help-examples-in-help、help-flag-summary、help-suggest-next-steps	使用 grep 检查各子命令的帮助信息中是否有 Examples:、短标志与长标志配对，以及“See also”
P4 可执行的错误提示	err-actionable-fix、err-include-example-invocation、err-exit-fast-on-missing-required、err-no-stack-traces-by-default	使用无效标志调用；使用 grep 检查 stderr 中是否包含修复建议和示例；检查是否有原始堆栈跟踪
P5 stderr 通道	err-stderr-not-stdout	错误文本必须输出到 fd 2
P6 退出码	err-non-zero-exit-codes	用法错误和运行时错误必须返回不同的非零代码
P7 stdin 组合使用	input-accept-stdin-dash、input-flags-over-positional	使用 grep 检查帮助信息中是否说明 - 表示 stdin；统计位置参数与标志的数量
P8 结构化输出	output-json-flag、output-respect-no-color	--json 生成 JSON；NO_COLOR=1 禁用 ANSI
P9 破坏性操作安全	safe-dry-run-flag、safe-force-bypass-flag、safe-no-prompts-with-no-input	检查破坏性动词的 --help 中是否包含 --dry-run / --yes / --force / --no-input
P10 命令结构	struct-resource-verb、struct-standard-flag-names、struct-no-hidden-subcommand-catchall、struct-flag-order-independent	检查结构是否一致、是否提供 --help / --version、未知子命令是否报错，以及标志位置是否不影响结果

覆盖范围： cli-for-agents 中的 45 条规则有 30 条可通过黑盒测试。其余 15 条（幂等性、状态协调、NDJSON 流式传输、有界输出、仅崩溃恢复、环境变量回退、机密信息通过 stdin 输入、通过输入名称确认）需要实际调用或检查源代码——报告会将它们列为“需要人工审查”。

配置

config.json 存储动词分类列表和默认超时时间。该技能无需任何设置即可使用——默认值已足够合理。可通过标志按次覆盖，或编辑文件进行项目级更改。

{
  "timeout_seconds": 5,
  "safe_verbs": ["list", "get", "show", "status", "describe", "help", "version", "config", "ls", "inspect"],
  "destructive_verbs": ["delete", "drop", "destroy", "remove", "reset", "purge", "rm", "del"]
}

安全模型

所有探测默认均为只读：

• 安全动词（list、get、show 等）可以搭配无效标志调用，以测试错误处理
• 破坏性动词（delete、drop 等）仅通过 --help 检查——绝不搭配参数执行
• 每次探测都在 </dev/null 下运行，并设有 5 秒的墙钟超时
• 目标 CLI 仅在其自身进程中运行沙箱；参数中不包含 shell 元字符

传入 --include-destructive 时，探测也可能搭配无效标志调用破坏性动词。这会暴露一种罕见情况：CLI 在验证标志前就执行破坏性操作。仅对你信任的 CLI 或一次性测试环境启用此选项。

自测

发布探测变更前，请运行自测——它会生成一个故意违反特定规则的模拟 CLI，并断言探测能够检测到这些问题：

bash scripts/selftest.sh

预期输出：Results: 8 passed, 0 failed。任何失败都表明 scripts/lib/probes.sh 出现了回归。

文件

文件	用途
scripts/review.sh	主入口——负责协调探测并生成报告
scripts/render.sh	输出格式化工具：text / json / ndjson
scripts/selftest.sh	使用故意存在缺陷的模拟 CLI 进行健全性检查
scripts/lib/common.sh	共享辅助函数：超时、动词分类器、JSON 转义、目录加载器
scripts/lib/probes.sh	探测函数 probe_p1..probe_p10
references/rule-catalog.tsv	来自 cli-for-agents 的 45 条规则，已映射至探测
references/workflow.md	逐项探测的方法、故障模式和扩展指南
gotchas.md	使用过程中发现的已知边缘情况
config.json	动词分类器列表和默认超时时间

相关技能

• cli-for-agents——此技能据以审查的 45 条规则设计目录。报告指出问题且你需要完整说明时，请阅读其中的规则文件。