Pi Agent 源码级教程
M08

上下文装配 —— 八节提示词,一条目录链

9,551 字 · 含 553 行代码 · 约 47 分钟

M06 讲消息系统时,最后落在 SystemMessage 的一个字段上: sections: Record<string, string | null>。当时只说了它的语义—— "每一节可以单独替换,null 表示删掉这一节"——没说这些节从哪来。

M07 讲事件驱动时,turn_end 的 boundary 能往会话里追加条目, before_agent_start 能改系统提示词。也没说改完落到哪。

两个悬念指向同一个地方:模型看到的那一大坨提示词, 是谁、在什么时候、用哪些材料拼出来的?

答案是 packages/coding-agent/src/core/system-prompt.ts。 这个文件只有 229 行,核心函数 buildSystemPromptSections 占 65 行, 产物是八个键值对,不是一段字符串。

这一章拆这个函数,以及喂养它的三个加载器。


零、读这章之前,你需要先知道一件事

上下文工程:每一轮真正发给模型的不是"你打的那几个字",而是一份拼好的 payload: 系统提示词 + 项目说明 + 技能清单 + 历史消息 + 工具结果。

没有它会怎样:以为改了 AGENTS.md 就立即生效——它只在下一次拼装时进去, 而且可能被合并、折叠、甚至因为没命中触发条件而根本不出现。

本书哪里用到:§二 那张六段表([0]..[5]);M09 压的就是其中一段。


一、为什么提示词不能是写死的一段

1.1 一段常量字符串,三个改不动的点

最朴素的实现是:

ts
// 反面教材,Pi 没有这么写const SYSTEM_PROMPT = `You are a coding assistant.- read: Read a file- bash: Execute a command...`;

三种情况立刻卡住:

  • 工具集变了。默认四个工具(read bash edit write), 但用户可以用 --tools 换成十个,或者 MCP 动态注册一批。 工具列表在提示词里,就得跟着变。
  • 目录变了。同一份 pi,在 /repo/a 和 /repo/b 下启动, cwd 不同、AGENTS.md 不同、skills/ 不同。
  • 用户想加一句话。没有地方可加,除非改源码。

这三种需求的共性:提示词的内容取决于运行期环境。 写死的字符串和运行期环境是矛盾的。

1.2 一次请求只能有一段 system

那"拼成三段 system 消息"行不行?

不行。绝大多数 chat API 只接受一个 system 角色,或者只认 "消息数组最前面那一条"。Pi 在 ai/src/utils/transcript.ts 里专门写了 两个函数处理这件事(注意:取第一条和合并都在这个文件,text.ts 只管渲染):

ts
// packages/ai/src/utils/transcript.ts:47-50export function getInitialSystemMessage(	messages: TranscriptMessages,): SystemMessage | undefined {	const first = messages[0];	return first && isSystemMessage(first) ? first : undefined;}

以及 collapseSystemMessages(:108-112)——把散落的 system 消息 重放合并成一条,放在最前面。

所以真实约束是:一条 system 消息,装下所有内容。 既然只能一条,那内部就必须是结构化的——这就是 sections。

1.3 结论:提示词要"可寻址"

把提示词拆成命名小节,换来四件事:

  1. 独立替换。改 cwd 不用重发 project_context。
  2. 可增量下发。只发变了的节(§七)。
  3. 可被扩展改写。扩展能拿到 systemPromptOptions.sections 直接改某一节(docs/extensions.md:657)。
  4. 可 diff。两次提示词的差异是一个 map,不是两坨文本。

代价也直接:多了一层间接。你读代码时永远看不到 "完整提示词长什么样",得在脑子里拼。这一章大部分篇幅都在拼它。


二、八节,一个真源

2.1 顺序与来源

buildSystemPromptSections(system-prompt.ts:128-191)按代码顺序 往一个普通对象里塞键。JS 对象的字符串键按插入顺序枚举, 所以写入顺序就是最终顺序:

# 节名 内容 何时出现
1 preamble 角色定位一句话 总是
2 tools 每行 - name: 一句话描述 无 customPrompt 时
3 rules 每行 - 一条规则 无 customPrompt 时
4 docs pi 自身文档路径 无 customPrompt 时
5 addendum APPEND_SYSTEM.md 的内容 非空时
6 project_context AGENTS.md 链 至少一个文件时
7 skills <available_skills> 清单 有技能且有读取工具时
8 cwd 工作目录(正斜杠) 总是
9+ 自定义 扩展传入的 sections 逐个非空时

九行,但第 9 行是"零到多个"。八节是骨架,自定义节是挂在末尾的。

preamble 的默认值是一句话(:155-156):

ts
promptSections.preamble =	"You are a coding assistant running inside pi, a coding agent harness. " +	"Help users inspect files, run commands, and modify code.";

而 tools 的收尾有点意思(:157-160):

ts
const visibleTools = declaredTools.filter((name) => !!toolSnippets[name]);const tools =	visibleTools.length > 0		? visibleTools.map((name) => `- ${name}: ${toolSnippets[name]}`).join("\n")		: "(none)";promptSections.tools = `${tools}\n\nAdditional tools may be available.`;

"Additional tools may be available" 是恒定尾巴。 因为声明给模型的工具集,和实际能调用的工具集,不是同一个集合—— codemode 和 deferred 暴露的工具能被别的工具通过 ctx.executeTool() 调到,但不声明(见 M05)。这句话是提前打补丁, 避免模型因为"列表里没有"就断言"我做不到"。

2.2 只有 preamble 不带标签

拼完键值对,还有一步包装(:187-190):

ts
const sections: SystemPromptSections = { preamble: promptSections.preamble };for (const [name, content] of Object.entries(promptSections)) {	if (name !== "preamble") sections[name] = `<${name}>\n${content}\n</${name}>`;}return sections;

preamble 是唯一裸露的,其余全部包成 <名字> 标签。 渲染出来是这样:

text
You are a coding assistant running inside pi, ...<tools>- read: Read a file from the workspace- bash: Execute a shell command...Additional tools may be available.</tools><rules>- Use bash for file operations like ls, rg, find- Be concise in your responses</rules>...<cwd>/repo/packages/coding-agent</cwd>

为什么只有第一节不包?因为它是提示词的"开头"。 XML 标签的价值是给模型一个可以回头对号的锚点—— 后面 renderSystemMessageUpdate 会说 "Updated system prompt section tools",模型得知道 tools 指的是哪一块。第一节没有歧义,不需要名字。

2.3 节的命名是被校验的

自定义节名要先过一道闸(:144-148):

ts
for (const name of Object.keys(customSections)) {	if (!SYSTEM_PROMPT_SECTION_NAME.test(name) || name === "preamble") {		throw new Error(`Invalid system prompt section name: ${name}`);	}}

SYSTEM_PROMPT_SECTION_NAME = /^[a-z][a-z0-9_-]*$/(:58)。

三条限制各有理由:

  • 小写开头。XML 标签名习惯,也避免和 TypeScript 类型混淆。
  • 不允许空格和中文。标签名会进入提示词文本,也会成为 sections 的 JSON 键。带空格的名字在 \<${name}>`` 里 会生成非法标签。
  • preamble 保留。这是硬编码的"第一节",如果允许扩展写, 就会出现两个 preamble——后写的覆盖先写的,且没人知道。

注意这是 throw,不是 console.warn。名字写错会让整个 构建流程崩掉,而不是静默丢掉一节。这个选择是对的: 一节静默消失,比一个异常难排查一百倍。

2.4 空节不写,而不是写空

三个地方用了同一个模式:

ts
if (appendSystemPrompt) promptSections.addendum = appendSystemPrompt;   // :171if (contextFiles.length > 0) promptSections.project_context = ...;      // :172if (skillsPrompt) promptSections.skills = skillsPrompt;                 // :180

不存在 = 不出现,而不是"出现但为空"。

差别很大。如果 addendum 恒存在只是空串,那提示词里会多一行 <addendum></addendum>——几十 token 的纯噪音,每一轮都付。 而且 diffSystemPromptSections 会因为 "" !== undefined 一直判定 "变了",产生无效 patch。

skills 那一段还多覆盖了一层:formatSkillsForPrompt 在 visibleSkills.length === 0 时返回 ""(skills.ts:361-363), 所以 :179 的 .trim() 和 :180 的 if 是两个独立的闸门—— 一个过滤"没有可见技能",一个过滤"格式化的结果是空白"。


三、四种材料怎么进来

BuildSystemPromptOptions 有十三个字段(:9-37)。分四组。

3.1 工具集:selected 与 hidden

ts
// packages/coding-agent/src/core/system-prompt.ts:150const declaredTools = selectedTools.filter((name) => !hiddenTools.includes(name));

两个数组,一个减法。selectedTools 是"激活的工具", hiddenTools 是"激活但声明要藏起来"的工具。

为什么会有"激活但藏起来"?看 hiddenTools 的注释(:16-19):

Selected tools whose declarations requests leave out (prepareLoadout hidden declarations). They are reachable only through another tool.

场景:某个工具需要被 tool_search 或 codemode 脚本调用, 但不该出现在模型的工具列表里(列表太长会稀释注意力, 或者这个工具只服务于另一个工具)。它仍然注册、仍然可执行, 只是请求里不声明。

hiddenTools 从哪来?_applyToolLoadout (agent-session.ts:1614-1661)里跑每个工具的 prepareLoadout 钩子, 收集 changes.hiddenDeclarations:

ts
// packages/coding-agent/src/core/agent-session.ts:1637-1652for (const { definition, sourceInfo } of hooks) {	try {		const changes = definition.prepareLoadout?.(loadout);		for (const [name, description] of			Object.entries(changes?.descriptions ?? {})) {			descriptions.set(name, description);		}		for (const name of changes?.hiddenDeclarations ?? []) hidden.add(name);	} catch (error) {		this._extensionRunner.emitError({ ... });	}}

这段代码同时给出两个信息:

  1. prepareLoadout 能改描述(descriptions),不只是隐藏。
  2. 钩子抛错只上报不改流程。emitError 后继续下一个钩子。 对比 buildSystemPromptSections 里非法节名直接 throw—— 同样是"用户写错了",一个容错一个不容错。区别在于: 节名写错是结构性错误(会破坏协议), 加载钩子报错是业务性错误(最多描述不理想)。

declaredTools 一路传下去,影响三处:tools 节、 rules 节(§3.3)、skills 节的 fileReadTool(§5.3)。 改一个数组,三节同步变——这就是"一个真源"。

3.2 一句话描述与规则子弹

两个 map:

字段 形状 落到哪
toolSnippets Record<string, string> tools 节,每行一个
toolGuidelines Record<string, string[]> rules 节,每个一条

它们由工具定义自己声明,在 _rebuildSystemPrompt (agent-session.ts:1741-1767)里被收集:

ts
const toolSnippets: Record<string, string> = {};for (const name of this._toolRegistry.keys()) {	const snippet = this._toolPromptSnippets.get(name);	// Tools without a snippet are not listed.	if (snippet) toolSnippets[name] = snippet;}

注意 for 遍历的是 this._toolRegistry.keys(),整个注册表, 不是"激活的工具"。selectedTools 才是激活的那部分, 它在后面 :1762 才传进来。两个集合的交集,就是 visibleTools (system-prompt.ts:157)。

所以一个工具要出现在提示词里,得同时满足: 注册了、激活了、没被隐藏、有一句话描述。四个条件缺一不可。 缺最后一个就静默消失(注释:"Tools without a snippet are not listed")。

_toolPromptSnippets 的来源在注册工具时处理, _normalizePromptSnippet(:1717-1724)会把它压成一行:

ts
private _normalizePromptSnippet(text: string | undefined): string | undefined {	if (!text) return undefined;	const oneLine = text		.replace(/[\r\n]+/g, " ")		.replace(/\s+/g, " ")		.trim();	return oneLine.length > 0 ? oneLine : undefined;}

换行被压成空格。因为一个 snippet 只占一行, 如果它含换行,tools 节的结构就乱了——模型会以为那是两条工具。

3.3 规则的三段式

buildRules(system-prompt.ts:88-125)比看起来复杂。它按顺序灌三段:

第一段,条件规则(:108-116):

ts
const hasBash = selectedTools.includes("bash");const hasPowerShell = selectedTools.includes("powershell");const hasGrep = selectedTools.includes("grep");const hasFind = selectedTools.includes("find");const hasLs = selectedTools.includes("ls");if ((hasBash || hasPowerShell) && !hasGrep && !hasFind && !hasLs) {	if (hasBash && hasPowerShell) {		addRule(			"Use bash or PowerShell for file operations like listing," +				" searching, and finding files",		);	} else if (hasPowerShell) {		addRule(			"Use PowerShell for file operations like listing," +				" searching, and finding files",		);	} else {		addRule("Use bash for file operations like ls, rg, find");	}}

条件很窄:有 shell,但没有专用的文件工具。 这时候必须告诉模型"用 shell 干这些活",否则它会因为 "没有 grep 工具"而放弃搜索。有 grep 工具时这条不出现—— 免得模型明明有专工具还去 grep -r。

三种措辞对应三种工具组合,Windows 上 bash 和 PowerShell 都可能有,所以并列。

第二段,工具自己的规则(:118-121):

ts
for (const name of selectedTools) {	for (const rule of toolGuidelines[name] ?? []) addRule(rule);}for (const rule of promptGuidelines) addRule(rule);

遍历顺序是 selectedTools 的顺序,不是插入顺序。 所以工具顺序稳定 → 规则顺序稳定 → 提示词字节稳定 → 缓存命中。 M04 讲过 timestamp: 0 的同一个动机。

第三段,两条固定规则(:122-123):

ts
addRule("Be concise in your responses");addRule("Show file paths clearly when working with files");

Be concise 放在最后,因为提示词末尾对输出的影响更强—— 这是 prompt engineering 的常识,Pi 用固定两条兜住风格底线。

三段共用一个 seen 去重(:94-100):

ts
const seen = new Set<string>();const addRule = (rule: string): void => {	const normalized = rule.trim();	if (!normalized || seen.has(normalized)) return;	seen.add(normalized);	rules.push(normalized);};

先来的赢。如果某个工具的 guideline 也是 "Be concise in your responses",那固定那两条就没机会加。 这个优先级顺序是有意的:具体工具的规则比通用风格更该保留。

normalized 是 trim() 后的值,所以 " Be concise " 和 "Be concise" 会判重。但 "be concise"(小写)不会—— Set 是大小写敏感的。这是个小缺口,实际不会踩到, 因为规则都是源码里手写的。

3.4 三个"整段替换",语义完全不同

这是本章最容易混的地方。三个字段名字都像"换掉提示词":

字段 从哪来 换掉什么 其他节
customPrompt .pi/SYSTEM.md、--system-prompt 只换 preamble 照常生成
appendSystemPrompt .pi/APPEND_SYSTEM.md、--append-system-prompt 不换,只加 addendum 照常生成
forceSystemPrompt before_agent_start 返回 systemPrompt 全部 一个都不生成

customPrompt 的代码路径在 :152-169:

ts
if (customPrompt) {	promptSections.preamble = customPrompt;} else {	promptSections.preamble = "You are a coding assistant running inside pi, ...";	// tools / rules / docs 三节全在这里面}

if 和 else 的边界就是三节的存在与否。 自定义提示词只替换了 preamble,tools / rules / docs 三节不会生成。这不是笔误——看 docs 的说法 (docs/configuration.md:19):"Replaces Pi's default system prompt"。 整段默认提示词(含工具列表)就是那三节 + preamble。

所以写 .pi/SYSTEM.md 是个危险动作:工具列表消失。 模型还看得见请求里的工具声明(那是 tools 字段,不是文本), 但看不见一句话描述了。想保留,就写 APPEND_SYSTEM.md—— 它只加 addendum,什么都不删。

forceSystemPrompt 走了完全不同的路(:198-204):

ts
export function buildSystemPromptState(input: BuildSystemPromptOptions): {	content: string;	sections?: SystemPromptSections;} {	if (input.forceSystemPrompt !== undefined) {		return { content: input.forceSystemPrompt };	}	return { content: "", sections: buildSystemPromptSections(input) };}

两种状态,互斥:

  • 有 forced:content 是全文,sections 是 undefined。 这个提示词对你的代码是不透明的——你拿到一坨字符串, 没有结构可 diff。
  • 无 forced:content 是空串,全部信息在 sections 里。

注意 !== undefined 而不是 if (input.forceSystemPrompt)。 空串 "" 也是合法的强制提示词("我就要一个空提示词"), 用真值判断会把它当成"没设置"。这种边界在生成式代码里很常见。

buildSystemPrompt 最后统一渲染成文本(:207-209):

ts
export function buildSystemPrompt(input: BuildSystemPromptOptions): string {	return getSystemMessageText({		role: "system",		...buildSystemPromptState(input),		timestamp: 0,	});}

timestamp: 0,且注释写着"rendered exactly as the transcript's system message replays it"。渲染路径和重放路径必须用同一个函数, 否则 session.systemPrompt(给人看)和 provider 收到的提示词 会不一样,而测试断言就靠这个相等(system-prompt-updates.test.ts:181)。

3.5 自定义节:扩展的入口

options.sections 是 Record<string, string>,最后被逐个塞进去:

ts
// packages/coding-agent/src/core/system-prompt.ts:183-185for (const [name, content] of Object.entries(customSections)) {	if (content) promptSections[name] = content;}

这里的 if (content) 又是"空则不写"。而且它在 cwd 之后—— 自定义节永远在最后,位置由用户代码决定不了。 这是有意的:核心节位置固定,扩展节追加。否则一节插到 preamble 前面,模型的第一印象就乱了。

扩展怎么改这些节?before_agent_start 能拿到 event.systemPromptOptions(docs/extensions.md:628-640), 其中 .sections 是可变对象。改完不用返回什么—— Pi 会在下一轮 diff 时发现变化并生成 patch。

这条路径的官方措辞很值得抄下来(docs/extensions.md:657):

Prefer changing sections, selectedTools, or promptGuidelines: Pi diffs the resulting prompt sections against what the model already has and appends one system message patching only the changed sections.


四、AGENTS.md 链:从 cwd 往上爬

project_context 节的内容来自 ResourceLoader。 核心函数是 loadProjectContextFiles(resource-loader.ts:260-302)。

4.1 五个候选名,命中即停

ts
// packages/coding-agent/src/core/resource-loader.ts:212-231function loadContextFileFromDir(	dir: string,): { path: string; content: string } | null {	const candidates = [		"AGENTS.override.md",		"AGENTS.md",		"AGENTS.MD",		"CLAUDE.md",		"CLAUDE.MD",	];	for (const filename of candidates) {		const filePath = join(dir, filename);		if (existsSync(filePath)) {			try {				if (!statSync(filePath).isFile()) continue;				return {					path: filePath,					content: stripBom(readFileSync(filePath, "utf-8")),				};			} catch (error) {				console.error(					chalk.yellow(`Warning: Could not read ${filePath}: ${error}`),				);			}		}	}	return null;}

五个名字,一个目录只取一个,按顺序第一个存在的赢。

优先级 文件名 用途
1 AGENTS.override.md 临时覆盖,通常 gitignore
2 AGENTS.md 主用名
3 AGENTS.MD 大小写变体(Linux 大小写敏感)
4 CLAUDE.md 兼容 Claude Code 生态
5 CLAUDE.MD 同上

override 在最前,是给"我改一下但不想动原文件"的场景。 两个大小写变体并列,因为 macOS/Windows 大小写不敏感, Linux 敏感——只写一个会在某些系统上失效。

stripBom 值得停一下。Windows 上编辑器容易在 UTF-8 文件开头 写 BOM(EF BB BF),读进来是个 \uFEFF 字符。 它进提示词就是不可见但存在的垃圾。stripBom 在读取时剥掉。

existsSync 和 statSync 之间还有一层 isFile() 检查: 同名目录会被跳过,继续看下一个候选。catch 里只 console.error 不抛出——一个读不了的 AGENTS.md 不该让 agent 起不来。

4.2 三段装配顺序

ts
// packages/coding-agent/src/core/resource-loader.ts:267-299(节选)const contextFiles: Array<{ path: string; content: string }> = [];const seenPaths = new Set<string>();const globalContext = loadContextFileFromDir(resolvedAgentDir);if (globalContext) {	contextFiles.push(globalContext);	seenPaths.add(globalContext.path);}const ancestorContextFiles = [];const shadowedContextFile = findShadowedContextFile(resolvedCwd);let currentDir = resolvedCwd;while (true) {	const contextFile = loadContextFileFromDir(currentDir);	// ...	if (contextFile && !isShadowed && !seenPaths.has(contextFile.path)) {		ancestorContextFiles.unshift(contextFile);		seenPaths.add(contextFile.path);	}	const parentDir = dirname(currentDir);	if (parentDir === currentDir) break;	currentDir = parentDir;}contextFiles.push(...ancestorContextFiles);

三件事:

  1. 全局文件先压入 contextFiles。 resolvedAgentDir 通常是 ~/.pi——用户级规范,跨项目共享。
  2. 祖先链爬到根。currentDir 从 cwd 开始,每次 dirname, 到 parentDir === currentDir 停(/ 或 C:\ 的 dirname 是自己)。
  3. 用 unshift 而不是 push。这是本节最巧的一行。

为什么 unshift?因为循环是从内往外走的: 先 cwd,再父目录,再祖父……如果 push,顺序就是 "最具体 → 最通用"。unshift 把它翻过来,变成 "最通用 → 最具体",然后整体追加在全局文件之后。

最终顺序:

text
~/.pi/AGENTS.md            ← 全局(用户级)/repo/AGENTS.md            ← 最外层(最通用)/repo/packages/AGENTS.md   ← 中间/repo/packages/agent/AGENTS.md  ← cwd(最具体)

读起来像一本分层规范手册:先总则,后细则。 这也符合模型的阅读习惯——前面的内容权重高, 把通用规则放前面、特例放后面,冲突时后文更容易被理解成"例外"。

seenPaths 解决一个具体问题:全局目录可能就在祖先链上。 比如 ~/.pi 是 cwd 的某个祖先的子目录,或者 agentDir 被配成项目内的路径。没去重的话,同一份规范会进提示词两次—— 浪费 token,还让模型以为"这条规则被强调了"。

4.3 worktree 遮蔽:一个很窄但真实的坑

findShadowedContextFile(:242-258)只有十几行,但它的存在 说明有人真的踩过。场景:

text
/repo/AGENTS.md              ← 主仓库的规范/repo/.git/worktrees/feat/   ← git worktree 的元数据/repo-feat/AGENTS.md         ← worktree 自己的副本

用 git worktree add /repo-feat 建一个同级的 worktree。 在 /repo-feat 里启动 pi,祖先链会往上爬到 /, 碰不到 /repo/AGENTS.md(它们是兄弟目录)。 所以 worktree 里要有一份自己的 AGENTS.md——通常是指向主仓库的 符号链接,或者一份拷贝。

问题来了:如果 cwd 在 /repo-feat/sub/dir,祖先链会往上走 /repo-feat/sub → /repo-feat → /。/repo-feat/AGENTS.md 被收进来一次。这没问题。

但如果是嵌套 worktree(worktree 在主仓库目录内部), 祖先链就会同时碰到 worktree 的副本和主仓库的原件—— 同一份逻辑规范被应用两次。

findShadowedContextFile 的判断(:245-257):

ts
const gitPaths = findGitPaths(cwd);if (!gitPaths) return undefined;const commonGitDir = canonicalizePath(gitPaths.commonGitDir);const worktreeRoot = canonicalizePath(gitPaths.repoDir);const mainRepoRoot = dirname(commonGitDir);// False for an ordinary repo, where the two are the same dir, and for a// sibling worktree (`git worktree add ../feat`), whose main repo is not an// ancestor.if (	!isPathWithin(mainRepoRoot, worktreeRoot) ||	pathsEqual(worktreeRoot, mainRepoRoot)) {	return undefined;}// dirname of the common git dir is the main worktree root only when that dir// is itself checked out from the same repo. ...const mainGitDir = canonicalizePath(join(mainRepoRoot, ".git"));if (!pathsEqual(mainGitDir, commonGitDir)) return undefined;const worktreeContextFile = loadContextFileFromDir(worktreeRoot);if (!worktreeContextFile) return undefined;return join(mainRepoRoot, basename(worktreeContextFile.path));

三道闸,缺一不可:

  1. 不是普通仓库(worktreeRoot !== mainRepoRoot)。
  2. 主仓库是 worktree 的祖先(isPathWithin)。兄弟 worktree 返回 undefined,走正常继承。
  3. mainRepoRoot/.git 就是 commonGitDir。 排掉 bare 布局(proj/.bare + proj/main)和 submodule (gitdir 落在 .git/modules 下)。这两种情况下 dirname(commonGitDir) 只是个"装东西的目录",不代表工作树。

三道过后,返回"主仓库里那个同名文件"的路径。 loadProjectContextFiles 用它比对(:285-288):

ts
const isShadowed =	shadowedContextFile !== undefined &&	contextFile !== null &&	pathsEqual(		join(canonicalizePath(currentDir), basename(contextFile.path)),		shadowedContextFile,	);

注意比对的是目录的 realpath + 文件名,不是文件自己的 realpath。 原因写在注释里(:283-284):

a worktree AGENTS.md that symlinks to the main repo's file resolves to the shadowed path itself

如果 worktree 的 AGENTS.md 是指向主仓库文件的符号链接, canonicalizePath(文件) 会直接等于 shadowedContextFile—— 无论如何都会被认为是"遮蔽的",于是 worktree 那份被丢掉, 主仓库那份也没进(因为是兄弟目录)。结果是一份都没有。 所以必须用"目录 realpath + 文件名"做比较,还原出这个文件 在逻辑上的身份。

这一小段代码有 8 行注释、3 个提前返回,是整章"防御性 编程"的极端样本。它处理的场景可能一年遇到一次, 但遇到时没有它就是一小时的困惑。

4.4 XML 包装:路径是元数据

找到文件后,renderProjectContext(system-prompt.ts:79-86) 把它们包成 <project_instructions>:

ts
function renderProjectContext(	contextFiles: Array<{ path: string; content: string }>,): string {	return [		"Project-specific instructions and guidelines:",		...contextFiles.map(			({ path, content }) =>				`<project_instructions path="${path}">\n${content}\n` +				`</project_instructions>`,		),	].join("\n\n");}

外层是 project_context 节(<project_context>...</project_context>), 内层每个文件一个 project_instructions,带 path 属性。

三层嵌套,path 是关键:

  • 让模型知道规范的范围。/repo/AGENTS.md 说的是整个仓库, /repo/packages/agent/AGENTS.md 说的是这个包。 没有 path,模型无法判断"这条规则对整个项目都成立, 还是只对我现在改的这个包成立"。
  • 让模型能自己去看原文。看到路径不对,可以 read 完整文件。
  • 让冲突可解释。两条规则打架时,path 决定了哪条更具体。

path 用的是绝对路径,且没做斜杠转换。对比 cwd 节 (:182):

ts
promptSections.cwd = cwd.replace(/\\/g, "/");

cwd 转正斜杠,path 不转。这个不一致是有理由的: cwd 是模型做路径解析的基准,必须和工具实现一致 (工具在 Windows 上也接受正斜杠);path 只是标注来源, 原样保留更利于用户对照。

代价是 Windows 上提示词里 path="D:\repo\AGENTS.md", 反斜杠在 XML 属性里不需要转义(只有 " < & 需要), 所以不会出错,但读起来有点脏。这是已知的取舍,不是遗漏。

4.5 一份真实的 AGENTS.md 长什么样

到这里讲完了怎么找到、怎么装配,还剩一个问题没答:里面到底写什么?

pi 自己就有一份,就在仓库根的 AGENTS.md,141 行。它的读者不是人,是 agent,所以写法跟一般的贡献指南很不一样。摘五条:

md
- Read files in full before wide-ranging changes, before editing files ...- Never modify `packages/ai/src/models.generated.ts` directly; update ...- Never remove or downgrade code to fix type errors from outdated deps ...- Always ask before removing functionality or code that appears intentional.- Do not preserve backward compatibility unless the user asks for it.

一条一条看它们防什么:

规则(缩短) 防的失败模式
大改前把文件读完 靠搜索片段改,改完才发现上下文错
不许手改 models.generated.ts 生成物被手改,下次重新生成就丢掉
不许为了过类型检查降级代码 "把它变成 any 就绿了"
删东西前先问 顺手清理看起来没用的代码
不主动保留向后兼容 没人要的兼容层越堆越多

把这五条并排看,语法很统一:否定式的边界 + 替代做法。第二条说"不许 手改",后半句立刻给出口——去改 catalog/ 再重新生成。人类的代码规范 大多在说"该做什么"(两个空格、驼峰命名),给 agent 的规范几乎全在说 "不许做什么",因为 agent 的失败模式是过度行动:它不会不写代码,它 会写太多、改太宽、删太快。

还有一条更值得记:这份文件专门开了一节 Conversational Style,管的是 回答顺序和措辞——"When the user asks a question, answer it first before making edits"、"No emojis"、"No fluff"。规范连"先答再做"这种 行为习惯都要写下来,说明一件事:agent 不会从你的性格里学到风格,只 会从文件里读。

最后提醒一句:别照抄这五条。不同仓库的翻车点不同,判断标准只有一条—— 每一条能不能对应一次真实的翻车。写不出对应的那次翻车,这条规范大概 只是装饰。


五、Skills:清单进提示词,正文后读

Skills 是"项目特定的操作指南"。每个技能是一个 SKILL.md 文件, 可能几千字——全塞进系统提示词是灾难。所以只放清单。

5.1 发现规则:四种情形

loadSkillsFromDirInternal(skills.ts:173-275)是个递归函数, 第一次调用 includeRootFiles = true,递归时传 false。

情形一:目录里就有 SKILL.md(:194-221):

ts
for (const entry of entries) {	if (entry.name !== "SKILL.md") continue;	const fullPath = join(dir, entry.name);	// ... 处理符号链接 ...	const relPath = toPosixPath(relative(root, fullPath));	if (!isFile || ig.ignores(relPath)) continue;	const result = loadSkillFromFile(fullPath, source);	if (result.skill) skills.push(result.skill);	diagnostics.push(...result.diagnostics);	return { skills, diagnostics };   // ← 注意这里直接返回}

return 在 for 里——找到一个 SKILL.md 就停,不再往下走。 这个目录被当成"一个技能的根",不做递归。

这三个判断的语义是:看到 SKILL.md,这个目录就归它了。 下面的子目录不再扫描。所以技能目录里可以放任意多文件 (脚本、模板、示例),不会被误判成技能。

情形二:无 SKILL.md,根目录直系 .md 也是技能(:262-271):

ts
if (!isFile || !includeRootFiles || !entry.name.endsWith(".md")) {	continue;}const result = loadSkillFromFile(fullPath, source);

includeRootFiles 只在顶层是 true。也就是说: .pi/skills/foo.md 是一个技能,但 .pi/skills/group/foo.md 不是(递归时传 false)。 这避免了"子目录里的 README 被当技能"。

情形三:递归找子目录的 SKILL.md(:255-259):

ts
if (isDirectory) {	const subResult = loadSkillsFromDirInternal(fullPath, source, false, ig, root);	skills.push(...subResult.skills);	diagnostics.push(...subResult.diagnostics);	continue;}

情形四:跳过点目录和 node_modules(:224-231):

ts
if (entry.name.startsWith(".")) continue;// Skip node_modules to avoid scanning dependenciesif (entry.name === "node_modules") continue;

node_modules 单独一条注释,因为它是真实痛点: skills/ 下如果有个包依赖,里面有几十个 SKILL.md, 一次扫描就是几千次 stat。

还有一层 .gitignore 支持(IGNORE_FILE_NAMES = [".gitignore", ".ignore", ".fdignore"],:16)。addIgnoreRules(:47)在每层 目录读这三个文件,prefixIgnorePattern(:24)把模式加上 相对前缀——这样嵌套的 .gitignore 也能正确作用到子树。

顺带解决一个坑:符号链接。三处都处理了 (:202-208、:238-247),statSync 可能抛错(断链), catch 后 continue。断链不该让整次加载失败。

5.2 两道校验

loadSkillFromFile(:277+)读 frontmatter,然后过两个校验函数。

validateName(:92-115):

规则 上限/模式 违反时
长度 ≤ 64 字符 报错
字符集 /^[a-z0-9-]+$/ 报错
首尾 不能是 - 报错
连续 不能有 -- 报错

validateDescription(:117-134):必填,≤ 1024 字符。

两条上限都不是随手定的。名字要在 XML 标签内容里出现 (<name>...</name>),64 字符足够,也避免模型看到超长名字 把它当成一段描述。1024 是描述的字数上限——描述会完整进提示词, 十个技能就是一万字,这就是清单本身也要有预算的原因。

校验失败不会抛异常,而是返回 diagnostics(skills.ts 的类型是 ResourceDiagnostic),技能被丢弃(result.skill 为 null)。 这和系统提示词节名的 throw 又相反:

  • 节名错 → 崩。因为节名是协议的一部分。
  • 技能名错 → 丢。因为技能是可选资源,丢一个不致命。

5.3 XML 与三态 fileReadTool

formatSkillsForPrompt(skills.ts:358-388):

ts
export function formatSkillsForPrompt(	skills: Skill[],	fileReadTool: "read" | "bash" | "indirect" = "read",): string {	const visibleSkills = skills.filter((s) => !s.disableModelInvocation);	if (visibleSkills.length === 0) return "";	const lines = [		"\n\nThe following skills provide specialized instructions" +			" for specific tasks.",		fileReadTool === "read"			? "Use the read tool to load a skill's file when the task" +				" matches its description."			: fileReadTool === "bash"				? "Use bash to load a skill's file when the task" +					" matches its description."				: "Load a skill's file when the task matches its description.",		"Resolve relative paths against the skill's directory (parent of" +			" SKILL.md). Use absolute paths in tool calls.",		"",		"<available_skills>",	];	for (const skill of visibleSkills) {		lines.push("  <skill>");		lines.push(`    <name>${escapeXml(skill.name)}</name>`);		lines.push(`    <description>${escapeXml(skill.description)}</description>`);		lines.push(`    <location>${escapeXml(skill.filePath)}</location>`);		lines.push("  </skill>");	}	lines.push("</available_skills>");	return lines.join("\n");}

三句引导语,只有中间那句随工具变。这是懒加载契约的全部文本, 三行说清四件事:清单存在、用什么读、相对路径相对于谁、 工具调用里要用绝对路径。

最后一句("Use absolute paths in tool calls")很实在。 location 给的是绝对路径,但模型容易把技能目录当 cwd 去拼相对路径。

fileReadTool 三态的决策在 system-prompt.ts:174-181:

ts
// A hidden reader is still reachable through another tool, so skills stay// but the hint names no tool.const readers = ["read", "bash"] as const;const skillFileReadTool =	readers.find((tool) => declaredTools.includes(tool)) ??	(readers.some((tool) => selectedTools.includes(tool)) ? "indirect" : undefined);if (skillFileReadTool && skills.length > 0) {	const skillsPrompt = formatSkillsForPrompt(skills, skillFileReadTool).trim();	if (skillsPrompt) promptSections.skills = skillsPrompt;}

三种结果:

情况 fileReadTool 提示词措辞
read 或 bash 已声明 "read" / "bash" 点名那个工具
两者都被 hiddenTools 藏了 "indirect" 不提工具名
两者都不在 selectedTools undefined 整节不写

第二态是关键。declaredTools 是减法后的集合,selectedTools 是减法前的。两者都查,才能区分"藏了"和"没有"。 藏了说明还能通过别的工具调到,所以技能列表有用但工具名不能说—— 说了模型会调一个不存在的工具。

第三态直接不写技能节。没有读取工具,技能清单就是纯噪音: 模型知道有技能,但没有任何办法读到。

escapeXml(:390-397)转五个字符(& < > " '), 顺序有讲究:& 必须第一个转,否则后面的 &lt; 会被二次转义成 &amp;lt;。这是所有 XML 转义函数的共同陷阱。

5.4 disableModelInvocation

ts
const visibleSkills = skills.filter((s) => !s.disableModelInvocation);

一个布尔字段,把技能从提示词里排除,但技能仍然加载着 (能被用户手动 /skill-name 触发)。

这是"给人用"和"给模型用"的分野。有些技能是危险操作 (deploy、force-push),不该让模型自己决定什么时候调用。 关闭 modelInvocation 后,模型看不到它,也就不会自己触发。

这是上下文工程里最便宜的降权手段:不改代码、 不改行为,只是让它不出现在提示词里。


六、Prompt templates:另一条入口

Prompt templates 不进系统提示词,但和它共用一套"发现 → 解析 → 替换" 的思路,而且经常和 AGENTS.md 放同一个目录(.pi/prompts/), 所以放在这一章。

6.1 解析:bash 风格的引号

parseCommandArgs(prompt-templates.ts:25-61)逐字符扫:

ts
let current = "";// Tracks whether a token has started, so quoted empty strings ("") are// kept as argumentslet hasToken = false;let inQuote: string | null = null;for (let i = 0; i < argsString.length; i++) {	const char = argsString[i];	if (inQuote) {		if (char === inQuote) inQuote = null;		else current += char;	} else if (char === '"' || char === "'") {		inQuote = char;		hasToken = true;	} else if (/\s/.test(char)) {		if (hasToken) {			args.push(current);			current = "";			hasToken = false;		}	} else {		current += char;		hasToken = true;	}}if (hasToken) args.push(current);

hasToken 这个变量存在的唯一理由:保留 "" 空串参数。

没有它,/cmd "" 会解析成零个参数——因为引号内没字符, current 是空串,遇到空白时 if (hasToken) 为假,直接跳过。 后果是 $1 变成 undefined,模板里的默认值逻辑就误判了。

inQuote 不转义反斜杠。所以 "a\"b" 会解析成 a\ 然后遇到 " 结束引号,再 b"。这是有意的简化: prompt template 的参数是自然语言,不是 shell 脚本, 支持转义反而增加误用空间。

6.2 六种占位符

substituteArgs(:76-108)用一个正则处理全部:

ts
const ARG_PATTERN = new RegExp(	[		"\\$\\{(\\d+|ARGUMENTS|@):-([^}]*)\\}",		"\\$\\{@:(\\d+)(?::(\\d+))?\\}",		"\\$(ARGUMENTS|@|\\d+)",	].join("|"),	"g",);

拆开看是三组选择,对应六种写法:

写法 含义
$1 $2 第 N 个位置参数(1-based)
$@ 全部参数,空格连接
$ARGUMENTS 同上
${N:-默认} 第 N 个,缺失或空时用默认
${@:N} 从第 N 个到末尾(bash 切片)
${@:N:L} 从第 N 个起取 L 个

${@:N} 有个边界处理(:89-91):

ts
let start = parseInt(sliceStart, 10) - 1;// Treat 0 as 1 (bash convention: args start at 1)if (start < 0) start = 0;

${@:0} 会被当成 ${@:1}。bash 里 ${@:0} 其实是含 $0 的, 这里不支持 $0,退化成"从头开始"是合理的妥协。

${@:N:L} 的 L 边界由 Array.prototype.slice 天然处理—— 超出长度就取到末尾。不需要额外判断。

${N:-默认} 的"空"判断(:82-86):

ts
if (defaultTarget) {	const value =		defaultTarget === "@" || defaultTarget === "ARGUMENTS"			? allArgs			: args[parseInt(defaultTarget, 10) - 1];	return value ? value : defaultValue;}

value ? 而不是 value !== undefined ?。所以传了空串 /cmd "" 也会走默认值——空串等于没传。这和 hasToken 的设计有张力:解析层费劲保留空串,替换层把它当"没传"。

实际使用中这是对的:用户按回车得到一个空参数, 希望的是"用默认值",不是"替换成空"。

6.3 三条边界

边界一:不递归。注释写得很直白(:73-74):

Replacement happens on the template string only. Argument and default values containing patterns like $1, $@, or $ARGUMENTS are NOT recursively substituted.

String.replace 带 g 只扫一遍。如果参数里含 $1, 它会原样留在输出里。这是安全默认:递归替换意味着 用户输入可以控制模板结构,是注入面。

边界二:只认 /name 开头(:309-313):

ts
if (!text.startsWith("/")) return text;const match = text.match(/^\/([^\s]+)(?:\s+([\s\S]*))?$/);if (!match) return text;

模板名到第一个空白为止,之后全是参数字符串([\s\S]* 支持多行)。 不以 / 开头就直接返回原文——普通提示词不会被误解析。

边界三:名字必须精确匹配(:318-321):

ts
const template = templates.find((t) => t.name === templateName);if (template) {	const args = parseCommandArgs(argsString);	return substituteArgs(template.content, args);}return text;

find 不是模糊匹配,=== 不是前缀。写错名字就原样发出去—— 模型会收到 /revie w some file 这种文本。没有"你是不是想用 revie"的提示。

这是有意的:如果做模糊匹配,一个恰好以 / 开头的普通句子 (比如路径 /etc/hosts 是什么)可能被误当成模板调用。 宁可漏,不可错。


七、增量:只发变了的那几节

到这里我们有了一个函数,能把当前环境算成八节。 但它每轮都要被调用一次,而八节里通常只有一节会变。 全量重发是浪费,也是缓存杀手。

7.1 每轮都算,但只在变了时发

prepareNextTurnWithContext(agent-session.ts:920-947):

ts
this.agent.prepareNextTurnWithContext = async (turn, signal) => {	const context = await this._compactBeforeNextAssistantResponse(turn.context);	const previousSnapshot = await previousPrepareNextTurnWithContext?.(...);	const nextContext = previousSnapshot?.context ?? context;	const runOptions =		this._runSystemPromptOptions ?? this._baseSystemPromptOptions;	const options = normalizeBuildSystemPromptOptions({		...runOptions,		selectedTools: this.getActiveToolNames(),		// ... snippets / guidelines 合并	});	const updateMessage = this._preparePromptAndToolLoadout(		options,		nextContext.messages,	);	// Keep session.systemPrompt and ctx.getSystemPrompt() in step with what	// the provider sees.	this._runSystemPromptOptions = options;	return {		...previousSnapshot,		context: { ...nextContext, tools: this.agent.state.tools.slice() },		messages: updateMessage			? [...(previousSnapshot?.messages ?? []), updateMessage]			: previousSnapshot?.messages,		model: this.agent.state.model,		thinkingLevel: this.agent.state.thinkingLevel,	};};

三个细节:

  1. options 每轮重建。selectedTools 从 getActiveToolNames() 取, 不信任 runOptions 里的旧值——中间可能被扩展改过。
  2. updateMessage 可能为 undefined。为 undefined 时 messages 保持 previousSnapshot?.messages,什么都不加。
  3. _runSystemPromptOptions 被写回。目的是让 session.systemPrompt(给人看)和 ctx.getSystemPrompt() (给扩展看)跟 provider 实际收到的一致。

7.2 diffSystemPromptSections 的两种输出

ts
// packages/coding-agent/src/core/system-prompt.ts:216-228export function diffSystemPromptSections(	previous: Record<string, string | null>,	current: SystemPromptSections,): Record<string, string | null> | undefined {	const patch: Record<string, string | null> = {};	for (const [name, text] of Object.entries(current)) {		if (previous[name] !== text) patch[name] = text;	}	for (const name of Object.keys(previous)) {		if (current[name] === undefined) patch[name] = null;	}	return Object.keys(patch).length > 0 ? patch : undefined;}

两个循环,两种语义:

  • 第一循环:新值 ≠ 旧值 → 这一节要更新(给新文本)。
  • 第二循环:旧有、新无 → 这一节要删除(给 null)。

null 的含义直接接回 M06 的 SystemMessage.sections: 重放时 value === null 就 sections.delete(name) (ai/src/utils/transcript.ts:82-85)。

"删除"必须显式表达。如果只是"不在 patch 里", 重放时那一节会原样留着——因为重放是累积的, 不是替换。这是增量协议和全量协议最大的差别: 全量协议里"缺失"就是"没有",增量协议里"缺失"是"没说"。 所以必须有 null 这个哨兵值。

第三个 return:空 patch 返回 undefined, 而不是 {}。调用方用真值判断(sections ? {...} : undefined), 空对象 {} 是真值,会生成一条什么都不改的 system 消息—— 既浪费 token,又在会话记录里留下垃圾。空即无,这个约定 在 buildSystemPromptSections 里已经用过三次(§2.4)。

7.3 上一版从哪来

ts
// packages/coding-agent/src/core/agent-session.ts:1786-1790const sections = diffSystemPromptSections(	getCurrentSystemMessage(messages)?.sections ?? {},	buildSystemPromptSections(options),);return sections	? { role: "system", content: "", sections, timestamp: Date.now() }	: undefined;

previous 不是"上一轮我们算出来的那一份",而是 从会话记录里重放出来的当前状态。这是关键设计:

  • 如果缓存"上一次计算的 sections",就得自己维护状态, 出错时会和真实对话分叉。
  • 从 messages 重放,真源永远是会话记录。 即使进程重启、会话恢复、回退分支,重放结果都是对的。

代价:每次 diff 都要扫一遍所有 system 消息。 getCurrentSystemMessage(transcript.ts:73-96)确实是 O(n) 的:

ts
const content: string[] = [];const sections = new Map<string, string>();let timestamp: number | undefined;for (const message of messages) {	if (!isSystemMessage(message)) continue;	timestamp ??= message.timestamp;	const text = contentText(message.content);	if (text.length > 0) content.push(text);	for (const [name, value] of Object.entries(message.sections ?? {})) {		if (value === null) sections.delete(name);		else sections.set(name, value);	}}

注意 content 和 sections 两套机制并存: content 是追加(content.push),sections 是patch (set / delete)。这也解释了为什么 _preparePromptAndToolLoadout 返回的消息 content: ""——结构化提示词全走 sections, content 留给 forceSystemPrompt 那种不透明场景。

timestamp ??= message.timestamp 取第一条。 后面 ? { role:"system", ... } 里的 timestamp: Date.now() 是新消息的 时间戳,两者不冲突——重放时用的是第一条的。

7.4 两条下行路线

patch 生成后,交给 provider 层。ai 包在这里分叉:

ts
// packages/ai/src/utils/transcript.ts:114-120export function resolveTranscript(	context: TranscriptContext,	supportsMidConvoSystemMessages: boolean | undefined,): TranscriptContext {	return supportsMidConvoSystemMessages		? context		: collapseSystemMessages(context);}

路线 A:模型接受中途 system 消息。 patch 原样留在消息数组中间。渲染时 (ai/src/utils/text.ts:28-40):

ts
export function renderSystemMessageUpdate(message: SystemMessage): string {	const parts: string[] = [];	const text = contentText(message.content);	if (text.length > 0) parts.push(text);	for (const [name, value] of Object.entries(message.sections ?? {})) {		parts.push(			value === null				? `Removed system prompt section "${name}".`				: `Updated system prompt section "${name}":\n\n${value}`,		);	}	return parts.join("\n\n");}

null 被渲染成一句自然语言 Removed system prompt section "x". ——模型没有 JSON patch 的概念,得翻译成人话。

注释里那句"This framing is request-time only and may change between versions"(:26)很重要:这段措辞不是协议,是渲染细节。 升级 pi 后模型看到的字样可能变,别在扩展里断言它。

路线 B:模型不支持。collapseSystemMessages (:108-112)把所有 system 消息重放合并成一条,放在最前面:

ts
const head = getCurrentSystemMessage(context.messages);const messages = context.messages.filter((message) => message.role !== "system");return { messages: head ? [head, ...messages] : messages } as TranscriptContext;

这条路是全量的:合并后的头部包含完整八节。 docs/extensions.md:657 说得准确:

Models that accept system messages mid-conversation receive the patch in place and keep their cached prefix; other models get the replayed prompt as their system prompt, which is a cache miss once per change.

哪些模型走 A?catalog 里显式标了 supportsMidConvoSystemMessages: true 的:Anthropic、Azure、DeepSeek、Fireworks、GitHub Copilot、 Kimi、Moonshot、OpenRouter、OpenCode 等 (ai/catalog/providers/*.ts 逐个声明)。没在 catalog 里声明的模型 兜底是 ?? false(openai-responses.ts:94)——没标就当不支持。

7.5 为什么这套设计省的是两笔钱

第一笔:token。八节里通常只有 cwd 或某一节在变。 全量重发是几千 token,patch 是几十 token。

第二笔:缓存。所有主流 provider 的 prompt cache 都按 前缀匹配。系统提示词在最前面,它一变,后面全部失效。 patch 走中途 system 消息时,前缀不动——缓存保住了。 这也是为什么 _rebuildSystemPrompt 会保留工具顺序 (agent-session.ts:1611-1612 的注释:"Reordering the same names does not change the prompt (#11495)")。顺序变化 = 字节变化 = 缓存失效, 哪怕语义完全一样。

代价写在注释里:路线 B 是"once per change" 的 cache miss。 所以"支持中途 system"这个能力,实际价值就是保住缓存。


八、完整装配流程

text
启动 / reload│├─ ResourceLoader.reload()                    (resource-loader.ts:678-708)│   ├─ loadProjectContextFiles()   → contextFiles[]│   ├─ loadSkills()                → skills[]│   ├─ discoverSystemPromptFile()  → customPrompt(.pi/SYSTEM.md)│   └─ discoverAppend…()           → appendSystemPrompt│├─ 工具注册 → _toolPromptSnippets / _toolPromptGuidelines│└─ _rebuildSystemPrompt(toolNames)            (agent-session.ts:1741)    └─ normalizeBuildSystemPromptOptions()    → _baseSystemPromptOptions每轮开头│└─ prepareNextTurnWithContext()               (agent-session.ts:920)    ├─ selectedTools ← getActiveToolNames()    ├─ _applyToolLoadout() → hiddenDeclarations → hiddenTools    ├─ buildSystemPromptSections(options)     (system-prompt.ts:128)    │   ├─ preamble        裸文本    │   ├─ tools           ← selectedTools ∩ snippets    │   ├─ rules           ← 条件规则 + guidelines + 固定两条    │   ├─ docs            ← getDocsPath() 等    │   ├─ addendum        ← APPEND_SYSTEM.md    │   ├─ project_context ← AGENTS.md 链(服务端已排好序)    │   ├─ skills          ← formatSkillsForPrompt()    │   ├─ cwd             ← 反斜杠转正斜杠    │   └─ 自定义节         ← options.sections    ├─ diffSystemPromptSections(重放旧值, 新值)  → patch | undefined    └─ patch 存在 → 追加 { role:"system", sections: patch }每次请求前(transformContext,按安装顺序 wrap)│├─ _installHiddenDeclarationsProjection()     (agent-session.ts:1808)├─ _installAgentForcedPromptProjection()      (agent-session.ts:1828)│     有 forceSystemPrompt → 全部 system 压成一条头,content=forced│└─ resolveTranscript(context, supportsMidConvo?)   (transcript.ts:115)       ├─ true  → 每个 patch 渲染成 "Updated system prompt section"       └─ false → collapseSystemMessages() 合并成一条完整头部

两个"每轮"和"每次请求"的区别值得说清:

  • prepareNextTurnWithContext 每轮一次。一轮 = 一个 assistant 回合(可能含多次工具调用)。它决定"这轮要发什么 system 消息"。
  • transformContext 每次请求一次。一次请求 = 一次 LLM 调用。 它做的是投影——把消息数组加工成 provider 能接受的样子, 但不改会话记录。

重试、溢出恢复、compaction 后重发,都会再走一遍 transformContext。 这就是为什么它能修正"会话记录里有、但这次请求不该带"的东西。


九、自己动手验证

环境:v1.4.0 / node v24.12.0 / Windows 24H2。每条判据都是这一版实跑的输出。

六个实验,都不需要改源码。

实验 1:打印完整提示词。

先写一个二十行的脚本,后面几个实验都复用它:

js
// dump-prompt.mjsimport { createAgentSession } from "@earendil-works/pi-coding-agent";const args = process.argv.slice(2);const { session } = await createAgentSession({	cwd: process.cwd(),	...(args.length > 0 ? { tools: args } : {}),});console.log(session.systemPrompt);session.dispose();
bash
node dump-prompt.mjs > prompt.txt

session.systemPrompt 是只读属性(agent-session.ts:1504-1507)。 按 docs/sdk.md 的说法,它返回"当前有效提示词, 含还没发给模型的变化"。

打开 prompt.txt,数一数有几对 <...> 标签,对照 §2.1 的表。

实验 2:验证"空则不发"。

在没有 AGENTS.md 的空目录里跑一次,grep project_context 应该什么都没输出。然后:

bash
printf '# hi\n' > AGENTS.mdnode dump-prompt.mjs | grep -c project_context   # 1
powershell
Set-Content AGENTS.md '# hi' -Encoding utf8(node dump-prompt.mjs | Select-String 'project_context').Count   # 1

再往父目录放一份 AGENTS.md,确认两段都出现, 且根目录那段在前(§4.2 的 unshift)。

实验 3:验证 customPrompt 吃掉三节。

两条路效果一样——文件(resource-loader.ts:1245-1258) 和参数(cli/args.ts:121):

bash
mkdir -p .pi && echo "You are a terse assistant." > .pi/SYSTEM.mdnode dump-prompt.mjs
powershell
New-Item -ItemType Directory -Force .pi | Out-NullSet-Content .pi/SYSTEM.md 'You are a terse assistant.' -Encoding utf8node dump-prompt.mjs
bash
pi --system-prompt "You are a terse assistant."

预期:只剩自定义的 preamble + cwd(有技能时还有 skills)。 <tools> <rules> <docs> 全部消失。删掉 SYSTEM.md 恢复。

对照组:把同一句话写进 .pi/APPEND_SYSTEM.md, 确认它变成 <addendum> 而三节都在。

实验 4:观察增量 patch。

在 ~/.pi/extensions/ 放一个每轮加一个自定义节的扩展:

ts
// ~/.pi/extensions/tick.tsexport default function (pi) {	let n = 0;	pi.on("before_agent_start", async (event) => {		n += 1;		event.systemPromptOptions.sections.tick = `tick ${n}`;	});}

sections 的值是裸内容——buildSystemPromptSections 会自己包 <tick>...</tick>(§2.2)。写 <tick>tick 1</tick> 会得到双层标签。

跑三轮对话,用 /export 导出 JSONL (core/slash-commands.ts:25),翻到后面的 system 条目: 应该只看到 sections: { tick: "tick 2" } 这种小 patch, 而不是整段提示词。

不想手搓扩展的话,直接读 coding-agent/test/system-prompt-updates.test.ts—— 它就是这条链的官方断言,比任何文档都准。

实验 5:确认 provider 能力。

bash
grep -rn "supportsMidConvoSystemMessages: true" \  packages/ai/catalog/providers/

对着你正在用的 provider 查一遍。如果没标, openai-responses.ts:94 那类写法会兜底成 false, 你就走 collapseSystemMessages 那条路——每变一次节,缓存全失效。

实验 6:验证 skills 的三种措辞。

bash
mkdir -p .pi/skills/democat > .pi/skills/demo/SKILL.md <<'EOF'---name: demodescription: A demo skill---Do the demo.EOFnode dump-prompt.mjs | grep -A3 available_skills
powershell
New-Item -ItemType Directory -Force .pi/skills/demo | Out-Null# PS 用 here-string 代替 heredoc:开头 @' 独占一行,结尾 '@ 必须顶格@'---name: demodescription: A demo skill---Do the demo.'@ | Set-Content .pi/skills/demo/SKILL.md -Encoding utf8node dump-prompt.mjs | Select-String -Context 0,3 'available_skills'

然后换三组工具跑:

bash
node dump-prompt.mjs read bash | grep "load a skill"node dump-prompt.mjs bash      | grep "load a skill"node dump-prompt.mjs grep      | grep -c available_skills

预期:第一次点名 read,第二次点名 bash, 第三次是 0——整节消失(没有任何读取工具)。

要看到 indirect 那种"不提工具名"的措辞,得让 read 和 bash 都被 prepareLoadout 藏掉——tool_search 场景才会出现, 手搓成本高,直接读 system-prompt.ts:174-181 更快。


十、工程暗坑

1. SYSTEM.md 会静默吃掉工具列表。 if (customPrompt) 的 else 分支包住了 tools/rules/docs 三节。 写 SYSTEM.md 的直觉是"换掉开头那句话",实际是 "换掉开头那句话 + 删掉三节"。想追加就写 APPEND_SYSTEM.md。

2. 节名写错会 throw,不是 warn。 buildSystemPromptSections 在 :146 直接抛。 如果扩展在 before_agent_start 里传了非法节名, 整个 agent run 挂掉,而且错误信息只有 Invalid system prompt section name: xxx——不看源码不知道规则是 /^[a-z][a-z0-9_-]*$/。

3. preamble 是保留名。 正则能过(^[a-z] 开头),但被额外排除。 写了会得到同一个异常,而错误信息看起来像"名字格式不对"。

4. 工具顺序变化会让缓存失效。 _applyToolLoadout 特意保留"仍在激活的旧工具顺序,新工具追加在尾部" (:1611-1616),注释提到 issue #11495。 如果你在扩展里 setActiveTools 每次都传一个新排序, 提示词会字节级变化,tools 和 rules 两节都会被 diff 成"变了"。

5. hiddenTools 查了两遍,漏一个就打脸。 declaredTools 减掉隐藏的(:150),但 skills 的判定还单独查了 selectedTools(:177)。如果你新增一处"从工具列表里减东西"的逻辑, 只改 declaredTools 不够——skillFileReadTool 会误判成 "根本没这个工具",而不是"藏了"。

6. cwd 转正斜杠,project_instructions path 不转。 Windows 上同一个提示词里两种斜杠并存。如果你的扩展按 path="..." 做正则匹配,得同时兼容 \ 和 /。

7. AGENTS.override.md 排第一,但没人告诉你它不该提交。 它不带 .gitignore 条目。团队里一个人提交了它的"临时"版本, 所有人的规范就被覆盖了,而且没有任何提示—— loadContextFileFromDir 找到第一个就返回。

8. getCurrentSystemMessage 只看 role === "system" 的消息。 如果 compaction 之后 system 消息被重排到中间, 重放仍然会捡到(for 遍历全部)。但如果你在扩展里 把 system 消息删掉,重放结果里就没有 sections 了—— previous 变成 {},下一轮会全量重发。 删 system 消息的代价是一次缓存失效。

9. 路线 B 是静默的降级。 resolveTranscript 走 collapseSystemMessages 时, 没有任何日志。你只能通过"token 用量突然涨了"或 "缓存命中率掉了"察觉。要确认,看 provider 配置里 supportsMidConvoSystemMessages 的实际值。

10. renderSystemMessageUpdate 的措辞会变。 text.ts:26 的注释明确说"This framing is request-time only and may change between versions"。 不要在扩展或测试里断言 Updated system prompt section 这个前缀。

11. substituteArgs 不递归,是安全特性不是缺陷。 如果你的模板需要"参数里再含占位符",只能自己调两次。 设计者选的是"不让用户输入控制模板结构"。

12. parseCommandArgs 不支持 \" 转义。 参数里要带双引号只能换单引号包裹。反过来同理。

13. skills 递归找到第一个 SKILL.md 就 return。 一个目录里有 SKILL.md,它的所有子目录都不再扫描。 想把多个技能放一个父目录,每个技能必须一个子目录, 且父目录不能有自己的 SKILL.md。


十一、三个可以带走的方法

方法一:把可变提示词拆成"命名段 + 增量 patch"

Pi 的 SystemMessage.sections 本质是一个 CRDT 的极简版: 每段独立,null 表示删除,重放是累积的。

这个模式的适用条件很明确:

  • 提示词里有独立变化的部分(工具列表、项目规范、目录)
  • 请求频率高(每轮都发,所以增量有收益)
  • provider 支持前缀缓存

不满足第三条时,收益只剩 token 量,仍值得做; 不满足第一条时(整段都在变),增量协议完全是负担。

注意 Pi 处理了协议层的分叉:模型不支持中途 system 消息时, 用 collapseSystemMessages 退化成全量。能力探测 + 降级路径 是这类优化必须配套的东西,否则你在某些 provider 上会拿到 更差的结果(多了一堆 "Updated ..." 文本,还丢了缓存)。

方法二:分层的上下文文件,用"具体度"排序

AGENTS.md 链的排序(全局 → 根 → ... → cwd)不是随意的: 越具体的越靠后。理由有三层:

  1. 后文覆盖前文。模型的注意力对近处内容更强, 冲突时"后面的"更容易被当成修正。
  2. 读者心智模型。"总则 → 细则"是人类读规范的方式。
  3. 可预测性。用户知道自己在 cwd 写的规则一定生效, 不用猜先后。

配套的两个机制也值得抄:seenPaths 去重(同一文件不进两次)、 override 文件名(临时覆盖不动原文件)。

如果要再加一层,我建议加"作用域标注"——Pi 用的是 <project_instructions path="...">。让每条规范带来源, 比让模型猜"这条是谁定的"好得多。

方法三:清单进提示词,正文靠工具拉

Skills 的核心是把上下文加载变成一次工具调用。

对比两种极端:

全量塞进提示词 只放清单
token 预付全部 用时才付
命中率 大部分无关 精准
模型主动性 无 需要判断
失败模式 挤掉真正重要的内容 模型不知道要读

第三种风险最容易被忽略:模型不知道自己不知道。 所以清单里的 description 必须写成"什么时候该用我", 而不是"我是什么"。Pi 的校验里 description 是必填、 ≤1024 字符,就是在保证这句"何时用"的信息量。

还有一个实现细节值得抄:fileReadTool 的三态。 如果读取工具被藏了,措辞要退化成"不提工具名"; 如果根本没有读取工具,整节不写。 提示词里最贵的东西不是 token,是指向不存在能力的指令。


本章小结

  1. 提示词不是一段字符串,是八个键值对(sections)。
  2. 四种材料:基础指令 / 项目文件 / 技能清单 / 模板。
  3. AGENTS.md 链从 cwd 往上爬,越具体越靠后。
  4. 增量下发:缺失 = 没说;全量协议里缺失 = 没有。
  5. 指向不存在能力的指令,比多花 token 更贵。

概念回顾

术语 一句话 在哪
八节 sections 的八个键,各自独立可变 §二
四种材料 四类来源,加载时机各不相同 §三
AGENTS.md 链 全局 → 根 → … → cwd,并带去重 §四
清单式 Skills 清单进提示词,正文靠工具拉 §五
增量 只发变了的那几节 §七

练习

练习 1(读):§七 说增量协议里"缺失"等于"没说"。 如果宿主中间漏发一轮增量、下一轮直接发全量,模型会看到什么? → 回 §七 与 collapseSystemMessages 的降级分支。

练习 2(改):把 §四 的 seenPaths 去重去掉,让同一个 AGENTS.md 进两次。预期:提示词里出现重复段落、token 上升;回滚:把 seenPaths 加回。

常见误区

  1. 你会以为 提示词就是一大段文本;实际是 八个独立段; 证据 §二 的 sections。
  2. 你会以为 Skills 正文也塞进提示词;实际是 只放清单; 证据 §五 的对比表。
  3. 你会以为 越上层的规范越优先;实际是 越具体越靠后、后覆盖前; 证据 §四 的三条理由。

读完自检

四条,能不能不看稿说出来?

自检 一句话答案 不会就去
提示词为什么不能是写死的一段? 三个改不动的点:工具集、目录、技能每轮都在变 §1.1
它产出的到底是什么形状? 八个键值对,不是一段字符串 §二
增量下发时,"缺失"是什么意思? 全量协议里缺失=没有;增量协议里缺失=没说 §七
给 agent 的规范和给人的有什么不一样? 前者写否定式边界加替代做法,对应失败模式;后者多写风格偏好 §4.5

下一步

到这一章结束,Part C 的"装配"部分齐了:提示词怎么拼、 文件从哪来、增量怎么下发。但一个关键机制还挂着—— 第八节的流程图里有一行被我省略了:

ts
const context = await this._compactBeforeNextAssistantResponse(turn.context);

压缩。当对话长到装不下,sections 能省的那点 token 毫无意义。 下一章讲 compaction.ts:怎么判断该压、从哪里切、 摘要怎么保持可续写、压缩之后 session 树怎么变。


本章源码索引

文件 关键位置 内容
coding-agent/src/core/system-prompt.ts 128-192 八节装配
同上 60-77 normalizeBuildSystemPromptOptions
同上 88-125 buildRules 三段式
同上 198-209 buildSystemPromptState / buildSystemPrompt
同上 216-228 diffSystemPromptSections
coding-agent/src/core/resource-loader.ts 212-231 五个候选文件名
同上 242-258 worktree 遮蔽
同上 260-302 loadProjectContextFiles
同上 1245-1272 SYSTEM.md / APPEND_SYSTEM.md 发现
coding-agent/src/core/skills.ts 92-134 两道校验
同上 173-275 递归发现(四种情形)
同上 358-397 formatSkillsForPrompt / escapeXml
coding-agent/src/core/prompt-templates.ts 25-108 parseCommandArgs / substituteArgs
同上 309-325 expandPromptTemplate
coding-agent/src/core/agent-session.ts 920-947 每轮装配与 patch 下发
同上 1614-1661 _applyToolLoadout / prepareLoadout
同上 1741-1791 _rebuildSystemPrompt / _preparePromptAndToolLoadout
同上 1808-1843 两个 transformContext 投影
ai/src/utils/transcript.ts 73-120 重放与 resolveTranscript
ai/src/utils/text.ts 15-40 getSystemMessageText / renderSystemMessageUpdate
coding-agent/docs/extensions.md 615-659 before_agent_start 与缓存说明