| name | cli-developer |
| description | 构建 CLI / command-line 工具时使用，支持两种模式。模式 A 人类 CLI（终端 UX、彩色、交互式提示、进度条、Shell 自动补全），关键词包括 commander / yargs / oclif / typer / click / cobra。模式 B agent-native CLI（JSON envelope / schema 自省 / dry-run 写入安全 / 契约驱动），关键词包括 agent-native CLI、JSON envelope、friction signal。混合场景默认走 B（agent 约束更严格）。只要用户提到 CLI、command-line、命令行工具、agent-native、envelope、schema、friction signal，或要给 agent 提供可调用的 CLI 工具，就应主动使用此 skill。 |
CLI 开发专家
支持两种 CLI 形态的专家：人类终端工具 和 agent-native 工具。
⚡ 模式选择【首次介入必问】
介入任何 CLI 任务前，必须先问用户：
你要构建的 CLI，主要调用方是？
A) 人类 CLI —— 开发者在终端手动调用，需要 TTY/彩色/交互式提示/进度条
B) Agent-native CLI —— 调用方是 AI agent，需要稳定 JSON 输出契约
如果两者都要（人机共用的双面 CLI），选择 B 并遵守"agent 优先，人类兼容"原则。
选定后走对应工作流，不混用约束。混合场景按 B 处理（agent 约束更严格）。
A) 人类 CLI 工作流
最终用户是开发者，在终端手动调用。核心关注：启动速度、交互体验、错误可读性、跨平台。
何时走这条路径
- 用户明确说"人类用"、"终端工具"、"给开发者用"
- 强调彩色输出、进度条、交互式提示、Shell 自动补全
- 没有 agent 调用场景
核心工作流程（保留现有 5 步）
- 分析用户体验 - 识别用户工作流程、命令层次结构和常见任务
- 设计命令 - 规划子命令、标志、参数和配置
- 实现 - 使用适合语言的 CLI 框架
- 优化 - 添加自动补全、帮助文本、错误消息和进度指示器
- 测试 - 跨平台测试和性能基准测试
必须做
- 保持启动时间在 50ms 以下
- 提供 --help 和 --version 标志
- 使用一致的标志命名约定
- 优雅地处理 SIGINT（Ctrl+C）
- 尽早验证用户输入
- 同时支持交互式和非交互式模式
- 在 Windows、macOS 和 Linux 上测试
不能做
- 在不必要的情况下阻塞同步 I/O
- 如果输出将被管道传输，则打印到 stdout
- 当输出不是 TTY 时使用颜色
- 破坏现有命令签名
- 在 CI/CD 环境中要求交互式输入
- 硬编码路径或特定平台的逻辑
- 发布时不包含 Shell 自动补全
参考文档加载
| 主题 | 参考文档 | 加载时机 |
|---|
| 设计模式 | references/design-patterns.md | 子命令、标志、配置、架构 |
| Node.js CLI | references/node-cli.md | commander、yargs、inquirer、chalk |
| 用户体验模式 | references/ux-patterns.md | 进度条、颜色、帮助文本 |
B) Agent-native CLI 工作流
调用方是 AI agent。核心关注：输出契约稳定、错误可机器分支、命令可自省、写入安全。
何时走这条路径
- 用户明确说"agent 用"、"给 AI 调用"、"agent-native"
- CLI 会集成到 agent 工具链（Claude Code、Cursor、自动化 agent 流程）
- 用户提到 envelope / schema / friction signal / dry-run 等 agent-native 关键词
- 混合场景（人类 + agent 共用），默认走这条
核心工作流程（8 步）
- 设计命令语义 - 先忘掉输出格式，定义每个命令的"语义目标"
- 设计 envelope 契约 - 为每个命令定义 success data 和 error.code 集合
- 设计 schema 自省 - 提供 schema 命令，让 agent 能自动学会用法
- 实现核心 + envelope - 用最小依赖实现，stdout 永远只输出 JSON envelope
- 添加写入安全 - 写入类命令实现 dry-run + --yes 两段式
- 类型契约（可选） - 资源管理类 CLI 引入类型契约
- 观测系统（可选） - 反复调用的 CLI 引入 signal + intent
- 测试 envelope - 断言 JSON envelope，不测人类文本
必须做
- stdout 永远是单一 JSON envelope，不输出人类文本、日志、彩色
- 每个 error 必须有稳定
code + 可执行 hint
- schema 命令必须可自省，agent 跑陌生命令前先查 schema
- 写入类命令必须 dry-run + --yes，agent 不自动 --yes
- 退出码与 ok 字段一致：0 = ok:true，非 0 = ok:false
- 错误 code 用英文小写 snake_case
- 不依赖 TTY 交互，所有输入通过 args/flags/stdin
不能做
- 在 stdout 输出 console.log / console.error 的人类文本
- 用 process.exit(1) 而不写 envelope
- 用 HTTP 风格错误码（404_NOT_FOUND）或 camelCase
- 在 error.message 里塞控制流信息
- 引入 commander/yargs/inquirer 等人类 CLI 框架（除非同时服务人类）
- 默认启用 signal/intent 观测
参考文档加载
| 主题 | 参考文档 | 加载时机 |
|---|
| Agent-native 核心范式 | references/agent-native.md | envelope / schema / dry-run / 契约 / 测试 |
| 观测系统（进阶） | references/friction-signals.md | friction signal / intent / drift / 周期维护 |
加载策略：
- B 路径默认必读 agent-native.md（核心范式不可绕过）
- friction-signals.md 仅在以下场景加载：用户提到"周期维护/漂移/signal/intent"，或 CLI 管理会演化资源且被反复调用
- 不要默认加载 friction-signals.md（YAGNI，避免上下文膨胀）
混合场景处理（人类 + agent 共用）
当 CLI 同时服务人类和 agent 时：
原则：agent 约束优先，人类体验兼容。
具体做法：
- stdout 永远是 JSON envelope（agent 强约束）
- 人类可读信息走 stderr 或
--human 标志：
cli read foo
cli read foo --human
- 检测
--human 或 isTTY 切换输出层，但 envelope 是真相源
- 测试必须断言 envelope，人类文本不在测试范围内
输出模板
A 路径输出
- 命令结构（主入口、子命令）
- 配置处理（文件、环境变量、标志）
- 带错误处理的核心实现
- Shell 自动补全脚本
- UX 设计决策说明
B 路径输出
- 命令语义定义（每个命令要达成的目标）
- Envelope 契约表（success data 字段 + error.code 枚举）
- Schema 自省设计（命令清单的 JSON 结构）
- 核心实现（envelope 输出 + 参数解析）
- 写入安全设计（dry-run 预览字段 + --yes 确认机制）
- 错误码字典（每个 code 的触发条件 + hint 模板）
- （可选）类型契约定义
- （可选）观测系统设计（signal patterns + intent 标志）
约束条件（双路径共用）
必须做（共用）
- 保持启动时间在 50ms 以下（agent 调用频繁，启动成本敏感）
- 尽早验证用户输入
- 优雅地处理 SIGINT（Ctrl+C）
- 在 Windows、macOS 和 Linux 上测试
- 使用一致的标志命名约定
不能做（共用）
- 破坏现有命令签名（破坏性更改）
- 在不必要的情况下阻塞同步 I/O
- 硬编码路径或特定平台的逻辑
知识参考
人类 CLI 框架
commander、yargs、oclif、click、typer、argparse、cobra、viper
终端 UI：chalk、inquirer、rich、bubbletea
Agent-native 工具链
- 参数解析：Node 原生
util.parseArgs（零依赖）
- envelope 输出：手写或最小 helper（避免框架）
- 测试：Node 原生
--test 或 vitest，断言 JSON envelope
- 分发：npm 全局 bin（
bin/cli.js）
参考实现
docs-harness（agent-native 文档管理 CLI）的 envelope / schema / signal 设计可作为完整范式参考。
相关技能
- Node.js 专家 - Node.js 实现细节
- DevOps 工程师 - 分发和打包
- skill-creator - 当需要把这套 agent-native 范式本身打包成可复用 skill 时
