仪表板插件

仪表板插件允许你向网页仪表板添加自定义标签页。一个插件可以展示自己的用户界面、调用 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/gateway（通过 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 打包文件路径
css	否	要注入的 CSS 文件路径
api	否	包含 FastAPI 路由的 Python 文件路径

标签位置

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

• "end" —— 在所有内置标签之后（默认）
• "after:skills" —— 在“技能”标签之后
• "before:config" —— 在“配置”标签之前
• "after: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。这避免了版本冲突，并保持插件包体积小巧。

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 路由绕过会话令牌认证。

访问 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 —— “示例”标签将在“技能”之后出现。

小贴士

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