从面向人类到 Agent-Native：PIG 的 CLI 契约
决策日期： 2026-02-12
状态： 在 pig v1.1.0 中实现，之后继续通过命令层重构收敛。
当前参考：pig命令总览
范围： PIG 自己拥有的命令及其机器消费契约；不透明的透传命令保留原生接口。
决策
PIG 应当既适合人在终端中使用，也适合自动化 Agent 调用，而且不要求任何一方解析另一方的展示格式。 面向人的文本保持简洁、便于操作；真正拥有稳定结果的命令提供明确的 JSON/YAML 结果、状态码与执行计划。 仅仅转发外部工具的命令则保留原生输出流、提示与退出码，不能套上一层看似统一、实则失真的结果信封。
因此，Agent-Native 的含义是明确能力边界，而不是“给每条命令都加上 JSON”。
背景
PIG 最初是一套便捷的软件包管理 CLI。随着它扩展到 PostgreSQL、Patroni、pgBackRest、 Pigsty 与软件仓库操作，纯面向人的接口出现了几个问题：
- 自动化只能抓取带颜色的自然语言文本；
- 外层进程退出为零时，内层操作仍可能已经失败；
- 破坏性工作流在执行前无法被审阅；
- Agent 需要连续调用许多发现命令才能理解当前主机；
- 包装器容易把子进程输出与结构化结果混在一起。
v1.1.0 引入了全局输出选择、稳定结果对象、执行计划与 pig context 快照。
后续重构又把这些承诺收窄到 PIG 真正能够可靠拥有的命令上。
考虑过的方案
以下三种看似简单的方案被否决：
- 解析人类文本。 文案、翻译、颜色与上游工具变化都会让它失效。
- 把所有子进程输出捕获进 JSON。 这会破坏交互程序、流式输出、终端控制与原生退出语义。
- 设计一个万能结果模式。 软件包事务、恢复计划、指标和环境快照拥有不同的稳定语义，强行拍平只会丢失信息。
契约
长期有效的契约是：
- 文本是面向人的默认接口；
- 只有在 PIG 拥有稳定结果时，命令才声明支持结构化输出；
- 结构化 stdout 只包含一个可解析结果，诊断与被包装工具的输出进入 stderr；
- 计划描述动作、范围、风险和预期效果，但不执行动作；
- PIG 自己拥有的破坏性操作在缺少确认时默认失败；
- 状态码区分用法、确认、环境、依赖与执行失败；
pig context提供有边界的环境快照，不要求调用方自行拼接；- 透传与交互命令保持上游契约。
影响
这种分离让脚本更可靠，也让 Agent 能够依据风险与输出能力选择命令。与此同时，每个结构化字段都会成为兼容表面， stdout 纯净性需要测试，包装器也不能承诺比被委托工具更高的稳定性。
PIG 有意允许不同命令采用不同接口风格。统一很有价值，但忠实表达语义比外观一致更重要。
验证与演进
最初框架随 v1.1.0 发布。
命令层整合提交 fb93602 随后删除重复包装器，
统一计划和输出胶水。Patroni 后来改为透明透传，正好说明当上游接口已经权威时，PIG 应减少自己拥有的结构。
当前测试覆盖结构化 stdout 隔离、结果渲染、计划、确认门与环境上下文采集。
当前状态
这项原则仍然有效：应使用具体命令明确声明支持的结构化模式，不能推断全局 -o 能安全转换所有外部或交互输出流。
当前命令面与示例维护在 pig 参考文档中。