143 lines
13 KiB
Markdown
143 lines
13 KiB
Markdown
# 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.<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|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 内核)。
|