13 KiB
AgentHub 平台规划
目标:以 AgentTown 的多 Agent 协作理念为基础,构建一个**框架无关(framework-agnostic)**的 Agent 控制平面。被管理的 Agent 不限于 nanobot / OpenClaw —— 任何进程只要能说 Gateway 协议, 就能被注册、被观测、被派活、被编进协作剧本。当前以 nanobot 作为首批纳管 Agent。
1. 核心设计取舍
| 决策 | 选择 | 原因 |
|---|---|---|
| Agent 寻址方式 | 双向:外拨(Agent 侧接入件主动连 hub)+ 直连(hub 拨 Agent) | 本地/云端部署可直接 HTTP 访问;笔记本、无 ingress 的容器、跳板机后的云主机无法被拨入,只能让 Agent 主动外拨一条 WebSocket。两种形态共用同一套 Frame 协议与同一套任务生命周期;接入件随 Agent 走,hub 不替 Agent 做部署。 |
| 纳管异构框架 | Driver 抽象 + entry-point 插件 | nanobot(OpenAI 兼容 HTTP)、OpenClaw(WebSocket RPC)内置;未知框架通过 agenthub.drivers entry-point 注册,不改本仓库代码。成熟度:connector(所有外拨接入件的 hub 侧驱动)/nanobot/openai_compatible 有真实或等价服务端测试,openclaw 为实验(脚本化 peer 锁协议,上游无可导入的网关实现)。 |
| 数据库 | SQLAlchemy 2.0 async + SQLite,PG/MySQL 仅换 URL | 模型只用可移植类型(字符串主键在 Python 侧生成、JSON 列、UTC datetime),不写 SQL 方言。后期迁移零改写。 |
| 通信 | 单一 Frame 协议贯穿 REST / WebSocket / 外拨接入件 / 控制台 | 新驱动只需实现自己认识的 kind,控制台仍看到同一条事件流。 |
| 前端 | 沿用 AgentTown 技术栈:Next.js 16 + React 19 + Tailwind 4 + lucide + ArkPixel 像素 HUD | 与 AgentTown 视觉语言一致;不引入 Phaser(控制台是表格/事件流,不是场景渲染)。 |
2. 功能模块
2.1 Agent 注册中心(Registry)
- 统一规范:跨 Agent 类型(nanobot / dsh / OpenClaw / direct / 自研接入件)的注册与身份规范见
AGENT_REGISTRATION.md(v2,当前行为)。要点:身份即配置、取消 Agent 侧 身份文件、渠道配置只留连接与身份、role/model归 hub / Agent 自身、只有一种凭证: hub 为这个 Agent 签一把ag_...(库里只存哈希),Agent 侧配置只有 hub 地址 + 这把凭证。 - 建档签发:控制台「接入」页或
POST /agents(issue_credential)建这一行并签出凭证,POST /agents/{ref}/credentials轮换;凭证写进 Agent 自己的配置,agent_id由 hub 在连接 建立时回送 —— Agent 侧没有身份文件,也没有第二种令牌要去分辨。 - 直连:控制台填入 base_url → direct 模式,hub 主动探测,Agent 侧不需要凭证。
- 同名 Agent 再建档 = 409(不静默接管);进程重启靠配置里那把凭证回到同一行,不会变成僵尸记录。
- 元数据:driver、connection_mode、deployment_kind(
local|docker|cloud)、deployment_ref (容器名/主机名/云实例)、labels、capabilities、role、max_concurrency。 - 类型(
agent_type):nanobot | deepseek_harness | openclaw | hermes(其余解析为custom)。 它与 driver(怎么通信)、deployment_kind(跑在哪)正交,控制台的像素小人形象与徽章取自它; 留空表示"跟着 driver 走",老库启动时由增量列迁移补齐(db/init_db.py)。
2.2 Gateway(通信层)
Frame:{v,id,ts,type(req|res|event|err),kind,topic,payload,reply_to,actor,agent_id,task_id,run_id,seq}。- kind:
task.run/task.cancel/agent.ping/agent.describe/agent.command(下行);agent.hello/agent.heartbeat/agent.event/agent.deregister(上行);hub.*/agent.changed/task.changed/run.changed(广播)。 topic支持agent.*.task.<id>.>通配订阅;控制台一条 WS 订阅全部,详情页只订阅自己那棵树。- EventBus:进程内扇出 + 环形缓冲,慢消费者丢弃而不是拖垮 hub;控制台 socket 带
?since=<seq>重连时补发漏掉的帧(先订阅再取快照,补发与直播不重不漏)。 - ControlChannel:外拨接入件在线时 hub 通过它下发
task.run并等待res;连接断开时 pending future 立即失败,不会挂死任务。 - TaskPump:驱动侧事件 → 任务服务是唯一把事件变成 DB 行 + 总线帧的地方,HTTP 流式 / 外拨 WebSocket / mock 三条路径产出完全一致的事件序列。
- 复用 nanobot WebUI 的通道:
nanobot_wsdriver 直接说 nanobot 网关自带 WebSocket 渠道的协议 (ready/message{chat_id,content}/delta/reasoning_delta/stream_end/turn_end), hub 的session_key映射成稳定的 nanobotchat_id,因此一个网关既能被官方 WebUI 用,也能被 hub 派活。
2.3 存在性与健康(Presence)
- 三段判定:外拨通道在线(hub 内存) > 心跳新鲜度(
last_heartbeat_at) > 主动探测(direct HTTP probe)。 - 后台 presence 循环把过期 Agent 标记
offline,degraded由驱动 probe 结果决定。
2.4 任务编排(Tasks)
- 生命周期
queued → dispatched → running → completed|failed|cancelled。 - 事件持久化(
task_events:status/delta/reasoning/tool/log/completed/failed)+ SSE/WS 实时流。 - 全局并发信号量 + 每 Agent
max_concurrency;超时、取消会向下游传播(direct 调 driver.cancel,外拨通道下发task.cancel)。 - 取消幂等:一次取消只发一条
task.cancel(API 与执行协程各自发送会让 API 卡在没人应答的重复 RPC 上), 迟到的completed不能复活已取消的任务。
2.5 多 Agent 协作(Collab,AgentTown 能力承接)
- Team = 成员(agent + role + instructions + 顺序)+ playbook。
- Playbook:
sequential(流水线)/parallel(并发扇出后汇总)/round_robin(多轮)/handoff(Agent 自主移交,[[handoff to:<role>]]或协作 API 投递)。 - Run / RunStep:一次目标执行的全部步骤,逐步产出、可取消。step 在创建任务时就写回
task_id, 执行协程登记在运行表里,取消才能真的打断在跑的那一步并拦住后续成员。 - Blackboard:跨 Agent 共享上下文(不只是上一位的回复)。
- Inter-agent messages:
inform/ask/handoff显式通信留痕,控制台可回放。 - 参与者通过 run grant(HMAC 签名、短期、绑定 run_id+agent_id)回写 blackboard / 投递消息,不持有 hub 主密钥。
2.6 部署纳管(Deployment)
- 三种形态统一登记:
local(本机进程)、docker(容器)、cloud(远端)。 - 接入片段生成器:给定 Agent 配置 → 输出"粘到哪一行"的接入片段
(nanobot 的
channels.agenthub、dsh 的插件 config、direct 的登记命令),内含 hub 地址与凭证; hub 不再生成"跑一个 Agent/桥接进程"的编排(connector 产品面已按规范删除)。
2.7 控制台(Console,前端)
/ 总览(在线/在跑/最近帧)· /agents [id](存在性/能力/任务/探测/凭证/接入片段)·
/tasks [id](实时流)· /teams [id](花名册/playbook/协作回放/黑板)· /runs/[id](时间线)·
/workbench(通用派活面板:任一 Agent + 按 session_key 延续的对话线程 + 实时事件)·
/office(像素办公室,小人按 agent_type 取形象;画面只呈现状态——正在跑的 prompt、人偶走位、
墙上那块合并看板(左栏在岗、右栏任务队列)——产出一律留给右侧控制台。布局数学抽到 frontend/lib/office-layout.ts,
像素块边长由工位数推导并在 1~9 个工位范围内取最大;canvas 后备缓冲 = 显示尺寸 × devicePixelRatio,
所以窗口拉宽或换高 DPI 屏都不会被拉伸糊掉)·
/connect(连入只有两类 · 三步:① 选类型(插件 / 渠道 · 桥接)② 选是哪套 Agent ③ 生成凭证,给出接入片段并随时可回看)· /settings(API Key、驱动、审计、帧审计)。
2.8 被纳管方插件(plugins/)
Hub 不解析每个 Agent 框架的内部;框架侧只要会说 Gateway 协议,就能用自己最自然的方式接进来。
第一个样例是 DeepSeek Harness 插件 @nex/dsh-agenthub:Host 半在 DSH 进程内 apply(ctx),
注册时自报 driver=deepseek_harness + connection_mode=embedded,把 task.run 变成
ctx.sessionController.create/prompt(WebUI 同一条投递路径:自带 agent preset、模型选择、冷会话
resume 与取消策略),把 agent/assistant-stream 与 session/event 变成 hub 的
delta/reasoning/tool 事件;组合里没有 sessionController 时退回 ctx.agents.create/resume 并自装
system-prompt/assemble + agent/request 监听补上模型选择。Client 半提供一个「AgentHub」设置面板。
自带离线自检(打桩 hub + 伪 Cordis ctx),不需要 DSH 运行时即可验证帧协议没跑偏;真机路径已在本机
隔离实例(假模型端点)跑通一整轮,并在现役 web profile 上热加载成功。
3. API 契约(REST,/api/v1)
鉴权:X-API-Key: <key> 或 Authorization: Bearer <key>;Agent 侧用 Bearer ag_...;协作接口用 grant。
| 资源 | 端点 |
|---|---|
| meta/health | GET /healthz(免鉴权) · GET /meta(控制台唯一的枚举来源:drivers / agent_types / connection_modes / deployment_kinds / playbooks) · GET /stats |
| agents | GET/POST /agents(?status=&agent_type=&driver=&deployment_kind=&label=)· GET/PATCH/DELETE /agents/{ref} · `POST /agents/{ref}/probe |
| tasks | GET/POST /tasks · GET /tasks/{id} · GET /tasks/{id}/events?since= · GET /tasks/{id}/stream(SSE) · POST /tasks/{id}/cancel |
| teams | GET/POST /teams · GET/PATCH/DELETE /teams/{ref} · POST /teams/{ref}/runs · `GET /teams/{ref}/blackboard |
| runs | GET /runs · GET /runs/{id} · POST /runs/{id}/cancel · GET /runs/{id}/stream(SSE) |
| collab(Agent 用) | POST /collab/blackboard · POST /collab/messages · GET /collab/context |
| gateway | POST /gateway/heartbeat · POST /gateway/deregister · GET /gateway/status · GET /gateway/frames · WS /gateway/ws?agent_token=(Agent 外拨) · WS /stream?topics=&since=(console) |
| 密钥/审计 | GET/POST /keys · DELETE /keys/{id} · GET /audit · GET /presence |
| 接入片段 | GET /deploy/templates · POST /deploy/plan(拼接入 config,不落盘、不起进程) |
4. 目录结构
backend/agenthub/
config.py security.py utils.py cli.py app.py
db/{base,models,init_db}.py
gateway/{frames,bus,hub}.py # 协议 + 总线 + 控制通道
tasks/pump.py # 任务事件泵
adapters/{base,http_openai,openclaw,connector,mock}.py # 驱动
services/{registry,tasks,collab}.py
api/{deps,serializers,routes_*}.py
deploy/snippets.py # 接入片段(nanobot config / dsh 插件 config / direct 登记)
frontend/ # Next.js 16 控制台
deploy/ # 仓库级 docker-compose、Dockerfile
plugins/ # 可选插件包(DeepSeek Harness 等),由被纳管方安装
dsh-agenthub/ # DSH 插件:AgentHub 接入网关(Host + Client 两半)
data/ # 运行数据(SQLite + hub-credentials.json)
docs/PLAN.md # 本文
5. 里程碑
- M1 内核:config/db/models/gateway/adapters/services —— 已完成。
- M2 API + 实时:
api/全部路由、SSE+WS、鉴权、存在性循环、CLI。验证:pytest全绿(注册→派活→流式→取消→协作跑通)。 - M3 外拨接入:接入件带着自己的凭证外拨 + NAT 后派活(connector 产品面后按规范降级为 SDK)。
- M4 控制台:上述 7 个页面,
pnpm typecheck+pnpm build通过。 - M5 接入片段:nanobot / dsh / direct 三类片段生成 + 文档。
- 移植:
AGENTHUB_DATABASE_URL=postgresql+asyncpg://…或mysql+aiomysql://…即切换;Alembic 在表结构开始演进时引入。 - M6 通用接入面:
nanobot_ws(复用 nanobot WebUI 的 WebSocket 渠道)+/workbench通用派活面板agent_type类型与像素形象;运行数据统一到仓库根data/。
- M7 插件化接入:
plugins/dsh-agenthub落地 DeepSeek Harness;Hermes 类型与形象已就位, 待按其 CLI/协议补一个 adapter(同一套 Gateway,不改 hub 内核)。