buchidonggua / dg-piagent

pi-agent SDK 开发指南

⚠‹VARIATION SELECTOR U+FE0F› 版本基线: 本 skill 的 API 描述已对齐到 pi-coding-agent v0.83.0。

遇 pi-ai import 失败时，先查 node_modules/@earendil-works/pi-ai/dist/compat.d.ts 的 export * 列表，确认符号归属哪个入口。

版本协议 ⭐

本 skill 核对到顶部基线版本（当前 v0.83.0）。涉及安装/升级 pi-agent 时遵循三步：

1. 默认对齐：引导安装一律用基线版本 npm install @earendil-works/pi-coding-agent@0.83.0，不装 latest——skill 的 API 描述精确核对到基线版本，装 latest 会立即漂移。场景文档里的安装命令同样以基线版本为准。
2. 升级前评估：当任务涉及安装/升级（或用户问版本）时，先跑 npm view @earendil-works/pi-coding-agent version 拿 latest 与基线对比。若不同，联网查该版本 CHANGELOG/release notes，从 SDK 二次开发角度评估（新功能 / 破坏性变更），给用户简短建议，由用户决定是否升级。日常开发（项目已装好）不触发。
3. 升级即更新 skill：若用户同意升到 X.Y.Z，安装后按 [skill-maintenance.md](references/skill-maintenance.md) 流程，对照新版 dist/**/*.d.ts + CHANGELOG 审查 skill 差异，产出更新清单，报用户确认后再改，并同步更新顶部基线版本号。

变更查阅渠道（第 2/3 步执行依据）：

时序关键：升级前 node_modules 仍是旧版，渠道①看不到新版内容，第 2 步必须用②（GitHub）。

Overview

pi-agent 是基于事件驱动的 Agent 开发框架(@earendil-works/pi-coding-agent)。核心心智模型:

createAgentSession()  ← 组装入口(Provider + 工具 + 资源)
       │
       ├── session.prompt(text)          ← 驱动 Agent 主循环
       │
       ├── session.subscribe(handler)    ← 外部订阅层
       │     多数事件与扩展层共有(turn_*/message_*/tool_execution_*/agent_start/agent_end/agent_settled)
       │     外部层独有: queue_update / compaction_* / session_info_changed 等 session 状态事件
       │
       └── 扩展(pi.on)                   ← 内部扩展层
             扩展独有(仅这 6 个 subscribe 收不到):
               context / tool_call / tool_result / before_agent_start / input / model_select

关键区分(最大集成坑): 有 6 个扩展独有事件——context / tool_call / tool_result / before_agent_start / input / model_select。
在 server 层用 session.subscribe 监听这 6 个会静默失败(handler 被调用但 type 分支永不命中,无报错)。
对策: 需要抓这 6 个事件的逻辑(日志/trace/拦截/抓这 6 个事件的数据落库)必须写成扩展走 pi.on。⚠‹VARIATION SELECTOR U+FE0F› 但注意——pi.on handler 被派发方 await，落库这类慢 I/O 必须 fire-and-forget（推队列后台写），否则阻塞 agent loop。若只需存 message_*/turn_*/tool_execution_* 等 subscribe 收得到的事件，落库优先走 session.subscribe（不 await listener，可直接 await 写库，零阻塞）。详见 [04-events.md 关键细节](references/sdk_doc/04-events.md#关键细节)。
详见 Common Mistakes 与 [sdk_doc/04-events.md](references/sdk_doc/04-events.md)。

⭐ v0.83.0 推荐：需要"agent 真正结束"信号时，订阅 agent_settled 替代 agent_end——前者保证所有 retry/compaction/queue 处理完才触发，每 prompt 一次，两层都派发。详见 [sdk_doc/04 坑 1](references/sdk_doc/04-events.md#坑-1不要把-agent_end-当成流程结束的唯一信号)。

When to Use

该用本 skill:

• 基于 pi-agent SDK 做 Agent 二次开发(Web 服务、CLI、定制化应用)
• 调用 createAgentSession / AgentSession / defineTool / pi.on 等 API

快速开始

npm install @earendil-works/pi-coding-agent@0.83.0

最简示例:

import { createAgentSession } from "@earendil-works/pi-coding-agent";

const { session } = await createAgentSession();

session.subscribe((event) => {
  if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
    process.stdout.write(event.assistantMessageEvent.delta);
  }
});

try {
  await session.prompt("What files are in the current directory?");
} finally {
  session.dispose();
}

完整场景: [scenarios/A01-minimal-startup.md](references/scenarios/A01-minimal-startup.md)

⭐ 二开起步检查清单

不管做什么 Agent，先过这几项（默认值都是 pi 编码助手的产品烙印）：

必改三项

• 系统提示词 → 默认硬编码 pi 人设（不覆盖会自称 "expert coding assistant operating inside pi"），必须覆盖 → [A03](references/scenarios/A03-system-prompt.md)
• 可用工具 → 默认 read/bash/edit/write 编码四件套；垂直 Agent 要换业务工具，bash 在多用户场景是安全口子 → [A04](references/scenarios/A04-tool-whitelist.md)
• 会话存储 → 默认落盘 ~/.pi/agent/sessions/（CLI 单用户设计）；Web 多用户必须 SessionManager.inMemory() + 自己落库 → [F01](references/scenarios/F01-session-persistence.md)

易踩坑：createAgentSession 传了 resourceLoader 就不自动 reload——用扩展（尤其扩展注册 provider）时必须自己 await loader.reload()，否则扩展 factory 不执行、provider 选不到 → [A06](references/scenarios/A06-load-extensions.md)

意图总表

按「我要做什么」找文件。场景编号保留在文件名,向后兼容。

1. 启动与组装

2. 工具系统

3. 扩展与事件 ⭐(最常用)

4. 持久化与会话

F01 同时覆盖: 获取会话 ID/路径、纯内存会话(SessionManager.inMemory())
F05 同时覆盖: 读取/操作历史消息(session.state.messages)

5. 上下文与记忆

6. Provider 与认证

7. 多 Agent 与打包发布

未列出的场景(终端 UI / 自定义命令 / RPC / Sandbox 等低频或 CLI 专属)直接翻 references/scenarios/ 目录。

项目结构

约定: .pi/ 放资源(人可编辑),src/ 放逻辑(开发者维护)。
核心: main.ts 只做组装(Provider → 工具 → createAgentSession)。

完整目录建议、规模演进、常见错误 → [project-structure.md](references/project-structure.md)

注意：项目结构仅是对新项目的建议，并不是必须选择，请按照实际情况（尤其是旧项目）调整项目结构。

SDK API 索引

按包/模块查 API。每个条目指向 references/sdk_doc/ 下的详细文档。

@earendil-works/pi-coding-agent(核心 SDK)

@earendil-works/pi-ai(AI 层)与高级主题

完整 sdkdoc 索引直接翻 `references/sdkdoc/` 目录（TUI/UI API/Faux Provider/RPC 模式等 CLI 专属低频项已从本 skill 剔除，需要时查 SDK 源码）。

源码兜底协议 ⭐(本 skill 不够用时)

当 scenarios/ 和 sdk_doc/ 都无法回答你的问题时,不要凭空推断——直接查 node_modules 内的包内容。pi-agent 的 npm 包自带文档、示例和类型,任何装了 SDK 的项目都自动拥有。

触发信号:类型/字段/方法名在 skill 内 grep 不到、签名未列出、实际行为与描述冲突、集成场景超出已覆盖模式。

4 层优先级(信息密度从高到低,先用上层):

完整路径导航表(三个包自带内容不对称)、检索配方、降级策略、回流提示 → [source-fallback.md](references/source-fallback.md)

兜底解决后:若该问题任何用 pi-agent 的项目都可能遇到,主动建议用户「值得补进 skill 吗」,由用户决定(遵循 [skill-maintenance.md](references/skill-maintenance.md) 沉淀)。

资源 & 维护

官方源码参考: packages/coding-agent/src/(SDK)、packages/agent/src/(Agent 核心)、packages/ai/src/(AI 抽象)

Skill 维护: 发现信息缺失/错误导致走弯路时,按 [skill-maintenance.md](references/skill-maintenance.md) 6 条原则完善本 skill,并同步更新 [CHANGELOG.md](CHANGELOG.md)（历史沿革，永久保留）。