项目 .pi 目录与信任
哪些项目资源 Pi 只在授予信任之后才加载,以及哪些上下文文件无论信任决策如何都会加载。
你克隆了一个仓库。它里面有 .pi/extensions/migrate-schema.ts,而 migrate-schema.ts 用一个从提示词拼出来的字符串调用 execSync。Pi 会问你信不信任这个文件夹。你被问到一个真实的问题,而诚实的回答是:这个提示词对于"是"到底能换来什么,并没有说清楚。
security.md 精确地回答了它,而答案里有一个细节上的曲折,值得你在回答之前就知道。
是什么触发了这个提示
当 Pi 从当前工作目录中发现以下任何一样时,它需要一个项目信任决策:
.pi/settings.json.pi/mcp.json.pi/extensions、.pi/skills、.pi/prompts或.pi/themes.pi/SYSTEM.md或.pi/APPEND_SYSTEM.md- 当前目录或某个祖先目录中的项目
.agents/skills
一个空的 .pi 目录不需要信任。请求信任,是因为有东西将要加载。
信任准入了什么
授予信任让 Pi 可以加载项目设置、来自 .pi/mcp.json 的 MCP 服务器、.pi 下的扩展、技能、提示词模板、主题和系统提示词文件、通过项目设置配置的缺失包,以及项目本地和项目包中的扩展。
那是一份完整的清单,而它比初看更窄:清单上的每一样都是"会加载的东西",不是"被授予的许可"。
信任不做什么
security.md 在这一点上异常直接:项目信任并不限制工具调用可以访问或影响什么。Pi 启动之后,已启用的工具仍然使用 Pi 进程的操作系统权限。文件夹里的指令和其他内容也能影响模型。
以及那个无论如何都会加载的东西:
像
AGENTS.override.md、AGENTS.md和CLAUDE.md这样的上下文文件,无论项目信任如何都会加载,除非你禁用上下文加载。即使你拒绝了项目信任,也要把文件夹里的指令当作不可信的输入。
正是这个区分绊住了人们。信任管辖的是可执行资源;上下文文件携带的是指令,而它们两条路都会到达。configuration.md 从另一个方向确认了这一点:上下文文件的发现不需要项目信任。
错误:“拒绝信任意味着这个文件夹无法影响本次运行。”
正确:拒绝信任会阻止列出的那些项目资源加载。
AGENTS.md和CLAUDE.md仍然触达模型,而一旦某个工具读了其中一个,文件本身的文本也会。
flowchart TD
W["工作目录"] --> D["发现项目资源"]
D --> K{"是哪一类?"}
K -->|"上下文文件"| CF["按上下文规则加载"]
CF --> CFN["不会询问信任决策"]
K -->|"受保护资源"| T{"信任决策"}
T -->|"授予"| L["已加载"]
T -->|"拒绝"| X["已跳过"]
唯一的例外
项目信任不是一道完整的启动边界。Pi 在选择或创建会话时会读取项目的 sessionDir 设置,那发生在它判定信任之前。拒绝信任能阻止其余的项目设置和受保护资源加载,但它无法撤销那次初始的会话目录查找。
实际上:一个项目可以在你回答任何东西之前,就把你的会话指向任意目录。当你 cd 进一个你控制不了的目录时,这一点值得知道。
这个决策是如何做出的
命令行的 --approve 或 --no-approve 覆盖项最先生效。否则:
- 用户级和命令行的扩展可以处理
project_trust事件。第一个返回 yes 或 no 的扩展拥有这个决策。 - 如果没有扩展做出决定,Pi 会为当前目录或其某个父目录查找已保存的决策。最近的那个决策适用。
- 如果没有已保存的决策适用,Pi 遵循
defaultProjectTrust,它的默认值是"ask"。
已保存的决策使用规范化目录路径,存放在:
~/.pi/agent/trust.json
/trust 为以后的进程保存一个决策。父目录的决策向子级传播很方便,而在你依赖它之前值得想一想。
自动化看不见的那个漏洞
print、JSON 和 RPC 模式无法显示内置的信任提示。在没有覆盖项、扩展或已保存决策时:
defaultProjectTrust: "always"会加载受保护的项目资源。"ask"或"never"会跳过它们。
所以一次自动化的运行无法回答一个它无法提出的问题。当你想在脚本里做一个显式的一次性决定时,用 --approve 或 --no-approve:
pi --no-approve --print "Summarize README.md"
pi --approve --print "Run the project's own test suite"
一个安全的项目实际包含什么
.pi 里没有任何东西天生危险。风险状况在于这个文件夹是否包含可执行资源,以及你是否会在一个你信任的文件夹里运行它们。
一个便于审阅的项目看起来像这样:
.pi/
├── settings.json # 工具选择、压缩预算;没有扩展
├── APPEND_SYSTEM.md # 每次运行都值得写明的约定
├── prompts/ # 已审阅的文本
└── skills/ # 已审阅的文本与已审阅的脚本
审阅的顺序很重要。扩展在 Pi 进程内以你的权限执行;一个技能可以指示模型运行脚本;一个提示词模板是一个人选择运行的文本。按这个顺序读它们,能告诉你实际的风险在哪里。
信任不是你的沙箱
security.md 给出三种运行 Pi 的方式,以及每一种保护什么:
| Pi 如何运行 | 什么仍然受到保护 |
|---|---|
| 直接作为你的操作系统用户 | 那个用户无法访问的任何东西 |
| 完全在一个容器、虚拟机或沙箱内 | 你没有暴露出来的宿主机文件和进程 |
| 在隔离环境之外,工具在其中 | 通过那些工具采取的行动所触及的宿主机资源 |
无论你选哪一种,只提供任务所需的文件和服务。在命令不需要网络时限制网络访问。信任是一道审阅闸门;隔离才是边界。
需要硬边界时禁用上下文文件
如果你想对一个不熟悉的仓库运行 Pi,且不希望任何文件夹指令触达模型,-nc/--no-context-files 会禁用 AGENTS.md 和 CLAUDE.md 的发现。这是唯一有文档记载的、能移除这个未设闸门的通道的办法。
这一切都是一道加载闸门。这里决定的一切都不会约束 Pi 运行之后工具做什么,所以下一个问题不是这个文件夹被允许贡献什么,而是第一条命令实际落进的那个环境是什么。
运行了什么
examples/ch08-trust/ 在真实目录上,锻炼信任决策中住在 Pi 导出代码里的那些部分:
- 一个空的
.pi目录不需要决策,而每一个有文档记载的触发项都需要:settings.json、mcp.json、extensions、skills、prompts、themes、SYSTEM.md、APPEND_SYSTEM.md,以及祖先目录中的一个项目.agents/skills; - 上下文文件不是触发项:一个只含
AGENTS.md和CLAUDE.md的仓库什么都不会问; - 已保存的决策按最近的路径解析:父级的决策覆盖其子级,子级上的决策胜出且不动父级的决策,它们持久化在
trust.json中,而把某一项设为null会清除它; - 通过真实的资源加载器,一个未获信任的项目的扩展和提示词模板没有加载,而它的
AGENTS.md仍然加载了;同一个项目在获得信任后三者全部加载。
决策顺序本身需要随附的二进制文件,因为它住在命令行入口点里。examples/ch08-trust/decision.test.ts 在 print 模式下把真实的 pi 当作子进程运行,配一个加载时会写标志文件的项目扩展,以及一个脚本化的模型。在 print 模式下没有可以用来询问的 UI,所以被观察到的是每一个来源决定了什么:
- 在没有标志、没有扩展、没有已保存决策也没有设置时,项目扩展不会加载:默认值是
ask,而 print 模式无法询问; --approve会加载它,--no-approve不会;- 智能体目录里的
defaultProjectTrust: "always"会加载它,而"ask"和"never"不会; - 为该目录保存的决策无需任何标志即可适用,并且胜过
defaultProjectTrust; - 命令行标志胜过已保存的决策,两个方向都如此;
- 命令行扩展中的
project_trust处理器在已保存决策和默认值之前做决定:yes胜过已保存的 no,no胜过已保存的 yes,yes胜过defaultProjectTrust: "never"; - 一个回答
undecided的扩展会把决策交出去,于是已保存的决策随后适用; - 标志的级别高于扩展。
这就是本章给出的顺序,已观察:标志,然后扩展,然后已保存的决策,然后 defaultProjectTrust。
有一个细节,正文在这里说得不严谨。security.md 说第一个"返回 yes 或 no"的扩展拥有这个决策,这读起来像一个裸字符串,但 project_trust 处理器返回的不是它。随附的示例 project-trust.ts 和声明都显示出真正的契约。它的结果是一个对象,{ trusted: "yes" | "no" | "undecided", remember?: boolean }。一个返回裸字符串的处理器会被静默忽略,于是项目的资源转而遵循已保存的决策或默认值。测试的第一个版本正是这么做的,并且以那种安静的、却让这一点值得知道的方式失败了。remember 有声明,但它的行为没有被测试。