创建 CLI
设计 CLI 交互面(语法 + 行为),以人为本,脚本友好。
首先执行
- 阅读
agent-scripts/skills/create-cli/references/cli-guidelines.md并将其作为默认标准。 - 上游/完整指南:https://clig.dev/ (提出更改:https://github.com/cli-guidelines/cli-guidelines)
- 仅提出锁定界面所必需的最少澄清问题。
快速澄清
提问,如果用户不确定,则使用最佳猜测默认值继续:
- 命令名称 + 一句话用途。
- 主要用户:人类、脚本,或两者兼顾。
- 输入来源:参数 vs stdin;文件 vs URL;秘密(绝不能通过标志传递)。
- 输出契约:人类文本、
--json、--plain、退出码。 - 交互性:是否允许提示?是否需要
--no-input?破坏性操作是否需要确认? - 配置模型:标志/环境变量/配置文件;优先级;XDG 还是仓库本地。
- 平台/运行时约束:macOS/Linux/Windows;单二进制文件还是运行时依赖。
交付物(需要输出的内容)
设计 CLI 时,生成一个用户可以实现的紧凑规范:
- 命令树 + USAGE 语法摘要。
- 参数/标志表(类型、默认值、必需/可选、示例)。
- 子命令语义(每个子命令的功能;幂等性;状态变更)。
- 输出规则:stdout vs stderr;TTY 检测;
--json/--plain;--quiet/--verbose。 - 错误 + 退出码映射(主要故障模式)。
- 安全规则:
--dry-run、确认机制、--force、--no-input。 - 配置/环境变量规则 + 优先级(标志 > 环境变量 > 项目配置 > 用户配置 > 系统配置)。
- Shell 补全方案(若相关):安装/可发现性;生成命令或绑定脚本。
- 5–10 个示例调用(常见流程;包含管道/stdin 示例)。
默认约定(除非用户另有说明)
-h/--help始终显示帮助信息并忽略其他参数。--version将版本信息打印到 stdout。- 主要数据输出到 stdout;诊断/错误信息输出到 stderr。
- 添加
--json用于机器输出;考虑使用--plain输出稳定的基于行的文本。 - 仅当 stdin 是 TTY 时才进行提示;
--no-input禁用提示。 - 破坏性操作:交互式需确认;非交互式需要
--force或显式--confirm=...。 - 尊重
NO_COLOR、TERM=dumb;提供--no-color。 - 处理 Ctrl-C:快速退出;有限清理;尽可能支持崩溃安全。
模板(复制到回答中)
CLI 规范骨架
填写以下部分,删除不相关的内容:
- 名称:
mycmd - 一句话描述:
... - 用法:
mycmd [全局标志] <子命令> [参数]
- 子命令:
mycmd init ...mycmd run ...
- 全局标志:
-h, --help--version-q, --quiet/-v, --verbose(精确定义)--json/--plain(若适用)
- I/O 契约:
- stdout:
- stderr:
- 退出码:
0成功1通用失败2无效用法(解析/验证)- (仅在确实有用时添加特定命令的退出码)
- 环境变量/配置:
- 环境变量:
- 配置文件路径 + 优先级:
- 示例:
- …
备注
- 仅在询问时推荐解析库(语言特定);否则保持该技能语言无关。
- 如果请求是“设计参数”,不要偏离到实现细节。