上下文准入是应用策略
一个文件存在、被发现、被准入和到达模型是四个不同的事实;本章把它们分开,展示哪些是 Pi 的规则、哪些属于应用,并实际运行那些发现规则。
压缩把你解释过的 schema 摘要掉了,而模型请你重述一遍。你不会重述。补救办法是一个文件,因为被加载的指令随每一次请求同行,而一段对话会被压缩。第 23 章就讲到这里。
但"把它放进一个文件"是问题的开始,而不是结束。磁盘上的一个文件可能被忽略、被替换、被过滤掉,或者由你以外的某个人提供。本章讲的是藏在模型读了我的 AGENTS.md这句话里的四个分开的事实,以及谁来决断其中每一个。
四个事实,不是一个
EXISTS 文件在磁盘上,某处
DISCOVERED Pi 通过遍历目录找到了它
ADMITTED 某个东西决定它应当被使用
IN CONTEXT 它在模型实际收到的那个请求里
每一步都可能独自失败,而每一步都有一个不同的所有者:
| 步骤 | 由谁决定 | 规则 |
|---|---|---|
| 存在 | 无论谁写了这个仓库 | 无 |
| 被发现 | Pi 的目录遍历 | 智能体目录、工作目录及其父目录 |
| 被准入 | Pi 的规则、你、一个扩展,或宿主 | 覆盖文件、--no-context-files、一个资源加载器 |
| 在上下文中 | 请求构建器 | 被包含进每一次请求,取自加载器所持有的东西 |
最常见的调试错误,是检查第一步并假定其余三步。一个存在的文件未必是一个模型已经读过的文件。
被发现:向上走,而不是向下扫
configuration.md:Pi 从"智能体目录、工作目录及其父目录"加载上下文文件,而一个上下文文件"在 Pi 运行于该目录或它下面任何位置时生效"。被接受的名字是 AGENTS.override.md、AGENTS.md、AGENTS.MD、CLAUDE.md 和 CLAUDE.MD,所以一个为另一个工具写成的仓库可以原样工作。
注意方向。发现是从你启动 Pi 的位置向上走。它从不横向或向下。所以 repo/docs/AGENTS.md 里的一条规则不适用于在 repo/src/billing/ 启动的工作,即使两者在同一个仓库里。这是被运行过的,不是推断出来的:
const loader = new DefaultResourceLoader({ cwd: billing, agentDir });
await loader.reload();
const got = names(loader.getAgentsFiles().agentsFiles);
assert.ok(got.includes("AGENTS.md=user rules"), "the agent directory applies everywhere");
assert.ok(got.includes("AGENTS.md=repo rules"), "a parent directory is inherited downward");
assert.ok(!got.some((g) => g.includes("docs rules")), "a sibling directory is never discovered");
从 repo/src/billing 启动时,同一棵 fixture 树会发现用户的智能体目录文件和仓库根的那个文件,而不会发现那个兄弟的 docs 文件。那个实际后果是关于你在哪里启动 Pi:工作目录选择这一次运行有哪些规则存在。
被准入:覆盖是本地的,而过滤是某个人的决定
一旦被发现,一个文件仍可能被替换。configuration.md 有一条狭窄的规则:“一个 AGENTS.override.md 只替换同一目录下的 AGENTS.md 或 CLAUDE.md。它不会抑制来自智能体目录或其他目录的上下文文件。”
flowchart TD
R["repo AGENTS.md"] -->|向下继承| M
S["repo/src AGENTS.md"] -->|向下继承| M
O["repo/src/billing AGENTS.override.md"] -->|只替换它旁边的 AGENTS.md| M
A["agent dir AGENTS.md"] -->|适用于每一个工作目录| M
M["加载器所持有的指令,在每一次请求中"]
测试确认了两半:覆盖被准入,它旁边的 AGENTS.md 没有,而仓库根的那个仍然在。一个覆盖是一个兄弟替换,而不是一个全局关闭开关。
除 Pi 自己的规则之外,还有三方可以决定准入:
- 你,在命令行上。
-nc/--no-context-files为一次调用关掉发现。它是唯一有文档记载的开关。 - 一个扩展。
before_agent_start可以添加、替换或删除提示词节,这就是第 18 章的run_checks指引随该工具出现和消失的方式。 - 宿主,如果宿主是一个 SDK 应用。 这一个改变整个图景,而它就是本章标题的由来。
在一个应用里,宿主拥有准入
当你用 createAgentSession()(第 34 章)嵌入 Pi 时,到达模型的那些文件就是资源加载器返回的东西。DefaultResourceLoader 给你 Pi 的标准发现,外加一个覆盖钩子:agentsFilesOverride 接收被找到的东西并返回要使用的东西。编码智能体自己的 SDK 示例添加了一个根本不在磁盘上的虚拟文件。
agentsFilesOverride: (current) => ({
agentsFiles: [
...current.agentsFiles.filter((f) => !f.content.includes("user rules")), // never admit the user's own file
{ path: "/virtual/AGENTS.md", content: "policy supplied by the host" },
],
}),
这个宿主丢掉了用户自己的 AGENTS.md,并添加了一个只存在于它的配置里的文件。两者都生效了,而模型会看到那个策略文件、看不到用户写的那个文件。对一个代表许多用户运行 Pi 的服务器来说,这就是设计:应用——而不是恰好拥有某个目录的那个人——决定智能体从哪些指令起步。sdk.md 为加载器本身划出了相应的界线:当你想要带选择性覆盖的标准发现时用 DefaultResourceLoader,而当宿主完全拥有资源存储与发现时用一个自定义的 ResourceLoader。
这就是为什么准入是一种应用策略。在终端里,是 Pi 的规则在决定,而你可以覆盖它们。在一个被嵌入的智能体里,是应用在决定,而 Pi 的规则是一个它可以保留也可以替换的默认值。同一个文件可以存在、被发现,却仍然从未被准入。
系统提示词文件是另一套机制
SYSTEM.md 替换 Pi 的默认系统提示词,而 APPEND_SYSTEM.md 给它追加内容,各自都在用户级(<agent-dir>)和项目级(.pi/)上。configuration.md 的两条规则把它们与上下文文件区别开来:
对于
SYSTEM.md和APPEND_SYSTEM.md,受信任的项目文件优先于对应的智能体目录文件。同名文件不会被合并。
不合并:一个项目级的 APPEND_SYSTEM.md 会替换个人级的那个。如果你两个都要,请在一个文件里说出来。而这些文件属于项目信任门,上下文文件不属于。那种不对称——它准入什么、不准入什么——是第 8 章的主题,这里不重复。
在上下文中:没有人检查的那一部分
最后一步是可见度最低的那一步。被加载的指令被放进每一次请求的系统提示词里,取自加载器所持有的东西。正是这一点让它们在压缩后存留:关于它们没有任何东西依赖于历史。这也是它们为什么在每一次请求上都花费 token,那是第 4 章的预算。一个大的 AGENTS.md 是一项长期税,而压缩不会减少它。
“每一次请求"不意味着"每一次请求都重新读”
这个区别值得精确地说出来,因为它的错误版本是一种常见信念,而本章此前曾断言过它。默认的资源加载器在加载时读取被发现的文件,而 getAgentsFiles() 返回那份缓存列表。它不会为每一次请求重新读那个文件。
在 1.0.4 上已观察:启动一个真实会话,其 AGENTS.md 内容是 REVIEW_CONTEXT_BEFORE,发送一个请求,把文件覆盖成 REVIEW_CONTEXT_AFTER,然后在没有重载的情况下再发送一个请求。第二个 provider 请求仍然包含 REVIEW_CONTEXT_BEFORE,而不包含新文本。DefaultResourceLoader.getAgentsFiles() 自始至终返回缓存列表;reload() 才是从磁盘加载并赋予一份新列表的东西。
所以这两个事实是:
在压缩后存留 是。压缩重写对话历史,而不重写
加载器所持有的指令。
看到你最新的编辑 只有在 /reload 之后,或宿主的资源重载之后。
两个说法都是一致的。“文件在每一次请求上被读取"是错的,而这个错误很容易犯,因为那条实用建议——把它放进一个文件,而不是放进对话里——出于第一行给出的理由是对的。
这里描述的是 DefaultResourceLoader。一个自己实现 ResourceLoader 的宿主决定何时重读,而一个可以自由这么做的 SDK 应用能让那个更强的承诺成真。
要看到实际被准入了什么,usage.md 说"启动头部会列出 Pi 加载的指令与资源”,而 /reload 是把一个被编辑过的文件变成一次生效改动的那个东西。在一个 SDK 宿主里,loader.getAgentsFiles() 返回该会话将使用的列表,而打印它就是那次检查。
选择一个事实该去哪里
四个目的地,而它们不可互换。
一个上下文文件,当这个事实对代码为真时:“这个服务用整数分,绝不用浮点数。“它在压缩后存留、在每一次会话中加载,并在评审中有 diff。
一个技能,当这个事实只在某些情形下适用时。它的描述在每一次请求里,而它的正文按需加载(第 13 章)。
一个扩展,当这个事实必须被计算出来时,例如一个从哪些工具处于活动状态推导出来的提示词节(第 18 章)。
一个提示词模板,当它是你只说一次、按需才说的东西时。
要避免的错误,是把一个项目级的不变量放进一个会话的第一条用户消息里。它一直有效,直到第一次压缩,然后它就没了,而没人能说清模型为什么不再遵守它。
一个它不是的边界
一个上下文文件不是一道安全边界,拒绝信任一个项目也不是。security.md 说文件、注释、指令、命令输出和模型响应都能通过提示词注入来引导模型,而项目信任"不会让那内容或由此产生的动作变得安全”。上下文文件在没有信任的情况下也会加载,所以克隆一个不熟悉的仓库并在其中运行 pi,会在你批准任何东西之前就准入它的 AGENTS.md。对一个应用来说,推论正是上一节的要点:如果那些指令要紧,就由你自己准入它们。
你能主张什么、不能主张什么
有文档记载: 来自智能体目录和工作目录父目录的发现、被接受的文件名、覆盖规则、SYSTEM.md 和 APPEND_SYSTEM.md 的优先级、--no-context-files,以及 agentsFilesOverride 和那个加载器区分(configuration.md、sdk.md,以及 SDK 示例,1.0.4)。
已观察: examples/ch28-admission/ 里的三个测试,针对 pi-coding-agent 1.0.4 在一棵临时目录树上运行:兄弟目录不会被发现,一个覆盖只替换它旁边的文件,而一个宿主覆盖既丢弃又添加文件。这些是在默认加载器下、没有模型的情况下运行的。
本书提出: 四事实拆分,以及把准入框定为应用策略。
下一章
一个文件可能是正确的、被发现且被准入的,而这次运行仍然可能失败,因为一个智能体可靠性的另一半不是它被告知了什么,而是它底下出问题时会发生什么。
第 29 章讲失败:被重试的、被恢复的和被停止的。