| name | dg-piagent |
| description | Use when working with pi-agent / @earendil-works/pi-coding-agent SDK — 创建 agent、自定义工具、
编写扩展、修改系统提示词、管理会话、配置模型、处理认证、加载 skills/prompts/context files、
实现完全控制模式、或任何需要调用 pi-agent SDK API 的任务时使用。
也用于企业内网接口接入评估：用户给出企业/内网 LLM 接口文档或地址，问「能不能接」「怎么配」时，
按接口核对清单给出接入建议 + models.json 配置初稿。
触发关键词：createAgentSession、AgentSession、pi.on、session.subscribe、extensionFactories、
ModelRegistry、defineTool、pi-coding-agent、pi-ai、@earendil-works、SSE 流式集成、
企业接口文档、内网模型接入、OpenAI 兼容判断、接口接入评估。
|
pi-agent SDK 开发指南
⚠️ 版本基线: 本 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 时遵循三步：
-
默认对齐：引导安装一律用基线版本 npm install @earendil-works/pi-coding-agent@0.83.0，不装 latest——skill 的 API 描述精确核对到基线版本，装 latest 会立即漂移。场景文档里的安装命令同样以基线版本为准。
-
升级前评估：当任务涉及安装/升级（或用户问版本）时，先跑 npm view @earendil-works/pi-coding-agent version 拿 latest 与基线对比。若不同，联网查该版本 CHANGELOG/release notes，从 SDK 二次开发角度评估（新功能 / 破坏性变更），给用户简短建议，由用户决定是否升级。日常开发（项目已装好）不触发。
-
升级即更新 skill：若用户同意升到 X.Y.Z，安装后按 skill-maintenance.md 流程，对照新版 dist/**/*.d.ts + CHANGELOG 审查 skill 差异，产出更新清单，报用户确认后再改，并同步更新顶部基线版本号。
变更查阅渠道（第 2/3 步执行依据）：
| 渠道 | 路径/命令 | 适用阶段 |
|---|
| ① node_modules CHANGELOG | <proj>/node_modules/@earendil-works/pi-coding-agent/CHANGELOG.md（标准 Keep-a-Changelog，按 ## [版本号] 分节，含 Breaking Changes） | 升级后（第3步） |
| ② GitHub | github.com/earendil-works/pi 的 packages/coding-agent/CHANGELOG.md 或 Releases | 升级前（第2步，需联网） |
时序关键：升级前 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。⚠️ 但注意——pi.on handler 被派发方 await，落库这类慢 I/O 必须 fire-and-forget（推队列后台写），否则阻塞 agent loop。若只需存 message_*/turn_*/tool_execution_* 等 subscribe 收得到的事件，落库优先走 session.subscribe（不 await listener，可直接 await 写库，零阻塞）。详见 04-events.md 关键细节。
详见 Common Mistakes 与 sdk_doc/04-events.md。
⭐ v0.83.0 推荐：需要"agent 真正结束"信号时，订阅 agent_settled 替代 agent_end——前者保证所有 retry/compaction/queue 处理完才触发，每 prompt 一次，两层都派发。详见 sdk_doc/04 坑 1。
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
⭐ 二开起步检查清单
不管做什么 Agent，先过这几项（默认值都是 pi 编码助手的产品烙印）：
必改三项
- 系统提示词 → 默认硬编码 pi 人设（不覆盖会自称 "expert coding assistant operating inside pi"），必须覆盖 → A03
- 可用工具 → 默认
read/bash/edit/write 编码四件套；垂直 Agent 要换业务工具，bash 在多用户场景是安全口子 → A04
- 会话存储 → 默认落盘
~/.pi/agent/sessions/（CLI 单用户设计）；Web 多用户必须 SessionManager.inMemory() + 自己落库 → F01
易踩坑：createAgentSession 传了 resourceLoader 就不自动 reload——用扩展（尤其扩展注册 provider）时必须自己 await loader.reload()，否则扩展 factory 不执行、provider 选不到 → A06
意图总表
按「我要做什么」找文件。场景编号保留在文件名,向后兼容。
1. 启动与组装
2. 工具系统
| 我想... | 详见 |
|---|
| 写自定义工具(查 DB/调 API) | D01 |
| 工具白名单(禁用部分工具) | A04 |
| 动态注册 / 覆盖内置工具 | D02 |
| 工具调用前确认(安全闸门) | D04 |
| 工具结果自定义渲染 | D05 |
| 限制工具只在特定目录执行 | D06 |
3. 扩展与事件 ⭐(最常用)
| 我想... | 详见 |
|---|
| 写一个完整的扩展 | E02 |
| 拦截 / 修改工具调用 | E01 |
| 在生命周期阶段触发逻辑 | E04 |
| 拦截 / 变换用户输入 | E05 |
| 流式处理工具输出 | E06 |
| ⭐ Web/SSE 流式进度集成 | E11 |
| turn 开始时预加载数据 | G04 |
4. 持久化与会话
| 我想... | 详见 |
|---|
| 持久化会话 / 断点续聊 | F01 |
| 运行时切换 / 恢复 / 分叉 | F02 |
| 中止正在运行的 prompt | F04 |
| steer() 注入消息到队列 | F05 |
| 注入外部上下文 / 记忆 | G01 |
F01 同时覆盖: 获取会话 ID/路径、纯内存会话(SessionManager.inMemory())
F05 同时覆盖: 读取/操作历史消息(session.state.messages)
5. 上下文与记忆
| 我想... | 详见 |
|---|
| 加载/过滤/创建自定义 Skill | C01 |
定义 Prompt 模板(/command) | C02 |
| 注入虚拟 AGENTS.md 指令 | C03 |
| 自定义压缩策略 | G02 |
| 自动总结历史对话 | G03 |
6. Provider 与认证
| 我想... | 详见 |
|---|
| 配置 API Key / OAuth | B01 |
| 管理 settings 配置项 | B02 |
| 获取可用模型列表 | B03 |
| 自定义 Provider(智谱等) | H02 |
| 企业接口能否接入 + 出 models.json 初稿 | H07 |
| 用 Faux Provider 做测试 | H03 |
7. 多 Agent 与打包发布
| 我想... | 详见 |
|---|
| 多 Agent 协作 | H06 |
| 打包发布 Pi Package | I01 |
分发扩展(.piplugin) | I02 |
| 扩展引用第三方依赖 | I03 |
| 子 Agent 调度 | I05 |
未列出的场景(终端 UI / 自定义命令 / RPC / Sandbox 等低频或 CLI 专属)直接翻 references/scenarios/ 目录。
项目结构
约定: .pi/ 放资源(人可编辑),src/ 放逻辑(开发者维护)。
核心: main.ts 只做组装(Provider → 工具 → createAgentSession)。
完整目录建议、规模演进、常见错误 → project-structure.md
注意：项目结构仅是对新项目的建议，并不是必须选择，请按照实际情况（尤其是旧项目）调整项目结构。
SDK API 索引
按包/模块查 API。每个条目指向 references/sdk_doc/ 下的详细文档。
@earendil-works/pi-coding-agent(核心 SDK)
| 模块 | 说明 | 详细 |
|---|
createAgentSession | 创建会话主入口,接收全部配置 | 01 |
AgentSession | prompt / steer / abort / setModel / dispose / subscribe | 02 |
AgentSessionRuntime | newSession / switchSession / fork | 03 |
| 事件系统 | 全部事件类型、触发时机、数据结构、集成踩坑 | 04 |
ModelRuntime / ModelRegistry | 模型/认证运行时（v0.80.8+）+ 扩展兼容包装器 | 05 |
defineTool / 工具系统 | 自定义工具定义、内置工具、参数 schema | 06 |
ExtensionAPI | pi.on / pi.registerTool / pi.registerCommand / pi.ui | 07 |
DefaultResourceLoader | system prompt / skills / prompts / context files / extensions | 08 |
Skill 接口 | Skill 数据结构与加载机制(渐进式披露) | 09 |
PromptTemplate | /command 模板 | 10 |
| Context Files (AGENTS.md) | 项目级指令文件机制 | 11 |
SessionManager | create / continueRecent / open / list / inMemory | 12 |
SettingsManager | applyOverrides / flush / drainErrors | 13 |
@earendil-works/pi-ai(AI 层)与高级主题
| 模块 | 说明 | 详细 |
|---|
getModel / Custom Provider | 按 provider/id 查模型 / 自定义 Provider 注册 | 16 |
| Compaction | 上下文窗口压缩机制 | 18 |
| Pi Package | 打包、发布、版本管理 | 20 |
| 多 Agent 架构 | 多 Agent 协作模式 | 21 |
| 扩展推荐 SOP | 按用户需求实时查 npm + 给出推荐清单（用户主动询问时触发） | 22 |
完整 sdk_doc 索引直接翻 references/sdk_doc/ 目录（TUI/UI API/Faux Provider/RPC 模式等 CLI 专属低频项已从本 skill 剔除，需要时查 SDK 源码）。
源码兜底协议 ⭐(本 skill 不够用时)
当 scenarios/ 和 sdk_doc/ 都无法回答你的问题时,不要凭空推断——直接查 node_modules 内的包内容。pi-agent 的 npm 包自带文档、示例和类型,任何装了 SDK 的项目都自动拥有。
触发信号:类型/字段/方法名在 skill 内 grep 不到、签名未列出、实际行为与描述冲突、集成场景超出已覆盖模式。
4 层优先级(信息密度从高到低,先用上层):
| 优先级 | 查什么 | 最适合 |
|---|
| 1 | pi-coding-agent/examples/sdk/0X-*.ts | 「怎么做 X」 |
| 2 | pi-coding-agent/docs/*.md | 「X 是什么 / 有哪些能力」 |
| 3 | */dist/**/*.d.ts | 「X 有哪些字段/方法」 |
| 4 | */dist/**/*.js | 「X 为什么这样行为」 |
完整路径导航表(三个包自带内容不对称)、检索配方、降级策略、回流提示 → source-fallback.md
兜底解决后:若该问题任何用 pi-agent 的项目都可能遇到,主动建议用户「值得补进 skill 吗」,由用户决定(遵循 skill-maintenance.md 沉淀)。
资源 & 维护
官方源码参考: packages/coding-agent/src/(SDK)、packages/agent/src/(Agent 核心)、packages/ai/src/(AI 抽象)
Skill 维护: 发现信息缺失/错误导致走弯路时,按 skill-maintenance.md 6 条原则完善本 skill,并同步更新 CHANGELOG.md（历史沿革，永久保留）。
