pi 可以创建扩展：为你的用例构建一个

扩展（Extensions）

扩展是 TypeScript 模块，用于扩展 pi 的行为。它们可以订阅生命周期事件、注册 LLM 可调用的自定义工具、添加命令等。

/reload 的放置位置： 将扩展放在 ~/.pi/agent/extensions/（全局）或 .pi/extensions/（项目本地）中，以便自动发现。仅对快速测试使用 pi -e ./path.ts。位于自动发现位置的扩展可以通过 /reload 热重载。

主要能力：

• 自定义工具 - 通过 pi.registerTool() 注册 LLM 可以调用的工具
• 事件拦截 - 阻止或修改工具调用、注入上下文、自定义压缩
• 用户交互 - 通过 ctx.ui 提示用户（select、confirm、input、notify）
• 自定义 UI 组件 - 通过 ctx.ui.custom() 实现完整的 TUI 组件，支持键盘输入，用于复杂交互
• 自定义命令 - 通过 pi.registerCommand() 注册类似 /mycommand 的命令
• 会话持久化 - 通过 pi.appendEntry() 存储在重启后仍然有效的状态
• 自定义渲染 - 控制工具调用/结果和消息在 TUI 中的显示方式

用例示例：

• 权限门（在 rm -rf、sudo 等操作前确认）
• Git 检查点（每轮执行 stash，分支恢复）
• 路径保护（阻止写入 .env、node_modules/）
• 自定义压缩（按你的方式总结对话）
• 对话摘要（参见 summarize.ts 示例）
• 交互式工具（问题、向导、自定义对话框）
• 有状态工具（待办列表、连接池）
• 外部集成（文件监听器、Webhooks、CI 触发器）
• 等待时的游戏（参见 snake.ts 示例）

参阅 examples/extensions/ 获取工作实现的示例。

目录

• 快速开始
• 扩展位置
• 可用导入
• 编写扩展
  • 扩展风格
• 事件
  • 生命周期概览
  • 资源事件
  • 会话事件
  • Agent 事件
  • 模型事件
  • 工具事件
• ExtensionContext
• ExtensionCommandContext
• ExtensionAPI 方法
• 状态管理
• 自定义工具
  • 动态工具加载
• 自定义 UI
• 错误处理
• 模式行为
• 示例参考

快速开始

创建 ~/.pi/agent/extensions/my-extension.ts：

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";

export default function (pi: ExtensionAPI) {
  // React to events
  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" };
    }
  });

  // Register a custom tool
  pi.registerTool({
    name: "greet",
    label: "Greet",
    description: "Greet someone by name",
    parameters: Type.Object({
      name: Type.String({ description: "Name to greet" }),
    }),
    async execute(toolCallId, params, signal, onUpdate, ctx) {
      return {
        content: [{ type: "text", text: `Hello, ${params.name}!` }],
        details: {},
      };
    },
  });

  // Register a command
  pi.registerCommand("hello", {
    description: "Say hello",
    handler: async (args, ctx) => {
      ctx.ui.notify(`Hello ${args || "world"}!`, "info");
    },
  });
}

使用 --extension（或 -e）标志测试：

pi -e ./my-extension.ts

扩展位置

安全性： 扩展以你的完整系统权限运行，可以执行任意代码。仅从你信任的来源安装。

扩展从受信任的位置自动发现。项目本地 .pi/extensions 中的条目仅在项目被信任后才会加载。

位置	范围
~/.pi/agent/extensions/*.ts	全局（所有项目）
~/.pi/agent/extensions/*/index.ts	全局（子目录）
.pi/extensions/*.ts	项目本地
.pi/extensions/*/index.ts	项目本地（子目录）

通过 settings.json 添加额外路径：

{
  "packages": [
    "npm:@foo/bar@1.0.0",
    "git:github.com/user/repo@v1"
  ],
  "extensions": [
    "/path/to/local/extension.ts",
    "/path/to/local/extension/dir"
  ]
}

要通过 npm 或 git 作为 pi 包共享扩展，请参阅 packages.md。

可用导入

包	用途
@earendil-works/pi-coding-agent	扩展类型（ExtensionAPI, ExtensionContext，事件）
typebox	工具参数的 Schema 定义
@earendil-works/pi-ai	AI 工具（用于 Google 兼容枚举的 StringEnum）
@earendil-works/pi-tui	用于自定义渲染的 TUI 组件

npm 依赖也可以使用。在扩展旁边（或父目录）添加一个 package.json，运行 npm install，则 node_modules/ 中的导入会自动解析。

对于通过 pi install（npm 或 git）安装的分发 pi 包，运行时依赖必须放在 dependencies 中。包安装默认使用生产安装（npm install --omit=dev），因此 devDependencies 在运行时不可用；当配置了 npmCommand 时，git 包为了与包装器兼容而使用普通 install。

Node.js 内置模块（node:fs, node:path 等）也可用。

编写扩展

扩展导出一个接收 ExtensionAPI 的默认工厂函数。该函数可以是同步或异步的：

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  // Subscribe to events
  pi.on("event_name", async (event, ctx) => {
    // ctx.ui for user interaction
    const ok = await ctx.ui.confirm("Title", "Are you sure?");
    ctx.ui.notify("Done!", "info");
    ctx.ui.setStatus("my-ext", "Processing...");  // Footer status
    ctx.ui.setWidget("my-ext", ["Line 1", "Line 2"]);  // Widget above editor (default)
  });

  // Register tools, commands, shortcuts, flags
  pi.registerTool({ ... });
  pi.registerCommand("name", { ... });
  pi.registerShortcut("ctrl+x", { ... });
  pi.registerFlag("my-flag", { ... });
}

扩展通过 jiti 加载，因此 TypeScript 无需编译即可工作。

如果工厂返回一个 Promise，pi 会在继续启动之前等待它。这意味着异步初始化会在 session_start、resources_discover 以及通过 pi.registerProvider() 排队的提供者注册刷新之前完成。

异步工厂函数

使用异步工厂进行一次性启动工作，例如获取远程配置或动态发现可用模型。

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default async function (pi: ExtensionAPI) {
  const response = await fetch("http://localhost:1234/v1/models");
  const payload = (await response.json()) as {
    data: Array<{
      id: string;
      name?: string;
      context_window?: number;
      max_tokens?: number;
    }>;
  };

  pi.registerProvider("local-openai", {
    baseUrl: "http://localhost:1234/v1",
    apiKey: "$LOCAL_OPENAI_API_KEY",
    api: "openai-completions",
    models: payload.data.map((model) => ({
      id: model.id,
      name: model.name ?? model.id,
      reasoning: false,
      input: ["text"],
      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
      contextWindow: model.context_window ?? 128000,
      maxTokens: model.max_tokens ?? 4096,
    })),
  });
}

这种模式使获取的模型在正常启动期间和 pi --list-models 时可用。

长期资源与关闭

扩展工厂可能在没有启动会话的情况下运行。不要从工厂启动后台资源，例如进程、套接字、文件监听器或计时器。

将后台资源启动推迟到 session_start 或需要该资源的命令/工具/事件。注册一个幂等的 session_shutdown 处理程序来关闭你启动的任何会话范围资源。

扩展风格

单文件 - 最简单，适用于小型扩展：

~/.pi/agent/extensions/
└── my-extension.ts

包含 index.ts 的目录 - 适用于多文件扩展：

~/.pi/agent/extensions/
└── my-extension/
    ├── index.ts        # 入口点（导出默认函数）
    ├── tools.ts        # 帮助模块
    └── utils.ts        # 帮助模块

包含依赖的包 - 适用于需要 npm 包的扩展：

~/.pi/agent/extensions/
└── my-extension/
    ├── package.json    # 声明依赖和入口点
    ├── package-lock.json
    ├── node_modules/   # npm install 之后
    └── src/
        └── index.ts

// package.json
{
  "name": "my-extension",
  "dependencies": {
    "zod": "^3.0.0",
    "chalk": "^5.0.0"
  },
  "pi": {
    "extensions": ["./src/index.ts"]
  }
}

在扩展目录中运行 npm install，然后 node_modules/ 中的导入会自动工作。

事件

生命周期概览

pi starts
  │
  ├─► project_trust (user/global and CLI extensions only, before project resources load)
  ├─► session_start { reason: "startup" }
  └─► resources_discover { reason: "startup" }
      │
      ▼
user sends prompt ─────────────────────────────────────────┐
  │                                                        │
  ├─► (extension commands checked first, bypass if found)  │
  ├─► input (can intercept, transform, or handle)          │
  ├─► (skill/template expansion if not handled)            │
  ├─► before_agent_start (can inject message, modify system prompt)
  ├─► agent_start                                          │
  ├─► message_start / message_update / message_end         │
  │                                                        │
  │   ┌─── turn (repeats while LLM calls tools) ───┐       │
  │   │                                            │       │
  │   ├─► turn_start                               │       │
  │   ├─► context (can modify messages)            │       │
  │   ├─► before_provider_headers (can mutate headers)     |
  │   ├─► before_provider_request (can inspect or replace payload)
  │   ├─► after_provider_response (status + headers, before stream consume)
  │   │                                            │       │
  │   │   LLM responds, may call tools:            │       │
  │   │     ├─► tool_execution_start               │       │
  │   │     ├─► tool_call (can block)              │       │
  │   │     ├─► tool_execution_update              │       │
  │   │     ├─► tool_result (can modify)           │       │
  │   │     └─► tool_execution_end                 │       │
  │   │                                            │       │
  │   └─► turn_end                                 │       │
  │                                                        │
  ├─► agent_end                                            │
  └─► agent_settled (no retry/compaction/follow-up left)   │
                                                           │
user sends another prompt ◄────────────────────────────────┘

/new (new session) or /resume (switch session)
  ├─► session_before_switch (can cancel)
  ├─► session_shutdown
  ├─► session_start { reason: "new" | "resume", previousSessionFile? }
  └─► resources_discover { reason: "startup" }

/fork or /clone
  ├─► session_before_fork (can cancel)
  ├─► session_shutdown
  ├─► session_start { reason: "fork", previousSessionFile }
  └─► resources_discover { reason: "startup" }

/name or pi.setSessionName()
  └─► session_info_changed

/compact or auto-compaction
  ├─► session_before_compact (can cancel or customize)
  └─► session_compact

/tree navigation
  ├─► session_before_tree (can cancel or customize)
  └─► session_tree

/model or Ctrl+P (model selection/cycling)
  ├─► thinking_level_select (if model change changes/clamps thinking level)
  └─► model_select

thinking level changes (settings, keybinding, pi.setThinkingLevel())
  └─► thinking_level_select

exit (Ctrl+C, Ctrl+D, SIGHUP, SIGTERM)
  └─► session_shutdown

启动事件

project_trust

在 pi 决定是否信任具有动态配置（.pi 或 .agents/skills）的项目之前触发。它在启动期间以及当会话替换（例如 /resume）进入其信任尚未在当前进程中解析的 cwd 时运行。只有用户/全局扩展和 CLI -e 扩展参与；项目本地扩展在信任解析之前不会被加载。

pi.on("project_trust", async (event, ctx) => {
  // event.cwd - 当前工作目录
  // ctx 有一个有限的信任上下文：cwd、mode、hasUI 以及 select/confirm/input/notify UI 帮助方法
  if (await ctx.ui.confirm("Trust project?", event.cwd)) {
    return { trusted: "yes", remember: true };
  }
  return { trusted: "undecided" };
});

project_trust 处理程序必须返回 { trusted: "yes" | "no" | "undecided" }。返回 "yes" 或 "no" 的用户/全局或 CLI 扩展拥有决定权；第一个 yes/no 决定获胜，并抑制内置的信任提示。使用 remember: true 来持久化 yes/no 决定；否则它仅适用于当前进程。返回 "undecided" 以让后续处理程序或内置信任流程决定。在提示之前检查 ctx.hasUI。如果没有处理程序返回 yes/no，则继续正常的信任解析：首先应用已保存的 trust.json 决定，然后 defaultProjectTrust 控制 pi 是询问、信任还是默认拒绝。

资源事件

resources_discover

在 session_start 之后触发，以便扩展可以提供额外的技能、提示和主题路径。启动路径使用 reason: "startup"。重载使用 reason: "reload"。

pi.on("resources_discover", async (event, _ctx) => {
  // event.cwd - 当前工作目录
  // event.reason - "startup" | "reload"
  return {
    skillPaths: ["/path/to/skills"],
    promptPaths: ["/path/to/prompts"],
    themePaths: ["/path/to/themes"],
  };
});

会话事件

有关会话存储内部机制和 SessionManager API，请参阅 Session Format。

session_start

当会话启动、加载或重载时触发。

pi.on("session_start", async (event, ctx) => {
  // event.reason - "startup" | "reload" | "new" | "resume" | "fork"
  // event.previousSessionFile - 对于 "new", "resume", 和 "fork" 存在
  ctx.ui.notify(`Session: ${ctx.sessionManager.getSessionFile() ?? "ephemeral"}`, "info");
});

session_info_changed

当当前会话显示名称通过 /name、RPC 或 pi.setSessionName() 设置时触发。

pi.on("session_info_changed", async (event, ctx) => {
  // event.name - 当前规范化的名称，如果清除则为 undefined
  ctx.ui.notify(`Session renamed: ${event.name ?? "(none)"}`, "info");
});

session_before_switch

在开始新会话（/new）或切换会话（/resume）之前触发。

pi.on("session_before_switch", async (event, ctx) => {
  // event.reason - "new" 或 "resume"
  // event.targetSessionFile - 我们要切换到的会话（仅适用于 "resume"）

  if (event.reason === "new") {
    const ok = await ctx.ui.confirm("Clear?", "Delete all messages?");
    if (!ok) return { cancel: true };
  }
});

成功切换或新会话操作后，pi 为旧扩展实例发出 session_shutdown，为新会话重载并重新绑定扩展，然后发出带有 reason: "new" | "resume" 和 previousSessionFile 的 session_start。在 session_shutdown 中进行清理工作，然后在 session_start 中重建任何内存中状态。

session_before_fork

当通过 /fork 分支或通过 /clone 克隆时触发。

pi.on("session_before_fork", async (event, ctx) => {
  // event.entryId - 所选条目的 ID
  // event.position - 对于 /fork 为 "before"，对于 /clone 为 "at"
  return { cancel: true }; // 取消 fork/clone
  // 或者
  return { skipConversationRestore: true }; // 保留给未来的对话恢复控制
});

成功分支或克隆后，pi 为旧扩展实例发出 session_shutdown，为新会话重载并重新绑定扩展，然后发出带有 reason: "fork" 和 previousSessionFile 的 session_start。在 session_shutdown 中进行清理工作，然后在 session_start 中重建任何内存中状态。

session_before_compact / session_compact

在压缩时触发。有关详细信息，请参阅 compaction.md。

pi.on("session_before_compact", async (event, ctx) => {
  const { preparation, branchEntries, customInstructions, reason, willRetry, signal } = event;

  // reason - "manual" (/compact), "threshold", 或 "overflow"
  // willRetry - 是否在压缩后重试中断的轮次（溢出恢复）

  // 取消：
  return { cancel: true };

  // 自定义摘要：
  return {
    compaction: {
      summary: "...",
      firstKeptEntryId: preparation.firstKeptEntryId,
      tokensBefore: preparation.tokensBefore,
      // usage: summaryResponse.usage, // 可选；包含在会话总计中
    }
  };
});

pi.on("session_compact", async (event, ctx) => {
  // event.compactionEntry - 保存的压缩
  // event.fromExtension - 扩展是否提供了它
  // event.reason - "manual" (/compact), "threshold", 或 "overflow"
  // event.willRetry - 是否在压缩后重试中断的轮次（溢出恢复）
});

session_before_tree / session_tree

在 /tree 导航时触发。有关树导航概念，请参阅 Sessions。

pi.on("session_before_tree", async (event, ctx) => {
  const { preparation, signal } = event;
  return { cancel: true };
  // 或者提供自定义摘要：
  return {
    summary: {
      summary: "...",
      // usage: summaryResponse.usage, // 可选；包含在会话总计中
      details: {},
    },
  };
});

pi.on("session_tree", async (event, ctx) => {
  // event.newLeafId, oldLeafId, summaryEntry, fromExtension
});

session_shutdown

在已启动的会话运行时被拆除之前触发。用于清理从 session_start 或其他会话范围 Hook 中打开的资源。

pi.on("session_shutdown", async (event, ctx) => {
  // event.reason - "quit" | "reload" | "new" | "resume" | "fork"
  // event.targetSessionFile - 会话替换流程的目标会话
  // 清理、保存状态等
});

Agent 事件

before_agent_start

在用户提交提示之后、agent 循环之前触发。可以注入消息和/或修改系统提示。

pi.on("before_agent_start", async (event, ctx) => {
  // event.prompt - 用户的提示文本
  // event.images - 附加的图像（如果有）
  // event.systemPrompt - 当前为此处理程序链接的系统提示
  //   （包括之前 before_agent_start 处理程序的更改）
  // event.systemPromptOptions - 用于构建系统提示的结构化选项
  //   .customPrompt - 任何自定义系统提示（来自 --system-prompt, SYSTEM.md 或自定义模板）
  //   .selectedTools - 当前提示中活跃的工具
  //   .toolSnippets - 每个工具的一行描述
  //   .promptGuidelines - 自定义准则要点
  //   .appendSystemPrompt - 来自 --append-system-prompt 标志的文本
  //   .cwd - 工作目录
  //   .contextFiles - AGENTS.md 文件和其他已加载的上下文文件
  //   .skills - 已加载的技能

  return {
    // 注入一条持久消息（存储在会话中，发送给 LLM）
    message: {
      customType: "my-extension",
      content: "Additional context for the LLM",
      display: true,
    },
    // 为此轮次替换系统提示（跨扩展链接）
    systemPrompt: event.systemPrompt + "\n\nExtra instructions for this turn...",
  };
});

systemPromptOptions 字段为扩展提供了与 Pi 用于构建系统提示的相同结构化数据。这使你可以检查 Pi 加载了什么——自定义提示、准则、工具片段、上下文文件、技能——而无需重新发现资源或重新解析标志。当你的扩展需要对系统提示进行深入、有根据的更改，同时尊重用户提供的配置时，请使用此字段。

在 before_agent_start 内部，event.systemPrompt 和 ctx.getSystemPrompt() 都反映当前处理程序的链接系统提示。后面的 before_agent_start 处理程序仍然可以再次修改它。

agent_start / agent_end / agent_settled

agent_start 在低级 agent 运行开始时触发。agent_end 在该运行结束时触发，但 Pi 可能仍然会自动重试、自动压缩并重试，或继续处理排队的后续消息。对于需要知道 Pi 不会继续自动运行的状态集成，请使用 agent_settled。

pi.on("agent_start", async (_event, ctx) => {});

pi.on("agent_end", async (event, ctx) => {
  // event.messages - 来自此低级运行的消息
});

pi.on("agent_settled", async (_event, ctx) => {
  // 除非另一个扩展启动了新运行，否则这里 ctx.isIdle() 为 true
});

turn_start / turn_end

为每个轮次（一次 LLM 响应 + 工具调用）触发。

pi.on("turn_start", async (event, ctx) => {
  // event.turnIndex, event.timestamp
});

pi.on("turn_end", async (event, ctx) => {
  // event.turnIndex, event.message, event.toolResults
});

message_start / message_update / message_end

为消息生命周期更新触发。

• message_start 和 message_end 为用户、助手和 toolResult 消息触发。
• message_update 为助手流式更新触发。
• message_end 处理程序可以返回 { message } 以替换最终确定的消息。替换必须保持相同的 role。

pi.on("message_start", async (event, ctx) => {
  // event.message
});

pi.on("message_update", async (event, ctx) => {
  // event.message
  // event.assistantMessageEvent (token-by-token stream event)
});

pi.on("message_end", async (event, ctx) => {
  if (event.message.role !== "assistant") return;

  return {
    message: {
      ...event.message,
      usage: {
        ...event.message.usage,
        cost: {
          ...event.message.usage.cost,
          total: 0.123,
        },
      },
    },
  };
});

tool_execution_start / tool_execution_update / tool_execution_end

为工具执行生命周期更新触发。

在并行工具模式下：

• tool_execution_start 在预检阶段按助手源顺序发出
• tool_execution_update 事件可能跨工具交错
• tool_execution_end 在每个工具完成后按工具完成顺序发出
• 最终的 toolResult 消息事件仍会在稍后按助手源顺序发出

pi.on("tool_execution_start", async (event, ctx) => {
  // event.toolCallId, event.toolName, event.args
});

pi.on("tool_execution_update", async (event, ctx) => {
  // event.toolCallId, event.toolName, event.args, event.partialResult
});

pi.on("tool_execution_end", async (event, ctx) => {
  // event.toolCallId, event.toolName, event.result, event.isError
});

context

在每次 LLM 调用之前触发。非破坏性地修改消息。有关消息类型，请参阅 Session Format。

pi.on("context", async (event, ctx) => {
  // event.messages - 深拷贝，可以安全修改
  const filtered = event.messages.filter(m => !shouldPrune(m));
  return { messages: filtered };
});

before_provider_headers

在传出 HTTP 头部组装后触发。用于添加、覆盖或删除请求头部。

处理程序就地修改 event.headers。将键设置为字符串以添加或覆盖它，或设置为 null 以删除它。

pi.on("before_provider_headers", (event, ctx) => {
  // 添加或覆盖——例如用于网关跟踪/归属的会话 ID
  event.headers["x-session-id"] = ctx.sessionManager.getSessionId();

  // 删除 pi 为此调用添加的跟踪头部
  event.headers["X-OpenRouter-Title"] = null;
});

每个提供者请求运行一次；重试重用相同的头部，而不是重新触发 Hook。

before_provider_request

在构建提供者特定的有效负载之后、发送请求之前触发。处理程序按扩展加载顺序运行。返回 undefined 保持有效负载不变。返回任何其他值会替换有效负载，供后续处理程序和实际请求使用。

这个 Hook 可以重写提供者级别的系统指令或完全删除它们。这些有效负载级别的更改不会反映在 ctx.getSystemPrompt() 中，后者报告 Pi 的系统提示字符串，而不是最终的序列化提供者有效负载。

pi.on("before_provider_request", (event, ctx) => {
  console.log(JSON.stringify(event.payload, null, 2));

  // 可选：替换有效负载
  // return { ...event.payload, temperature: 0 };
});

这主要用于调试提供者序列化和缓存行为。

after_provider_response

在收到 HTTP 响应之后、消费其流主体之前触发。处理程序按扩展加载顺序运行。

pi.on("after_provider_response", (event, ctx) => {
  // event.status - HTTP 状态码
  // event.headers - 规范化的响应头部
  if (event.status === 429) {
    console.log("rate limited", event.headers["retry-after"]);
  }
});

头部的可用性取决于提供者和传输。抽象 HTTP 响应的提供者可能不会暴露头部。

模型事件

model_select

当模型通过 /model 命令、模型循环（Ctrl+P）或会话恢复更改时触发。

pi.on("model_select", async (event, ctx) => {
  // event.model - 新选择的模型
  // event.previousModel - 上一个模型（如果是首次选择则为 undefined）
  // event.source - "set" | "cycle" | "restore"

  const prev = event.previousModel
    ? `${event.previousModel.provider}/${event.previousModel.id}`
    : "none";
  const next = `${event.model.provider}/${event.model.id}`;

  ctx.ui.notify(`Model changed (${event.source}): ${prev} -> ${next}`, "info");
});

使用此事件在活跃模型更改时更新 UI 元素（状态栏、页脚）或执行特定于模型的初始化。

thinking_level_select

当思考级别更改时触发。这仅是通知；处理程序返回值被忽略。

pi.on("thinking_level_select", async (event, ctx) => {
  // event.level - 新选择的思考级别
  // event.previousLevel - 上一个思考级别

  ctx.ui.setStatus("thinking", `thinking: ${event.level}`);
});

当 pi.setThinkingLevel()、模型更改或内置思考级别控件更改活跃思考级别时，使用此事件更新扩展 UI。

工具事件

tool_call

在 tool_execution_start 之后、工具执行之前触发。可以阻止。 使用 isToolCallEventType 进行窄化并获取类型化输入。

在 tool_call 运行之前，pi 会等待之前发出的 Agent 事件通过 AgentSession 完成排空。这意味着 ctx.sessionManager 通过当前的助手工具调用消息是最新的。

在默认的并行工具执行模式下，来自同一助手消息的兄弟工具调用按顺序预检，然后并发执行。tool_call 不能保证在 ctx.sessionManager 中看到来自同一助手消息的兄弟工具结果。

event.input 是可变的。就地修改它以在执行前修补工具参数。

行为保证：

• 对 event.input 的修改会影响实际的工具执行
• 后面的 tool_call 处理程序会看到前面处理程序所做的修改
• 你的修改后不会执行重新验证
• 来自 tool_call 的返回值仅通过 { block: true, reason?: string } 控制阻止

import { isToolCallEventType } from "@earendil-works/pi-coding-agent";

pi.on("tool_call", async (event, ctx) => {
  // event.toolName - "bash", "read", "write", "edit", 等
  // event.toolCallId
  // event.input - 工具参数（可变）

  // 内置工具：不需要类型参数
  if (isToolCallEventType("bash", event)) {
    // event.input 是 { command: string; timeout?: number }
    event.input.command = `source ~/.profile\n${event.input.command}`;

    if (event.input.command.includes("rm -rf")) {
      return { block: true, reason: "Dangerous command" };
    }
  }

  if (isToolCallEventType("read", event)) {
    // event.input 是 { path: string; offset?: number; limit?: number }
    console.log(`Reading: ${event.input.path}`);
  }
});

键入自定义工具输入

自定义工具应导出其输入类型：

// my-extension.ts
export type MyToolInput = Static<typeof myToolSchema>;

使用带有显式类型参数的 isToolCallEventType：

import { isToolCallEventType } from "@earendil-works/pi-coding-agent";
import type { MyToolInput } from "my-extension";

pi.on("tool_call", (event) => {
  if (isToolCallEventType<"my_tool", MyToolInput>("my_tool", event)) {
    event.input.action;  // 类型化
  }
});

tool_result

在工具执行完成之后、tool_execution_end 和最终的工具结果消息事件发出之前触发。可以修改结果。

在并行工具模式下，tool_result 和 tool_execution_end 可能按工具完成顺序交错，而最终的 toolResult 消息事件仍然稍后按助手源顺序发出。

tool_result 处理程序像中间件一样链接：

• 处理程序按扩展加载顺序运行
• 每个处理程序在看到前一个处理程序更改后的最新结果
• 处理程序可以返回部分补丁（content, details, isError 或 usage）；省略的字段保持当前值

在处理程序内部为嵌套的异步工作使用 ctx.signal。这使 Esc 可以取消模型调用、fetch() 以及其他由扩展启动的支持中止的操作。

import { isBashToolResult } from "@earendil-works/pi-coding-agent";

pi.on("tool_result", async (event, ctx) => {
  // event.toolName, event.toolCallId, event.input
  // event.content, event.details, event.isError, event.usage

  if (isBashToolResult(event)) {
    // event.details 被键入为 BashToolDetails
  }

  const response = await fetch("https://example.com/summarize", {
    method: "POST",
    body: JSON.stringify({ content: event.content }),
    signal: ctx.signal,
  });

  // 修改结果：
  return { content: [...], details: {...}, isError: false, usage: nestedModelUsage };
});

用户 Bash 事件

user_bash

当用户执行 ! 或 !! 命令时触发。可以拦截。

import { createLocalBashOperations } from "@earendil-works/pi-coding-agent";

pi.on("user_bash", (event, ctx) => {
  // event.command - bash 命令
  // event.excludeFromContext - 如果使用 !! 前缀则为 true
  // event.cwd - 工作目录

  // 选项 1：提供自定义操作（例如 SSH）
  return { operations: remoteBashOps };

  // 选项 2：包装 pi 的内置本地 bash 后端
  const local = createLocalBashOperations();
  return {
    operations: {
      exec(command, cwd, options) {
        return local.exec(`source ~/.profile\n${command}`, cwd, options);
      }
    }
  };

  // 选项 3：完全替换——直接返回结果
  return { result: { output: "...", exitCode: 0, cancelled: false, truncated: false } };
});

输入事件

input

在用户输入被接收后、扩展命令被检查之后但在技能和模板扩展之前触发。该事件看到原始输入文本，因此 /skill:foo 和 /template 尚未扩展。

处理顺序：

1. 首先检查扩展命令（/cmd）——如果找到，处理程序运行并跳过 input 事件
2. input 事件触发——可以拦截、转换或处理
3. 如果未处理：技能命令（/skill:name）扩展为技能内容
4. 如果未处理：提示模板（/template）扩展为模板内容
5. Agent 处理开始（before_agent_start 等）

pi.on("input", async (event, ctx) => {
  // event.text - 原始输入（在技能/模板扩展之前）
  // event.images - 附加的图像，如果有
  // event.source - "interactive" (typed), "rpc" (API), 或 "extension" (via sendUserMessage)
  // event.streamingBehavior - "steer" | "followUp" | undefined
  //   undefined 当空闲时，用于流中中断的 "steer"，
  //   用于在 agent 完成之前排队消息的 "followUp"

  // 转换：在扩展之前重写输入
  if (event.text.startsWith("?quick "))
    return { action: "transform", text: `Respond briefly: ${event.text.slice(7)}` };

  // 处理：无需 LLM 响应（扩展显示自己的反馈）
  if (event.text === "ping") {
    ctx.ui.notify("pong", "info");
    return { action: "handled" };
  }

  // 按来源路由：跳过扩展注入消息的处理
  if (event.source === "extension") return { action: "continue" };

  // 在扩展之前拦截技能命令
  if (event.text.startsWith("/skill:")) {
    // 可以转换、阻止或让其通过
  }

  return { action: "continue" };  // 默认：传递到扩展
});

结果：

• continue - 保持不变传递（如果处理程序不返回任何内容，则为默认值）
• transform - 修改文本/图像，然后继续到扩展
• handled - 完全跳过 agent（返回此值的第一个处理程序获胜）

转换跨处理程序链接。请参阅 input-transform.ts 和 input-transform-streaming.ts 了解 streamingBehavior 感知路由。

ExtensionContext

所有处理程序都接收 ctx: ExtensionContext。

ctx.ui

用于用户交互的 UI 方法。有关完整详细信息，请参阅 自定义 UI。

ctx.mode

当抢跑模式："tui", "rpc", "json" 或 "print"。使用 ctx.mode === "tui" 来保护仅限终端的特性，例如 custom()、组件工厂、终端输入和直接 TUI 渲染。

ctx.hasUI

在 TUI 和 RPC 模式下为 true。在打印模式（-p）和 JSON 模式下为 false。使用它来保护在 TUI 和 RPC 模式下都能工作的对话框方法（select, confirm, input, editor）和即发即弃方法（notify, setStatus, setWidget, setTitle, setEditorText）。在 RPC 模式下，某些特定于 TUI 的方法是无操作或返回默认值（参见 rpc.md）。

ctx.cwd

当前工作目录。

使用 CONFIG_DIR_NAME 而不是硬编码 .pi 来构建项目本地的配置路径。重新分发的发行版可能使用不同的配置目录名称。

import { CONFIG_DIR_NAME, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { join } from "node:path";

export default function (pi: ExtensionAPI) {
  pi.on("session_start", (_event, ctx) => {
    const projectConfigPath = join(ctx.cwd, CONFIG_DIR_NAME, "my-extension.json");
    // ...
  });
}

ctx.isProjectTrusted()

返回当前会话上下文的项目本地信任是否活跃。这包括临时信任决策和 CLI 信任覆盖，而不仅仅是全局信任存储中的已保存决策。

在读取项目本地扩展配置之前使用它，这些配置只应在受信任的项目中被尊重。

ctx.sessionManager

对会话状态的只读访问。有关完整的 SessionManager API 和条目类型，请参阅 Session Format。

对于 tool_call，此状态在处理程序运行之前通过当前助手消息进行同步。在并行工具执行模式下，仍然不能保证包括来自同一助手消息的兄弟工具结果。

ctx.sessionManager.getEntries()             // 所有条目
ctx.sessionManager.getBranch()              // 当前分支
ctx.sessionManager.buildContextEntries()    // 应用了压缩的活跃分支条目
ctx.sessionManager.getLeafId()              // 当前叶子条目 ID

ctx.modelRegistry / ctx.model / ctx.thinkingLevel / ctx.scopedModels

访问模型、提供者和已解析的身份验证。ctx.modelRegistry.getProvider(id) 返回有效的 pi-ai 提供者，而 getProviderAuth(id) 解析其当前 API 密钥、头部、基础 URL 和提供者范围的环境，无需加载模型。ctx.model 是活跃模型，ctx.thinkingLevel 是其当前有效的思考级别。

ctx.scopedModels 是限定在当前会话范围内的模型的只读列表——与 /scoped-models 命令显示的集合相同。它在会话启动时从 --models CLI 标志和 enabledModels 设置中解析（对可用目录进行 minimatch 匹配，使用 provider/modelId 或纯 modelId）。当没有配置作用域时为空，意味着每个可用模型都是可用的。每个条目是 { model, thinkingLevel? }，其中 thinkingLevel 仅当模式固定了它时才设置（例如 anthropic/*:high）。使用它来填充镜像内置模型选择器的模型选择器，而不是通过 ctx.modelRegistry.getAvailable() 枚举整个目录。

ctx.signal

当前的 agent 中止信号，如果没有活跃的 agent 轮次则为 undefined。

将其用于由扩展处理程序启动的、支持中止的嵌套工作，例如：

• fetch(..., { signal: ctx.signal })
• 接受 signal 的模型调用
• 接受 AbortSignal 的文件或进程帮助方法

ctx.signal 通常在活跃轮次事件中定义，例如 tool_call、tool_result、message_update 和 turn_end。在空闲或非轮次上下文中通常为 undefined，例如会话事件、扩展命令以及 pi 空闲时触发的快捷键。

pi.on("tool_result", async (event, ctx) => {
  const response = await fetch("https://example.com/api", {
    method: "POST",
    body: JSON.stringify(event),
    signal: ctx.signal,
  });

  const data = await response.json();
  return { details: data };
});

ctx.isIdle() / ctx.abort() / ctx.hasPendingMessages()

控制流帮助方法。当 Pi 正在处理 agent 运行、自动重试、自动压缩重试或排队延续时，ctx.isIdle() 为 false。

ctx.shutdown()

请求优雅关闭 pi。

• 交互模式： 延迟到 agent 变为空闲（处理完所有排队的 steer 和 follow-up 消息后）。
• RPC 模式： 延迟到下一个空闲状态（完成当前命令响应后，等待下一个命令时）。
• 打印模式： 无操作。进程在处理完所有提示后自动退出。

在退出前向所有扩展发出 session_shutdown 事件。在所有上下文中可用（事件处理程序、工具、命令、快捷键）。

pi.on("tool_call", (event, ctx) => {
  if (isFatal(event.input)) {
    ctx.shutdown();
  }
});

ctx.getContextUsage()

返回活跃模型的当前上下文使用情况。如果可用，使用最后一次助手的 usage，然后估计尾部消息的 tokens。

const usage = ctx.getContextUsage();
if (usage && usage.tokens > 100_000) {
  // ...
}

ctx.compact()

触发压缩而不等待完成。使用 onComplete 和 onError 进行后续操作。

ctx.compact({
  customInstructions: "Focus on recent changes",
  onComplete: (result) => {
    ctx.ui.notify("Compaction completed", "info");
  },
  onError: (error) => {
    ctx.ui.notify(`Compaction failed: ${error.message}`, "error");
  },
});

ctx.getSystemPrompt()

返回 Pi 当前的系统提示字符串。

• 在 before_agent_start 期间，这反映了当前轮次到目前为止所做的链接系统提示更改。
• 它不包括后面的 context 消息修改。
• 它不包括 before_provider_request 有效负载重写。
• 如果在你的扩展之后加载了其他扩展，它们仍然可以更改最终发送的内容。

pi.on("before_agent_start", (event, ctx) => {
  const prompt = ctx.getSystemPrompt();
  console.log(`System prompt length: ${prompt.length}`);
});

ExtensionCommandContext

命令处理程序接收 ExtensionCommandContext，它扩展了 ExtensionContext 并包含会话控制方法。这些仅在命令中可用，因为如果从事件处理程序调用它们可能会导致死锁。

ctx.getSystemPromptOptions()

返回 Pi 当前用于构建系统提示的基本输入。

const options = ctx.getSystemPromptOptions();
const contextPaths = options.contextFiles?.map((file) => file.path) ?? [];

它具有与 before_agent_start 的 event.systemPromptOptions 相同的形状和可变性：自定义提示、活跃工具、工具片段、提示准则、附加的系统提示文本、cwd、已加载的上下文文件和已加载的技能。它可能包含完整的上下文文件内容，因此将其视为敏感的扩展本地数据，并避免通过命令列表、日志或自动完成元数据暴露它。

这报告当前的基本提示输入。它不包括每轮的 before_agent_start 链接系统提示更改、后面的 context 事件消息修改或 before_provider_request 有效负载重写。

ctx.waitForIdle()

等待 agent 完全稳定，包括自动重试、自动压缩重试和排队延续：

pi.registerCommand("my-cmd", {
  handler: async (args, ctx) => {
    await ctx.waitForIdle();
    // Agent 现在空闲，可以安全修改会话
  },
});

ctx.newSession(options?)

创建一个新会话：

const parentSession = ctx.sessionManager.getSessionFile();
const kickoff = "Continue in the replacement session";

const result = await ctx.newSession({
  parentSession,
  setup: async (sm) => {
    sm.appendMessage({
      role: "user",
      content: [{ type: "text", text: "Context from previous session..." }],
      timestamp: Date.now(),
    });
  },
  withSession: async (ctx) => {
    // 仅在此处使用替换会话的 ctx。
    await ctx.sendUserMessage(kickoff);
  },
});

if (result.cancelled) {
  // 扩展取消了新会话
}

选项：

• parentSession：要在新会话头部中记录的父会话文件
• setup：在 withSession 运行之前修改新会话的 SessionManager
• withSession：针对新鲜的替换会话上下文运行切换后工作。不要使用捕获的旧 pi / 命令 ctx；请参阅 会话替换生命周期和陷阱。

ctx.fork(entryId, options?)

从特定条目分叉，创建一个新的会话文件：

const result = await ctx.fork("entry-id-123", {
  withSession: async (ctx) => {
    // 仅在此处使用替换会话的 ctx。
    ctx.ui.notify("Now in the forked session", "info");
  },
});
if (result.cancelled) {
  // 扩展取消了分叉
}

const cloneResult = await ctx.fork("entry-id-456", { position: "at" });
if (result.cancelled) {
  // 扩展取消了克隆
}

选项：

• position："before"（默认）在所选用户消息之前分叉，将该提示恢复到编辑器
• position："at" 复制通过所选条目的活动路径，而不恢复编辑器文本
• withSession：针对新鲜的替换会话上下文运行切换后工作。不要使用捕获的旧 pi / 命令 ctx；请参阅 会话替换生命周期和陷阱。

ctx.navigateTree(targetId, options?)

导航到会话树中的不同点：

const result = await ctx.navigateTree("entry-id-456", {
  summarize: true,
  customInstructions: "Focus on error handling changes",
  replaceInstructions: false, // true = 完全替换默认提示
  label: "review-checkpoint",
});

选项：

• summarize：是否生成已放弃分支的摘要
• customInstructions：摘要器的自定义指令
• replaceInstructions：如果为 true，customInstructions 替换默认提示而不是附加
• label：附加到分支摘要条目的标签（如果不生成摘要，则附加到目标条目）

ctx.switchSession(sessionPath, options?)

切换到不同的会话文件：

const result = await ctx.switchSession("/path/to/session.jsonl", {
  withSession: async (ctx) => {
    await ctx.sendUserMessage("Resume work in the replacement session");
  },
});
if (result.cancelled) {
  // 扩展通过 session_before_switch 取消了切换
}

选项：

• withSession：针对新鲜的替换会话上下文运行切换后工作。不要使用捕获的旧 pi / 命令 ctx；请参阅 会话替换生命周期和陷阱。

要发现可用会话，请使用静态方法 SessionManager.list() 或 SessionManager.listAll()：

import { SessionManager } from "@earendil-works/pi-coding-agent";

pi.registerCommand("switch", {
  description: "Switch to another session",
  handler: async (args, ctx) => {
    const sessions = await SessionManager.list(ctx.cwd);
    if (sessions.length === 0) return;
    const choice = await ctx.ui.select(
      "Pick session:",
      sessions.map(s => s.file),
    );
    if (choice) {
      await ctx.switchSession(choice, {
        withSession: async (ctx) => {
          ctx.ui.notify("Switched session", "info");
        },
      });
    }
  },
});

会话替换生命周期和陷阱

withSession 接收一个新鲜的 ReplacedSessionContext，它扩展了 ExtensionCommandContext 并包含绑定到替换会话的异步 sendMessage() 和 sendUserMessage() 帮助方法。

生命周期和陷阱：

• withSession 仅在旧会话发出 session_shutdown、旧运行时被拆除、替换会话被重新绑定并且新的扩展实例已经接收到 session_start 之后运行。
• 回调仍然在原始闭包中执行，而不是在新的扩展实例内部。这意味着你的旧扩展实例可能在 withSession 开始之前已经运行了其关闭清理。
• 捕获的旧 pi / 旧命令 ctx 的会话绑定对象在替换后已过时，使用时会抛出异常。仅对会话绑定的工作使用传递给 withSession 的 ctx。
• 以前提取的原始对象仍然是你的责任。例如，如果你在替换之前捕获了 const sm = ctx.sessionManager，那么 sm 仍然是旧的 SessionManager 对象。替换后不要重复使用它。
• withSession 中的代码应假定任何由你的 session_shutdown 处理程序失效的状态已经消失。仅捕获能够干净存活于关闭状态的纯数据，例如字符串、ID 和序列化配置。

安全模式：

pi.registerCommand("handoff", {
  handler: async (_args, ctx) => {
    const kickoff = "Continue from the replacement session";
    await ctx.newSession({
      withSession: async (ctx) => {
        await ctx.sendUserMessage(kickoff);
      },
    });
  },
});

不安全模式：

pi.registerCommand("handoff", {
  handler: async (_args, ctx) => {
    const oldSessionManager = ctx.sessionManager;
    await ctx.newSession({
      withSession: async (_ctx) => {
        // 过时的旧对象：不要这样做
        oldSessionManager.getSessionFile();
        pi.sendUserMessage("wrong");
      },
    });
  },
});

ctx.reload()

运行与 /reload 相同的重载流程。

pi.registerCommand("reload-runtime", {
  description: "Reload extensions, skills, prompts, themes, and context files",
  handler: async (_args, ctx) => {
    await ctx.reload();
    return;
  },
});

重要行为：

• await ctx.reload() 为当前扩展运行时发出 session_shutdown
• 然后它重载资源并发出带有 reason: "reload" 的 session_start 和带有原因 "reload" 的 resources_discover
• 当前正在运行的命令处理程序仍然在旧的调用帧中继续
• await ctx.reload() 之后的代码仍然从重载前的版本运行
• await ctx.reload() 之后的代码不能假定旧的内存中扩展状态仍然有效
• 在处理程序返回后，未来的命令/事件/工具调用使用新的扩展版本

为获得可预测的行为，将重载视为该处理程序的终止点（await ctx.reload(); return;）。

工具使用 ExtensionContext 运行，因此它们不能直接调用 ctx.reload()。使用命令作为重载入口点，然后暴露一个将该命令排队为后续用户消息的工具。

示例工具 LLM 可以调用以触发重载：

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";

export default function (pi: ExtensionAPI) {
  pi.registerCommand("reload-runtime", {
    description: "Reload extensions, skills, prompts, themes, and context files",
    handler: async (_args, ctx) => {
      await ctx.reload();
      return;
    },
  });

  pi.registerTool({
    name: "reload_runtime",
    label: "Reload Runtime",
    description: "Reload extensions, skills, prompts, themes, and context files",
    parameters: Type.Object({}),
    async execute() {
      pi.sendUserMessage("/reload-runtime", { deliverAs: "followUp" });
      return {
        content: [{ type: "text", text: "Queued /reload-runtime as a follow-up command." }],
      };
    },
  });
}

ExtensionAPI 方法

pi.on(event, handler)

订阅事件。有关事件类型和返回值，请参阅 事件。

pi.registerTool(definition)

注册 LLM 可调用的自定义工具。有关完整详细信息，请参阅 自定义工具。

pi.registerTool() 在扩展加载期间和启动后都可以工作。你可以在 session_start、命令处理程序或其他事件处理程序内部调用它。新工具会立即在同一个会话中刷新，因此它们会出现在 pi.getAllTools() 中，并且无需 /reload 即可被 LLM 调用。

使用 pi.setActiveTools() 在运行时启用或禁用工具（包括动态添加的工具）。

使用 promptSnippet 选择自定义工具在 Available tools 中作为一行条目，使用 promptGuidelines 在该工具活跃时向默认的 Guidelines 部分添加特定于工具的要点。

重要： promptGuidelines 要点被扁平附加到 Guidelines 部分，没有工具名称前缀。每个准则必须命名它所指的工具——避免“Use this tool when...”因为 LLM 无法判断“this”指的是哪个工具。请改为写“Use my_tool when...”。

有关完整示例，请参阅 dynamic-tools.ts。

import { Type } from "typebox";
import { StringEnum } from "@earendil-works/pi-ai";

pi.registerTool({
  name: "my_tool",
  label: "My Tool",
  description: "What this tool does",
  promptSnippet: "Summarize or transform text according to action",
  promptGuidelines: ["Use my_tool when the user asks to summarize previously generated text."],
  parameters: Type.Object({
    action: StringEnum(["list", "add"] as const),
    text: Type.Optional(Type.String()),
  }),
  prepareArguments(args) {
    // 可选的兼容性垫片。在 schema 验证之抢跑。
    // 返回当前 schema 形状，例如将旧字段折叠到现代参数对象中。
    return args;
  },

  async execute(toolCallId, params, signal, onUpdate, ctx) {
    // 流式进度
    onUpdate?.({ content: [{ type: "text", text: "Working..." }] });

    return {
      content: [{ type: "text", text: "Done" }],
      details: { result: "..." },
    };
  },

  // 可选：自定义渲染
  renderCall(args, theme, context) { ... },
  renderResult(result, options, theme, context) { ... },
});

pi.sendMessage(message, options?)

将会话中的自定义消息注入。自定义消息参与 LLM 上下文。对于不应发送给 LLM 的持久 TUI 内容，请使用 pi.appendEntry() 配合 pi.registerEntryRenderer()。

pi.sendMessage({
  customType: "my-extension",
  content: "Message text",
  display: true,
  details: { ... },
}, {
  triggerTurn: true,
  deliverAs: "steer",
});

选项：

• deliverAs - 传递模式：
  • "steer"（默认）- 在流式传输时排队消息。在当前助手轮次完成其工具调用后、在下一次 LLM 调用之前传递。
  • "followUp" - 等待 agent 完成。仅在 agent 没有更多工具调用时传递。
  • "nextTurn" - 为下一个用户提示排队。不中断或触发任何操作。
• triggerTurn: true - 如果 agent 空闲，立即触发 LLM 响应。仅适用于 "steer" 和 "followUp" 模式（对于 "nextTurn" 忽略）。

pi.sendUserMessage(content, options?)

向 agent 发送用户消息。与发送自定义消息的 sendMessage() 不同，这发送一条实际用户消息，看起来就像用户输入的一样。总是触发一个轮次。

// 简单文本消息
pi.sendUserMessage("What is 2+2?");

// 使用内容数组（文本 + 图像）
pi.sendUserMessage([
  { type: "text", text: "Describe this image:" },
  { type: "image", source: { type: "base64", mediaType: "image/png", data: "..." } },
]);

// 在流式传输期间 - 必须指定传递模式
pi.sendUserMessage("Focus on error handling", { deliverAs: "steer" });
pi.sendUserMessage("And then summarize", { deliverAs: "followUp" });

选项：

• deliverAs - 当 agent 正在流式传输时需要：
  • "steer" - 排队消息，在当前助手轮次完成其工具调用后传递
  • "followUp" - 等待 agent 完成所有工具

当不流式传输时，消息立即发送并触发一个新的轮次。当流式传输时没有 deliverAs，则抛出错误。

请参阅 send-user-message.ts 获取完整示例。

pi.appendEntry(customType, data?)

持久化扩展数据。自定义条目不参与 LLM 上下文。在交互模式下，当与 pi.registerEntryRenderer() 配对时，它们也可以在聊天记录中渲染。

pi.appendEntry("my-state", { count: 42 });
pi.appendEntry("status-card", { title: "Indexed files", count: 17 });

// 在重载时恢复
pi.on("session_start", async (_event, ctx) => {
  for (const entry of ctx.sessionManager.getEntries()) {
    if (entry.type === "custom" && entry.customType === "my-state") {
      // 从 entry.data 重建
    }
  }
});

pi.setSessionName(name)

设置会话显示名称（在会话选择器中显示，而不是第一条消息）。

pi.setSessionName("Refactor auth module");

pi.getSessionName()

获取当前会话名称（如果已设置）。

const name = pi.getSessionName();
if (name) {
  console.log(`Session: ${name}`);
}

pi.setLabel(entryId, label)

设置或清除条目标签。标签是用户定义的标记，用于书签和导航（在 /tree 选择器中显示）。

// 设置标签
pi.setLabel(entryId, "checkpoint-before-refactor");

// 清除标签
pi.setLabel(entryId, undefined);

// 通过 sessionManager 读取标签
const label = ctx.sessionManager.getLabel(entryId);

标签在会话中持久存在，并在重启后存活。使用它们在对话树中标记重要点（轮次、检查点）。

pi.registerCommand(name, options)

注册一个命令。

如果多个扩展注册了相同的命令名称，pi 会保留它们所有，并按加载顺序分配数字调用后缀，例如 /review:1 和 /review:2。

pi.registerCommand("stats", {
  description: "Show session statistics",
  handler: async (args, ctx) => {
    const count = ctx.sessionManager.getEntries().length;
    ctx.ui.notify(`${count} entries`, "info");
  }
});

可选：为 /command ... 添加参数自动完成：

import type { AutocompleteItem } from "@earendil-works/pi-tui";

pi.registerCommand("deploy", {
  description: "Deploy to an environment",
  getArgumentCompletions: (prefix: string): AutocompleteItem[] | null => {
    const envs = ["dev", "staging", "prod"];
    const items = envs.map((e) => ({ value: e, label: e }));
    const filtered = items.filter((i) => i.value.startsWith(prefix));
    return filtered.length > 0 ? filtered : null;
  },
  handler: async (args, ctx) => {
    ctx.ui.notify(`Deploying: ${args}`, "info");
  },
});

pi.getCommands()

获取当前会话中可通过 prompt 调用的斜杠命令。包括扩展命令、提示模板和技能命令。该列表匹配 RPC get_commands 的顺序：首先是扩展，然后是模板，然后是技能。

const commands = pi.getCommands();
const bySource = commands.filter((command) => command.source === "extension");
const userScoped = commands.filter((command) => command.sourceInfo.scope === "user");

每个条目具有以下形状：

{
  name: string; // 可调用的命令名称，不带前导斜杠。可能带有后缀，如 "review:1"
  description?: string;
  source: "extension" | "prompt" | "skill";
  sourceInfo: {
    path: string;
    source: string;
    scope: "user" | "project" | "temporary";
    origin: "package" | "top-level";
    baseDir?: string;
  };
}

使用 sourceInfo 作为规范的来源字段。不要从命令名称或临时路径解析推断所有权。

内置交互命令（如 /model 和 /settings）不在此包含。它们仅在交互模式下处理，如果通过 prompt 发送则不会执行。

pi.registerMessageRenderer(customType, renderer)

为具有你的 customType 的自定义消息注册自定义 TUI 渲染器。自定义消息通过 pi.sendMessage() 创建，并参与 LLM 上下文。参见 自定义 UI。

pi.registerEntryRenderer(customType, renderer)

为具有你的 customType 的自定义条目注册自定义 TUI 渲染器。自定义条目通过 pi.appendEntry() 创建，不参与 LLM 上下文。

import { Box, Text } from "@earendil-works/pi-tui";

pi.registerEntryRenderer("status-card", (entry, { expanded }, theme) => {
  const data = entry.data as { title: string; count: number };
  const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
  box.addChild(new Text(`${theme.bold(data.title)}: ${data.count}`));
  if (expanded) {
    box.addChild(new Text(theme.fg("dim", JSON.stringify(data, null, 2))));
  }
  return box;
});

pi.appendEntry("status-card", { title: "Indexed files", count: 17 });

pi.registerShortcut(shortcut, options)

注册键盘快捷键。有关快捷键格式和内置键绑定，请参阅 keybindings.md。

pi.registerShortcut("ctrl+shift+p", {
  description: "Toggle plan mode",
  handler: async (ctx) => {
    ctx.ui.notify("Toggled!");
  },
});

pi.registerFlag(name, options)

注册 CLI 标志。

pi.registerFlag("plan", {
  description: "Start in plan mode",
  type: "boolean",
  default: false,
});

// 检查值
if (pi.getFlag("plan")) {
  // Plan mode enabled
}

pi.exec(command, args, options?)

执行 shell 命令。

const result = await pi.exec("git", ["status"], { signal, timeout: 5000 });
// result.stdout, result.stderr, result.code, result.killed

pi.getActiveTools() / pi.getAllTools() / pi.setActiveTools(names)

管理活跃工具。这对内置工具和动态注册的工具都有效。pi.getActiveTools() 以 string[] 形式返回活跃工具名称；pi.getAllTools() 返回所有已配置工具的元数据。

const active = pi.getActiveTools(); // ["read", "bash", ...]
const all = pi.getAllTools();
// all = [{
//   name: "read",
//   description: "Read file contents...",
//   parameters: ...,
//   promptGuidelines: ["Use read to examine files instead of cat or sed."],
//   sourceInfo: { path: "<builtin:read>", source: "builtin", scope: "temporary", origin: "top-level" }
// }, ...]
const builtinTools = all.filter((t) => t.sourceInfo.source === "builtin");
const extensionTools = all.filter((t) => t.sourceInfo.source !== "builtin" && t.sourceInfo.source !== "sdk");
pi.setActiveTools([...new Set([...active, "my_custom_tool"])]); // 保持当前工具并启用 my_custom_tool
pi.setActiveTools(["read", "bash"]); // 切换到只读

pi.getAllTools() 返回 name, description, parameters, promptGuidelines 和 sourceInfo。

典型的 sourceInfo.source 值：

• builtin 用于内置工具
• sdk 用于通过 createAgentSession({ customTools }) 传递的工具
• 扩展来源元数据用于扩展注册的工具

pi.setModel(model)

设置当前模型。如果没有该模型的 API 密钥，则返回 false。有关配置自定义模型，请参阅 models.md。

const model = ctx.modelRegistry.find("anthropic", "claude-sonnet-4-5");
if (model) {
  const success = await pi.setModel(model);
  if (!success) {
    ctx.ui.notify("No API key for this model", "error");
  }
}

pi.getThinkingLevel() / pi.setThinkingLevel(level)

获取或设置思考级别。级别会被限制在模型能力范围内（非推理模型始终使用 "off"）。更改会触发 thinking_level_select。

const current = pi.getThinkingLevel();  // "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max"
pi.setThinkingLevel("high");

pi.events

用于扩展间通信的共享事件总线：

pi.events.on("my:event", (data) => { ... });
pi.events.emit("my:event", { ... });

pi.registerProvider(name, config)

动态注册或覆盖模型提供者。适用于代理、自定义端点或团队范围的模型配置。

在扩展工厂函数期间进行的调用会被排队，并在运行器初始化时应用。之后进行的调用——例如来自用户设置流程之后的命令处理程序——会立即生效，无需 /reload。

动态提供者可以实现 refreshModels。Pi 在模型刷新时调用它，通过提供者同步发布返回的列表，并传递规范的 credential/store/network/signal 上下文。扩展决定是否通过 context.store 持久化目录；像 llama.cpp 这样的实时服务器可以忽略它。

需要原生提供者认证、过滤、刷新或流行为的扩展可以注册一个完整的来自 @earendil-works/pi-ai 的 Provider。该提供者成为组合基础，并且 models.json 覆盖仍然在其之上应用。

import { createProvider, openAICompletionsApi } from "@earendil-works/pi-ai";

const provider = createProvider({
  id: "local-server",
  name: "Local Server",
  baseUrl: "http://localhost:8080/v1",
  auth: {
    apiKey: {
      name: "Local server setup",
      async login(interaction) {
        return {
          type: "api_key",
          key: await interaction.prompt({ type: "secret", message: "API key" }),
        };
      },
      async resolve({ credential }) {
        return credential?.key
          ? { auth: { apiKey: credential.key }, source: "stored API key" }
          : undefined;
      },
    },
  },
  models: [],
  api: openAICompletionsApi(),
});

pi.registerProvider(provider);

// 注册带有自定义模型的新提供者
pi.registerProvider("my-proxy", {
  name: "My Proxy",
  baseUrl: "https://proxy.example.com",
  apiKey: "$PROXY_API_KEY",  // 环境变量引用
  api: "anthropic-messages",
  models: [
    {
      id: "claude-sonnet-4-20250514",
      name: "Claude 4 Sonnet (proxy)",
      reasoning: false,
      input: ["text", "image"],
      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
      contextWindow: 200000,
      maxTokens: 16384
    }
  ]
});

// 注册实时 llama.cpp 目录，不持久化发现的模型
pi.registerProvider("llama.cpp", {
  baseUrl: "http://localhost:8080/v1",
  apiKey: "local",
  api: "openai-completions",
  async refreshModels({ signal }) {
    const response = await fetch("http://localhost:8080/v1/models", { signal });
    const { data } = await response.json();
    return data.map(({ id }) => ({
      id,
      name: id,
      reasoning: false,
      input: ["text"],
      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
      contextWindow: 128000,
      maxTokens: 16384
    }));
  }
});

// 覆盖现有提供者的 baseUrl（保留所有模型）
pi.registerProvider("anthropic", {
  baseUrl: "https://proxy.example.com"
});

// 注册支持 OAuth 的提供者用于 /login
pi.registerProvider("corporate-ai", {
  baseUrl: "https://ai.corp.com",
  api: "openai-responses",
  models: [...],
  oauth: {
    name: "Corporate AI (SSO)",
    async login(callbacks) {
      // 自定义 OAuth 流程
      callbacks.onAuth({ url: "https://sso.corp.com/..." });
      const code = await callbacks.onPrompt({ message: "Enter code:" });
      return { refresh: code, access: code, expires: Date.now() + 3600000 };
    },
    async refreshToken(credentials) {
      // 刷新逻辑
      return credentials;
    },
    getApiKey(credentials) {
      return credentials.access;
    }
  }
});

对象形式接受完整的 pi-ai Provider，包括原生 auth、getModels、refreshModels、filterModels、stream 和 streamSimple 行为。

遗留配置选项：

• name - 在 UI（如 /login）中显示的提供者名称。
• baseUrl - API 端点 URL。定义模型时需要。
• apiKey - API 密钥字面量、环境插值（$ENV_VAR 或 ${ENV_VAR}）或前导 !command。定义模型时需要（除非提供了 oauth）。$$ 转义 $，$! 转义字面量 ! 而不触发命令执行。
• api - API 类型："anthropic-messages", "openai-completions", "openai-responses" 等。
• headers - 要包含在请求中的自定义头部。
• authHeader - 如果为 true，自动添加 Authorization: Bearer 头部。
• models - 模型定义数组。如果提供，替换此提供者的所有现有模型。模型定义可以设置 baseUrl 以覆盖该模型的提供者端点。
• refreshModels - 异步动态发现回调。其返回的模型替换扩展提供的模型。仅当结果应持久化时使用限定的 context.store。
• oauth - 支持 /login 的 OAuth 提供者配置。提供时，提供者会出现在登录菜单中。
• streamSimple - 用于非标准 API 的自定义流实现。

有关高级主题，请参阅 custom-provider.md：自定义流 API、OAuth 详细信息、模型定义参考。

pi.unregisterProvider(name)

删除先前注册的提供者及其模型。被提供者覆盖的内置模型会恢复。如果提供者未注册，则无效。

与 registerProvider 一样，在初始加载阶段之后调用时立即生效，因此不需要 /reload。

pi.registerCommand("my-setup-teardown", {
  description: "Remove the custom proxy provider",
  handler: async (_args, _ctx) => {
    pi.unregisterProvider("my-proxy");
  },
});

状态管理

有状态的扩展应该将状态存储在工具结果 details 中，以支持正确的分支：

export default function (pi: ExtensionAPI) {
  let items: string[] = [];

  // 从会话重建状态
  pi.on("session_start", async (_event, ctx) => {
    items = [];
    for (const entry of ctx.sessionManager.getBranch()) {
      if (entry.type === "message" && entry.message.role === "toolResult") {
        if (entry.message.toolName === "my_tool") {
          items = entry.message.details?.items ?? [];
        }
      }
    }
  });

  pi.registerTool({
    name: "my_tool",
    // ...
    async execute(toolCallId, params, signal, onUpdate, ctx) {
      items.push("new item");
      return {
        content: [{ type: "text", text: "Added" }],
        details: { items: [...items] },  // 存储用于重建
      };
    },
  });
}

自定义工具

通过 pi.registerTool() 注册 LLM 可调用的工具。工具出现在系统提示中，并且可以具有自定义渲染。

使用 promptSnippet 在默认系统提示的 Available tools 部分中获取简短的一行条目。如果省略，自定义工具将被排除在该部分之外。

使用 promptGuidelines 向默认系统提示的 Guidelines 部分添加特定于工具的要点。这些要点仅在该工具活跃时包含（例如，在 pi.setActiveTools([...]) 之后）。

重要： promptGuidelines 要点被扁平附加到 Guidelines 部分，没有工具名称前缀或分组。每个准则必须命名它所指的工具——避免“Use this tool when...”因为 LLM 无法判断“this”指的是哪个工具。请改为写“Use my_tool when...”。

注意：某些模型是白痴，会在工具路径参数中包含 @ 前缀。内置工具在解析路径之前会去除前导 @。如果你的自定义工具接受路径，也请规范化前导 @。

如果你的自定义工具修改文件，请使用 withFileMutationQueue() 使其参与与内置 edit 和 write 相同的按文件队列。这很重要，因为工具调用默认情况下并行运行。没有队列，两个工具可以读取相同的旧文件内容，计算不同的更新，然后最后写入的那个会覆盖另一个。

示例失败情况：你的自定义工具编辑 foo.ts，而内置 edit 也在同一个助手轮次中更改 foo.ts。如果你的工具不参与队列，两者都可以读取原始 foo.ts，应用单独的更改，并且其中一个更改会丢失。

将真实的目标文件路径传递给 withFileMutationQueue()，而不是原始用户参数。首先将其解析为绝对路径，相对于 ctx.cwd 或你工具的工作目录。对于现有文件，帮助方法通过 realpath() 进行规范化，因此同一文件的符号链接别名共享一个队列。对于新文件，它回退到解析的绝对路径，因为还没有东西可以 realpath()。

在该目标路径上排队整个变异窗口。这包括读-修改-写逻辑，而不仅仅是最终的写操作。

import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
import { mkdir, readFile, writeFile } from "node:fs/promises";
import { dirname, resolve } from "node:path";

async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
  const absolutePath = resolve(ctx.cwd, params.path);

  return withFileMutationQueue(absolutePath, async () => {
    await mkdir(dirname(absolutePath), { recursive: true });
    const current = await readFile(absolutePath, "utf8");
    const next = current.replace(params.oldText, params.newText);
    await writeFile(absolutePath, next, "utf8");

    return {
      content: [{ type: "text", text: `Updated ${params.path}` }],
      details: {},
    };
  });
}

工具定义

import { Type } from "typebox";
import { StringEnum } from "@earendil-works/pi-ai";
import { Text } from "@earendil-works/pi-tui";

pi.registerTool({
  name: "my_tool",
  label: "My Tool",
  description: "What this tool does (shown to LLM)",
  promptSnippet: "List or add items in the project todo list",
  promptGuidelines: [
    "Use my_tool for todo planning instead of direct file edits when the user asks for a task list."
  ],
  parameters: Type.Object({
    action: StringEnum(["list", "add"] as const),  // 使用 StringEnum 以确保 Google 兼容性
    text: Type.Optional(Type.String()),
  }),
  prepareArguments(args) {
    if (!args || typeof args !== "object") return args;
    const input = args as { action?: string; oldAction?: string };
    if (typeof input.oldAction === "string" && input.action === undefined) {
      return { ...input, action: input.oldAction };
    }
    return args;
  },

  async execute(toolCallId, params, signal, onUpdate, ctx) {
    // 检查是否取消
    if (signal?.aborted) {
      return { content: [{ type: "text", text: "Cancelled" }] };
    }

    // 流式进度更新
    onUpdate?.({
      content: [{ type: "text", text: "Working..." }],
      details: { progress: 50 },
    });

    // 通过 pi.exec 运行命令（从扩展闭包捕获）
    const result = await pi.exec("some-command", [], { signal });

    // 返回结果
    return {
      content: [{ type: "text", text: "Done" }],  // 发送给 LLM
      details: { data: result },                   // 用于渲染和状态
      // usage: nestedModelResponse.usage,          // 可选的嵌套 LLM usage
      // 可选：当该批次中每个最终确定的工具结果也返回 terminate: true 时，在此工具批次后停止。
      terminate: true,
    };
  },

  // 可选：自定义渲染
  renderCall(args, theme, context) { ... },
  renderResult(result, options, theme, context) { ... },
});

用量核算： 如果工具进行嵌套 LLM 调用，请将其组合的 Usage 作为 usage 返回。Pi 会将其持久化在工具结果上，并包含在页脚、/session 和 RPC 会话总计中。tool_result 处理程序可以检查或替换此值。

错误信号： 要将工具执行标记为失败（在结果上设置 isError: true 并报告给 LLM），请从 execute 抛出错误。返回一个值永远不会设置错误标志，无论你在返回对象中包含什么属性。

提前终止： 从 execute() 返回 terminate: true 以提示应在当前工具批次之后跳过自动后续 LLM 调用。这仅当该批次中每个最终确定的工具结果都是终止性的时才生效。请参阅 examples/extensions/structured-output.ts 获取一个最小示例，其中 agent 在一次最终的结构化输出工具调用后结束。

// 正确：抛出错误以表示错误
async execute(toolCallId, params) {
  if (!isValid(params.input)) {
    throw new Error(`Invalid input: ${params.input}`);
  }
  return { content: [{ type: "text", text: "OK" }], details: {} };
}

重要： 对字符串枚举使用来自 @earendil-works/pi-ai 的 StringEnum。Type.Union/Type.Literal 不适用于 Google 的 API。

参数准备： prepareArguments(args) 是可选的。如果定义，它会在 schema 验证和 execute() 之抢跑。当 pi 恢复一个存储的工具调用参数不再匹配当前 schema 的旧会话时，使用它来模拟旧的接受的输入形状。返回你希望针对 parameters 进行验证的对象。保持公开 schema 严格。不要仅仅为了使旧的恢复会话正常工作而将已弃用的兼容性字段添加到 parameters。

示例：一个旧会话可能包含一个 edit 工具调用，其中包含顶级的 oldText 和 newText，而当前 schema 只接受 edits: [{ oldText, newText }]。

pi.registerTool({
  name: "edit",
  label: "Edit",
  description: "Edit a single file using exact text replacement",
  parameters: Type.Object({
    path: Type.String(),
    edits: Type.Array(
      Type.Object({
        oldText: Type.String(),
        newText: Type.String(),
      }),
    ),
  }),
  prepareArguments(args) {
    if (!args || typeof args !== "object") return args;

    const input = args as {
      path?: string;
      edits?: Array<{ oldText: string; newText: string }>;
      oldText?: unknown;
      newText?: unknown;
    };

    if (typeof input.oldText !== "string" || typeof input.newText !== "string") {
      return args;
    }

    return {
      ...input,
      edits: [...(input.edits ?? []), { oldText: input.oldText, newText: input.newText }],
    };
  },
  async execute(toolCallId, params, signal, onUpdate, ctx) {
    // params 现在匹配当前 schema
    return {
      content: [{ type: "text", text: `Applying ${params.edits.length} edit block(s)` }],
      details: {},
    };
  },
});

覆盖内置工具

扩展可以通过注册同名工具来覆盖内置工具（read, bash, edit, write, grep, find, ls）。交互模式会在发生这种情况时显示警告。

## 扩展的 read 工具替换内置的 read
pi -e ./tool-override.ts

或者，使用 --no-builtin-tools 在没有任何内置工具的情况下启动，同时保持扩展工具启用：

## 没有内置工具，只有扩展工具
pi --no-builtin-tools -e ./my-extension.ts

请参阅 examples/extensions/tool-override.ts 获取一个完整示例，该示例使用日志记录和访问控制覆盖 read。

渲染： 内置渲染器继承按槽位解析。执行覆盖和渲染覆盖是独立的。如果你的覆盖省略了 renderCall，则使用内置的 renderCall。如果你的覆盖省略了 renderResult，则使用内置的 renderResult。如果你的覆盖两者都省略，则自动使用内置渲染器（语法高亮、差异等）。这让你可以包装内置工具以进行日志记录或访问控制，而无需重新实现 UI。

提示元数据： promptSnippet 和 promptGuidelines 不会从内置工具继承。如果你的覆盖应该保留这些提示指令，请在覆盖上显式定义它们。

你的实现必须匹配精确的结果形状，包括 details 类型。UI 和会话逻辑依赖这些形状进行渲染和状态跟踪。

内置工具实现：

• read.ts - ReadToolDetails
• bash.ts - BashToolDetails
• edit.ts
• write.ts
• grep.ts - GrepToolDetails
• find.ts - FindToolDetails
• ls.ts - LsToolDetails

远程执行

内置工具支持可插拔的操作，用于委派给远程系统（SSH、容器等）：

import { createReadTool, createBashTool, type ReadOperations } from "@earendil-works/pi-coding-agent";

// 创建带有自定义操作的工具
const remoteRead = createReadTool(cwd, {
  operations: {
    readFile: (path) => sshExec(remote, `cat ${path}`),
    access: (path) => sshExec(remote, `test -r ${path}`).then(() => {}),
  }
});

// 注册，在执行时检查标志
pi.registerTool({
  ...remoteRead,
  async execute(id, params, signal, onUpdate, _ctx) {
    const ssh = getSshConfig();
    if (ssh) {
      const tool = createReadTool(cwd, { operations: createRemoteOps(ssh) });
      return tool.execute(id, params, signal, onUpdate);
    }
    return localRead.execute(id, params, signal, onUpdate);
  },
});

操作接口： ReadOperations, WriteOperations, EditOperations, BashOperations, LsOperations, GrepOperations, FindOperations

对于 user_bash，扩展可以通过 createLocalBashOperations() 重用 pi 的本地 shell 后端，而不是重新实现本地进程生成、shell 解析和进程树终止。

bash 工具还支持一个 spawn hook，用于在执行前调整命令、cwd 或 env：

import { createBashTool } from "@earendil-works/pi-coding-agent";

const bashTool = createBashTool(cwd, {
  spawnHook: ({ command, cwd, env }) => ({
    command: `source ~/.profile\n${command}`,
    cwd: `/mnt/sandbox${cwd}`,
    env: { ...env, CI: "1" },
  }),
});

createBashTool() 通过 PI_SESSION_ID, PI_SESSION_FILE, PI_PROVIDER, PI_MODEL 和 PI_REASONING_LEVEL 将当前会话暴露给命令。注入发生在 spawnHook 之前，因此 Hook 会收到 env 中的这些值，并在按上述方式展开现有环境时保留它们。设置 exposeSessionEnvironment: false 以禁用它们：

const bashTool = createBashTool(cwd, {
  exposeSessionEnvironment: false,
});

有关变量语义，请参阅 Bash tool session environment。有关包含 --ssh 标志的完整 SSH 示例，请参阅 examples/extensions/ssh.ts。

输出截断

工具必须截断其输出，以避免压倒 LLM 上下文。大型输出可能导致：

• 上下文溢出错误（提示过长）
• 压缩失败
• 模型性能下降

内置限制为 50KB（约 10k tokens）和 2000 行，以先达到者为准。使用导出的截断工具：

import {
  truncateHead,      // 保留前 N 行/字节（适用于文件读取、搜索结果）
  truncateTail,      // 保留后 N 行/字节（适用于日志、命令输出）
  truncateLine,      // 将单行截断到 maxBytes，带省略号
  formatSize,        // 人类可读的大小（例如 "50KB", "1.5MB"）
  DEFAULT_MAX_BYTES, // 50KB
  DEFAULT_MAX_LINES, // 2000
} from "@earendil-works/pi-coding-agent";

async execute(toolCallId, params, signal, onUpdate, ctx) {
  const output = await runCommand();

  // 应用截断
  const truncation = truncateHead(output, {
    maxLines: DEFAULT_MAX_LINES,
    maxBytes: DEFAULT_MAX_BYTES,
  });

  let result = truncation.content;

  if (truncation.truncated) {
    // 将完整输出写入临时文件
    const tempFile = writeTempFile(output);

    // 告知 LLM 在哪里找到完整输出
    result += `\n\n[Output truncated: ${truncation.outputLines} of ${truncation.totalLines} lines`;
    result += ` (${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}).`;
    result += ` Full output saved to: ${tempFile}]`;
  }

  return { content: [{ type: "text", text: result }] };
}

关键点：

• 对开头重要的内容（搜索结果、文件读取）使用 truncateHead
• 对结尾重要的内容（日志、命令输出）使用 truncateTail
• 始终在输出被截断时告知 LLM，以及在哪里可以找到完整版本
• 在工具描述中记录截断限制

请参阅 examples/extensions/truncated-tool.ts 获取包装 rg（ripgrep）并带有适当截断的完整示例。

多个工具

一个扩展可以注册多个具有共享状态的工具：

export default function (pi: ExtensionAPI) {
  let connection = null;

  pi.registerTool({ name: "db_connect", ... });
  pi.registerTool({ name: "db_query", ... });
  pi.registerTool({ name: "db_close", ... });

  pi.on("session_shutdown", async () => {
    connection?.close();
  });
}

自定义渲染

工具可以提供 renderCall 和 renderResult 用于自定义 TUI 显示。有关完整组件 API，请参阅 tui.md；有关工具行如何组合，请参阅 tool-execution.ts。

默认情况下，工具输出包装在一个处理内边距和背景的 Box 中。定义的 renderCall 或 renderResult 必须返回一个 Component。如果某个槽位的渲染器未定义，则 tool-execution.ts 会使用该槽位的回退渲染。

设置 renderShell: "self" 当工具应渲染自己的 shell 而不是使用默认的 Box。这适用于需要完全控制框架或背景行为的工具，例如必须在该工具稳定后保持视觉稳定的大型预览。

pi.registerTool({
  name: "my_tool",
  label: "My Tool",
  description: "Custom shell example",
  parameters: Type.Object({}),
  renderShell: "self",
  async execute() {
    return { content: [{ type: "text", text: "ok" }], details: undefined };
  },
  renderCall(args, theme, context) {
    return new Text(theme.fg("accent", "my custom shell"), 0, 0);
  },
});

renderCall 和 renderResult 各自接收一个 context 对象，其中包含：

• args - 当前工具调用参数
• state - 跨 renderCall 和 renderResult 的共享行本地状态
• lastComponent - 之前为该槽位返回的组件（如果有）
• invalidate() - 请求重新渲染此工具行
• toolCallId, cwd, executionStarted, argsComplete, isPartial, expanded, showImages, isError

使用 context.state 进行跨槽位共享状态。当你希望跨渲染重用和修改同一组件实例时，将槽位本地缓存保留在返回的组件实例上。

renderCall

渲染工具调用或头部：

import { Text } from "@earendil-works/pi-tui";

renderCall(args, theme, context) {
  const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
  let content = theme.fg("toolTitle", theme.bold("my_tool "));
  content += theme.fg("muted", args.action);
  if (args.text) {
    content += " " + theme.fg("dim", `"${args.text}"`);
  }
  text.setText(content);
  return text;
}

renderResult

渲染工具结果或输出：

renderResult(result, { expanded, isPartial }, theme, context) {
  if (isPartial) {
    return new Text(theme.fg("warning", "Processing..."), 0, 0);
  }

  if (result.details?.error) {
    return new Text(theme.fg("error", `Error: ${result.details.error}`), 0, 0);
  }

  let text = theme.fg("success", "✓ Done");
  if (expanded && result.details?.items) {
    for (const item of result.details.items) {
      text += "\n  " + theme.fg("dim", item);
    }
  }
  return new Text(text, 0, 0);
}

如果某个槽位有意没有可见内容，则返回一个空的 Component，例如空的 Container。

键绑定提示

使用 keyHint() 来显示尊重活动键绑定配置的键绑定提示：

import { keyHint } from "@earendil-works/pi-coding-agent";

renderResult(result, { expanded }, theme, context) {
  let text = theme.fg("success", "✓ Done");
  if (!expanded) {
    text += ` (${keyHint("app.tools.expand", "to expand")})`;
  }
  return new Text(text, 0, 0);
}

可用函数：

• keyHint(keybinding, description) - 格式化已配置的键绑定 ID，例如 "app.tools.expand" 或 "tui.select.confirm"
• keyText(keybinding) - 返回键绑定 ID 的原始已配置键文本
• rawKeyHint(key, description) - 格式化原始键字符串

使用命名空间的键绑定 ID：

• Coding-agent ID 使用 app.* 命名空间，例如 app.tools.expand, app.editor.external, app.session.rename
• 共享 TUI ID 使用 tui.* 命名空间，例如 tui.select.confirm, tui.select.cancel, tui.input.tab

有关键绑定 ID 和默认值的详尽列表，请参阅 keybindings.md。keybindings.json 使用这些相同的命名空间 ID。

自定义编辑器和 ctx.ui.custom() 组件接收 keybindings: KeybindingsManager 作为注入参数。它们应直接使用该注入的管理器，而不是调用 getKeybindings() 或 setKeybindings()。

最佳实践

• 使用带有内边距 (0, 0) 的 Text。默认的 Box 处理内边距。
• 使用 \n 实现多行内容。
• 处理 isPartial 以实现流式进度。
• 支持 expanded 以按需提供详细信息。
• 保持默认视图紧凑。
• 在 renderResult 中读取 context.args，而不是将 args 复制到 context.state 中。
• 仅使用 context.state 存储必须在调用和结果槽位之间共享的数据。
• 当同一组件实例可以在原地更新时，重用 context.lastComponent。
• 仅当默认的盒装 shell 妨碍时，才使用 renderShell: "self"。在自 shell 模式下，工具负责自己的框架、内边距和背景。

回退

如果某个槽位的渲染器未定义或抛出异常：

• renderCall：显示工具名称
• renderResult：显示来自 content 的原始文本

动态工具加载

扩展可以注册许多工具，同时只保持一个小的初始集合活跃。然后，工具可以在执行期间通过 pi.setActiveTools() 添加更多工具。Pi 检测纯粹的增加性更改，在该工具结果上记录新可用的工具名称，并在下一次模型请求之前应用更新的活跃集合。

这适用于每个模型。具有原生延迟加载支持的模型保留稳定的提示前缀，并在工具结果位置加载新定义。其他模型使用下面描述的回退。

生命周期是：

1. 使用 pi.registerTool() 注册每个工具，使其出现在 pi.getAllTools() 中。
2. 保持加载器工具（例如 search_tools）活跃，并使可搜索工具不活跃。
3. 在加载器执行期间，调用 pi.setActiveTools([...currentTools, ...matchingTools])。更改必须是增加性的：不要在同一调用中移除当前活跃的工具。
4. Pi 在加载器的工具结果上记录添加了哪些工具。
5. 在下一次模型响应之前，Pi 在支持时使用原生延迟加载暴露添加的定义，否则使用正常的活跃工具列表。

你不需要返回提供者特定的工具引用或将加载器标记为特殊的搜索工具。活跃工具更改就是信号。传递给 pi.setActiveTools() 的名称必须已经注册；未知名称会被忽略。

支持原生延迟加载的模型

• Anthropic
  • 模型： Sonnet, Opus, Fable 版本 4.5 或更新（不含 Haiku）
  • 原生表示： 延迟定义使用 defer_loading；加载点使用 tool_reference 内容。
• OpenAI
  • 模型： gpt-5.4 及更新系列
  • 原生表示： Pi 在加载点添加已完成的客户端 tool_search_call 和 tool_search_output 项。

对于经过验证的自定义模型或代理，可以通过 compat.supportsToolReferences: true（针对 anthropic-messages）或 compat.supportsToolSearch: true（针对 openai-responses 和 openai-codex-responses）启用原生处理。除非端点与模型接受相应的原生协议，否则请保持这些禁用。

回退行为

对于所有其他模型和提供者，动态激活仍然有效：Pi 在下一次请求中正常发送完整的当前活跃工具列表。模型可以调用新激活的工具，但添加它们的定义可能会使提供者的缓存提示前缀失效。

当活跃集合不是纯粹增加性时（例如用另一组工具替换一组工具），Pi 也使用此安全回退。因此，工具移除有效，但它们不使用延迟加载。

为获得最佳缓存行为，保持加载器工具在整个会话期间活跃，并添加工具而不是替换活跃集合。还需注意，激活带有 promptSnippet 或 promptGuidelines 的工具会重建系统提示；即使提供者支持延迟 schema，该系统提示更改也可能使前缀失效。延迟加载的工具通常应依赖其工具 description，并省略仅活跃时的提示元数据。

搜索工具示例

以下扩展注册了两个可搜索工具，将它们从初始活跃集合中移除，并仅保留 search_tools 作为其加载器。该示例使用简单的关键字匹配，但搜索实现可以使用 BM25、嵌入向量、远程目录或项目特定的路由。

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { Type } from "typebox";

const SEARCHABLE_TOOL_NAMES = new Set(["lookup_weather", "search_issues"]);

export default function (pi: ExtensionAPI) {
  pi.registerTool({
    name: "lookup_weather",
    label: "Lookup Weather",
    description: "Look up the current weather for a city",
    parameters: Type.Object({ city: Type.String() }),
    async execute(_toolCallId, params) {
      return {
        content: [{ type: "text", text: `Weather for ${params.city}: sunny` }],
        details: {},
      };
    },
  });

  pi.registerTool({
    name: "search_issues",
    label: "Search Issues",
    description: "Search project issues by keyword",
    parameters: Type.Object({ query: Type.String() }),
    async execute(_toolCallId, params) {
      return {
        content: [{ type: "text", text: `No open issues matching ${params.query}` }],
        details: {},
      };
    },
  });

  pi.registerTool({
    name: "search_tools",
    label: "Search Tools",
    description: "Search for and enable tools relevant to a task",
    promptSnippet: "Search for additional tools when the active tools cannot perform the task",
    promptGuidelines: [
      "Use search_tools when a task requires a capability that is not currently available.",
    ],
    parameters: Type.Object({
      query: Type.String({ description: "Capability or task to search for" }),
      limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 10 })),
    }),
    async execute(_toolCallId, params) {
      const terms = params.query.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
      const matches = pi.getAllTools()
        .filter((tool) => SEARCHABLE_TOOL_NAMES.has(tool.name))
        .map((tool) => ({
          tool,
          score: terms.reduce(
            (score, term) =>
              score + (`${tool.name} ${tool.description}`.toLowerCase().includes(term) ? 1 : 0),
            0,
          ),
        }))
        .filter((match) => match.score > 0)
        .sort((a, b) => b.score - a.score)
        .slice(0, params.limit ?? 3)
        .map((match) => match.tool.name);

      if (matches.length === 0) {
        return {
          content: [{ type: "text", text: `No tools found for: ${params.query}` }],
          details: { matches: [] },
        };
      }

      const active = pi.getActiveTools();
      const added = matches.filter((name) => !active.includes(name));
      pi.setActiveTools([...new Set([...active, ...added])]);

      return {
        content: [{
          type: "text",
          text: added.length > 0
            ? `Loaded tools: ${added.join(", ")}`
            : `Matching tools already active: ${matches.join(", ")}`,
        }],
        details: { matches, added },
      };
    },
  });

  pi.on("session_start", () => {
    // 保持可搜索工具已注册但最初不活跃。保留内置工具和其他扩展拥有的工具，并保持加载器本身活跃。
    const initialTools = pi.getActiveTools().filter(
      (name) => !SEARCHABLE_TOOL_NAMES.has(name),
    );
    pi.setActiveTools([...new Set([...initialTools, "search_tools"])]);
  });
}

当 search_tools 添加一个匹配项时，模型会在紧接着的下一个请求中收到该定义。在具备原生能力的模型上，该定义锚定在搜索结果之后，而不更改初始工具 schema 前缀。在其他模型上，它会在同一个后续请求中出现在正常的工具列表中。

自定义 UI

扩展可以通过 ctx.ui 方法与用户交互，并自定义消息/工具的渲染方式。

有关自定义组件，请参阅 tui.md，其中包含可复制粘贴的模式：

• 选择对话框（SelectList）
• 带取消的异步操作（BorderedLoader）
• 设置开关（SettingsList）
• 状态指示器（setStatus）
• 流式传输期间的工作消息、可见性和指示器（setWorkingMessage, setWorkingVisible, setWorkingIndicator）
• 编辑器上方/下方的小部件（setWidget）
• 在内置斜杠/路径补全之上叠加的自动完成提供者（addAutocompleteProvider）
• 自定义页脚（setFooter）

对话框

// 从选项中选择
const choice = await ctx.ui.select("Pick one:", ["A", "B", "C"]);

// 确认对话框
const ok = await ctx.ui.confirm("Delete?", "This cannot be undone");

// 文本输入
const name = await ctx.ui.input("Name:", "placeholder");

// 多行编辑器
const text = await ctx.ui.editor("Edit:", "prefilled text");

// 通知（非阻塞）
ctx.ui.notify("Done!", "info");  // "info" | "warning" | "error"

带倒计时的定时对话框

对话框支持 timeout 选项，该选项会显示实时倒计时并自动关闭：

// 对话框显示 "Title (5s)" → "Title (4s)" → ... → 在 0 时自动关闭
const confirmed = await ctx.ui.confirm(
  "Timed Confirmation",
  "This dialog will auto-cancel in 5 seconds. Confirm?",
  { timeout: 5000 }
);

if (confirmed) {
  // 用户确认
} else {
  // 用户取消或超时
}

超时时的返回值：

• select() 返回 undefined
• confirm() 返回 false
• input() 返回 undefined

使用 AbortSignal 手动关闭

为了更多控制（例如，区分超时和用户取消），请使用 AbortSignal：

const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 5000);

const confirmed = await ctx.ui.confirm(
  "Timed Confirmation",
  "This dialog will auto-cancel in 5 seconds. Confirm?",
  { signal: controller.signal }
);

clearTimeout(timeoutId);

if (confirmed) {
  // 用户确认
} else if (controller.signal.aborted) {
  // 对话框超时
} else {
  // 用户取消（按下 Escape 或选择 "No"）
}

请参阅 examples/extensions/timed-confirm.ts 获取完整示例。

小部件、状态和页脚

// 页脚中的状态（持久化直到清除）
ctx.ui.setStatus("my-ext", "Processing...");
ctx.ui.setStatus("my-ext", undefined);  // 清除

// 工作加载器（流式传输期间显示）
ctx.ui.setWorkingMessage("Thinking deeply...");
ctx.ui.setWorkingMessage();  // 恢复默认
ctx.ui.setWorkingVisible(false);  // 完全隐藏内置工作加载器行
ctx.ui.setWorkingVisible(true);   // 显示内置工作加载器行

// 工作指示器（流式传输期间显示）
ctx.ui.setWorkingIndicator({ frames: [ctx.ui.theme.fg("accent", "●")] });  // 静态点
ctx.ui.setWorkingIndicator({
  frames: [
    ctx.ui.theme.fg("dim", "·"),
    ctx.ui.theme.fg("muted", "•"),
    ctx.ui.theme.fg("accent", "●"),
    ctx.ui.theme.fg("muted", "•"),
  ],
  intervalMs: 120,
});
ctx.ui.setWorkingIndicator({ frames: [] });  // 隐藏指示器
ctx.ui.setWorkingIndicator();  // 恢复默认旋转器

// 编辑器上方的小部件（默认）
ctx.ui.setWidget("my-widget", ["Line 1", "Line 2"]);
// 编辑器下方的小部件
ctx.ui.setWidget("my-widget", ["Line 1", "Line 2"], { placement: "belowEditor" });
ctx.ui.setWidget("my-widget", (tui, theme) => new Text(theme.fg("accent", "Custom"), 0, 0));
ctx.ui.setWidget("my-widget", undefined);  // 清除

// 自定义页脚（完全替换内置页脚）
ctx.ui.setFooter((tui, theme) => ({
  render(width) { return [theme.fg("dim", "Custom footer")]; },
  invalidate() {},
}));
ctx.ui.setFooter(undefined);  // 恢复内置页脚

// 终端标题
ctx.ui.setTitle("pi - my-project");

// 编辑器文本
ctx.ui.setEditorText("Prefill text");
const current = ctx.ui.getEditorText();

// 粘贴到编辑器（触发粘贴处理，包括对大内容进行折叠）
ctx.ui.pasteToEditor("pasted content");

// 在内置提供者之上堆叠自定义自动完成行为
ctx.ui.addAutocompleteProvider((current) => ({
  triggerCharacters: ["#"],
  async getSuggestions(lines, line, col, options) {
    const beforeCursor = (lines[line] ?? "").slice(0, col);
    const match = beforeCursor.match(/(?:^|[ \t])#([^\s#]*)$/);
    if (!match) {
      return current.getSuggestions(lines, line, col, options);
    }

    return {
      prefix: `#${match[1] ?? ""}`,
      items: [{ value: "#2983", label: "#2983", description: "Extension API for autocomplete" }],
    };
  },
  applyCompletion(lines, line, col, item, prefix) {
    return current.applyCompletion(lines, line, col, item, prefix);
  },
  shouldTriggerFileCompletion(lines, line, col) {
    return current.shouldTriggerFileCompletion?.(lines, line, col) ?? true;
  },
}));

// 工具输出展开
const wasExpanded = ctx.ui.getToolsExpanded();
ctx.ui.setToolsExpanded(true);
ctx.ui.setToolsExpanded(wasExpanded);

// 自定义编辑器（vim 模式、emacs 模式等）
ctx.ui.setEditorComponent((tui, theme, keybindings) => new VimEditor(tui, theme, keybindings));
const currentEditor = ctx.ui.getEditorComponent();
ctx.ui.setEditorComponent((tui, theme, keybindings) =>
  new WrappedEditor(tui, theme, keybindings, currentEditor?.(tui, theme, keybindings))
);
ctx.ui.setEditorComponent(undefined);  // 恢复默认编辑器

// 主题管理（有关创建主题，请参阅 themes.md）
const themes = ctx.ui.getAllThemes();  // [{ name: "dark", path: "/..." | undefined }, ...]
const lightTheme = ctx.ui.getTheme("light");  // 加载而不切换
const result = ctx.ui.setTheme("light");  // 按名称切换
if (!result.success) {
  ctx.ui.notify(`Failed: ${result.error}`, "error");
}
ctx.ui.setTheme(lightTheme!);  // 或者通过 Theme 对象切换
ctx.ui.theme.fg("accent", "styled text");  // 访问当前主题

自定义工作指示器帧会逐字渲染。如果你想要颜色，请自己添加到帧字符串中，例如使用 ctx.ui.theme.fg(...)。

自动完成提供者

使用 ctx.ui.addAutocompleteProvider() 在内置斜杠命令和路径提供者之上堆叠自定义自动完成逻辑。设置 triggerCharacters 以实现自定义的自然触发，例如 $。

典型模式：

• 检查光标前的文本
• 当你的扩展特定语法匹配时，返回你自己的建议
• 否则委托给 current.getSuggestions(...)
• 委托 applyCompletion(...)，除非你需要自定义插入行为

pi.on("session_start", (_event, ctx) => {
  ctx.ui.addAutocompleteProvider((current) => ({
    triggerCharacters: ["#"],
    async getSuggestions(lines, cursorLine, cursorCol, options) {
      const line = lines[cursorLine] ?? "";
      const beforeCursor = line.slice(0, cursorCol);
      const match = beforeCursor.match(/(?:^|[ \t])#([^\s#]*)$/);
      if (!match) {
        return current.getSuggestions(lines, cursorLine, cursorCol, options);
      }

      return {
        prefix: `#${match[1] ?? ""}`,
        items: [
          { value: "#2983", label: "#2983", description: "Extension API for registering custom @ autocomplete providers" },
          { value: "#2753", label: "#2753", description: "Reload stale resource settings" },
        ],
      };
    },

    applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
      return current.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
    },

    shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
      return current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ?? true;
    },
  }));
});

请参阅 github-issue-autocomplete.ts 获取完整示例，该示例使用 gh issue list 预加载最新的开放 GitHub issues，并在本地过滤它们以实现快速的 #... 补全。它需要 GitHub CLI (gh) 和 GitHub 仓库检出。

自定义组件

对于复杂 UI，使用 ctx.ui.custom()。这会临时用你的组件替换编辑器，直到调用 done()：

import { Text, Component } from "@earendil-works/pi-tui";

const result = await ctx.ui.custom<boolean>((tui, theme, keybindings, done) => {
  const text = new Text("Press Enter to confirm, Escape to cancel", 1, 1);

  text.onKey = (key) => {
    if (key === "return") done(true);
    if (key === "escape") done(false);
    return true;
  };

  return text;
});

if (result) {
  // 用户按下了 Enter
}

回调接收：

• tui - TUI 实例（用于屏幕尺寸、焦点管理）
• theme - 用于样式的当前主题
• keybindings - 应用键绑定管理器（用于检查快捷键）
• done(value) - 调用以关闭组件并返回值

请参阅 tui.md 获取完整组件 API。

叠加模式（实验性）

传递 { overlay: true } 将组件渲染为浮动模态框，覆盖在现有内容之上，而不清除屏幕：

const result = await ctx.ui.custom<string | null>(
  (tui, theme, keybindings, done) => new MyOverlayComponent({ onClose: done }),
  { overlay: true }
);

对于高级定位（锚点、边距、百分比、响应式可见性），传递 overlayOptions。使用 onHandle 以编程方式控制焦点或可见性：

const result = await ctx.ui.custom<string | null>(
  (tui, theme, keybindings, done) => new MyOverlayComponent({ onClose: done }),
  {
    overlay: true,
    overlayOptions: { anchor: "top-right", width: "50%", margin: 2 },
    onHandle: (handle) => {
      handle.focus(); // 聚焦此叠加层并将其带到视觉前端
      // handle.unfocus({ target: editorComponent }); // 将输入释放给特定组件
      // handle.setHidden(true/false); // 切换可见性
      // handle.hide(); // 永久移除
    }
  }
);

一个聚焦的可见叠加层可以在临时非叠加自定义 UI 关闭后回收输入。如果你有意希望另一个组件在叠加层保持可见时继续接收输入，请调用 handle.unfocus({ target })。传递 { target: null } 会释放叠加层而不聚焦另一个组件。

请参阅 tui.md 获取完整的 OverlayOptions 和 OverlayHandle API，以及 overlay-qa-tests.ts 获取示例。

自定义编辑器

用自定义实现替换主输入编辑器（vim 模式、emacs 模式等）：

import { CustomEditor, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { matchesKey } from "@earendil-works/pi-tui";

class VimEditor extends CustomEditor {
  private mode: "normal" | "insert" = "insert";

  handleInput(data: string): void {
    if (matchesKey(data, "escape") && this.mode === "insert") {
      this.mode = "normal";
      return;
    }
    if (this.mode === "normal" && data === "i") {
      this.mode = "insert";
      return;
    }
    super.handleInput(data);  // 应用键绑定 + 文本编辑
  }
}

export default function (pi: ExtensionAPI) {
  pi.on("session_start", (_event, ctx) => {
    ctx.ui.setEditorComponent((tui, theme, keybindings) =>
      new VimEditor(tui, theme, keybindings)
    );
  });
}

关键点：

• 继承 CustomEditor（而不是基础 Editor）以获得应用键绑定（escape 中止、ctrl+d、模型切换）
• 对于你不处理的键，调用 super.handleInput(data)
• 工厂从应用接收 tui, theme 和 keybindings
• 在 setEditorComponent() 之前使用 ctx.ui.getEditorComponent() 来包装之前配置的自定义编辑器
• 传递 undefined 以恢复默认：ctx.ui.setEditorComponent(undefined)

要与已经替换了编辑器的另一个扩展组合，在设置你的之前捕获之前的工厂：

const previous = ctx.ui.getEditorComponent();
ctx.ui.setEditorComponent((tui, theme, keybindings) =>
  new MyEditor(tui, theme, keybindings, { base: previous?.(tui, theme, keybindings) })
);

请参阅 tui.md 模式 7 获取带有模式指示器的完整示例。

消息和条目渲染

为具有你的 customType 的消息注册自定义渲染器。对应该参与 LLM 上下文的内容使用消息渲染器：

import { Text } from "@earendil-works/pi-tui";

pi.registerMessageRenderer("my-extension", (message, options, theme) => {
  const { expanded, outputPad } = options;
  let text = theme.fg("accent", `[${message.customType}] `);
  text += message.content;

  if (expanded && message.details) {
    text += "\n" + theme.fg("dim", JSON.stringify(message.details, null, 2));
  }

  return new Text(text, outputPad, 0);
});

消息通过 pi.sendMessage() 发送：

pi.sendMessage({
  customType: "my-extension",  // 匹配 registerMessageRenderer
  content: "Status update",
  display: true,               // 在 TUI 中显示
  details: { ... },            // 在渲染器中可用
});

对于不应发送给 LLM 的 TUI 专用内容，请改为渲染自定义条目：

pi.registerEntryRenderer("my-card", (entry, options, theme) => {
  return new Text(theme.fg("accent", JSON.stringify(entry.data)));
});

pi.appendEntry("my-card", { status: "done" });

主题颜色

所有渲染函数都接收一个 theme 对象。有关创建自定义主题和完整调色板，请参阅 themes.md。

// 前景色
theme.fg("toolTitle", text)   // 工具名称
theme.fg("accent", text)      // 高亮
theme.fg("success", text)     // 成功（绿色）
theme.fg("error", text)       // 错误（红色）
theme.fg("warning", text)     // 警告（黄色）
theme.fg("muted", text)       // 次要文本
theme.fg("dim", text)         // 第三级文本

// 文本样式
theme.bold(text)
theme.italic(text)
theme.strikethrough(text)

在自定义工具渲染器中进行语法高亮：

import { highlightCode, getLanguageFromPath } from "@earendil-works/pi-coding-agent";

// 使用显式语言高亮代码
const highlighted = highlightCode("const x = 1;", "typescript", theme);

// 从文件路径自动检测语言
const lang = getLanguageFromPath("/path/to/file.rs");  // "rust"
const highlighted = highlightCode(code, lang, theme);

错误处理

• 扩展错误会被记录，agent 继续
• tool_call 错误会阻止该工具（故障安全）
• 工具 execute 错误必须通过抛出错误来发出信号；抛出的错误会被捕获，以 isError: true 报告给 LLM，并且执行继续

模式行为

模式	ctx.mode	ctx.hasUI	备注
交互模式	"tui"	true	带有终端渲染的完整 TUI
RPC (--mode rpc)	"rpc"	true	通过 JSON 协议的对话框和通知；custom() 返回 undefined。请参阅 rpc.md
JSON (--mode json)	"json"	false	事件流到 stdout；UI 方法为无操作
打印 (-p)	"print"	false	扩展运行但不能提示

在 TUI 特定特性（custom()、组件工厂、终端输入）之前使用 ctx.mode === "tui"。在同时适用于 TUI 和 RPC 模式的对话框和通知方法之前使用 ctx.hasUI。

示例参考

所有示例位于 examples/extensions/。

示例	描述	关键 API
工具
hello.ts	最小工具注册	registerTool
question.ts	带用户交互的工具	registerTool, ui.select
questionnaire.ts	多步骤向导工具	registerTool, ui.custom
todo.ts	带持久化的有状态工具	registerTool, appendEntry, renderResult, 会话事件
dynamic-tools.ts	在启动后和命令期间注册工具	registerTool, session_start, registerCommand
structured-output.ts	带有 terminate: true 的最终结构化输出工具	registerTool, 终止性工具结果
truncated-tool.ts	输出截断示例	registerTool, truncateHead
tool-override.ts	覆盖内置 read 工具	registerTool（与内置同名）
命令
pirate.ts	每轮修改系统提示	registerCommand, before_agent_start
summarize.ts	对话摘要命令	registerCommand, ui.custom
handoff.ts	跨提供者模型交接	registerCommand, ui.editor, ui.custom
qna.ts	带自定义 UI 的问答	registerCommand, ui.custom, setEditorText
send-user-message.ts	注入用户消息	registerCommand, sendUserMessage
reload-runtime.ts	重载命令和 LLM 工具交接	registerCommand, ctx.reload(), sendUserMessage
shutdown-command.ts	优雅关闭命令	registerCommand, shutdown()
事件与门
permission-gate.ts	阻止危险命令	on("tool_call"), ui.confirm
project-trust.ts	从用户/全局或 CLI 扩展决定或推迟项目信任	on("project_trust"), 信任 UI, 必需的信任结果
protected-paths.ts	阻止写入特定路径	on("tool_call")
confirm-destructive.ts	确认会话更改	on("session_before_switch"), on("session_before_fork")
dirty-repo-guard.ts	在脏 git 仓库时警告	on("session_before_*"), exec
input-transform.ts	转换用户输入	on("input")
input-transform-streaming.ts	流式感知的输入转换	on("input"), streamingBehavior
model-status.ts	对模型更改作出反应	on("model_select"), setStatus
provider-payload.ts	检查有效负载和提供者响应头部	on("before_provider_request"), on("after_provider_response")
system-prompt-header.ts	显示系统提示信息	on("agent_start"), getSystemPrompt
claude-rules.ts	从文件加载规则	on("session_start"), on("before_agent_start")
prompt-customizer.ts	使用 systemPromptOptions 添加上下文感知的工具指南	on("before_agent_start"), BuildSystemPromptOptions
file-trigger.ts	文件监听器触发消息	sendMessage
压缩与会话
custom-compaction.ts	自定义压缩摘要	on("session_before_compact")
trigger-compact.ts	手动触发压缩	compact()
git-checkpoint.ts	每轮 Git stash	on("turn_start"), on("session_before_fork"), exec
git-merge-and-resolve.ts	获取、合并和解决冲突	on("agent_end"), exec, sendUserMessage
auto-commit-on-exit.ts	退出时提交	on("session_shutdown"), exec
UI 组件
status-line.ts	页脚状态指示器	setStatus, 会话事件
working-indicator.ts	自定义流式工作指示器	setWorkingIndicator, registerCommand
github-issue-autocomplete.ts	通过预加载 gh issue list 中的最近开放问题，在内置自动完成之上添加 #1234 issue 补全	addAutocompleteProvider, on("session_start"), exec
custom-footer.ts	完全替换页脚	registerCommand, setFooter
custom-header.ts	替换启动头部	on("session_start"), setHeader
modal-editor.ts	Vim 风格模态编辑器	setEditorComponent, CustomEditor
rainbow-editor.ts	自定义编辑器样式	setEditorComponent
widget-placement.ts	编辑器上方/下方的小部件	setWidget
overlay-test.ts	叠加组件	ui.custom 带叠加选项
overlay-qa-tests.ts	全面的叠加测试	ui.custom, 所有叠加选项
notify.ts	简单通知	ui.notify
timed-confirm.ts	带超时的对话框	ui.confirm 带超时/信号
mac-system-theme.ts	自动切换主题	setTheme, exec
复杂扩展
plan-mode/	完整计划模式实现	所有事件类型, registerCommand, registerShortcut, registerFlag, setStatus, setWidget, sendMessage, setActiveTools
preset.ts	可保存的预设（模型、工具、思考）	registerCommand, registerShortcut, registerFlag, setModel, setActiveTools, setThinkingLevel, appendEntry
tools.ts	打开/关闭工具的 UI	registerCommand, setActiveTools, SettingsList, 会话事件
远程与沙箱
ssh.ts	SSH 远程执行	registerFlag, on("user_bash"), on("before_agent_start"), 工具操作
interactive-shell.ts	持久 shell 会话	on("user_bash")
sandbox/	沙箱化工具执行	工具操作
gondolin/	将内置工具和 ! 命令路由到 Gondolin 微 VM	工具操作, 内置工具覆盖, on("user_bash")
subagent/	生成子 agent	registerTool, exec
游戏
snake.ts	贪吃蛇游戏	registerCommand, ui.custom, 键盘处理
space-invaders.ts	太空入侵者游戏	registerCommand, ui.custom
doom-overlay/	在叠加层中玩 Doom	ui.custom 带叠加
提供者
custom-provider-anthropic/	自定义 Anthropic 代理	registerProvider
custom-provider-gitlab-duo/	GitLab Duo 集成	registerProvider 带 OAuth
消息与通信
message-renderer.ts	自定义消息渲染	registerMessageRenderer, sendMessage
entry-renderer.ts	TUI 专用自定义条目渲染	registerEntryRenderer, appendEntry
event-bus.ts	扩展间事件	pi.events
会话元数据
session-name.ts	为选择器命名会话	setSessionName, getSessionName
bookmark.ts	为 /tree 添加书签	setLabel
杂项
inline-bash.ts	在工具调用中内联 bash	on("tool_call")
bash-spawn-hook.ts	在执行前调整 bash 命令、cwd 和 env	createBashTool, spawnHook
with-deps/	带 npm 依赖的扩展	包结构，包含 package.json

• 原文链接： github.com/badlogic/pi-m...
• 登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～