agenthub/docs/PLAN.md

13 KiB
Raw Blame History

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_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:<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. 里程碑

  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 内核)。