dg-piagent

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 时遵循三步：

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 流程，对照新版 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. 启动与组装

我想...	详见
最简跑起来	A01
选模型 / 推理深度	A02
改系统提示词 / 人设	A03
指定 cwd	A05
加载 .pi/ 目录扩展文件	A06
完全手动组装所有组件	H01

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（历史沿革，永久保留）。