为什么要把「一次对话」拆到函数级

上篇文章中我跑通了第一个插件，但那只是“会用”。这次的目标是“懂”：当我在 pi 里敲下一行 “+ 等于几”。到我看到回答，这中间到底发生了什么？

痛点：开发者往往只关注最终输出。却忽视了内部流程，导致难以定位问题。按理说，

这篇文章把这条链路从入口拆到工具执行。 每一环都标注源码文件:行号。 配合一张时序图和一张工具调用图，读完你也能闭着眼画出 pi 的运行时骨架。老实说，

环境与版本

• 再看仓库，
• 从版本来看，.
• 再看关键目录。
  • packages/coding-agent
  • packages/agent

一次交互的完整调用栈

痛点：没有可视化时序图时开发者很难快速定位错误来源。

// 使用者输入 → sendUserMessage → prompt → _runAgentPrompt
// ├─ await this.agent.prompt ← 跨包桥
// │ → runPromptMessages
// │ ├─ createContextSnapshot ← AgentContext 快照
// │ └─ runWithLifecycle ← 包生命周期事件
// → runAgentLoop
// → runLoop ← 模型/工具循环
// ├─ while _handlePostAgentRun ← 重试/follow-up
// │ └─ _checkCompaction ← 上下文压缩检查
// └─ finally:
// ├─ _flushPendingBashMessages
// └─ _emitAgentSettled ← 发 agent_settled 事件

更直观的时序图：

sequenceDiagram
participant U as 使用者
participant S as AgentSession
participant A as agent 包
participant M as Model / LLM
participant R as Tool Runner
participant T as Tool
再看U->S。输入 “+ 等于几”
S->S这方面，prompt 组装上下文/程序提示词
从S->A来看，agent.prompt 跨包桥
再看A->M，请求
至于M-->A，tool_call
从A->R来看，executeToolCalls
说到R->T，execute
T-->R这方面，{content: &#;+ &#，}
至于R-->A，toolResult 消息
A->M的观点是，追加结果，请求
M-->A的观点是，最终文本
A-->S这方面，agent_settled
S-->U的观点是。渲染输出

最关键的架构认知：两个包的职责分界

痛点：因为缺乏清晰模块划分，许多新手在 时会把工具写进错误的位置，导致无法被正确调用。

• @earendil-works/pi-coding-agent：管会话、资源加载、 注册、UI。它是“壳”，
• @earendil-works/pi-agent：管模型循环本身。它是“核”，

You register tools and extensions in shell layer,but actual model loop and tool execution logic lives in core layer. Understanding this boundary prevents you from getting lost when inspecting any pi extension code.

ExtensionAPI 全貌：一张图数完组能力

M0 我只会 .registerCommand 和 .registerTool. 本轮阅读了整个接口文件 ) 并按注释分块：

• Easiest pitfall: .ctx.ui.xxx  doesn't belong to ExtensionAPI—it's part of ExtensionContext passed to handlers.
• Nevessary note on events: 's second generic R  if determines wher you can intercept events. Events like tool_call/input/context support interception via returning {block:true}。 whereas start events do not.

registerTool 深潜：工具是怎么被调起来的

注册的观点是，只存不干

The implementation ) simply adds tool definition to an internal Map. Real work happens in core package.

说到执行，按名字 find

A model’s tool_call is handed off to runLoop → executeToolCalls → prepareToolCall . The key line:

const tool = currentContext.tools?.find => t.name === toolCall.name);不过，if {
return {
至于kind，"immediate"。result:createErrorToolResult,isError:true,};}

: If not found you immediately get an error result—no execution occurs.

A complete sequence diagram for a single call:

sequenceDiagram autonumber
participant M as Model
participant L as runLoop
participant P as prepareToolCall
participant X as execute
participant T as emitToolResult

M->L : tool_call L->P : executeToolCalls → prepareToolCall P-<-P : tools.find <- 查找 P-&rarr>X : executePreparedToolCall 执行 X--<-P : {content: &#+ = &#} P-&rarr>T : finalize &rarr emitToolResult T--<-M : toolResult 消息 &rarr 增加上下文 &rarr 再请求

说到实验。让 LLM 真正调一次工具

M1 的主要实验是编写一个简单加法工具并让 LLM 调用它，以验证链路是否正常工作。

// .pi/extensions/add-tool.ts

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

const addTool = defineTool({ 说到name，"add",label:"Add",description:"当使用者问加法/算术问题时使用。计算两个数字之和",parameters:{ a: Type.Number,b: Type.Number },async execute{ if{ return{content:};} const result=params.a+params.b;怎么说呢，return{ content:。details:{a:param,b:param,result} };} })，

export default function{ pi.registerTool;}

In practice inside pi:

ini

Notice how model actively recalls “add” tool,initiates a tool_call,receives result,and n continues generating final answer—this is a live test of entire chain described earlier.

•  Packing two modules’ responsibilities: coding‑agent is shell。agent is core . The bridge lives in #agent‑session.ts#.
•  The full capability set exposed by ExtensionAPI: tools / commands / events / rendering / actions / session metadata / models / providers / event bus—all accessible via distinct registration points.
•  The complete lifecycle of a tool: Registration only stores definitions → Model triggers tool_call → Lookup by name → Execution → Return toolResult → Next round loop.