扩展(下)—— 自己造一个工具
F05 让扩展能「看」和「拦」。这一章让扩展能「做」——注册一个模型能调用的工具。
难点不在 registerTool 怎么写,而在状态存哪儿。存在扩展的内存变量里,
分叉一次就错;存在外部文件里,一 reload 就不同步。Pi 给的答案很有意思:
存在会话条目里。
三个问题:
registerTool那十几个字段,哪几个不填会导致工具根本不出现在提示词里?- 用户在
/tree里跳回五步之前,扩展的内存状态怎么跟上? - TUI 里工具调用的那几行彩色输出,是 Pi 画的还是扩展画的?
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)每次工具调用都返回完整快照:
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 -->
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):
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 是干什么的
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」, 很长;自定义渲染能让一行说清发生了什么。
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 守卫
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。有了它,你的工具可以调别的工具:
你的工具 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 真的进了会话。
$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 那套沙箱脚本到底能干什么不能干什么。