手册/第 08 章
08
扩展与集成:五个机制、五种接入
pi 砍掉了内置功能,但把「加功能」做得很便宜。官方文档的建议是 选满足需求的最小机制——从纯文本到可执行代码,一共五档。
| 机制 | 是什么 | 成本 / 边界 |
|---|---|---|
| AGENTS.md | 项目上下文文件,自动注入 system prompt 的 project_context | 零成本,纯文本;最该先试的一档 |
| Prompt template | 斜杠命令模板,在输入变 user message 前展开 | 纯文本;适合固定流程 |
| Skill | 专门指令集,只有描述常驻,完整内容按需加载 | 渐进披露,省 token |
| Extension | TypeScript 模块:注册工具、命令、快捷键、provider、事件钩子、状态栏、UI | 与 pi 同权限;能改上下文与拦截工具调用 |
| Theme | 终端配色与样式 | 纯展示 |
其中 Extension 是唯一有执行权限的一档,所以它也是唯一被单独圈进 security-group 的一档。最小例子:
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"; export default function (pi: ExtensionAPI) { pi.registerCommand("hello", { description: "Show a greeting", handler: async (name, ctx) => { ctx.ui.notify(`Hello, ${name || "world"}!`, "info"); }, }); }
pi --extension ./hello.ts # 开发期直接加载,jiti 免编译 # 会话内输入 /hello 触发
五种接入方式,一套核心
这是「渲染是纯消费者」这一架构带来的直接好处:
| 方式 | 场景 | 入口 |
|---|---|---|
| 交互式 TUI | 日常开发 | pi |
| 脚本 / CI / 一次性任务 | pi --print "..." | |
| JSON 事件流 | 结构化消费、自己的 UI | pi --mode json |
| RPC | 控制一个独立 pi 进程(跨语言) | stdin/stdout JSON 协议 |
| TypeScript SDK | 嵌入到 Node/Bun 应用里 | createAgentSession() |
import { createAgentSession } from "@earendil-works/pi-coding-agent"; const { session } = await createAgentSession(); try { await session.prompt("What files are in the current directory?"); console.log(session.getLastAssistantText()); } finally { session.dispose(); }
session.prompt() 在整轮跑完后才 resolve;想流式取文本就订阅事件。
SessionManager 是最终上下文的唯一权威——直接改
session.agent.state.messages 不会改变持久化上下文,这一点在文档里被特别强调。