← Pi Agents

项目 .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 覆盖项最先生效。否则:

  1. 用户级和命令行的扩展可以处理 project_trust 事件。第一个返回 yes 或 no 的扩展拥有这个决策。
  2. 如果没有扩展做出决定,Pi 会为当前目录或其某个父目录查找已保存的决策。最近的那个决策适用。
  3. 如果没有已保存的决策适用,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 有声明,但它的行为没有被测试。