用途:为 Hermes 桌面应用编写插件,在不修改应用本身的前提下新增界面元素(面板、状态栏组件、仪表盘、命令、快捷键、路由、主题),或把自算数据通过网关 RPC 呈现到应用界面。
前置条件:需已安装 Hermes 桌面应用(仅 CLI/网关不会加载插件),并对 $HERMES_HOME/desktop-plugins/(默认 ~/.hermes/desktop-plugins/)有写权限。
用法:从 skill 目录的 templates/plugin.js 创建 $HERMES_HOME/desktop-plugins/<name>/plugin.js,目录名与插件 id 一致;命名 profile 下路径为 ~/.hermes/profiles/<profile>/...。应用会监视该目录,文件落下数秒内加载,之后每次保存原地热重载,无需重启;若未出现,可用 ⌘K → Reload desktop plugins。加载失败时应用会弹出指明错误的消息提示。
主要能力:唯一导入面为 @hermes/plugin-sdk(加 react / react/jsx-runtime,解析到应用自带 React;须用 jsx() 调用而非 JSX 语法,文件不被编译)。host.state.* 提供只读响应式原子(activeSessionId、cwd、gateway、model、profile、viewport);host.request 调网关 JSON-RPC;host.onEvent 订阅实时事件;host.notify/host.navigate/host.logs/host.status、haptic('tap')。ctx.register 贡献 UI,区域包括 statusBar.left/right、panes、PALETTE_AREA(⌘K 命令)、KEYBINDS_AREA、ROUTES_AREA、SIDEBAR_NAV_AREA。面板用 placement:'left'|'right'|'bottom'|'main' 分配语义角色,或用 dock:{ pane, pos } 落到指定边缘。ctx.storage 提供按插件命名空间的持久化;ctx.i18n.register 注册插件自有语言包,组件内用 usePluginI18n(id) 响应式读取。数据用 useQuery/useMutation/queryClient 等应用统一 React Query 客户端。后端可随插件携带 Python plugin_api.py,通过 ctx.rest('/path') 与 ctx.socket('/events', onMessage) 访问,均限定在 /api/plugins/<id>;ctx.socket 在 OAuth 远程下为 no-op,应保留轮询回退。插件在 Settings → Plugins 中启用/禁用,禁用状态跨重启保持;默认导出设 defaultEnabled:false 即为可选开启。UI 可直接导入应用设计语言组件(Button、Input、Tabs、Dialog 等)并用主题变量样式。
限制与注意:不得硬编码颜色或背景,须用主题变量;canvas 面板必须用 ResizeObserver 跟踪容器尺寸;除上述模块外不要导入其他标识符;处理函数须用 $atom.get() 读取状态;组件尽量小,仅在渲染该值的叶子组件订阅。列出的是操作规范与约束,具体版本适配与更细说明暂未提供。