agenthub/docs/PLAN.md

143 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

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