3步给 Hermes WebUI 添加自定义功能：扩展开发新手教程

3步给 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-webuiHermes WebUI 是 Hermes Agent 的网页端界面支持从浏览器和手机直接操作 Agent它内置的 Hermes WebUI 扩展机制让你不改一行核心代码就能加界面换肤、专属小面板这类自定义功能。下面先讲清楚加载机制再陪你走完最小化落地的 3 步。扩展能帮你解决什么问题 默认界面够用但每个人都有自己的小别扭默认配色太扎眼想要一套顺眼的皮肤又不想逐行翻核心样式表。需要专属小功能一个快捷按钮、一块小统计面板写进主仓库太重了。不敢动核心代码改完源码后一升级就容易翻车回滚都不知道从哪下手。这三类需求小到不值得开 issue自己动手又麻烦。扩展就是为这种场景准备的我们只写本地的 CSS 和 JSWebUI 页面启动时自动把它们加载进来核心文件一个都不用碰。先搞懂机制扩展是怎么被加载的三句话说清整套扩展系统默认是关闭的只有把HERMES_WEBUI_EXTENSION_DIR环境变量指向一个已存在的目录才会激活你可以把环境变量理解成扩展的总开关激活之后WebUI 会把你声明的 CSS 文件注入页面头部管长相、JS 文件注入页面底部之前管行为所有扩展文件统一挂在/extensions/路径下对外提供且必须先登录才能访问匿名请求一律拒绝。加载过程一张图概括环境变量总开关目录必须已存在 │ ├─ /extensions/*.css ── 注入 head负责样式 ├─ /extensions/*.js ─── 注入 /body 前负责行为 └─ /extensions/其他文件 ─ 静态资源登录后可访问加载器的具体实现在 api/extensions.py想深挖可以翻这个文件。三步最小化落地目标非常小一个改背景色的文件加一个往控制台打字的文件跑通一次确认整条链路没问题。第 1 步建扩展目录和两个文件mkdir -p ~/.hermes/my-ext echo body { background: #10131a; } ~/.hermes/my-ext/theme.css echo console.log(my-ext ready); ~/.hermes/my-ext/app.jsCSS 负责把整页背景调暗JS 负责在开发者工具的控制台输出一行字就够用来验证。第 2 步配置三个环境变量export HERMES_WEBUI_EXTENSION_DIR~/.hermes/my-ext export HERMES_WEBUI_EXTENSION_SCRIPT_URLS/extensions/app.js export HERMES_WEBUI_EXTENSION_STYLESHEET_URLS/extensions/theme.css第一个变量声明文件放在哪后两个声明注入哪些文件。URL 前缀固定是/extensions/后面接目录内的相对路径要注入多个文件就用逗号分隔。扩展目录如何配置、扩展环境变量怎么设置记住这三件套就够了。第 3 步重启服务并刷新页面./start.sh服务起来之后在浏览器按 F5 刷新看两处页面整体背景变暗、控制台出现my-ext ready。两处都对了说明样式和脚本已经成功注入。扩展脚本运行在登录后的页面上下文里理论上可以操作界面任意区域比如右侧这块工作区文件面板就是挂小工具或快捷入口的好位置。能力边界扩展能做什么、不能做什么能做的 ✅注入同源样式与脚本CSS 进头部、JS 进页底通过/extensions/访问扩展目录内的静态文件以登录会话身份调用 WebUI 现有 API不能做的 ❌绕过 WebUI 鉴权匿名运行访问或提供扩展目录之外的文件加载第三方域名的脚本或样式直接修改 Agent 权限或模型设置除非走现有 API 本来允许的途径再提醒一句扩展 JS 以登录会话的完整权限运行等于能登录的人做什么扩展就能做什么。所以只加载你自己写的、或你完全信任的扩展代码。扩展没生效自查清单 页面看起来没变化→ 多半是HERMES_WEBUI_EXTENSION_DIR没设置或指向了不存在的目录系统不会自动建目录→ 先确认目录存在再重启服务。控制台报/extensions/xxx.js404→ URL 与实际文件名对不上或漏写了/extensions/前缀 → 逐个核对文件名。样式生效但脚本不执行→/extensions/路径要求登录或漏配了 JS 变量 → 登录后刷新确认SCRIPT_URLS已设置。当前终端有效重启后失效→export只作用于当前 shell → 把变量写进启动脚本或持久化 env 文件。想加载 CDN 上的脚本→ 设计上只允许同源路径第三方域名会被直接拒绝 → 把文件放本地扩展目录里。收尾扩展机制是个本地定制的逃生舱一个加载器、几个环境变量能力上限由现有 API划定了边界。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），仅供参考