Hermes Labyrinth 是 Hermes Agent 的只读可观测性插件，由 ara.so 提供，属于 Hermes Skills 集合。它用于监控自主智能体的执行过程，将智能体的“旅程”（journeys）可视化为一系列“穿越”（crossings），包括提示、工具调用、结果、失败、模型切换和子智能体等事件，并生成可导出的报告，内置密钥脱敏。
用途 该插件面向需要审计、调试或分析自主智能体运行轨迹的用户。它读取 Hermes 的状态数据，以只读方式呈现智能体会话的完整执行序列，帮助理解智能体在任务中做了什么、调用了哪些工具、是否发生失败或模型切换。
主要能力
- 旅程可视化：将智能体执行过程展示为按顺序排列的穿越事件（消息、工具调用、结果等）。
- 报告导出：支持 JSON 和 Markdown 格式导出单个旅程报告，两种格式均自动应用密钥脱敏。
- 只读 API：提供健康检查、旅程列表、旅程详情、旅程穿越、技能清单、Cron 配置、Guideposts 观察等端点，所有端点均为只读并自动脱敏。
- 技能清单：返回已加载的有效技能、被覆盖的预期用户覆盖项、重复诊断、技能扫描错误。
- Cron 配置：返回计划自主任务、下次运行时间、最近失败和工作目录。
- Guideposts：返回基于本地证据生成的跨旅程观察。
- 前端仪表盘：在 Hermes 仪表盘 UI 中新增 Labyrinth 标签页，地址为 http://127.0.0.1:9119。
使用方式 安装到 Hermes 用户插件目录：
mkdir -p ~/.hermes/plugins git clone https://github.com/stainlu/hermes-labyrinth.git ~/.hermes/plugins/hermes-labyrinth
安装后重启 Hermes 仪表盘：
hermes dashboard
Docker 安装时，挂载插件目录并固定到已审查版本：
mkdir -p ~/.hermes/plugins git clone https://github.com/stainlu/hermes-labyrinth.git ~/.hermes/plugins/hermes-labyrinth cd ~/.hermes/plugins/hermes-labyrinth git checkout v0.1.3
然后将 Hermes 主目录挂载到容器中并重启仪表盘。
插件管理：
- 仅前端重扫描：curl http://127.0.0.1:9119/api/dashboard/plugins/rescan（后端 API 变更需完整重启仪表盘）。
- 禁用/移除：hermes plugins disable hermes-labyrinth；rm -rf ~/.hermes/plugins/hermes-labyrinth；curl http://127.0.0.1:9119/api/dashboard/plugins/rescan。
API 参考（均为只读并自动脱敏）：
- 健康检查：curl http://127.0.0.1:9119/api/plugins/hermes-labyrinth/health
- 旅程列表：curl http://127.0.0.1:9119/api/plugins/hermes-labyrinth/journeys
- 旅程详情：curl http://127.0.0.1:9119/api/plugins/hermes-labyrinth/journeys/{journey_id}
- 旅程穿越：curl http://127.0.0.1:9119/api/plugins/hermes-labyrinth/journeys/{journey_id}/crossings
- 技能清单：curl http://127.0.0.1:9119/api/plugins/hermes-labyrinth/skills
- Cron 配置：curl http://127.0.0.1:9119/api/plugins/hermes-labyrinth/cron
- Guideposts：curl http://127.0.0.1:9119/api/plugins/hermes-labyrinth/guideposts
- 导出 JSON 报告：curl http://127.0.0.1:9119/api/plugins/hermes-labyrinth/reports/{journey_id}.json > journey.json
- 导出 Markdown 报告：curl http://127.0.0.1:9119/api/plugins/hermes-labyrinth/reports/{journey_id}.md > journey.md
插件读取的数据源：
- ~/.hermes/state.db：会话和消息（SQLite）
- ~/.hermes/skills/：用户和捆绑技能
- ~/.hermes/cron/：计划任务配置
前端开发：仪表盘 UI 由模块化 JavaScript 组件构建。构建命令 npm run build 生成 dashboard/dist/labyrinth-bundle.js、dashboard/dist/labyrinth.css 和 index.html。开发工作流包括 npm run build、npm run check、npm run smoke、npm run smoke:live。
配置：可选主题可复制到 ~/.hermes/dashboard-themes/。插件清单位于 dashboard/manifest.json，包含名称、版本、标题、描述、入口 JS/CSS 和 API 模块。
安全与脱敏 Labyrinth 对所有输出应用 Hermes 核心密钥脱敏。若脱敏器不可用，则采用失败关闭机制，返回 [redaction unavailable]，不会导出未脱敏内容。生产前建议用虚拟密钥验证脱敏是否生效。
测试
- 完整测试套件：npm test（包含构建可复现性检查、JavaScript/Python 解析验证、API 规范化夹具测试、无头 Chrome 冒烟测试）。
- 后端 API 测试：python3 scripts/test-plugin-api.py。
- 手动冒烟测试：npm run smoke。
适用场景 适用于需要监控自主智能体执行轨迹、审计工具调用模式、分析失败原因、检查技能加载情况、查看计划任务配置，以及导出脱敏报告进行进一步分析的场景。
限制 该插件为只读，不修改智能体行为。后端 API 变更需要完整重启仪表盘，仅前端重扫描不够。脱敏依赖 Hermes 核心，若不可用则导出内容会被替换为占位符。其他具体限制暂未提供。