如何开发OpenClacky扩展:从ext.yml到自定义面板、Hook与API的完整开发者指南

原创2026-10-13 22:45:501,707 阅读
文章标签:人工智能AI AgentAgent 框架MCP Clients工具调用交互助手

如何开发OpenClacky扩展:从ext.yml到自定义面板、Hook与API的完整开发者指南

开发 OpenClacky 扩展其实很简单:一个 ext.yml 清单文件,加上你想要的面板(panels)、Hook、API 后端,就能让你的功能挂进 WebUI、拦截 Agent 的工具调用,甚至暴露自定义 HTTP 接口。本文是一份面向新手和老手的完整开发者指南,带你从零跑通第一个扩展,再到发布上架。

OpenClacky扩展开发助手 Ext Developer 齿轮与放大镜图标

一、先搞懂 OpenClacky 扩展架构:ext.yml 是什么?

一个扩展就是一个包含 ext.yml 的目录,它声明了这个扩展"贡献"(contributes)了哪些能力单元。OpenClacky 支持 8 种贡献类型:

类型 作用
panels WebUI 面板,挂载到命名 UI 插槽
api HTTP 后端,挂载到 /api/ext/<id>/
hooks Agent 生命周期钩子(工具调用前后、任务完成等)
skills 可被 Agent 调用的技能(SKILL.md)
agents 自定义 Agent 人设
channels 消息渠道适配器
tools 自定义工具类
patches 对宿主方法的补丁(慎用)

扩展按三层结构加载,同名 id 时高优先级层覆盖低优先级层(见 loader.rb):

  1. builtin — 随仓库自带的默认扩展(lib/clacky/default_extensions/)
  2. installed — 用户安装的扩展(~/.clacky/ext/installed/)
  3. local — 开发者本地工作副本(~/.clacky/ext/local/)

📌 好消息:开发时你只需要动 local 层,改完刷新 WebUI 页面即可生效,面板和 API 均支持热加载,无需重启服务。

以仓库内置的 Advisor 扩展为例,它同时贡献了 agent、hooks、api 和 panel(ext.yml):

id: advisor
name: Advisor
version: "0.1.0"
contributes:
  hooks:
    - event: after_tool_use
      file: hooks/advisor_tool_use.rb
  api: api/handler.rb
  panels:
    - id: advisor
      title: 工作建议
      view: panels/advisor/view.js
      attach: ["*"]        # "*" = 对所有 Agent 可见

二、一键脚手架:用 clacky ext new 创建你的第一个扩展

不需要手写目录结构,OpenClacky 内置了脚手架命令(cli_commands.rb):

clacky ext new my-panel          # 生成最小可用模板:一个面板 + 一个 API 后端
clacky ext new my-ext --full    # 生成"全家桶"模板,覆盖全部 8 种 contributes 类型
  • 最小模板位于 templates/hello,包含一份 ext.yml 模板 和可运行的 hello 面板;
  • --full 模板位于 templates/full,官方推荐把它当作学习示例:读完它,你就掌握了所有能力单元的写法。

生成后立即验证与查看已解析的单元:

clacky ext verify   # 解析三层容器,报告结构错误与警告
clacky ext list     # 列出所有扩展及其面板、API 等单元

三、编写自定义 WebUI 面板(view.js)

面板是一个 JavaScript 文件,通过 Clacky.ext.ui.mount(插槽, 渲染函数, 选项) 把 UI 注入宿主页面(注册机制见 ext.js)。宿主提供了一组命名插槽,选对插槽面板就出现在正确的位置:

  • session.aside — 会话侧栏(标签页容器,需声明 tab 选项)
  • session.composer — 输入框上方(适合推荐卡片)
  • session.banner — 会话顶部横幅
  • settings.tabs / settings.body — 设置页新增一个 Tab
  • sidebar.nav、header.left、main.workspace — 全局界面区域

最小示例(脚手架生成,可直接运行):

Clacky.ext.ui.mount("session.aside", function (ctx) {
  var el = document.createElement("div");
  var btn = document.createElement("button");
  btn.className = "btn-primary";           // 直接复用宿主样式类
  btn.textContent = "Ping backend";
  btn.addEventListener("click", async function () {
    var res = await fetch("/api/ext/my-ext/");
    // 展示结果…
  });
  el.appendChild(btn);
  return el;
}, { tab: { id: "my-ext", label: () => "My Ext" }, order: 500 });

💡 两个实用技巧:

  • 可见性控制:attach: ["*"] 表示所有 Agent 可见;写具体 Agent id(如 attach: ["general"])则只对指定 Agent 显示;省略则由 Agent 侧 panels: [...] 声明决定。
  • 国际化:扩展自带中英文字典即可,无需改动宿主 i18n,参考 Advisor 面板 的 DICT 写法。

四、用 Hook 接入 Agent 生命周期

Hook 让你在每个 Agent 的关键节点插入逻辑。在 hook_manager.rb 中定义了 7 种事件:

事件 触发时机 典型用途
before_tool_use 工具调用前 拦截危险命令、改写参数
after_tool_use 工具调用后 记录审计轨迹
on_tool_error 工具报错时 错误上报
on_start / on_complete 任务开始/结束 注入上下文、生成总结
on_iteration 每轮迭代 观测 Token 消耗
session_rollback 会话回滚 状态同步

在扩展的 hook 文件中通过 Clacky::ExtensionHookRegistry.add 注册回调(加载机制见 hook_loader.rb):

Clacky::ExtensionHookRegistry.add do |tool_name, args|
  Clacky::Logger.debug("[ext-hook] before_tool_use", tool: tool_name)
  { action: :allow }   # 也可返回 { action: :deny, reason: "..." } 拦截调用
end

返回值语义很直观:{ action: :allow } 放行;{ action: :deny, reason: "..." } 第一个 deny 生效并终止链条;{ action: :handled, result: "..." } 表示 Hook 已自行处理(常用于 on_start 直接给出答复)。每个 Agent 初始化时都会复制一份独立钩子链,互不干扰。

五、搭建后端 API:继承 ApiExtension

一个扩展最多贡献一个 API 单元(contributes.api: api/handler.rb),继承 Clacky::ApiExtension 后用路由 DSL 声明接口,自动挂载到 /api/ext/<id>/(路由分发与超时保护见 dispatcher.rb):

class MyExt < Clacky::ApiExtension
  get "/stats" do
    json(uptime: Process.clock_gettime(Process::CLOCK_MONOTONIC))
  end

  post "/notes" do
    File.write(data_path("notes.json"), JSON.generate(json_body["notes"] || []))
    json(ok: true)
  end
end

框架已替你处理好:访问密钥鉴权、请求超时、JSON 错误包、路径参数解析(get "/items/:id")。内置上下文方法包括:

  • json(...) / text(...) / send_data(...) — 快捷响应
  • error!(msg, status: 400) — 统一错误包
  • json_body / query — 请求参数
  • data_path("xxx") — 返回 ~/.clacky/ext-data/<id>/ 下的持久化路径(用户数据务必存这里,卸载扩展不会被误删)
  • create_session / submit_task / dispatch_to_session — 从 API 直接驱动 Agent 会话

⚡ 热加载:每次请求都会检测 handler.rb 的文件变更并自动重新加载,改完保存即生效,不用重启。完整 API 面参考 api_extension.rb。

六、验证、打包与发布:clacky ext 一条龙

开发完成后的分发流程全部内置在 CLI 中(打包/安装逻辑见 packager.rb):

clacky ext pack my-ext              # 打包成可分发的 zip(先自动跑 verify)
clacky ext install ./my-ext.zip     # 安装到 installed 层(也支持 URL)
clacky ext publish my-ext --status published --changelog "v0.2 修复XX"
clacky ext published                # 查看你已发布的扩展
clacky ext search 面板               # 搜索公开扩展市场

打包会自动剔除 .git、IDE 配置等元数据,安装端会做路径穿越校验,80MB 体积上限,安全性可以放心。

🎨 如果你不想盯着终端,还可以使用 OpenClacky 内置的 **Extension Studio(创作者中心)**扩展——它自带"扩展开发"Agent,可在 WebUI 里直接帮你构建、调试和发布扩展,见 ext-studio 配置。

七、开发者最佳实践清单

  1. 用户数据放 data_path,别放扩展目录 — 卸载会删除包目录,ext-data 在包外且重装自动续接;
  2. 面板命名空间要前缀 — 自定义类名/CSS 类加扩展前缀(如 .my-ext-card),避免污染宿主样式;
  3. Hook 只做 O(1) 记账 — 重活(如 LLM 分析)丢到独立线程,别阻塞主 Agent 线程;
  4. 先用 --full 模板学习,再删减 — 官方把"能跑的完整示例"当作最好的文档;
  5. 发布前跑 clacky ext verify — 它会把 ext.yml 解析错误结构化报出,快速定位问题。

相关源码索引

掌握 ext.yml + 面板 + Hook + API 这四件套,你就能把 OpenClacky 变成完全贴合自己工作流的 AI Agent 工作台。动手 clacky ext new 吧!🚀

登录后查看全文
openclacky