在上下文管线中把发现与准入分开
一个文件可以存在、被发现、被准入,却永远到不了模型——用一棵临时 fixture 树看清这四个步骤各自归谁所有。
“模型读了我的 AGENTS.md"这句话藏着四个事实:文件存在、Pi 发现了它、某个东西准入了它,而它在模型收到的请求里。每一个都可能独自失败,而每一个都有一个不同的所有者。下面的摘录作为第 28 章的测试在一棵临时树上运行——默认加载器,没有模型。
发现:向上走,而不是向下扫
在 repo/src/billing 启动 Pi 时,发现从工作目录向上走到智能体目录——从不横向或向下,所以即使两者在同一个仓库里,repo/docs/AGENTS.md 也不适用于在 repo/src/billing 启动的工作:
在 repo/src/billing 中启动
agent/AGENTS.md 已发现 — 智能体目录
repo/AGENTS.md 已发现 — 一个父目录
repo/src/billing/AGENTS.md 已发现 — 工作目录
repo/docs/AGENTS.md 未被发现 — 一个兄弟测试断言那些向上走的行:
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");准入:一个覆盖只替换它旁边的东西
一个 AGENTS.override.md 替换同一目录下的 AGENTS.md 或 CLAUDE.md,而且只替换那一个。它是一个兄弟替换,而不是一个全局关闭开关——仓库根和智能体目录的那些文件在它之后仍然存续。被引用的那个测试断言了两半。
宿主拥有准入
在一个被嵌入的应用里,模型看到的文件就是资源加载器返回的东西。agentsFilesOverride 接收被找到的东西并返回要使用的东西——这里宿主丢掉用户文件并添加一个虚拟文件:
const loader = new DefaultResourceLoader({
cwd: billing,
agentDir,
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" },
],
}),
});预期结果
| 步骤 | 所有者 | fixture 结果 |
|---|---|---|
| 存在 | 无论谁写了这个仓库 | 五个文件全都在磁盘上 |
| 被发现 | Pi 的目录遍历 | 智能体、仓库和 billing 文件;docs 从不会 |
| 被准入 | Pi 的规则、你、一个扩展,或宿主 | 覆盖只替换 billing 的 AGENTS.md;宿主用一个虚拟文件换掉用户文件 |
| 在上下文中 | 请求构建器 | 加载器的列表,在每一次请求上 |
工作目录选择有哪些规则存在,而默认加载器把它读到的东西缓存起来,直到 reload();一个自定义的 ResourceLoader 自己决定。
机制与局限
有文档记载:configuration.md 锁定了发现(智能体目录、工作目录及其父目录)、被接受的名字、本地覆盖规则和 --no-context-files;sdk.md 锁定了 DefaultResourceLoader 和 agentsFilesOverride(1.0.4)。已观察:admission.test.ts 的三个测试在一棵临时树中、没有模型、用真实加载器通过对:兄弟目录从不会被发现,一个覆盖只替换它旁边的文件,而一个宿主覆盖既丢弃又添加文件。**本书提出:**四步拆分以及把准入框定为应用策略,是本书的框定方式。
这不是一道安全边界:上下文文件在没有项目信任的情况下也会加载,所以一个不熟悉仓库的 AGENTS.md 在任何东西被批准之前就被准入。如果那些指令要紧,宿主必须自己准入它们;这里不涉及模型。
完整源码与测试 。
Understand this example
Copy this prompt into your AI tool. No code runs here.
Apply this example
Copy this prompt into your AI tool. No code runs here.