cli-builder

CLI 构建器

为任何模块或应用程序、使用任何语言构建适用于生产环境的 CLI 工具。

参考文件（按需逐个读取，不要预先全部读取，以减少 Agent 的上下文占用）：

• references/cli-libraries.md — 在第 2 步（设计）中读取，用于推荐库；在第 4 步（执行）中读取，用于搭建起始框架
• references/btop-style.md — 在第 2 步（设计）中读取，用于撰写「视觉风格」部分；在第 4 步（执行）中读取，用于构建样式模块及其测试
• references/testing-patterns.md — 在第 4 步（执行）中编写测试时读取
• references/final-report.md — 在第 5 步（总结）中读取，用于撰写最终报告

编辑前同步仓库（必须执行）

在第 1 步之前运行本节一次，确保分析基于当前代码。如果 git rev-parse --git-dir 失败，则当前目录不是 git 仓库：跳过本节、「分支优先安全规则」和第 4 步中的提交，并在最终报告的 Uncertainty: 下列出 no git repository: no branch or commits。

在 git 仓库中，将当前分支与远程同步：

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

如果工作区不干净，先暂存更改，再同步，然后还原：

git stash push -u -m "pre-sync"
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin && git pull --rebase origin "$branch"
git stash pop

如果没有 origin、无法拉取，或 rebase／暂存操作发生冲突，请停止并询问用户，然后再继续。

分支优先安全规则

在第 4 步开始时、首次写入文件之前运行此规则，并将 CLI_NAME 设为第 2 步中获批的工具名称。仅当当前分支为 main 或 master 时才创建新分支；否则继续使用现有分支（用户可能已提前设置，或正在恢复工作）：

current_branch="$(git rev-parse --abbrev-ref HEAD)"
if [ "$current_branch" = "main" ] || [ "$current_branch" = "master" ]; then
  slug="$(echo "${CLI_NAME:-cli}" | tr '[:upper:] ' '[:lower:]-' | tr -cd 'a-z0-9-')"
  ts="$(date +%Y%m%d-%H%M%S)"
  git checkout -b "feat/cli-${slug}-${ts}"
fi

必须遵循的 5 步工作流（需逐步审批）

明确批准是指用户回复接受当前呈现的内容，例如“已批准”或“看起来不错，继续吧”。提出问题、要求修改或未回复都不算批准。第 1 至第 3 步不写入任何文件。

第 1 步：分析

提出任何方案之前，先了解项目。

自动检测语言，方法是检查清单文件：

• package.json / tsconfig.json -> JavaScript/TypeScript
• pyproject.toml / setup.py / setup.cfg / requirements.txt -> Python
• go.mod -> Go
• Cargo.toml -> Rust
• pom.xml / build.gradle / build.gradle.kts -> Java/Kotlin
• Gemfile / *.gemspec -> Ruby

识别现有 CLI／入口点：检查 bin 字段、__main__.py、main.go、fn main()、现有参数解析代码或 package.json 中的 scripts。

记录模块结构：列出 CLI 将公开的函数或类、它们的输入和输出、核心数据类型及运行时依赖项。

提出澄清问题（仅询问无法推断的信息）：

• 主要用例（自动化、开发者工具、数据处理、管理）
• 目标受众（开发者、运维人员、最终用户）
• 单命令还是多命令（子命令树）
• 所需输出格式（文本、JSON、表格、CSV）
• 分发方式（pip/npm/go install、独立二进制文件、源码）

呈现分析结果：检测到的语言、入口点、公开函数列表和待解决的问题。等待用户明确批准后，再进入第 2 步。

---

步骤 2：设计

提交一份结构清晰的 CLI 设计文档：

• 工具名称和二进制文件／入口点名称
• 命令树（适用于多命令工具的层级结构图）
• 各命令的参数和选项（名称、类型、必填／可选、默认值、帮助文本）
• 全局选项（verbose、quiet、输出格式、配置文件、no-color）
• I/O 行为（是否支持 stdin、stdout/stderr 分离、管道）
• 配置策略（CLI 参数 > 环境变量 > 配置文件 > 默认值）
• 调用示例（至少 3 个体现常见用例的真实示例）
• 视觉风格（每次设计都必须包含）——采用 references/btop-style.md 中受 btop 启发的外观：各命令的组件、主题角色、回退方案、样式库或零依赖模块，以及一个展示命令样式输出的示意图。只有当用户明确拒绝这种风格时，才使用其他风格。

审批流程：

1. 提交设计文档。
2. 征求反馈。
3. 如果回复不是明确批准，则修改设计并返回第 1 步。

设计获批前不得开始实现。 如果用户结束运行时尚未批准设计，则停止；最终状态为 BLOCKED。

---

步骤 3：规划

将实现拆分为三个阶段，每个阶段包含细化的任务。

阶段 1——基础（搭建可运行的 CLI 骨架）：

• 设置入口点和参数解析
• 实现一个核心命令（最重要的命令）
• 帮助文本和版本标志
• 基本测试（帮助输出、版本、一个命令）

阶段 2——完善（实现完整功能集）：

• 所有剩余命令
• 输入验证和错误处理
• 通过遵循已批准视觉风格的单一样式模块实现输出格式（文本、JSON、表格，按设计而定）
• 全面测试

阶段 3——打磨（可选；仅在用户确认后纳入）：

• 支持配置文件
• 环境变量覆盖
• Shell 补全（bash、zsh、fish）
• 分发／打包设置（setup.py、package.json bin、goreleaser 等）

每项任务都包含：

• 目标：用一句话描述
• 文件：创建或修改的文件
• 预期行为：完成此任务后用户可以做什么
• 测试：如何验证
• 工作量：S / M / L

规划也使用步骤 2 中相同的审批流程。

计划获批前不得开始执行。 如果用户结束运行时尚未批准计划，则停止；最终状态为 BLOCKED。

---

步骤 4：执行

首次写入文件前，应用“分支优先安全规则”。然后，对已批准计划中的每项任务：

1. 实现任务。
2. 运行项目清单文件中指定的测试命令（例如 pytest、npm test、go test ./...、cargo test）。
3. 如果测试失败，修复代码并重新运行测试命令。同一任务的修复尝试失败 3 次后，停止步骤 4，展示失败输出并询问用户如何继续。测试失败时不得开始下一项任务。
4. 如果无法运行测试命令（缺少工具链或测试运行器），告知用户。只有获得明确批准后才能继续，并将该任务的测试记录为 not run。

每个阶段结束时：

5. 运行演示（--help 加上至少一个已批准的调用示例），并展示输出。从阶段 2 起，还要使用 FORCE_COLOR=1 运行一个示例，除非用户拒绝了 btop 风格（references/btop-style.md → 验证）。演示以非零状态码退出即视为测试失败（第 3 项）。
6. 如果位于 git 仓库中，仅暂存此阶段创建或修改的文件，然后使用描述性消息提交。

如果某项任务需要更改已批准的设计（命令、选项或输出格式有所不同），则停止步骤 4。提出建议的更改，并等待明确批准后再继续。

---

步骤 5：总结

在最后一份步骤完成报告之后，在聊天中以纯文本形式打印最终报告，只打印一次。除非用户要求，否则不要写入报告文件。阅读 references/final-report.md，了解各部分的内容、状态规则和两个示例。四个部分按以下顺序排列：

1. Result: — 先写状态（COMPLETE、PARTIAL — <reason> 或 BLOCKED — <reason>），再写工具名称。
2. Evidence: — 只列出已运行的检查：文件、测试数量、演示退出代码。
3. Uncertainty: — 列出未经测试的行为和假设，并与已验证的事实分开标注。
4. Decision: — 写明需要的批准，或写 No approval needed.，然后列出用户接下来需要采取的每项行动。

四个部分之后，打印使用快速入门（安装命令和 3-5 个调用示例）以及后续步骤（建议的改进、缺失的功能、分发待办事项）。

状态规则 — 应用第一个符合条件的规则：

1. BLOCKED — 在首次写入文件之前运行停止，例如设计或计划未获批准、没有可封装的模块且用户未作答，或 Repo Sync 遇到冲突或缺少 origin，且用户未批准绕过该问题。
2. PARTIAL — 至少写入了一个文件，之后发生以下任一情况：测试或演示仍未通过、测试命令无法运行、用户提前停止步骤 4、已批准的任务尚未完成，或设计变更仍待批准。
3. COMPLETE — 已完成获批计划中的所有任务，且所有测试命令和演示均已运行并通过。用户拒绝的 Phase 3 不会导致运行状态变为 partial。

预期输出

在名为 mylib 的 Python 模块上运行此技能后，最终报告如下所示（完整示例见 references/final-report.md）：

Result: COMPLETE — mylib CLI (Python, click) with subcommands run and info
Evidence:
  Branch: feat/cli-mylib-20260419-143200
  Created: cli/main.py, cli/commands/run.py, cli/commands/info.py, tests/test_cli.py
  Modified: pyproject.toml ([project.scripts] entry point)
  pytest: 8 passed, 0 failed
  Visual style: btop, rich
  Demo: mylib --help, mylib --version, mylib info, env -u NO_COLOR FORCE_COLOR=1 mylib info (all exit 0)
Uncertainty:
  Tested on macOS only. Styled output not viewed in a real terminal; light-background terminal not tried.
  Shell completions not built (Phase 3 declined).
Decision: No approval needed.
  Remaining action: review the branch and push it.

Usage quick-start:
  pip install -e .
  mylib --help
  mylib run --input data.csv --output results.json
  mylib info --format json

Step Completion Report (Steps 4-5):

◆ Execute + Summarize (step 4-5 of 5 — mylib CLI)
··································································
  Implementation:         √ pass (2 subcommands, 4 files created)
  Test coverage:          √ pass (8/8 tests passing)
  Phase demos completed:  √ pass (help, version, run verified)
  Final report delivered: √ pass
  Criteria:               √ 4/4 met
  ____________________________
  Result:                 PASS

边界情况

• 没有明确的可封装模块：继续分析前，询问用户 CLI 应开放哪些函数或功能。
• 检测到多种语言：提供选择，并推荐现有 CLI 相关代码最多的语言。
• 已存在 CLI：先审查现有内容，再提供扩展或重构方案，而不是重建。
• 现有 CLI 有自己的视觉风格：设计方案中仍要展示 btop 风格，列出其与当前输出的差异，并让用户在批准设计时选择。
• 用户要求实时刷新的 btop 式视图：在步骤 1 中说明全屏实时视图属于 TUI，此技能不会构建此类界面，并提供仅追加输出的方案（references/btop-style.md）。
• 包含许多软件包的单体仓库：询问用户应为哪个软件包或服务添加 CLI；将分析范围限定在该子树。
• 没有测试框架：将最小化测试环境（pytest、jest、go test）作为 Phase 1 基础任务的一部分添加。
• 需要二进制输出（独立的 .exe / 编译产物）：在设计阶段注明分发方式，并在 Phase 3 打磨阶段添加构建步骤（PyInstaller、pkg、goreleaser）。
• 用户批准设计但拒绝实施：返回设计阶段；不要擅自继续采用被拒绝的方案。

验收标准

• 在提出澄清问题前，先从清单文件中自动检测语言
• 在开始任何实现之前，先提交 CLI 设计文档并获得明确批准
• 在开始执行之前，先提交实施计划并获得明确批准
• 每个命令层级的 --help 都能正常工作，并已实现 --version
• 退出码遵循 references/testing-patterns.md 中的规范表格
• 错误消息输出到 stderr；干净的输出输出到 stdout（可通过管道传输）
• 遵循 NO_COLOR 环境变量或 --no-color 标志
• 终端输出遵循已批准的视觉风格；--format json、管道传输和 NO_COLOR 输出中均不包含 ESC（0x1b）字节
• 在进入下一阶段之前，先编写并通过测试
• 最终报告包含安装命令和至少 3 个用法示例
• 最终报告以 Result: 和根据步骤 5 状态规则选定的状态开头，接着是 Evidence:、Uncertainty: 和 Decision:
• 读者能够找到结果，区分已验证的检查与假设，将每项声明追溯到文件或命令，并看到下一步决策（读者检查项见 references/final-report.md）。在用户回答这些检查项之前，用户是否理解仍无法确认

步骤完成报告

完成每个主要步骤后，按以下格式输出状态报告：

◆ [Step Name] ([step N of M] — [context])
··································································
  [Check 1]:          √ pass
  [Check 2]:          √ pass (note if relevant)
  [Check 3]:          × fail — [reason]
  [Check 4]:          √ pass
  [Criteria]:         √ N/M met
  ____________________________
  Result:             PASS | FAIL | PARTIAL

根据步骤实际验证的内容调整检查项名称。通过使用 √，失败使用 ×，简短补充说明使用 —。“Criteria”行概述已满足的验收标准数量。“Result”行给出总体结论。

各阶段的技能专属检查项

阶段：分析（步骤 1） — 检查项：Project analysis、Language detected、Entry points identified、Clarifying questions asked

阶段：设计（步骤 2） — 检查项：Design approval、Command tree defined、I/O behavior specified、Example invocations provided、Visual style defined

阶段：计划（步骤 3） — 检查项：Plan approval、Phases broken down、Tasks have goals and tests、Effort estimated

阶段：执行 + 总结（步骤 4–5） — 检查项：Implementation、Test coverage、Phase demos completed、Final report delivered

错误处理

情况	操作
没有明确可封装的模块	询问用户 CLI 应提供哪些功能
检测到多种语言	询问用户应使用哪种语言，并建议选择 CLI 代码较多的语言
已发现现有 CLI	提议扩展或重构，而不是重建；先审查现有 CLI
用户要求使用未知框架	阅读该框架的官方文档；如果无法访问文档，则向用户索要文档链接
实现后测试失败	修复并重新运行；绝不跳过失败的测试。针对同一任务尝试失败 3 次后，停止并询问用户（步骤 4）
测试命令无法运行	告知用户；只有在获得明确批准后才能继续，并将测试记录为 not run（状态为 PARTIAL）
不是 git 仓库	跳过 Repo Sync、分支规则和提交；在 Uncertainty: 下列出

质量保障

使用此技能构建的每个 CLI 都必须包含：

• 帮助文本：每个命令和选项都有说明（每个层级的 --help 均可正常工作）
• 错误消息：写入 stderr，说明出错原因及修复方法
• 退出码：遵循 references/testing-patterns.md 中的规范表格（0 = 成功，非零 = 失败）
• POSIX 约定：--long-flag、-s 短标志、使用 -- 结束选项
• 可通过管道传输的 I/O：在适用时支持 stdin，并确保 stdout 干净以便通过管道传输
• 无颜色支持：遵循 NO_COLOR 环境变量或 --no-color 标志
• 版本标志：--version 输出版本并退出