Hermes WebUI 扩展开发实操5 分钟跑通一个自定义面板不动核心代码【免费下载链接】hermes-webuiHermes WebUI: The best way to use Hermes Agent from the web or from your phone!项目地址: https://gitcode.com/GitHub_Trending/he/hermes-webuiHermes WebUI 是给 Hermes Agent 做的 Web 界面手机或电脑浏览器里打开就能用。本文用扩展机制把第一个扩展 5 分钟跑通只写 2 个文件注入自定义 CSS 和 JS再通过现有 API 读会话数据全程不碰核心代码。扩展能做什么、不能做什么先把结论摆在前面扩展的能力边界可以概括成四个能、四个不能。能做的事扩展目录里的静态资源可以通过/extensions/前缀被浏览器取走你自己的 CSS 会被注入到页面头部负责改外观你自己的 JS 会被注入到页面底部负责加交互浏览器里的fetch可以调用 WebUI 现有的/api/接口把后端数据读出来展示。不能做的事同样清楚它绕不过登录认证读不到扩展目录之外的文件加载不了第三方域名的脚本或样式也不能直接改 Agent 的权限和模型设置——后者只能通过现有 API 走通。还有一个关键点整套扩展机制默认是关着的。只有当HERMES_WEBUI_EXTENSION_DIR指向一个真实存在的目录时WebUI 才会打开扩展注入其余时间这些能力全部不存在。这种默认关的设计让扩展的影响面很小出了问题关掉就行核心升级时你的扩展文件也不受影响。让第一个扩展跑起来最小扩展示例 准备环境需要 Git、Python 3.8以及 Hermes WebUI 的源码git clone https://gitcode.com/GitHub_Trending/he/hermes-webui cd hermes-webui然后建一个扩展目录里面放两个空文件mkdir -p ~/.hermes/webui-extension touch ~/.hermes/webui-extension/app.css ~/.hermes/webui-extension/app.js写两个文件app.css 与 app.js 最小骨架app.css 只需要面板头部和按钮几条规则/* 扩展面板的头部与按钮样式 */ .my-extension-header { background-color: #202236; color: white; padding: 10px; border-radius: 4px; } .my-extension-button { background-color: #4CAF50; color: white; border: none; padding: 8px 16px; border-radius: 4px; cursor: pointer; }app.js 管交互结构是四步用 IIFE 包起来避免污染全局变量放一个标记节点防重复执行搭出面板本体再往侧边栏挂一个切换按钮// 自执行函数包裹避免污染全局变量 (() { // 防重复标记节点已存在就直接退出 if (document.getElementById(my-extension-loaded)) return; const marker document.createElement(div); marker.id my-extension-loaded; document.body.appendChild(marker); // 搭扩展面板默认隐藏 const panel document.createElement(div); panel.className main-view my-extension-panel; panel.hidden true; panel.innerHTML div classmy-extension-headerh2我的自定义扩展/h2/div button classmy-extension-button点我试试/button ; document.querySelector(main)?.appendChild(panel); // 往侧边栏挂一个切换按钮 const sidebar document.querySelector(.sidebar); if (sidebar) { const button document.createElement(button); button.textContent 扩展功能; button.onclick () { document.querySelectorAll(main .main-view).forEach(view { view.hidden view ! panel; }); }; sidebar.appendChild(button); } })();用环境变量激活并验证三个环境变量指向你的文件然后启动 WebUIexport HERMES_WEBUI_EXTENSION_DIR~/.hermes/webui-extension export HERMES_WEBUI_EXTENSION_SCRIPT_URLS/extensions/app.js export HERMES_WEBUI_EXTENSION_STYLESHEET_URLS/extensions/app.css ./start.sh打开浏览器侧边栏应该多出扩展功能按钮点下去你刚写的面板就出现了。想确认资源真的被加载可以打开 F12 的网络面板看/extensions/app.js和/extensions/app.css两个请求是否都返回 200。扩展加载是怎么工作的整条链路在 api/extensions.py 里弄清三步就够用。第一步发生在服务端启动它读三个环境变量确认目录真实存在后把/extensions/静态路由注册上——你扩展目录里的每个文件都挂在这个前缀下面且全部走你自己的域名。第二步发生在页面渲染WebUI 在/head之前插一条指向样式 URL 的link在/body之前插一条指向脚本 URL 的script。这就是头部注 CSS、底部注 JS的时机样式先于内容生效脚本在 DOM 解析完才执行所以代码里querySelector能直接找到元素。第三步是安全闸门/extensions/路由带登录认证资产前缀只允许/extensions/和/static/这类同源路径第三方域名在这一步就会被拒掉不能加载第三方脚本的边界就是从这里来的。让扩展与后端对话fetch 调用 API扩展不会给后端开新接口它只是消费 WebUI 已经暴露的/api/接口集。最典型的用法是读会话列表// 拉取会话列表渲染进扩展面板 async function renderSessions() { try { const response await fetch(/api/sessions); const sessions await response.json(); const list document.createElement(ul); sessions.forEach(session { const item document.createElement(li); item.textContent session.title; list.appendChild(item); }); document.querySelector(.my-extension-panel)?.appendChild(list); } catch (error) { // 401 多半是未登录其他情况看 F12 网络面板的响应 console.error(获取会话失败:, error); } } renderSessions();这里也划清了能力边界扩展只能碰 WebUI 已经暴露出来的数据现有接口里没有的字段扩展自己也变不出来。常见故障排查避坑速查 日常调试就靠三样F12 的 Console 里看扩展自己的console输出WebUI 侧日志里看扩展的加载状态和报错扩展目录里的 CSS/JS 是静态资源改完内容一般刷新页面就生效而三个环境变量是启动时读取的改了必须重启。最常踩的三个坑整理成下表症状先查哪里扩展不加载HERMES_WEBUI_EXTENSION_DIR指向的目录是否真实存在三个环境变量是否拼写错误、是否混入逗号空格浏览器里/extensions/app.js与app.css是否 404样式与主程序冲突给类名加扩展专属前缀如my-extension-别直接覆盖主程序元素的样式选择器API 调用失败确认已登录扩展资源和 API 都过认证401 是未登录404 是接口路径写错到 F12 网络面板看响应写在最后扩展开发说到底就一句话目录指到实处三个环境变量指到两个文件剩下的都是你自己的 HTML、CSS 和 JavaScript。信任模型的完整说明、多扩展 manifest 配置等进阶细节直接去官方文档 docs/EXTENSIONS.md 查比本文详细得多。【免费下载链接】hermes-webuiHermes WebUI: The best way to use Hermes Agent from the web or from your phone!项目地址: https://gitcode.com/GitHub_Trending/he/hermes-webui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考