第一部分 · 总览
第 1 章：架构总览——把模型放进 REPL
三个问题：如何行动，如何记住，如何活得久
三个问题
任何一个生产级 Agent 都要回答三个问题。它给出的答案决定了它的架构形状：
- 模型如何行动？——工具调用的形态：结构化 JSON，还是代码？能力是枚举出来的工具表，还是一个可编程的环境？
- 系统如何记住？——经验的去向：随会话蒸发，还是沉淀为某种可改进的持久状态？
- 会话如何活得久？——执行的寿命：绑定在终端上，还是能脱离界面、跨越断线、被定时唤醒？
Claude Code 与 pi 对第一个问题的回答相同（结构化 JSON 工具调用），因此它们的架构差异主要体现在后两个问题上。Prime Agent 把第一个问题也重新回答了一遍——然后发现后两个问题的答案必须跟着重写。这就是它的全部架构动机。
它的答案写在 README 的第一屏：
Recursive Language Model（RLM） 把上下文当作变量（prompt-as-a-variable），把递归子代理这类工具当作函数调用（programmatic tool/sub-agent calling），一切发生在一个持久 REPL 里。
Continual Harness 把补充提示词、记忆、技能描述、可复用子代理规格存成持久状态，让 Agent 通过小的、有证据支撑的更新去精炼它们。
本章先把这两根支柱和托起它们的进程架构摆在纸上；后续每一章都是对图中某条边的放大。
两根支柱，一个底座
轴一：RLM——一切皆程序
RLM 的完整定义留给第二部分，这里只立骨架。它把传统 Agent 的三个部件逐一翻译成了程序概念：
| 传统 Agent | RLM 的翻译 | 后果 |
|---|---|---|
| 上下文窗口里的文本 | 变量（prompt-as-a-variable） | 大数据不进提示词，进 Python 对象；上下文保持聚焦 |
| 工具调用（JSON） | 函数调用（programmatic tool calling） | 文件/shell/技能/子代理全部是 kernel 里的名字；第 4、10 章 |
| 子代理机制（Task 工具等） | 递归调用（await rlm(...)） | 子代理是函数返回值可预期的调用，但永不返回答案；第 6 章 |
| 工具执行环境 | 持久 REPL（IPython kernel） | 状态跨轮次存活，跨会话可快照复活；第 3 章 |
注意这张翻译表的代价栏：持久 REPL 需要一个真实的长寿命进程（进程管理、崩溃恢复、冷启动优化）；「永不返回答案」需要另一套结果通道（agent 间消息）；函数调用需要跨越 Python/TypeScript 边界的权威划分（宿主桥）。RLM 的每一项简洁都是用一处新的复杂性换来的——这本书的大部分章节都在讲那些换出去的复杂性。
轴二：Continual Harness——可以改进的记忆
harness 指 Agent 的「挽具」：系统提示词、资源、技能这些约束与增强模型行为的装配物。Prime 把它切成两层：
- 不可变基座——基础系统提示词。
/refine永不改写它。 - 可变持久层——补充提示词（prompt notes）、记忆（memories）、技能描述、子代理规格。四类条目存成 JSON 状态账本（
rlm/harness.py的HarnessState），会话本地与全局两级，跨进程按 mtime 同步。
改进的入口是 /refine：审阅当前轨迹，产出「小的、有证据支撑的」更新，每次记录在案、快照可回滚。技能则是更重的沉淀形态——可安装的 Python 包，模型 import 后直接调用（第 10 章）。第三部分讲这条轴的全部机制。
底座：daemon 化的寿命
前两根轴都要求会话寿命超过终端：harness 的积累要跨会话，子代理要能在父会话断线后继续被寻址。Prime 的答案是把执行整体搬进守护进程：
- 终端只是客户端——渲染与键盘输入，不拥有任何执行状态；
- daemon supervisor 负责发现、路由、连接管理；
- 每棵会话树住在一个独立的 session worker 进程里；
- 心跳、计划任务、持久目标、自主模式让会话被时间唤醒而不只是被用户唤醒。
第五部分拆解它。现在先看它落在磁盘与进程上的样子。
进程拓扑
一次常规交互会话涉及的进程如下：
prime-agent attach 随时接回。worker 与 kernel 是独立进程——为了生命周期隔离与恢复，不是安全沙箱（README 原话强调）。五条边界值得记住，后面每一章都会踩在其中某条上：
- client ↔ supervisor：版本化协议 + 能力协商。客户端声明能力（
attach_snapshot、event_sequence…），服务端宣告能力（model_catalog、heartbeat_management…），命令发送前逐条校验。第 14 章。 - supervisor ↔ worker：一个 worker 拥有一棵 root 会话树（root session + 全部 RLM 后代 + scheduler + kernels）。私有 socket，二进制分帧，supervisor 只读路由头转发负载。第 14 章。
- worker（TS）↔ kernel（Python）：Jupyter 协议 over ZeroMQ。TS 独占策略、凭据、转录、调度；Python 是模型的编程面。第 3、5 章。
- 会话 ↔ 磁盘：JSONL 转录 + artifacts 目录。子代理注册表、kernel 快照、harness 状态都在会话的目录树下——作用域跟随转录。第 11 章。
- agent ↔ agent：不经用户、不经中心调度，家族可达域内直接投递消息。第 7 章。
所有权地图：什么归 TypeScript，什么归 Python
RLM 最容易让人误解的地方是「Python 是不是一切」。不是。官方架构文档的第一句就把边界画死了：
"Prime Agent separates terminal presentation, process coordination, agent execution, model-facing Python, and persisted state."
具体的所有权划分：
| 归 TypeScript 宿主 | 归 Python kernel |
|---|---|
| provider 调用、流式解析、重试 | 模型生成的代码执行 |
| 转录写入、会话分支、压缩 | 工作变量、导入、数据对象 |
| 凭据（auth store 不进 kernel） | 技能的可调用接口 |
| 子代理生命周期、注册表权威 | 子代理的派生请求 |
| goal/heartbeat/cron/autonomous 状态机 | 对上述状态机的 host request |
| worker 路由、租约、崩溃恢复 | — |
一句话：Python 是面向模型的编程面，TypeScript 是面向正确性的权威面。kernel 里跑的代码能以用户权限做任何事（信任模型见 README 的警告），但「会话状态机往哪走」从来不是它说了算。这条边界的工程实现——typed host request——是第 5 章的主题。
代码地图
序言给过了包级视图，这里给出 packages/coding-agent 内部的地图——全书 90% 的戏份在这个包里：
| 目录 | 内容 | 章节 |
|---|---|---|
src/core/kernel/ | KernelManager、fork-server、boot-gate、venv 引导、状态快照 | 第 3 章 |
src/core/tools/ | ipython 工具与引导 cell（其余工具大多只剩辅助角色） | 第 4 章 |
src/core/rlm-runtime.ts | rlm.* host request 的验证与类型 | 第 5、6 章 |
src/core/agent-session.ts（11,289 行） | 中央编排器：队列、转录、压缩、goal、RLM、refine | 第 11–13 章 |
src/core/refinement/ | /refine 的更新机制 | 第 9 章 |
src/core/skills.ts + package-manager.ts | 技能发现、Python 包安装 | 第 10 章 |
src/core/compaction/ | 压缩与分支摘要 | 第 12 章 |
src/core/goals.ts / cron-jobs.ts / autonomous.ts | 长任务原语 | 第 13 章 |
src/modes/daemon/ | supervisor、worker、协议、连接、恢复 | 第 14、15 章 |
src/modes/interactive/ | TUI（含 IPython cell 渲染、agents-view） | 第 16 章 |
skills/（包根目录） | 内置 Python 技能：goal、edit、compact、agent-message、refine、websearch… | 第 10 章 |
加上仓库根部的 prime-agent-runtime/——那个 32KB 的 harness.py 与 rlm 包——就是全部战场。
与三种范式的对照
把 Prime 放进坐标系里。第一列是它的直系上游，后两列是另外两种流行形态：
| 维度 | pi（上游） | Claude Code（综合体） | Prime Agent |
|---|---|---|---|
| 执行形态 | JSON 工具调用 | JSON 工具调用 | 持久 REPL 里的 Python 代码 |
| 工具面 | 七个内置工具 | 四十多个工具 + MCP | 一个工具（ipython）+ 技能即包 |
| 子代理 | 无内置 | Task 工具（阻塞返回结果） | rlm()（准入即返回，结果走消息） |
| 自我改进 | 无 | 无（CLAUDE.md 靠人写） | /refine（模型写，证据支撑，可回滚） |
| 会话寿命 | 终端内 | 终端内（+后台任务受限） | daemon 托底：detach/reattach/心跳/计划 |
| 复杂性策略 | 挡在核心外 | 固化进单体 | 推进解释器，用边界管住 |
最后一行是全书的主线表述：pi 把复杂性挡在核心之外，Claude Code 把复杂性固化进单体，Prime Agent 把复杂性推进解释器之内，再用一条类型化的边界管住它。三种策略没有高下——但它们各自需要的机制完全不同，这本书讲的是第三种的全部机制。
如何读这本书
第二部分（第 3–7 章）自内而外拆 RLM：kernel 进程 → ipython 工具 → 宿主桥 → 子代理 → 消息通信。这是本书的心脏，也是 Prime 区别于一切既有 Agent 的部分。
第三部分（第 8–10 章）转向时间轴：系统提示词如何装配，/refine 如何让 harness 变好，技能如何沉淀成可执行包。
第四部分（第 11–13 章）讲会话如何扛住长度：400KB 的中央编排器、压缩、goal/heartbeat/cron/autonomous。
第五部分（第 14–16 章）讲进程架构与界面：daemon、AgentConnection、TUI 的 RLM 增量。
如果你只关心「Prime 新在哪」，从第 3 章直接读起，第 2 章的 pi 血统可以后补。
总结
Prime Agent 的架构可以压缩成三句话：模型住在一个持久 REPL 里，以代码为唯一行动方式（RLM）；系统的经验以受控的方式沉淀进可回滚的持久层（Continual Harness）；执行属于守护进程，终端只是窗口（daemon 化）。三条轴互相需要：没有 daemon 的寿命，积累无从谈起；没有宿主桥的边界，「Python 里什么都能干」会变成「Python 里什么都可能失控」。
下一章先回头看清来路：这个 fork 从 pi 继承了什么，包装了什么，替换了什么。