CLI 绑定¶
CLI 绑定适合本地自动化、脚本与无浏览器工作流。本页规定 AXI 语义如何映射到已有命令，不定义全行业统一的可执行文件名。
发现与调用¶
提供方应提供离线可用的帮助及窄目录读取，区分目录、精确合同和实际联网调用。以下是接口形态，product 不是本仓库提供的命令：
product capabilities --query review --format json
product schema documents.decide --format json
product call documents.decide --input-file review-input.json --format json
product operation get --key review_contract_001 --format json
能力已知时可跳过前两步。--help 或无参数调用不应意外访问生产资源或产生写入。
I/O 合同¶
人类TTY可以交互输入项目名、存放目录或已有项目；Agent也可以按需使用宿主原生选择或对话补问，参数齐备和默认政策适用时不重复提问，不先要求选择运行拓扑。显式机器模式与非TTY不能等待不可见向导；有适用且获准的默认目录政策时回显实际位置，否则返回具体缺项。人类交互与无人值守分别测试，见项目目录实践。
机器模式的 stdout 只输出一个完整 JSON 文档，诊断到 stderr；进度不得混入 JSON。大输入用 stdin 或文件，敏感参数避免出现在进程参数和 Shell 历史。文件与命令边界需正确引用，不能把 JSON 转义当 Shell 转义。
命令行设计约定¶
AXI 借鉴 POSIX 的 Utility Syntax Guidelines 和社区 Command Line Interface Guidelines。POSIX 是命令语法标准的一部分，后者是设计指南；它们都不定义 Agent 的业务授权与原操作恢复。
| 约定 | Agent 接入建议 |
|---|---|
| 一致命名与帮助 | 提供离线 --help / --version，子命令按资源和动作组织，不让帮助触发业务写入 |
| 参数与操作数 | 使用成熟解析器；正确处理引号、空格、以连字符开头的文件和 -- 分隔符；现代长选项与 POSIX 短选项的范围分别说明 |
| 人类与机器输出 | TTY 可提供简洁可读输出；显式机器模式关闭 ANSI、分页器和动画，保证稳定 JSON |
| 非交互执行 | 非 TTY 或显式无输入模式不得等待不可见提示；缺项返回具体错误，不自选生产账号 |
| 预览 | 可提供只读计划或 dry-run，明确它没有提交，也不保证稍后写入时前置仍有效 |
| 自动确认 | --yes 等选项只表达工具约定的确认，不能绕过业务权限、费用限制或用户意图 |
| 配置 | 发布参数、环境变量、配置文件的实际优先级及当前来源；切换配置不隐式改变已有未知操作 |
| 重试 | 有界处理确定未接收的可恢复错误；未知写入沿原键核对，不因通用网络重试再次提交 |
| 分发 | 使用原生包管理或可核对制品，说明平台、依赖、升级与卸载，不随意散落常驻组件 |
这些建议按真实任务采用，不要求参考例子实现一套完整包管理器或所有通用 flags。原生 CLI 已有惯例时保留兼容性，并明确映射。
| 参考例退出码 | 含义 | 是否可自动重发写入 |
|---|---|---|
| 0 | 本动作 succeeded | 否 |
| 1 | 本地或执行错误 | 需先判断是否已接收 |
| 2 | blocked 或命令参数错误 | 修正原因后重新判断 |
| 3 | unknown | 仅沿原操作恢复 |
这是本仓库示例的映射，不要求其他 CLI 放弃已有退出码。采用方必须公布自己的映射，特别是部分失败、等待结束与未知结果的区别。退出码 0 也不能代替回执中的业务状态。
取消与等待¶
Ctrl-C 或进程结束默认只停止本地等待；业务取消必须调用明确动作并回读终态。发生断开后保留安全的原任务引用，不在重启时自动重提写入。
可运行实现¶
本地审批例子使用 --db 选择示例数据库，get、decide、recover 为子命令，完整命令见快速上手。它没有联网传输或真实认证；不要把示例命令格式视为通用生产 API。