跳转到主要内容

从面向人类到 Agent-Native:PIG 的 CLI 契约

PIG 如何分别提供终端文本、结构化结果、执行计划与环境上下文。

决策日期: 2026-02-12
状态: 随 pig v1.1.0 发布,并在 pig v1.10.0 中完成验收修订。2026-11-11 的输出修订已在 a95f37f 实现,不声明已发布。
当前参考: pig 命令总览
范围: PIG 命令的自动化接口,以及外部工具的原生透传接口。

决策

PIG 为终端用户提供文本,为自动化提供结构化结果。产生稳定数据的命令提供 JSON 或 YAML 与状态码, 支持计划的工作流还提供执行计划。pig pt 等透明透传命令保留外部工具的输出、提示与退出码。

背景

PIG 最初是一套便捷的软件包管理 CLI。随着它扩展到 PostgreSQL、Patroni、pgBackRest、 Pigsty 与软件仓库操作,纯面向人的接口出现了几个问题:

  • 自动化只能抓取带颜色的自然语言文本;
  • 外层进程退出为零时,内层操作仍可能已经失败;
  • 破坏性工作流在执行前无法被审阅;
  • Agent 需要连续调用许多发现命令才能理解当前主机;
  • 包装器容易把子进程输出与结构化结果混在一起。

v1.1.0 引入了全局输出选择、稳定结果对象、执行计划与 pig context 快照。 后续重构明确了各命令支持的输出方式。

考虑过的方案

考虑过以下方案:

  1. 解析人类文本。 文案、翻译、颜色与上游工具变化都会让它失效。
  2. 把所有子进程输出捕获进 JSON。 这会破坏交互程序、流式输出、终端控制与原生退出语义。
  3. 设计一个万能结果模式。 软件包事务、恢复计划、指标和环境快照拥有不同的稳定语义,强行拍平只会丢失信息。

契约

长期有效的契约是:

  • 文本是面向人的默认接口;
  • 只有在 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。参数中省略签名私钥,私钥加载的原始错误在命令内部 替换为固定文案。参数错误和不含私钥的签名密钥诊断在所有输出格式中保持可读。 其他敏感命令包装器继续隐藏捕获输出与错误详情。

2026-11-11 接受的修订要求早期错误渲染识别所有支持的输出参数形式,包括 -ojson,并尊重原生参数边界。 下载进度在文本模式进入 stderr,在结构化旧式包装器捕获期间关闭;不能出现在结果前面, 也不能进入 captured_output。有上限的旧式诊断捕获同时保留开头与结尾,并明确标记截断, 以保留最后的失败上下文。既有敏感输出隐藏规则继续覆盖全部保留的诊断内容。

影响

这种分离让脚本更可靠,也让 Agent 能够依据风险与输出能力选择命令。与此同时,每个结构化字段都需要保持兼容, stdout 纯净性需要测试,包装器也不能承诺比被委托工具更高的稳定性。

输出方式由命令决定:PIG 操作使用 PIG 结果,转发工具使用原生输出。

验证与演进

v1.10.0 已提交修订的固定源码与回归测试证据包括: 可用性与计数、 部分导入失败、 exporter HTTP 失败。上述修订已随 v1.10.0 发布。

最初框架随 v1.1.0 发布。 命令层整合提交 fb93602 随后删除重复包装器, 统一计划与输出处理。Patroni 后来改为透明透传,直接使用上游接口。

当前测试覆盖结构化 stdout 隔离、结果渲染、计划、确认门与环境上下文采集。

输出修订已在 a95f37f 中补充进程级参数错误测试,并通过旧式包装器执行隔离的 HTTP 下载,验证 stdout 恰好能解析为一个结果; 诊断截断测试保留末尾失败信息,并在超过捕获上限后继续读完输入。

当前状态

按具体命令选择其支持的输出方式。结构化结果与透传行为见 pig 参考文档。