agenthub/docs/AGENT_REGISTRATION.md

683 lines
39 KiB
Markdown
Raw Permalink 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.

# 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/<profile>/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_token> 占位
# 控制台等价入口:接入 → ① 选是哪套 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://<hub>/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-<name>.json`、
`--state-file` 指向的文件)**只读兜底一次**:读到就用它上线(升级期内不让人掉线),同时打印
可粘贴进配置的片段提示迁移,之后不再写入。配置里**已经写了**凭证时完全不读它 —— 老文件里
上一世的 `agent_id` 拼到新凭证上会 401(真机撞过)。
### 3.6 安全边界
- `agent_token` 按密钥对待:配置文件权限 `0600`;容器里走 env / secret,不进镜像层、不进日志。
- 一把凭证 = 一台 Agent:它能领这台 Agent 的活、上报它的状态;读不了别的 Agent,
也碰不到控制台面。
- 泄漏处置:`agenthub agent rotate <name>`(或控制台轮换)。旧凭证立刻失效,接入件会在日志里
说清去哪把新的,不需要重启 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.<id>.task.<id>.event", // 总线路由用这个(支持 *.> 通配)
"actor": "hub|agent|<name>",
"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=<seq>`:控制台订阅全部事件;`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 它直接印出真凭证(库里存着
一份可解开的封存副本),还没建档的才留 `<agent_token>` 占位。
---
## 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 <name>`(或控制台轮换)后重填;换 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 直接印真凭证。措辞上「边车」统一改叫「桥接」。 |