自扩展 Agent
的 monorepo

9 包 monorepo 的解剖

打开仓库第一眼就该注意到的事：根目录有 9 个 packages/ 子目录，彼此通过 "workspace:*" 互相依赖。Pi 不是把 Agent 塞进一个进程——它把 Agent 拆成 9 个独立 npm 包（其中 packages/storage/ 本身不是包，真正的存储包在 packages/storage/sqlite-node/），每个可以单独发布、单独嵌入。

数字化的项目形状

读完这份报告，你会看到 三个在前面所有 Agent 项目里都没有的设计：自扩展 Extensions、协议驱动进程分离、差分渲染 TUI。这三个加起来，让 Pi 成为"Agent 工程的另一种可能性"。

38 Provider 的统一接口

Pi 支持 38 个 Provider（OpenAI/Anthropic/Google/Bedrock/DeepSeek/Groq/Kimi/Moonshot/ZAI/Xiaomi…），但不依赖 Vercel AI SDK。它的 pi-ai 包是完全独立实现——每个 Provider 的 SDK 适配自己写，主 bundle 不含任何 SDK。

lazyStream：按需加载 SDK

packages/ai/src/api/lazy.ts:46 的 lazyStream 是 Pi 性能优化的核心：

// 同步返回 stream，异步在背后跑 setup
export function lazyStream<T>(
  setup: () => Promise<StreamFunction>,
): StreamFunction {
  return async function*(model, context, options) {
    const real = await setup()  // 动态 import() SDK
    yield* real(model, context, options)
  }
}

lazyApi()（lazy.ts:68）包装动态 import()——Provider 实现按需加载。主 bundle 不含任何 SDK，anthropic-messages.ts 高达 1351 行（含 @anthropic-ai/sdk 调用、cache_control、thinking），但只有用到时才加载。

三个最独特设计

代价与收益

pi-protocol：自定义二进制线协议

pi-protocol 包（12 个 TS 文件）定义了 Pi 的 wire format。不是 JSON-RPC，也不是 MCP——它是自定义的请求/响应 + 事件流协议，管 session 生命周期（create/attach/detach/abort）和 transcript 流式同步。

flowchart LR
    subgraph WIRE["线协议 = 长度帧 + CBOR"]
        LEN["4 字节大端
长度前缀"]
        CBOR["CBOR 编码
payload"]
    end
    subgraph SCHEMA["TypeBox 校验"]
        HELLO["ClientHello / ServerHello
（握手首帧）"]
        REQ["RequestEnvelope
（id + command）"]
        RES["ResponseEnvelope
（ok/error）"]
        EVT["EventEnvelope
（server/session snapshot）"]
    end
    subgraph CMD["命令"]
        C1["list / create / attach"]
        C2["detach / prompt / steer"]
        C3["abort / set_model / set_thinking"]
    end
    WIRE --> SCHEMA
    SCHEMA --> CMD

核心数据结构

• TranscriptItem（schemas.ts）：user / assistant / tool 三类；assistant 有 streaming / complete / error / aborted 四态。
• TranscriptProgress（schemas.ts）：item_started / assistant_delta / item_updated / item_finished，增量流式。
• SessionSnapshot（schemas.ts）：含 revision + transcript + queuedSteer——revision 用于客户端单调丢弃旧快照。

和 MCP 的关系：pi-protocol 是 Pi 自己的会话级协议，MCP 是工具调用协议——二者正交。pi-protocol 传输的 toolCall/tool transcript 项里才包含工具语义，但协议本身不规定工具发现/调用——那是 coding-agent 层的事。protocol/src/schemas.ts:381-447

多客户端 attach 同一 session

pi-server（packages/server/src/server.ts，399 行）实现 PiSessionBackend/PiSessionRuntime 接口，runtime 实际由 coding-agent 的 AgentSession 提供。多客户端 attach 同一 session是它最大的设计目的。

Session 租约模型

pi-client（packages/client/src/client.ts，433 行）实现了精巧的租约模型：

• createSession() → 独占租约（exclusive）：只有一个连接能操作
• attachSession() → 共享租约（shared）：多个连接可以同时订阅快照
• 引用计数 #sessionLeaseCounts：最后一个 release 时才发 detach 命令
• #sessionLeaseGenerations：detach 失败时标记 #sessionCleanupRequired，下次 acquire 前 #reconcileSessionCleanup 重试

Unix socket 而不是 HTTP 是有意为之——listener.ts:1-4 的 PiServerListener 只接受 Unix transport，Windows 直接抛错。传输层抽象为 ByteConnection（connection.ts），任何能给出有序字节流的传输都可接入。这让 Pi 可以未来扩展到 WebSocket、stdio、TCP——只需替换 transport，协议不变。server/src/transports/unix/listener.ts:22

双层 while 主循环

packages/agent/src/agent-loop.ts:155-275 的 runLoop() 是 Pi 的核心——一个双层 while(true) 循环，不是状态机也不是纯事件驱动：

flowchart TB
    A["外层 while(true)
处理 follow-up 消息"]
    A --> B["内层 while
(hasMoreToolCalls || pendingMessages.length > 0)"]
    B --> C["1. streamAssistantResponse()
→ pi-ai Models.streamSimple()
→ AssistantMessageEventStream"]
    C --> D{"2. 检查 stopReason"}
    D -->|error/aborted| E["立即终止"]
    D -->|length| F["截断保护：
failToolCallsFromTruncatedMessage()"]
    D -->|tool_use| G["3. executeToolCalls()
parallel: Promise.all"]
    G --> H["4. prepareNextTurn()
harness 钩子：
compaction + 刷 system prompt"]
    H --> I{"5. shouldStopAfterTurn()?"}
    I -->|是| J["退内层"]
    I -->|否| B
    J --> K["getFollowUpMessages()?"]
    K -->|有| A
    K -->|无| L["结束"]

与 Claude Code 的本质区别

AgentMessage：开放联合类型

packages/agent/src/types.ts:319 的 AgentMessage = Message | CustomAgentMessages[keyof ...] 是 Pi 与 Claude Code 最大的架构差异之一——通过 declaration merging 扩展自定义消息。

自定义消息类型

harness 注入了以下自定义消息类型（packages/agent/src/harness/messages.ts:54-61）：

convertToLlm：边界投影

packages/agent/src/harness/messages.ts:120 的 convertToLlm 函数是关键——它把这些自定义消息投影成 LLM 可懂的 user 消息或过滤掉。

这个设计的精髓：UI/存储能用富消息（带元数据、可交互、可分支），而 LLM 只看标准 user/assistant/tool 消息。中间通过 convertToLlm 做边界投影——不把内部表示泄漏给模型，也不让模型被迫理解私有协议。packages/agent/src/harness/messages.ts:120

三层状态管理

pi-agent-core 不是单层状态——它把状态分成三个抽象层级，每层关注不同的事：

flowchart TB
    subgraph L1["① AgentContext（types.ts:406）"]
        C1["纯快照
{systemPrompt, messages, tools}
每个 turn 都 snapshot"]
    end
    subgraph L2["② Agent 类（agent.ts:171）"]
        C2["MutableAgentState
系统提示 / 模型 / thinking
工具 / 消息 / isStreaming
tools & messages 用 getter/setter
拷贝写入（防外部 mutate）"]
    end
    subgraph L3["③ AgentHarness（agent-harness.ts:173）"]
        C3["在 Agent 之上叠加：
Session 持久化
compaction
skills 注入
prompt templates
provider hooks"]
    end
    L1 --> L2
    L2 --> L3

每个层级的取舍

Extensions 与 jiti 动态加载

packages/coding-agent/src/core/extensions/ 是 Pi 最具差异化的子系统（loader 713 行 / runner 1236 行 / types 1713 行）。

一个扩展长什么样

.pi/extensions/tps.ts（仓库内置的示例）就是一段普通 TS——它通过 jiti 被 loader.ts 动态 require，然后调用 ExtensionAPI.registerTool 注册一个 "tps" 工具。不需要打包、不需要 npm install、不需要重启——resource-loader.ts:reload() 会热重载。

Skills · Prompt Templates · Themes

.pi/ 目录除了 extensions/ 还有三个子目录——它们一起构成 Pi 的内容层。

Skills 加载机制

packages/coding-agent/src/core/skills.ts（487 行）实现完整流程：

1. 发现：loadSkillsFromDir（L168）递归扫描，遇到 SKILL.md 即视为 skill root 不再下钻
2. 解析：loadSkillFromFile（L277）用 parseFrontmatter 提取 name / description / disable-model-invocation
3. 冲突解决：user → project → path 优先级；同名产生 collision 诊断
4. 注入：formatSkillsForPrompt（L335）生成 <available_skills><skill>...</skill></available_skills> XML 块，指示模型用 read 工具加载 skill 文件

Skills 不是"自动调用"——是"告诉模型有哪些 skill 可用，让模型自己选择要不要 read"。disable-model-invocation=true 的 skill 不进提示，只能 /skill:name 显式调用。这种"模型自决"的注入方式比"自动注入"更安全——模型可以根据上下文判断是否需要某个 skill。packages/coding-agent/src/core/skills.ts:99-105

pi-tui：差分渲染

packages/tui/（74 个 TS 文件）是 Pi 自研的终端 UI 库。无 React、无 Virtual DOM、无 flexbox——组件就是 render(width): string[]，渲染靠逐行字符串 diff。

差分渲染算法

TuiMainScreen.doRender()（TuiMainScreen.ts:146）的核心算法：

1. render(width) 渲染全部组件为字符串行数组
2. 合成 overlays（compositeOverlays）
3. 提取 CURSOR_MARKER（APC 序列 \x1b_pi:c\x07）定位硬件光标用于 IME
4. 逐行 diff（L261-274）：遍历 previousLines vs newLines，找 firstChanged/lastChanged
5. 特殊路径：首帧 / 宽度变化 / 高度变化 / 内容缩过多 → fullRender(true) 全清
6. 增量写（L356-495）：用 \x1b[?2026h…\x1b[?2026l 包裹，computeLineDiff 算光标位移，只对 firstChanged..lastChanged 区间行写 \x1b[2K + 新内容
7. Kitty 图片特殊处理：expandChangedRangeForKittyImages 把图片占用的多行纳入 diff 范围

键盘处理

packages/tui/src/keys.ts（1401 行）同时支持：

• 传统转义序列（\x1b[A = Up）
• Kitty keyboard protocol（setKittyProtocolActive / isKeyRelease / isKeyRepeat）——区分按下/释放/重复

stdin-buffer.ts（434 行）把 stdin chunk 按 ESC 序列边界拆分成原子事件，避免半个 CSI 被分发。packages/tui/src/stdin-buffer.ts:1

SQLite 事件溯源

packages/storage/sqlite-node/（12 个 TS 文件）实现 session 持久化。用 Node 22+ 内置的 node:sqlite，无第三方原生依赖。

六张表

-- 001_initial.sql
CREATE TABLE sessions (
  id TEXT PRIMARY KEY,
  cwd TEXT NOT NULL,
  parent_session_id TEXT,
  active_leaf_id TEXT,
  metadata TEXT
);

CREATE TABLE session_entries (
  session_id TEXT NOT NULL,
  id TEXT NOT NULL,
  entry_seq INTEGER NOT NULL,
  parent_id TEXT,
  type TEXT NOT NULL,  -- message / thinking_level_change / model_change /
                     -- active_tools_change / compaction / branch_summary /
                     -- custom / custom_message / label / session_info / leaf
  timestamp INTEGER NOT NULL,
  payload TEXT NOT NULL,  -- JSON
  PRIMARY KEY (session_id, id)
);

CREATE TABLE session_sequences (
  session_id TEXT PRIMARY KEY,
  next_seq INTEGER NOT NULL
);

CREATE TABLE branch_entries (
  branch_id TEXT,
  entry_id TEXT,
  seq INTEGER,
  PRIMARY KEY (branch_id, entry_id)
);

CREATE TABLE session_materialized (
  session_id TEXT PRIMARY KEY,
  snapshot TEXT  -- 整体摘要
);

CREATE TABLE entry_materialized (
  session_id TEXT,
  entry_id TEXT,
  type TEXT,
  payload TEXT,
  PRIMARY KEY (session_id, entry_id)
);

并发控制：SerialOperationQueue（session-store.ts:45-60）串行化所有写，SqliteSessionConnection 每 session 缓存一个 writer 连接。PRAGMA journal_mode=WAL; synchronous=FULL; busy_timeout=5000（session-store.ts:33-37）。packages/storage/sqlite-node/src/sqlite/session-store.ts:33-60

分支 · fork · compaction

Pi 的 storage 不是简单的 CRUD——它把分支、fork、compaction 都做成 session 树操作。

与 Claude Code · CodePilot · open-design

与 Claude Code 的对比（最直接的对标）

与 CodePilot 的对比（同为多 Provider）

与 open-design 的对比（同为"宿主"形态）

设计哲学与取舍

Pi 的核心取舍

Pi 的独特贡献

给阅读者的建议

1. 想理解 Agent runtime 的抽象：先读 packages/agent/src/agent-loop.ts 的双层 while（ch6）——这是 Pi 的"心脏"
2. 想理解多 Provider 怎么统一：先读 packages/ai/src/api/lazy.ts 的 lazyStream（ch2）——按需加载是核心
3. 想理解协议设计：先读 packages/protocol/src/schemas.ts（ch4）——TypeBox 校验是契约的形态
4. 想理解 TUI 怎么做：先读 packages/tui/src/TuiMainScreen.ts 的 doRender()（ch11）——逐行 diff 是关键
5. 想理解自扩展：先读 packages/coding-agent/src/core/extensions/loader.ts（ch9）——jiti 是机制
6. 想理解持久化：先读 packages/storage/sqlite-node/src/sqlite/session-store.ts（ch12-13）——事件溯源 + 物化视图

Pi 不是 Claude Code 的复刻，也不是另一个"轻量级 Claude Code"。它是 Agent 工程的另一种可能性：把协议、运行时、UI、存储拆开，靠显式契约粘合。工程复杂度极高，但换来的是可组合性、可替换性、可观测性。