Pi Agent 源码级教程
F04

指令四层 —— 从 AGENTS.md 到 SKILL.md

2,740 字 · 含 40 行代码 · 约 18 分钟

前三章都在配「Pi 能做什么」。这一章配的是「Pi 怎么想」。

大多数人只会用一个地方:往 AGENTS.md 里堆规则。堆到两百行之后发现 ——模型开始忽略后半段,而且每次请求都白白付着这两百行的 token。 Pi 给了四层不同代价的入口,选对层比写得好更重要。

三个问题:

  1. 我在子目录里放一个 AGENTS.md,它会覆盖根目录那个吗?
  2. SYSTEM.md 和 APPEND_SYSTEM.md 差一个字,行为差多远?
  3. 一个技能有两百行说明,怎么才能只在用到时才付出这部分 token?
text
  第 1 层  SYSTEM.md          整段替换系统提示词    最贵,也最横  第 2 层  APPEND_SYSTEM.md   追加到系统提示词      与上一层不合并,二选一  第 3 层  AGENTS.md          作为「项目指令」注入   按目录链叠加,不覆盖  第 4 层  SKILL.md           只注入名字和描述      用到才读全文  ───────  F04 的四层,代价从上到下递减 ───────  另有      prompts/*.md      不是注入,是你手动敲 /name 才展开

一、探索链:AGENTS.md 从哪几个目录找

loadContextFileFromDir(resource-loader.ts:212-231)定义了同目录下的优先级, 就是一个长度 5 的候选名数组(:213),按顺序试,命中即返回:

顺序 文件名
1 AGENTS.override.md
2 AGENTS.md
3 AGENTS.MD
4 CLAUDE.md
5 CLAUDE.MD

同一个目录里只取第一个存在的,五个名字是同义词,不是累加。 AGENTS.MD 和 CLAUDE.MD 那两个全大写版本是给文件系统大小写敏感的 场景准备的(macOS 上 Agents.md 和 AGENTS.md 是两个文件)。

跨目录的部分在 loadProjectContextFiles(:260-302)。它分两段走:

先放全局,再放祖先链。 第一步读 <agent-dir> 里那个 (:270-274),第二步从 cwd 一路往上走到根, 每层找到一个就 unshift 进数组(:290)。

unshift 这个词是关键:从当前目录往上走,越往上越靠前插入, 所以最终顺序是全局 → 最外层祖先 → … → 当前目录。 近的在后,也就是近的更靠后、更容易被模型重视。 配置文档的说法是「a context file applies whenever Pi runs in its directory or anywhere below it」(configuration.md:43)——它们是叠加关系。

三件事顺带说明白:

子目录的 AGENTS.md 不会覆盖父目录的。 两份都进提示词, 按从外到内的顺序排列。

同目录 AGENTS.override.md 优先。 这不是 URL 覆盖, 是「二选一」的覆盖——configuration.md:45 原文是 replaces AGENTS.md or CLAUDE.md only in the same directory。

它不需要项目信任。 F01 已经说过,这里再说一遍原因: loadProjectContextFiles 根本不接收 isProjectTrusted(), 它是 Pi 启动流程里少数无条件读的路径(configuration.md:47)。

1.1 git worktree 的那个特例

:242-258 有一个函数叫 findShadowedContextFile,专门处理 git worktree add 造出来的嵌套工作树。逻辑是:如果当前目录是个 嵌套 worktree,且它自己也有 AGENTS.md,那么主仓库那份就跳过。

为什么?注释写得很直接:两者「occupy the same logical repository scope」, 两份都加载等于把同一段上下文应用两次。这是个很细的坑, 你在用 worktree 时会遇到「为什么规则被说了两遍」——答案在这。


二、SYSTEM.md 与 APPEND_SYSTEM.md:二选一,不合并

这两个文件的发现逻辑几乎一模一样(:1245-1271), 都是先看项目、再看全局,命中即返回:

<!-- file: pi-main/pi-main/packages/coding-agent/src/core/resource-loader.ts -->

ts
	private discoverSystemPromptFile(): string | undefined {		const projectPath = join(this.cwd, CONFIG_DIR_NAME, "SYSTEM.md");		if (this.settingsManager.isProjectTrusted() && existsSync(projectPath)) {			return projectPath;		}

注意两个 return:项目那份命中就返回了,全局那份根本不会被读。 这就是 configuration.md:39 那句「Files with the same name are not combined」 的代码实现。

所以行为矩阵是这样:

SYSTEM.md 在哪 结果
项目 .pi/ 有(且已信任) 用项目的,全局那份被忽略
项目没有,全局 <agent-dir>/ 有 用全局的
都没有 用 system-prompt.ts 里拼出来的默认提示词

注意项目那份受信任闸门约束(isProjectTrusted() 在条件里), 而 AGENTS.md 不受。这是四层里唯一有这个区别的地方。

2.1 替换 vs 追加,代价差多少

SYSTEM.md 是整段替换。换了之后,Pi 那套 preamble / tools / rules / docs / cwd 五段结构还在不在? 取决于你怎么写。buildSystemPromptSections(system-prompt.ts:128-160) 里 customPrompt 只顶掉 preamble 这一段(:152-153):

<!-- file: pi-main/pi-main/packages/coding-agent/src/core/system-prompt.ts -->

ts
	if (customPrompt) {		promptSections.preamble = customPrompt;	} else {

也就是说 SYSTEM.md 换的是开头那段身份描述,工具清单、规则、 文档路径这些结构化段落仍然由 Pi 现算。这个设计很克制: 你写自己的开场白,但不会因此丢掉「有哪些工具」这种必须准确的信息。

APPEND_SYSTEM.md 则是往末尾追加,不动任何既有段落。 它的用途基本只有一个:跨项目通用的偏好,比如「回答用中文」 「不要给我写总结章节」。这类东西写进全局 APPEND_SYSTEM.md, 每个项目都生效,又不影响任何人自己的 AGENTS.md。

一句话选型:改「Pi 是谁」用 SYSTEM.md,加「我的习惯」用 APPEND_SYSTEM.md, 写「这个项目的规矩」用 AGENTS.md。


三、AGENTS.md 里到底该写什么

这一层是「项目上下文」,注入形式是一个 XML 块, 由 renderProjectContext(system-prompt.ts:79-86)生成:

text
Project-specific instructions and guidelines:<project_instructions path="D:\proj\AGENTS.md">(文件原文)</project_instructions>

带 path 属性很重要——模型能看出某条规则来自哪个目录, 在多层叠加时这个信息不可省。

因为是原文注入,写得越啰嗦,每个 turn 就多付一次。 三条经验,都是踩出来的:

写「怎么验证」,不写「要注意质量」。 后者模型本来就知道, 前者是它猜不到的。比如「跑 npm run all,它会依次做八件事」 比「提交前请充分测试」有用一百倍。

写「不要做什么」,且给出替代。 「不要用 npm run build, 用 npm run build:fast」是可执行的;「构建时小心」不是。

路径写相对路径。 注入块里没有 cwd 信息,模型的当前目录在另一段 (sections.cwd)。绝对路径会让人在 clone 到别处之后全部失效。

想验证注入效果,还是那招——看 sections.docs:

powershell
$env:PI_OFFLINE="1"; pi --mode json -p "x" | Out-File -Encoding utf8 t.jsonl

t.jsonl 里 message_end 那条 system 消息的 sections.docs 就是所有上下文文件拼起来的那一段。文件里写了什么,这里就该看到什么 ——如果没看到,是没找到文件,不是模型没读。


四、SKILL.md:只注入名字,用到才展开

前三层的代价都是「每 turn 全量」。技能解决的是「有一大套流程, 但一个月才用一次」。

formatSkillsForPrompt(skills.ts:358-388)只做一件事: 把每个技能的名字、描述、位置三行塞进一个 <available_skills> 块。 正文一个字都不进提示词。每个技能固定输出三个字段(:377-383):

ts
// skills.ts:379-381<name>${escapeXml(skill.name)}</name><description>${escapeXml(skill.description)}</description><location>${escapeXml(skill.filePath)}</location>

location 是个绝对路径。模型判断「这个任务匹配」之后, 会用 read 去读那个文件,读完才拥有完整指令。 这就是渐进加载:先付一条描述的钱,需要时再付全文的钱。

4.1 一个技能的最小形态

目录 + SKILL.md:

text
pdf-tools/├── SKILL.md├── scripts/extract.sh└── references/formats.md
markdown
---name: pdf-toolsdescription: Extract text and tables from PDF files.  Use when reading, converting, or inspecting PDFs.---# PDF toolsRead `references/formats.md` before converting a document.Run scripts relative to this skill directory.

description 是唯一决定「会不会被想起来」的字段。skills.md:37 的要求是:既说清做什么,也说清什么时候用。 「Helps with PDFs」这种描述路由不到任何具体任务。

name 有格式约束:小写字母、数字、连字符,不能以连字符开头或结尾, 不能连续两个连字符,最长 64 字符;描述最长 1024 (skills.md:81)。不合规只是警告,不会阻止加载 (skills.md:7,skills.ts:313-332 也是记 warning 后继续)。

4.2 强制加载与隐藏

模型可能漏掉一个明明相关的技能。skills.md:45 给的解法是手动敲:

text
/skill:pdf-tools extract report.pdf

后面那串参数会作为「用户请求」追加到技能正文后面 (skills.md:47-51)。

反过来的需求也有:某个技能只想被人手动调用,不想被模型自动联想。 在 frontmatter 里加一行 disable-model-invocation: true, 它就从 <available_skills> 里消失了(skills.ts:359 那个 filter), 但 /skill:name 还能用。

4.3 放哪儿

按 skills.md:57-63,Pi 认这几个位置:

位置 范围
<agent-dir>/skills/ 全局
.pi/skills/ 项目(需信任)
~/.agents/skills/ Agent Skills 标准的全局位置
.agents/skills/ 标准位置,从 cwd 向上找到仓库根

技能目录是递归扫描的(skills.md:59)——这和扩展只下一层正好相反。 所以你可以在 skills/ 下面按分类建子目录,skills/pdf/tools/SKILL.md 照样能被找到。

最后一条安全提醒来自原文(skills.md:65):技能可以让模型跑脚本、改文件。 信任一个项目之前,先看看它的 .pi/skills/ 里有什么。


五、prompts/:不是注入,是手敲的快捷方式

这一层和上面四层性质不同——它不进系统提示词。 <agent-dir>/prompts/*.md 里的每个文件变成一个斜杠命令, 你敲 /文件名 时才展开成一段话发给模型。

占位符替换在 substituteArgs(prompt-templates.ts:76-108), 支持这些写法:

写法 含义
$1 $2 … 第 N 个参数
$@ 或 $ARGUMENTS 所有参数拼起来的整串
${1:-默认值} 第 1 个参数,缺省用默认值
${@:-默认值} 全部参数,缺省用默认值
${@:2} 从第 2 个开始到末尾
${@:2:3} 从第 2 个开始取 3 个

两个容易踩的点:

不递归替换。 注释写得很明确(:73-75):只替换模板字符串本身, 参数值和默认值里出现的 $1 不会再被展开。所以你没法用默认值套默认值。

序号从 1 开始,但 ${@:0} 不报错。 :89-91 有个 if (start < 0) start = 0, 把 0 当 1 处理——bash 习惯。写错成 ${@:0} 不会给你任何提示。

文件不合法时会发生什么?prompt-templates.ts:110-115 之后是 解析 frontmatter 的逻辑,出错记 warning 并跳过该文件, 其余提示词照常可用。和技能一样:单点失败不拖垮全局。


六、自己动手验证

实验 1:看叠加顺序。

在项目根建 AGENTS.md 写 ROOT-MARK,在 src/ 建 AGENTS.md 写 SRC-MARK, 然后 cd src 跑:

powershell
$env:PI_OFFLINE="1"; pi --mode json -p "x" | Out-File -Encoding utf8 t.jsonl

用 F03 那个 tools.mjs 改个字段名,把 sections.tools 换成 sections.docs 打出来。期望:ROOT-MARK 在前,SRC-MARK 在后。 再把根目录的改成 AGENTS.override.md,重跑——ROOT-MARK 还在, 但文件名变了,因为 override 只是同目录内的替换。

实验 2:确认 AGENTS.md 不受信任影响。

进一个没信任过的仓库(.pi/ 里有 settings.json 但内容随意), 跑 pi -p "x" -na(--no-approve 强制不信任)。 此时 .pi/settings.json 被忽略,但 AGENTS.md 仍然出现在 sections.docs 里。 这是本章最值得亲手确认的一条——它和「项目配置」是两套机制。

实验 3:确认技能只注入了三行。

在 <agent-dir>/skills/demo/SKILL.md 写一个 200 行的技能, 描述写 Use when testing skill loading。跑起来看 sections.docs, 搜索 available_skills:你只会看到 <name> <description> <location> 三行,正文那 200 行不在里面。

改一处试试

给全局 APPEND_SYSTEM.md 加一行:

text
Always answer in Chinese, even if the code and comments are in English.

然后随便跑一次。这条规则每个项目都生效,而你不用改任何人的 AGENTS.md。反过来,如果你想试试 SYSTEM.md,写一句话进去, 用 sections.preamble 观察——只有那一段变了, sections.tools 和 sections.rules 原封不动。


七、工程暗坑

坑一:以为子目录的 AGENTS.md 会覆盖父目录。 它是叠加。想「只让子目录生效」,得让父目录那份自己消失, 没有「取消继承」的开关。

坑二:项目 SYSTEM.md 与全局 SYSTEM.md 不合并。 「不合并」的意思是全局那份完全不被读,不是「项目覆盖同名键」。 把公共部分放全局、项目只写差异,这个用法在 SYSTEM.md 上不成立。

坑三:AGENTS.md 越写越长,每 turn 都付钱。 两百行上下文文件对每个 turn 都是固定成本。长流程搬到 SKILL.md 里,用不到就不花钱。

坑四:技能不写 description 就等于不存在。 skills.ts:306-308 和 :330-332 两处都在检查:没有描述, 非显式声明的技能直接不加载。而且不报错。

坑五:提示词模板里的 $ 会被吃掉。 想在提示词里写一个字面的 $1 给模型看,做不到——它一定会被替换。 要么改措辞,要么把这个符号拆到参数里传进去。


八、本章源码索引

文件 行数 本章用到的位置
packages/coding-agent/src/core/resource-loader.ts 1,320 五个候选名、祖先链 unshift、两个 discover*
packages/coding-agent/src/core/system-prompt.ts 229 renderProjectContext、五段结构与 customPrompt
packages/coding-agent/src/core/skills.ts 506 frontmatter 校验、formatSkillsForPrompt 三行注入
packages/coding-agent/src/core/prompt-templates.ts 326 substituteArgs 七种占位符
packages/coding-agent/docs/configuration.md 47 13 项 / 8 项 / 上下文文件三节
packages/coding-agent/docs/skills.md 93 技能的目录形态与 frontmatter 字段

九、下一章

四层指令都是「静态文本」。F05 开始写代码:扩展到底怎么被加载、 on() 那四十多个钩子里哪些真正常用、 以及怎么在工具真正执行之前把它拦下来。