标签：性价比方案

前沿哨所

• Pi Agent Core 实战（10/10）：循环上线之后

  极简框架把复杂度从框架搬到了你身上。循环本身只有 1445 行，它不替你做日志、不替你做预算、不替你做回滚、不替你做评测。它只保证一件事：模型做了什么、失败了什么，都变成事件发出来。剩下的账，得自己付。

  20 条失败用例覆盖四类：调用不存在的工具、参数不合 schema、工具抛异常、工具超时。每条独立跑一次完整循环，统计失败信号是否送达模型、循环是否崩溃。

  框架能保证的：失败一定被说出来

  20 条用例，四类失败各 5 条。结果很干净：20 条全部产生了明确的错误结果，带 isError 标记和可读原因；循环零崩溃，每次都能继续或正常收尾。

  四类的处理路径不一样。工具不存在时，循环直接生成「Tool xxx not found」的结果，不让模型空等；参数不合 schema 时，校验在执行前失败，工具根本没被调用；工具抛异常时，异常被捕获成错误结果；超时同理。

  这个一致性是设计出来的，不是碰巧。它意味着模型永远知道「刚才那步为什么没成」，而不是收到一个空结果或者一个被吞掉的异常。上一代系统最缺的就是这一层。

  20 条失败用例的实际结果

  失败类型	用例数	信号送达	循环崩溃	错误信息平均长度
  工具不存在	5	5	0	74 字符
  参数不合 schema	5	5	0	90 字符
  工具抛异常	5	5	0	77 字符
  工具超时	5	5	0	88 字符

  四类失败各 5 条，全部把错误如实送给模型，循环没有一次崩溃。

  注意：但「信号送达」不等于「问题解决」。框架保证模型看见错误，不保证它看见之后能改对。实测里能跑通是因为策略是脚本化的、确定会换策略；真实模型可能在同一处反复试，这时候需要的是预算闸门和人工接管，不是更多的重试。

  框架不保证的四件事

  一、成本

  循环没有内置预算。模型可以一直调工具，直到上下文爆掉或者你手动停。必须在钩子里计次、在上层计 token，两道闸门都要有。

  计次容易，计 token 麻烦——用量在 assistant 消息的 usage 字段里，要自己累加。累加的地方应该是 afterToolCall 或每轮结束，别放在界面层，界面层可能在重连后丢掉。

  这不是理论风险。我让一个脚本化模型在同一个错误上反复重试：权限被拒，它继续读同一个路径。没有闸门时，30 轮上限内它把 30 次调用全用完了；加一条「8 次预算 + 拦下后 terminate」的规则，第 9 轮就收尾。

  

  同一个死循环任务：无预算闸门时 30 轮上限内把 30 次调用全部用尽，加 8 次预算后 9 轮收尾。差的不只是次数，还有这 22 轮里每一个 token。

  更值得记的是那 30 轮不是终点，是我给实验设的上限。没有 terminate，模型会在这个错误上继续试下去，直到上下文撑爆或者你手动 kill。脚本编排时代这个由进程超时兜着，循环里没有进程生命周期，只能靠钩子。

  所以预算闸门要做两件事：到点拦住，并且让这一轮直接结束。只拦不终止，模型下一轮还会再请求同一个工具，你只是把频率降低了。

  二、观测

  pi 生态里有独立的 pi-telemetry 包，但那是可选项。真正必须做的是把事件落盘：每个事件带会话 id、轮次、时间戳、工具名、耗时、结果摘要。有了这份结构化记录，任何一次线上异常都能重放出来。

  反例是只记日志。日志是自由文本，事后要靠正则去猜当时发生了什么；事件是结构化的，可以直接算工具成功率、平均轮次、按失败类型分组。

  三、回滚

  循环会改东西——改文件、写库、重启服务。要能回滚，前提是每个有副作用的工具都留下「改之前是什么」。这件事框架不管，工具的作者必须管。

  务实做法是给工具加一个 replay 策略字段：声明为 safe 的工具可以重放，声明为 never 的工具出错后必须人工确认。循环本身支持这个语义，但具体哪些工具是 safe，只有你知道。

  四、评测

  真实模型做回归测试几乎不可能：温度、采样、上游版本都会让结果漂移。可行的做法是分层——循环用脚本化模型做单测，锁死「钩子是否拦截」「队列是否消费」「错误是否送达」这类行为；模型效果用固定用例集做抽查，允许答案措辞不同但要求关键结论一致。

  评测集不要超过 30 条。超过就没人维护了。每条用例写清三件事：输入、期望的关键结论、不可接受的结果。

  上线前的检查清单

  把这一篇和前九篇压缩成一张表。每一条都对应一个具体的失败模式，不是泛泛而谈。

  检查项	失败模式	对应实验
  工具描述能区分用途	模型选错工具、反复试同一个	04
  失败带 code 与原因	模型不知道发生了什么，原样重试	10
  危险动作有钩子	提示词约束失效，危险命令被执行	07
  有调用预算	同一错误上无限重试，烧成本	07
  上下文有剪枝策略	20 轮后上下文线性膨胀	06
  长任务有进度事件	用户以为卡死，提前退出	05
  支持插话	方向错了只能等跑完或杀进程	08
  事件落盘可重放	线上异常无法还原	—
  有回归集	换模型或改提示词后无据可依	10

  最后：极简不是省事，是把选择权还给你

  回头看这十篇，pi-agent-core 做的事情可以一句话概括：它只实现循环，把所有判断留给你和模型。工具只有几个，没有 MCP，没有子 Agent，没有沙箱，没有计划模式。

  这套设计的代价很明确，就是这一篇列的四件事都要自己做。收益也很明确：每个决定都是你做的，所以每个失败你都能定位。不会出现「框架内部在某处重试了三次」这种查不下去的情况。

  从 LangGraph 迁过来最大的变化不是代码少了，是心态变了。以前你在设计图的形状，试图把所有分支提前想到；现在你在设计工具和闸门，接受模型会走弯路。前者追求确定性，后者追求可恢复性——面对开放的任务，可恢复比确定更值钱。

  十篇的实验代码都在一个仓库里，每个数字都能自己跑一遍。如果你的场景是流程固定、分支可穷举，状态机仍然是更好的选择；如果你的场景是排障、调研、修复这类「下一步取决于这一步看到了什么」的任务，循环的性价比会高得多。

  引用与来源

  • pi-agent-core 官方仓库 — 核对 2026-10-31
  • pi-telemetry：厂商中立可观测性 — 可选依赖
  • 本系列第 1 篇：循环与图的对照实验 — 30 个任务集的原始数据
  刚刚

• Pi Agent Core 实战（8/10）：中断与排队

  长任务做到一半，用户发现方向错了。上一代系统的处理方式是等它跑完，或者直接杀进程——前者浪费时间和 token，后者丢掉全部中间结果。循环给了第三种可能：把话插进去，让它下一轮就改。

  6 轮工具循环，每轮工具固定 150 毫秒，并在每次 provider 请求前补 25 毫秒模拟网络往返。在第 3 轮开始时入队一条 steering 消息，观察它何时被消费。

  steering 和 followUp 不是一回事

  steering 是插话：任务还在跑，你要改变它的方向。它会尽快被消费——在下一个 provider 请求之前被注入上下文。适合「停一下，换个思路」「别扫全量了，先看最近的」。

  followUp 是追加：当前任务跑完了，接着做另一件事。它不会打断正在进行的工作，等自然停止之后才被消费。适合「这个查完了，顺手把另一个也看看」。

  搞混这两个的后果很直接：该用 steering 的场景用了 followUp，用户的指令要等十几轮之后才生效，体验上等于没听见。反过来，该用 followUp 的用了 steering，正在跑的任务被打断，前面白做。

  两种队列的调用方式

  // 插话：下一轮生效
  agent.steer({ role: 'user', content: '别扫了，直接给结论。', timestamp: Date.now() })
  
  // 追加：当前任务结束后生效
  agent.followUp({ role: 'user', content: '之后再查一下磁盘水位。', timestamp: Date.now() })
  

  背景：还有一个队列模式参数：one-at-a-time 是默认，每次只注入一条；all 是把队列里所有消息一次性注入。多人协作或高频插话的场景，one-at-a-time 更可控，不会让模型一下子收到五条互相矛盾的指令。

  实测：省 3 轮，快一倍

  基线跑完 6 个分片需要 7 轮请求（6 次工具加 1 次总结），总耗时 1110 毫秒。第 3 轮插话之后，模型在下一轮就用 3 个分片的已有结果收尾，总轮次降到 4 轮，耗时 571 毫秒。

  插话入队到模型真正看到它，间隔 362 毫秒——差不多是当前这一轮工具执行加请求往返的时间。这个延迟是结构性的：插话只能在轮次边界生效，不能打断已经在跑的工具。

  所以插话的响应时间取决于单轮长度。如果一轮里有 5 个并行工具、跑 30 秒，插话最坏要等 30 秒。想更快只有一个办法：把长轮拆成短轮。

  

  同一任务三种跑法的轮次数：不插话 7 轮，插话后 4 轮。两种队列模式结果一致，差别只在多条消息的注入粒度。

  三种跑法的完整对照

  跑法	轮次	扫描分片	总耗时（毫秒）	最终回复
  不插话	7	6	1110	6 个分片全部完成
  steer 单条	4	3	571	收到，停止扫描
  steer 全量	4	3	562	收到，停止扫描

  这里有个容易被忽略的设计后果：插话之后模型的行为完全变了，但它并没有“取消”已经跑的工具。第 3 轮那两个工具照常跑完，结果照常进了上下文，模型只是在下一轮决定不再继续。

  这意味着steering 是软中断，不是硬取消。真要立刻停下，得用 AbortSignal——那是另一条路径，会丢掉当前轮的产出。选哪个取决于任务能不能白跑。

  设计插入点要考虑的事

  第一件事是幂等。插话可能在奇怪的位置生效，比如工具刚跑完、结果还没进上下文。你的工具应该允许被重复调用而不产生副作用，否则一次 steering 可能导致重复扣款、重复写库。

  第二件事是确认。插话被消费的时候，界面应该给一个明确反馈——「指令已生效」。否则用户不知道自己的话有没有被听见，只能反复发。

  第三件事是冲突。如果队列里有两条方向相反的指令，one-at-a-time 模式会先注入第一条，模型执行后可能就不再需要第二条。这通常是对的，但要在界面上让用户看到队列状态，而不是静默丢弃。

  第四件事是审计。谁在什么时候插了什么话，必须留在会话记录里。出问题时这是唯一能还原「为什么它突然改主意」的证据。

  还有一件反直觉的事：不是所有任务都该允许插话。扫描、迁移、批量修复这类任务，中途改变方向往往意味着前面的工作全废，模型还得重新建立上下文。这种场景更应该做的是把任务切小——跑一个分片就停一次，让人在边界上决定要不要继续，而不是在中间拽方向盘。

  判断标准很简单：如果插话之后模型必须回头重做已经做过的部分，那插话就是在制造浪费。这时候真正需要的是更细的任务粒度，不是更强的中断能力。

  到这里，循环本身的能力已经讲完。剩下两篇回到工程现场：第 9 篇把脚本编排的死调用改成模型自主决策，第 10 篇讲上线之后的可观测与回归。

  引用与来源

  • pi-agent-core：continue() 与队列行为 — steering / followUp 与 QueueMode 语义
  • PendingMessageQueue 实现 — 版本 1.4.0
  刚刚

• Pi Agent Core 实战（7/10）：拦截钩子

  给 Agent 一个 bash，你就把整台机器交出去了。常见的应对是往提示词里写「只执行只读命令」——这不是约束，是请求。实测里，写了这句话的系统，5 条危险命令一条不落地全执行了。

  12 条命令请求分三类：5 条正常只读、5 条危险（删除、改状态、读敏感文件）、2 条越界。两组对照：一组只有提示词约束，一组加 beforeToolCall 三条闸门和 8 次调用预算。

  提示词约束为什么不算约束

  提示词是上下文的一部分，模型可以选择遵守，也可以不遵守。它没有强制力，也没有留痕。更麻烦的是，它在长会话里会被稀释——前面二十轮的历史压过来，「不要读 /etc」这句话的权重可能还不如最近一条工具输出。

  实测结果很直白。系统提示里明确写了「绝对不要执行 rm -rf、systemctl restart、读取 /etc/shadow 或往外 scp 文件」，12 条命令全部落地，其中 5 条正是不该执行的那批。

  这不是模型不听话的问题，是架构问题。你给了它能力，却没在能力前面放闸门。能做的事，模型迟早会做——不是因为它坏，是因为那个时刻它觉得该做。

  注意：一条实用的判断：如果一句话失效的后果是不可逆的（删数据、改生产状态、数据外传），那它就不能只写在提示词里。必须有一个代码层的检查点，在动作发生前拦住。

  beforeToolCall 能做什么

  这个钩子在参数校验之后、工具执行之前触发。它拿到完整的工具调用、已校验的参数、以及当前上下文，可以返回 block: true 直接拦下，并附上原因。

  时机很关键：参数已经合法，所以你能放心地基于字段做判断，不用担心它传了个字符串来搞乱解析；但它还没执行，所以拦下来是真的没跑。

  配套的 afterToolCall 在执行完、事件发出前触发，可以改写结果、打审计标记、或者给这一批调用打上 terminate 让循环不再请求模型。两个钩子一个管入口，一个管出口。

  三条闸门加一个预算

  const agent = new Agent({
    tools: [bashTool],
    beforeToolCall: async ({ toolCall }) => {
      const cmd = toolCall.arguments?.cmd ?? ''
      if (/brms+-rfb/.test(cmd)) return { block: true, reason: '危险命令需人工确认' }
      if (/systemctls+restart|find .+-delete/.test(cmd)) return { block: true, reason: '改状态命令需人工确认' }
      if (//etc/|/.ssh/|scps/.test(cmd)) return { block: true, reason: '越界路径' }
      if (++callCount > BUDGET) return { block: true, reason: '本轮调用预算已用尽' }
      return undefined
    },
  })
  

  注意最后一个闸门——调用预算。它不是安全策略，是资源策略：防止模型在同一个错误上反复尝试，把 token 和时间一起烧掉。在脚本编排时代这个由轮次上限兜着，在循环里必须自己加。

  实测：8 条被拦，危险命令零执行

  同一批 12 条请求，加上钩子之后只执行了 4 条：读日志、grep 错误、看磁盘、tail 日志——全是只读操作。其余 8 条被拦下，分别是 1 条危险命令、2 条改状态命令、2 条越界路径、3 条超预算。

  对照组那边 12 条全执行，其中 5 条是危险操作。两个数字放在一起，就是「提示词约束」和「代码约束」的全部差别。

  顺带一个观察：被拦的次数比危险请求多，是因为预算闸门在最后 3 条上也拦了。这说明闸门是会叠加的——先执行策略检查，再执行预算检查，两者互不干扰。

  

  12 条请求的处置分布：有钩子时执行 4 条、拦截 8 条（危险 1、改状态 2、越界 2、超预算 3）；只有提示词时 12 条全部执行，其中 5 条危险。

  两组对照

  指标	只有提示词	加 beforeToolCall
  实际执行	12	4
  被拦截	0	8
  危险命令执行	5	0
  拦截原因可追溯	否	是

  钩子里该写什么，不该写什么

  该写的是硬规则：路径白名单、命令模式黑名单、单轮预算、需要人工确认的动作清单。这些判断应该是纯函数式的——同样的输入永远给同样的结论，不依赖上下文里模型的措辞。

  不该写的是业务判断。见过在钩子里调模型做「这个命令危险吗」的二次判断，结果延迟翻倍、结论还不稳定。钩子必须在毫秒级返回，否则它自己成了瓶颈。

  还有一条容易被忽略：拦截要给原因。reason 会作为错误结果交给模型，模型据此换策略。只说「被拒绝」等于让模型瞎猜，它大概率会原样再试一次，然后被再拦一次。

  拦截次数和原因要单独记录。这组数据比任何日志都有用——它直接告诉你模型的危险倾向在哪一类操作上，下次系统提示或工具设计该怎么调。

  权限管住了，下一个问题是人在回路。任务跑到一半用户改主意了，怎么办？第 8 篇讲 steering 和 follow-up，实测能省下 3 轮和一半耗时。

  引用与来源

  • pi-agent-core：beforeToolCall / afterToolCall 语义 — 钩子触发时机与 block/terminate 行为
  • AfterToolCallResult 类型定义 — 版本 1.4.0
  刚刚

• Pi Agent Core 实战（5/10）：把事件流当 UI

  用户判断一个 Agent 靠不靠谱，用的不是准确率，是它有没有在动。同一个工具跑 600 毫秒，你可以让用户盯着空白等 600 毫秒，也可以在第 100 毫秒就告诉他扫到第几片了。后者不会让任务更快，但会让它看起来更可信。

  工具固定 600 毫秒、分 6 段推进，对比“只在结束时发一次结果”与“每段用 onUpdate 推送”两种模式下的首次可见时间。

  事件流本身就是给界面的协议

  循环发出来的九种事件，本质上是一份界面渲染协议：agent_start 代表开始思考，turn_start 代表新的一轮，message_update 携带文字增量，tool_execution_start 代表开始调用工具，tool_execution_update 携带进度，tool_execution_end 代表工具完成。

  不需要额外设计一套状态管理，也不需要在后端和前端之间同步一个“当前状态”字段。把事件按顺序重放，界面自然就是对的。这是事件驱动的最大好处：不存在状态漂移，只有事件缺失。

  这也是一个排查思路。界面上显示和实际不符，一定是某类事件没被处理，而不是“状态不对”。事件是唯一真相源，状态只是它的投影。

  把进度推出去

  execute: async (id, params, signal, onUpdate) => {
    for (let i = 1; i <= 6; i++) {
      await scanShard(i, signal)
      onUpdate?.({
        content: [{ type: 'text', text: `已扫描 ${i}/6 个分片` }],
        details: { done: i, total: 6 },
      })
    }
    return { content: [{ type: 'text', text: '扫描完成，3 条异常' }], details: { done: 6, total: 6 } }
  }
  

  背景：onUpdate 的第三个参数是 AbortSignal。长任务里必须把它往下传——用户点了取消，扫描循环要真的停下，而不是等它自己跑完。这是中断语义能不能落地的地方，第 8 篇会展开。

  508 毫秒的差，感知上是两个产品

  我测了两种模式。不报进度时，第一次有东西可显示是在 611 毫秒——也就是工具结束那一刻。用 onUpdate 每 100 毫秒推一次，第一次可见是 103 毫秒。

  508 毫秒的差距在人类感知里是明显的：低于 200 毫秒感觉是“立刻”，超过 500 毫秒开始怀疑“是不是卡了”，超过 1 秒很多人会刷新页面。

  更重要的不是感知，是可中断性。界面上一片空白的时候，用户不知道该不该等；一旦看到“正在扫描 3/6”，他就能判断这次还要多久，要不要停。

  

  首次可见时间：不报进度要等 611 毫秒，用 onUpdate 只要 103 毫秒。总耗时几乎一样，感知完全不同。

  两种模式的实测对照

  指标	仅结束事件	onUpdate 流式	差值
  首次可见（毫秒）	611	103	-508
  总耗时（毫秒）	612	610	-2
  中间事件数	0	6	+6
  用户可判断剩余时间	否	是	—

  别把进度做成噪音

  进度推送不是越多越好。每 10 毫秒推一次，界面会被高频更新拖垮，用户也读不出信息。合理的粒度是「每完成一个有意义的单位推一次」——一个分片、一批文件、一条记录。

  还有一点：进度内容要能回答「还要多久」。只推「正在处理」没有信息量，推「3/6，预计还要 300 毫秒」才有。所以 details 里带上 done 和 total，让界面自己算百分比。

  最后是节流。如果工具的天然粒度太细（比如逐行处理十万行日志），在工具内部累积到一定量再推，而不是每行推一次。

  放到服务端要考虑的三件事

  本地跑和放到服务端是两回事。第一件是传输：这些事件要转发给浏览器，SSE 是最省的方案，因为它是单向推送，不需要 WebSocket 的双向握手，也能穿过大多数代理。转发的时候只挑界面需要的字段，不要整个消息对象序列化——一条 tool result 里可能塞了几百 KB 的日志。

  第二件是顺序。事件的价值在于顺序，乱序重放会得到错误的界面。用一条自增序号或单调时间戳标注每个事件，前端检测到跳号就重新拉一次状态快照，而不是硬着头皮往下画。

  第三件是断线。长任务里网络中断几乎必然发生，用户刷新页面之后不该看到一个空界面。要把事件落盘（哪怕只是追加到一个本地 JSONL），重连时按 last-event-id 补发。这件事在脚本编排时代不需要考虑，因为脚本是同步阻塞的；一旦换成循环，任务可能跑十几分钟，补发就成了必需品。

  顺带一个反直觉的结论：事件持久化的成本比日志持久化低。因为事件是结构化的，落盘体积小；而日志是自由文本，事后要靠正则去猜当时发生了什么。把事件存好，等于把现场存好了。

  事件流打通之后，下一层问题就来了：上下文会越积越长。第 6 篇讲消息的两套模型，以及为什么压缩必须在 Agent 层做、不能写进提示词。

  引用与来源

  • pi-agent-core 事件类型表 — 九种事件与 tool_execution_update 语义
  • AgentToolUpdateCallback 类型定义 — 版本 1.4.0
  刚刚

• Pi Agent Core 实战（3/10）：40 行跑通第一个 Agent

  上一代框架最容易劝退人的地方是脚手架：配置文件、目录约定、中间件注册，跑通一个 hello world 要读半小时文档。pi-agent-core 反过来——核心就是 new Agent() 加一个 streamFn，剩下都是你自己决定。这一篇把最小可运行版本拆开，顺便看清一次 prompt 到底发生了什么。

  为了不依赖任何 API 密钥且可复现，实验注入了一个确定性 streamFn 取代真实模型。循环、工具调度、事件发射全部是真实运行时，只有模型输出是脚本化的。

  最小骨架：三个东西就能跑

  一个能跑起来的 Agent 只需要三样：初始状态（系统提示、模型、工具列表）、一个 streamFn（怎么把上下文变成模型的输出流）、以及一次 prompt 调用。没有 registry，没有 pipeline，没有 chain 组合器。

  streamFn 是关键设计。它的签名是拿到模型对象和上下文，返回一个异步事件流。这意味着循环不关心你用什么模型、走什么协议——真实 provider 用它，测试用假的也用它，两者走同一条路径。

  这个设计带来的直接好处是可测性：你可以把模型行为完整脚本化，然后精确断言循环在每种情况下做了什么。后面九篇的实验能复现，靠的就是这一点。

  最小可运行版本

  import { Agent } from '@earendil-works/pi-agent-core'
  import { createAssistantMessageEventStream } from '@earendil-works/pi-ai'
  
  const agent = new Agent({
    initialState: {
      systemPrompt: '你是一个排障助手。',
      model,
      tools: [],
    },
    streamFn: (m, context) => {
      const stream = createAssistantMessageEventStream()
      const text = '收到。'
      stream.push({ type: 'start', partial: partialMessage() })
      stream.push({ type: 'text_delta', contentIndex: 0, delta: text, partial: partialMessage(text) })
      stream.push({ type: 'done', reason: 'stop', message: finalMessage(text) })
      return stream
    },
  })
  
  agent.subscribe((e) => {
    if (e.type === 'message_update') process.stdout.write(e.assistantMessageEvent.delta ?? '')
  })
  
  await agent.prompt('帮我看看服务状态')
  

  背景：注意事件顺序里的一个细节：先 push start，再 push 增量，最后 push done。done 事件里带的是完整消息，而不是“结束标记”。循环拿这个完整消息继续判断要不要调工具、要不要再来一轮。

  一次 prompt 的完整事件序列

  我跑了一次带两个工具调用的会话：模型先决定同时读日志和查负载，两个工具并行执行，然后基于结果给出结论。整个过程发出 27 个事件，总耗时 314.7 毫秒。

  事件顺序是：agent_start → turn_start → 用户消息开始结束 → 助手消息开始 → 若干 text_delta → 助手消息结束 → 两个 tool_execution_start → 工具结束（按完成顺序）→ 工具结果消息 → turn_end → 下一轮 turn_start → 助手消息 → turn_end → agent_end。

  关键观察有两点。第一，单个 turn 内可以有多次工具调用，但只有一次模型请求；第二轮请求是因为工具结果需要模型解读，不是循环自己加的。第二，工具结束事件的顺序是完成顺序，不是声明顺序——180 毫秒的那个先结束，300 毫秒的后结束。

  

  一次 prompt 的耗时构成：两个工具并行执行占 300 毫秒，框架自身调度开销不到 5 毫秒。所谓 Agent 慢，慢在模型和工具，不在循环。

  这个数据推翻了一个常见直觉：以为 Agent 框架本身很重。实际上循环的开销是毫秒级，你感知到的所有延迟都来自模型往返和工具执行。

  推论也很直接：优化 Agent 性能，不要去优化循环。要么并行化工具，要么减少轮次，要么换更快的模型。循环本身没有可优化的空间。

  状态是你唯一需要读的东西

  Agent 实例上挂着一个 state 对象，里面是当前模型、思考等级、工具列表、完整消息历史，以及几个只读标记：是否正在流式、正在流式的消息、待完成的工具调用、错误信息。

  这个 state 是可变的，而且可以直接改。想临时换模型，改 state.model；想在两轮之间塞一条消息，push 进 state.messages。这在很多框架里是禁忌，在这里是设计。

  代价是责任：你改了 state，就要保证它仍然是一段合法上下文。宽松的接口换来的是自由，不是零成本。

  读状态做展示

  agent.subscribe((e) => {
    if (e.type === 'turn_start') {
      console.log('轮次', agent.state.messages.length, '待办工具', agent.state.pendingToolCalls.size)
    }
    if (e.type === 'agent_end') {
      console.log('会话结束，共', e.messages.length, '条消息')
    }
  })
  

  还有一个容易被忽略的方法：waitForIdle。prompt 返回不代表界面已经稳定，因为订阅 agent_end 的异步监听器可能还在跑。需要“确定一切结束”的时候，等它，而不是等 prompt。

  不配真实模型也能开发

  这个系列所有实验都不需要 API 密钥，原因是 streamFn 可以整个替换。把模型行为写成脚本，你就得到了一个完全确定的 Agent——同样的输入永远产生同样的工具调用、同样的事件序列。

  这在工程上价值很大。真实模型做回归测试几乎不可能：温度、采样、上游版本变化都会让结果漂移。但把模型换成脚本之后，你可以断言“第三次工具调用必须被钩子拦住”“队列里的消息必须在下一轮被消费”这类循环级行为。

  结论：把模型当外部依赖，把循环当自己的代码。前者用集成测试抽查，后者用单元测试锁死。

  下一篇讲工具。这是整个系列里最容易被低估的部分——大多数人以为工具就是“注册一个函数”，实际上工具的 schema 设计直接决定了模型能不能用对，执行模式决定了任务要跑多久。

  引用与来源

  • pi-agent-core README：Quick Start 与事件流 — 核对 2026-10-31
  • AssistantMessageEventStream 工厂函数 — createAssistantMessageEventStream 为公开导出
  刚刚

• Pi Agent Core 实战（2/10）：三层拆开看

  很多人第一次看 pi 的仓库会困惑：为什么一个 Agent 框架要拆成三个包？装一个不行吗？答案藏在一个数字里——真正的循环层只占整个体系代码量的 1.7%。拆开不是因为讲究，是因为不拆就没法只替换其中一层。

  统计口径：各包 dist 目录下 .js 文件的物理行数（含空行与注释），版本 1.4.0。这不是有效代码行数，但用来比较相对体量足够稳。

  三层分别解决什么问题

  最底下是 pi-ai，管模型接入。它把 OpenAI、Anthropic、Gemini、Bedrock、本地 Ollama 这些不同的 API 抹平成一套接口：统一的流式协议、统一的工具调用格式、统一的用量统计。上层代码不需要知道背后是哪家模型，换模型只换一个 provider 对象。

  中间是 pi-agent-core，管循环。它拿一段上下文发给模型，模型说要调工具，它执行，把结果塞回去，再来一轮。它还管状态、事件流、消息队列、钩子——但不管“你要做什么业务”。

  最上面是 pi-coding-agent，是一个完整产品：命令行界面、会话管理、主题、扩展加载、斜杠命令。你在终端里用的那个 pi，是这一层。

  为什么这个切分值得学

  大多数 Agent 框架把这三件事揉在一个包里。后果是：你想换模型，得改框架内部；你想换界面，得 fork 整个仓库；你只想用循环，被迫装进一整套 CLI 依赖。

  切成三层之后，每一层的替换成本是独立的。做后端服务只需要 pi-ai 加 pi-agent-core，不用拖进 25MB 的终端界面。做终端工具就三层全要。想做嵌入式或浏览器端，中间那层是纯 TypeScript，没有任何 Node 原生依赖。

  这个思路可以直接搬到自己项目里：接入层、循环层、交互层分开，界面永远不参与决策。

  体量比例：1.7% 是核心，74.6% 是壳

  我把三个包的 dist 目录全量扫了一遍，数物理行数。结果比预想的更极端：核心循环 1445 行，模型接入层 20551 行，产品层 64769 行。

  这个比例说明一件事：Agent 的复杂度不在循环，在模型适配和交互。循环本身是十几行伪代码就能说清的东西——发请求、收工具调用、执行、回填、再来一轮。真正吃掉工程量的是各家 API 的差异、流式解析的边界、终端界面的渲染。

  所以那些“用框架写了三个月还在调”的项目，时间大概率花在了产品层，而不是循环层。这个认知很重要：换掉循环，省不下多少代码；换掉循环，省下的是决策权的归属。

  

  三层代码量对比：核心循环只占 1.7%，产品层占了近四分之三。想改行为，改的是那 1445 行；想改体验，改的是那 6 万行。

  三层的依赖与导出

  包	职责	一级依赖	导出符号	占比
  pi-ai	模型接入	10	36	23.7%
  pi-agent-core	Agent 循环	2	5	1.7%
  pi-coding-agent	CLI 产品	22	44	74.6%

  循环层只有 2 个一级依赖，这是刻意的。依赖越少，越容易嵌进别人的运行时——Cloudflare Worker、浏览器、你自己的后端服务。

  导出符号只有 5 个，也说明它的 API 面很小。小的 API 面意味着升级不容易炸：你依赖的东西少，别人改的时候波及你的概率就低。

  每一层你实际会碰什么

  在 pi-ai 这层，你打交道的是 provider 和 model 对象。日常操作是选模型、配 baseUrl、处理密钥轮换。如果要做私有化部署，这层是唯一需要改的地方。

  在 pi-agent-core 这层，你打交道的是 Agent 实例、工具定义、事件订阅、钩子。这一层是你写业务逻辑的地方，也是这个系列后面八篇的主战场。

  在 pi-coding-agent 这层，你打交道的是扩展、命令、主题、会话存储。如果你只是要用它当工具，这层是配置问题；如果你要把它嵌进自己产品，这层大概率整个不要。

  只用前两层的最小安装

  npm install @earendil-works/pi-agent-core @earendil-works/pi-ai
  # 不需要 pi-coding-agent，省下 25MB 和 22 个依赖
  

  背景：一个常见的误判：以为装了 Agent 框架就自动获得“工具生态”。pi 的官方态度是不内置 MCP、不内置子 Agent、不内置沙箱。这些能力在 pi-mcp、pi-codemode 这些独立包里，或者由你自己实现。选型时把这块算进成本。

  三层切分对自建系统的启发

  如果你正在维护一个内部 Agent 平台，这套切分可以直接借。接入层只负责“把请求变成统一格式”，循环层只负责“决定下一步”，交互层只负责“把事件渲染出来”。三层之间只通过事件和消息通信。

  这样做最直接的好处是可观测。所有决策都发生在循环层，所有决策都会发出事件；交互层不参与决策，所以你能确定“看到的”就是“发生的”。反过来，如果界面层能偷偷改工具参数，你的日志就永远对不上现场。

  第二个好处是可替换。模型换代时只换接入层，界面改版时只改交互层。循环层的代码一年可能都不动一次——因为它要做的事本来就没变过。

  下一篇进入实操：不装 CLI、不配真实模型，用 40 行代码把循环跑起来，看看一次 prompt 到底发出了哪些事件、按什么顺序发。这是后面所有中级技巧的地基。

  引用与来源

  • pi-mono 仓库（三层同仓管理） — 核对 2026-10-31
  • pi-ai on npm — 版本 1.4.0
  • pi-coding-agent on npm — 版本 1.4.0
  刚刚