Pi Agent 源码级教程
F06

扩展(下)—— 自己造一个工具

2,040 字 · 含 53 行代码 · 约 19 分钟

F05 让扩展能「看」和「拦」。这一章让扩展能「做」——注册一个模型能调用的工具。

难点不在 registerTool 怎么写,而在状态存哪儿。存在扩展的内存变量里, 分叉一次就错;存在外部文件里,一 reload 就不同步。Pi 给的答案很有意思: 存在会话条目里。

三个问题:

  1. registerTool 那十几个字段,哪几个不填会导致工具根本不出现在提示词里?
  2. 用户在 /tree 里跳回五步之前,扩展的内存状态怎么跟上?
  3. TUI 里工具调用的那几行彩色输出,是 Pi 画的还是扩展画的?
text
  tool call ──> execute() ──> { content, details }                                 |       |                    给模型看的 ──┘       └── 存进会话条目(不进模型上下文)                                              |                          分叉 / 恢复 ──> session_tree 事件                                              |                                    扫历史重建内存状态

一、registerTool 的字段分成三组

ToolDefinition(types.ts:599-688)字段很多,按「缺了会怎样」分三组:

组 字段 缺了会怎样
必需 name label description parameters execute 编不过;parameters 要 TypeBox schema
影响可见性 promptSnippet promptGuidelines exposure defaultActive 工具可能不出现(见下)
影响体验 renderCall renderResult outputSchema executionMode 有默认渲染,能跑

第二组是坑最多的地方。promptSnippet 的注释(:606)写得很清楚:

Custom tools are omitted from that section when this is not provided.

也就是说,不写 promptSnippet,你的工具就不出现在系统提示词的 Available tools 列表里。它仍然能被调用(在 tools 数组里声明着), 但模型不知道它存在,基本不会主动用。

promptGuidelines 是「什么时候该用它」的提示行,进了 sections.rules。这两个一起写,才算把工具「介绍」给了模型。

exposure 默认 "direct"(:627-629),F03 讲过五档。 defaultActive 默认 true——注释(:646-651)特别点明: 这个默认只对 direct 和 model-only 成立,其它三档注册后一律不激活。


二、execute 返回两个东西,各走各的路

签名(:670-676)有五个参数,只有两个常用:

参数 用途
toolCallId 同一次调用的唯一 id,打日志时带上
params 已按 parameters schema 校验过的入参
signal 中止信号,长任务要检查它
onUpdate 流式输出部分结果(可选)
ctx ExtensionToolContext,里面有 cwd ui executeTool 等

返回值是 AgentToolResult<TDetails>,关键是两个字段的分工:

content 是给模型看的。文本或图片块,进对话历史。

details 是给扩展自己看的。它随工具结果存进会话条目, 不进模型上下文。这正是本章开头那个问题的答案: 扩展的持久状态放这儿,既不占 token,又天然跟着分支走。

这个设计的妙处在于「分叉自动正确」。你存到外部 JSON 里, 用户 /tree 跳回十步之前,文件还是最新的,历史和现状对不上。 存进 details,跳回去之后历史里就只有那十步之前的工具结果, 重建出来的状态自然对。


三、走一遍 todo.ts:状态重建

examples/extensions/todo.ts(305 行)是官方最完整的自定义工具样本。 它做的事很简单——增删改一个待办列表——但每个设计都在回答一个真问题。

3.1 状态存在 details 里

TodoDetails 结构(:24-29)每次工具调用都返回完整快照:

ts
interface TodoDetails {	action: "list" | "add" | "toggle" | "clear";	todos: Todo[];	nextId: number;	error?: string;}

注意它是「全量」不是「增量」。原因在文件头的注释里:

State is stored in tool result details (not external files), which allows proper branching - when you branch, the todo state is automatically correct for that point in history.

存全量的代价是每条工具结果都带一份完整列表。对十几条待办来说无所谓, 但它提示了一个通用原则:能重放的小状态存全量快照,重放大状态存操作日志。

3.2 重建:扫历史,不读文件

<!-- file: pi-main/pi-main/packages/coding-agent/examples/extensions/todo.ts -->

ts
	const reconstructState = (ctx: ExtensionContext) => {		todos = [];		nextId = 1;		for (const entry of ctx.sessionManager.getBranch()) {			if (entry.type !== "message") continue;			const msg = entry.message;			if (msg.role !== "toolResult" || msg.toolName !== "todo") continue;			const details = msg.details as TodoDetails | undefined;			if (details) {				todos = details.todos;				nextId = details.nextId;			}		}	};

四步:清空、遍历当前分支、只认自己的工具结果、用最后一份快照覆盖。

getBranch() 拿的是当前分支,不是整棵树。所以用户在 /tree 里跳到别的分支,重建出来的就是那个分支的历史——这正是想要的。

三个钩子把它挂上去(:132-133):

ts
	pi.on("session_start", async (_event, ctx) => reconstructState(ctx));	pi.on("session_tree", async (_event, ctx) => reconstructState(ctx));

session_start 覆盖启动、reload、new、resume、fork 五种情况; session_tree 覆盖分支跳转。两个一起挂,状态就不会漂。

注意它没在 session_start 里注册工具——F05 坑一说的就是这个。 registerTool 在工厂顶层,重建只动内存变量。

3.3 参数 schema:StringEnum 是干什么的

ts
const TodoParams = Type.Object({	action: StringEnum(["list", "add", "toggle", "clear"] as const),	text: Type.Optional(Type.String({ description: "Todo text (for add)" })),	id: Type.Optional(Type.Number({ description: "Todo ID (for toggle)" })),});

StringEnum 来自 @earendil-works/pi-ai,不是 TypeBox 原生的。 它把枚举值编译成 JSON Schema 的 enum,并且让模型只能从这个集合里选。

相比 Type.String() 加描述「请填 list/add/toggle/clear」, StringEnum 是结构约束,模型没有自由发挥的余地。 工具的入参里凡是有限的选项集,都该用它。

另外 execute 里对 params.text / params.id 的检查 (:158-163、:173-178)说明了一件事:schema 校验不管业务语义。 action: "add" 但不给 text,schema 是合法的(text 是可选的), 得自己判。而且它选择返回一个带 error 字段的正常结果, 而不是抛异常——抛异常会让整轮工具调用变成错误,模型看到的是「工具崩了」; 返回带错误的 details,模型能读到「text required」并重试。

3.4 渲染器:renderCall 与 renderResult

这两个字段让扩展接管 TUI 里的显示。默认渲染是「工具名 + 参数 JSON」, 很长;自定义渲染能让一行说清发生了什么。

ts
		renderCall(args, theme, _context) {			let text = theme.fg("toolTitle", theme.bold("todo "));			text += theme.fg("muted", args.action);			return new Text(text, 0, 0);		},

(原文还有两行拼 args.text / args.id,这里只留主体。)

renderCall 拿到的 theme 是个调色板对象,theme.fg(color, text) 上色, theme.bold() 加粗。颜色名是语义化的(toolTitle muted dim success error accent borderMuted),换主题时自动跟着变。

renderResult 多两个参数:result 和 options。 options.expanded 是 Ctrl+O 展开状态的布尔值——todo.ts:247 用它决定显示 5 条还是全部。

3.5 命令:registerCommand 加 UI 守卫

ts
	pi.registerCommand("todos", {		description: "Show all todos on the current branch",		handler: async (_args, ctx) => {			if (ctx.mode !== "tui") {				ctx.ui.notify("/todos requires interactive mode", "error");				return;			}

ctx.mode 有四档:interactive / print / json / rpc。 只有 interactive 时 ctx.mode === "tui" 为真。 任何弹全屏 UI 的命令都必须先判这个,否则在 -p 模式下会挂住或直接崩。

ctx.ui.custom(...)(:299-301)是挂自定义组件的入口: 给它一个工厂,返回一个带 render(width) 和 handleInput(data) 的对象。 todo.ts 里的 TodoListComponent(:40-103)就是个手写的列表视图, 连缓存都自己做了(cachedWidth / cachedLines)。


四、ctx 里还有什么

ExtensionToolContext(types.ts:403-415)除了 cwd ui, 最值得注意的是 executeTool。有了它,你的工具可以调别的工具:

text
你的工具 execute()   └─> ctx.executeTool("read", { path: "a.txt" })          └─> 走的是同一条工具执行链路(含 tool_call 拦截)

注释(:521-524)里那句 "Callable means callable from other tools through ctx.executeTool(), as the codemode tool does" 说的就是它。 codemode 不是特例,它只是第一个把这个能力用起来的工具。

ExtensionCommandContext 另有一套(:421-455),多出来的几个值得记: newSession() fork() navigateTree() switchSession() reload()。 命令确实能「替用户做会话操作」,这也是权限扩展要小心的原因。


五、自己动手验证

实验 1:跑一遍 todo,看 details 真的进了会话。

powershell
$ex = "./sources/pi-main/pi-main/packages/coding-agent/examples/extensions"pi -e $ex/todo.ts

让它加两条待办,然后 /todos 看一眼。接着退出,用 pi --resume 恢复这个会话,再 /todos——列表还在。

这证明状态不是靠进程内存活着的。想看原始数据, 找到会话文件(<agent-dir>/sessions/ 下),搜 "customType" 或 "todo",能看到每条工具结果带的 details。

实验 2:分叉之后状态对不对。

在交互模式里加两条待办,然后 /tree 跳到加第一条之前的位置, 再 /todos。期望只剩第一条。

这条实验比读一百行代码管用。它让你亲眼看到 getBranch() 和「全量快照」两个设计是怎么合起来解决分叉问题的。

实验 3:删掉 promptSnippet 看会怎样。

把 todo.ts 里加上 promptSnippet: "Manage a todo list" 重跑一次, 对比 --mode json 里的 sections.tools。不加的时候,todo 根本不在那份清单里——工具能用,但模型「看不见」它。

改一处试试

给 TodoDetails 加一个字段,比如 createdAt: number, 在 add 分支里写入时间戳,然后让 renderResult 显示它。

改完不需要重启:在交互模式里 /reload。但注意——reload 之后 旧会话里的 details 没有 createdAt,renderResult 要能容忍 undefined。这正是「状态存在历史里」的必然代价: 你的代码要兼容所有历史版本的数据结构。


六、工程暗坑

坑一:不写 promptSnippet,工具等于隐身。 能调,但模型不知道有它。这是自定义工具「写了没效果」的第一原因。

坑二:把状态存在扩展的内存里,不走 details。 reload 一次清零,分叉之后与实际历史不符。凡是需要跨轮次记住的东西, 都该落进 details 或 appendEntry。

坑三:在 execute 里抛异常代替返回错误结果。 抛异常会让整批工具调用变成错误状态。业务错误用 { content: [...], details: { error } } 返回,模型能读懂并重试。

坑四:命令里直接弹 UI,不判 ctx.mode。 -p / --mode json / --mode rpc 下会挂住。先判 ctx.mode !== "tui",用 ctx.ui.notify 给个提示。

坑五:改了 details 结构却不兼容旧数据。 会话文件是长期的。加字段可以,删字段或改类型会让历史会话里的 renderResult 崩掉。


七、本章源码索引

文件 行数 本章用到的位置
packages/coding-agent/src/core/extensions/types.ts 2,329 ToolDefinition 全字段、ExtensionToolContext
packages/coding-agent/examples/extensions/todo.ts 305 reconstructState、registerTool、渲染器、命令
packages/coding-agent/src/core/session-manager.ts 2,029 getBranch() 的语义
packages/coding-agent/docs/extensions.md — 官方扩展指南

八、下一章

内置工具和自造工具都会了,下一层是「别人的工具」。 F07 讲 MCP:怎么加一台服务器、工具名怎么变成 mcp__server__tool、 OAuth 怎么登,以及 codemode 那套沙箱脚本到底能干什么不能干什么。