inkreach-agent/docs/pi-sdk-notes.md

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 应用的标准路径）

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（当前会话内分支）