仪表盘插件

仪表盘插件允许你向 Web 仪表盘添加自定义标签页。插件可以显示自己的 UI、调用 Hermes API，并可选择注册后端端点——所有这些都无需修改仪表盘的源代码。

快速开始

创建一个包含清单文件和 JS 文件的插件目录：

mkdir -p ~/.hermes/plugins/my-plugin/dashboard/dist

manifest.json：

{
  "name": "my-plugin",
  "label": "My Plugin",
  "icon": "Sparkles",
  "version": "1.0.0",
  "tab": {
    "path": "/my-plugin",
    "position": "after:skills"
  },
  "entry": "dist/index.js"
}

dist/index.js：

(function () {
  var SDK = window.__HERMES_PLUGIN_SDK__;
  var React = SDK.React;
  var Card = SDK.components.Card;
  var CardHeader = SDK.components.CardHeader;
  var CardTitle = SDK.components.CardTitle;
  var CardContent = SDK.components.CardContent;

  function MyPage() {
    return React.createElement(Card, null,
      React.createElement(CardHeader, null,
        React.createElement(CardTitle, null, "My Plugin")
      ),
      React.createElement(CardContent, null,
        React.createElement("p", { className: "text-sm text-muted-foreground" },
          "Hello from my custom dashboard tab!"
        )
      )
    );
  }

  window.__HERMES_PLUGINS__.register("my-plugin", MyPage);
})();

刷新仪表盘——你的标签页将出现在导航栏中。

插件结构

插件位于标准的 ~/.hermes/plugins/ 目录内。仪表盘扩展是一个 dashboard/ 子文件夹：

~/.hermes/plugins/my-plugin/
  plugin.yaml              # optional — existing CLI/gateway plugin manifest
  __init__.py              # optional — existing CLI/gateway hooks
  dashboard/               # dashboard extension
    manifest.json          # required — tab config, icon, entry point
    dist/
      index.js             # required — pre-built JS bundle
      style.css            # optional — custom CSS
    plugin_api.py          # optional — backend API routes

单个插件可以从一个目录同时扩展 CLI/网关（通过 plugin.yaml + __init__.py）和仪表盘（通过 dashboard/）。

清单参考

manifest.json 文件向仪表盘描述你的插件：

{
  "name": "my-plugin",
  "label": "My Plugin",
  "description": "What this plugin does",
  "icon": "Sparkles",
  "version": "1.0.0",
  "tab": {
    "path": "/my-plugin",
    "position": "after:skills"
  },
  "entry": "dist/index.js",
  "css": "dist/style.css",
  "api": "plugin_api.py"
}

字段	必需	描述
name	是	唯一的插件标识符（小写，可以使用连字符）
label	是	在导航标签页中显示的显示名称
description	否	简短描述
icon	否	Lucide 图标名称（默认：Puzzle）
version	否	Semver 版本字符串
tab.path	是	标签页的 URL 路径（例如 /my-plugin）
tab.position	否	插入标签页的位置：end（默认）、after:<tab>、before:<tab>
entry	是	相对于 dashboard/ 的 JS bundle 路径
css	否	要注入的 CSS 文件路径
api	否	包含 FastAPI 路由的 Python 文件路径

标签页位置

position 字段控制你的标签页在导航中的显示位置：

• "end" — 在所有内置标签页之后（默认）
• "after:skills" — 在 Skills 标签页之后
• "before:config" — 在 Config 标签页之前
• "after:cron" — 在 Cron 标签页之后

冒号后面的值是目标标签页的路径段（不带前导斜杠）。

可用图标

插件可以使用以下任何 Lucide 图标名称：

Activity, BarChart3, Clock, Code, Database, Eye, FileText, Globe, Heart, KeyRound, MessageSquare, Package, Puzzle, Settings, Shield, Sparkles, Star, Terminal, Wrench, Zap

无法识别的图标名称将回退到 Puzzle。

插件 SDK

插件不捆绑 React 或 UI 组件——它们使用暴露在 window.__HERMES_PLUGIN_SDK__ 上的 SDK。这避免了版本冲突并保持插件 bundle 小巧。

SDK 内容

var SDK = window.__HERMES_PLUGIN_SDK__;

// React
SDK.React              // React instance
SDK.hooks.useState     // React hooks
SDK.hooks.useEffect
SDK.hooks.useCallback
SDK.hooks.useMemo
SDK.hooks.useRef
SDK.hooks.useContext
SDK.hooks.createContext

// API
SDK.api                // Hermes API client (getStatus, getSessions, etc.)
SDK.fetchJSON          // Raw fetch for custom endpoints — handles auth automatically

// UI Components (shadcn/ui style)
SDK.components.Card
SDK.components.CardHeader
SDK.components.CardTitle
SDK.components.CardContent
SDK.components.Badge
SDK.components.Button
SDK.components.Input
SDK.components.Label
SDK.components.Select
SDK.components.SelectOption
SDK.components.Separator
SDK.components.Tabs
SDK.components.TabsList
SDK.components.TabsTrigger

// Utilities
SDK.utils.cn           // Tailwind class merger (clsx + twMerge)
SDK.utils.timeAgo      // "5m ago" from unix timestamp
SDK.utils.isoTimeAgo   // "5m ago" from ISO string

// Hooks
SDK.useI18n            // i18n translations
SDK.useTheme           // Current theme info

使用 SDK.fetchJSON

用于调用插件的后端 API 端点：

SDK.fetchJSON("/api/plugins/my-plugin/data")
  .then(function (result) {
    console.log(result);
  })
  .catch(function (err) {
    console.error("API call failed:", err);
  });

fetchJSON 自动注入会话认证令牌，处理错误，并解析 JSON。

使用现有 API 方法

SDK.api 对象拥有所有内置 Hermes 端点的方法：

// Fetch agent status
SDK.api.getStatus().then(function (status) {
  console.log("Version:", status.version);
});

// List sessions
SDK.api.getSessions(10).then(function (resp) {
  console.log("Sessions:", resp.sessions.length);
});

后端 API 路由

插件可以通过在清单中设置 api 字段来注册 FastAPI 路由。创建一个导出 router 的 Python 文件：

# plugin_api.py
from fastapi import APIRouter

router = APIRouter()

@router.get("/data")
async def get_data():
    return {"items": ["one", "two", "three"]}

@router.post("/action")
async def do_action(body: dict):
    return {"ok": True, "received": body}

路由挂载在 /api/plugins/<name>/，因此上述示例变为：

• GET /api/plugins/my-plugin/data
• POST /api/plugins/my-plugin/action

插件 API 路由绕过会话令牌认证，因为仪表盘服务器仅绑定到 localhost。

访问 Hermes 内部组件

后端路由可以从 hermes-agent 代码库中导入：

from fastapi import APIRouter
from hermes_state import SessionDB
from hermes_cli.config import load_config

router = APIRouter()

@router.get("/session-count")
async def session_count():
    db = SessionDB()
    try:
        count = len(db.list_sessions(limit=9999))
        return {"count": count}
    finally:
        db.close()

自定义 CSS

如果你的插件需要自定义样式，请添加一个 CSS 文件并在清单中引用它：

{
  "css": "dist/style.css"
}

CSS 文件在插件加载时作为 <link> 标签注入。使用特定的类名以避免与仪表盘现有样式冲突。

/* dist/style.css */
.my-plugin-chart {
  border: 1px solid var(--color-border);
  background: var(--color-card);
  padding: 1rem;
}

你可以使用仪表盘的 CSS 自定义属性（例如 --color-border, --color-foreground）以匹配当前主题。

插件加载流程

1. 仪表盘加载——main.tsx 在 window.__HERMES_PLUGIN_SDK__ 上暴露 SDK
2. App.tsx 调用 usePlugins()，获取 GET /api/dashboard/plugins
3. 对于每个插件：注入 CSS <link>（如果声明），加载 JS <script>
4. 插件 JS 调用 window.__HERMES_PLUGINS__.register(name, Component)
5. 仪表盘将标签页添加到导航并将组件挂载为路由

插件在其脚本加载后最多有 2 秒的时间进行注册。如果插件加载失败，仪表盘将继续运行而不包含该插件。

插件发现

仪表盘扫描以下目录以查找 dashboard/manifest.json：

1. 用户插件： ~/.hermes/plugins/<name>/dashboard/manifest.json
2. 捆绑插件： <repo>/plugins/<name>/dashboard/manifest.json
3. 项目插件： ./.hermes/plugins/<name>/dashboard/manifest.json（仅在设置 HERMES_ENABLE_PROJECT_PLUGINS 时）

用户插件优先——如果多个来源中存在相同名称的插件，则用户版本胜出。

要在不重启服务器的情况下强制重新扫描新添加的插件：

curl http://127.0.0.1:9119/api/dashboard/plugins/rescan

插件 API 端点

端点	方法	描述
/api/dashboard/plugins	GET	列出已发现的插件
/api/dashboard/plugins/rescan	GET	强制重新扫描新插件
/dashboard-plugins/<name>/<path>	GET	提供插件静态资源
/api/plugins/<name>/*	*	插件注册的 API 路由

示例插件

代码库在 plugins/example-dashboard/ 中包含一个示例插件，演示了：

• 使用 SDK 组件（Card、Badge、Button）
• 调用后端 API 路由
• 通过 window.__HERMES_PLUGINS__.register() 进行注册

要尝试它，请运行 hermes dashboard — “Example” 标签页将出现在 Skills 之后。

提示

• 无需构建步骤 — 编写纯 JavaScript IIFE。如果你更喜欢 JSX，可以使用任何打包工具（esbuild、Vite、webpack），目标输出为 IIFE 并将 React 作为外部依赖。
• 保持捆绑包小巧 — React 和所有 UI 组件均由 SDK 提供。你的捆绑包应仅包含你的插件逻辑。
• 使用主题变量 — 在 CSS 中引用 var(--color-*) 以自动匹配用户选择的任何主题。
• 本地测试 — 运行 hermes dashboard --no-open 并使用浏览器开发者工具验证你的插件是否正确加载和注册。