Hubloom

如果说 Spring Boot 是后端接口的「地基」，Vue Admin 是后台页面的「脚手架」，那 Hubloom 就是 AI Agent 时代的基座脚手架。

它不是一个独立的聊天机器人，而是一层让现有业务系统长出 AI 手脚的胶水：接上你现有的 Swagger/OpenAPI 文档，Agent 就能在真实 API 上完成「决策 → 调工具 / 追问 / 确认 → 收工」。回复用 Markdown；网页可挂起等人（interactive），企微等入口用跨轮交班。业务逻辑依然留在你的系统里，Hubloom 只做「翻译」和「路由」。

你主要做： 配 LLM 与 Swagger、写 Skill（含可选 Playbook）、按需定制前端或嵌入门户。
底座替你搞定： 工具调用（MCP）、Typed ReAct 编排、SSE 流式回合、会话记忆、鉴权透传与过程可观测。

交付分两层：Hubloom Serve（src/server/ / main.py）产品 API；演示前端（examples/chat/web）开箱对话。记忆、RAG、A2A、Events、企微等为可选能力，默认不挡主路径。

推荐部署： 浏览器 / App → 企业 BFF → Hubloom（不建议公网直连 Serve）。登录与限流放在 BFF；Hubloom 侧重办事编排。

协议要点：MCP 把 HTTP 变成工具；产品出站为简洁 JSON SSE（无 A2UI / AG-UI）。完整手册见 docs/（Docsify）。

特性

• 嵌入式智能，而非旁路助手：智能体站在流程与数据平面上办事，直接触达企业 API，结果可核对、过程可复盘

• 契约即能力：OpenAPI/Swagger 动态映射工具面，换业务域主要换配置，快速复用存量数字化资产

• Policy-Bounded Typed ReAct：单环 Decide → Gate → act / ask / await_confirm / finish；Skill Playbook 可硬拦

• Wait Profile：网页 interactive 挂起续跑；企微等 turn_based 跨轮；事件入口 no_wait

• Markdown 体验：结论与过程用 Markdown；工具调用可展开复盘（演示前端无 A2UI 面板）

• 从建议到闭环：经 MCP 元工具调用真实 REST，把「能说会道」变成「能做完事」

• 会话历史可选后端：memory.conversation_store = sqlite | postgres（库不存在时可自动建库）

• Redis 必填：挂起态、按 session 锁、Events 幂等/串行、企微会话队列

• Events / 企微已挂 Serve：POST /v1/events、GET|POST /v1/im/wecom/callback

• 过程可审计：轨迹、工具链与 SSE 事件可上屏、可复盘

Related MCP server: Swagger MCP

界面预览

对话办事：自然语言驱动 MCP 工具，Markdown 呈现结论（工具调用过程可展开查看）。

创建完成后用表格核对系统状态（工具调用过程可展开查看）。

架构文档

Hubloom Serve 负责产品 HTTP API；examples/chat/web 负责开箱演示前端；Runtime（HubloomRuntime）可嵌入门户与自有应用。生产推荐由企业 BFF 转发，演示前端仅用于本地联调。

本地预览文档站（Docsify）：

npx --yes serve docs -p 3000

浏览器打开 http://127.0.0.1:3000。文档按学习路径组织：

产品 API 速查：Hubloom Serve。

快速开始

环境要求

• Python 3.12+

• uv（推荐）或 pip

• Redis（必填）

• Node.js（仅跑演示前端时需要）

• Postgres（仅当 memory.conversation_store=postgres 时需要）

1. 安装依赖

uv sync

或使用 pip：

pip install -r requirements.txt

2. 配置

cp config/env.example.yaml config/env.yaml

在 config/env.yaml 中填写：

• llm.*、redis.url（必填）

• mcp.swagger_url / base_url（启用 MCP 时）

• 可选：memory.conversation_store（sqlite | postgres）、events.*、im.wecom.*

业务 Bearer 由请求传入（Authorization / X-MCP-Token 或事件体 bearer_token），不要写进配置文件。

3. 启动 Hubloom Serve + 演示前端

# 产品 API（默认 :8765，见 config http.port）
PYTHONPATH=src uv run python main.py
# 或：PYTHONPATH=src uv run python -m server serve --config config/env.yaml

# 前端（另开终端；本地演示用）
cd examples/chat/web && npm install && npm run dev

• Web 对话页：http://127.0.0.1:5173/（Vite 代理 /v1 → Serve）

• API 文档：http://127.0.0.1:8765/docs

健康检查

curl http://127.0.0.1:8765/health

调用对话接口

curl -s http://127.0.0.1:8765/v1/chat \
  -H "Content-Type: application/json" \
  -H "X-Session-Id: demo-session" \
  -H "X-MCP-Token: your-business-token" \
  -d '{"message":"你好，你能做什么？","stream":false,"wait_profile":"interactive"}'

默认 SSE（"stream": true）。历史：GET /v1/chat/history?session_id=demo-session。
缺参续跑：POST /v1/chat/resume（interactive）。

事件入站

# 需 events.enable=true；若配置了 shared_secret 则带上 X-Event-Secret
curl -sS -X POST "http://127.0.0.1:8765/v1/events" \
  -H "Content-Type: application/json" \
  -H "X-Event-Secret: change-me" \
  -d '{"event_id":"evt-1","type":"locker.created","session_id":"demo-1","payload":{"deviceId":"LK-A-001"}}'

企业微信

• Serve：GET|POST /v1/im/wecom/callback（im.wecom.enable=true）

• 企微后台「接收消息 URL」填公网 HTTPS，例如 https://<tunnel>/v1/im/wecom/callback

• 管道联调（不经 Agent）：tests/test_im_wecom.py 的 send / echo

• 说明见 企业微信入口、模块文档

测试计划

目标：用分层测试证明「换 Swagger 能办事、多入口行为一致、并发与幂等正确」。本地演示前端仅联调；生产路径以 BFF → Serve 为准。

A. 冒烟（CI / 无真 LLM）

PYTHONPATH=src .venv/bin/python -m pytest \
  tests/test_hubloom_serve.py \
  tests/test_hubloom_serve_events_wecom.py \
  tests/test_conversation_store_factory.py \
  tests/test_agent_v2_step1.py \
  tests/test_agent_v2_step2.py \
  tests/test_agent_v2_step3.py \
  tests/test_agent_v2_step4.py \
  tests/test_agent_v2_flow.py -q

B. 不同业务 Swagger（真 MCP）

换 mcp.swagger_url / base_url（及按需 Bearer），验证「契约即能力」：

辅助脚本：tests/test_mcp_list_tools.py、tests/test_mcp_serve_swagger.py；端到端对话：tests/test_hubloom_serve_chat_task.py（需已启动 Serve + 真 LLM）。

C. 事件（Events）

D. 企业微信（IM）

E. 并发与稳定性

F. 记忆 / RAG / Skill（按需）

G. 高强度复杂问题（建议清单）

人工 / 脚本构造，优先覆盖：

• 多轮追问 + 确认 + 真实写操作（含 Gate 打回）

• 工具失败重试、部分成功、空结果

• 长对话历史裁剪后仍能办完事

• Events 重放与并发同 session

• 企微短回复 vs Web 长历史一致性

• thought_delta 与最终答案是否冗余刷屏

• 换业务域 swagger 后旧 Skill/Playbook 是否仍成立

路线图

当前版本

• OpenAPI → MCP 工具面（catalog + 元工具 list_api / call_api）

• Policy-Bounded Typed ReAct 单环（Decide → Gate → Act / Ask / AwaitConfirm / Finish）

• Evidence Journal + Wait Profile（interactive / turn_based / no_wait）

• Hubloom Serve 产品 HTTP API（简洁 SSE，无 A2UI / AG-UI）

• 演示前端：Markdown 对话 + interactive 挂起续跑

• 会话历史 SQLite / Postgres 可配置；Redis 挂起态与 session 锁

• 可选长期记忆与 RAG 知识库

• A2A 双向 MVP：入站 Server、出站 list_agents / delegate_task

• Events 入站已挂 Serve（POST /v1/events，Redis 幂等 + 串行）

• 企微回调已挂 Serve（/v1/im/wecom/callback，Redis 队列，短回复）

下一步

• 高强度测试与文档：按上方测试计划推进；README / 模块文档与现状持续对齐

• 事件驱动增强：消息队列 / 定时告警入站、结果回调完善、打开会话时主动推屏

• IM 增强：事件结果推企微、钉钉 / 飞书 / Slack、企微内表单/卡片

• 体验打磨：thought_delta 与最终答案去重、企微/Web 话术分层

• 自动化运营增强：流程编排与无人值守、多智能体协同再进一步

• A2A 增强：链式委托、动态发现、正式凭证 Provider

• 可观测与运维：出站指标、部署与 BFF 对接约定（Hubloom 侧服务鉴权按需再加）

协议栈

产品路径不再依赖 A2UI / AG-UI；演示与集成以 Markdown + Serve SSE 为准。

许可证

本项目基于 Apache License 2.0 开源发布。