cli-ops 是一套用于构建 CLI 工具的模式集合，目标是让 AI 助手和高级用户能够链式调用、程序化解析并依赖这些工具。它强调为智能体工作流而构建——使用者会串联命令、解析输出，并期望行为可预测。
核心理念
工具应当遵循六条核心原则：自文档化（--help 全面且始终最新，使 LLM 无需外部文档即可发现能力）；可预测（所有命令使用相同模式，学一次即可到处使用）；可组合（遵循 Unix 哲学，一件事做好，工具自然串联）；可解析（--json 始终可用且始终有效，便于机器消费）；默认安静（只输出数据，除非请求否则不加装饰，脚本不会因意外输出而中断）；快速失败（无效输入立即报错，不出现静默失败或部分结果）。
设计公理
stdout 是神圣的——只放数据，绝不放进度、日志或装饰。stderr 是给人看的——进度条、颜色、表格、警告都放在这里。退出码有意义——脚本可以根据失败模式分支。帮助中包含示例——这是理解工具最快的路径。JSON 结构可预测——所有命令使用相同结构。
命令架构
命令采用分层结构：<tool> [global-options] <resource> <action> [options] [arguments]。资源使用复数名词作为域资源，支持 list（获取多个）、get <id>（按 ID 获取一个）、create（创建，如支持）、update <id>（修改，如支持）、delete <id>（删除，如支持）以及自定义动作。命名约定要求：工具名小写、2-12 字符；资源为小写复数名词；动作为小写动词；长标志使用 kebab-case；短标志为单个字母。
标志与选项
每个命令必须支持 --help/-h（显示含示例的帮助，输出到 stdout，退出码 0）和 --json（机器可读输出到 stdout）。根命令还必须额外支持 --version/-V。推荐标志包括 --quiet/-q、--verbose/-v、--dry-run、--limit/-n、--output/-o、--format/-f。标志行为规则：布尔标志不带值（--json 而非 --json=true）；短标志可组合（-vq 等于 -v -q）；未知标志视为错误，绝不静默忽略；重复标志以最后一个值为准（或不合适时报错）。
输出规范
最关键规则是流分离：stdout 只接收数据（--json 时为 JSON，交互时为最小文本输出），stderr 接收进度指示、状态消息、警告、富格式表格、颜色装饰以及调试信息。交互检测通过 sys.stdout.isatty() and sys.stderr.isatty() 判断：连接终端时向 stderr 输出富文本、向 stdout 输出摘要；管道或重定向时向 stdout 输出最小/JSON 内容；设置 --json 时向 stdout 输出 JSON 并抑制 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（状态冲突）。脚本可根据退出码分支处理。
错误处理
使用 --json 时，错误将结构化 JSON 输出到 stdout，同时向 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。
帮助系统
每个 --help 输出必须包含：一行简要描述、用法语法、带描述的选项、示例（对发现能力至关重要）。示例应展示基本用法、常用过滤器、JSON 管道（与 jq 链接）以及真实场景。
认证
需要认证的工具必须实现 auth login、auth status、auth logout。凭据存储优先级：环境变量（最高优先级）、操作系统钥匙串（主要安全存储，Windows 凭据管理器、macOS 钥匙串、Linux Secret Service）、.env 文件（开发回退，需加入 .gitignore）。依赖包括 keyring 和 python-dotenv，也可简化为 ~/.config/<tool>/ 下的配置文件。未认证时返回退出码 2 并提示运行 auth login。
数据约定
日期输入灵活（ISO 日期、ISO 日期时间、相对时间如 today/yesterday），输出严格使用 ISO 8601。金额存储为十进制数而非分，歧义时包含货币，JSON 中不做格式化。ID 始终为字符串。枚举在 JSON 中使用 UPPER_SNAKE_CASE，输入大小写不敏感。
过滤与分页
支持按状态、日期范围、关联实体、文本搜索、布尔过滤器筛选。分页支持 --limit、基于偏移的 --page/--offset 以及基于游标的 --cursor/--after。
反模式
避免输出污染（进度信息混入 stdout）、非交互上下文中的交互式提示（应快速失败并提示必需标志）、不一致的标志、静默失败（失败时应返回语义化退出码）。
快速参考
必备清单：--version、含示例的 --help、resource list [--json]、resource get <id> [--json]、语义化退出码、错误到 stderr 数据到 stdout、--json 输出有效 JSON、流分离。推荐添加：认证命令、增删改操作、--quiet/--verbose 模式、--dry-run、分页、过滤、自动化测试。框架推荐 Typer（类型提示自动验证、内置帮助生成、Rich 集成、样板少），Click 可接受（Typer 基于 Click，结构良好的 Click 代码无需迁移）。使用 Rich 时 Console(stderr=True) 将 UI 输出到 stderr。