5 分钟搭好你的第一个 Hermes WebUI 扩展不用改核心代码【免费下载链接】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跟着这篇走下来你会做出一个真正的 Hermes WebUI 扩展侧边栏多出一个自定义功能面板带独立样式、能调用真实接口而 WebUI 核心代码一行不动。整个过程只写两个静态文件、设三个环境变量剩下的事情由 扩展系统源码 替我们完成。把扩展机制想成一面挂墙货架在敲第一行代码前花 30 秒建立正确的心智模型。把 Hermes WebUI 看成一栋装修好的房子扩展机制就是墙上预留的挂钩。你以管理员身份用环境变量指定一块货架一个本地目录WebUI 启动时会把货架上的东西自动挂到固定位置——静态文件经/extensions/路径对外可见你点名的 CSS 被注入页面headJS 被注入/body之前。房子里原有的门锁身份认证和水电API照常运转货架上的东西可以借用电线但不能拆墙、不能换锁。想明白这一点后面所有配置都是顺理成章的事。动手前对照这张检查清单项目要求运行环境Python 3.8./start.sh能正常拉起 WebUI前端基础熟悉 DOM 操作和fetch即可不要求任何框架文件权限对~/.hermes目录可写用来放扩展文件调试手段会用 F12 打开开发者工具看 Console 和 Network四项都满足就可以开工了。从零搭出你的第一个 Hermes WebUI 扩展 搞懂了原理现在真正动手。你正在做的事分四步建货架、放货、挂牌、开门。第一步建目录并把它指给 WebUI。扩展默认是关闭的只有环境变量指向一个已存在的目录时才会激活——WebUI 不会替我们自动创建指定路径所以先建目录再启动mkdir -p ~/.hermes/webui-extension touch ~/.hermes/webui-extension/app.css ~/.hermes/webui-extension/app.js # 两个文件的内容稍后在编辑器里补 export 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 # 在 hermes-webui 仓库目录内执行注意 URL 必须以/extensions/开头——这是 WebUI 为扩展静态文件保留的路径前缀写成别的值会在加载阶段被拒。第二步给货架贴内容。CSS 只负责让面板有自己的长相.my-ext-panel { background: #1e1f2b; border-left: 3px solid #4c8bf5; border-radius: 6px; padding: 12px; margin: 8px; }第三步写 JS。两个细节很重要用立即执行函数包住逻辑避免污染全局命名空间再加一个重复加载守卫防止热重载时脚本被执行两遍(() { if (window.__myExtLoaded) return; window.__myExtLoaded true; const btn document.createElement(button); btn.className sidebar-button; btn.textContent 我的扩展; btn.onclick () console.log(扩展按钮被点击); // ……创建 .my-ext-panel 面板、追加到 main 的其余逻辑略 document.querySelector(.sidebar)?.appendChild(btn); })();第四步刷新浏览器验证。侧边栏底部应该多出一个我的扩展按钮点下去页面出现一块带蓝色左边框的面板Console 里打出一条日志。一个能跑的 Hermes WebUI 扩展到此诞生。从玩具到可用先划清能力边界能跑起来只是第一步。真正开始写功能之前先把边界摸清楚——这套边界是 loader 硬性执行的不是约定俗成能做不能做从配置目录经/extensions/提供静态文件访问扩展目录之外的任何文件CSS 注入head、JS 注入/body前经注入配置加载第三方域的脚本或样式调用当前登录会话能调的任何 WebUI API绕过 WebUI 身份认证按 manifest 声明 loopback sidecar在设置中获得代理同意后受控调用注册新的后端路由直接改 Agent 权限、模型或工具配置⚠️ 必须说清楚的一件事扩展 JS 以完整的 WebUI 会话权限运行能读会话历史、发消息、改设置。所以只启用我们自己写的、或信任度等同于 WebUI 源码的扩展多人共用的实例上干脆别开扩展。让扩展调一次真实接口就能体会借用电线的含义。把这段放进 app.js 里扩展面板就会实时显示会话数量async function refreshSessionCount() { const res await fetch(/api/sessions); if (!res.ok) return; // 未登录时先按 401 处理 const sessions await res.json(); // ……把 sessions 渲染进面板列表的其余逻辑略 badge.textContent String(sessions.length); }这就是玩具变可用的关键一步扩展自己长不出新的后端能力但它能完整复用浏览器会话里已有的全部接口把内部小工具和个人面板拼出来绰绰有余。排障速查东西没按预期出现时先别怀疑人生按这张表过一遍Q按钮始终不出现A确认SCRIPT_URLS与STYLESHEET_URLS都以/extensions/开头且和真实文件名一致用 F12 的 Network 面板看请求是不是 200。Q/extensions/xxx返回 404AHERMES_WEBUI_EXTENSION_DIR没设、指向的目录不存在或文件不在该目录下WebUI 不会自动创建指定路径。QJS 里 fetch 拿到 401 或跳到登录页A扩展不绕过认证浏览器里先登录一次让会话 cookie 就位。Q改了扩展文件没生效AJS/CSS 是在页面渲染时注入的硬刷新页面即可但改动环境变量必须重启 WebUI。Q面板样式被主程序覆盖A类名加专属前缀如my-ext-避开sidebar-button之外的通用类名。延伸阅读从三个环境变量到一个挂在侧边栏上的自定义功能Hermes WebUI 扩展这条路你已经走通了。manifest 契约、sidecar 授权、扩展库完整规则去读仓库里的 docs/EXTENSIONS.md 和 api/extensions.py 就能得到权威答案。【免费下载链接】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），仅供参考