@pi-web/extension-kit

写 pi 扩展时的编写面 —— 注册斜杠命令、注册带上下文的工具、用 ctx.ui 在 pi-web 的浏览器界面里弹一张交互卡片。

npm i -D @pi-web/extension-kit

扩展文件放在 agent 目录的 .pi/extensions/ 下（由 pi 自己从磁盘装载）：

// .pi-web/agents/my-agent/.pi/extensions/confirm-demo.ts
import { defineExtension } from "@pi-web/extension-kit";

export default defineExtension((pi) => {
  pi.registerCommand("confirm-demo", {
    description: "演示一次确认卡片",
    handler: async (args, ctx) => {
      const ok = await ctx.ui.confirm("Proceed?", args.trim() === "" ? "删除临时文件？" : args);
      ctx.ui.notify(ok ? "好，动手了" : "算了", "info");
    },
  });
});

命令会出现在 Web 界面的命令面板里（来源标为 extension）。★ 扩展命令不产生用户消息、 也不触发一个回合 —— 它只执行你的 handler，所以想在界面上留痕就用 ctx.ui。

与 @pi-web/agent-kit 的分工

| | 用来写 | |---|---| | @pi-web/agent-kit | agent 定义（defineAgent）与简单工具（customTools） | | @pi-web/extension-kit | pi 扩展：注册命令、拿到 ExtensionContext（ctx.ui 等） |

工具定义只差一处：extension 的工具多一个第 5 参数 ctx。agent-kit 刻意省掉它（不把 ExtensionContext 这个巨大的 pi 表面拖进 agent 定义文件），而扩展本来就活在扩展上下文里 —— ctx.ui.confirm 这类交互正是写扩展的理由。

刻意只代理子集

pi 的 ExtensionAPI 有 30+ 个事件重载和十几个方法。全量代理的成本接近把 pi 抄一遍， 且每次 pi 升级都要跟着漂。所以这里是按需扩张：只暴露真正支持、并且在 Web 前端讲得通 的能力。

ctx.ui 收了五个方法，挑选依据就是"能映射成浏览器里的一张内联卡片"：

| | | |---|---| | notify(message, type?) | 单向通知，不等回答 | | confirm(title, message) | → Promise<boolean> | | select(title, options) | → Promise<string \| undefined>（undefined = 用户取消） | | input(title, placeholder?) | → Promise<string \| undefined> |

pi 还有 setStatus / setWidget / onTerminalInput 等终端专属能力，Web 端没有对应物， 故不代理。ExtensionContext 里 pi 的内部对象（sessionManager / modelRegistry / model） 也不代理 —— 暴露它们等于让扩展直接耦合到 pi 的内部结构。

收窄的方向是安全的：pi-web 的 agent-conformance.ts 断言pi 的真实 API 能被看作这个视图， 所以 pi 改了签名或去掉了我们声明的东西 → typecheck 报红。反过来，没声明的东西你拿不到 —— 这是有意的摩擦：支持面是一张显式的表，不是"顺手把整个 pi 暴露出去"。

要用一个还没代理的 pi 能力：往这个包里加声明 + 去 agent-conformance.ts 加一条断言。

导出

defineExtension(factory)（恒等函数，只为类型收窄）+ ExtensionApi / ExtensionContext / ExtensionCommandContext / ExtensionCommand / ExtensionToolDefinition / ExtensionUi / ExtensionFactory 这些类型。

License

MIT