Orca 插件系统入门从零编写你的第一个 Orca 插件完整教程【免费下载链接】orcaOrca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop, mobile and VPS.项目地址: https://gitcode.com/GitHub_Trending/orca48/orcaOrca 插件让每个 Orca 用户都能扩展自己的智能体舰队工作台。Orca 是面向并行编码智能体coding agents的 ADEAgent Development Environment而 Orca 插件系统允许你在不修改主程序的前提下添加自定义面板、命令和事件监听器。本教程带新手从零编写第一个 Orca 插件全程不超过 30 分钟。为什么需要 Orca 插件在使用多智能体并行开发时你常会遇到这些场景想在 Orca 里加一个自定义控制面板一眼看到当前工作区状态希望自动监听事件比如新 worktree 创建时通知我、agent 状态变化时记录日志想给团队分发自己的小工具而不用等待官方版本更新。Orca 插件正是为解决这些问题设计的它是一个独立进程中的 Node 模块 一个沙箱 HTML 面板通过受权限管控的宿主 API 与 Orca 主程序通信。插件架构速览3 个文件搞定一个最简 Orca 插件只需要 3 个文件仓库里就有一个官方示例文件作用参考orca-plugin.json插件清单ID、版本、能力声明、贡献声明orca-plugin.jsonmain.mjsworker 入口注册命令和事件main.mjspanel.html沙箱 UI 面板panel.html核心设计有 3 个要点权限门控capabilities插件必须显式声明需要的能力如workspace:read、terminal:send未声明的能力会被拒绝进程隔离main.mjs运行在独立的 Node 进程中无 Electron崩溃不会影响 Orca 主程序面板沙箱panel.html运行在不透明 origin 的 iframe 中只能通过postMessage与宿主通信。第一步编写插件清单 orca-plugin.json清单是插件的身份证。以官方示例为例来源orca-plugin.jsonid/version唯一标识与语义化版本engines.orca声明兼容的 Orca 最低版本示例为1.4.0contributes.panels向主界面注册面板指定标题、图标与入口 HTMLcontributes.commands注册可手动调用的命令如hello-pingcontributes.events声明要订阅的事件如worktree.created、agent.status.changedcapabilities声明所需权限例如storage持久化存储、notifications:show系统通知。 新手建议第一版只申请你真正需要的能力。Orca 的权限系统会在用户同意后才放行对应 API 调用。第二步编写 worker 入口 main.mjsworker 入口的默认导出是一个activate(orca)函数orca对象是插件 API。官方示例展示了 3 类最常用 API来源main.mjsexport default function activate(orca) { // 1. 注册命令可被面板按钮或用户手动触发 orca.commands.register(hello-ping, async (args) { const stored await orca.host.call(storage.get, { key: pings }) const count (typeof stored?.value number ? stored.value : 0) 1 await orca.host.call(storage.set, { key: pings, value: count }) return { pong: true, count } }) // 2. 订阅事件新 worktree 创建时弹出系统通知 orca.events.on(worktree.created, async (payload) { await orca.host.call(notifications.show, { title: Worktree created, body: payload.path }) }) // 3. 记录日志orca.log 输出到插件日志缓冲 orca.events.on(agent.status.changed, (payload) { orca.log(agent status: ${payload.state}) }) }orca.host.call(action, params)是统一的能力门控通道常用 action 包括Action所需 capability说明storage.get/storage.setstorage键值持久化存储notifications.shownotifications:show发送系统通知workspace.readContextworkspace:read读取聚焦 worktree 与终端列表terminal.sendTextterminal:send向指定终端输入文本并回车第三步编写沙箱面板 panel.html面板是用户能看到的 UI。它运行在沙箱 iframe 中与宿主通信的唯一方式是postMessage请求/响应模式。官方示例封装了一个call(action, params)工具函数来源panel.html发出{ type: orca-panel-action, requestId, action, params }监听orca-panel-action-result消息按requestId匹配并 resolve Promise。面板样式可以直接使用 Orca 注入的 CSS 设计令牌如var(--foreground)、var(--border)你的插件 UI 会自动跟随主应用主题无需额外适配。第四、五步安装与调试插件开发涉及的服务端实现集中在 src/main/plugins/ 目录几个关键模块插件发现plugin-discovery.ts 扫描并解析插件清单开发者热重载plugin-dev-watcher.ts 监听插件文件变化改完即生效worker 生命周期plugin-worker-manager.ts 负责按需 fork、监督与重启 worker 进程面板宿主plugin-panel-controller.ts 管理面板 iframe 的创建与消息路由。调试建议先把插件目录放入 Orca 的插件发现路径确认清单解析无报错触发contributes中注册的命令观察orca.log输出打开面板用读取上下文 / 显示通知两个按钮验证权限是否已授予——若返回error/errorCode优先检查清单中的capabilities是否缺失。安全与最佳实践清单✅最小权限原则只声明必要的 capabilities权限越少越容易通过用户信任审查✅不要假设当前终端API 没有活动终端概念terminal.sendText必须传明确的terminalId✅面板保持无状态依赖所有数据都通过宿主 API 获取不要直连网络或读取本地文件✅错误要展示面板中检查result.ok并把错误显示给用户便于排障⚠️ 仓库中还附有一个恶意面板反例 hostile-panel可帮助你理解沙箱边界——插件做不到清单之外的事这是 Orca 插件安全模型的核心。常见问题FAQQ我的插件支持哪些事件A在contributes.events中订阅示例覆盖了worktree.created与agent.status.changed事件总线实现见 plugin-event-bus.ts。Q插件崩溃会影响 Orca 吗A不会。worker 是独立 Node 进程由 plugin-supervisor.ts 监督并在必要时重启。Q如何持久化数据A使用storage.get/storage.set数据由 Orca 的插件存储plugin-storage-store.ts统一管理。Q下一步学什么A读完示例后再看 src/main/plugins/plugin-host-methods.ts了解宿主向插件开放的全部方法族。从示例复制、改名、改逻辑你就拥有第一个 Orca 插件了。配合 Orca CLI把插件能力融入你的多智能体工作流从用工具升级为造工具。【免费下载链接】orcaOrca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop, mobile and VPS.项目地址: https://gitcode.com/GitHub_Trending/orca48/orca创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考