生产级绕不开的一课
前面的模块教你「怎么把 pi 用起来、包出去」。生产级的另一半是**「怎么用得安全」。这一节讲安全的两根支柱：项目信任（project trust）和「没有内置沙箱」这个事实**。
先记住 pi 的定位：它是本地编码 agent，以启动它的用户权限运行，并把该用户可写的文件视为同一个本地信任边界。
.pi/ 资源、AGENTS.md，也要知道它们什么时候会触发信任提示。本节就是给 md-tools 打「安全地基」的一课。项目信任是什么、不是什么
项目信任控制的是：pi 是否加载项目本地的设置、资源、包和扩展。 关键澄清两点：
- 它不是沙箱
- 它不限制模型在你在某个目录开始工作后，能请工具做什么
一句话：信任只是「输入加载」的闸门——它防止一个仓库在你批准前静默改变 pi 的设置或扩展。它不会让不受信的代码、不受信的提示词或不受信的模型输出变安全。
什么会触发信任
pi 在以下情况下，认为项目有「需要信任的资源」：
- 存在
.pi/settings.json - 存在
.pi/extensions、.pi/skills、.pi/prompts或.pi/themes - 存在
.pi/SYSTEM.md或.pi/APPEND_SYSTEM.md - 当前目录或祖先目录有
.agents/skills
注意：光秃秃一个
.pi目录不算需要信任的项目资源。
信任决策怎么定
- 在交互会话里，pi 会提示你信任与否，默认值来自全局设置的
defaultProjectTrust（默认是"ask"） - 已保存的决策按规范目录存在
~/.pi/agent/trust.json - 会优先采用当前或父路径上最近的已保存决策，再回退到全局默认
信任一个项目后，pi 会加载这些受保护资源：.pi/settings.json、.pi 下的扩展/技能/提示词/主题/系统提示词文件、缺失的项目包、项目本地扩展等。
不信任则跳过受保护资源。注意：上下文文件（AGENTS.md、CLAUDE.md 等）无论如何都会加载（除非禁用了上下文加载）——它们不归项目信任管。
非交互模式的信任行为
-p、--mode json、--mode rpc 这些非交互模式不会弹信任提示。它们的行为取决于是否有适用的已保存决策：
defaultProjectTrust: "ask"和"never"会忽略这些资源"always"会信任它们
要单次覆盖，用 --approve/-a 或 --no-approve/-na。这对 CI、对跑 md-tools 的自动化很重要——别让脚本在无人值守时意外加载了不受信设置。
没有内置沙箱：正确看待
pi 不包含内置沙箱。内置工具能以 pi 进程的权限读文件、写文件、编辑文件、跑 shell 命令；扩展是 TypeScript 模块，也以同样的权限运行。装包、跑 shell、语言服务器、测试命令，都是普通本地进程的行为。
这是故意的：pi 设计成在本地源码树上工作、调用项目工具链、融入现有开发环境。一个「部分进程内沙箱」容易被误当成安全边界，却仍依赖宿主 shell、文件系统、包管理器、凭据和扩展代码。
真正的隔离来自操作系统或虚拟化/容器边界。
跑不受信或无人值守任务怎么办
对不受信的仓库、你不打算密切盯着的生成代码、或无人值守的自动化，官方建议在受控环境里跑：
- 把整个 pi 进程放进容器/沙箱
- 只挂载 agent 该访问的工作区路径
- 避免挂载宿主
~/.pi/agent（除非容器该访问宿主的会话、设置和凭据） - 传最小必需的 API key，或用短期凭据
- 任务不需要时限制网络访问
- 把结果拷回可信系统前，先审查 diff 和输出
如果你以读写方式 bind-mount 宿主工作区，容器/VM 里的写入仍能改宿主文件。想要更强的防误写保护，用只读挂载，或把文件拷进拷出沙箱。
落地练习：检查你的项目会触发什么信任
给 md-tools 项目做一次安全体检：
- 在项目根运行
ls -a，找出.pi/、.agents/、AGENTS.md等资源 - 用上面的「触发信任」清单逐条对照，判断它会不会触发信任提示
- 想清楚：如果是，默认
"ask"下别人首次打开会看到什么提示
怎么判断做对了？——你能判断出 md-tools 项目「需要信任」还是「不需要」；并且知道在 CI / 无人值守场景下，该用
--approve还是--no-approve。
卡住了怎么办？ 不确定某目录算不算？对照官方列出的资源清单，.pi 光秃秃不算、.pi/settings.json 才算。想让脚本自动跑？先想清楚它的 defaultProjectTrust 是什么。
常见坑：把「项目信任」当成沙箱
最危险的误解，是把项目信任当「沙箱」——以为「我信任了这个项目，所以它安全」。
完全相反。 信任只是决定「加载哪些项目设置和扩展」；它既不隔离模型，也不隔离扩展。信任了一个恶意仓库，等于给它的扩展开了绿灯。安全边界只来自操作系统/容器/VM。信任 ≠ 安全，审查 + 隔离才等于安全。
小结
- 项目信任控制是否加载项目本地设置/资源/包/扩展，不是沙箱
.pi/settings.json、.pi/*资源、.agents/skills会触发信任- 决策存
trust.json，非交互模式不弹提示 - pi 无内置沙箱，真正的隔离靠容器/VM
- 跑不受信/无人值守任务要在受控环境里，用最小凭据
下一节，讲怎么用 compaction 优化上下文。