# 设计注记

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

---

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

---

设计注记解释 PIG 的决策与提案。每篇都列出日期、状态、范围、备选方案与依据。
提案介绍正在讨论的方向；已实现、已发布的记录说明已经完成的对应工作。

查命令语法与操作步骤，请读 [PIG 文档](/zh/docs/)；查各版本的变更，请读 [发布注记](/zh/release/)。

---

本节页面：

- [从面向人类到 Agent-Native：PIG 的 CLI 契约](/zh/design/agent-native-cli/): PIG 如何分别提供终端文本、结构化结果、执行计划与环境上下文。
- [先编译和校验，再提交：原生 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 如何复用 Pigsty 既有 PostgreSQL CMDB，并撤销重复的版本存储设计。
- [用有边界的 Grafana 客户端替代仪表盘脚本](/zh/design/native-grafana-management/): pig sty grafana 如何通过原生 HTTP 客户端管理仪表盘与偏好设置。
- [让 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 提案：不可变的分类快照](/zh/design/catalog-v2-snapshots/): 用分类数据文件组成可验证的 Catalog 快照，支持原子激活、项目版本锁定与离线导入。
- [把 Pigsty 控制节点引导设计成可恢复事务](/zh/design/native-sty-boot/): 为什么 pig sty boot 在提权前解析来源、分离硬失败与收尾告警，并在软件源准备失败时恢复仓库定义。
- [为什么 PIG 默认构建调试包](/zh/design/debug-packages-by-default/): 将 RPM debuginfo/debugsource 与 DEB dbgsym 从显式启用改为显式退出的构建策略决策。
- [自动安装 Pigsty 仓库公钥](/zh/design/automatic-pigsty-repo-key/): 配置 Pigsty 仓库时准备内嵌公钥，明确默认失败处理与显式密钥要求。
- [一键配置 Xray 客户端与服务端](/zh/design/xray-client-server/): 以现有可工作的客户端与服务端为参考，为 build proxy 增加配套的 VLESS、REALITY 与 Vision 初始化能力。
- [受保护软件包只能通过显式内核别名卸载](/zh/design/protected-package-removal/): 根据最终软件包和原始输入决定卸载边界，同时保留独立语言包的卸载能力。
- [官网与 CLI 统一按目录条目计数](/zh/design/catalog-entry-count/): 官网、扩展列表、可用性摘要和目录刷新结果统一统计全部目录记录。
- [分类别名按目标 PostgreSQL 大版本解析](/zh/design/category-alias-target-version/): 动态分类别名选择扩展软件包时，使用请求的 PostgreSQL 大版本。
