返回课程首页

第 30 章

选择正确的集成层次

比较 pi-ai、agent-core、Harness、SDK 与 RPC。

源码基线：Pi v0.82.0 · commit 518855d

现在开始把 Pi 嵌入桌面 Agent。Pi 不是单一入口，而是一组由低到高的层：

flowchart TD
    AI["pi-ai<br/>模型与流"] --> CORE["pi-agent-core<br/>Agent Loop + Tool"]
    CORE --> H["AgentHarness<br/>Session/Resource Hooks"]
    CORE --> SDK["Coding Agent SDK<br/>完整 AgentSession"]
    SDK --> RPC["RPC Mode<br/>进程协议"]

越高层，现成功能越多；越低层，产品自由度越高。

1. 先问五个问题

  1. 只要一次模型生成，还是需要 Tool Loop？
  2. 是否需要 Session Tree、Compaction、Queue？
  3. 是否需要 Skills、Extensions、Package/Trust？
  4. Agent 能否与桌面 UI 同进程？
  5. 谁负责 Crash Isolation 与 Protocol Version？

答案会直接决定依赖层。

2. 第一层：只使用 pi-ai

pi-ai 负责：

  • Provider/Model 类型；
  • Message/Content；
  • Streaming Event；
  • Usage；
  • Provider Auth/Request；
  • Tool Schema 的模型协议表示。

你直接准备 Model、Context 和 Stream Options，再消费 Assistant Stream。

它不替你提供：

  • 多 Turn Tool Loop；
  • Tool Execute；
  • Session Persistence；
  • Skill/Extension；
  • Queue/Compaction；
  • Desktop State。

3. pi-ai 适合什么

适合：

  • 文本改写；
  • 单轮总结；
  • 应用内 Copilot 的一次生成；
  • 自己已有 Workflow Engine；
  • 需要完全掌控 Provider Payload。

不适合直接承担一个完整桌面 Coding Agent，除非你愿意自己实现 Loop、Tool、Session 与 Recovery。

4. 第二层：pi-agent-core

Agent 把模型流与 Tool Execution 串成 Loop：

Context
→ Model Stream
→ Assistant Tool Call
→ Validate/Execute Tool
→ Tool Result
→ 下一 Turn
→ Final Assistant Message

它提供 Agent State、Tool、Steer/Follow-up、Abort、Event、Context Transform、Before/After Tool Hook。

它仍不等于 coding-agent 的 AgentSession：没有 .pi Resource Discovery、Extension Loader、 Package、项目 Trust 和完整 JSONL Session 产品语义。

5. pi-agent-core 适合什么

适合：

  • 自己有数据库和对话存储；
  • 只需要通用 Tool Agent；
  • 想自定义所有资源与权限；
  • 不想引入 Coding Agent 的项目约定；
  • 服务端 Worker 或嵌入式 Workflow。

代价是宿主自己管理：

  • Model/Auth；
  • Session；
  • Resource；
  • Retry/Compaction Policy；
  • Extension-like Middleware；
  • UI Projection。

6. 第三层：AgentHarness

packages/agent 的 AgentHarness 在 Agent Core 上增加：

  • Prompt/Skill/Template 调用；
  • 可注入的 skills 与 promptTemplates Resource；
  • Session Store；
  • Compaction；
  • Branch Navigation/Summary；
  • Turn-level Hook；
  • Tool Context；
  • 标准化 Error/Phase。

它是通用宿主层，不是 coding-agent Test Suite 中也叫 Harness 的内部测试对象。

7. AgentHarness 的边界

它的 Resource 类型只包含 Skill 与 Prompt Template。packages/agent 提供 loadSkills()、loadPromptTemplates() 和 Formatter；宿主选择目录与 ExecutionEnv，调用 Loader，再通过构造参数或 setResources() 注入。它不自动拥有 coding-agent 的：

  • DefaultResourceLoader；
  • .pi/.agents 扫描；
  • Extension System；
  • Pi Package；
  • Project Trust；
  • Built-in Coding Tools；
  • coding-agent AgentSession Event。

例如模型自动发现 Skill，宿主必须在 System Prompt Callback 中调用 Formatter，并提供文件 读取 Tool；显式 harness.skill() 则直接注入已经加载的 Skill Content。

8. AgentHarness 适合什么

适合：

  • 需要 Session/Compaction，但不需要 coding-agent 约定；
  • 只需 Skill/Prompt Template，并愿意自己控制它们的发现与加载；
  • 想要比 Agent Core 更高层、比 Coding SDK 更小；
  • 构建非 Coding Domain 的桌面 Agent。

它要求你理解自己的 Storage、Resource、Prompt 和 Tool Context Contract。

9. 第四层：Coding Agent SDK

createAgentSession() 组合：

  • Model Runtime/Auth；
  • Agent Core；
  • AgentSession；
  • SessionManager；
  • SettingsManager；
  • ResourceLoader；
  • Built-in Tools；
  • Skills/Templates/Context Files；
  • Extensions；
  • Retry/Compaction/Queue；
  • 可由宿主接线的 Project Trust 相关 Resource Reload 能力。

简单 createAgentSession() 不会自动组织完整 Trust Flow：默认 Settings 状态会直接加载。 宿主可以预设 Settings Trust；也可以调用 createAgentSessionServices({ resourceLoaderReloadOptions: { resolveProjectTrust } }) 后再调用 createAgentSessionFromServices()。另一种方式是自行创建带 Resolver Reload 的 DefaultResourceLoader，再作为 resourceLoader 传给 createAgentSession()。注意 resourceLoaderReloadOptions 不是 createAgentSession() 自身的参数。Built-in Main/RPC 才组装 Trust Store、Pre-trust Extension 与决策流程。

这最接近本书桌面 Agent 示例需要的能力。

10. Coding SDK 不等于 UI

SDK 返回运行时对象和 Event，使用 API 时不要求启动 Pi 的终端界面。但 @earendil-works/pi-coding-agent 是 Node Package，要求 Node >=22.19.0；当前 Package 仍声明 @earendil-works/pi-tui Dependency，所以 Headless 使用不等于安装依赖中完全没有 TUI Package。

桌面应用可以：

Electron Main / Node Sidecar
→ Desktop Store/Bridge
→ AgentSession SDK
→ Pi Runtime

Electron Main 可直接调用 SDK；普通 Tauri/SwiftUI Native Process 需要 Node Sidecar + RPC 或其他 Bridge，不能直接运行 Node Package。

你仍要实现：

  • Window/Multi-session State；
  • Desktop Approval Dialog；
  • File Picker；
  • OS Sandbox；
  • Crash Recovery；
  • Update；
  • Telemetry。

11. createAgentSession 与 Runtime Factory

简单嵌入使用：

const { session } = await createAgentSession({
  cwd,
  sessionManager,
});

复杂的 CWD/Session Replacement 可使用：

  • createAgentSessionServices()；
  • createAgentSessionFromServices()；
  • createAgentSessionRuntime()；
  • AgentSessionRuntime。

后者正是 Built-in Modes 使用的层：Factory 固定 Process-wide Input，并按有效 CWD 重建 CWD-bound Services 与 Session。

12. 第五层：RPC Mode

RPC 把 coding-agent 放进独立 Process：

flowchart LR
    UI["Desktop UI Process"] <-->|"stdin/stdout JSONL"| P["Pi RPC Process"]
    P --> M["Providers"]
    P --> T["Local Tools"]

UI 发送 Command，Process 返回 Response 与异步 Event。Dialog 类 Extension UI 请求也通过 Protocol 往返。

13. RPC 适合什么

适合：

  • 桌面语言不是 TypeScript；
  • 希望 Agent Crash 不带崩 UI；
  • 想独立升级/重启 Agent Worker；
  • 需要独立 Crash/Address-space/Lifecycle Boundary，并计划由宿主另加权限限制；
  • 多前端复用同一 Protocol Client。

代价：

  • JSONL Protocol 与 Request ID；
  • Event Ordering/Backpressure；
  • Child Lifecycle；
  • Restart/Rehydrate；
  • Binary/large payload handling；
  • Version Negotiation。

当前 RpcCommand/RpcResponse 没有内置 Protocol Version/Handshake 字段；版本固定或兼容协商 必须由宿主在外层实现。

14. RPC 不是完整沙箱

子进程默认仍可能继承：

  • 用户权限；
  • Environment；
  • Filesystem；
  • Network；
  • Working Directory。

Process Separation 改善 Crash Isolation，不自动形成 Least Privilege。需要 OS Sandbox、Container Profile 或 Brokered Tool 才能限制权限。

15. 五层对照

能力 pi-ai agent-core AgentHarness Coding SDK RPC
Provider Stream ✓ ✓ ✓ ✓ ✓
Tool Loop 自建 ✓ ✓ ✓ ✓
Session/Branch 自建 自建 ✓ ✓ ✓
Generic Skill/Template 自建 自建 ✓ ✓ ✓
coding-agent Resource — — — ✓ ✓
Extension/Pi Package — — — ✓ ✓
Project Trust — — — 宿主接线 Built-in RPC 启动流
同进程类型调用 ✓ ✓ ✓ ✓ —
Process Isolation — — — — ✓

表中的 “✓” 表示该层直接提供，不表示宿主无需配置。

16. 按产品复杂度选择

单次 AI 功能

选 pi-ai。

自有 Workflow/Storage 的 Tool Agent

选 pi-agent-core。

非 Coding Domain，但需要 Session/Compaction

选 AgentHarness。

需要 Skills、Extensions、Session、Coding Tools 的桌面 Agent

优先 Coding Agent SDK。

跨语言或需要 Worker Crash Isolation

选 RPC，或在 SDK 外自己建立 Process Protocol。

17. 本书的选择

本书主线选择 Coding Agent SDK：

Desktop UI
→ Application State Adapter
→ AgentSession
→ Agent Core / pi-ai

理由：

  • 要完整讲 Skills；
  • Extension 是核心特色；
  • 要 Session、Compaction、Queue；
  • 不使用 Pi TUI；
  • 桌面 UI 需要直接订阅 Event。

第 32 章再把同一能力迁到 RPC Process。

18. 什么时候不要直接选最高层

如果产品：

  • 不需要 Filesystem/Coding Tool；
  • 已有稳定 Session Backend；
  • Extension Package 不是需求；
  • 强制使用自己的 Resource/Policy；
  • Bundle Size 与 Surface Area 极敏感；

Coding SDK 可能过重。高层不是“更先进”，只是做了更多产品决策。

19. 迁移成本

从低到高：

  • 可以逐步获得 Session/Resource/Extension；
  • 但已有自己的类型和 Lifecycle 需要适配。

从高到低：

  • 会失去 Default Behavior；
  • 必须重建 Retry、Compaction、Trust、Package 等。

决定前列出“必须保留的行为”，不要只比较 API 数量。

20. 常见误区

“pi-ai 就是 Agent Framework”

它是模型/Provider 层，不负责完整 Tool Agent。

“AgentHarness 自动继承 coding-agent Extensions”

错误。它是通用 Harness。

“Coding SDK 必须使用 Pi TUI”

错误。SDK 可由桌面宿主直接消费。

“RPC 天然安全”

错误。它提供进程边界，不自动降低系统权限。

“最高层总是最省事”

只有当它的产品约定与你一致时才省事。

21. 本章小结

  • pi-ai 负责模型与流；
  • pi-agent-core 负责通用 Agent Tool Loop；
  • AgentHarness 增加通用 Session/Resource/Compaction；
  • Coding Agent SDK 提供 Skills、Extensions、Package、Trust 和完整 AgentSession；
  • RPC 把 Coding Agent 放进独立 Process，并用 JSONL 协议连接；
  • Process Separation 不等于 Permission Sandbox；
  • 本书桌面主线选择 SDK，跨语言/崩溃隔离场景再选 RPC；
  • 选择层次的核心是产品需要哪些既有行为，以及愿意自己维护哪些边界。

22. 自测

  1. pi-ai 不提供哪三类 Agent 能力？
  2. agent-core 与 AgentSession 的主要差别是什么？
  3. AgentHarness 为什么不会自动发现 coding-agent Skill？
  4. Coding SDK 为桌面 Agent 省下哪些基础设施？
  5. Coding SDK 是否要求使用 Pi TUI？
  6. RPC 带来什么隔离，又缺少什么安全边界？
  7. 一个已有自有 Session Backend 的 Tool Agent 应优先考虑哪层？
  8. 为什么最高层不一定总是最佳选择？