项目信任 Project Trust 与 /trust

为什么需要「信任」

你可能会想：都让 Pi 干活了，还问什么信不信任？原因很实在：项目里有 project-local settings、资源，以及 .agents/skills，甚至项目扩展。这些是别人写的、能被 Pi 自动执行的代码——万一项目是从网上下来的，里面藏了危险操作怎么办？

所以 Pi 在交互式启动时，会在遇到一个「含项目级设置/资源/技能、且父目录也没有保存过信任决定」的项目文件夹时，先问你一句要不要信任。

信任之后，Pi 才允许加载这个项目的 project-local extensions、project package-managed extensions 和 project settings。

---

信任前后，加载的东西不一样

官方文档专门强调了这个「信任分界」：

信任决定前，Pi 只加载：上下文文件、用户/全局扩展、CLI 用 -e 指定的扩展——这样它们能处理 project_trust 事件。

信任决定后，Pi 才加载：项目本地扩展、项目包管理的扩展、项目设置。

这就像过安检：先让「信得过的自己人」进去处理信任判断，放行后再让项目自带的代码进来。

---

三个信任档位：ask / always / never

如果你的项目没有扩展或保存的决定来决定，回退行为由 defaultProjectTrust 控制，三档可选：

档位	行为
ask	询问（默认）
always	总是信任，直接加载项目资源
never	从不信任，忽略项目资源

在 ~/.pi/agent/settings.json 里这样配置：

{
  "defaultProjectTrust": "always"
}

也可以用交互式 /settings 改。想改默认行为、又不想每次都被问，就把默认设成你常用的档位。

---

非交互模式与一次性的信任

不是所有模式都会弹窗。官方明确：非交互模式（-p、--mode json、--mode rpc）不显示信任提示。 没有保存的信任决定时，就按 defaultProjectTrust 来。

想给单次运行临时覆盖，用这两个旗标：

pi --approve       # 本次信任项目本地文件
pi --no-approve    # 本次忽略项目本地文件

适合在脚本、CI、一次性批处理里用——不想被交互弹窗卡住，就显式指定。

---

落地练习：信任 md-tools 项目并保存决定

1. 给 md-tools/.pi/ 建一个空的 settings.json（制造「项目级设置」），触发信任询问
2. 启动 pi，遇到询问时选「信任」，然后执行 /trust 把决定保存下来
3. 退出再进，确认不再重复询问（决定已写入 ~/.pi/agent/trust.json）

怎么判断做对了？——首次会问，保存后用 /trust 或直接再次启动不再重复问；查看 ~/.pi/agent/trust.json 能看到对应目录的记录。

卡住了怎么办？ 不弹窗 → 可能项目不含触发信任的资源，先放个 .pi/settings.json 或 .agents/skills。保存不生效 → /trust 只写 trust.json，当前会话不会热重载，要重启 Pi 才生效。想改默认 → 在 ~/.pi/agent/settings.json 设 defaultProjectTrust。

---

常见坑：改了 /trust 却「没反应」

很多人保存了信任决定，却发现没变化。关键点官方写得很清楚：/trust 只写入 ~/.pi/agent/trust.json，当前会话不会重载——你要重启 Pi，改动才生效。

这不是 bug，是设计。所以判断信任是否生效，记住三步：先 /trust 保存 → 重启 Pi → 再看行为。别指望当场见效。

---

小结

1. Project Trust 是 Pi 对项目级设置/资源/技能的「信任开关」
2. 信任前只加载上下文、全局/CLI 扩展；信任后才加载项目级代码
3. 默认档位 ask，可改 always / never（defaultProjectTrust）
4. 非交互模式不弹窗，可用 --approve / --no-approve 单次覆盖
5. /trust 只写 trust.json，需重启生效

下一节进入 M02，我们开始真正造「技能」——把 md-tools 变成可一键复用的 Skill。