# 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`](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..>` 通配订阅;控制台一条 WS 订阅全部,详情页只订阅自己那棵树。 - **EventBus**:进程内扇出 + 环形缓冲,慢消费者丢弃而不是拖垮 hub;控制台 socket 带 `?since=` 重连时补发漏掉的帧(先订阅再取快照,补发与直播不重不漏)。 - **ControlChannel**:外拨接入件在线时 hub 通过它下发 `task.run` 并等待 `res`;连接断开时 pending future 立即失败,不会挂死任务。 - **TaskPump**:驱动侧事件 → 任务服务是**唯一**把事件变成 DB 行 + 总线帧的地方,HTTP 流式 / 外拨 WebSocket / mock 三条路径产出完全一致的事件序列。 - **复用 nanobot WebUI 的通道**:`nanobot_ws` driver 直接说 nanobot 网关自带 WebSocket 渠道的协议 (`ready` / `message{chat_id,content}` / `delta` / `reasoning_delta` / `stream_end` / `turn_end`), hub 的 `session_key` 映射成稳定的 nanobot `chat_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:]]` 或协作 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: ` 或 `Authorization: Bearer `;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|describe` · `POST /agents/{ref}/command` · `GET /agents/{ref}/tasks` | | 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|messages` | | 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. 里程碑 1. **M1 内核**:config/db/models/gateway/adapters/services —— 已完成。 2. **M2 API + 实时**:`api/` 全部路由、SSE+WS、鉴权、存在性循环、CLI。验证:`pytest` 全绿(注册→派活→流式→取消→协作跑通)。 3. **M3 外拨接入**:接入件带着自己的凭证外拨 + NAT 后派活(connector 产品面后按规范降级为 SDK)。 4. **M4 控制台**:上述 7 个页面,`pnpm typecheck` + `pnpm build` 通过。 5. **M5 接入片段**:nanobot / dsh / direct 三类片段生成 + 文档。 6. **移植**:`AGENTHUB_DATABASE_URL=postgresql+asyncpg://…` 或 `mysql+aiomysql://…` 即切换;Alembic 在表结构开始演进时引入。 7. **M6 通用接入面**:`nanobot_ws`(复用 nanobot WebUI 的 WebSocket 渠道)+ `/workbench` 通用派活面板 + `agent_type` 类型与像素形象;运行数据统一到仓库根 `data/`。 8. **M7 插件化接入**:`plugins/dsh-agenthub` 落地 DeepSeek Harness;Hermes 类型与形象已就位, 待按其 CLI/协议补一个 adapter(同一套 Gateway,不改 hub 内核)。