用途
cli-patterns 提供用于构建生产级 CLI 工具的模式，目标是让 AI 助手和高级用户能够串联命令、以程序化方式解析输出，并依赖其可预测的行为。资料将其定位为面向 agentic workflows（智能体工作流）的 CLI 设计规范。
核心理念
- 自文档化：--help 内容全面且始终最新，使 LLM 无需外部文档即可发现能力。
- 可预测：所有命令遵循相同模式，学一次即可处处使用。
- 可组合：遵循 Unix 哲学，把一件事做好，工具之间自然串联。
- 可解析：--json 始终可用且始终有效，便于机器消费。
- 默认静默：只输出数据，除非明确要求，否则不加装饰。
- 快速失败：无效输入立即报错，不产生静默失败或部分结果。
设计公理
- stdout 是神圣的：只放数据，绝不放进度、日志或装饰。
- stderr 面向人类：进度条、颜色、表格、警告都放在这里。
- 退出码有意义：脚本可据此判断失败模式。
- 帮助包含示例：这是理解工具最快的路径。
- JSON 结构可预测：所有命令保持相同结构。
命令架构
结构模式：
<tool> [global-options] <resource> <action> [options] [arguments]
层级包含全局标志（--version、--help）、auth 子命令（login、status、logout）以及以复数名词表示的领域资源，资源下包含 list、get <id>、create、update <id>、delete <id> 及自定义动作。
命名约定：工具名小写 2-12 字符；资源用复数小写名词；动作用小写动词；长标志用 kebab-case；短标志用单个字母。
标准资源动作：list（GET /resources，返回数组，幂等）、get <id>（返回对象，幂等）、create（POST，返回创建对象，非幂等）、update <id>（PATCH，返回更新对象，幂等）、delete <id>（DELETE，返回确认，幂等）、search（GET /resources?q=，返回数组，幂等）。
标志与选项
每个命令必须支持 --help/-h（帮助文本到 stdout，退出 0）和 --json（JSON 到 stdout）。根命令还必须支持 --version/-V。
推荐标志包括 --quiet/-q、--verbose/-v、--dry-run、--limit/-n（默认 20）、--output/-o、--format/-f。
标志行为规则：布尔标志不带值（--json 而非 --json=true）；短标志可组合（-vq 等于 -v -q）；未知标志视为错误，绝不静默忽略；重复标志取最后一个值（或在不适当时报错）。
输出规范
流分离是最关键规则：stdout 只接收数据（设置 --json 时为 JSON，交互模式下为最小文本输出），永远不放其他内容；stderr 接收进度指示、状态消息、警告、富格式表格、颜色装饰和调试信息。
交互检测通过 sys.stdout.isatty() 和 sys.stderr.isatty() 判断是否连接终端。终端场景下富输出到 stderr、摘要到 stdout；管道或重定向场景下最小/JSON 输出到 stdout；设置 --json 时 JSON 到 stdout 并抑制 stderr 噪音。
JSON 输出约定：列表响应为 {"data": [...], "meta": {...}}；单项为 {"data": {...}}；错误为 {"error": {"code": "...", "message": "..."}}；日期用 ISO 8601，金额用十进制，ID 用字符串。
退出码
采用语义化退出码：0 SUCCESS、1 ERROR（一般/未知错误）、2 AUTH_REQUIRED、3 NOT_FOUND、4 VALIDATION、5 FORBIDDEN、6 RATE_LIMITED、7 CONFLICT。脚本可据此分支处理，示例中给出 case $? 的用法，以及对应的 Python 常量定义方式。
错误处理
设置 --json 时，错误向 stdout 输出结构化 JSON，同时向 stderr 输出人类可读消息。错误代码包括 AUTH_REQUIRED、TOKEN_EXPIRED、FORBIDDEN、NOT_FOUND、VALIDATION_ERROR、INVALID_ARGUMENT、MISSING_ARGUMENT、RATE_LIMITED、CONFLICT、ALREADY_EXISTS、INTERNAL_ERROR、API_ERROR、NETWORK_ERROR，并给出对应退出码。文档给出 _error 函数的实现模式。
帮助系统
每个 --help 输出必须包含：一行简要描述、用法语法、带描述的选项、以及示例。示例应展示基本用法、常用过滤、JSON 管道（如通过 jq）以及真实场景。
认证
需要认证的工具必须实现 auth login、auth status、auth logout。凭证存储优先级：环境变量（如 MYTOOL_API_TOKEN）优先级最高并覆盖其他来源；OS keyring 作为主要安全存储（Windows 凭据管理器、macOS Keychain、Linux Secret Service），静态加密、按用户隔离；.env 文件作为开发回退，须加入 .gitignore。依赖示例包括 keyring>=24.0.0 和 python-dotenv>=1.0.0。简单替代方案是仅在 ~/.config/<tool>/ 下使用配置文件。未认证时的行为示例会返回退出码 2。
数据约定
- 日期输入灵活（ISO 日期、ISO 日期时间、today/yesterday/tomorrow、last/this），输出严格使用 ISO 8601。
- 金额存储为十进制数而非分，歧义时包含货币，JSON 中不做格式化（不带 $ 或 ,）。
- ID 始终为字符串，即使原本是数字，并保留源格式。
- 枚举在 JSON 中为 UPPER_SNAKE_CASE，输入大小写不敏感。
过滤与分页
提供按状态、日期范围（--from/--to、--month）、相关实体、文本搜索、布尔过滤的常见模式，以及基于 limit/offset、page、cursor 的分页方式。
反模式
文档列出：输出污染（进度信息混入 stdout）、非交互场景弹出交互提示、同一概念使用不一致标志、以及失败时仍返回成功退出码的静默失败。
快速参考
必选清单包括 --version、带示例的 --help、list、get <id>、语义化退出码、错误到 stderr/数据到 stdout、--json 输出有效 JSON、流分离。推荐补充包括认证命令、增删改操作、--quiet/--verbose、变更操作的 --dry-run、分页、过滤和自动化测试。
框架选择
新工具推荐 Typer（类型提示自动校验、内置帮助生成、Rich 集成、样板代码少）；已有工具可接受 Click（Typer 基于 Click，100% 兼容）。两者必须遵循相同的输出约定，示例中将 Console 指向 stderr。
限制
资料未提供具体的安装命令、该技能本身的调用方式、定价或平台支持信息，暂未提供。