oh-my-pi 扩展开发教程：TS 模块即扩展，与内置功能同权

oh-my-pi 扩展开发教程TS 模块即扩展与内置功能同权【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pioh-my-piomp是一个内置 IDE 能力的 AI 编码代理支持 60 模型提供商与 31 个内置工具。它的最大亮点之一是扩展开发极其简单一个 TypeScript 模块就是一个扩展。把文件放进指定目录即可注册事件钩子、自定义工具、斜杠命令与内置功能完全同权——这是本文面向新手的 oh-my-pi 扩展开发完整教程。一、什么是TS 模块即扩展在传统插件系统里你可能需要实现一套接口、写清单文件、跑构建脚本。而 oh-my-pi 的扩展只需要满足一个约定模块的默认导出是一个工厂函数。import type { ExtensionAPI } from oh-my-pi/pi-coding-agent; export default function myExtension(pi: ExtensionAPI) { // 在这里注册事件、工具、命令…… }工厂函数接收一个piExtensionAPI对象所有能力都挂在上面。加载流程只有三步发现扫描约定目录找到.ts/.js文件导入用 Bun 直接 import 模块支持 TS 原生无需编译执行工厂注册阶段完成后ExtensionRunner.initialize()接入运行时官方文档docs/extensions.md、加载机制详解见 docs/extension-loading.md。二、扩展放在哪三个自动发现位置 不用任何注册步骤把文件放到以下任一位置就会被自动加载级别路径适用场景项目级项目/.omp/extensions/只对当前仓库生效随代码提交共享用户级~/.omp/agent/extensions/全局生效显式指定命令行-e ./my-ext.ts或配置文件的extensions数组开发调试期最方便配置文件的写法很简单~/.omp/agent/config.ymlextensions: - ~/my-exts/safety.ts - ./local/ext-pack目录形式也支持目录里放index.ts即可若带package.json可用omp.extensions字段声明多个入口文件。加载顺序为项目级 → 用户级 → 插件包 → 显式配置同一路径只加载一次。三、五分钟写出第一个扩展 ✨官方示例 hello-extension 只有 27 行完整覆盖了两大核心能力export default function helloExtension(pi: ExtensionAPI) { // ① 事件监听会话启动时弹一条通知 pi.on(session_start, async (_event, ctx) { ctx.ui.notify(Hello from hello-extension!, info); }); // ② 斜杠命令/hello 向对话中注入一条消息 pi.registerCommand(hello, { description: Send a greeting into the conversation, handler: async (args, ctx) { pi.sendMessage({ content: Hello, ${args}!, display: true }); }, }); }一个模块里可以同时组合 事件处理器pi.on(...)——会话、提示词、工具全生命周期️ LLM 可调用的工具pi.registerTool(...)⌨️ 斜杠命令pi.registerCommand(...)、快捷键、命令行参数 自定义消息渲染器 消息注入 APIsendMessage/sendUserMessage/appendEntry四、与内置功能同权工具、拦截与 UI这是 oh-my-pi 扩展系统的精髓。扩展注册的工具与内置的bash、read、edit走同一条注册表模型调用时完全无法区分而内置工具的执行又全部经过扩展的拦截层。拦截内置工具安全护栏示例官方 safety-hook 示例 展示如何否决内置 bash 工具的调用pi.on(tool_call, async (event) { if (event.toolName ! bash) return; const cmd String(event.input?.command ?? ); if (/\brm\s-rf\s\//.test(cmd)) { return { block: true, reason: refusing to delete root filesystem }; } });tool_call事件支持先执行拦截block阻断或改写inputtool_result支持后执行修补结果内容——对内置和扩展工具一视同仁。包装内置工具而不重写它如果你的扩展工具名与内置工具同名如包装write加日志ctx.invokeTool(...)可以直接委托执行原生实现无需重新实现文件写入逻辑且不会突破审批边界。深入会话与 UI ️ctx.ui.notify/select/confirm/input直接驱动 TUI 对话框与通知pi.sendMessage支持steer打断当前运行、followUp排队、nextTurn下一轮注入三种投递方式pi.appendEntry(...)可把扩展状态持久化进会话切分支/树时自动恢复registerProvider甚至能让扩展注册新的模型提供商用法量显示与内置提供商一致五、加载生命周期两条必须记住的规则 ⚠️注册期 ≠ 运行期工厂函数执行时只能注册此时调用pi.sendMessage()等运行动作会抛出ExtensionRuntimeNotInitializedError。正确姿势是先注册行为放进事件/命令/工具回调。失败相互隔离单个扩展加载失败导入失败、导出不是函数、工厂抛异常只产生一条错误记录不会拖垮其他扩展。另外两个新手常踩的坑后台任务别用裸setInterval扩展在进程内运行、无沙箱隔离裸定时器里抛异常会直接搞崩整个会话。请用ctx.setInterval/ctx.setTimeout异常会被捕获上报且会话结束时自动清理。命令名冲突与内置命令重名时会被跳过并给出诊断ctrlc等保留快捷键不可注册。六、开关与调试 ️目的方法临时禁用全部自动发现启动加--no-extensions显式-e路径仍生效禁用某个扩展配置disabledExtensions: [extension-module:foo]名称取自文件路径开发时热加载直接改文件再启动模块按mtime缓存失效重新导入七、进一步阅读 扩展 API 全量清单事件名、上下文方法、渲染器docs/extensions.md发现路径、加载顺序、失败处理docs/extension-loading.md官方示例hello-extension、safety-hook可运行的 Python/代码执行与图表能力扩展可以围绕它们构建工作流总结在 oh-my-pi 中扩展开发 写一个默认导出工厂函数的 TS 文件 放进.omp/extensions/。事件、工具、命令、UI、甚至提供商注册全部开箱可用且与内置功能同权同拦截。从 hello 到安全护栏最快五分钟即可上手。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考