pi 系统学习手册 第 08 / 12 章 总目录 单页全本 架构图 GitHub

手册/第 08 章

08

扩展与集成:五个机制、五种接入

pi 砍掉了内置功能,但把「加功能」做得很便宜。官方文档的建议是 选满足需求的最小机制——从纯文本到可执行代码,一共五档。

机制是什么成本 / 边界
AGENTS.md项目上下文文件,自动注入 system prompt 的 project_context零成本,纯文本;最该先试的一档
Prompt template斜杠命令模板,在输入变 user message 前展开纯文本;适合固定流程
Skill专门指令集,只有描述常驻,完整内容按需加载渐进披露,省 token
ExtensionTypeScript 模块:注册工具、命令、快捷键、provider、事件钩子、状态栏、UI与 pi 同权限;能改上下文与拦截工具调用
Theme终端配色与样式纯展示

其中 Extension 是唯一有执行权限的一档,所以它也是唯一被单独圈进 security-group 的一档。最小例子:

~/.pi/agent/extensions/hello.ts
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");
    },
  });
}
bash
pi --extension ./hello.ts   # 开发期直接加载,jiti 免编译
# 会话内输入 /hello 触发

五种接入方式,一套核心

这是「渲染是纯消费者」这一架构带来的直接好处:

方式场景入口
交互式 TUI日常开发pi
Print脚本 / CI / 一次性任务pi --print "..."
JSON 事件流结构化消费、自己的 UIpi --mode json
RPC控制一个独立 pi 进程(跨语言)stdin/stdout JSON 协议
TypeScript SDK嵌入到 Node/Bun 应用里createAgentSession()
typescript · SDK 最小示例
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 不会改变持久化上下文,这一点在文档里被特别强调。

docs/extensions.md docs/sdk.md docs/packages.md

本章学习记录

记录仅保存在当前浏览器。