Hermes WebUI扩展开发实战5步为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 里挂上一个自己写的扩展一个带状态角标的面板点一下能看到当前会话总数。从建目录、写文件、配环境变量到验证效果全程动手不碰一行核心代码。动手前的三件事开始前确认这三样东西就绪准备项要求说明源码hermes-webui 仓库本地能跑起./start.sh运行时Python 3 bash启动脚本会自动找 python3基础会改 HTML/CSS/JS本教程只用到这三个git clone https://gitcode.com/GitHub_Trending/he/hermes-webui cd hermes-webui克隆下来后不用装额外依赖后面直接./start.sh就能拉起。一张图看懂它在系统里的位置扩展加载的核心逻辑在 api/extensions.py。它做三件事把HERMES_WEBUI_EXTENSION_DIR目录映射成/extensions/静态路径再把配置的同源 CSS/JS 分别注进页面头部和底部。注入位置在应用外壳渲染之前所以你的脚本可以安全地挂 DOM。✅ 能做注入本地 CSS / JS调用 WebUI 已有 API经/extensions/提供静态文件❌ 不能做绕过 WebUI 登录鉴权加载第三方域名的脚本或样式注册新的后端路由实战从骨架到跑通搭骨架建目录写第一个 app.css这一步是给扩展立个家只放样式。目录建议放~/.hermes/webui-extensionWebUI 本身不写这里改起来方便。mkdir -p ~/.hermes/webui-extension cat ~/.hermes/webui-extension/app.css CSS .ext-hub[hidden] { display: none !important; } .ext-hub { padding: 16px 20px; color: var(--text, #fff); } .ext-hub-badge { position: fixed; right: 12px; bottom: 12px; padding: 6px 12px; border-radius: 999px; background: #202236; color: #fff; font-size: 12px; cursor: pointer; z-index: 9999; } CSS看到终端没有报错、文件落在目录下说明骨架就位了。填血肉app.js 造面板、拉数据这一步是扩展的主逻辑造一个面板和一个角标点角标切换显示并调 WebUI 的会话列表 API 把数量显示出来。(() { if (document.getElementById(ext-hub-badge)) return; const panel document.createElement(section); panel.id ext-hub; panel.className main-view ext-hub; panel.hidden true; panel.textContent 会话统计加载中…; document.querySelector(main)?.appendChild(panel); const badge document.createElement(button); badge.id ext-hub-badge; badge.className ext-hub-badge; badge.textContent 我的扩展; badge.onclick () { panel.hidden !panel.hidden; if (!panel.hidden) { document.querySelectorAll(main .main-view) .forEach(v { if (v ! panel) v.hidden true; }); } }; document.body.appendChild(badge); fetch(/api/sessions) .then(r r.json()) .then(data { const rows Array.isArray(data) ? data : (data.sessions || []); panel.textContent 当前会话总数 rows.length; badge.textContent 我的扩展 · rows.length; }) .catch(err { panel.textContent 拉取会话失败; }); })();这段代码涉及两个文件的分工app.css管外观app.js管行为fetch(/api/sessions)走的是浏览器当前登录态和 WebUI 自身用的是同一套会话。接电源3步配好环境变量这一步的作用是告诉 WebUI 扩展在哪、要注入哪些文件。三个变量一个都不能少。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注意两点目录变量指的位置必须已经存在WebUI 不会替你自动创建后两个变量只认以/extensions/或/static/开头的同源路径别的格式会被静默忽略。验效果刷页面点角标浏览器打开 WebUI看到右下角出现「我的扩展」角标说明注入成功。点一下主区域切到扩展面板角标文字变成「我的扩展 · N」N 就是会话数——看到这两个现象说明从静态服务到 API 调用整条链路都通了。如果卡在角标始终不出现大概率是环境变量没生效回上一节核对拼写。进阶玩法用 manifest.json 管理多个扩展文件文件一多环境变量里的逗号列表就难看了进阶一点可以改用清单文件manifest扩展的资产登记表。cat ~/.hermes/webui-extension/manifest.json JSON { extensions: [ { id: ext-hub, scripts: [app.js], stylesheets: [app.css] } ] } JSON export HERMES_WEBUI_EXTENSION_MANIFESTmanifest.json清单里写相对路径即可WebUI 会自动拼成/extensions/app.js这样的 URL清单和显式环境变量可以同时用重复项自动去重。注册一个自定义皮肤想让扩展顺手改外观可以把它注册进原生的 Settings → Appearance 皮肤选择器而不是自己再做一个主题开关。window.registerHermesSkin({ name: E-Ink, scheme: light, tokens: { --bg: #ffffff, --text: #000000, --accent: #000000 } });返回true即注册成功设置页立刻多出这个皮肤。核心会先清洗 token 值不在允许名单里的 CSS 值直接被丢弃你只管写规范颜色就行。调 API 拉会话数据上面已经调过/api/sessions如果你还想做会话名列表、最近活跃排序之类的展示直接在这个 API 返回的字段上做文章就行不需要任何后端改动。注意鉴权状态没登录时请求会 401扩展里最好像示例那样带.catch兜底。踩坑手册 安全红线现象扩展没出现。原因环境变量没设或目录路径不对。解法确认三个变量都在、目录真实存在然后刷新页面。现象样式互相打架。原因类名和 WebUI 撞车。解法给所有类名加专属前缀。现象fetch 返回 401。原因未登录或权限不足。解法先完成登录再验证扩展。现象改了文件没反应。原因静态文件在服务启动时注入。解法改完刷新浏览器页面。安全底线扩展目录不要指向共享机器上的可写路径扩展代码等同于登录用户的权限在跑只加载你审过的、信任度等同源码的代码。下一步完整契约看 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），仅供参考