PiG（Pi in Go）是把 Pi 终端编码代理的 TypeScript 代码库忠实移植为 Go 原生二进制的开源项目。它的安全设计围绕三件事展开：项目信任机制、清晰的威胁模型、以及覆盖构建到发布的供应链签名验证。本文带你读懂 PiG 主动划定的五条信任边界，并附一份可直接对照执行的 10 条安全使用清单。

PiG 是什么？为什么需要"安全深潜"

PiG 是一个极简、可扩展的终端编码代理：它以你当前用户的系统权限运行，能读写工作区文件、执行 shell 命令、加载扩展（Extension）与技能（Skill）。这意味着PiG 本身不是安全沙箱——模型输出、工具、扩展都在你的系统账户权限下执行。

因此在上手前，值得先搞清楚：哪些输入源被 PiG 当作可信？哪些它主动设防？哪些必须由你自己拍板。

📖 核心文档：docs/site/docs/security.md、docs/threat-model.md

项目信任机制：先验明正身，再开门

一个仓库里可能包含会改变 PiG 行为的项目级配置和资源。PiG 在加载任何项目可控的可执行或配置输入之前，必须先得到一个信任决定（trust decision）。信任敏感的项目路径包括：

.pig/settings.json .pig/mcp.json .pig/extensions/ .pig/skills/ .pig/prompts/ .pig/themes/ .pig/SYSTEM.md .pig/APPEND_SYSTEM.md .agents/skills/

信任判定的优先级

PiG 按以下顺序得出信任决定：

1. 命令行--approve/--no-approve优先生效；
2. 用户级或命令行扩展可处理project_trust事件，第一个返回 yes/no 的扩展拥有决定权；
3. 否则使用当前目录或最近父目录的已保存决定（按规范目录存放在~/.pig/agent/trust.json）；
4. 否则遵循全局defaultProjectTrust设置，默认值为"ask"。

⚠️ 注意：AGENTS.md、CLAUDE.md等上下文文件无论信任决定如何都会加载，所以应把目录中的指令默认视为不可信输入。

用 /trust 管理项目信任

在交互会话中运行/trust可查看和修改当前项目的信任决定；修改后请重启 PiG，让启动发现流程在新的决定下运行。

威胁模型：PiG 划出的五条信任边界

PiG 在 docs/threat-model.md 中正式声明了覆盖范围、受保护资产与威胁-控制配对，核心可归纳为五条信任边界：

常见威胁与控制措施对照：

三条值得记住的安全假设：

• 模型输出默认是不可信输入——即使连接可信，模型也可能提出危险命令；
• 单独的校验和不能替代经过认证的发布身份；
• 用户是信任的最后一道闸门：授予项目或扩展信任前，先审查来源。

供应链与发布安全：从构建到签名

PiG 采用与具体扫描器无关的供应链证据流程（docs/supply-chain.md）。每个发布候选版本都要走完：来源清点、生成 SPDX 与 CycloneDX 双格式 SBOM、核对许可证、审查漏洞可达性，最终把证据绑定到精确的产物文件上。两个细节值得了解：

1. 每个产物独立 SBOM：源码目录扫描不能替代二进制或镜像的 SBOM——源码清单可能缺少工具链组件，而二进制里可能含测试阶段不存在的依赖；
2. 主动不信任已知有问题的 CA：PiG 自身的 HTTPS/WebSocket 连接会拒绝包含特定 eMudhra 中间证书（其私钥可被恢复）的证书链，该检查无法关闭，运行在系统信任库之上。

Piglet Binary 的签名验证是整套签名体系的亮点：

• 构建时用--sign-key签名，签名覆盖全部可执行字节与 DSSE manifest；
• 执行前，Binary 先验证内嵌 Piglet、组件计划与签名，任何一个字节被改动都会拒绝运行；
• pig piglet trust add/list/revoke管理本地签名信任存储；pig piglet trust require on后，只有受信任签名者签名的 Binary 才能运行；
• pig piglet pull首次拉取即 pin 签名者，后续签名变更会被拒绝，除非你用--accept-signer ed25519:<key-id>明确接受新密钥。

详见 docs/site/docs/piglet-binaries.md。

扩展与 Package 安全使用要点

扩展会执行代码。子进程边界可以隔离崩溃、支持取消，但它不是权限沙箱。加载扩展前建议：

• ✅ 确认来源与出处，审查其依赖；
• ✅ 检查它需要执行的命令和网络访问；
• ✅ 弄清它能读到哪些文件和密钥；
• ✅ 不可信代码优先放入受限的 OS 环境；
• ✅ fused（融合）扩展与 PiG 共享进程，崩溃或死锁会影响整个应用，审查要严格一些。

Package 可以分发可执行扩展和指令类资源，安装前先用命令审查成员：

pig package validate ./package pig install ./extension --validate-only --json

参考文档：docs/site/docs/extensions.md、docs/site/docs/packages.md

凭证、会话与隐私

PiG 在本地权限管理上相当细致：

• agent 目录、sessions目录和每个项目的会话目录创建时使用0700 权限（仅属主可访问）；
• auth.json以仅属主方式创建（POSIX 下 0600，Windows 下仅属主 DACL）；
• 首次启动向导会明确询问是否共享匿名使用数据，可随时用/privacy查看和更改。

两点提醒：

1. 会话可能包含凭证——会话里会有提示词、工具参数、命令输出、文件内容，甚至对话中出现过的凭据，导出或分享前务必先审查；
2. 不要把密钥写进Piglet YAML、扩展源码包、prompt 或 skill——用环境变量或仅属主文件，PiG 会在启动前校验声明，缺失时直接拒绝启动。

强隔离：什么时候该上容器或虚拟机

如果任务涉及不可信代码或敏感数据，PiG 明确建议使用容器、虚拟机等 OS 级边界。docs/site/docs/containerization.md 提供了可直接套用的多阶段 Dockerfile，以及关键实践：

• 只挂载 PiG 需要的项目路径；只读审查时用:ro只读挂载；
• 不需要外网时直接--network none；
• 不要挂载宿主机的~/.pig——那等于把宿主凭证和会话一起送进容器。

10 条 PiG 安全使用清单

如何报告安全漏洞

发现潜在安全问题时，不要直接开公开的 issue。请遵循 .github/SECURITY.md 中的私有报告流程：附上受影响的版本、操作系统、复现步骤与影响范围，但不要附带真实凭证或无关敏感数据。

PiG 的安全哲学可以概括为一句话：它不假装能保护你，而是把能力与边界讲清楚，把信任决定权交还给你。读懂威胁模型、对照清单逐项执行，你就能安全地用好这个 Go 原生终端编码代理。