第 9 课：扩展与主题

这是 pi 真正的超能力。扩展是能改变 pi 几乎一切的 TypeScript 模块；主题能重排整个界面。如果你曾经想过"我希望 pi 能……"，扩展就是答案。

扩展：基础

扩展是一个 TypeScript 文件，导出接收 ExtensionAPI 的默认工厂函数：

// ~/.pi/agent/extensions/my-extension.ts
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";

export default function (pi: ExtensionAPI) {
  pi.on("session_start", async (_event, ctx) => {
    ctx.ui.notify("Extension loaded!", "info");
  });

  // 拦截危险命令
  pi.on("tool_call", async (event, ctx) => {
    if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
      const ok = await ctx.ui.confirm("Dangerous!", "Allow rm -rf?");
      if (!ok) return { block: true, reason: "Blocked by user" };
    }
  });

  // 自定义工具，LLM 可以调用
  pi.registerTool({
    name: "greet",
    description: "Greet someone by name",
    parameters: Type.Object({ name: Type.String() }),
    async execute(toolCallId, params) {
      return { content: [{ type: "text", text: `Hello, ${params.name}!` }], details: {} };
    },
  });

  // 自定义斜杠命令
  pi.registerCommand("hello", {
    description: "Say hello",
    handler: async (args, ctx) => ctx.ui.notify(`Hello ${args || "world"}!`, "info"),
  });
}

TypeScript 无需编译即可运行（通过 jiti 加载）。用 pi -e ./my-extension.ts 测试；想通过 /reload 热重载，就放到 ~/.pi/agent/extensions/（全局）或 .pi/extensions/（项目）。

扩展能做什么

1. 响应事件。 事件系统非常丰富：tool_call（可以拦截）、tool_result（可以修改）、input（拦截用户输入）、before_agent_start（注入消息或改写系统提示词）、session_start/shutdown、model_select、thinking_level_select、context（每次 LLM 调用前修剪消息）等等。

2. 注册自定义工具。 模型可以调用的工具——用 TypeBox 模式定义参数。这就是人们添加子代理、MCP 服务器、网页搜索、待办清单等的方式。

3. 注册命令与快捷键。 /mycommand 处理器，加上自定义按键绑定和 CLI 标志。

4. 用户交互。 ctx.ui.confirm、select、input、notify、setStatus（底部栏）、setWidget（编辑器上方）——甚至可以通过 ctx.ui.custom() 做完整的自定义 TUI 组件。

5. 持久化状态。 pi.appendEntry() 把扩展数据存进会话文件，重启后依然保留。

著名的用例： 权限门禁、git 检查点（每回合 stash/恢复）、路径保护（阻止写入 .env）、自定义压缩、外部集成、等待时的游戏。

安全： 扩展以完整系统权限运行，可以执行任意代码。只运行你信任或自己写的。

自己写一个

问 pi 就行！文档甚至这么说："pi can create extensions. Ask it to build one for your use case." 只要描述你的需求："创建一个在包含 sudo 的 bash 命令执行前需要确认的扩展"。放到 .pi/extensions/ 然后 /reload。

主题：让它变成你的

主题是定义 51 个颜色 token 的 JSON 文件。位置：~/.pi/agent/themes/*.json、.pi/themes/*.json、包，或 --theme <path>。通过 /settings 或设置里的 "theme": "my-theme" 选择。

{
  "$schema": "https://raw.githubusercontent.com/earendil-works/pi/main/packages/coding-agent/src/modes/interactive/theme/theme-schema.json",
  "name": "my-theme",
  "vars": { "primary": "#00aaff", "gray": 242 },
  "colors": {
    "accent": "primary",
    "border": "primary",
    "success": "#00ff00",
    "error": "#ff0000",
    "text": "",
    "thinkingHigh": "#ff00ff"
  }
}

颜色支持十六进制、256 色索引、vars 引用，或 ""（终端默认色）。$schema 字段让编辑器有自动补全。热重载： 修改当前激活的主题文件，pi 会立即重新应用。

专业建议：以定义在 vars 里的 Nord/Gruvbox/Tokyo Night 为基色调；用工具状态和 markdown 内容测试；运行 echo $COLORTERM 检查 → 应显示 truecolor。

---

作业： 让 pi 写一个小扩展——比如在 agent_end 时通知你耗时多少。存到 .pi/extensions/，/reload，观察它触发。然后调整你主题的 thinkingHigh 颜色，看它热重载。