← Pi Agents

你的第一个扩展

扩展(extension)是一个默认导出接收 ExtensionAPI 的 TypeScript 模块;这里给出能工作的最小工具、它如何被加载,以及工厂函数的生命周期规则。

评审守卫可以请模型去运行 scripts/run-checks.sh。它无法提供一个新的操作、拦住一条危险的命令,或者显示一行状态。这些需要代码,而 quickstart.md 毫不含糊:可执行的工具、命令或事件处理器,就意味着一个扩展。

本章构建的是能做一件技能做不到的事的最小的扩展。

扩展是什么

extensions.md:扩展是被加载进 Pi 进程的 TypeScript 模块,它们的工厂函数会注册工具、命令、快捷键、provider、事件处理器、渲染器和终端 UI。

把第一句再读一遍,因为它回答了安全问题:一个扩展运行在 Pi 进程内部,带着同样的操作系统权限,并且它可以检查提示词、工具调用、文件、凭据和会话历史。只从你信任的来源加载扩展。

错误:"一个里面带脚本的技能就是一个扩展。"
正确:"技能是模型阅读的指令,加上一组它可能运行的文件。扩展是 Pi 加载并调用的 TypeScript。当你需要 registerTool、registerCommand 或 pi.on 的那一刻,你已经跨过了信任边界。"

契约

一个扩展导出一个默认工厂函数,它接收 ExtensionAPI。Pi 使用 jiti,所以本地的 TypeScript 扩展不需要单独的编译步骤。

下面是最小的命令扩展,来自文档:

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

export default function (pi: ExtensionAPI) {
	pi.registerCommand("hello", {
		description: "Show a greeting",
		handler: async (name, ctx) => {
			ctx.ui.notify(`Hello, ${name || "world"}!`, "info");
		},
	});
}

启动 Pi 并运行 /hello。在开发过程中,可以直接加载一个文件而不安装它:

pi --extension ./hello.ts

这个一条命令的循环,就是先用 TypeScript 写扩展、而不是先去构建并安装一个包的理由。

这个一贯示例:一个工具

extensions.md 描述了一个自定义工具是什么:一个名字、一段面向模型的描述、一个 TypeBox 参数 schema,以及一个 execute() 函数。它的结果需要面向模型的 content 和一个 details 字段。

下面是评审守卫的第一个工具,它使用 defineTool 和 Type,与随附的 examples/extensions/hello.ts 完全一样:

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

const reviewScopeTool = defineTool({
	name: "review_scope",
	label: "Review Scope",
	description:
		"List the files changed in this repository and the checks this project defines. " +
		"Use before reviewing a diff so findings cover the files that actually changed.",
	parameters: Type.Object({
		base: Type.Optional(
			Type.String({
				description: "Optional git ref to compare against. Defaults to the working tree.",
			}),
		),
	}),

	async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
		const base = params.base?.trim() || "";
		const diffCmd = base ? `git diff --name-only ${base}` : "git status --short";
		return {
			content: [
				{ type: "text", text: `Run \`${diffCmd}\` and report the changed files.` },
			],
			// details is for rendering or state reconstruction; keep it small.
			details: { base: base || null, diffCmd },
		};
	},
});

export default function (pi: ExtensionAPI) {
	pi.registerTool(reviewScopeTool);
}

把它保存为 .pi/extensions/review-scope.ts,然后运行 /reload。

重要的五个字段

字段 用途
name 模型用什么名字调用它
label 它在终端里如何渲染
description 模型读它来决定是否调用
parameters 参数的 TypeBox schema
execute() 实现

描述不是文档。它是模型选择这个工具而不是 bash 的唯一依据。“List the files changed in this repository and the checks this project defines. Use before reviewing a diff” 既告诉模型这个工具做什么,也告诉模型什么时候用。

content 与 details

结果携带两类信息:content 给模型,details 给渲染或状态重建。当没有结构化的东西要保留时,用 details: undefined。

上面的例子在 content 上故意做得很薄——它告诉模型该运行什么,而不是替它运行。对第一个扩展来说,这是诚实的:一个每次调用都要去执行外部命令的工具,相比 bash 什么也挣不到。第 17 章会用真正的执行、outputSchema 和嵌套调用来替换它。

带进那一章的一条纪律:从 execute() 抛出会产生一个失败的工具结果,而返回一个对象不会把它标记为错误。一个做不了这件事的工具应当在文本里说明,或者抛出,而不是返回一个读起来像成功的对象。

把它放在哪

extensions.md:把扩展放在你的用户或项目扩展目录里。Pi 会加载直接的 TypeScript 或 JavaScript 文件,以及含有 index.ts 或 index.js 入口点的子目录。

小扩展用单个文件,多文件的实现用目录。把 npm 依赖放在附近的 package.json 里。

对这个一贯示例来说:

.pi/
├── extensions/
│   └── review-scope.ts       # 一个文件,一个工具
├── skills/
│   └── review-guard/
└── prompts/
    └── review.md

.pi/extensions/ 需要项目信任,如第 8 章所确立。在你授予它之前,这个工具不存在,而第 13 章的技能会在没有它的情况下触发——在审查输出时值得记住这一点。

选择一个挂接点

extensions.md 给出了这张表,它是关于一个扩展能做什么的最快的地图:

能力 主要 API
观察或修改生命周期行为 pi.on()
添加一个模型可调用的操作 pi.registerTool()
添加一个 / 命令 pi.registerCommand()
添加快捷键或 CLI 标志 pi.registerShortcut() 或 pi.registerFlag()
发送用户消息或自定义消息 pi.sendUserMessage() 或 pi.sendMessage()
持久化非上下文的会话数据 pi.appendEntry()
改变活动工具、模型或思考级别 pi 上的会话控制方法
添加一个模型 provider pi.registerProvider()
添加一个 MCP 服务器 pi.registerMcpServer()
把每个请求路由到一个模型 pi.registerVirtualModel()
添加终端渲染 渲染器注册和 ctx.ui
与另一个扩展通信 pi.events
    flowchart TD
  LOAD["发现"] --> TRUST{"项目扩展?"}
  TRUST -->|"是,但尚未被信任"| SKIP["完全不会被加载"]
  TRUST -->|"否,或已授予信任"| FAC["工厂函数运行<br/>可以是异步的;Pi 会等待"]
  FAC --> REG["你注册的东西<br/>工具、命令、处理器、provider"]
  REG --> START["session_start<br/>在这里启动进程、套接字、计时器"]
  START --> RUN["会话运行"]
  RUN --> SHUT["session_shutdown<br/>幂等的清理"]
  REL["/reload"] -.->|"替换运行时"| FAC
  CANCEL["取消、替换会话、退出"] -.->|"全部汇聚到这里"| SHUT
  

工厂函数那个方框是任何东西都不能被启动、而一切都可以被注册的地方——这个区分就是规则 2 的全部,而来自 session_start 的那支箭头就是补救。虚线的 REL 箭头是下面的规则 4:一次重新加载会构建一个新的运行时,所以旧运行时捕获的任何东西都过期了。进入 session_shutdown 的三支虚线箭头,是规则 3 要求幂等性的原因。

工厂函数的生命周期规则

这是导致真实 bug 的部分,而 extensions.md 陈述了三条约束:

  1. 工厂函数可以是同步的或异步的。在启动继续之前,Pi 会等待一个异步的工厂函数,使它能获取配置或注册启动期间需要的 provider。
  2. 不要在工厂函数里启动进程、套接字、监视器或计时器,因为某些调用会在不启动会话的情况下加载扩展。从 session_start、或从需要这些资源的命令或工具那里启动长生命周期的资源。
  3. 用一个幂等的 session_shutdown 处理器关闭会话作用域的资源。

幂等之所以要紧,是因为 extensions.md 解释了原因:取消、重新加载、替换会话和进程退出,可能汇聚到同一条清理路径上。

一个只做注册的工厂函数——像我们的这个——不做别的事,就同时满足了这三条。

重新加载会让状态失效

extensions.md 毫不含糊:重新加载会替换扩展运行时,所以 await ctx.reload() 之后的代码不得复用来自旧运行时的状态。只有个人的和显式的命令行扩展,才能参与在项目扩展加载之前运行的 project_trust 事件。

各种模式并不一致

扩展会在交互式、RPC、JSON 和 print 模式下加载。交互式模式提供完整的终端 UI。RPC 可以通过 RPC Extension UI 协议转发受支持的对话框和通知,但不能转发自定义的终端组件;JSON 和 print 模式完全没有 UI。

用 ctx.mode === "tui" 来限定只对终端成立的行为,用 ctx.hasUI 处理交互式与 RPC 客户端都支持的交互。让工具和事件的行为独立于渲染,这样非交互模式仍然可用。

我们的 review-scope.ts 完全没有 UI,这意味着它在四种模式下都能工作。这是一个值得刻意去选择的属性。

运行了什么

本章的这些扩展是 examples/ch15-first-extension/ 里的文件。它们用 TypeScript 编译器针对锁定的 1.0.4 声明编译,然后被加载进一个来自 pi-coding-agent 的真实 AgentSession:真实的扩展运行时、真实的内置工具、一个内存中的会话。唯一的替换是模型,它是 pi-ai 的 faux provider,重放一段脚本。测试骨架里没有任何东西重新实现一条 Pi 规则。第 16 到 21 章使用同一个测试骨架,而第 20 和 21 章还替换了界面,以及在 MCP 的情形下替换了连接的远端。

这里的测试确立了什么:

  • 注册一个 direct 工具会让它变为活动,而一次脚本化的工具调用会跑过 Pi 自己的流水线,并产生一个带有代码所返回的 content 和 details 的工具结果;
  • 这个命令被注册在内置命令旁边。

它们也发现了本章第一稿里的一个缺陷。base 被声明为 Type.String(...),而它的描述说的是可选,所以一个照着描述去做、因而省略它的模型,会发出不符合 schema 的参数。它现在是 Type.Optional(Type.String(...)),并且有一个测试用不带参数的方式调用这个工具。一个参数的描述和一个参数的 schema 是两个陈述,而只有 schema 会被检查。

接下来的三步

这个扩展注册了某个东西,然后就停在那里。仍然缺三样东西,而每一样的缺失各有不同的原因:

  • 16 加入事件,因为一个只是存在的工具无法介入。tool_call 是唯一一个在工具运行之前触发的钩子,而它就是拦住强制推送的东西。
  • 17 把这个工具讲具体,因为注册它和模型看见它是两个不同的事实,而两者都不是许可。
  • 18 改变模型所知的内容,因为一个模型不知道的工具,就是模型会用 bash 绕开的工具。

从 .pi/extensions/review-scope.ts 开始,然后 /reload,然后让 Pi 使用这个工具。