从 Pi 的入口读到 Agent Core

先把范围说清楚。这里的 Agent 指一段会反复请求模型、执行工具、再把工具结果送回模型的程序。Pi 把这段机制拆成多个 package，同时提供了一个可以直接使用的 Coding Agent 命令行产品。

假设你在 AgentHarness.prompt() 里打了断点，随后启动 Pi Coding Agent，输入“概括这个目录”。终端正常返回，断点却一次也没有命中。

代码没有失效，断点也没有打错。当前 Coding Agent 仍然通过 createAgentSession() 构造 Agent，再由 Agent 驱动底层 Loop。仓库里的 AgentHarness 已经能调用同一套 Loop，但 CLI 还没有完全迁过去。

这两条路径要分开记录。仓库里已经出现的类，不等于 CLI 当前已经使用的内核。

先认四个包

Pi 是一个 monorepo。用户在终端里看到的 Coding Agent，由四个 package 叠在一起：

包	它处理的事情	这一层不会处理的事情
`@earendil-works/pi-ai`	Model、Provider、鉴权、各家 API 适配和统一流事件	不决定循环是否继续，也不执行文件工具
`@earendil-works/pi-agent-core`	消息状态、Agent Loop、工具校验与执行、生命周期事件	不决定 Coding Agent 要开放哪些工具
`@earendil-works/pi-coding-agent`	CLI、文件工具、Session、Extension、Skill、设置与自动压缩	不实现各家模型协议
`@earendil-works/pi-tui`	终端组件、输入框和增量渲染	不改变 Agent 的执行规则

Pi 的根 README 对四个 package 有一段简洁说明，可以先把它当作源码地图：固定版本的 package 列表。

四层分开有一个直接好处。Provider 的流格式变了，通常去 pi-ai 找；工具重复执行，先看 pi-agent-core；Skill 没有加载，则去 pi-coding-agent；终端刷新异常，才轮到 pi-tui。这比在整个仓库里搜索 “agent” 有效得多。

CLI 现在走哪条路

当前 Coding Agent 的 composition root 是 createAgentSession()。它准备模型、工具、资源加载器和存储，然后构造一个 Agent，再用 AgentSession 包住它。查看 createAgentSession() 的固定版本源码。

把细节收起来，现行路径可以写成：

TUI / RPC / Print
        ↓
createAgentSession()
        ↓
AgentSession
        ↓
Agent.prompt()
        ↓
runAgentLoop()
        ↓
streamFn() / tool.execute()

AgentSession 负责产品能力。它处理 Extension 命令、Skill 展开、模型鉴权、压缩检查和消息持久化；Agent 保存内存状态并对外发事件；runAgentLoop() 才负责一轮又一轮地请求模型、执行工具、放回结果。

AgentHarness 正在补什么

新的 AgentHarness 把 Model、Session、Resources、Tools 和运行阶段重新收进 core：

AgentHarness
  ├─ Models
  ├─ Session
  ├─ Resources
  ├─ Tools
  └─ runAgentLoop()

它已经拥有 turn snapshot、Session 写入、保存点、树导航和手动压缩等实现。查看 AgentHarness.prompt() 进入 Loop 的位置。

但官方文档仍明确写着，Coding Agent 目前由 AgentSession + Agent + streamFn 驱动，产品当前路径说明；AgentSession 向 AgentHarness 的迁移仍在后续清单里，迁移计划。

后面的章节会按这三个名称说话：

runAgentLoop 指最小执行机制；
Agent 指当前稳定的有状态包装；
AgentHarness 指正在把 Session、资源和生命周期收回 core 的新路径。

准备运行环境

离线实验需要 Node.js 24 或更高版本，不需要模型 Key，也没有第三方运行依赖。第一次从仓库开始：

git clone https://github.com/summerchaserwwz/summer-ai-knowledge-system.git
cd summer-ai-knowledge-system/agent-harness-lab
node --version
npm run lab -- 01

Windows PowerShell 可以使用同一组命令。node --version 低于 24 时，先升级 Node.js；实验成功时会输出一段 JSON，不会访问网络。

跑一次源码地图

第一个实验不需要模型。它只打印版本、四层职责和两条路径：

cd agent-harness-lab
npm run lab -- 01

输出中应当能找到：

{
  "sourceRevision": "b4f293684bba718d59cc1157679bcf6157b3a7f5",
  "auditedHeadRevision": "5bc1c2c0a6f07e00e8c240304182f213ab8d311f",
  "productPath": "createAgentSession → AgentSession → Agent.prompt → runAgentLoop → streamFn/tool.execute",
  "inProgressPath": "AgentHarness（尚未完全替代 Coding Agent 的 AgentSession）"
}

跑完这条命令，你就有了后面读源码时的坐标。接下来沿现行路径跟踪一条不调用工具的请求，看用户输入怎样到 Provider，再变成事件。