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

> 为什么 PIG 将人类文本、结构化结果、执行计划与环境上下文分开，而不是把 JSON 当成最后附加的格式选项。

---

LLMS 索引： [llms.txt](/zh/llms.txt)

---

> **决策日期：** 2026-02-12<br>
> **状态：** 在 [pig v1.1.0](/zh/release/pig-1.1.0/) 中实现，之后继续通过命令层重构收敛。<br>
> **当前参考：** [`pig` 命令总览](/zh/cmd/)<br>
> **范围：** PIG 自己拥有的命令及其机器消费契约；不透明的透传命令保留原生接口。

## 决策 {#decision}

PIG 应当既适合人在终端中使用，也适合自动化 Agent 调用，而且不要求任何一方解析另一方的展示格式。
面向人的文本保持简洁、便于操作；真正拥有稳定结果的命令提供明确的 JSON/YAML 结果、状态码与执行计划。
仅仅转发外部工具的命令则保留原生输出流、提示与退出码，不能套上一层看似统一、实则失真的结果信封。

因此，Agent-Native 的含义是明确能力边界，而不是“给每条命令都加上 JSON”。

## 背景 {#context}

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

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

v1.1.0 引入了全局输出选择、稳定结果对象、执行计划与 `pig context` 快照。
后续重构又把这些承诺收窄到 PIG 真正能够可靠拥有的命令上。

## 考虑过的方案 {#alternatives}

以下三种看似简单的方案被否决：

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

## 契约 {#contract}

长期有效的契约是：

- 文本是面向人的默认接口；
- 只有在 PIG 拥有稳定结果时，命令才声明支持结构化输出；
- 结构化 stdout 只包含一个可解析结果，诊断与被包装工具的输出进入 stderr；
- 计划描述动作、范围、风险和预期效果，但不执行动作；
- PIG 自己拥有的破坏性操作在缺少确认时默认失败；
- 状态码区分用法、确认、环境、依赖与执行失败；
- `pig context` 提供有边界的环境快照，不要求调用方自行拼接；
- 透传与交互命令保持上游契约。

## 影响 {#impact}

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

PIG 有意允许不同命令采用不同接口风格。统一很有价值，但忠实表达语义比外观一致更重要。

## 验证与演进 {#verification}

最初框架随 [v1.1.0](https://github.com/pgsty/pig/releases/tag/v1.1.0) 发布。
命令层整合提交 [`fb93602`](https://github.com/pgsty/pig/commit/fb93602) 随后删除重复包装器，
统一计划和输出胶水。Patroni 后来改为透明透传，正好说明当上游接口已经权威时，PIG 应减少自己拥有的结构。

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

## 当前状态 {#status}

这项原则仍然有效：应使用具体命令明确声明支持的结构化模式，不能推断全局 `-o` 能安全转换所有外部或交互输出流。
当前命令面与示例维护在 [`pig` 参考文档](/zh/cmd/)中。