从面向人类到 Agent-Native：PIG 的 CLI 契约
决策日期： 2026-02-12
状态： 随 pig v1.1.0 发布，之后随命令层演进调整。下述验收修订已实现（Implemented），纳入 v1.10.0 候选版本，尚未发布。
当前参考：pig命令总览
范围： PIG 命令的自动化接口，以及外部工具的原生透传接口。
决策
PIG 为终端用户提供文本，为自动化提供结构化结果。产生稳定数据的命令提供 JSON 或 YAML 与状态码，
支持计划的工作流还提供执行计划。pig pt 等透明透传命令保留外部工具的输出、提示与退出码。
背景
PIG 最初是一套便捷的软件包管理 CLI。随着它扩展到 PostgreSQL、Patroni、pgBackRest、 Pigsty 与软件仓库操作，纯面向人的接口出现了几个问题：
- 自动化只能抓取带颜色的自然语言文本；
- 外层进程退出为零时，内层操作仍可能已经失败；
- 破坏性工作流在执行前无法被审阅；
- Agent 需要连续调用许多发现命令才能理解当前主机；
- 包装器容易把子进程输出与结构化结果混在一起。
v1.1.0 引入了全局输出选择、稳定结果对象、执行计划与 pig context 快照。
后续重构明确了各命令支持的输出方式。
考虑过的方案
考虑过以下方案：
- 解析人类文本。 文案、翻译、颜色与上游工具变化都会让它失效。
- 把所有子进程输出捕获进 JSON。 这会破坏交互程序、流式输出、终端控制与原生退出语义。
- 设计一个万能结果模式。 软件包事务、恢复计划、指标和环境快照拥有不同的稳定语义，强行拍平只会丢失信息。
契约
长期有效的契约是：
- 文本是面向人的默认接口；
- 只有在 PIG 拥有稳定结果时，命令才声明支持结构化输出；
- 结构化 stdout 只包含一个可解析结果，诊断与被包装工具的输出进入 stderr；
- 计划描述动作、范围、风险和预期效果，但不执行动作；
- PIG 自己拥有的破坏性操作在缺少确认时默认失败；
- 状态码区分用法、确认、环境、依赖与执行失败；
pig context提供有边界的环境快照，不要求调用方自行拼接；- 透明透传命令保持上游契约。
2026-10-16 修订将同一契约应用于 pig ext：
- 可用性判断与各格式摘要共用矩阵优先级、架构别名及元数据回退规则。 macOS 只报告声明支持的 PostgreSQL 版本，不承诺存在安装包。 这里描述的是目录中的包快照；默认构建目标仍按版本元数据与本机安装规则选择， 不受包矩阵影响。
- 部分导入失败必须返回失败，同时保留已解析、已下载和未解析的条目。 已完成的下载留在磁盘上，操作不承诺全有或全无事务。
pig pe将 HTTP 4xx/5xx 视为失败。错误详情只包含状态码与标准说明， 不包含响应体或服务端自定义的状态描述。pig license issue明确交付新签发的凭据，成功时在结构化结果的data.captured_output中保留 Token。参数中省略签名私钥，私钥加载的原始错误在命令内部 替换为固定文案。参数错误和不含私钥的签名密钥诊断在所有输出格式中保持可读。 其他敏感命令包装器继续隐藏捕获输出与错误详情。
影响
这种分离让脚本更可靠，也让 Agent 能够依据风险与输出能力选择命令。与此同时，每个结构化字段都需要保持兼容， stdout 纯净性需要测试，包装器也不能承诺比被委托工具更高的稳定性。
输出方式由命令决定：PIG 操作使用 PIG 结果，转发工具使用原生输出。
验证与演进
v1.10.0 已提交修订的固定源码与回归测试证据包括： 可用性与计数、 部分导入失败、 exporter HTTP 失败。这些提交不构成版本发布证据。
最初框架随 v1.1.0 发布。
命令层整合提交 fb93602 随后删除重复包装器，
统一计划与输出处理。Patroni 后来改为透明透传，直接使用上游接口。
当前测试覆盖结构化 stdout 隔离、结果渲染、计划、确认门与环境上下文采集。
当前状态
按具体命令选择其支持的输出方式。结构化结果与透传行为见 pig 参考文档。