Example

在上下文管线中把发现与准入分开

一个文件可以存在、被发现、被准入,却永远到不了模型——用一棵临时 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.