PRIME AGENT FROM SOURCE

Prime Agent 源码解析

一个自我改进的 RLM Agent——把模型放进持久 REPL，让 harness 随经验演化

本书是一份教育性的源码研究笔记。分析对象 Prime Agent（PrimeIntellect 开源的编码与研究 Agent）采用 MIT 许可发布，书中所有代码片段均直接取自真实源码，文件路径与函数名皆可逐一核对。本书与 Prime Agent 的维护者无关，未获其背书或赞助。

分析基于的版本为 monorepo v0.7.2。

这本书想回答什么问题

在我们的前作《Pi Agent 源码解析》里，你见过一种极端：刻意保持最小的包联邦，把一切复杂性挡在核心之外。而在本书仓库的 reference/ 中作为参照收录的《Claude Code 源码解析》（在线阅读）展示了另一种极端：近两千个文件的单体综合体，把每一种故障模式都固化成 if 分支。这两条路线回答的是同一个问题的两个方向：Agent 的复杂性应该放在哪里？

Prime Agent 提出了第三个问题，一个更根本的问题：

模型到底应该以什么方式行动？

Claude Code 和 pi 给出的答案是相同的：工具调用。模型输出一段结构化的 JSON——「调用 read 工具，参数是这个路径」——宿主执行，把结果塞回上下文，循环往复。每个能力是一个工具；每个工具是一份 JSON schema；每次使用是一次结构化输出。

Prime Agent 的回答是：写代码。它把模型放进一个持久 IPython 解释器里，整个系统只有一个内置模型工具——ipython。读文件？Path.read_text()。跑命令？%%bash 魔法。派一个子代理去做安全审查？handle = await rlm("Review the auth flow", name="auth-reviewer")。文件、shell、技能、子代理、上下文管理，全部是 Python 里的变量、函数与调用。这就是它所说的 RLM（Recursive Language Model，递归语言模型）：提示词即变量，工具调用即函数调用，而 REPL 是持久的。

第二个创新关乎时间。大多数 Agent 的能力在每次会话结束时清零：学到的教训、磨出来的工作流、验证过的套路，统统随聊天窗口关闭而蒸发。Prime Agent 的 Continual Harness（持续 harness）把补充提示词、记忆、技能描述和子代理规格存成持久状态，让 Agent 可以通过 /refine 命令对它们做小的、有证据支撑的更新——基础系统提示词永远不可变，每次更新都有快照可以回滚。配合把技能做成可安装的 Python 包，有用的工作模式可以沉淀成可执行的能力，活过任何一次会话。

于是这本书的核心问题是：

当「一切皆程序」——执行是代码、子代理是调用、上下文是变量——一个生产级 Agent 的内核会长成什么样？它要付出什么代价，又能换回什么？

与前作的关系：站在 pi 的肩膀上

Prime Agent 不是从零写起的。它的 README.md 明确致谢：

Our agent and TUI is built on top of pi. We thank the authors of pi for their valuable work.

它的代码库就是 pi-mono 的派生：同样是 ai / agent / tui / coding-agent 四个包的 monorepo，同样是那套统一多提供商的流式 API、两层嵌套的 Agent 循环、字符串差分渲染的终端 UI。《Pi Agent 源码解析》覆盖过的许多机制——pi-ai 的提供商抽象、agent-loop 的续接/停止决策、pi-tui 的逐行差分——在这里依然成立。把本书当作那本书的第二篇来读是合适的：底座相同，执行哲学截然不同。

因此本书采取这样的策略：继承的部分快速带过，创新的部分深挖。第 2 章用一章的篇幅交代 pi 的血统——那些被保留、被包装、被替换的机制——然后全书的重心压在了 Prime 真正新增的东西上：

维度pi（上一本书的对象）Prime Agent（本书的对象）
模型如何行动结构化 JSON 工具调用（read/edit/bash…）在持久 IPython 里写 Python 代码，唯一内置工具是 ipython
子代理扩展可自行实现；核心无内置rlm(...) 一等公民：函数调用派生真实子会话，递归可配置
代理间通信无agent_message 直接互发消息，不经用户路由
系统改进TypeScript 扩展系统（开发者写代码）/refine：模型自己给 harness 写经验（有证据、可回滚）
技能skills：markdown 指令skills 是可安装的 Python 包，模型 import 后直接调用
会话寿命终端关闭即结束daemon 托底：detach/reattach、goal、heartbeat、cron、自主模式
上下文状态消息数组 + 会话树消息 + kernel 变量空间：压缩杀不死的 Python 状态

一句话概括差异：pi 把复杂性挡在核心之外，Prime 把执行搬进解释器之内。

黄金路径：一次 prompt 的旅程

先建立一条贯穿全书的路径。当你在项目目录里敲下 prime-agent，输入「修复 auth.ts 里的空指针 bug」，请求会这样流过整个系统：

图 1：一次 prompt 的黄金路径。从会话队列往后，无论 prompt 来自用户、心跳、计划任务、目标续跑还是另一个 agent，走的都是同一条执行与持久化路径。

这条路径上的每一段都是后续某一章的放大：

  • TUI 与执行为何分离、断线后画面如何恢复 → 第 15 章、第 16 章
  • daemon 如何拥有进程拓扑、supervisor 与 worker 各管什么 → 第 14 章
  • AgentSession 如何编排一轮对话、队列与事件如何流动 → 第 11 章
  • 模型为何只会输出一种工具调用、IPython cell 如何执行 → 第 4 章
  • kernel 进程从哪来、Python 端预装了什么 → 第 3 章
  • 「类型化宿主请求」如何跨越 Python/TypeScript 边界 → 第 5 章
  • rlm(...) 派生的子会话去了哪里 → 第 6 章
  • 这一轮对话如何写进会话存储 → 第 11 章、第 12 章

代码组织：四个 TypeScript 包 + 一个 Python 运行时

Prime Agent 的仓库由四个 TypeScript 包和一个 Python 包组成。理解它们各自的职责与边界，是理解整个系统的前提：

图 2：代码组织。上三层继承自 pi-mono；coding-agent 是 Prime 改造最重的一层，而 prime-agent-runtime 是整个 RLM 的 Python 侧——一个新的维度。
位置一句话职责对应章节
packages/ai统一多提供商 LLM 流式 API（继承自 pi，几乎未动）第 2 章
packages/agentAgent 循环与工具执行内核（继承，被 RLM 重新包装）第 2 章
packages/tui自研终端 UI 库：字符串差分渲染（继承）第 2、16 章
packages/coding-agentprime-agent 命令本体：会话、kernel、harness、daemon、全部模式第 3–16 章
prime-agent-runtimePython 侧 RLM harness：rlm 对象、技能基座、MCP 桥第 3、5、6 章

值得注意的不对称：packages/agent 里那个干净的两层循环还在，但它现在驱动的是一个几乎只暴露单一工具的系统——循环的复杂性没变，工具的含义变了。这正是第 2 章的切入点。

全书结构

全书六个部分。第一部分建立全景；第二部分是本书的心脏，拆解 RLM 的五个层次；第三部分讲 harness 如何变得可以改进；第四部分讲会话如何跨越时间与压缩存活；第五部分讲进程架构与界面；第六部分是结语。

第一部分 · 总览

在深入任何机制之前，先看清整个系统的形状与它的血统。

  1. 01架构总览：把模型放进 REPL进程拓扑、两条主线、与三种 agent 范式的对照
  2. 02pi 的血统：被包装的循环继承的四包、agent-loop 现状、单一工具化的转向

第二部分 · RLM

提示词即变量，工具调用即函数调用——自内而外拆开这个持久 REPL。

  1. 03持久 IPython 内核fork-server、引导脚本、崩溃恢复、状态快照
  2. 04ipython：唯一的内置工具工具定义、执行管道、输出截断、%%bash
  3. 05宿主桥：跨越边界的类型化请求host_request 的端到端旅程与权限边界
  4. 06rlm()：作为函数调用的子代理admission handle、子注册表、继承与递归深度
  5. 07代理间直接通信agent_message、agent-observe、上下文树与用量归属

第三部分 · Continual Harness

让系统记住、沉淀、并且谨慎地改进自己。

  1. 08系统提示词与资源装配不可变基座、资源加载器、RLM 教学提示词
  2. 09/refine：能自我改进的 harness证据支撑的更新、快照与回滚、refinement 历史
  3. 10可执行技能与包管理器SKILL.md、Python 包安装、skill-creator

第四部分 · 会话与长任务

有用的工作要跨越许多轮次——甚至跨越终端的死亡。

  1. 11AgentSession：中央编排器与会话持久化400KB 的心脏、prompt 生命周期、JSONL 会话格式
  2. 12压缩：在遗忘中保持记忆触发条件、切点、kernel 状态如何幸免、分支摘要
  3. 13目标、心跳、计划任务与自主模式goal、heartbeat、cron-jobs、autonomous 与质量门

第五部分 · 进程架构与界面

终端只是窗口；执行属于守护进程。

  1. 14守护进程与会话 worker进程拓扑、daemon 协议、能力协商、崩溃恢复
  2. 15AgentConnection：可重连的执行边界快照、generation、重放、detach/reattach
  3. 16RLM 的终端界面ipython-cell 渲染、agents-view、Prime 的 TUI 增量

第六部分 · 结语

  1. 17结语：可编程性的赌注架构赌注盘点、可迁移的模式、未尽的代价

代码引用约定

  • 书中所有文件路径均相对于 prime-agent-src/ 目录（即 Prime Agent 仓库的根）。例如 packages/coding-agent/src/core/kernel/index.ts 指 prime-agent-src/packages/coding-agent/src/core/kernel/index.ts。
  • 代码片段为便于讲解可能省略部分类型标注或分支，但函数名、类型名、字段名与文件位置均与源码一致，可直接检索核对。
  • 中文行文；代码、标识符、文件路径、CLI 命令保持英文。
  • 分析基于的版本为 monorepo 各包 v0.7.2。

适用人群

  • 构建 Agentic 系统的工程师——想看「一切皆程序」路线如何落地：持久 REPL、宿主桥、递归子代理都是可迁移的模式。
  • 对长时运行 Agent 感兴趣的团队——daemon 托底、目标与心跳、有预算约束的自主模式，是面向研究评估与后台工作的完整答案。
  • 读过《Pi Agent 源码解析》的读者——本书是它的直接续篇：同样的底座，截然不同的执行哲学。

免责声明

本书为独立的技术分析，纯属教育目的。Prime Agent 是其维护者的产品，本书与其无关，未获背书或赞助。书中观点为作者基于源码的解读，如有错漏，以源码为准。