内容
# boardstate-hermes-plugin
> **您与代理共同构建的面板 — 持久、可审计、操作员管理。**
Hermes 的插件，添加了一个实时的 **面板** 到网页仪表盘（`hermes dashboard`）和桌面应用程序中：
一个布局即数据的workspace，由 Hermes 代理**构建和操作** — 您共同拥有、审计和管理。基于 [Boardstate](https://github.com/100yenadmin/boardstate)
（npm上的`@boardstate/*`，MIT — 一个 45k 行的workspace库）。
**上游：** Hermes的合并请求是开放的 — 跟踪器
[hermes-agent#66413](https://github.com/NousResearch/hermes-agent/issues/66413)，网页
[PR #66381](https://github.com/NousResearch/hermes-agent/pull/66381)，桌面
[PR #66425](https://github.com/NousResearch/hermes-agent/pull/66425).
## 功能
- **代理实时构建面板。** 一个网络化的MCP端点（19个`boardstate_*`工具）通过插件后端与浏览器监视的同一主机交互 —
小部件在代理工作时出现，无需重新加载。
- **实时Hermes数据，零配置。** 使用情况、会话、实例和cron小部件
自动绑定到仪表盘的REST表面 — 真实数据，优雅的空状态，
绝不会出现错误单元格。凭证保留在服务器端。
- **16种内置小部件类型** — 统计卡、图表（线形/条形/面积/火柴图/仪表盘）、
表格、Markdown、笔记、活动、操作按钮/表单、聊天和实时
数据源小部件 — 加上**一键模板**：代理总部 · 使用情况和成本 ·
会话监视器 · Office Ops。
- **沙盒自定义小部件。** 安装小部件包（游戏、计算器、
跟踪器）；它以**待处理**状态着陆（资产统一404），您批准后，它将安装
在一个不透明源的iframe中，带有无网络CSP — 通过令牌化的
遍历阻止资产路由提供。库的2048，安装、批准和在Hermes中播放：
- **操作层。** 通过操作员管理的授权连接外部MCP工具（一个**OfficeCLI**预设发货）—
代理*请求*工具，您按工具批准；
读取通过清单哈希门（更改工具的连接器重新挂起）；
**变异始终停靠以供您确认** — 有界，绝不会挂起。每个授权在批准小部件中
都是可见和可撤销的。
- **原生于Hermes，两种设计系统。** 主题令牌别名为主机调色板并
遵循实时交换（ 显示整个调色板交换）；
网页皮肤与仪表盘的设计语言相匹配（数值上，对抗看板页面），桌面皮肤与应用的macOS语言相匹配。库发货20种本地化。
## 安全模型（设计用于审查）
- 浏览器仅连接到仪表盘源；身份验证是仪表盘自己的WebSocket网关。
Node侧车绑定到环回仅后面一个每个生成的随机数；
**每个状态目录一个侧车** （端口文件采用，`chmod 600`）因此网页和桌面绝不会双重写入。
- **操作员动词** （批准/确认/拒绝）无法从浏览器WebSocket和
代理MCP表面到达。它们仅通过身份验证的插件路由，该路由由专用每个生成的**操作员密钥（绝不持久）**和
`boardstate.operators.json`允许列表（不存在 ⇒ 仅环回；有门控多用户 ⇒
没有允许列表则拒绝）。
- **连接器配置绝不离开服务器**：长度不限，优先最长删除（命令/网址/参数/环境值 + 随机数）每次代理错误；
防拉清单哈希重新挂起每个代理可达的连接器调用。
- **自定义小部件资产**：仅批准且统一404，沙盒CSP保留
原样通过代理，遍历段在任何上游请求之前被拒绝。
- 通过三个独立的对抗性审查通道和外部审查
轮进行强化；他们发现的漏洞随**回滚检查**的回归测试一起发货。
## 架构
```
浏览器 <boardstate-view> 桌面应用程序 （单文件ESM插件）
│ WebSocket /api/plugins/boardstate/ws ←──────────┘ （同一后端，桌面桥）
│ HTTP /api/plugins/boardstate/mcp ◄─ Hermes代理（StreamableHTTP，19个工具）
│ HTTP /api/plugins/boardstate/operator ◄─ 批准UI（会话 + 允许列表）
│ HTTP /boardstate-widget-assets/<token>/… ◄─ 自定义小部件iframe（能力令牌）
▼
plugin_api.py — WebSocket桥 · MCP代理 · 操作员门控 · 令牌化资产路由 · 侧车生命周期
▼ （每个生成的随机码 + 操作员密钥，通过环境变量注入，绝不持久）
sidecar/server.js — 一个主机，一个写入者：控制平面 · 实时Hermes数据RPC ·
连接器代理（boardstate.connectors.json）· 待处理操作引擎 · /widgets（CSP）
▼
$HERMES_HOME/boardstate-state/dashboard/workspace.json ← 面板即此文档
```
面板是一个**验证文档** — 一个写入者，每个变异都通过门控动词 —
这使得撤销、历史、导出/导入、模板和审计成为可能。
## 安装（网页仪表盘）
需要在运行`hermes dashboard`的机器上安装Node ≥ 20。
```bash
mkdir -p ~/.hermes/plugins/boardstate
cp -r dashboard ~/.hermes/plugins/boardstate/dashboard
# 在 ~/.hermes/config.yaml 中启用它： plugins: { enabled: [boardstate] }
hermes dashboard # 技能之后出现面板选项卡
```
### 安装（桌面应用程序）
桌面前端是桌面插件表面上的单个文件（必须安装上述后端）：
```bash
mkdir -p ~/.hermes/desktop-plugins/boardstate
cp dashboard/desktop/plugin.js ~/.hermes/desktop-plugins/boardstate/plugin.js
```
应用程序热加载它 — **面板**条目出现在侧边栏（真正的Electron证明）：
### 让代理构建它
在`~/.hermes/config.yaml`（或配置文件）中注册插件的MCP端点，以便Hermes通过工具构建和操作面板：
```yaml
mcp_servers:
boardstate:
url: http://127.0.0.1:9119/api/plugins/boardstate/mcp # 您的仪表盘端口
headers:
X-Hermes-Session-Token: <仪表盘会话令牌>
```
### 连接外部工具（操作层）
```bash
# 状态目录 = $HERMES_HOME/boardstate-state
cat > ~/.hermes/boardstate-state/boardstate.connectors.json <<'EOF'
{ "connectors": [ { "name": "officecli", "transport": "stdio", "command": "officecli", "args": ["mcp"] } ] }
EOF
```
重启；批准小部件显示连接器的**请求**授权。批准您想要的工具 — 工具不会运行，直到您这样做。参见 [docs/connectors/officecli.md](docs/connectors/officecli.md).
### 配置
| 设置 | 默认值 | 备注 |
|---------|---------|-------|
| 面板状态目录 | `$HERMES_HOME/boardstate-state` | `BOARDSTATE_HERMES_STATE_DIR`覆盖 |
| Node二进制文件 | `PATH`上的`node` | `HERMES_NODE_BIN`覆盖 |
| 连接器 | 无 | 操作员编写的`boardstate.connectors.json`在状态目录中 — 绝不是面板文档 |
| 操作员允许列表 | 无（仅环回） | `boardstate.operators.json`；**需要**在有门控多用户模式下 |
| 变异确认超时 | 300 000 毫秒 | `BOARDSTATE_MUTATION_TIMEOUT_MS`（必须 > 0） |
## 执行/观察
| 执行 | 观察 |
|----|---------|
| 打开 **面板**选项卡（网页或桌面） | 在活动主题中渲染；实时跟随调色板交换 |
| 请求代理添加小部件 | 它实时出现，无需重新加载 |
| 点击 **代理总部** | 实时使用情况/会话/实例/ cron — 零错误单元格 |
| 编写`boardstate.connectors.json`，重启 | 批准小部件显示**请求**授权 |
| 批准，然后运行Office Ops操作 | 它**停靠**；确认；一个真正的`.docx`落地 |
| 安装 + 批准小部件包（例如`twenty48`） | 待处理资产404；批准后 → 安装在沙盒中，可玩 |
| 杀死Node / 卸载 | 仪表盘不受影响；选项卡降级为清晰的消息 |
## 开发循环
```bash
npm ci && npm run build # 网页选项卡 + 桌面插件 + 侧车 + 捆绑包（npm固定的@boardstate/*）
```
### 测试（所有测试都在CI中运行 — 23个节点套件 + 3个Python）
| 亮点 | 证明 |
|------|--------|
| `operational-e2e.mjs` | 完整的循环无头：请求 → 批准 → 调用 → **停靠** → 确认 → 结果 |
| `custom-widget.mjs` | 待处理资产404；批准后提供CSP监狱 |
| `rugpull-repend.mjs` | 清单漂移重新挂起授权，绝不执行（回滚检查） |
| `secret-redaction.mjs` | 连接器配置 — 包括环境值 — 绝不到达代理表面（回滚检查） |
| `operator-secret.mjs` | 端口文件知识无法驱动操作员平面 |
| `invoke-timeout.mjs` | 未确认的变异作为停靠结算，绝不会挂起 |
| `asset_proxy.py` | 运行时令牌化资产路由：遍历阻止，CSP原样转发 |
| `operator_wire.py` | 操作员网关的线路合约，包括门控模式403 |
| + 侧车烟雾测试，MCP活跃度，数据线路合约，聊天翻译器，主题（48），模板（27），皮肤，桌面捆绑合约（14） | 每个缝隙都有测试 |
[CHANGELOG.md](CHANGELOG.md)中的完整历史（v1.0.0 → v1.4.0）。
## 许可证
MIT
