https://murasaki010.github.io/tags/source-code/Recent content in Source Code on Yukari's BlogHugozh-cnFri, 29 May 2026 00:00:00 +0000https://murasaki010.github.io/posts/pi-architecture/agent-loop-code-walkthrough/Fri, 29 May 2026 00:00:00 +0000https://murasaki010.github.io/posts/pi-architecture/agent-loop-code-walkthrough/<h1 id="pi-agent-包源码逐行解读">Pi Agent 包源码逐行解读</h1> <blockquote> <p>本文对 <code>packages/agent/src/</code> 下的 <code>agent-loop.ts</code>（~700 行）和 <code>agent.ts</code>（~540 行）做<strong>逐行级</strong>的代码解读，涵盖每个函数的设计意图、类型系统、控制流和错误处理策略。</p> </blockquote> <hr> <h2 id="目录">目录</h2> <ol> <li><a href="#%E6%96%87%E4%BB%B6%E6%A6%82%E8%A7%88">文件概览</a></li> <li><a href="#agent-loopts-%E9%80%90%E8%A1%8C%E8%A7%A3%E8%AF%BB">agent-loop.ts 逐行解读</a> <ul> <li><a href="#%E7%B1%BB%E5%9E%8B%E4%B8%8E%E5%AF%BC%E5%85%A5">类型与导入</a></li> <li><a href="#agentloop--agentloopcontinue--%E5%85%AC%E5%BC%80%E5%85%A5%E5%8F%A3">agentLoop / agentLoopContinue — 公开入口</a></li> <li><a href="#runagentloop--runagentloopcontinue--%E5%BC%82%E6%AD%A5%E5%BA%95%E5%B1%82">runAgentLoop / runAgentLoopContinue — 异步底层</a></li> <li><a href="#runloop--%E6%A0%B8%E5%BF%83%E5%8F%8C%E5%B1%82%E5%BE%AA%E7%8E%AF">runLoop — 核心双层循环</a></li> <li><a href="#streamassistantresponse--llm-%E6%B5%81%E5%BC%8F%E8%B0%83%E7%94%A8">streamAssistantResponse — LLM 流式调用</a></li> <li><a href="#executetoolcalls--%E5%B7%A5%E5%85%B7%E8%B0%83%E5%BA%A6">executeToolCalls — 工具调度</a></li> <li><a href="#executetoolcallssequential--parallel--%E4%B8%B2%E8%A1%8C%E4%B8%8E%E5%B9%B6%E8%A1%8C">executeToolCallsSequential / Parallel — 串行与并行</a></li> <li><a href="#preparetoolcall--%E5%89%8D%E7%BD%AE%E7%AE%A1%E9%81%93">prepareToolCall — 前置管道</a></li> <li><a href="#executepreparedtoolcall--%E5%B7%A5%E5%85%B7%E6%89%A7%E8%A1%8C">executePreparedToolCall — 工具执行</a></li> <li><a href="#finalizeexecutedtoolcall--%E5%90%8E%E5%A4%84%E7%90%86">finalizeExecutedToolCall — 后处理</a></li> <li><a href="#%E8%BE%85%E5%8A%A9%E5%87%BD%E6%95%B0">辅助函数</a></li> </ul> </li> <li><a href="#agentts-%E9%80%90%E8%A1%8C%E8%A7%A3%E8%AF%BB">agent.ts 逐行解读</a> <ul> <li><a href="#%E7%B1%BB%E5%9E%8B%E4%B8%8E%E5%AF%BC%E5%85%A5-1">类型与导入</a></li> <li><a href="#mutableagentstate-%E4%B8%8E-createmutableagentstate">MutableAgentState 与 createMutableAgentState</a></li> <li><a href="#pendingmessagequeue">PendingMessageQueue</a></li> <li><a href="#agent-%E7%B1%BB--%E6%9E%84%E9%80%A0%E5%99%A8">Agent 类 — 构造器</a></li> <li><a href="#subscribe--%E4%BA%8B%E4%BB%B6%E8%AE%A2%E9%98%85">subscribe — 事件订阅</a></li> <li><a href="#prompt--%E5%8F%91%E8%B5%B7%E5%AF%B9%E8%AF%9D">prompt — 发起对话</a></li> <li><a href="#continue--%E7%BB%A7%E7%BB%AD%E5%AF%B9%E8%AF%9D">continue — 继续对话</a></li> <li><a href="#steer--followup--%E6%B6%88%E6%81%AF%E9%98%9F%E5%88%97">steer / followUp — 消息队列</a></li> <li><a href="#abort--waitforidle--reset--%E7%94%9F%E5%91%BD%E5%91%A8%E6%9C%9F%E6%8E%A7%E5%88%B6">abort / waitForIdle / reset — 生命周期控制</a></li> <li><a href="#%E7%A7%81%E6%9C%89%E6%96%B9%E6%B3%95runpromptmessages--runcontinuation">私有方法：runPromptMessages / runContinuation</a></li> <li><a href="#runwithlifecycle--%E5%B9%B6%E5%8F%91%E6%8E%A7%E5%88%B6">runWithLifecycle — 并发控制</a></li> <li><a href="#handlerunfailure--%E5%A4%B1%E8%B4%A5%E5%A4%84%E7%90%86">handleRunFailure — 失败处理</a></li> <li><a href="#finishrun--%E8%BF%90%E8%A1%8C%E7%BB%88%E7%BB%93">finishRun — 运行终结</a></li> <li><a href="#processevents--%E4%BA%8B%E4%BB%B6%E5%BD%92%E7%BA%A6">processEvents — 事件归约</a></li> <li><a href="#createcontextsnapshot--createloopconfig--%E9%80%82%E9%85%8D%E5%B1%82">createContextSnapshot / createLoopConfig — 适配层</a></li> </ul> </li> <li><a href="#%E8%AE%BE%E8%AE%A1%E6%A8%A1%E5%BC%8F%E6%80%BB%E7%BB%93">设计模式总结</a></li> </ol> <hr> <h2 id="文件概览">文件概览</h2> <pre tabindex="0"><code>packages/agent/src/ ├── agent-loop.ts # 无状态循环引擎（~700 行，纯函数） ├── agent.ts # 有状态封装层（~540 行，Agent 类） ├── types.ts # 类型定义（~400 行） ├── proxy.ts # HTTP 代理（~320 行） ├── index.ts # 导出入口（~8 行） ├── agent-learn.ts # 学习相关 ├── agent-loop-learn.ts └── README.md </code></pre><p><strong>核心分界线：</strong></p>