企业官网建设流程全解析

Hermes WebUI 外部数据源接入指南：5 分钟让 AI 会话连上你的看板、数据库和文件

【免费下载链接】hermes-webuiHermes WebUI: The best way to use Hermes Agent from the web or from your phone!项目地址: https://gitcode.com/GitHub_Trending/he/hermes-webui

你手里的任务数据在 Kanban 里，用量数据在 Insights 里，业务数据散落在 Excel 和 CSV 中——想让 Hermes WebUI 这个 Web 端 AI 助手直接读到它们，却不知道从哪下手。这篇指南按数据流动的方向，带你把外部数据源一步步接进 Hermes WebUI：从看板数据库到会话数据，再到工作区文件，每条路径都给出具体入口和最小配置。

你的数据卡在哪：先分清四类外部数据

这一节帮你把"外部数据源"拆成四件具体的事，避免一上来就纠结技术选型。Hermes WebUI 的接入方式取决于数据在哪、谁写谁读：

判断顺序很简单：数据已经在 Hermes 体系内（看板、会话）走前两类；数据是你的本地文件走第三类；数据要给别的程序用走第四类。

5 分钟接上第一个数据源：Kanban 看板数据库

看板是 Hermes WebUI 与外部数据库交互最完整的一条链路，适合当你的第一个练手数据源。它不需要你写任何适配代码。

按下面顺序操作：

1. 启动 WebUI，确认 Hermes Agent 侧的看板数据库可访问。WebUI 侧的 kanban_bridge.py 把hermes_cli.kanban_db当作唯一数据源，前端只是读写它。
2. 打开任意会话，确认看板任务卡片能正常加载。这一层走的是/api/kanban/*下的完整 CRUD 接口，包含多看板管理、任务依赖、评论与 SSE 实时事件流。
3. 想验证数据一致性，直接在浏览器地址栏请求任务接口，返回的 JSON 应与看板上卡片字段一致。
4. 数据源接好后，你在 Web 界面的每次改板操作都会写回同一份数据库，不存在双份状态。

到这里，第一个数据源就接上了：没有配置项，没有代码，WebUI 与 Agent 看板共享同一个事实来源。

用 MCP 把会话数据暴露给外部 Agent

这一节解决反向问题：不是 WebUI 读你的数据，而是别的 MCP 兼容 Agent 来读 WebUI 的项目与会话。仓库根目录的 mcp_server.py 已经实现了这套协议，它直接复用 WebUI 的api.models、api.profiles等模块，保证锁和 profile 隔离与 WebUI 主进程行为一致。

在 Agent 的 config.yaml 里注册服务

打开你的 Hermes Agent 配置文件，按下面格式添加一段（command指向 venv 里的 Python，args指向 mcp_server.py）：

mcp_servers: hermes-webui: command: /path/to/venv/bin/python3 args: [/path/to/hermes-webui/mcp_server.py] env: HERMES_WEBUI_PASSWORD: your_password

保存后重启 Agent，它就能以工具调用方式列出你的项目、读取会话元数据。若 WebUI 没有跑在默认端口，设置HERMES_WEBUI_HOST和HERMES_WEBUI_PORT环境变量即可对齐，不用改代码。

多 profile 场景下指定数据范围

如果 WebUI 管理了多个 profile，在args里追加--profile参数，例如[/path/to/hermes-webui/mcp_server.py, --profile, work]，外部 Agent 就只能看到这个 profile 下的项目与会话。这是最省事的数据范围控制手段，比事后过滤安全。

让工作区里的 Excel 和 CSV 进入 AI 视野

文件类数据源不需要任何"连接"——文件放进会话工作区，就是数据源。这一节讲清楚它是怎么生效的、以及一个常见报错。

把 CSV、JSON、docx、xlsx、pptx 拖进工作区面板后，workspace.py 会解析并生成预览；其中 Office 格式由 office_documents.py 负责，它内置了严格的体积上限（单文档 4MB、单表 5000 单元格等），防止超大文件拖垮服务。预览生效后，AI 在会话中就能引用这些内容做分析，你无需导出再粘贴。

如果预览报错提示缺少依赖，说明服务器端没装 Office 解析库。按提示执行一次即可：

pip install python-docx openpyxl python-pptx

装完刷新页面，预览恢复。用量类数据则不需要你操心：会话的 token、成本指标自动写入状态库，Insights 面板直接可视化。

选哪种接入方式：三个高频问题的直接回答

前面四条路径都过了一遍，这一节用问答帮你快速定位该走哪条。

Q：我只想让自己的 Agent 在网页上查自己的数据，要配置什么？什么都不用配。看板与会话数据走内置桥接和状态库，登录 WebUI 就能用，重点是确认 profile 对不对。

Q：两个不同系统的 Agent 都要访问这批数据，怎么办？走 MCP。它用标准协议暴露项目与会话管理工具，任何 MCP 兼容端都能接，再用--profile划清数据边界。

Q：数据是运营团队每周发来的 xlsx，怎么让 AI 直接分析？放进对应会话的工作区就行。文件即数据源，Office 解析库装好之后 AI 可以直接引用单元格内容，不用你手工转格式。

接不通时先查这 3 个地方

排障顺序从便宜到贵：先确认数据源本身活着，再确认 WebUI 侧的入口，最后看隔离配置。

1. 数据源侧：Kanban 桥接报 400 多半是?board=<slug>参数拼错，接口会主动抛错而不是 500；MCP 连不上先检查HERMES_WEBUI_PASSWORD是否与 WebUI 端一致。
2. 服务侧：确认 WebUI 跑在预期端口（默认 8787），MCP 端的环境变量HERMES_WEBUI_HOST/PORT与实际监听一致。
3. 隔离侧：profile 不匹配时你看不到的是"空"而不是"错"——先切到正确 profile 再排查其他原因。

下一步

• 读完 docs/EXTENSIONS.md，了解如何用本地扩展把自研数据面板嵌进 WebUI 界面
• 对照 docs/onboarding.md 检查 Agent 与 WebUI 的 profile 是否对齐
• 打开 Insights 面板核对接入后的用量数据是否如预期落库

【免费下载链接】hermes-webuiHermes WebUI: The best way to use Hermes Agent from the web or from your phone!项目地址: https://gitcode.com/GitHub_Trending/he/hermes-webui