683 lines
39 KiB
Markdown
683 lines
39 KiB
Markdown
# 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 直接印真凭证。措辞上「边车」统一改叫「桥接」。 |
|