# pi SDK 集成笔记

> 来源：pi.dev 官方文档 + 仓库调研（2026-09-05）。
> ⚠️ 本文是二手摘要，**写代码前必须对照已安装包的 `.d.ts` 类型定义核对 API 签名**。

## 1. 包与运行时

- 包名：`@earendil-works/pi-coding-agent`（主包自带 SDK，无需单独安装）
- Node ≥ 22.19（Electron 37.6+ 主进程满足；系统 Node 仅跑构建）
- MIT 协议；monorepo 结构：`pi-agent-core`（agent 运行时）/ `pi-ai`（多 Provider LLM 统一接口）/ `pi-tui` / `chord` / `telemetry`

## 2. SDK 三段式（嵌入 Node 应用的标准路径）

```ts
const { session } = await createAgentSession({ /* options */ });
session.subscribe((event) => { /* 处理 text_delta 等 */ });
await session.prompt("...");
```

- `prompt()` 返回 Promise，完成后 resolve；流式期间可用 `steer()` / `followUp()` 排队插话。
- 事件流：`agent_start/end`、`message_update`（含 `text_delta` / `thinking_delta`）、`tool_execution_start/update/end`、`turn_end`、`queue_update`、压缩与自动重试事件。

## 3. 会话管理

- `SessionManager.inMemory()`（无持久化）/ `.create()` / `.continueRecent()` / `.open()`
- 会话是树结构，支持分支（`fork()`）；多会话动态替换用 `AgentSessionRuntime`（`newSession()` / `switchSession()` / `fork()` / `importFromJsonl()`，替换后需重新订阅）
- 持久化后端可插拔：官方 `session-backends/sqlite-node`（与我们本地 sqlite 方案契合）
- 本地文件布局（与 pi CLI / pi-web 共享）：`~/.pi/agent/sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl`

## 4. 模型与凭据

- 认证解析优先级：运行时 API key → `auth.json`（API key 或 OAuth）→ 环境变量 → 自定义 provider fallback resolver
- `setRuntimeApiKey()`（不落盘）、`InMemoryCredentialStore`、自定义 auth/models 路径、`PI_OFFLINE` 离线模式
- 内置 Provider：OpenAI、Anthropic、Google 等；自定义模型用 `models.json`，自定义 provider 支持实现自有 API 与 OAuth（为将来"服务器 LLM 代理端点"预留）
- 本机现状：`~/.pi/agent/` 已有 `auth.json` 与 `models-store.json`，应用零配置可直接复用

## 5. 定制点（SDK options）

| 维度 | 方式 |
|---|---|
| 系统提示 | `DefaultResourceLoader({ systemPromptOverride: () => "..." })` |
| 工具 | `tools` 白名单内置工具；`excludeTools` 排除；`noTools: "all"` 全关；`defineTool()` 经 `customTools` 注入 |
| 扩展 | `extensionFactories` 内联扩展（`pi.registerTool()` / `pi.on()` / 命令），支持命名与共享 eventBus |
| 模型 | `getModel()` 取内置模型；`models.json` 自定义；`thinkingLevel`、`scopedModels` |
| Skills/上下文/提示模板 | ResourceLoader 的 `skillsOverride`、`agentsFilesOverride`、`promptsOverride` |
| 设置 | `SettingsManager.inMemory()` / `.create()`，可覆盖压缩、重试等 |

## 6. 安全要点

- pi **无内置权限系统**，工具以进程用户权限执行。业务 agent 必须 `noTools` 或白名单收窄，能力全部走 `defineTool()` 自定义工具；本地文件类操作按需开启并配 `tool_call` 拦截。

## 7. 扩展（Extension）API 摘要

- 加载：`~/.pi/agent/extensions/*.ts`（全局）、`.pi/extensions/*.ts`（项目级，需 trust）、`pi -e ./x.ts`（临时）；jiti 加载 TS 免编译，`/reload` 热重载（SDK 路径用 `extensionFactories` 内联）
- 能力：`pi.on(event, handler)`（拦截 `tool_call`、改写 `input`、`before_agent_start` 注入上下文/改提示词）、`pi.registerTool()`（typebox 参数、流式进度 `onUpdate`）、`pi.registerCommand()`、`ctx.ui` 自定义交互、`pi.appendEntry()` 会话持久化、`pi.sendMessage()`
- 注意：自定义工具需手动截断输出（默认 50KB/2000 行）、`withFileMutationQueue()` 防并行写冲突

## 8. 备选集成模式

| 模式 | 用途 | 取舍 |
|---|---|---|
| SDK 同进程（主选） | 嵌入 Electron 主进程 | 类型安全、直接访问 agent state |
| RPC 模式（`pi --mode rpc`） | 子进程隔离 | 崩溃隔离好，但失去类型安全，自管 JSONL 协议 |
| JSON event stream | 结构化事件打印 | 观测/调试用 |

## 9. pi-web 可借鉴的实现细节

- WebSocket 事件以快照推送、60ms 节流（我们的 IPC 转发同样适用）
- 会话列表 UI 数据：运行状态、上下文用量、成本、压缩详情
- 双分支设计：New session（从历史消息建独立会话）/ Edit from here（当前会话内分支）