上下文装配 —— 八节提示词,一条目录链
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 一段常量字符串,三个改不动的点
最朴素的实现是:
// 反面教材,Pi 没有这么写const SYSTEM_PROMPT = `You are a coding assistant.- read: Read a file- bash: Execute a command...`;三种情况立刻卡住:
- 工具集变了。默认四个工具(
readbasheditwrite), 但用户可以用--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 只管渲染):
// 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 结论:提示词要"可寻址"
把提示词拆成命名小节,换来四件事:
- 独立替换。改
cwd不用重发project_context。 - 可增量下发。只发变了的节(§七)。
- 可被扩展改写。扩展能拿到
systemPromptOptions.sections直接改某一节(docs/extensions.md:657)。 - 可 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):
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):
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):
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 是唯一裸露的,其余全部包成 <名字> 标签。
渲染出来是这样:
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):
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 空节不写,而不是写空
三个地方用了同一个模式:
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
// 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 (
prepareLoadouthidden declarations). They are reachable only through another tool.
场景:某个工具需要被 tool_search 或 codemode 脚本调用,
但不该出现在模型的工具列表里(列表太长会稀释注意力,
或者这个工具只服务于另一个工具)。它仍然注册、仍然可执行,
只是请求里不声明。
hiddenTools 从哪来?_applyToolLoadout
(agent-session.ts:1614-1661)里跑每个工具的 prepareLoadout 钩子,
收集 changes.hiddenDeclarations:
// 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({ ... }); }}这段代码同时给出两个信息:
prepareLoadout能改描述(descriptions),不只是隐藏。- 钩子抛错只上报不改流程。
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)里被收集:
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)会把它压成一行:
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):
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):
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):
addRule("Be concise in your responses");addRule("Show file paths clearly when working with files");Be concise 放在最后,因为提示词末尾对输出的影响更强——
这是 prompt engineering 的常识,Pi 用固定两条兜住风格底线。
三段共用一个 seen 去重(:94-100):
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:
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):
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):
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>,最后被逐个塞进去:
// 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, orpromptGuidelines: 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 五个候选名,命中即停
// 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 三段装配顺序
// 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);三件事:
- 全局文件先压入
contextFiles。resolvedAgentDir通常是~/.pi——用户级规范,跨项目共享。 - 祖先链爬到根。
currentDir从 cwd 开始,每次dirname, 到parentDir === currentDir停(/或C:\的 dirname 是自己)。 - 用
unshift而不是push。这是本节最巧的一行。
为什么 unshift?因为循环是从内往外走的:
先 cwd,再父目录,再祖父……如果 push,顺序就是
"最具体 → 最通用"。unshift 把它翻过来,变成
"最通用 → 最具体",然后整体追加在全局文件之后。
最终顺序:
~/.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)只有十几行,但它的存在
说明有人真的踩过。场景:
/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):
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));三道闸,缺一不可:
- 不是普通仓库(
worktreeRoot !== mainRepoRoot)。 - 主仓库是 worktree 的祖先(
isPathWithin)。兄弟 worktree 返回undefined,走正常继承。 mainRepoRoot/.git就是commonGitDir。 排掉 bare 布局(proj/.bare+proj/main)和 submodule (gitdir 落在.git/modules下)。这两种情况下dirname(commonGitDir)只是个"装东西的目录",不代表工作树。
三道过后,返回"主仓库里那个同名文件"的路径。
loadProjectContextFiles 用它比对(:285-288):
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>:
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):
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,所以写法跟一般的贡献指南很不一样。摘五条:
- 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):
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):
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):
if (isDirectory) { const subResult = loadSkillsFromDirInternal(fullPath, source, false, ig, root); skills.push(...subResult.skills); diagnostics.push(...subResult.diagnostics); continue;}情形四:跳过点目录和 node_modules(:224-231):
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):
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:
// 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;。这是所有 XML 转义函数的共同陷阱。
5.4 disableModelInvocation
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)逐字符扫:
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)用一个正则处理全部:
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):
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):
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$ARGUMENTSare NOT recursively substituted.
String.replace 带 g 只扫一遍。如果参数里含 $1,
它会原样留在输出里。这是安全默认:递归替换意味着
用户输入可以控制模板结构,是注入面。
边界二:只认 /name 开头(:309-313):
if (!text.startsWith("/")) return text;const match = text.match(/^\/([^\s]+)(?:\s+([\s\S]*))?$/);if (!match) return text;模板名到第一个空白为止,之后全是参数字符串([\s\S]* 支持多行)。
不以 / 开头就直接返回原文——普通提示词不会被误解析。
边界三:名字必须精确匹配(:318-321):
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):
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, };};三个细节:
options每轮重建。selectedTools从getActiveToolNames()取, 不信任runOptions里的旧值——中间可能被扩展改过。updateMessage可能为undefined。为undefined时messages保持previousSnapshot?.messages,什么都不加。_runSystemPromptOptions被写回。目的是让session.systemPrompt(给人看)和ctx.getSystemPrompt()(给扩展看)跟 provider 实际收到的一致。
7.2 diffSystemPromptSections 的两种输出
// 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 上一版从哪来
// 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) 的:
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 包在这里分叉:
// 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):
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 消息重放合并成一条,放在最前面:
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"这个能力,实际价值就是保住缓存。
八、完整装配流程
启动 / 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:打印完整提示词。
先写一个二十行的脚本,后面几个实验都复用它:
// 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();node dump-prompt.mjs > prompt.txtsession.systemPrompt 是只读属性(agent-session.ts:1504-1507)。
按 docs/sdk.md 的说法,它返回"当前有效提示词,
含还没发给模型的变化"。
打开 prompt.txt,数一数有几对 <...> 标签,对照 §2.1 的表。
实验 2:验证"空则不发"。
在没有 AGENTS.md 的空目录里跑一次,grep project_context
应该什么都没输出。然后:
printf '# hi\n' > AGENTS.mdnode dump-prompt.mjs | grep -c project_context # 1Set-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):
mkdir -p .pi && echo "You are a terse assistant." > .pi/SYSTEM.mdnode dump-prompt.mjsNew-Item -ItemType Directory -Force .pi | Out-NullSet-Content .pi/SYSTEM.md 'You are a terse assistant.' -Encoding utf8node dump-prompt.mjspi --system-prompt "You are a terse assistant."预期:只剩自定义的 preamble + cwd(有技能时还有 skills)。
<tools> <rules> <docs> 全部消失。删掉 SYSTEM.md 恢复。
对照组:把同一句话写进 .pi/APPEND_SYSTEM.md,
确认它变成 <addendum> 而三节都在。
实验 4:观察增量 patch。
在 ~/.pi/extensions/ 放一个每轮加一个自定义节的扩展:
// ~/.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 能力。
grep -rn "supportsMidConvoSystemMessages: true" \ packages/ai/catalog/providers/对着你正在用的 provider 查一遍。如果没标,
openai-responses.ts:94 那类写法会兜底成 false,
你就走 collapseSystemMessages 那条路——每变一次节,缓存全失效。
实验 6:验证 skills 的三种措辞。
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_skillsNew-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'然后换三组工具跑:
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)不是随意的:
越具体的越靠后。理由有三层:
- 后文覆盖前文。模型的注意力对近处内容更强, 冲突时"后面的"更容易被当成修正。
- 读者心智模型。"总则 → 细则"是人类读规范的方式。
- 可预测性。用户知道自己在 cwd 写的规则一定生效, 不用猜先后。
配套的两个机制也值得抄:seenPaths 去重(同一文件不进两次)、
override 文件名(临时覆盖不动原文件)。
如果要再加一层,我建议加"作用域标注"——Pi 用的是
<project_instructions path="...">。让每条规范带来源,
比让模型猜"这条是谁定的"好得多。
方法三:清单进提示词,正文靠工具拉
Skills 的核心是把上下文加载变成一次工具调用。
对比两种极端:
| 全量塞进提示词 | 只放清单 | |
|---|---|---|
| token | 预付全部 | 用时才付 |
| 命中率 | 大部分无关 | 精准 |
| 模型主动性 | 无 | 需要判断 |
| 失败模式 | 挤掉真正重要的内容 | 模型不知道要读 |
第三种风险最容易被忽略:模型不知道自己不知道。
所以清单里的 description 必须写成"什么时候该用我",
而不是"我是什么"。Pi 的校验里 description 是必填、
≤1024 字符,就是在保证这句"何时用"的信息量。
还有一个实现细节值得抄:fileReadTool 的三态。
如果读取工具被藏了,措辞要退化成"不提工具名";
如果根本没有读取工具,整节不写。
提示词里最贵的东西不是 token,是指向不存在能力的指令。
本章小结
- 提示词不是一段字符串,是八个键值对(
sections)。 - 四种材料:基础指令 / 项目文件 / 技能清单 / 模板。
AGENTS.md链从 cwd 往上爬,越具体越靠后。- 增量下发:缺失 = 没说;全量协议里缺失 = 没有。
- 指向不存在能力的指令,比多花 token 更贵。
概念回顾
| 术语 | 一句话 | 在哪 |
|---|---|---|
| 八节 | sections 的八个键,各自独立可变 |
§二 |
| 四种材料 | 四类来源,加载时机各不相同 | §三 |
AGENTS.md 链 |
全局 → 根 → … → cwd,并带去重 | §四 |
| 清单式 Skills | 清单进提示词,正文靠工具拉 | §五 |
| 增量 | 只发变了的那几节 | §七 |
练习
练习 1(读):§七 说增量协议里"缺失"等于"没说"。
如果宿主中间漏发一轮增量、下一轮直接发全量,模型会看到什么?
→ 回 §七 与 collapseSystemMessages 的降级分支。
练习 2(改):把 §四 的 seenPaths 去重去掉,让同一个 AGENTS.md
进两次。预期:提示词里出现重复段落、token 上升;回滚:把 seenPaths 加回。
常见误区
- 你会以为 提示词就是一大段文本;实际是 八个独立段;
证据 §二 的
sections。 - 你会以为 Skills 正文也塞进提示词;实际是 只放清单; 证据 §五 的对比表。
- 你会以为 越上层的规范越优先;实际是 越具体越靠后、后覆盖前; 证据 §四 的三条理由。
读完自检
四条,能不能不看稿说出来?
| 自检 | 一句话答案 | 不会就去 |
|---|---|---|
| 提示词为什么不能是写死的一段? | 三个改不动的点:工具集、目录、技能每轮都在变 | §1.1 |
| 它产出的到底是什么形状? | 八个键值对,不是一段字符串 | §二 |
| 增量下发时,"缺失"是什么意思? | 全量协议里缺失=没有;增量协议里缺失=没说 | §七 |
| 给 agent 的规范和给人的有什么不一样? | 前者写否定式边界加替代做法,对应失败模式;后者多写风格偏好 | §4.5 |
下一步
到这一章结束,Part C 的"装配"部分齐了:提示词怎么拼、 文件从哪来、增量怎么下发。但一个关键机制还挂着—— 第八节的流程图里有一行被我省略了:
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 与缓存说明 |