源码篇第5章 调度台——pi-coding-agent ​

小A与老Z将发光的回合事件接入打开的会话册,册中连续的历史卡片分出一条新路径。

本章导读: 源码路线第 ④ 站(产品层的核心部件)。v1.0.0 把会话、压缩和 Skills 从 pi-agent-core 移到了 pi-coding-agent/src/core。这一站读 agent-session.ts、session-manager.ts、agent-session-runtime.ts、compaction/compaction.ts 和 skills.ts。要拆掉小A以为的“fork 就是 Git 分支”的错觉,看清会话到底靠什么活过一次进程。

小A照着 源码篇第4章,把 loop 里的状态变化理清楚了。但他翻遍 packages/agent/src,只找到五个文件,会话代码一行都没有。他又在 coding-agent 里看到 fork 这个方法名,忽然冒出个想法:“这不就是 Git 分支吗?我 fork 一个会话,再让两个 Agent 各改各的,互不干扰?”

“停。”老Z说,“会话 fork 不是 Git 分支,也不会创建或隔离 worktree。你这句话里有两个概念被焊在一起了。先弄清会话代码搬到了哪儿,再按装配层把‘会话活过一次进程’讲清楚。”

低层 loop 能把一次流和工具结果推进完,却不知道会话应保存到哪里、何时压缩、哪些 Skills 可用。在 v1.0.0 里,把这些宿主决策接到 loop 上的是 coding-agent 的 AgentSession。

本章依据上游 pi 标签 v1.0.0(提交 a13d35a742c6ef8462812a28fbe1d8c8b7431c32)、@earendil-works/pi-coding-agent 1.0.0。跟读 AgentSession 的装配插口、一次 prompt 的写入、JSONL 会话文件、fork、compaction 和 skills。不覆盖 coding-agent 如何解析命令行和选工作目录(见源码篇第7章),也不证明文件系统在断电下的耐久性。

Harness 去了哪里 ​

小A:“旧资料里说 pi-agent-core 有个 AgentHarness,管会话和压缩。现在呢?”

“上游提交 7fd478a2 的标题是 ‘remove the experimental harness from pi-agent-core’。”老Z说,“v1.0.0 的 packages/agent/src/index.ts 只导出 agent.ts、agent-loop.ts、proxy.ts、setDefaultStreamFn 和 types.ts。原来那层装配的职责,按下表分散到了产品层。”

旧版职责 v1.0.0 的位置 本章读什么
把宿主决策接到 loop core/agent-session.ts 的 AgentSession 构造函数装的插口
会话文件与会话树 core/session-manager.ts 的 SessionManager _persist、loadEntriesFromFile、createBranchedSession
fork 与换会话 core/agent-session-runtime.ts 的 AgentSessionRuntime fork
压缩 core/compaction/ prepareCompaction、compact、getSummarizationFailure
Skills core/skills.ts loadSkillsFromDir、formatSkillsForPrompt

pi-durable 包里另有一套 harness/ 和 SQLite 存储,那是另一种“先原子落盘、后对外可见”的运行时。本章不展开它;源码篇第13章 先落盘,后可见——pi-durable 专门读那个内核,并与本章对照。

比喻:调度台

loop 是引擎,AgentSession 是调度台:它决定会话写哪、何时压缩、哪些技能可见;引擎本身不是它造的,它只在引擎留出的插口上接线。

调度台接在哪几个插口上 ​

小A猜:“AgentSession 听起来像个更大的循环?”

“不是。它持有一个 Agent,然后在源码篇第4章那些插口上接线。”老Z打开构造函数:

ts
// packages/coding-agent/src/core/agent-session.ts,AgentSession 构造函数(v1.0.0,节选)
// Always subscribe to agent events for internal handling
// (session persistence, extensions, auto-compaction, retry logic)
this._unsubscribeAgent = this.agent.subscribe(this._handleAgentEvent);
this._installAgentToolHooks();
this._installAgentNextTurnRefresh();
this._installAgentRequestProjection();
this._installAgentBoundaryHooks();
this._installHiddenDeclarationsProjection();

“_installAgentToolHooks 直接把 beforeToolCall/afterToolCall 换成派发扩展的 tool_call 事件,扩展事件的整体结构见源码篇第8章。其余几个 _install* 都先保存 Agent 上原有的回调,再包一层新的,原回调仍会被调用。”老Z说,“注意这不表示每个功能都会启用:扩展没有注册处理器时,对应的边界事件直接跳过。”

插口(源码篇第4章) AgentSession 接上的东西 主要边界
subscribe _handleAgentEvent:先发扩展事件,再通知监听者,然后写会话 写会话是同步追加,失败会抛出
prepareNextTurn 超过阈值时先压缩,再重建 system prompt 与工具清单 压缩可能失败或被扩展取消
prepareRequest 每次请求前用 buildSessionProjection() 重建要发给模型的 messages 投影来自会话树,不来自 loop 的内存数组
finishTurn 派发扩展的 turn_end 边界,扩展可要求再请求一次 扩展不能把 error/aborted 变回成功

小A注意到第三行:“请求前 messages 被换掉了?”

“对。_installAgentRequestProjection 里的 canonicalContext 用的是 this.sessionManager.buildSessionProjection().messages。”老Z说,“所以模型看到的上下文以会话树为准:压缩摘要、分支摘要、context_edit 都在这一步生效。loop 里的 currentContext 只是这一次 run 的工作副本。”

本章其余小节为付费内容

登录后可购买;已购 Pi Cookbook Pro?登录即解锁完整章节。