diff --git a/README.md b/README.md index 5df789e..331568f 100644 --- a/README.md +++ b/README.md @@ -1,98 +1,171 @@ # AgentHub 多 Agent 协作控制面:把**本地进程、Docker 容器、云端实例**里的各种 Agent 统一纳管起来, -用一个 Gateway 通信,用一套 Playbook 编排协作。nanobot 是第一个被管理的 Agent,但不是唯一一个 -——OpenClaw、任何 OpenAI 兼容服务、甚至一个 shell 脚本都能接进来。 +用一条 Gateway 通信,用一套 Playbook 编排协作。nanobot 是第一个被纳管的 Agent,但不是唯一一个 +——DeepSeek Harness、codex / claude / WorkBuddy 这类无头 CLI、OpenClaw、任何 OpenAI 兼容服务都能接进来。 -规划文档见 [`docs/PLAN.md`](docs/PLAN.md);跨 Agent 类型的注册与身份规范(待沟通稿)见 -[`docs/AGENT_REGISTRATION.md`](docs/AGENT_REGISTRATION.md)。`soucecode/` 是参考仓库(nanobot、agent-town),不参与构建。 +规划文档见 [`docs/PLAN.md`](docs/PLAN.md);跨 Agent 类型的注册与身份规范见 +[`docs/AGENT_REGISTRATION.md`](docs/AGENT_REGISTRATION.md)。`soucecode/`(nanobot、agent-town 的参考 clone) +已 .gitignore,不参与构建。 ``` 浏览器 ── ▶ 控制台 (Next.js, :3100) │ REST + WebSocket/SSE(API Key) ▼ AgentHub Hub (FastAPI, :8100) - ├ Registry 登记 / 身份 / 能力 + ├ Registry 登记 / 身份 / 能力 / 凭证 ├ Gateway Frame 协议 + 事件总线 + 帧审计 ├ Tasks 单 Agent 任务(流式事件) ├ Collab 团队 / Playbook / Run / 黑板 / 交接 - └ Registry Agent 登记 / 凭证签发 + └ Deploy 接入片段渲染 + 签发存档 │ 唯一一条通道:Gateway 的 Frame 协议(JSON 帧 + 流式事件) ┌──────────────┴──────────────┐ ▼ 外拨(push) ▼ 直拨(direct) Agent 自己连 hub hub 拨 Agent 的 HTTP/WS - nanobot channel / dsh 插件 本机 nanobot serve / OpenClaw + nanobot 渠道 / dsh 插件 / 桥接 nanobot serve / OpenAI 兼容 / OpenClaw ``` -**只有 Gateway 一个通信进程**:任务下发、流式事件、心跳、探测、取消全走同一套 Frame 协议, -两种形态的差别只在「谁发起这条连接」,协议本身一模一样。**接入件随 Agent 走**: -每个 Agent 类型写一个专门的接入件(nanobot 是渠道、DeepSeek Harness 是插件),hub 不替它们做部署。 +**只有 Gateway 一个通信进程**:建档、派活、流式事件、心跳、探测、取消、指令全走同一套 Frame 协议, +两种形态的差别只在「谁发起这条连接」。帧类型: +`agent.hello/hub.hello/heartbeat/ping/probe/event/command/describe/deregister/changed`、 +`task.run/cancel/changed`、`run.changed`、`hub.event(s)`、`frame.audit`。 +Agent 侧走 `WS /api/v1/gateway/ws?agent_token=ag_…`,控制台事件流走 `WS /api/v1/stream`。 | 形态 | `connection_mode` | 谁发起连接 | Agent 侧改动 | 什么时候用 | | --- | --- | --- | --- | --- | -| **外拨**(推荐) | `embedded` | Agent 进程里的接入件往外拨 WS | 装接入件 + 写一段 config | 能改 Agent 的镜像 / 依赖,想一个容器就是一个 Agent | -| **直拨** | `direct` | hub 直接拨 Agent 的 HTTP/WS | 0 改动 | hub 能直达 Agent:本机进程、同网段、带 key 的公网端点。**「接入」向导不提供这一类**,只能手工登记 | +| **外拨**(推荐) | `embedded` / `connector` | Agent 进程里的接入件往外拨 WS | 装接入件 + 写一段 config | 能改 Agent 的镜像 / 依赖;NAT 后、只有出网权限的容器和云主机 | +| **直拨** | `direct` | hub 直接拨 Agent 的 HTTP/WS | 0 改动 | hub 能直达 Agent。**「接入」向导不提供这一类**,只能手工登记 | -连入只有两类(详见 [`docs/AGENT_REGISTRATION.md`](docs/AGENT_REGISTRATION.md)):**插件 / 渠道** -(Agent 里贴一段配置:DeepSeek Harness 插件、nanobot 渠道、OpenClaw 渠道)和**桥接** -(Agent 只有一套 CLI:codex / claude / WorkBuddy,旁边跑一个桥接进程)。两类要填的一字不差 —— -hub 给这把 `ag_…`,Agent 侧只填两样:**hub 的地址** + **这把凭证**,连上就算注册验证完成。 -`agent_id` 由 hub 在连接建立时告诉 Agent;**Agent 侧没有身份文件,也没有第二种凭证**; -签过的凭证随时能查回来(控制台「查看凭证」/ `agenthub config`),不必为看一眼明文而轮换。 - -**外拨**是 Agent 出站连 hub,所以 NAT 后面、只有出网权限的容器和云主机一样能纳管; -只有**直拨**要求 hub 能拨进 Agent,因此它需要 Agent 暴露入站端口。 +`driver_for()` 对 `connection_mode in ("connector", "embedded")` 一律返回 `connector` 驱动: +`embedded` 和 `connector` 在 hub 侧是同一条通道,`driver` 只说明背后跑的是什么。 ## 快速开始 +```bash +./scripts/dev.sh # 一键起 hub + 控制台,缺依赖自动补装 +./scripts/dev.sh --seed # 顺便灌一份演示 Agent / 团队 +./scripts/dev.sh --reload # 后端带 --reload +HUB_PORT=8200 CONSOLE_PORT=3200 ./scripts/dev.sh +``` + +脚本会检查端口占用(被 launchd 托管时说明为什么杀不掉),并把控制台用的 API Key 打在终端上。 +Ctrl-C 一起停两个进程。容器版在 `deploy/docker-compose.yml`。 + +手工两步: + ```bash # 1) 后端(Python 3.11+) cd backend && python -m venv .venv && source .venv/bin/activate pip install -e . # 国内可加 -i https://pypi.tuna.tsinghua.edu.cn/simple agenthub init # 建表 + 生成 /hub-credentials.json -agenthub seed # 可选:灌演示 Agent / 团队,方便先看效果 agenthub serve # http://127.0.0.1:8100 ,API 文档 /docs # 2) 前端(Node 20+,pnpm) cd frontend && pnpm install && pnpm dev # http://127.0.0.1:3100 ``` -登录控制台需要 hub API Key:首次启动写在项目根目录的 `data/hub-credentials.json`(也可在 -serve 日志里看到)。在页面右上角「配置 API KEY」粘贴即可,Key 只存在浏览器 localStorage。 +控制台右上角「配置 API KEY」粘贴 hub 的 API Key(首次启动写在 `data/hub-credentials.json`),Key 只存浏览器 localStorage。 -## 接入一个 Agent +## 接入:三步向导 -接入只有一种凭证:hub 签发一把 `ag_…`,Agent 那边填「hub 地址 + 这把凭证」 -(完整规范见 [`docs/AGENT_REGISTRATION.md`](docs/AGENT_REGISTRATION.md)): +只有两类接入:**插件 / 渠道**(Agent 里本来就有可以装东西的地方)和**桥接**(Agent 只有一套 CLI, +旁边跑一个进程替它拨 hub)。向导就三步,按钮只有**下一步 / 上一步 / 完成**: -**codex / claude / WorkBuddy 这类无头 CLI 走桥接**:不动它一行代码,在它所在机器上跑一个桥接进程, -它自己往外拨 hub(`deploy/cli-bridge/README.md`): +| 步骤 | 内容 | +| --- | --- | +| ① 选择类型 | 插件 / 渠道 · 桥接 | +| ② 选择 Agent | DeepSeek Harness、nanobot、OpenClaw / codex、claude、WorkBuddy;填「Agent 名字」。只有桥接多问两个:**工作目录** + **权限**(`readonly` / `write`) | +| ③ 生成凭证 | **走到这一步就已经签好了**:直接显示 `ag_…` 明文和那段配置原文,各自带 COPY。想换一把点右侧小号「重新签发」;点「完成」回到第 ① 步 | -```bash -agenthub agent add --name codex-1 --driver connector --connection connector --show-token -python3 deploy/cli-bridge/bridge.py --hub http://127.0.0.1:8100 --token ag_… \ - --name codex-1 --cli codex --workdir ~/code/目标仓库 --mode readonly +页面顶部只有一行 `Hub 地址 ` + COPY —— Agent 侧那一格 `server` 就抄它。 +名字已在册时不报错拦人:hub 返回 409 时向导自动改成给原来那一行**换一把新凭证**(同一台 Agent 重新接一次就是这个场景)。 + +签发一次实际发三个请求: + +``` +POST /api/v1/agents { …建档, issue_credential: true } → ag_… +POST /api/v1/agents/{name}/credentials (仅同名 409 时) +POST /api/v1/deploy/plan { kinds:[kind], agent_ref, agent, agent_token, record: true } ``` -其余 Agent(nanobot / DeepSeek Harness / OpenClaw / 自研)做的是同一件事:**控制台「接入」页选类型 -→ 选 Agent → 点「生成凭证」→ 把片段贴过去**,那一格里装的就是刚签出来的 `ag_…`。命令行等价: +### 四种片段 -```bash -agenthub agent add --name nanobot-1 --driver nanobot --connection embedded --show-token -agenthub config --name nanobot-1 --kind nanobot # 或 bridge / dsh / claw +`POST /deploy/plan` 返回 `{ agent, hub_url, files:[{kind, filename, content}], next_steps, note }`; +`KINDS = ("bridge","nanobot","dsh","claw")`,文件名分别是 `bridge.sh`、`nanobot-config.json`、 +`cordis.patch.yml`、`openclaw-agenthub.json`。不管哪一类,Agent 侧要填的都只有两格: +**哪个 hub**(`server`)+ **我是谁**(`agent_token`)。没有 hub id、也没有 agent id 可抄—— +凭证就是身份,socket 起来之后 hub 把自己的那份 id 告诉 Agent。 + +```yaml +# cordis.patch.yml(dsh)——接进 ~/.dsh/profiles//cordis.patch.yml 顶层数组 +- insert: + - id: dsh-agenthub + name: '@nex/dsh-agenthub' + config: + server: http://127.0.0.1:8100 + name: dsh-web + displayName: dsh-web + agentToken: ag_xxxxxxxx ``` -- **凭证就是身份**:只有那一格(`agent_token` / `agentToken` / `--token`),`agent_id` 不用抄, - hub 在 `hub.hello` 里给;「验证」= 控制台 Agents 页看到它 online。 -- **身份不落盘**:配置里那一把凭证就是它的全部状态。老版本留下的身份文件只被读一次, - 日志会打印可粘贴的迁移片段。 -- **同名不顶号**:建档时同名直接 409 —— 先决定是复用那一行(拿它现有的凭证)还是换名字。 -- hub 不生成"跑一个 Agent/桥接进程"的编排:`agenthub config` 只给"粘到哪一行"的接入片段。 +```jsonc +// nanobot-config.json → ~/.nanobot/config.json 的 channels.agenthub +{ "channels": { "agenthub": { "enabled": true, "server": "http://127.0.0.1:8100", + "name": "alpha", "display_name": "alpha", "agent_token": "ag_xxxxxxxx" } } } -### 内嵌接入:把 Gateway 客户端塞进 Agent 进程(推荐) +// openclaw-agenthub.json → OpenClaw 的 agenthub 渠道配置 +{ "agenthub": { "enabled": true, "server": "http://127.0.0.1:8100", + "name": "claw-1", "display_name": "claw-1", "agent_token": "ag_xxxxxxxx" } } +``` -`deploy/nanobot-gateway/channel/agenthub/agenthub_client.py` 是一个**单文件、只用标准库 + websockets** -的 Gateway 客户端。任何 Python Agent 接进去只要三步: +```bash +# bridge.sh —— 在有这套 CLI 的机器上跑,它自己往外拨 hub +python3 <本仓库>/deploy/cli-bridge/bridge.py --hub http://127.0.0.1:8100 --token ag_xxxxxxxx \ + --name codex-1 --cli codex --workdir ~/code/目标仓库 --mode readonly +``` + +桥接的工作目录与权限存在这一行的 `config` 里(`_LANDED_KEYS = ("profile","cli","workdir","mode")`), +所以按 `agent_ref` 重新生成片段时能还原出当时贴出去的那条命令。DSH 的 profile 后端仍支持, +但**向导已不再问这一格**:给已在册的 DSH 重生成 `next_steps` 时回落 `web` profile。 + +### 签发记录 + +向导下面的「签发记录」面板是**每次签发的存档本身**,不是连入的 Agent 列表: +一行一次签发,平时只看到「签给谁 + 类型 + 时间」,点开才是当时那把 token(明文)和那段配置原文。 +同一 Agent 的旧记录标 `已失效`。 + +| 项 | 实现 | +| --- | --- | +| 表 | `credential_issuances`(`id/agent_id/agent_name/kind/hub_url/payload_cipher/active/created_at`) | +| 落盘 | `security.seal(secret_key, {agent_token, files})`,读时 unseal;换过 `secret_key` 解不开就给空,不猜内容 | +| 读 | `GET /api/v1/deploy/issuances?limit=50`(token 是明文) | +| 写 | `POST /deploy/plan` 带 `record: true`,**要求 admin key**(read key → 403)。向导走的就是这条,所以存档和贴出去的片段不可能漂移 | + +### 凭证回看与轮换 + +签过的凭证随时能查回来,不必为看一眼明文而轮换: + +- 控制台:Agents 详情页的「凭证」面板(状态 / 查看凭证 / 签发或轮换凭证 / 轮换宽限秒数),或接入页的「签发记录」。 +- API:`GET /api/v1/agents/{ref}/credentials`(管理员 key;库里为此另存一份 seal 的可读副本 `token_cipher`,认证仍只读哈希)。 +- CLI:`agenthub config --name X --kind bridge|nanobot|dsh|claw`(已在册的直接印真值,未建档留 `` 占位)。 + +签在「可回看」之前的老凭证读不回明文(库里只有哈希),点「重新签发」换一把之后就能反复查看。 + +命令行等价(绕开向导时用): + +```bash +agenthub agent add --name codex-1 --connection connector --driver connector --show-token +agenthub agent rotate codex-1 # 立即失效;API 侧还能给 grace_seconds +``` + +## 接入件 + +**接入件随 Agent 走**:每种 Agent 一个专门的接入件,hub 不替它们做部署。协议同一套,所以凭证可以互相替换。 + +### 内嵌 SDK:把 Gateway 客户端塞进 Agent 进程 + +`deploy/nanobot-gateway/channel/agenthub/agenthub_client.py` 是那个单文件客户端(标准库 + websockets)。 +接自己的 Agent 就 import 它写十几行: ```python import os @@ -101,7 +174,7 @@ from agenthub_client import GatewayClient, GatewayConfig async def on_task(task, emit) -> str: # task 里有 prompt / session_key / context async with my_agent.turn(task["prompt"]) as turn: async for chunk in turn: - await emit("delta", text=chunk) # 过程事件:status / delta / reasoning / tool / log + await emit("delta", text=chunk) # status / delta / reasoning / tool / log return turn.answer async def describe() -> dict: # 可选:能力自述,控制台会显示 @@ -110,9 +183,8 @@ async def describe() -> dict: # 可选:能力自述 client = GatewayClient( GatewayConfig( hub_url="http://127.0.0.1:8100", - agent_token=os.environ["AGENTHUB_AGENT_TOKEN"], # 密钥只从环境读,不进代码也不进镜像 + agent_token=os.environ["AGENTHUB_AGENT_TOKEN"], # 密钥只从环境读,不进代码也不进镜像 name="my-agent", - driver="openclaw", deployment_kind="docker", ), on_task, @@ -121,187 +193,49 @@ client = GatewayClient( await client.run() # 断线重连 + 心跳 + 取消,都在里面 ``` -身份**不落盘**:配置里那一把 `agent_token` 就是它的全部身份,进程重建之后填的还是同一把, -`agent_id` 自然也不变。任务从这条 WS 进来, -`delta / reasoning / status / tool / completed` 原样回到 hub 的事件流, -所以不管是哪种接入件,在控制台里长得一模一样。 +身份**不落盘**:配置里那一把 `agent_token` 就是它的全部身份,进程重建之后填的还是同一把,`agent_id` 自然不变。 +`delta / reasoning / status / tool / completed` 原样回到 hub 的事件流。取消也是真的: +客户端收到 `task.cancel` 调 `runner.cancel()`,事件流以 `cancelled` 收场(DSH 插件走 `agent.cancel`)。 -**nanobot 就用这条路**:`channel/agenthub/` 是一个 nanobot channel 包。装进 nanobot 的安装树之后 -`channels.agenthub` 就是一个普通渠道(和 telegram、websocket 同级),nanobot 自己外拨, -它的代码和启动方式都不用改: +### nanobot 渠道 + +`deploy/nanobot-gateway/channel/agenthub/` 是一个 nanobot channel 包。nanobot 只扫 +`nanobot.channels.__path__`,没有外部插件目录,所以装一次进安装树: ```bash -# 1) 装渠道(一次):nanobot 只扫 nanobot.channels.__path__,没有外部插件目录 cp -R deploy/nanobot-gateway/channel/agenthub \ "$(python -c 'import nanobot.channels as p; print(list(p.__path__)[0])')/agenthub" ``` ```jsonc -// 2) ~/.nanobot/config.json —— 和其它渠道一样的写法。 -// 只放「连到哪 + 我是谁」:模型在 agents.defaults.model 里,角色是 hub 侧概念。 +// ~/.nanobot/config.json —— 和 telegram、websocket 同级的普通渠道 { "channels": { "agenthub": { "enabled": true, "server": "http://127.0.0.1:8100", "name": "alpha", "display_name": "阿尔法", - "agent_token": "ag_xxxxxxxx" // 控制台「接入」页签发,只有这一格是凭证 + "agent_token": "ag_xxxxxxxx" // 只有这一格是凭证 }}} ``` ```bash -nanobot gateway --foreground # 3) 起进程,渠道拨上 hub 就上线 +nanobot gateway --foreground # 渠道拨上 hub 就上线,nanobot 的代码和启动方式都不改 ``` -- 配置字段全在 `channels.agenthub` 下,config.json 是正规来源;只有 - `AGENTHUB_AGENT_TOKEN` 这一把凭证 env 优先级更高(compose 注入用), - 其余字段 env 只在没写配置文件时兜底。旧字段名(`hubUrl` 等)一个版本内仍可读。 -- 想要现成的容器:`cd deploy/nanobot-gateway && ./bootstrap.sh`,为两个容器各签一把凭证 - (写进 `.env` 的 `AGENT_TOKEN_ALPHA` / `AGENT_TOKEN_BETA`)→ build → up -d,两个容器、零桥接进程、零入站端口。 -- `bootstrap.sh` 里的模型密钥默认从 `~/.nanobot/config.json` 取,要换 `export DASHSCOPE_API_KEY=... NANOBOT_MODEL=...` 再跑。 -- 镜像 `nanobot:agenthub`(`deploy/Dockerfile.nanobot`)已经把 channel 软链进安装树,compose 又把 - `channel/` bind-mount 进容器,所以容器里不用拷;起栈后 `docker compose ps` 是 - `agenthub-gw-alpha` / `agenthub-gw-beta`。 -- **没有身份文件**:凭证写在 config.json(或 env)里;`docker compose restart` 之后 `agent_id` 不变 - (同名认领)。老实例留下的 `~/.nanobot/agenthub-state.json` 只被读一次,日志会打印可粘贴的迁移片段。 -- compose 里**没有任何 ports**:healthcheck 打的是容器内的 `127.0.0.1:18790`(nanobot gateway 自己的健康端点),hub 拨不进容器,也不需要拨进去。 +- 字段全在 `channels.agenthub` 下:`enabled/server/name/display_name/description/agent_token/deploymentKind/labels`; + 只有 `AGENTHUB_AGENT_TOKEN` 这一把 env 优先级最高(compose 注入用),其余 env 只在没写配置文件时兜底; + 旧字段名(`hubUrl` 等)一个版本内仍可读。 +- `describe()` 回 `{streaming, model, runtime:"nanobot"}`,模型由 Agent 自省上报,不在渠道配置里配。 +- 现成容器:`cd deploy/nanobot-gateway && ./bootstrap.sh` → 写 `.env`(`AGENT_TOKEN_ALPHA` / `AGENT_TOKEN_BETA`、 + `DASHSCOPE_API_KEY`、`NANOBOT_MODEL`,模型 key 默认从 `~/.nanobot/config.json` 取)→ build `nanobot:agenthub` + → 起 `agenthub-gw-alpha` / `agenthub-gw-beta`(阿尔法 / 贝塔,role writer/editor)。 +- 那份 compose **没有任何 ports**,healthcheck 打容器内 `127.0.0.1:18790`(nanobot 自己的健康端点)。 + hub 地址用 `HUB_URL` 覆盖(默认 `http://host.docker.internal:8100`;host 网络下写 `127.0.0.1`, + 同网络写 `http://hub:8100`),落到渠道的 `AGENTHUB_SERVER`(旧名 `AGENTHUB_HUB_URL` 仍可读), + 再加 `AGENTHUB_NAME/DISPLAY_NAME/AGENT_TOKEN/DEPLOYMENT_KIND/DEPLOYMENT_REF/LABELS/DESCRIPTION`。 -> **建档时同名会被拒(409)**:hub 不做静默认领,也不许第二把凭证顶掉第一台 Agent。 -> 要么用那一行现有的凭证,要么先删掉旧的登记行: -> -> ```bash -> curl -X DELETE http://127.0.0.1:8100/api/v1/agents/ -H "X-API-Key: $KEY" -> ``` +### DeepSeek Harness 插件(`plugins/dsh-agenthub`) -### 需要桥接进程时:贴一份 SDK(不再是一个产品) - -`deploy/nanobot-gateway/channel/agenthub/agenthub_client.py` 就是那个单文件客户端(只用标准库 + -websockets)。给"改不动、也拨不进"的 Agent 做桥时,import 它写十几行即可 —— 原来那个 -`agenthub-connector` 进程产品(CLI / Dockerfile / 四容器演示 / 部署产物生成器)已经删掉, -只把这份能力保留成 SDK,字段和别的接入件完全一致。 - -```python -from agenthub_client import GatewayClient, GatewayConfig - -client = GatewayClient( - GatewayConfig(hub_url="http://127.0.0.1:8100", name="bridge-agent", - agent_token="ag_xxxxxxxx"), # 控制台「接入」页签发的那一把 - on_task, -) -await client.run() # 断线重连 + 心跳 + 取消 -``` - -> **为什么内嵌是插件而不是 Agent 的一个 skill?** nanobot 的 skill(cron / github / memory / tmux) -> 是模型按需调用、跑完就退出的工具,而 Gateway 客户端必须常驻 + 断线自动重连 + 秒级心跳,生命周期对不上; -> nanobot 的常驻扩展点是 channel,所以内嵌接入就是一个 channel。别的 Agent 没有 channel 机制也没关系, -> 它们只需要 `agenthub_client.py` + 一个 `on_task` 回调。 -> -> **Agent 改不动、又拨不进去怎么办?** 用同一个客户端贴一份 SDK:拿 -> `agenthub_client.py` 起个小进程,或者干脆 import 进你自己的宿主进程。它不再是独立产品 -> (CLI / Dockerfile / 演示栈都删了),能力一点没少。 - -## 纳管 nanobot - -nanobot 自带 OpenAI 兼容服务(`nanobot serve`),但它比通用 OpenAI 服务器严格。AgentHub 的 -`nanobot` driver / provider 按真实实现对齐,并且有一组互测直接跑上游 `create_app()` -(`backend/tests/test_interop_nanobot.py`)来保证没有跑偏: - -| nanobot 的约定 | 真实行为 | AgentHub 的处理 | -| --- | --- | --- | -| 启动 | `nanobot serve --host 0.0.0.0 --port 8900`;绑定非本机地址时,`~/.nanobot/config.json` 里必须有 `{"api": {"api_key": "..."}}`,否则拒绝启动 | 接入时填 Bearer Key;`nanobot-docker` 产物按这个约定生成 | -| 健康 | `GET /health` → `{"status":"ok"}`,**不鉴权** | probe 与在线状态走它 | -| 模型 | `GET /v1/models` 只列出它自己配置的那一个;请求里的 `model` 不匹配就 400 | driver 先探测一次并缓存;探测不到就不传 `model` 字段。**hub 显示的模型一律由 Agent 自省上报**(心跳里的 `capabilities.model`),不在渠道配置里配 | -| 消息 | `messages` 只允许**一条 user 消息**,多条直接 400(它自己维护会话) | 协作指令和队友上下文折叠进同一条 user 消息,prompt 放最后 | -| 会话 | `session_id` 对应服务端会话 `api:` | 任务的 `session_key` 原样传下去,同一轮协作复用 nanobot 自己的记忆 | - -两条路指向同一个 nanobot,按「能不能改镜像 / 网络可不可达」二选一: - -```bash -# A. 外拨(推荐):装 agenthub 渠道,配置里只写 server + name + 凭证(见上一节) -# 容器现成栈:cd deploy/nanobot-gateway && ./bootstrap.sh - -# B. 直拨:hub 能访问到 nanobot serve 的端点 -curl -X POST http://127.0.0.1:8100/api/v1/agents -H "X-API-Key: $KEY" -H 'content-type: application/json' -d '{"name":"nanobot-1","driver":"nanobot","base_url":"http://127.0.0.1:8900/v1","auth":{"type":"bearer","token":""}}' -``` - -两种写法的 `base_url` 用 `http://host:8900` 或 `http://host:8900/v1` 都可以。接完验一下: - -```bash -curl -H "X-API-Key: $KEY" http://127.0.0.1:8100/api/v1/agents/nanobot-1 # status / live / capabilities.models -curl -X POST http://127.0.0.1:8100/api/v1/tasks -H "X-API-Key: $KEY" -H 'content-type: application/json' -d '{"agent_id":"nanobot-1","prompt":"只回一句话:你好","session_key":"demo-1"}' -``` - -容器里跑 nanobot:直接用现成栈(镜像 `nanobot:agenthub` 由 `deploy/Dockerfile.nanobot` 构建, -渠道已经软链进安装树)。 - -```bash -cd deploy/nanobot-gateway && ./bootstrap.sh # 两个容器、零桥接进程、零入站端口 -``` - -compose 里的 `AGENTHUB_SERVER`(旧名 `AGENTHUB_HUB_URL` 仍可读)取的是 hub 的对外地址: -容器内要能访问到它,host 网络下保留 `127.0.0.1` 即可,macOS / Windows 换成 -`http://host.docker.internal:8100`,或和 hub 共用一个 compose 网络后用服务名 `http://hub:8100`。 - -### 真实 nanobot 互测(可选) - -```bash -cp -R soucecode/nanobot /tmp/nanobot-build -uv venv .nanobot-venv -NANOBOT_SKIP_WEBUI_BUILD=1 uv pip install --python .nanobot-venv/bin/python "/tmp/nanobot-build[api]" -cd backend && .venv/bin/python -m pytest tests/test_interop_nanobot.py -q -``` - -它用真实 nanobot 包起一个临时 API 服务(只把 agent loop 换成假的,避免调用真大模型),跑完自动关。 -没有 nanobot 环境时整组自动 skip,不影响主测试套件;也可以 -`AGENTHUB_NANOBOT_PYTHON=/path/to/python` 指向任何能 `import nanobot` 的解释器。 - -## 顺着 WebUI 那条路接 nanobot(`nanobot_ws`) - -`nanobot gateway` 自带一条 WebSocket 渠道(默认 `127.0.0.1:8765`),而 **nanobot 官方 WebUI 只是它的一个 -客户端**:一条 socket 多会话,派活是一个 `{"type":"message","chat_id":…,"content":…}` 信封,回复按 -`delta` / `stream_end` / `reasoning_delta` / `message(kind=tool_hint)` / `file_edit` / `turn_end` -流回来(协议见 `soucecode/nanobot/docs/websocket.md`,帧形状见 `nanobot/webui/outbound_wire.py`)。 -`nanobot_ws` driver 复用的就是这条通道,没有第二套协议:hub 派活 = 发一个 `message`, -Agent 的推理与工具调用原样变成任务事件流。 - -```bash -# nanobot 侧不用改代码;要 token 就配 channels.websocket.token -nanobot gateway # ws://127.0.0.1:8765/ - -curl -X POST http://127.0.0.1:8100/api/v1/agents -H "X-API-Key: $KEY" -H 'content-type: application/json' \ - -d '{"name":"nano-ws","driver":"nanobot_ws","agent_type":"nanobot","connection_mode":"direct", - "base_url":"http://127.0.0.1:8765","auth":{"token":"wyc-secret"},"model":"qwen3.6-plus"}' -``` - -- `base_url` 写 `http://host:8900/v1`(nanobot serve 的写法)也认得,默认端口按 8765 推;路径不同给 - `config.path`,TLS / 反代给 `config.ws_url`(`wss://…`)。 -- **`session_key` 就是 nanobot 会话**:driver 把 hub 的 session_key 换成 `agenthub-` 形态的 - `chat_id`(非法字符或超长则取哈希),同一个 key 永远落进 nanobot 的同一个 session,所以「工作台」里 - 连续追问能续上上下文。 -- 轮次终点认 `turn_end`(带 usage / outcome),不是"一段时间没消息":多段回答、中间穿插工具调用都不会 - 提前收尾;`outcome=failed` 会让任务失败并把 `failure_message` 带回来。 -- nanobot 的渠道协议**没有中止信封**,所以这个 driver 的 `cancel()` 老实返回 false:控制台取消会让任务 - 停在 `cancelled`,但不会假装已打断 nanobot 那一轮(和 `nanobot` HTTP driver 一样)。 - -## Agent 类型与像素小人 - -Agent 行上有一个**类型**字段(`agent_type`),和 `driver`(怎么通信)、`deployment_kind`(跑在哪)是 -三个正交的维度。四个具名类型各自一套形象,办公室里的像素小人按它取配色和头饰: - -| 类型 | 值 | 形象 | 典型 driver | -| --- | --- | --- | --- | -| nanobot | `nanobot` | 金色工装 + 头顶天线 | `nanobot`(HTTP)、`nanobot_ws`(WebSocket) | -| DeepSeek Harness | `deepseek_harness` | 靛蓝工装 + 青色护目镜 | 内嵌插件(`connection_mode=embedded`) | -| OpenClaw | `openclaw` | 钢蓝工装 + 鸭舌帽 | `openclaw`(gateway 帧 RPC) | -| Hermes | `hermes` | 琥珀工装 + 羽翼头环 | 待接入(先占类型与形象) | -| 其它 | `custom` | 沿用按 driver 取色的老规则 | `mock` / `openai_compatible` / … | - -留空即"跟着 driver 走",换 driver 类型自动跟着变;显式选了某个类型就钉住不动。 -`GET /api/v1/agents?agent_type=hermes` 可按类型过滤。老库升级不用手工迁移: -启动/`agenthub init` 时会自动 `ALTER TABLE agents ADD COLUMN agent_type`(见 `db/init_db.py` 的增量列 -清单),老行按 driver 解析出类型。 - -## 接入 DeepSeek Harness(`plugins/dsh-agenthub`) - -DSH(`npx @deepseek-ai/dsh web`)是"一切皆插件"的 Agent Harness,所以接入方式是**给它写一个插件**, -而不是让 hub 去理解它内部:插件与 DSH 同进程,往 hub 拨一条出站 socket,说的还是那套 Frame 协议。 +DSH 是「一切皆插件」的 Harness,所以接入方式是给它写一个插件,而不是让 hub 去理解它内部: +插件与 DSH 同进程,往 hub 拨一条出站 socket。 ``` hub ◀── 出站 WS ── @nex/dsh-agenthub(DSH 插件,Host 半) @@ -312,109 +246,207 @@ hub ◀── 出站 WS ── @nex/dsh-agenthub(DSH 插件,Host 半) ``` ```bash -# 1) 装进 DSH profile(用 dsh 自己的命令;-w 因为 profile 目录是 pnpm workspace 根) -dsh plugin --profile web add -w link:/Users/jiliu/WorkSpace/nex_agenthub/plugins/dsh-agenthub - -# 2) 在 ~/.dsh/profiles/web/cordis.patch.yml 的顶层数组里 insert 一条(web profile 是 patchReload: live,存盘即生效): -# - insert: -# - id: dsh-agenthub -# name: '@nex/dsh-agenthub' -# config: { server: http://127.0.0.1:8100, name: dsh-web, agentToken: ag_xxxxxxxx } - -# 3) 插件自带离线自检(打桩 hub + 伪 Cordis ctx,不需要 DSH 运行时,也不需要真 hub) +# 装插件必须用 dsh 自己的命令(手改 profile 的 package.json 不算装) +dsh plugin --profile web add -w link:/绝对路径/nex_agenthub/plugins/dsh-agenthub +# 离线自检:打桩 hub + 伪 Cordis ctx,不需要 DSH 运行时,也不需要真 hub node plugins/dsh-agenthub/selfcheck.mjs ``` -插件注册出来的 Agent 是 `driver=deepseek_harness` + `connection_mode=embedded` + 类型 -**DeepSeek Harness**,在控制台里和别的 Agent 完全一样地派活、看流、取消。 -配置项、会话语义与排查表见 [`plugins/dsh-agenthub/README.md`](plugins/dsh-agenthub/README.md)。 +两个真机坑:profile 必须是 **web 模板**建的(默认只有 `dsh-base`,跑一条任务就退出,没有常驻进程去拨 hub); +`cordis.patch.yml` 里要**先删掉占位的 `[]`** 再接片段(两个根节点,YAML 直接解析失败)。 +web profile 是 `patchReload: live`,改 config 存盘即生效,**改插件代码要重启 `dsh web`**(Node ESM 缓存模块); +热重载会把同一 entry 应用两遍,插件内按进程做了单例。配置项与会话语义见 +[`plugins/dsh-agenthub/README.md`](plugins/dsh-agenthub/README.md)。 -三个实机结论,写在前面免得再踩: +### 无头 CLI:桥接(codex / claude / WorkBuddy) -- **投递要走 `ctx.sessionController`**(WebUI 同一条路),不能直接把文本塞给 `ctx.agents.create()` 出来的 - agent:后者没人装模型选择,`{{model}}` 变量在提示词装配阶段就会报错。组合里没有 - sessionController 时插件会退回 `agents.create/resume` 并自己补上装配监听。 -- **插件自己的 HTTP 接口别用 `connection.rpc.handle()`**(注册时它会去访问调用方 context 的 - `webServer`,dsh 0.1.5 里从 `ctx.inject(['connection','webServer'], …)` 的子 context 调用照样抛 - `cannot get property "webServer" without inject`)。走 `ctx.connection.fetch.register()` 在 - `/api` 下挂精确路由:既有 Host/Origin + 浏览器鉴权围栏,也不需要 webServer。 -- **改插件代码要重启 `dsh web`**:patch 文件增删条目是热生效的,但模块本身被 Node ESM 缓存住了。 -- **热重载会把同一个 entry 应用两遍**(见插件 README 的「热重载」一节):插件自己按进程做了单例, - 新实例上手先停掉上一份,旧实例不会再占着 hub 的 channel。 -- 本机现役实例(`~/.dsh/profiles/web`)已经按上面接好:hub 里是 `dsh-web`,`deepseek_harness` / - `embedded` / `online`,派活能跑完整一轮(status → reasoning → delta → completed)。 +不动 CLI 一行代码,在它所在机器上跑一个桥接进程(`bridge.py` 只需要 Python 3,不装任何依赖; +旁边 `adapters/` 里一个 CLI 一个适配器,新增一家就加一个文件)。 -## 目录结构 - -``` -backend/ FastAPI + SQLAlchemy(async) 控制面 + registry/gateway/tasks;CLI:agenthub -frontend/ Next.js 16 + React 19 + Tailwind 4 控制台(沿用 AgentTown 的像素 HUD) -deploy/ Dockerfile.backend / .console / .nanobot + docker-compose.yml - nanobot-gateway/ nanobot 接入样例(2 容器、零桥接进程、零入站端口) - cli-bridge/ 无头 CLI(codex / claude / WorkBuddy)的桥接进程 bridge.py -plugins/ 可选插件包(如 DeepSeek Harness 的 dsh 插件),不进后端构建 -data/ 运行数据:agenthub.db + hub-credentials.json(已 .gitignore,默认位置与启动目录无关) -docs/ PLAN.md(功能规划、API 契约、里程碑)+ AGENT_REGISTRATION.md(注册与身份规范) -soucecode/ 参考实现:nanobot、agent-town +```bash +agenthub agent add --name codex-1 --connection connector --driver connector --show-token +python3 deploy/cli-bridge/bridge.py --hub http://127.0.0.1:8100 --token ag_… \ + --name codex-1 --cli codex --workdir ~/code/目标仓库 --mode readonly ``` -## 控制台导航 +| 能力 | codex | claude | workbuddy | +| --- | --- | --- | --- | +| 派活 / 事件流 / 续话 / 取消 / describe | ✅ | ✅ | ✅ | +| `agent.command`(会话内下达指令) | ✅ `codex queue` | ❌ 明确回 `delivered:false` | ❌ 同左 | -顶栏右上角有 **暗 / 亮** 主题切换:默认暗色(AgentTown 的夜景像素 HUD),点一下换成白天的纸面 HUD。 -选择记在浏览器 `localStorage`,首帧由 `app/layout.tsx` 里的内联脚本按它写好 `data-theme`,所以刷新不会闪; -办公室画布的房间配色(墙、地板、窗外天色、机柜、看板纸面)跟着同一个开关走,见 `lib/office-palette.ts`。 +参数:`--hub --token --name --cli --workdir --mode --max-concurrency --verbose --state`, +分别可用 `AGENTHUB_URL`、`AGENTHUB_TOKEN`、`AGENTHUB_AGENT`、`AGENTHUB_CLI`、`AGENTHUB_WORKDIR`、 +`AGENTHUB_MODE`、`AGENTHUB_STATE` 兜底;state 默认 `~/.agenthub/cli-bridge-.json`。 +细节与两个真机坑(claude/workbuddy 的 `--add-dir` 是变长参数)见 +[`deploy/cli-bridge/README.md`](deploy/cli-bridge/README.md)。 + +派完活想回到那套 CLI 的原生会话里接着看: + +```bash +./scripts/attach.sh tsk_8b4337cc… # 本机直接进;跨机器自动走 ssh +./scripts/attach.sh -n tsk_xxx # 只打印命令不执行 +HUB_URL=http://10.0.0.5:8100 HUB_KEY=agp_xxx ./scripts/attach.sh tsk_xxx +``` + +会话记录存在 Agent 那台机器的磁盘上(`~/.codex/sessions/`、`~/.claude/projects//`…)且按工作目录归档,hub 只有事件流。 + +## 直拨(`direct`) + +hub 拨 Agent,Agent 零改动、零凭证。向导不提供这一类,手工登记: + +```bash +agenthub agent add --name nanobot-1 --driver nanobot --connection direct \ + --base-url http://127.0.0.1:8900/v1 # 需要鉴权就配 auth +agenthub agent add --name local-llm --driver openai_compatible --connection direct --base-url … +``` + +AgentHub 的 `nanobot` driver 按真实实现对齐,并且有一组互测直接跑上游 `create_app()` +(`backend/tests/test_interop_nanobot.py`)保证没有跑偏: + +| nanobot 的约定 | 真实行为 | AgentHub 的处理 | +| --- | --- | --- | +| 启动 | `nanobot serve --host 0.0.0.0 --port 8900`;绑定非本机地址时 `~/.nanobot/config.json` 必须有 `{"api":{"api_key":"…"}}`,否则拒绝启动 | 接入时填 Bearer Key | +| 健康 | `GET /health` → `{"status":"ok"}`,**不鉴权** | probe 与在线状态走它 | +| 模型 | `GET /v1/models` 只列它自己配的那一个;请求里的 `model` 不匹配就 400 | driver 先探测并缓存,探不到就不传 `model`;控制台显示的模型一律由 Agent 自省上报(心跳里的 `capabilities.model`) | +| 消息 | `messages` 只允许**一条 user 消息**,多条直接 400 | 协作指令和队友上下文折叠进同一条 user 消息,prompt 放最后 | +| 会话 | `session_id` 对应服务端会话 `api:` | 任务的 `session_key` 原样传下去,同一轮协作复用 nanobot 自己的记忆 | + +```bash +curl -X POST http://127.0.0.1:8100/api/v1/tasks -H "X-API-Key: $KEY" -H 'content-type: application/json' \ + -d '{"agent_id":"nanobot-1","prompt":"只回一句话:你好","session_key":"demo-1"}' +``` + +真实 nanobot 互测(可选;没有 nanobot 环境时整组自动 skip,也可用 `AGENTHUB_NANOBOT_PYTHON=/path/to/python` +指向任何能 `import nanobot` 的解释器):自备一份 nanobot 源码 → +`NANOBOT_SKIP_WEBUI_BUILD=1 uv pip install --python .nanobot-venv/bin/python "/tmp/nanobot-build[api]"` +→ `cd backend && .venv/bin/python -m pytest tests/test_interop_nanobot.py -q`。 + +### `nanobot_ws`:走 WebUI 那条 WebSocket + +`nanobot gateway` 自带一条 WebSocket 渠道(默认 `127.0.0.1:8765`),**官方 WebUI 只是它的一个客户端**: +一条 socket 多会话,派活是一个 `{"type":"message","chat_id":…,"content":…}` 信封,回复按 +`delta` / `stream_end` / `reasoning_delta` / `message(kind=tool_hint)` / `file_edit` / `turn_end` 流回来。 +`nanobot_ws` driver 复用的就是这条通道,没有第二套协议。 + +```bash +nanobot gateway # ws://127.0.0.1:8765/ ;要 token 就配 channels.websocket.token + +curl -X POST http://127.0.0.1:8100/api/v1/agents -H "X-API-Key: $KEY" -H 'content-type: application/json' \ + -d '{"name":"nano-ws","driver":"nanobot_ws","agent_type":"nanobot","connection_mode":"direct", + "base_url":"http://127.0.0.1:8765","auth":{"token":"wyc-secret"}}' +``` + +- `base_url` 写成 `http://host:8900/v1` 也认得,默认端口按 8765 推;路径不同给 `config.path`,TLS/反代给 `config.ws_url`。 +- **`session_key` 就是 nanobot 会话**:driver 把它换成 `agenthub-` 形态的 `chat_id`(非法字符或超长取哈希), + 同一个 key 永远落进同一个 session,「工作台」里连续追问能续上上下文。 +- 轮次终点认 `turn_end`(带 usage / outcome),不是「一段时间没消息」;`outcome=failed` 让任务失败并带回 `failure_message`。 +- nanobot 的渠道协议**没有中止信封**,所以 `nanobot`(HTTP)和 `nanobot_ws` 的 `cancel()` 老实返回 false: + 控制台取消会把任务停在 `cancelled`,但不会假装已打断 Agent 那一轮。外拨接入件才有真取消。 + +## Agent 类型与像素小人 + +`agent_type` 和 `driver`(怎么通信)、`deployment_kind`(跑在哪)是三个正交维度。办公室里的像素小人按它取配色和头饰: + +| 类型 | 值 | 形象 | 典型 driver | +| --- | --- | --- | --- | +| nanobot | `nanobot` | 金色工装 + 头顶天线 | `nanobot`(HTTP)、`nanobot_ws`(WebSocket) | +| DeepSeek Harness | `deepseek_harness` | 靛蓝工装 + 青色护目镜 | DSH 插件(`connection_mode=embedded`) | +| OpenClaw | `openclaw` | 钢蓝工装 + 鸭舌帽 | `openclaw`(gateway 帧 RPC,实验) | +| Hermes | `hermes` | 琥珀工装 + 羽翼头环 | 待接入(先占类型与形象) | +| 其它 | `custom` | 沿用按 driver 取色的老规则 | `mock` / `openai_compatible` / `connector` | + +留空=跟随 driver,换 driver 类型自动跟着变;显式选了钉住不动。`GET /api/v1/agents?agent_type=hermes` 按类型过滤。 +老库升级不用手工迁移:启动/`agenthub init` 时自动增量 `ALTER TABLE`。 + +## 控制台 + +`Next 16.1.6 / React 19.2.3 / Tailwind 4` + lucide-react + @tanstack/react-virtual(全在 devDependencies)。 +脚本:`dev`(`next dev -p 3100`)/ `build` / `start` / `lint` / `typecheck` / `format` / `format:check`。 | 页面 | 用途 | | --- | --- | | 总览 | Agent/任务状态分布、最近 Run、Presence 判定来源、最后一帧 | -| 办公室 | 像素办公室(参照 Star-Office-UI):每个 Agent 一个工位,屏幕写正在跑的 prompt、人偶走位对应状态,墙上只有一块看板——左栏在岗状态、右栏任务队列(待办/在途/完成),右侧机柜有告警时闪红灯;**产出只出现在右边控制台,画面里不重复**;点工位选中后可直接下指令。画布按「显示宽度 × devicePixelRatio」渲染(拉宽/换 2x 屏都不糊),工位像素块边长由 `lib/office-layout.ts` 算出 | -| 工作台 | 通用派活面板:左边是全部 Agent(本地/容器/远端一视同仁),右边是一条按 `session_key` 延续的对话——同一条 SSE 事件流,reasoning / 工具调用 / 产出都在里面,正在跑的还能取消 | -| Agents | 注册表**只管管理**:列表筛选、逐行删除(注销登记)、派活、探活、凭证查看与轮换、详情。**没有登记入口** —— 建档与签发都在「接入」页 | -| 任务 | 单 Agent 任务列表与流式事件(delta / reasoning / tool / log) | -| 团队 | 成员与角色、Playbook、Run 时间线、共享黑板、Agent 间消息 | -| 接入 | 顶部是在线通道数与 hub 地址(Agent 侧那一格 `server` 就抄它);**三步向导**:**① 选类型**(插件 / 渠道 · 桥接)→ **② 选是哪套 Agent**(渠道:DeepSeek Harness、nanobot、OpenClaw;桥接:codex / claude / WorkBuddy)→ **③ 生成凭证**(建档 + 当场签发 `ag_…`,片段里的凭证已是真值,贴过去之后这一行跟着 presence 变绿;签过的凭证点「查看凭证」随时读回,不必轮换) | -| 设置 | Hub 与 Gateway 状态、控制台面 API 密钥管理、帧窗口、审计日志 | +| 办公室 | 像素办公室:一 Agent 一工位,屏幕写正在跑的 prompt,走位对应状态,墙上一块看板(左在岗状态、右任务队列),机柜告警闪红灯。**产出只在右边控制台,画面里不重复**;点工位可直接下指令。画布按「显示宽度 × devicePixelRatio」渲染,布局 `lib/office-layout.ts`、配色 `lib/office-palette.ts` | +| 工作台 | 通用派活面板:左边全部 Agent(本地/容器/远端一视同仁),右边一条按 `session_key` 延续的对话,reasoning / 工具调用 / 产出同一条 SSE,在跑的能取消 | +| Agents | 只管管理:搜索 `name/driver/host`、按状态与接入方式筛选、主动探测、删除登记、逐行详情。**没有登记入口**——建档与签发都在「接入」页 | +| Agent 详情 | 凭证(查看 / 签发 / 轮换 + 宽限秒数)、指令 command、probe、describe、这个 Agent 的任务列表 | +| 任务 | 单 Agent 任务列表与流式事件(`delta / reasoning / tool / log`) | +| 团队 | 成员与角色、Playbook、Run 时间线、共享黑板、Agent 间消息;`/runs/{id}` 是 Run 详情 | +| 接入 | 顶部一行 `Hub 地址` + COPY;三步向导;下面「签发记录」 | +| 设置 | Hub、Gateway、API 密钥(控制台面)+吊销、Gateway 帧窗口、审计日志、最近帧原始 JSON | -### 控件与提示:一套规格 +暗 / 亮主题在右上角(默认暗色),记在 `localStorage`,首帧由 `app/layout.tsx` 内联脚本写好 `data-theme`,刷新不闪。 -- **尺寸只有两档**:`md` = 32px(页面/卡片的主操作、表单行),`sm` = 26px(工具条、表格行内动作、chip)。 - 边框统一 2px、圆角 6px、字体 ArkPixel(11px / 10px)、焦点环统一 2px 金色;token 在 - `frontend/app/globals.css` 的 `--ctl-*`,所以同一行里的按钮、输入框、下拉、chip 永远一样高。 -- **页面只用原语**:`PixelButton / LinkButton / Input / Select / Textarea / SearchInput / Chip / Tabs / - Field / Modal / Badge / Empty / ErrorNote / Spinner / KV / JsonBlock / CopyButton`(都在 - `frontend/components/ui.tsx`)。页面里不再出现 `className="pixel-input"` 这类裸类名,也没有裸 `