← Pi Agents

改变 Pi 的四种方式

一套用于在上下文文件、提示词模板、技能与扩展之间做出选择的决策流程,配有四个推演案例,以及一个贯穿本部分余下各章的一贯示例。

每次代码评审之前,你都在键入同样三行字。然后你注意到同一个文件出现在三个仓库里。再然后有人要一个 /review-tests 命令,你写了四十行 TypeScript,只为了展开一个字符串。

这三个动作每一个都是现成可用的。Pi 的文档给出了一条单行规则来在它们之间做选择——quickstart.md 说要从能满足你需求的最弱机制开始——然后把"最弱"是什么意思这件事留给读者,让他在下午三点自己猜。

本章把它变成一套流程:四个问题,以及一张读者可以随时回来的图。第 12 到 18 章各自接过这套流程的一个分支深入下去,并在它们之间带着同一个一贯示例。

这些机制

quickstart.md 把整套机制列成了一张表,顺序就是它希望你逐级爬上去的顺序:

需求 从这里开始
给 Pi 一个目录上的持久化指令 AGENTS.md
从 / 菜单中复用一条提示词 提示词模板
添加面向特定任务的指令和支撑文件 技能
添加可执行的工具、命令或事件处理器 扩展
构建一个自定义终端组件 终端 UI
连接一个不受支持的模型服务 自定义 provider
安装或分发多个资源 Pi 包

前四个是文本——除了其中最后一个,它是一个运行在 Pi 进程内、带着你的操作系统权限的 TypeScript 模块。第 12 到 18 章依次讲这四个,顺序就是这套流程触及它们的顺序。

最后三行不是更高的台阶。它们解决的是不同的问题,而不是同一个问题的更难版本:一个终端组件负责渲染,一个 provider 提供模型,一个包则是可以把上述任意一种包进去的分发格式。

这套流程

按顺序问四个问题。在第一个"是"处停下。

    flowchart TD
  N["一个你反复出现的需求"] --> Q1{"需要可执行的行为吗?"}
  Q1 -->|"是"| EXT["扩展"]
  Q1 -->|"否"| Q2{"在这里适用于每一项任务吗?"}
  Q2 -->|"是"| AG["AGENTS.md 或上下文文件"]
  Q2 -->|"否"| Q3{"比一屏更长,或需要文件吗?"}
  Q3 -->|"是"| SK["技能"]
  Q3 -->|"否"| PT["提示词模板"]
  

1. 这个改动需要运行代码,或者需要在运行时观察或阻止某件事吗? 如果它需要拦截一次工具调用、对一个会话事件做出反应、添加一个带行为的斜杠命令,或者以编程方式修改系统提示词,那它就是一个扩展。extensions.md 明确说,扩展是那些需要"工具、命令、事件处理器、模型 provider、会话状态或终端 UI,而不只是指令"的工作流所用的机制。

2. 这个改动适用于这个目录下的每一次请求、每一项任务吗? 如果是,那它就是一个上下文文件。configuration.md 把一个上下文文件描述为"每当 Pi 运行在它的目录或该目录下任何地方时"都会生效。如果这个行为依赖于某个条件——一个文件类型、一种任务形态、一个触发词——那上下文文件就是错误的归宿,因为上下文文件没有条件。

3. 内容超过大约一屏文字,或者它需要自己的文件吗? 如果是,那它就是一个技能。skills.md 说,当"一个工作流需要的上下文比一个提示词模板更多,但不需要一个新的可执行集成点"时就使用技能,而技能可以打包脚本、参考资料和资源。

4. 否则,它就是一个提示词模板。 prompt-templates.md 说,当"你想复用同一条提示词,而又不想添加可执行行为或更大的一组支撑指令"时就使用提示词模板。

为什么不是更低一级

在第一个"是"处停下,只有在那些否决是被迫的而不是出于偏好时才成立。它们确实是:

被否决的 原因
面向条件性需求的 AGENTS.md 上下文文件没有条件。configuration.md 说它"每当 Pi 运行在它的目录或该目录下任何地方时"都会生效,所以一条只应针对评审触发的规则,会在这个目录的每一项任务上触发。
面向长工作流的提示词模板 一条提示词,没有文件。清单、参考表和脚本都无处安放。
面向守卫的技能 skills.md 把技能保留给"不需要一个新的可执行集成点"的工作流。技能是模型阅读并遵循的指令;只有 pi.on("tool_call") 运行在调用之前。

包不是第五级台阶

packages.md 把一个包描述为一个普通目录或 npm 包,它把扩展、技能、提示词模板和主题"作为一个整体"安装,并自带运行时依赖。它回答的是"这些东西怎么一起走",而不是"这应该是什么"。

因此决策的顺序是:先选机制,再选分发方式。

信号与它们的答案

这四个问题覆盖的是一般情况。当你已经认出了眼前的局面时,下面这些就是答案——包括那些人们朝两个方向都会搞错的。

你局面里的信号 机制 原因
“我需要一个模型能调用的新操作” 扩展 只有扩展能添加一个工具
“我需要阻止或改写一次工具调用” 扩展 只有扩展能注册一个 tool_call 处理器
“我需要一个能做点什么的 / 命令” 扩展 pi.registerCommand() 接收一个处理器
“它就是 5 行文字” AGENTS.md 再长一点,恐怕就值得单独一个文件了
“它取决于我在处理哪种文件类型” 技能 描述就是路由机制

推演案例 1:“总是用仓库自己的测试命令”

你希望 Pi 运行 pnpm test:unit,而不是自己发明一条命令。

决策。 问题 1 答否——这不需要代码。问题 2 答是——它应当对这个仓库里的每一项任务都成立。上下文文件。

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

- 单元测试:`pnpm test:unit`
- 类型检查:`pnpm typecheck`
- 不要运行 `npm test`;本仓库的默认脚本指向了错误的 runner。

你不需要一个提示词模板,因为触发条件是"总是",而不是"当我请求评审时"。

推演案例 2:“评审这个 diff”

你一直在键入同一条评审提示词。

决策。 问题 1 否,问题 2 否——评审不是每一项任务。问题 3:它超过一屏吗?还没有。所以:提示词模板。

---
description: 评审未提交的 git 变更
argument-hint: "[关注点]"
---
评审未提交的 git 变更(`git status --short`、`git diff`)。
聚焦于 ${1:-正确性、安全性和错误处理}。
发现的问题要简短,按严重程度排序,每一条都附上文件路径。

注意这里的参数替换。这正是上下文文件无法表达的东西,也是提示词模板不只是宏的原因。

推演案例 3:“我们的发布清单”

这份清单有四十项,分布在三个文件里,只在发布时适用,而且其中一半的项需要运行一个校验 tarball 的脚本。

决策。 问题 1 否——没有什么需要拦截。问题 2 否——它只在一定时候适用。问题 3 是——它超过一屏,并且需要支撑文件。技能。

release-check/
├── SKILL.md
├── references/
│   ├── checklist.md
│   └── versioning-rules.md
└── scripts/
    └── validate-tarball.sh

描述就是路由它的东西,所以它必须同时说明这个技能做什么、什么时候适用。第 13 章讲路由规则;第 14 章讲打包进来的文件。

推演案例 4:“不要强制推送,并且在动 migrations/ 里的任何东西之前先确认”

两个需求,而它们不是同一种需求。“在动 migrations/ 里的任何东西之前先确认"是一个确认式守卫(confirmation guard):它去问一个人。“不要强制推送"是一个无条件的禁令,它不应该被实现成一个人可以挥手放行的东西。

决策。 问题 1 对两半都答是——阻止或确认一次 bash 调用是运行时行为,没有纯文本的等价物。扩展。但你一旦开始写一个扩展,这两半就需要不同的代码,而下面的例子正好说明这点。

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

export default function (pi: ExtensionAPI) {
	pi.on("tool_call", async (event, ctx) => {
		if (event.toolName !== "bash" && event.toolName !== "edit") return;
		const raw = JSON.stringify(event.input);
		// \b, not (^|\s): in the serialised input "git" follows a quote, not whitespace.
		const forcePush = /\bgit\s+push\b.*(?:\s--force\b|\s-f\b|--force-with-lease\b)/.test(raw);
		// An unconditional prohibition, not a question: no confirmation prompt, so
		// there is nothing for a person to approve.
		if (forcePush) return { block: true, reason: "Force pushes are not permitted by this repository's guard" };
		// A different kind of rule. Ask, then proceed on the answer.
		if (!/\bgit\s+push\b/.test(raw) && !/migrations\//.test(raw)) return;
		if (ctx.hasUI && (await ctx.ui.confirm("Allow this call?", raw.slice(0, 120)))) return;
		return { block: true, reason: "Blocked by guard extension" };
	});
}

把这两个分支当作不同的工具来读。强制推送那个分支在确认之前就返回了,所以不会出现提示,也没有人能批准它。migrations 那个分支会问。如果两半都被写成一个确认,这个守卫就会满足"动 migrations 之前先确认”,同时悄无声息地违背"不要强制推送”,因为一个好好提问的模型,得到的回答会是"行"。

这个守卫覆盖不到什么

把覆盖面讲清楚,因为一个读起来比实际更强的守卫,比没有守卫更糟。

它只检查 bash 和 edit,别的都不检查。往 migrations/ 下的一个文件 write、一次 multi_edit,或者一个扩展自己的工具,都不会被这些模式匹配到。gh pr merge --admin 也不会,一次拼写方式模式没有预料到的 git 调用也不会——git -C /repo push --force 会被抓住,但 git push origin +main 不会,而它同样具有破坏性地重写一个 ref。

而且匹配是对着 JSON.stringify(event.input) 做的,这意味着它匹配的是一个序列化后的命令字符串,而不是在解析一条 shell 命令。git push && echo done 和 echo "git push --force" 都会被一个到处查找该标志的模式匹配到。对于一个职责就是抓住模型实际吐出来的形状的守卫来说,这是务实的选择;它是一个流程,不是遏制,第 42 章会详细讨论这个区别。如果你需要的是一道边界而不是一个流程,答案在操作系统那一侧,而不是一条更长的正则表达式。

这个守卫被实际运行过,就在 examples/ch11-guard/ 里,而它的第一个版本错在一种值得留下的方式上。它用 (^|\s)git\s+push 匹配 git push,这看着对而并不对:处理器测试的是序列化后的输入 {"command":"git push origin main"},在那里 git 跟在一个双引号后面,而不是空白字符后面。一次普通的 git push 从来就没有被问起过。这个模式只对 cd x && git push 这样的复合命令触发,而这正是有人在不是专门找这个 bug 的时候会拿来测试的形式。\bgit\s+push\b 修好了它。测试把原始版本留在修好版本旁边,作为一条回归,因为一个静悄悄漏掉常见情形的守卫比没有守卫更糟:它看起来像安全。

修好的版本在 ctx.hasUI 为 false 时也会拒绝,因为那时没有人可问。这与第 16 章对强制推送守卫给出的规则相同。

第 16 章讲事件生命周期;第 17 章讲这里依赖的工具契约。

三个贯穿四种机制的区分

显式调用与路由选择。 提示词模板是被调用的:你键入 /review。技能是模型因为它的描述匹配上了而选中的。skills.md 很坦诚地说这可能会失败——“一个模型可能加载不了一个相关的技能”——并给出 /skill:name 作为手动覆盖方式。

注册与激活。 注册一个工具使它存在。把它声明给模型使它可用。第 6 章引入了这一点;第 17 章把它讲具体。

能力与权限。 一个工具被注册,并不意味着模型在某个特定情形下被允许使用它,而 security.md 直截了当地说,已启用的工具带着 Pi 进程的操作系统权限运行。决定某件事是否被许可,才是扩展的 tool_call 处理器的用途。

这个一贯示例

从这里到本部分结束,我们只构建一样东西:一个服务仓库的评审守卫(review guard)。上面的推演案例 2 是它的第一个版本,后面每一章都是同一个守卫为一个明确说出的理由上移一级台阶。它从文本开始,以一个扩展结束。

章 机制 这个一贯示例变成什么
12 提示词模板 带一个关注点参数的 /review
13 技能 一条路由描述和一份简短的清单,使模型无需提示就会去取用它
14 带文件的技能 清单移到 references/,外加一个运行仓库自身检查的脚本
15 扩展 一个注册评审者 commands 工具的扩展
16 事件 一个阻止强制推送的 tool_call 处理器
17 深入工具 守卫获得暴露方式、嵌套调用和注解
18 上下文 一节告诉模型这个守卫存在的提示词

每一步都由上面的流程来论证,而不是由偏好。如果在任何一步你说不出是哪个问题推着你往前走,那一步就是装饰。

这套流程在哪里失效

这套流程假定你能判断一个需求是否有条件。有两种诚实的情形下你判断不了:

  • 你还不知道这个工作流是否需要运行一个脚本。那就写技能;如果模型不靠帮助就跑不了那个脚本,那就是该移到扩展的信号。
  • 这个需求实际上是两回事。那就两个都写。上下文文件和提示词模板不是对头,而一个项目同时有陈述仓库约定的 AGENTS.md 和 /review 模板,是正常情形,不是妥协。

最便宜的那一级台阶是人们会跳过的那一级,因为省下一段提示词措辞,感觉太小了,算不上一个机制。它确实是:一个文件、一个可选参数,和一条 / 命令。精确知道它能做和不能做什么,也正是你判断自己何时已经超出它的依据——这就是为什么最低的一级要排在更重的那些之前。

三条规则,以及提问的顺序

上面那架梯子回答的是用哪个 Pi 机制。它是三条规则中的第一条,另外两条在机制选对了而放置位置错了的时候接管。第 1 章画出了那些层,并给出了第三条背后的原理。本章把它们变成一套流程,第 42 章则为那些必须成立的需求补上第四个问题。

行为。 使用能解决这个需求的最弱机制。

放置。 把决策放进拥有它的最窄那一层。

时机。 一层只有在能于后果变得不可逆转之前行动时,才拥有这个决策。

第三条是第二条的限定,它很容易被跳过,所以下面说说它排除掉什么。一层可以是最窄的、知道某个决策的那一层,却仍然不拥有它,因为等它听说这件事的时候,决策已经做出了。第 1 章把这称为观察一个决策与拥有一个决策之间的区别,第 39 章在智能体内核的钩子上度量了它:效果之前的一道闸门意味着工具主体永远不会运行,而效果之后的一次改写无法把它收回来。

所以,对你将要实现的任何需求,按下面顺序问:

  1. 哪个机制是能给出这个行为的最弱机制?(上面那架梯子。文本优先。)
  2. 谁拥有这个行为存在的理由,那是哪一层?(下面那张表。不是写起来碰巧方便的那一层。)
  3. 那一层能及时行动吗? 如果它只能在决策做出之后观察它,那是建议,不是拥有。把决策往前或往下挪,或者就按它的实质称呼它。
  4. 这个需求必须成立,还是只需要发生? 一条通常会发生的是约定,那是文本文件。一条即使模型、提示词和你自己的代码都错了也必须成立的禁令,不是同一个问题,而它的答案在第 42 章:仍然能阻止那个后果的最低边界。

问题 1 到 3 是放置。问题 4 是行为规则不再是正确规则的地方,也是"最便宜的机制并不总是答案"的原因。

具体说,下面每一行都是那架梯子为层而不是为机制重述一遍:

不要为项目策略修改 provider 配置
不要为终端呈现修改智能体循环
能用一条本地指令就够了的地方,不要用运行时扩展
需要操作系统边界的地方,不要用 UI 确认

应用问题 2 的一个有用方式,是问谁拥有这个行为存在的理由:

行为 它存在的理由 属于哪里
“用这个仓库的测试命令” 本仓库的约定 项目上下文,即 AGENTS.md
“绝不直接部署到生产环境” 我们的变更管理策略 应用或它的权限边界
“这个 provider 需要这个 header” provider 的协议 provider 配置
“把这次工具调用画成一张卡片” 这个用户想要一张图 渲染器
“在一次工具结果之后,判断是否需要再来一轮” 智能体自身的控制流 智能体内核

第 1 章给出那些层,第 42 章给出权限边界,所以这张表是它们之间的连接。它防住的失败,是一个 provider 适配器悄悄得知某一个特定仓库有一套不寻常的发布流程:一个关于应用的事实,坐在一个所有其他应用共享的层里。

推演案例 4 一次展示了全部四个问题。“用 pnpm test:unit“是问题 1 用文本回答的,由仓库拥有,并且根本没有时机问题。“阻止强制推送,并在动 migrations/ 之前先确认"是一个关于工具调用的决策,扩展的 tool_call 处理器能在调用运行之前对它行动,所以问题 2 和 3 由上面那个守卫满足。问题 4 是这个守卫无法回答的那个:它匹配呈现在它面前的那次调用,而一个作用于命令字符串的模式只能拦住它的作者想到的那些拼写。如果"绝不推送到发布分支"必须无论智能体做什么都成立,它需要比一个处理器更低的东西,第 42 章会说明是什么。

这条放置规则有一个代价,它值得被点明。把一个决策放进最窄的那一层,意味着一个别的应用无法免费继承它。这正是重点,而不是反对意见:能跨项目泛化的行为,多半不属于任何一个项目,而如果你发现自己在把应用策略放进共享基础设施,那张层表正在告诉你一些事。

论断类型。 那张机制表和每种机制的契约是有文档记载的。三条规则、四个问题和放置表是本书的提议,作为一套流程给出。时机这个限定,就智能体内核的钩子而言,在第 39 章中经过了测试。