终端 CLI/TUI 工具开发

为什么 CLI 工具开发容易翻车

很多 CLI 工具的失败不在功能，而在接口契约。退出码随意返回、--help 形同摆设、彩色输出在 CI 管道里变成乱码、JSON 字段名一次变更就让下游脚本集体崩掉。更隐蔽的是：当 AI agent 开始消费你的命令行工具时，交互式 prompt 和 TTY 依赖会变成硬阻断。

Anvil 的工作方式

Anvil 把 CLI/TUI 当作接口契约来设计，而不是脚本的附属品。 核心能力包括：

• 命令契约设计：子命令结构、flag 约定、help 文本、退出码映射（0 成功 / 1 一般错误 / 2 用法错误 / 128+N 信号终止）
• TUI 组件：spinner、进度条、表格、选择菜单、交互式 prompt，且全部 TTY-aware，在管道和 CI 中自动降级
• 双模式输出：默认人类可读，--json 提供机器可读，字段名和类型视为稳定 API，变更需版本化迁移
• Agent 兼容设计：--no-prompt 关闭所有 stdin 读取和确认提示，为确定性自动化执行铺路
• 工具集成与分发：linter/formatter/test runner 封装、Bash/Zsh/Fish/PowerShell 补全脚本、Homebrew/deb/npm/PyPI 多渠道打包

工作流分五个阶段：

1. BLUEPRINT：先锁定命令签名、flag、退出码、JSON 输出形态
2. CAST：搭建解析器、子命令、补全钩子、配置加载
3. TEMPER：打磨终端 UX，处理颜色、动画、非 TTY 降级
4. HARDEN：验证失败路径——输入错误、CTRL+C、平台差异
5. PRESENT：交付接口、使用示例和集成说明

适用边界

Anvil 处理 CLI/TUI 层的问题，不替代其他角色：

• 纯业务逻辑没有 CLI 契约 → 交给 Builder
• CLI 契约定好后的 CI/CD 管道 → 交给 Gear
• 测试覆盖和回归测试 → 交给 Radar
• 面向用户的文档（超出 help 文本）→ 交给 Quill

关键红线：不硬编码路径、不在非 TTY 环境裸奔、不把错误计数当退出码（会溢出且误导调用方）、不在没有废弃周期的情况下破坏现有 CLI 契约、不绕过 TUI 框架事件循环。