# Agent 接入规范(v2) 这份文档是**接一个 Agent 上 hub** 的唯一规范:nanobot、DeepSeek Harness(dsh)、OpenClaw、 OpenAI 兼容服务、自研框架都按它来。它描述的是**当前代码的真实行为**,不是提案 —— 每条都能在仓库里找到对应实现,改行为时同步改这里。 先读第 0 节,能覆盖 90% 的接入;排障直接跳第 9 节。 | 层 | 代码位置 | | --- | --- | | hub 协议与登记 | `backend/agenthub/api/routes_gateway.py`、`api/routes_agents.py`、`services/registry.py` | | 帧格式 / 驱动契约 | `backend/agenthub/gateway/frames.py`、`backend/agenthub/adapters/base.py` | | 外拨通道(hub 侧驱动) | `backend/agenthub/adapters/connector.py` | | 接入片段生成 | `backend/agenthub/deploy/snippets.py`(CLI `agenthub config`、`GET /deploy/templates`) | | nanobot 接入件(渠道) | `deploy/nanobot-gateway/channel/agenthub/` | | dsh 接入件(插件) | `plugins/dsh-agenthub/` | | 单文件 Python SDK | `deploy/nanobot-gateway/channel/agenthub/agenthub_client.py` | --- ## 0. 一页速查 ### 0.1 三种接入形态 | 形态 | 谁发起连接 | Agent 侧要什么 | hub 侧要什么 | 典型场景 | | --- | --- | --- | --- | --- | | **外拨** `embedded` | Agent 进程内的接入件外拨 WS | 连接配置 + 身份 | 无 | nanobot 内嵌渠道、dsh 插件(推荐) | | **外拨** `connector`(**桥接**) | Agent 同机/旁边的桥接进程外拨 WS | 同上(写在那个进程里) | 无 | 无头 CLI:`deploy/cli-bridge/bridge.py`(codex / claude / WorkBuddy);改不动也拨不进的 Agent 贴一份 SDK | | **直连** `direct` | hub 拨 Agent 的 HTTP/WS | **无 AgentHub 配置** | `base_url` + `auth` | nanobot `serve`、OpenAI 兼容服务。**「接入」向导不提供这一类**,只能手工登记 | 外拨两种形态在 hub 侧是同一个驱动(`connector`):hub 从不需要能"拨到" Agent,所以笔记本、 无 ingress 的容器、跳板机后的云主机都能接。 ### 0.2 一条凭证路径 外拨形态只有一种接法,五套 Agent 一字不差: 1. **hub 签发凭证**:控制台「接入」页点一下,或 `agenthub agent add --show-token`,拿到 属于这台 Agent 的 `ag_…`; 2. **Agent 侧填两样**:hub 的 IP+端口(`server`)+ 这个凭证,别的一律不填; 3. **注册验证 = 它上线**:Agent 外拨 `WS /api/v1/gateway/ws?agent_token=ag_…`,hub 从凭证 反查出它是谁,并在 `hub.hello` 里把 `agent_id` 告诉它 —— 所以连 agent id 都不用抄。 **没有** enrollment 入场令牌,**没有** Hub ID,**没有**预注册/自注册之分。凭证就是身份: 建档案 → 签凭证 → 填凭证 → 上线,每一步都只有这一条路。 直连(`direct`)没有 AgentHub 凭证 —— 不是 Agent 拨 hub,是 hub 拨它,用登记表里的 `base_url` + `auth`(那台服务自己的 key,跟 `ag_…` 无关)。它是 hub 侧的一种驱动能力, **不在「接入」向导里**:向导只给两类接入(插件 / 渠道、桥接),这一类要用 `agenthub agent add --connection direct` 手工登记。 ### 0.3 每个类型的最小接入 ```bash # A. 桥接(codex / claude / WorkBuddy 这类无头 CLI):在装有该 CLI 的机器上跑一个桥接进程 python3 deploy/cli-bridge/bridge.py --hub http://127.0.0.1:8100 \ --token ag_… --name workbuddy --cli workbuddy --workdir ~/code/目标仓库 --mode write # B. nanobot:贴进 ~/.nanobot/config.json 的 channels.agenthub,重启 nanobot # {"enabled": true, "server": "http://127.0.0.1:8100", "name": "alpha", "agent_token": "ag_…"} # C. dsh:贴进 ~/.dsh/profiles//cordis.patch.yml 的插件 config,起 dsh # - insert: # - id: dsh-agenthub # name: '@nex/dsh-agenthub' # config: { server: http://127.0.0.1:8100, name: dsh-web, agentToken: ag_… } # D. 自研 Agent:一个进程贴一份单文件 SDK(6.7),同样只有 hub_url + agent_token 两样 # E. 直连(自带 HTTP/WS 服务的 Agent,向导外手工登记):Agent 侧一行都不配 agenthub agent add --name ow-1 --driver openclaw --connection direct --base-url ws://127.0.0.1:18789 # 生成片段:agenthub config --name alpha --kind bridge|nanobot|dsh|claw # 已建档的 Agent 直接印出真凭证(第 0.2 步签的那把,见第 7 节);没建档的留 占位 # 控制台等价入口:接入 → ① 选是哪套 Agent → ② 签发凭证、贴过去、看它 online ``` `ah_…` 是控制台的 API Key,**不是** Agent 凭证:填进 `agentToken` / `--token` 会被明确拒绝, 不是默默失败。 --- ## 1. 概念模型 ### 1.1 五个正交维度 | 维度 | 取值 | 回答的问题 | 谁决定 | | --- | --- | --- | --- | | `driver` | `connector` / `nanobot` / `nanobot_ws` / `openai_compatible` / `openclaw` / `mock` / 第三方 entry-point | hub 用什么协议跟它说话 | hub(控制台可改;未知框架可注册) | | `agent_type` | `nanobot` / `deepseek_harness` / `openclaw` / `hermes` / `custom` | 这一行是哪个产品(决定像素小人形象与徽章) | hub 侧登记,留空 = 跟 driver 走 | | `connection_mode` | `embedded` / `connector` / `direct` | 谁发起连接 | Agent 自报(外拨)/ hub 登记(直连) | | `deployment_kind` | `local` / `docker` / `cloud` | 它跑在哪 | Agent 自报,或 hub 侧登记 | | `source` | `manual` | 这行是怎么来的(只剩「hub 侧建档」这一种来源) | hub | 四者互不影响:同一个 nanobot 既能 `direct`(hub 拨它的 serve 端点)也能 `embedded`(进程内渠道); 同一个 `connector` 驱动既服务 embedded 也服务外挂接入件。 ### 1.2 三层划分 ``` 连接层(都必须):server 地址 + connection_mode 身份层(只有外拨要):agent_token 一把凭证(agent_id 由 hub 在 hello 里回给你) 元数据层(hub 侧登记 / Agent 自省上报): name、display_name、description、emoji、agent_type、 role、labels、deployment_kind/ref、max_concurrency、 capabilities(自省)、model(**只**来自自省) ``` ### 1.3 字段归属(谁拥有什么) - **Agent 自己的**:模型(nanobot 的 `agents.defaults.model`、dsh 的默认模型设置)、provider 配置、 工作目录、超时、渠道/插件的行为开关(`streaming` / `sendProgress` / `sendToolHints` / `allowFrom`)。 hub 只显示 Agent 在心跳里**自省上报**的模型,不替它决定。 - **hub 侧的**:`role`(团队角色,playbook 选人用)、`labels`、`agent_type`、`deployment_kind` 兜底、 `max_concurrency` 上限、凭证哈希、`source`。 - **两边都不该有的**:Agent 侧身份文件(见 3.5 R3)、`model` 的注册副本、`role` 的渠道副本。 --- ## 2. 接入形态 ### 2.1 外拨(embedded / connector) 接入件拨一条出站 WebSocket 到 `ws:///api/v1/gateway/ws?agent_token=ag_…`,之后 hub 通过这条 连接下发任务、接入件把事件推回来。两种子形态的差别只在**接入件住在哪**: - `embedded`:接入件跑在 Agent 进程里(nanobot 渠道、dsh 插件)。推荐形态,没有第二个进程要管。 - `connector`:接入件是旁边一个进程(或同机另一个容器),用仓库里的单文件 SDK 起。 Agent 改不动、或宿主语言没有好用的插件机制时用。 hub 侧两者都走 `connector` 驱动(`driver_for()` 按 `connection_mode` 选驱动,所以外拨 Agent 的 `driver` 字段只说明"它本来是什么框架",派活实际走 socket)。 ### 2.2 直连(direct) hub 主动拨 `base_url`,用 `auth` 里的凭证(这一类不在「接入」向导里,只能手工登记)。存在性判定顺序是 **外拨 socket 在线 > 心跳新鲜度 > 主动探测(probe)**,控制台显示"判定来源"同此。 ### 2.3 怎么选 ``` 它是无头 CLI(codex / claude / WorkBuddy…)吗? └─ 是 → 桥接(connector):在它所在机器上跑 deploy/cli-bridge/bridge.py,不用改它一行代码 能改 Agent 代码或配置吗? ├─ 能 → 它是 nanobot / dsh 吗? │ ├─ 是 → embedded(用现成接入件,照第 6 节抄配置) │ └─ 否 → 自己写接入件(6.7 / 6.8),仍然 embedded 或 connector └─ 不能 → 它自己有可被访问的 HTTP/WS 服务吗? ├─ 有 → direct(hub 侧登记 base_url + auth) └─ 没有 → 贴一份单文件 SDK 起一个桥接进程(6.7) ``` --- ## 3. 身份与凭证 ### 3.1 一条路:建档 → 签发 → 填凭证 ```bash agenthub agent add --name alpha --driver nanobot --connection embedded --show-token agenthub agent rotate alpha # 轮换(旧凭证默认立即失效) ``` 控制台「接入」页点「签发凭证」就是下面这两个调用:`POST /api/v1/agents`(body 带 `"issue_credential": true`,明文在这一次响应里回来)与 `POST /api/v1/agents/{ref}/credentials` (轮换,可带 `grace_seconds` 开滚动升级的双活窗口)。另一处等价入口:Agents 列表 → 该行「编辑」→ 凭证卡片「签发/轮换」。 Agent 侧要抄的只有 `server` + 这一把凭证。`agentId` 可以填(有些接入件想在 hello 之前 就先知道自己是哪一行),但它只是提示:权威身份始终由 hub 从凭证反查,并在 `hub.hello` 里给出。 ### 3.2 凭证什么时候被校验 没有独立的「注册」或「验证」接口,也不需要: | 时机 | 调用 | 结果 | | --- | --- | --- | | 接入件启动时先探一次 | `POST /api/v1/gateway/heartbeat`(`Bearer ag_…`) | 200 = 凭证有效,去拨 WS;401/403 = 日志里直接说去哪把新的 | | 建立控制通道 | `WS /gateway/ws?agent_token=ag_…` | 凭证不对 `4401` 关闭;对了就标 online 并回 `hub.hello`(带 `agent_id`) | | 之后每次心跳 | `agent.heartbeat` 帧或 HTTP 心跳 | 顺带刷新自省字段(`model` / `capabilities` / `active_tasks`) | **验证 = 控制台上看到它 online**。控制台「接入」页第 ② 步那张卡片读的就是 `GET /api/v1/agents/{ref}/presence`,它和 Agents 页同源,不会出现"这边绿那边灰"。 ### 3.3 签发、轮换与可见性 - 明文(`ag_…`)只在签发/轮换响应里出现**一次**;库里只存 `sha256` 哈希 + `token_preview` (形如 `ag_qEv…W2Kd`)。控制台任何位置都不回显明文。 - Agent 列表/详情里的 `credential` 形状:`{ "installed": true, "preview": "ag_…" }`。 - 轮换默认让旧凭证**立即失效**;`grace_seconds > 0` 开一个双活窗口(新进程先起来、旧进程 还没走时用),到点自动作废。 - 换 hub = 换凭证:新 hub 上是新档案、新凭证,没有跨 hub 通用的身份。 ### 3.4 同名语义(单实例) - `name` 是 hub 上的唯一键,也是运维唯一需要记的标识;`agent_id` 由 hub 生成、跨重启稳定。 - 建档时同名 → **409**:先想清楚是复用那一行(直接拿它的凭证)还是换名字。不静默认领, 也不接管 —— 「谁把谁的档案覆盖了」这类事故全部来自那种聪明行为。 - 拿着某把凭证连上来 = 你就是那一行(凭证即身份),所以不存在"用新 token 顶掉别人的身份"。 - **不支持同名多实例**:滚动升级先下线旧实例,或给新实例换 `name`。 ### 3.5 无状态身份的四条硬性要求 接入件**不在磁盘保存任何身份**(没有 `statePath` / `--state-file` / 身份 json)。凭证只来自配置, 运行时只放内存。因此四条硬性要求,所有接入件都必须满足: - **R1 网络不可达 ≠ 凭证失效**:只有 `401/403/409` 才允许丢弃 token; 连接失败、超时、`5xx` 必须退避重试。 - **R2 启动阶段的探活必须进重试循环**:hub 没起来不能把接入件打死,hub 恢复后自动上线。 - **R3 凭证只进内存**:不落盘、不进日志。 - **R4 配置里的凭证是权威**:配置里的 `agent_token` 优先于任何缓存/遗留文件。 历史遗留身份文件(`~/.nanobot/agenthub-state.json`、`~/.agenthub/agent-.json`、 `--state-file` 指向的文件)**只读兜底一次**:读到就用它上线(升级期内不让人掉线),同时打印 可粘贴进配置的片段提示迁移,之后不再写入。配置里**已经写了**凭证时完全不读它 —— 老文件里 上一世的 `agent_id` 拼到新凭证上会 401(真机撞过)。 ### 3.6 安全边界 - `agent_token` 按密钥对待:配置文件权限 `0600`;容器里走 env / secret,不进镜像层、不进日志。 - 一把凭证 = 一台 Agent:它能领这台 Agent 的活、上报它的状态;读不了别的 Agent, 也碰不到控制台面。 - 泄漏处置:`agenthub agent rotate `(或控制台轮换)。旧凭证立刻失效,接入件会在日志里 说清去哪把新的,不需要重启 hub。 - 控制台 API Key(`ah_…`,管控制台与管理 API)与 Agent 凭证(`ag_…`,只管这一台 Agent)是两套 边界;填错位置会被明确拒绝,不会静默按另一套解释。 --- ## 4. 字段规范 ### 4.1 统一字段表 规范名(JSON 用 snake_case;dsh 插件 config 用 camelCase,语义一一对应;nanobot 两种都读): | 概念 | 规范名 | 环境变量 | 必需 | 说明 | | --- | --- | --- | --- | --- | | 服务端地址 | `server` | `AGENTHUB_SERVER` | 是(外拨) | 含协议与端口,如 `http://127.0.0.1:8100` | | 运行凭证 | `agent_token` | `AGENTHUB_AGENT_TOKEN` | 是(外拨) | `ag_…`,控制台「接入」页签发;明文可反复回看(`GET /agents/{ref}/credentials`,认证走的仍是哈希) | | Hub 上的名字 | `name` | `AGENTHUB_NAME` | 是 | 唯一键;同名 = 同一个 Agent | | Agent 身份 | `agent_id` | `AGENTHUB_AGENT_ID` | 否 | `agt_…`;hub 从凭证反查,hello 里回给你 | | 显示名 | `display_name` | `AGENTHUB_DISPLAY_NAME` | 否 | 缺省 = `name` | | 描述 | `description` | `AGENTHUB_DESCRIPTION` | 否 | 控制台展示 | | 图标 | `emoji` | — | 否 | 控制台展示,各家有默认值 | | 连接模式 | `connection_mode` | — | 否 | 接入件自己定:nanobot `embedded`、dsh `embedded`、SDK 默认 `embedded` | | 部署形态 | `deployment_kind` | `AGENTHUB_DEPLOYMENT_KIND` | 否 | `local` / `docker` / `cloud` | | 部署引用 | `deployment_ref` | `AGENTHUB_DEPLOYMENT_REF` | 否 | 容器名 / 主机名 / 云实例 | | 标签 | `labels` | `AGENTHUB_LABELS`(`k=v,k=v`,nanobot) | 否 | | | 并发上限 | `max_concurrency` | — | 否 | nanobot 键名 `maxConcurrency`,缺省 2 | | 协议版本 | `protocol_version` | — | 自动 | 当前 1 | | 接入件版本 | `connector_version` | — | 自动 | 排障用 | 桥接进程 `bridge.py` 没有配置文件,同名概念走命令行参数(env 是另一套名字,别混): `--hub`(`AGENTHUB_URL`)、`--token`(`AGENTHUB_TOKEN`)、`--name`(`AGENTHUB_AGENT`)、 `--cli`、`--workdir`、`--mode`。 ### 4.2 兼容读(一个版本窗口) | 旧名 | 新名 | 处理 | | --- | --- | --- | | `hubUrl` / `hub_url` / `AGENTHUB_HUB_URL` | `server` / `AGENTHUB_SERVER` | 兼容读 | | `AGENTHUB_AGENT_NAME` | `AGENTHUB_NAME` | 兼容读 | | `statePath` / `--state-file` | — | 只读兜底一次,不再写入(3.5) | | config 里的 `enrollment` / `hubId` / `takeOver` | — | **不再读**,读到就在日志里说一声让你删掉这行 | 线上协议字段不改名:配置键改了名也不需要两端同时动。 ### 4.3 不该出现在接入配置里的字段 | 字段 | 为什么 | 放哪 | | --- | --- | --- | | `model` | 渠道里那份只是注册时的自报副本,会跟真正跑的模型漂移 | Agent 自己的模型配置;hub 只显示心跳里自省上报的值 | | `role` | 它是 hub 的协作概念(团队角色 / playbook 选人) | hub 侧登记那一行(建档时或之后改) | | `statePath` / 身份文件 | 身份即配置(3.5 R3) | 删除 | 行为开关不属于注册规范,各接入件自己留着:`allowFrom`、`streaming`、`sendProgress`、 `sendToolHints`、`cwd`、`timeoutS`。 --- ## 5. 协议契约(Gateway) ### 5.1 Frame 格式 所有面共用一个小信封: ```jsonc { "v": 1, "id": "frm_…", // 帧 id;应答把它填进 reply_to "ts": 1790000000.0, "type": "req|res|event|err", "kind": "task.run", // 处理器 switch 用这个 "topic": "agent..task..event", // 总线路由用这个(支持 *.> 通配) "actor": "hub|agent|", "payload": { }, "reply_to": "frm_…", // 可选 "agent_id": "agt_…", // 可选 "task_id": "tsk_…", // 可选 "run_id": "run_…", // 可选 "seq": 42 // 可选,总线序号(重连补发用) } ``` ### 5.2 上行(Agent → hub) | 动作 | 端点 / kind | 说明 | | --- | --- | --- | | 心跳 | `POST /api/v1/gateway/heartbeat`(`Bearer ag_…`) | `{status, active_tasks, health, capabilities, connector_version}` | | 注销 | `POST /api/v1/gateway/deregister`(`Bearer ag_…`) | 置 offline 并断开控制通道 | | 连控制通道 | `WS /api/v1/gateway/ws?agent_token=ag_…` | 连上后 hub 先发 `hub.hello` | | 上线问好 | `agent.hello` | 可带 `capabilities`(会写入);`client_version` → `connector_version` | | 在线心跳 | `agent.heartbeat` | 与 HTTP 心跳同义,省一次请求 | | 任务事件 | `agent.event`(带 `task_id`) | `payload.type` ∈ `status`/`delta`/`reasoning`/`tool`/`log`/`completed`/`failed`/`cancelled` | | 应答 | `type: "res"` + `reply_to` | 对 `task.run` / `task.cancel` / `agent.ping` / `agent.describe` / `agent.command` 的应答 | | 下线 | `agent.deregister` | 主动断开并置 offline | 连上控制通道后 hub 先发的 `hub.hello`(Agent 由此知道自己是哪一行): ```jsonc { "agent_id": "agt_…", "agent_name": "alpha", "hub_url": "http://127.0.0.1:8100", "ws_url": "ws://127.0.0.1:8100/api/v1/gateway/ws", "heartbeat_interval_s": 15, "protocol_version": 1, "frame_kinds": ["task.run", "task.cancel", "agent.ping", "agent.describe", "agent.command"] } ``` Agent 侧不上报注册字段:`name` / `driver` / `connection_mode` / `deployment_*` 都在 hub 建档时 就定好了(改这些用控制台/API 改那一行)。心跳里能带的是**自省**: ```jsonc { "status": "online", "active_tasks": 1, "connector_version": "0.1.0", "health": { "host": "mb-jiliu" }, "capabilities": { "streaming": true, "runtime": "nanobot", "model": "qwen3.6-plus" } } ``` `role` 归 hub、`model` 只来自这里的自省 —— 两处都不接受配置副本。 `role` 与 `model` **不接受**出现在注册请求里(role 归 hub、model 归自省)。 ### 5.3 下行(hub → Agent) | kind | payload | 应答 | | --- | --- | --- | | `task.run` | `{task_id, prompt, session_key, invocation_id, timeout_s, context, provider, provider_config}` | `res.payload.{text, usage}`;过程中用 `agent.event` 流式上报 | | `task.cancel` | `{invocation_id}` | `res`(收到即算成功) | | `agent.ping` | `{}` | `res.payload.{rtt_ms, …}` | | `agent.describe` | `{}` | `res.payload`:能力/模型/工具等自省信息 | | `agent.command` | `{command, args?}` | `res.payload`(接入件自定义解释) | `agent.event` 的 `payload` 示例: ```jsonc {"type": "delta", "text": "正在回答…"} {"type": "reasoning", "text": "先看约束…"} {"type": "tool", "name": "read_file", "input": {"path": "README.md"}} {"type": "status", "message": "thinking"} {"type": "completed", "text": "最终答案", "usage": {"input_tokens": 120}} {"type": "failed", "error": "provider 401"} ``` ### 5.4 控制台面(了解用) - `WS /api/v1/stream?api_key=ah_…&topics=…&since=`:控制台订阅全部事件;`since` 用于重连补发 (先订阅再取快照,不重不漏);`{"action":"ping"}` → `pong`。 - `GET /api/v1/gateway/status`:在线通道、pending 请求、接入件版本。 - `GET /api/v1/gateway/frames?limit=&kind=&agent_id=`:环形缓冲里的最近帧(审计/排障)。 ### 5.5 鉴权 | 面 | 凭证 | 传递方式 | | --- | --- | --- | | 控制台 REST | `ah_…`(安装级 API Key) | `X-API-Key:` 或 `Authorization: Bearer` | | 控制台 WS | `ah_…` | `?api_key=` | | Agent REST(心跳/注销) | `ag_…` | `X-Agent-Token:` 或 `Authorization: Bearer` | | Agent WS | `ag_…` | `?agent_token=`(浏览器塞不了 header,所以走 query) | | 协作接口(blackboard/messages) | run grant(HMAC,绑定 run_id + agent_id) | `Authorization: Bearer` | ### 5.6 心跳、重连与存在性 - 心跳间隔 `heartbeat_interval_s`(默认 15s),超时 `heartbeat_timeout_s`(默认 45s)。 - 判定顺序:外拨 socket 在线 > 心跳新鲜度 > 主动探测。 - 控制通道断开 → hub 立刻把该 Agent 标 offline(`connector_socket_closed`),接入件按 R1/R2 退避重连。 --- ## 6. 各类型接入规范 ### 6.1 nanobot(内嵌渠道 `embedded`) 接入件:`deploy/nanobot-gateway/channel/agenthub/`(随 nanobot 装)。配置写在 `~/.nanobot/config.json` 的 `channels.agenthub`: ```jsonc { "agents": { "defaults": { "provider": "dashscope", "model": "qwen3.6-plus" } }, // 模型归这里 "channels": { "agenthub": { "enabled": true, "server": "http://127.0.0.1:8100", "name": "alpha", "display_name": "阿尔法", "agent_token": "ag_…", // 只有这一格是凭证:控制台「接入」页签发 "allowFrom": ["agenthub"], "maxConcurrency": 2, "streaming": true, "sendProgress": true, "sendToolHints": true } } } ``` - 环境变量:`AGENTHUB_SERVER` / `AGENTHUB_NAME` / `AGENTHUB_DISPLAY_NAME` / `AGENTHUB_DESCRIPTION` / `AGENTHUB_AGENT_TOKEN` / `AGENTHUB_AGENT_ID` / `AGENTHUB_DEPLOYMENT_KIND` / `AGENTHUB_DEPLOYMENT_REF` / `AGENTHUB_LABELS`(`k=v,k=v`)。**凭证类**以环境变量优先 (compose 注入的 token 要能盖住 config.json 里的陈旧副本),其余以配置文件为准。 - 自省上报:`{streaming, model, runtime: "nanobot"}`,`model` 读 nanobot 自己的模型配置。 - 不写身份文件;旧的 `~/.nanobot/agenthub-state.json` 只读兜底一次(3.5)。 ### 6.2 nanobot_ws(直连 nanobot 网关自带的 WS 渠道) `driver: "nanobot_ws"` + `connection_mode: "direct"`:hub 说 nanobot 网关自带 WebSocket 渠道的协议 (`ready` → `message{chat_id,content}` → `delta` / `reasoning_delta` / `tool_hint` / `stream_end` / `turn_end`),hub 的 `session_key` 映射成稳定的 nanobot `chat_id`。好处是同一个网关既能被官方 WebUI 用,也能被 hub 派活。 ```bash agenthub agent add --name desk --driver nanobot_ws --connection direct --base-url ws://127.0.0.1:8788 ``` ### 6.3 DeepSeek Harness(dsh 插件 `embedded`) 接入件:`plugins/dsh-agenthub/`。配置写在 profile 的 `cordis.patch.yml`: ```yaml - insert: - id: dsh-agenthub name: '@nex/dsh-agenthub' config: server: http://127.0.0.1:8100 name: dsh-web displayName: DeepSeek Harness agentToken: ag_… # 只有这一格是凭证:控制台「接入」页签发 deploymentKind: local # 行为开关(可选):cwd / timeoutS / maxConcurrency / autoConnect ``` - camelCase 键:`server` / `name` / `displayName` / `agentToken` / `agentId`(可选)/ `deploymentKind` / `deploymentRef` / `emoji` / `cwd` / `timeoutS` / `maxConcurrency`; env 是同一批概念(`AGENTHUB_SERVER` / `AGENTHUB_NAME` / `AGENTHUB_AGENT_TOKEN` / …)。 - 老配置里若还写着 `enrollment` / `hubId` / `takeOver`,插件日志会明确报一行让你删掉, 不会默默忽略。 - 也可以在 dsh 的「设置 → AgentHub」面板填「地址 + 这台 Agent 的凭证」点**上线**。面板只把 地址和名字落到 `~/.dsh/agenthub.json`(**不含凭证**,那把始终只在内存),「下线」只是断开连接。 插件 config 里写了凭证时 **config 赢**:那个文件不分 profile,别让上一次连别的 hub 留下的 地址把刚签发的凭证送去敲上一家的门。 - 装插件与 profile 的完整步骤见 `plugins/dsh-agenthub/README.md`(有两个真机坑:模板必须是 `web`,patch 文件末尾那行占位 `[]` 必须先删)。 - 热重载只保留一份网关实例;模型来自 harness 的默认模型设置并在心跳里自省上报。 ### 6.4 OpenClaw(`direct`,实验) OpenClaw 的 gateway 是 WebSocket 帧 RPC(`connect.challenge` → `connect` → `req/res` + `event`)。 hub 作为客户端拨它,Agent 侧**没有** AgentHub 配置: | 登记字段 | 值 | | --- | --- | | `driver` | `openclaw` | | `connection_mode` | `direct` | | `base_url` | `ws://…`(或放在 `config.ws_url`) | | `auth` | `{"token": "…"}`:OpenClaw 自己的网关令牌,不是 `ag_…` | 可在 Agent `config` 里覆盖 `method_send` / `method_abort` / `session_key` / `protocol`,换网关版本 不用改 hub 代码。该驱动标记 `experimental`(上游只发 CLI 二进制,测试用脚本化 peer 锁协议)。 ### 6.5 openai_compatible(`direct`) 任何暴露 OpenAI 风格 HTTP 接口(`/v1/models`、`/v1/chat/completions`)的服务: ```bash agenthub agent add --name local-llm --driver openai_compatible --connection direct \ --base-url http://127.0.0.1:8000 # auth 用控制台/API 填 {"token": "sk-…"}(该服务自己的鉴权,不是 AgentHub 的) ``` ### 6.6 mock(联调) `driver: "mock"`:不连任何外部服务,用 `config.delay_s` 模拟耗时,用来验证"派活 → 事件流 → 完成"的链路。**不要**用在生产。 ### 6.7 自研接入件 / 单文件 SDK(外拨) 仓库里有一份只用标准库 + `websockets` 的参考客户端: `deploy/nanobot-gateway/channel/agenthub/agenthub_client.py`。贴十几行起一个进程,就是一个 `connector` 形态的接入件: ```python from agenthub_client import GatewayClient, GatewayConfig config = GatewayConfig( hub_url="http://127.0.0.1:8100", name="my-agent", agent_token="ag_…", # 只有这一格:控制台「接入」页签发的凭证 driver="my-framework", connection_mode="connector", ) async def my_runner(payload, emit) -> str: # payload["prompt"] → 最终文本 await emit("status", message="running") return await my_framework.run(payload["prompt"]) async def my_capabilities() -> dict: # 自省:实际模型、runtime、是否流式 return {"model": "…", "runtime": "my-framework", "streaming": True} client = GatewayClient(config, my_runner, describe=my_capabilities) await client.run() # 内部处理重连、心跳、task.run / task.cancel ``` 要接 `agent.command` 就再给 `command=`:`async def command(name, args) -> dict`。 流式在 runner 里 `await emit("delta", text=…)` / `emit("tool", name=…, input=…)`, 返回值就是最终文本。 ### 6.8 新类型接入 checklist 1. 选形态(2.3)——凭证没有第二条路可挑(0.2)。 2. 照 4.1 的字段表写配置,**不要**新增字段名变体;`model` / `role` 不进接入配置。 3. 实现帧:上行 `agent.hello` / `agent.heartbeat` / `agent.event` / `agent.deregister`; 下行 `task.run` / `task.cancel` / `agent.ping` / `agent.describe`。 4. 满足 3.5 的 R1–R4(无状态身份、拒绝与不可达分离、启动重试、内存凭证)。 5. 自省上报 `capabilities`(实际模型、runtime、是否支持流式)。 6. 跑离线自检 → 跑真机验收(第 9 节)。 --- ## 7. 接入片段(snippets)与接入向导 hub 不部署任何 Agent,只给"粘到哪一行 / 跑哪条命令"的片段。四种片段 (`GET /api/v1/deploy/templates`): | kind | 落到哪 | 内容 | | --- | --- | --- | | `bridge` | 不落盘:在 Agent 那台机器上执行 | `deploy/cli-bridge/bridge.py` 的启动命令(hub 地址 + 凭证 + `--cli/--workdir/--mode`) | | `nanobot` | `~/.nanobot/config.json` 的 `channels.agenthub` | `server` + `name` + `agent_token` | | `dsh` | profile 的 `cordis.patch.yml` 插件 config | 同上(camelCase) | | `direct` | 不落盘:打印登记命令 | `POST /agents` 的 curl(base_url + auth) | 生成方式: ```bash agenthub config --name alpha --kind bridge # 或 nanobot / dsh / claw ``` 连入只有两类,向导也就三步:**选类型 → 选 Agent → 生成凭证**。 | 步 | 做什么 | | --- | --- | | **① 选类型** | 只有两类:**插件 / 渠道**(Agent 那边有地方贴一段配置 —— DeepSeek Harness 插件、nanobot 内置渠道、OpenClaw 渠道)和**桥接**(Agent 只有一套 CLI —— codex / claude / WorkBuddy,在它所在机器上跑一个桥接进程)。这一步只决定第 ② 步列出哪几套 Agent、片段贴进哪一格 | | **② 选是哪套 Agent** | 填名字(=这台 Agent 在 hub 上的唯一身份)和落点参数(桥接:工作目录 + 权限;DSH:profile)。这一步决定**片段长什么样、凭证贴进哪一格**,不决定凭证本身 | | **③ 生成凭证** | 点「生成凭证」= hub 建档 + 当场签发这台 Agent 的 `ag_…`;把「hub 地址 + 凭证」贴到 Agent 那边;下面那行状态读 `GET /agents/{ref}/presence`,它变绿就是注册验证通过。名字已存在时按钮是「重新签发」(旧的立即失效)——那通常就是同一台 Agent 重新接一次 | 两类要填的东西一字不差:`server`(hub 的 IP+端口)+ `agent_token`(这把 `ag_…`)。 **签过的凭证随时能查回来**:第 ③ 步的「查看凭证」走 `GET /agents/{ref}/credentials`(管理员 key), 不必为了再看一眼明文而轮换一次。 **OpenClaw 走的是 `claw` 渠道片段**:hub 照签一把 `ag_…` 并渲染出 `{"agenthub": {server, name, agent_token}}`,但 OpenClaw 侧的 agenthub 渠道实现**不在本仓库**, 要那侧先有对应配置才接得上。hub 里原有的 `openclaw` 驱动(hub 直拨它的 gateway, `connection_mode: direct`)没有删除,只是不再出现在向导里,登记办法见 2.2。 `agenthub config` 命令行没有"当场签发"这一步:已建档的 Agent 它直接印出真凭证(库里存着 一份可解开的封存副本),还没建档的才留 `` 占位。 --- ## 8. 端到端时序(一条路长什么样) ``` 控制台「接入」①② 选类型 + 选 Agent → 只决定片段长什么样(bridge|nanobot|dsh|claw) 控制台「接入」③ 点「生成凭证」 POST /api/v1/agents {issue_credential:true} → ag_…(之后 GET 同一把) Agent 侧 填 server + ag_… 照抄片段,一格都不多填 接入件 先探一次 POST /gateway/heartbeat(Bearer ag_…)→ 200 才去拨 WS 接入件 拨控制通道 WS /gateway/ws?agent_token=ag_… hub 从凭证反查 → online hub.hello{agent_id, heartbeat_interval_s, frame_kinds} 接入件 agent.hello capabilities(自省:model / runtime / streaming) 之后 agent.heartbeat ×N hub 侧判定:外拨 socket 在线 > 心跳新鲜 > 主动 probe ``` 派活时的下行与上行见 5.2 / 5.3。整条路上操作员只需要记住两件事:**hub 的地址** 和 **那一把凭证**。别的标识(`agent_id`)由 hub 在 hello 里给;出问题时的第一现场是接入件日志 + `GET /api/v1/gateway/status`,不是配置文件里抄来的某个 id。 --- ## 9. 排障与验收 | 现象 | 原因 | 处置 | | --- | --- | --- | | 401 `missing agent token` / WS 上来就 `4401` | Agent 侧那一格凭证是空的 | 填控制台「接入」页签的 `ag_…`(`agent_token` / `agentToken` / `--token`) | | 403 `unknown or rotated agent token` | 凭证被轮换/删掉了,或粘的是**别的 hub** 签的那份 | `agenthub agent rotate `(或控制台轮换)后重填;换 hub 得重新建档 | | 403 且提示"这是 hub 的 API Key" | 把 `ah_…` 填进了 Agent 凭证那一格 | 换成 `ag_…`;`ah_…` 只管控制台与管理 API | | 日志说 `enrollment` / `hubId` 已取消 | 配置里还留着旧机制那两行 | 删掉它们,只填 `agentToken` | | 409(建档那一步) | 同名那一行已经存在 | 用那一行现有的凭证,或换名字(3.4) | | Agent 显示 offline 但进程活着 | 控制通道断了(NAT 超时 / 网络抖动) | 接入件按 R1/R2 重连;看 `GET /gateway/status` | | 派活立刻失败 "no live connector session" | 外拨 Agent 不在线 | 等它重连;或改用 direct | | 模型显示为空 | Agent 没在心跳里自省上报 | 接入件补 `capabilities.model`(模型来自 Agent 自己,不是配置副本) | | 派活报 `no API key for provider route`(DSH) | 接入链路已经通了,缺的是**模型**凭证 | 在这个 DSH 的 Settings → Models 存 key,或起进程前 export `DEEPSEEK_API_KEY` | | 控制台一片 `TypeError: Failed to fetch` | CSP 没放行 hub origin | 见 README「常见坑」:重设 `NEXT_PUBLIC_HUB_URL` 后重新构建 | ### 9.2 验收清单 离线(不依赖真 hub): 1. 建档带 `issue_credential` → 拿到明文 `ag_…` → 用它拨 WS 上线;没有凭证或凭证不对被明确拒。 2. 轮换 → 旧凭证立刻失效;带 `grace_seconds` 时双活到点才失效。 3. 任何读接口都不回显明文(只有 `credential.preview`)。 4. 旧路由 `/gateway/register`、`/gateway/join`、`/enrollment`、`/meta/hub-id` 全是 404 —— 它们是被删掉的**第二、第三条路**,别再往回加。 5. 旧字段名(`hubUrl` / `AGENTHUB_AGENT_NAME`)仍可读;旧凭证字段(`enrollment` / `hubId`)不再被读。 6. 缺 `server` 时接入件明确拒绝启动,而不是默默连 `127.0.0.1`。 真机: 7. `agenthub agent add --show-token` → 把 `agent_token` 写进 nanobot / dsh 配置 → 控制台 online; 删掉任何身份文件后重启 → 仍然 online。 8. 控制台轮换凭证 → 接入件日志里说清去哪把新的;重填新凭证后恢复在线(不用重启 hub)。 9. 桥接(codex / claude / WorkBuddy):控制台派活 → 事件流完整 `status → delta/reasoning/tool → completed`,答案文本回到任务里。 10. DSH:照 `plugins/dsh-agenthub/README.md` 那四步(模板必须是 `web`、先删 patch 末尾的 `[]`) → 日志出现 `dialing` → 控制台 online。 ### 9.3 对应测试 | 测试 | 覆盖 | | --- | --- | | `tests/test_api_agents.py` | 建档 / 凭证签发与轮换(含宽限窗口)/ 心跳自省 / 探活 / describe / `/meta` 枚举;**旧自注册与加入路由必须 404** | | `tests/test_gateway_ws.py` | 真实 WS 帧:凭证鉴权、派活、探活、取消只发一条、控制台 `?since=` 补发 | | `tests/test_channel_config.py` | nanobot 渠道配置读取:config 为准、凭证 env 优先、旧字段名兼容读、缺 `server` 直接拒 | | `tests/test_client_lifecycle_api.py` | 单文件 SDK 的生命周期:方法不被实例属性遮蔽、`request_stop()` 可 await | | `tests/test_cli.py` | `init` / `doctor` / `status` / `agent add` / `agent rotate` / `config` 脱机可跑;片段里不出现旧凭证字样 | | `tests/test_snippets.py` | 四种接入片段的内容与占位符;Agent 侧文案不许指向步骤号 | | `tests/test_driver_nanobot_ws.py` | nanobot WS 渠道协议(ready / message / delta / … / turn_end、session_key→chat_id) | | `tests/test_driver_openclaw.py` | OpenClaw 帧协议(challenge / connect / req-res / stream / abort) | | `tests/test_driver_plugins.py` | 第三方驱动 entry-point 注册;坏插件不拖垮内置驱动 | | `tests/test_interop_nanobot.py` | 真 nanobot 互操作(health / models / 派活 / 它自己的 api key) | | `plugins/dsh-agenthub/selfcheck.mjs` | 插件接线与 Gateway 帧协议离线自检 | --- ## 10. 附录 ### 10.1 术语 | 词 | 含义 | | --- | --- | | **hub** | 本仓库的控制平面(REST + WS);DB 是唯一权威 | | **driver** | hub 侧的通信实现;`connector` 服务于所有外拨接入件 | | **接入件** | 跑在 Agent 侧、说 Gateway 协议的那段代码(nanobot 渠道 / dsh 插件 / 自研 SDK 进程) | | **agent_token** | `ag_…`,一台 Agent 的唯一凭证(=身份);明文可随时查回(第 7 节) | | **run grant** | 协作接口用的短期 HMAC 凭证,绑定 run_id + agent_id | ### 10.2 变更记录 | 时间 | 变更 | | --- | --- | | 2026-09-25 | 身份即配置:取消 Agent 侧身份文件(旧文件只读兜底一个版本);手工登记可签发 `agent_id`+`agent_token`;`role`/`model` 从注册字段里删除(role 归 hub,model 靠心跳自省);connector **产品面**(CLI / Dockerfile / 演示栈 / 部署产物生成器)删除,只保留驱动与单文件 SDK;`agenthub deploy` → `agenthub config`(接入片段);新增 Hub ID 加入路径。 | | 2026-09-26 | 设置项与枚举去重:删除幽灵设置「本机部署」与重复的 `/meta.driver_names`、`GET /agents/drivers`;`drivers` / `agent_types` / `connection_modes` / `deployment_kinds` 统一由 `GET /api/v1/meta` 下发,控制台不再各自硬编码(编辑弹窗的驱动 / 类型 / 接入方式 / 部署形态下拉改由 meta 驱动);本规范重写为 v2 —— 去掉提案与落地记录,只留当前行为。 | | 2026-10-14 | **接入向导收成三步**:第 ① 步只剩「Agent 主动外拨 / hub 直连过去」两种模式,第 ② 步才选是哪套 Agent,第 ③ 步建档并签发(直连那一类给登记命令,不签凭证)。Agent 侧的配置面仍然是 hub 地址 + 一把 `ag_` 凭证,一格都没多。 | | 2026-10-14 | **接入只剩一条路**:删掉 enrollment 入场令牌与 Hub ID 加入两条备用路径(`POST /gateway/register`、`/gateway/join`、`/enrollment`、`/meta/hub-id` 一并删除),统一成「hub 签发一把 `ag_` 凭证 → Agent 填 hub 地址 + 这把凭证 → 连上即注册验证」;控制台「接入」页收成一条路(选是哪套 Agent → 签发凭证并验证),不再区分预注册/自注册;dsh 插件与 nanobot 渠道同步取消 `enrollment` / `hubId` 配置键(读到就报一行让你删);`grace_seconds` 轮换窗口实装。 | | 2026-10-15 | **连入只有两类**:向导第 ① 步改成「插件 / 渠道」与「桥接」,第 ③ 步改名「生成凭证」;「hub 直连过去」这一类从向导里删除(`direct` 片段 kind 一并删除,OpenClaw 改出 `claw` 渠道片段,`connection_mode: direct` 作为驱动能力保留)。新增 `GET /agents/{ref}/credentials`:已签发的凭证可反复查回,库里为此另存一份 seal 过的副本(密钥 = `secret_key`),认证仍只读哈希;`agenthub config` 对已建档的 Agent 直接印真凭证。措辞上「边车」统一改叫「桥接」。 |