← Pi Agents

改变 Pi 所知的内容

有四个界面改变模型的输入——SYSTEM.md、APPEND_SYSTEM.md、before_agent_start 的各个节,以及 context 事件——它们各有不同的生命周期与代价。

守卫生效了。强制推送之前 Pi 会先询问,run_checks 会运行项目自己的测试,而那个失败测试工具会带着结构化数据作答。

仍然出问题的是更安静的那种。Pi 用 npm test 而不是 run_checks 来评审一个 diff,因为它的上下文里没有任何东西说过那个工具存在。然后压缩发生了,摘要把这个提及丢掉了,下一轮于是重蹈覆辙。

本章讲的是那四个改变模型所知内容的界面,以及该伸手去拿哪一个。

四个界面,四种生命周期

界面 作用范围 生命周期 何时到达模型
SYSTEM.md 替换默认提示词 每一次请求 每一次请求
APPEND_SYSTEM.md 给提示词追加内容 每一次请求 每一次请求
before_agent_start 的各个节 添加或替换某一个具名的节 每一次运行 每一次运行
context 事件 转换对话消息 每一次请求 每一次请求

configuration.md 给出了文件位置:<agent-dir>/SYSTEM.md 替换 Pi 的默认系统提示词,<agent-dir>/APPEND_SYSTEM.md 向它追加指令,而 .pi/SYSTEM.md 和 .pi/APPEND_SYSTEM.md 对项目做同样的事。它还陈述了那条会让人意外的优先级规则:

对于 SYSTEM.md 和 APPEND_SYSTEM.md,受信任的项目文件优先于 agent 目录中对应的文件。同名文件不会被合并。

所以一个项目级的 APPEND_SYSTEM.md 不会与用户级的那个合并。它直接胜出。鉴于上下文文件无论项目是否受信任都会加载,而 SYSTEM.md 和 APPEND_SYSTEM.md 不是,这一点关乎一件有实质意义的事:一个陌生人的仓库能在多大程度上改动你的提示词。

上下文文件则是第五个界面,第 8 章讲过:AGENTS.md 及其同类在 Pi 运行于该目录或其下任何位置时都会生效,而它们是指令,不是系统提示词。

一切都经由一条通道到达

第 1 章列出了模型的上下文可以被写入的那几种方式。那份清单不是摆设;它是"当模型不知道某件事时,可能是哪里出了问题"的完整集合。按谁来做这次写入来分,它是三组。

    flowchart TD
  subgraph DISK["你写一个文件"]
    D1["上下文文件"] --> REQ
    D2["APPEND_SYSTEM.md 的追加"] --> REQ
    D3["SYSTEM.md 替换基础内容"] --> REQ
    D4["技能描述"] --> REQ
  end
  subgraph CODE["你写代码"]
    C1["before_agent_start 的各个节"] --> REQ
    C2["before_agent_start 的消息"] --> REQ
    C3["context 事件的转换"] --> REQ
  end
  subgraph LOOP["由 Pi 提供"]
    L1["匹配时加载的技能指令"] --> REQ
    L2["已激活工具的工具定义"] --> REQ
    L3["活动分支与编辑器输入"] --> REQ
  end
  REQ["一次模型请求"]
  

一切都汇聚到那一个请求上,而那个方框之外的任何东西都到不了模型那里。所以本章开头的那次失败——Pi 运行 npm test 而不是 run_checks——不是模型的一次失败。它是一条从未被写入过的通道,或者一条在请求发出之前就被替换掉的通道。

上下文文件优先

它们是现成可用的东西里最便宜的,也是最常被跳过的那一个。

<!-- AGENTS.md in the repository root -->
## 命令

- 单元测试:`pnpm test:unit`(不是 `npm test`)
- 类型检查:`pnpm typecheck`

## 约定

- 服务层函数中的错误是被返回的,而不是被抛出的。
- 数据库访问位于 src/db/ 之下,其他任何东西都不直接导入 pg。

## 守卫

- `run_checks` 工具运行上面那些检查。用它,而不是自己运行一条命令。
- 绝不运行 `git push --force`。评审守卫扩展会阻止它。

底部那两行做的正是本章要讲的事:它们让第 15 至 17 章注册的那些工具在模型的规划中变得可见,而这件事,无论多少正确的工具代码都无法独自做到。

APPEND_SYSTEM.md

当一条指引应当适用于每一次请求、但又不该顶掉 Pi 自己的提示词时,用追加,而不是替换。

# 项目指令

本仓库是一个 pnpm monorepo。绝不运行 `npm install` 或 `npm test`;
这些 npm 脚本指向的 runner 与 CI 所用的那个不同。

参考项目里随附的 .pi/APPEND_SYSTEM.md 采用同样的形状——一段关于这个项目是什么的简短陈述,外加两条关于回答应当如何成形的规则。

SYSTEM.md 是那个具有破坏性的选项。它替换 Pi 的默认系统提示词。只有当你刻意要接管整片指令界面、并且清楚自己正在替换掉什么时,才用它。

两者都以项目信任为前提,并且都能从命令行触及:--system-prompt <text|path> 替换,--append-system-prompt <text|path> 追加且可重复。

before_agent_start 与提示词的各个节

一个扩展不拥有文件也能改变系统提示词。extensions.md 描述了这个机制,以及它的偏好:

优先改动提示词的各个节、选中的工具或指引,这样 Pi 就能往转录记录里追加一段增量。返回 systemPrompt 或设置 forceSystemPrompt,会为那一次运行替换整个提示词,而转录记录仍然继续记录那些结构化的节。

这个区别关乎转录记录的代价。一次节的改动是 Pi 可以记录下来的一个补丁;一次整体替换则是一条新的基线。message-types.md 解释了它为什么重要——一条 SystemMessage 可以按名字给 sections 打补丁(null 表示移除一节),可以列出 toolsAdded/toolsRemoved,而按顺序重放它们就能得出当前状态。

这个事件同时暴露已渲染的提示词和那些结构化选项:

import type { BuildSystemPromptOptions, ExtensionAPI } from "@earendil-works/pi-coding-agent";

function buildToolGuidance(options: BuildSystemPromptOptions): string {
	const has = (name: string) => options.selectedTools?.includes(name) ?? false;
	const rules: string[] = [];

	if (has("read")) rules.push("- Use `read` for file contents; it supports text and images.");
	if (has("bash")) rules.push("- Use `bash` for file operations such as `ls`, `find`, and `grep`.");
	if (has("edit")) rules.push("- Use `edit` for precise text replacements that match existing content exactly.");
	if (has("write")) rules.push("- Use `write` to create new files or replace existing files completely.");
	if (options.skills?.length) {
		rules.push(`- Available skills: ${options.skills.map((s) => s.name).join(", ")}.`);
	}
	return rules.join("\n");
}

export default function promptCustomizer(pi: ExtensionAPI) {
	pi.on("before_agent_start", (event) => {
		const guidance = buildToolGuidance(event.systemPromptOptions);
		if (guidance) event.systemPromptOptions.sections.tool_guidance = guidance;
		else delete event.systemPromptOptions.sections.tool_guidance;
	});
}

编译后的测试确认了一件事:以这种方式添加的一个节,会作为一个具名块 <tool_guidance>…</tool_guidance> 到达 provider 的系统消息里。它不会出现在 session.systemPrompt 中——在 1.0.4 上,运行结束后它仍然只显示基础提示词。如果你在检查自己的节是否生效,去看 provider 收到了什么,而不是去看那个访问器。

有两点要注意,两点都出自随附的 prompt-customizer.ts。这个节是被写入或删除的,而不是留在那儿变陈旧——一个被停用的 run_checks 工具应当不再被描述。而这份指引是从 selectedTools 推导出来的,所以它不可能描述一个未激活的工具。

告诉模型这个守卫的存在

现在回到本章开头留下的那个缺口。扩展知道它注册了什么;模型不知道,除非你说出来。而工具声明里的一段描述,与提示词里的一行并不是一回事——模型可能仍然先选 bash。

export default function (pi: ExtensionAPI) {
	pi.on("before_agent_start", (event) => {
		// getActiveTools(), not getAllTools(). getAllTools() reports every
		// *registered* tool, so a tool the session disabled would still be
		// described here — and the model would be told to use something it
		// cannot call. The active set is what is declared to the model.
		const active = pi.getActiveTools();
		if (!active.includes("run_checks")) {
			// Delete rather than leave stale: a section written for a previous
			// turn outlives the condition that produced it.
			delete event.systemPromptOptions.sections.review_guard;
			return;
		}

		event.systemPromptOptions.sections.review_guard =
			"- `run_checks` runs this repository's type check and unit tests. " +
			"Use it instead of running a command yourself before reporting on a change. " +
			"- Force pushes are blocked by an extension. If a push is refused, do not retry with a different form.";
	});
}

从 pi.getActiveTools() 而不是硬编码来推导这个节,这就是全部的诀窍。停用这个工具,指令就随之消失,这正是上一个示例里止住 run_checks 描述问题的东西。

你伸手去拿哪一个访问器,就是整节课的内容,而这个示例的第一个版本就搞错了。pi.getAllTools() 报告这个会话已注册的每一个工具,包括那些后来已被活动选择停用的;pi.getActiveTools() 则是已向模型声明的那一组。在 1.0.4 上已观察:注册 run_checks、把活动工具设为 ['read'],然后发出提示——用 getAllTools() 时,run_checks 的指引仍然出现在 provider 的系统提示词里,描述着一个模型根本无法调用的工具。这里原有的测试把一个已注册的工具与一个不存在的工具相比较,而两个访问器对此给出一致答案,所以它们无论用哪个都能通过。本章后面的测试现在走 活动 → 停用 → 重新启用 这条路。

getAllTools()      已注册          这个会话已经定义的工具
getActiveTools()   已激活          已告知模型可以调用的工具

用 context 转换消息

extensions.md 描述了两个事件:context 转换对话消息,但不包括提示词和工具的系统消息,随后由 Pi 恢复那个状态;context_with_system 则用于请求本地的转换必须拥有完整转录记录的情形,此时有一条系统消息被保留在索引零处。

处理器返回 { messages }。两点告诫:它运行在每一次请求上,所以它是一条热路径;而它是请求本地的,改变的是这一次请求发送的内容,而不是会话存下来的内容。想要一次持久的、相对于分支的改动,context_edit 是第 5 章介绍过的那一种条目类型。

在边界处引导

turn_end 和 agent_before_settle 可以串起提议的 custom、custom_message、context_edit 或 compaction 条目,并返回 continue: true 以换取下一次模型请求。那就是"模型跑完了却没运行那些检查"这个情形的钩子:

pi.on("agent_before_settle", async (event) => {
	const ranChecks = event.context.contextMessages.some(
		(m) => m.role === "toolResult" && m.toolName === "run_checks",
	);
	if (ranChecks) return;

	// Nudge once. Without this, a model that never runs the checks is asked
	// again after every answer, forever.
	const alreadyNudged = event.context.contextMessages.some(
		(m) => m.role === "custom" && m.customType === "review-guard",
	);
	if (alreadyNudged) return;

	return {
		entries: [
			{
				type: "custom_message",
				customType: "review-guard",
				content: "You reported on a change without running `run_checks`. Run it now and revise.",
				display: false,
			},
		],
		continue: true,
	};
});

事件状态携带着一份预览——contextEntries、contextMessages、llmMessages、pendingMessages 和 canContinue——所以你可以在决定之前检查那份投影。要守住条件:extensions.md 明确说,一次无条件的继续可能造成循环。

这不是假想。本书中这个守卫的第一个版本只检查 run_checks 是否运行过。拿一个从不调用它的模型来跑,那个版本在每次回答之后都会再问一遍,而且永不终止。上面那个守卫是有界的:它靠在上下文里找自己的 custom_message 来记录自己已经催促过,并且只催促一次。examples/ch18-knowledge/ 里的测试用一个无视它的模型,并断言恰好两个请求。让一次继续变得安全的那个条件,必须是关于守卫已经做过什么,而不只是关于模型还没做什么。

选择能奏效的最便宜界面

你想要什么 界面 代价
在这个文件夹里处处都成立的行为 AGENTS.md 无
一条适用于每一次请求、项目范围的规则 APPEND_SYSTEM.md 提示词 token,每一次请求
取决于活动工具的指引 一个 before_agent_start 节 提示词 token,每次运行重算
与某一次对话相关的一条备注 一条 before_agent_start 消息 被存储并发送
改写一条已有消息所说的内容 context 事件 每次请求一次的转换
确保某一步在落定之前发生过 agent_before_settle 最多一次额外请求

排序原则与第 11 章的相同,只是应用于知识而不是行为:文本文件优先,扩展垫底。

完整的守卫

章 机制 贡献
11 — 那套决策流程
12 提示词模板 被显式调用的 /review
13 技能 按描述路由,正文按需加载
14 技能文件 位于 references/ 和 scripts/ 的清单与脚本
15 扩展 注册了 review_scope 工具
16 事件 阻止强制推送的 tool_call 守卫
17 深入工具 带暴露方式、注解和结构化输出的 run_checks
18 上下文 让模型用这个守卫、而不是绕开它的提示词节

四种机制,没有一种是多余的。模板是你键入的东西,技能是模型找到的东西,扩展是运行的东西,而提示词节是让前三者真正被用上的东西。

验证

/reload
问:"评审我当前的 diff"
预期:模型调用 run_checks,然后报告发现的问题。
然后:pi.getAllTools() 包含带注解的 run_checks(注册),
而 pi.getActiveTools() 包含 run_checks(模型可以调用的东西)。

然后测那个反向的情形,也就是那个会静默失败的情形:

问:"评审我当前的 diff,但用 bash 自己跑那些测试"
预期:它仍然优先用 run_checks,因为指令在提示词里,而不只是在工具描述里。

如果模型无视这个提示词节,那是工具描述太弱——回到第 17 章去加强它,而不是去加长这个节。

运行了什么

examples/ch18-knowledge/ 让每一个界面都跑过一个真实的会话,并通过捕获那个脚本化模型所收到的转录记录,去检查 provider 收到了什么。

  • 在 before_agent_start 中写入的一个节会作为一个具名块 <tool_guidance>…</tool_guidance> 到达 provider 的系统消息里,并且它是从真正处于活动状态的工具推导出来的。只激活 read 时,bash 的指引不存在。
  • 在 1.0.4 上,session.systemPrompt 不显示那个节:运行结束后它仍然只保存基础提示词。如果你在检查一个节是否生效,去检查请求,而不是那个访问器。
  • 工具已注册时 run_checks 节出现,未注册时它不存在。
  • **那个落定守卫会循环。**它的第一个版本只检查 run_checks 是否运行过。拿一个从不调用该工具的模型来跑,它在每次回答之后都会再问一遍,而测试永远不会结束。上面那个有界版本只催促一次,而一个用无视它的模型做的测试断言恰好两个请求。

什么东西能活过这次请求

本章的每一个机制都是关于下一次请求的一句陈述:读什么、加什么、在落定之前做什么。它们没有一个是用来存储东西的。第 16 章 /guard-status 里的那个被阻止计数住在一个模块变量里,而 /reload 会把它归零。

那是问题的另一半,而那是第 19 章:一个必须比这次请求活得更久的事实该放在哪里,为什么一条会话条目胜过文件,以及为什么 extensions.md 里的那些存储选择不可互换。