# 设计注记

> 关于 PIG 关键决策、取舍与实现边界的设计注记。

---

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

---

设计注记解释 PIG 为什么采用今天的行为。每篇注记都会标明决策日期、实现与发布边界、
被否决的替代方案，以及对应的当前用户文档。

这些文章提供历史与架构背景。当前命令语法和行为以 [PIG 文档](/zh/docs/) 为准，
交付时间线以[发布注记](/zh/release/)为准。

---

本节页面：

- [从面向人类到 Agent-Native：PIG 的 CLI 契约](/zh/design/agent-native-cli/): 为什么 PIG 将人类文本、结构化结果、执行计划与环境上下文分开，而不是把 JSON 当成最后附加的格式选项。
- [先编译和校验，再提交：原生 sty conf 流水线](/zh/design/native-sty-conf/): 为什么 pig sty conf 把 Inventory 生成视为带路径安全、结构化变更、秘密纪律和原子输出的编译流水线。
- [七成正确的调优器：界定 pig pg tune 的边界](/zh/design/pg-tune/): 为什么 pig pg tune 只生成确定性的硬件相关核心参数，而不把自己包装成完整的生产 PostgreSQL 调优方案。
- [为什么 PIG 保持扁平的 Cobra 命令层](/zh/design/flat-cobra-command-layer/): 一个顶层命令对应 cmd 中一个文件，具体行为进入 cli 与 internal 包的源码布局决策。
- [危险操作只有一套语法：PIG 运维 CLI 安全契约](/zh/design/ops-cli-safety/): PIG 如何分离底层原语与编排器、显式表达破坏性意图，并防止别名或结构化输出改变操作含义。
- [编辑声明，保留文档：无损 Pigsty Inventory](/zh/design/lossless-inventory/): 为什么 pig inventory 将 YAML 语义与源字节分离，让局部编辑能够保留注释、顺序、锚点与格式。
- [复用 Pigsty 已经拥有的 CMDB](/zh/design/existing-cmdb-boundary/): 为什么 PIG 撤销全新的 revision store 设计，转而成为 Pigsty 既有 PostgreSQL CMDB 的轻量受控适配器。
- [用有边界的 Grafana 客户端替代仪表盘脚本](/zh/design/native-grafana-management/): 为什么 pig sty grafana 只拥有仪表盘生命周期与偏好设置的一小段 HTTP 契约，而不成为通用 Grafana 管理客户端。
- [让 Patronictl 自己说话](/zh/design/patronictl-passthrough/): 为什么 pig pt 不再镜像 Patronictl 命令树，而是只保留少量 PIG 本地辅助功能的透明启动器。
- [PIG 2.0 产品方向：一份提案，而不是发布契约](/zh/design/pig-2-product-direction/): PIG 2.0 的候选边界：稳定的 Pigsty 初始化前门、可验证 Catalog 客户端，以及保持显式部署的薄编排层。
- [Catalog v2 提案：不可变 typed snapshot，而不是更大的 CSV](/zh/design/catalog-v2-snapshots/): 一套候选的可验证 Catalog 模型：typed target、内容寻址 snapshot、显式激活、项目 pin 与离线导入。
- [把 Pigsty 控制节点引导设计成可恢复事务](/zh/design/native-sty-boot/): 为什么 pig sty boot 在提权前解析来源、分离硬失败与收尾告警，并在软件源准备失败时恢复仓库定义。