Extension 是 Pi 最核心的扩展点，允许用 TypeScript 模块注册自定义工具、命令、事件处理器、UI 组件等。
基本结构
export default function (pi: ExtensionAPI) {
// 注册自定义工具
pi.registerTool({ name: "deploy", ... });
// 注册斜杠命令
pi.registerCommand("stats", { ... });
// 监听事件
pi.on("tool_call", async (event, ctx) => { ... });
}默认导出也可以是 async 函数，Pi 会在启动继续之前等待异步工厂完成（适合一次性初始化，如提前拉取远程模型列表后调用 pi.registerProvider()）。
能力范围
Extension 可以做到的事情（几乎无限）：
- 自定义工具（或完全替换内置工具）
- 实现 sub-agents 和 plan mode
- 自定义 compaction 和摘要逻辑
- 权限门控和路径保护
- 自定义编辑器和 UI 组件（状态栏、页眉、页脚、Overlay）
- Git checkpoint 和自动提交
- SSH 和沙箱执行
- MCP server 集成
- 让 pi 看起来像 Claude Code
- 游戏（甚至 Doom 能跑）
加载位置
按优先级（从低到高）：
~/.pi/agent/extensions/— 全局用户扩展.pi/extensions/— 项目级扩展（需要项目信任）pi -e <path|npm|git>— CLI 一次性加载
与 Skills 的区别
| 维度 | Extension | Skill |
|---|---|---|
| 语言 | TypeScript | Markdown |
| 能力 | 完整 API 访问 | 注入到 context 的指令 |
| 复杂度 | 高，需编译 | 低，纯文本 |
| 适用场景 | 工具、UI、事件处理 | 使用流程、工作方法 |
Pi Packages
Extension 可以通过 pi-packages 发布和安装，npm 或 git 均可：
pi install npm:@foo/pi-tools
pi install git:github.com/user/repo安全警告：Pi 包以完整系统权限运行，Extension 可执行任意代码。安装第三方包前请审查源码。