AGENTS.md Instruction Loader

本课交付结果

你将交付 loadInstructions({ root, targetPaths, maxBytes })：只读取每个目标祖先链上的 AGENTS.md，按根级到更深目录排序；多目标共享指令只加载一次，并用 realpath 与总字节预算限制输入。

岗位问题

大型 monorepo 的不同目录有不同约束。全仓库扫描会把无关甚至冲突指令都塞给模型；只读根文件又会漏掉局部测试和风格规则。symlink 还可能把“指令文件”指向工作区外秘密。

前置检查

前置知识快照

回顾第 8 课词法与 realpath 双层边界：

bash

pnpm --filter @learn-traeai/coding-agent-bootcamp verify:lesson -- 08

目标路径可以尚不存在，但必须是工作区内相对路径；存在的 AGENTS.md 必须解析后仍在真实 root 内。

Instruction Loader不是全仓库搜索。它根据本次要修改的targetPaths计算作用域：根规则对全仓库生效，越靠近目标的局部规则越具体，完全无关目录的指令不进入上下文。这样既减少token，也避免API规则污染Web任务。

路径边界复用第8课：target拒绝绝对与..，root先realpath；每个实际AGENTS.md也realpath，防止工作区内symlink指向用户主目录秘密。提示词说“不要越界”不能替代读取层强制。

原理拆解

对 apps/web/src/a.ts 构造祖先链 root → apps → apps/web → apps/web/src，逐层查找 AGENTS.md。用 Set 保持首次发现顺序并为多目标去重。读取每个文件前 realpath，累加 UTF-8 字节数而非字符数。

mermaid

flowchart TD
  A[root + targetPaths] --> B[realpath root]
  B --> C[校验每个相对target]
  C --> D[构造根到目标目录祖先链]
  D --> E[逐层候选AGENTS.md]
  E --> F{已seen?}
  F -- 是 --> G[跳过共享祖先]
  F -- 否 --> H{文件存在?}
  H -- 否 --> I[继续]
  H -- 是 --> J[realpath仍在root?]
  J -- 否 --> K[拒绝逃逸]
  J -- 是 --> L[读取并累计UTF-8字节]
  L --> M{总预算内?}
  M -- 否 --> N[失败]
  M -- 是 --> O[按发现顺序返回]

目标路径可以尚不存在，因为Agent可能计划新建文件；祖先链基于词法目标目录构造。存在的指令文件才访问磁盘并验证真实路径。不能为了验证不存在target调用realpath，否则所有新文件任务都失败。

顺序决定覆盖语义。根指令先进入上下文，局部随后，模型与规则合并器可让更具体约束补充或覆盖全局。不要按文件名全局排序，apps/web/AGENTS.md若跑到根前，优先级含义倒置。

多目标按输入顺序遍历，各自祖先从根到深层；Set对完整候选路径去重，所以共享根只出现一次。web/api示例得到root、web、api。若目标顺序反转，则root、api、web；跨分支没有天然深浅优先，调用方顺序应稳定或按规范target排序。

预算按Buffer.byteLength(content)，不是字符串length。中文与emoji占多个UTF-8字节，磁盘和模型输入成本不能用UTF-16近似。每个文件读取后累计，超过总上限整次失败，不返回部分规则让Agent误以为指令完整。

代码实验

失败实现

递归扫描全仓并按文件名排序会加载无关规则，也看不到链接逃逸：

const files = await glob("**/AGENTS.md", { cwd: root });
return Promise.all(files.sort().map(async (path) => ({
  path,
  content: await readFile(join(root, path), "utf8"),
})));

正确实现从每个target祖先链构造候选，并对真实文件做边界检查：

const realRoot = await realpath(options.root);
for (const targetPath of options.targetPaths) {
  if (isAbsolute(targetPath) || targetPath.split(/[\\/]/).includes("..")) {
    throw new Error("目标路径超出工作区");
  }
  const target = resolve(realRoot, targetPath);
  const segments = relative(realRoot, dirname(target)).split(sep).filter(Boolean);
  let directory = realRoot;
  for (const segment of ["", ...segments]) {
    if (segment) directory = join(directory, segment);
    const instruction = join(directory, "AGENTS.md");
    if (seen.has(instruction)) continue;
    seen.add(instruction);
    // 存在时 realpath、边界比较、读取和预算累计
  }
}

候选在检查存在前加入seen，多个target共享一个缺失路径也只stat/realpath一次。若文件在两次目标遍历间被创建，单次load仍保持首次快照语义；下一次调用会读取。长运行缓存需要文件watch或内容hash失效。

打开本课 Lab

bash

pnpm --dir bootcamps/coding-agent/labs/24-instruction-loader/starter test
pnpm --dir bootcamps/coding-agent/labs/24-instruction-loader/solution test

Starter 应声明 实现嵌套指令优先级；Solution 应通过 5 项测试。

symlink逃逸测试使用真实外部临时目录：

it("拒绝链接到工作区外的指令", async () => {
  await writeFile(join(outside, "AGENTS.md"), "secret");
  await rm(join(root, "apps/web/AGENTS.md"));
  await symlink(
    join(outside, "AGENTS.md"),
    join(root, "apps/web/AGENTS.md"),
  );
  await expect(loadInstructions({
    root,
    targetPaths: ["apps/web/src/a.ts"],
    maxBytes: 100,
  })).rejects.toThrow("工作区");
});

关键实现讲解

具体例子：根 AGENTS.md 写“中文输出”，apps/web/AGENTS.md 写“运行前端测试”，apps/api/AGENTS.md 写“运行 API 测试”。只改 web 时得到 [root, web]；同时改 web/api 时得到 [root, web, api]，root 不重复。

外部路径判断使用relative(realRoot, actual)，结果等于..、以../开头或为absolute即越界。字符串startsWith会被相似前缀绕过；root与actual都必须是realpath，避免macOS系统别名造成误判。

ENOENT只代表该层没有AGENTS.md，继续祖先链；EACCES、ELOOP和越界错误必须抛出。把所有catch当不存在会在权限或链接攻击时静默少加载规则，让Agent在未知约束下继续。

返回path应是规范工作区相对候选路径，不暴露realpath外部细节；content来自actual。若链接仍指向工作区内部，产品可允许并保留逻辑path，也可拒绝所有链接以简化来源。课程允许内部链接、拒绝外部目标。

Instruction内容是不可信文本，即使来自仓库内部。Loader只负责范围、安全和预算，不把指令升级成系统权限；后续Prompt组装标注来源，组织安全策略始终高于仓库文本。恶意AGENTS.md不能授权网络、shell或外部文件。

运行与验证

真实运行输出

bash

pnpm --filter @learn-traeai/coding-agent-bootcamp verify:lesson -- 24
pnpm --filter @coding-agent/repo-context test

测试还把 web 指令 symlink 到外部 secret 文件，loader 必须以“超出工作区”拒绝，而不是读取内容。

真实Solution五项应全部通过：

text

solution: 5 passed, 0 failed
覆盖: 根到局部顺序 / 排除无关规则 / 多目标祖先去重 / 总字节上限 / symlink逃逸

再调换web/api target顺序、使用中文内容与恰好预算、空target列表、绝对/上跳路径、内部symlink和权限错误。每次失败确认没有返回部分entries或泄露外部内容。

常见失败与排查

故障案例 1

Web任务加载了API目录规则。

症状：模型同时收到互相冲突的前端与后端测试命令，执行错误门禁。

根因：全仓递归扫描所有AGENTS.md，没有按target祖先链筛选。

定位：工作区同时放web/api规则，只传web target，检查entries是否含api。

修复：从每个目标目录向根构造精确祖先链，不遍历兄弟与后代。

故障案例 2

局部规则被根规则意外覆盖。

症状：web明确要求专用测试，但Prompt最终只采用根通用命令。

根因：加载顺序深到浅或全局字典排序，与“更具体后出现”语义相反。

定位：检查entries顺序和Prompt合并顺序，根必须在web之前。

修复：每条祖先链从realRoot向下，保留首次发现顺序；同层冲突显式诊断。

故障案例 3

仓库内指令链接泄露外部secret。

症状：模型上下文出现用户主目录或临时外部文件内容。

根因：只验证候选字符串在root下，readFile跟随symlink到外部。

定位：创建真实外部文件与工作区内链接，比较instruction realpath相对root。

修复：存在文件先realpath再做路径段边界；越界拒绝且不回显真实目标。

课后作业

实现指令来源行号、相同层级冲突诊断和缓存失效；写测试覆盖目标目录本身、Windows 分隔符及 symlink 目录链。

进阶要求是解析指令frontmatter中的scope、priority和schemaVersion，但任何声明都不能扩大文件系统作用域。生成规范provenance hash，把实际加载文件、内容hash、顺序与预算写进Trace，Prompt审批绑定该hash。

验收 Rubric

维度	通过标准	常见扣分
相关性	只加载目标祖先链	全仓扫描
顺序	根到嵌套且多目标稳定	深度或文件系统顺序
安全	realpath 后仍在 root	symlink 泄漏外部内容
预算	累计 UTF-8 字节	无上限或按字符

总项目增量

总项目包：@coding-agent/repo-context

总项目路径：packages/repo-context/src/instruction-loader.ts

总项目验证命令：pnpm --filter @coding-agent/repo-context test

指令决定“怎么做”；下一课选择“为当前失败具体看哪些代码”。

AGENTS.md Instruction Loader

本课交付结果

岗位问题

前置检查

前置知识快照

原理拆解

代码实验

失败实现

关键实现讲解

运行与验证

真实运行输出

常见失败与排查

故障案例 1

故障案例 2

故障案例 3

课后作业

验收 Rubric

总项目增量

延伸阅读

方案对比与工程取舍

下一课衔接

AGENTS.md Instruction Loader ​

本课交付结果 ​

岗位问题 ​

前置检查 ​

前置知识快照 ​

原理拆解 ​

代码实验 ​

失败实现 ​

关键实现讲解 ​

运行与验证 ​

真实运行输出 ​

常见失败与排查 ​

故障案例 1 ​

故障案例 2 ​

故障案例 3 ​

课后作业 ​

验收 Rubric ​

总项目增量 ​

延伸阅读 ​

方案对比与工程取舍 ​

下一课衔接 ​

AGENTS.md Instruction Loader

本课交付结果

岗位问题

前置检查

前置知识快照

原理拆解

代码实验

失败实现

关键实现讲解

运行与验证

真实运行输出

常见失败与排查

故障案例 1

故障案例 2

故障案例 3

课后作业

验收 Rubric

总项目增量

延伸阅读

方案对比与工程取舍

下一课衔接