如何开发OpenClacky扩展:从ext.yml到自定义面板、Hook与API的完整开发者指南
如何开发OpenClacky扩展:从ext.yml到自定义面板、Hook与API的完整开发者指南
开发 OpenClacky 扩展其实很简单:一个 ext.yml 清单文件,加上你想要的面板(panels)、Hook、API 后端,就能让你的功能挂进 WebUI、拦截 Agent 的工具调用,甚至暴露自定义 HTTP 接口。本文是一份面向新手和老手的完整开发者指南,带你从零跑通第一个扩展,再到发布上架。
一、先搞懂 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):
- builtin — 随仓库自带的默认扩展(
lib/clacky/default_extensions/) - installed — 用户安装的扩展(
~/.clacky/ext/installed/) - 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— 设置页新增一个 Tabsidebar.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 配置。
七、开发者最佳实践清单
- 用户数据放
data_path,别放扩展目录 — 卸载会删除包目录,ext-data在包外且重装自动续接; - 面板命名空间要前缀 — 自定义类名/CSS 类加扩展前缀(如
.my-ext-card),避免污染宿主样式; - Hook 只做 O(1) 记账 — 重活(如 LLM 分析)丢到独立线程,别阻塞主 Agent 线程;
- 先用
--full模板学习,再删减 — 官方把"能跑的完整示例"当作最好的文档; - 发布前跑
clacky ext verify— 它会把ext.yml解析错误结构化报出,快速定位问题。
相关源码索引
- 扩展加载与三层覆盖:loader.rb
- CLI 命令(new/verify/list/pack/install/publish):cli_commands.rb
- API 基类与上下文:api_extension.rb
- Hook 加载与注册表:hook_loader.rb
- WebUI 扩展注册契约:ext.js
- 参考实现(内置 Advisor 扩展):default_extensions/advisor
掌握 ext.yml + 面板 + Hook + API 这四件套,你就能把 OpenClacky 变成完全贴合自己工作流的 AI Agent 工作台。动手 clacky ext new 吧!🚀