535 lines
33 KiB
Markdown
535 lines
33 KiB
Markdown
# AgentHub
|
||
|
||
多 Agent 协作控制面:把**本地进程、Docker 容器、云端实例**里的各种 Agent 统一纳管起来,
|
||
用一条 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 的参考 clone)
|
||
已 .gitignore,不参与构建。
|
||
|
||
```
|
||
浏览器 ── ▶ 控制台 (Next.js, :3100)
|
||
│ REST + WebSocket/SSE(API Key)
|
||
▼
|
||
AgentHub Hub (FastAPI, :8100)
|
||
├ Registry 登记 / 身份 / 能力 / 凭证
|
||
├ Gateway Frame 协议 + 事件总线 + 帧审计
|
||
├ Tasks 单 Agent 任务(流式事件)
|
||
├ Collab 团队 / Playbook / Run / 黑板 / 交接
|
||
└ Deploy 接入片段渲染 + 签发存档
|
||
│ 唯一一条通道:Gateway 的 Frame 协议(JSON 帧 + 流式事件)
|
||
┌──────────────┴──────────────┐
|
||
▼ 外拨(push) ▼ 直拨(direct)
|
||
Agent 自己连 hub hub 拨 Agent 的 HTTP/WS
|
||
nanobot 渠道 / dsh 插件 / 桥接 nanobot serve / OpenAI 兼容 / OpenClaw
|
||
```
|
||
|
||
**只有 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` / `connector` | Agent 进程里的接入件往外拨 WS | 装接入件 + 写一段 config | 能改 Agent 的镜像 / 依赖;NAT 后、只有出网权限的容器和云主机 |
|
||
| **直拨** | `direct` | hub 直接拨 Agent 的 HTTP/WS | 0 改动 | hub 能直达 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 # 建表 + 生成 <data_dir>/hub-credentials.json
|
||
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
|
||
```
|
||
|
||
控制台右上角「配置 API KEY」粘贴 hub 的 API Key(首次启动写在 `data/hub-credentials.json`),Key 只存浏览器 localStorage。
|
||
|
||
## 接入:三步向导
|
||
|
||
只有两类接入:**插件 / 渠道**(Agent 里本来就有可以装东西的地方)和**桥接**(Agent 只有一套 CLI,
|
||
旁边跑一个进程替它拨 hub)。向导就三步,按钮只有**下一步 / 上一步 / 完成**:
|
||
|
||
| 步骤 | 内容 |
|
||
| --- | --- |
|
||
| ① 选择类型 | 插件 / 渠道 · 桥接 |
|
||
| ② 选择 Agent | DeepSeek Harness、nanobot、OpenClaw / codex、claude、WorkBuddy;填「Agent 名字」。只有桥接多问两个:**工作目录** + **权限**(`readonly` / `write`) |
|
||
| ③ 生成凭证 | **走到这一步就已经签好了**:直接显示 `ag_…` 明文和那段配置原文,各自带 COPY。想换一把点右侧小号「重新签发」;点「完成」回到第 ① 步 |
|
||
|
||
页面顶部只有一行 `Hub 地址 <url>` + 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 }
|
||
```
|
||
|
||
### 四种片段
|
||
|
||
`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/<profile>/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
|
||
```
|
||
|
||
```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" } } }
|
||
|
||
// 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" } }
|
||
```
|
||
|
||
```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`(已在册的直接印真值,未建档留 `<agent_token>` 占位)。
|
||
|
||
签在「可回看」之前的老凭证读不回明文(库里只有哈希),点「重新签发」换一把之后就能反复查看。
|
||
|
||
命令行等价(绕开向导时用):
|
||
|
||
```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
|
||
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
|
||
return turn.answer
|
||
|
||
async def describe() -> dict: # 可选:能力自述,控制台会显示
|
||
return {"streaming": True, "runtime": "my-agent"}
|
||
|
||
client = GatewayClient(
|
||
GatewayConfig(
|
||
hub_url="http://127.0.0.1:8100",
|
||
agent_token=os.environ["AGENTHUB_AGENT_TOKEN"], # 密钥只从环境读,不进代码也不进镜像
|
||
name="my-agent",
|
||
deployment_kind="docker",
|
||
),
|
||
on_task,
|
||
describe=describe,
|
||
)
|
||
await client.run() # 断线重连 + 心跳 + 取消,都在里面
|
||
```
|
||
|
||
身份**不落盘**:配置里那一把 `agent_token` 就是它的全部身份,进程重建之后填的还是同一把,`agent_id` 自然不变。
|
||
`delta / reasoning / status / tool / completed` 原样回到 hub 的事件流。取消也是真的:
|
||
客户端收到 `task.cancel` 调 `runner.cancel()`,事件流以 `cancelled` 收场(DSH 插件走 `agent.cancel`)。
|
||
|
||
### nanobot 渠道
|
||
|
||
`deploy/nanobot-gateway/channel/agenthub/` 是一个 nanobot channel 包。nanobot 只扫
|
||
`nanobot.channels.__path__`,没有外部插件目录,所以装一次进安装树:
|
||
|
||
```bash
|
||
cp -R deploy/nanobot-gateway/channel/agenthub \
|
||
"$(python -c 'import nanobot.channels as p; print(list(p.__path__)[0])')/agenthub"
|
||
```
|
||
|
||
```jsonc
|
||
// ~/.nanobot/config.json —— 和 telegram、websocket 同级的普通渠道
|
||
{ "channels": { "agenthub": {
|
||
"enabled": true, "server": "http://127.0.0.1:8100", "name": "alpha",
|
||
"display_name": "阿尔法",
|
||
"agent_token": "ag_xxxxxxxx" // 只有这一格是凭证
|
||
}}}
|
||
```
|
||
|
||
```bash
|
||
nanobot gateway --foreground # 渠道拨上 hub 就上线,nanobot 的代码和启动方式都不改
|
||
```
|
||
|
||
- 字段全在 `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`。
|
||
|
||
### DeepSeek Harness 插件(`plugins/dsh-agenthub`)
|
||
|
||
DSH 是「一切皆插件」的 Harness,所以接入方式是给它写一个插件,而不是让 hub 去理解它内部:
|
||
插件与 DSH 同进程,往 hub 拨一条出站 socket。
|
||
|
||
```
|
||
hub ◀── 出站 WS ── @nex/dsh-agenthub(DSH 插件,Host 半)
|
||
├ task.run → ctx.agents.resume/create + agent.followup(createUserMessage)
|
||
├ 过程事件 ← agent/assistant-stream + session/event(tool/call, turn/end)
|
||
├ task.cancel → agent.cancel({kind:'user'})
|
||
└ 设置面板 ← POST /api/agenthub/status(Client 半:身份 / 连接 / 最近任务)
|
||
```
|
||
|
||
```bash
|
||
# 装插件必须用 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
|
||
```
|
||
|
||
两个真机坑: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)
|
||
|
||
不动 CLI 一行代码,在它所在机器上跑一个桥接进程(`bridge.py` 只需要 Python 3,不装任何依赖;
|
||
旁边 `adapters/` 里一个 CLI 一个适配器,新增一家就加一个文件)。
|
||
|
||
```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` | ❌ 同左 |
|
||
|
||
参数:`--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-<name>.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/<cwd>/`…)且按工作目录归档,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_id>` | 任务的 `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-<key>` 形态的 `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 判定来源、最后一帧 |
|
||
| 办公室 | 像素办公室:一 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`,刷新不闪。
|
||
|
||
四种 Playbook:`sequential`(A→B→C)、`parallel`(并行后汇总)、`round_robin`(N 轮讨论)、
|
||
`handoff`(Agent 输出交接块决定下一步交给谁)。Agent 侧零改造:hub 把 hub 地址、run id、
|
||
短期 run grant、「你是这队伍里的哪一个」写进 prompt,Agent 想协作时按提示 curl 一下 `/collab/*` 即可。
|
||
交给自己的交接块会被忽略并结束本次 Run,避免原地打转。
|
||
|
||
### 控件规格
|
||
|
||
- **尺寸只有两档**:`md` = 32px(页面/卡片主操作、表单行),`sm` = 26px(工具条、表格行内动作、chip)。
|
||
边框 2px、圆角 6px、ArkPixel 字体(11px / 10px)、焦点环 2px 金色;token 在 `app/globals.css` 的 `--ctl-*`。
|
||
- **页面只用原语**:`Panel PixelButton LinkButton Dot Badge Input Select Textarea SearchInput Field Tabs Chip
|
||
Modal Empty ErrorNote CopyButton JsonBlock Spinner KV usePaged/Pager`(都在 `components/ui.tsx`),
|
||
没有裸 `<button>` 和裸类名。`lib/`:`api format office-layout office-palette sse theme theme-keys types
|
||
useAsync useHubSocket`。
|
||
- **提示窗体只有两种**:要用户点头的用 `useConfirm()`(危险动作默认焦点在「取消」,确认按钮红色),
|
||
只报结果用 `useToast()`(右下角,错误 8s / 成功 3.2s)。代码里**不允许** `window.confirm/alert/prompt`。
|
||
- **弹窗外壳统一**:`size="sm|md|lg"`(420 / 640 / 920px),动作右对齐——取消在左、危险动作居中、主操作最右。
|
||
|
||
## 配置
|
||
|
||
全部走 `AGENTHUB_` 前缀环境变量(也支持 `backend/.env`):
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
| --- | --- | --- |
|
||
| `AGENTHUB_HOST` / `AGENTHUB_PORT` | `127.0.0.1` / `8100` | 监听地址 |
|
||
| `AGENTHUB_HUB_PUBLIC_URL` | 同监听地址 | 写进接入片段与协作 briefing 的对外地址 |
|
||
| `AGENTHUB_DATA_DIR` | `<仓库根>/data` | SQLite 文件与 `hub-credentials.json` 位置;默认值锚定仓库位置,与启动目录无关 |
|
||
| `AGENTHUB_DATABASE_URL` | 由 data_dir 推导 | 换库只改这里 |
|
||
| `AGENTHUB_DB_POOL_SIZE` / `AGENTHUB_DB_ECHO` | `5` / `false` | 连接池 |
|
||
| `AGENTHUB_API_KEY` / `AGENTHUB_SECRET_KEY` | 自动生成 | `secret_key` 也是凭证与签发存档的 seal 密钥 |
|
||
| `AGENTHUB_AUTH_ENABLED` | `true` | 控制台面鉴权 |
|
||
| `AGENTHUB_DEV_DISABLE_AUTH` | `false` | 仅本地调试 |
|
||
| `AGENTHUB_GRANT_TTL_S` | `21600` | 协作 run grant 的存活秒数 |
|
||
| `AGENTHUB_HEARTBEAT_INTERVAL_S` / `_TIMEOUT_S` | `15` / `45` | 外拨 Agent 心跳 |
|
||
| `AGENTHUB_PRESENCE_INTERVAL_S` / `AGENTHUB_PRESENCE_ENABLED` | `5` / `true` | presence 扫描 |
|
||
| `AGENTHUB_DIRECT_PROBE_INTERVAL_S` | `60` | 直拨 Agent 的定期探活 |
|
||
| `AGENTHUB_TASK_TIMEOUT_S` / `AGENTHUB_MAX_CONCURRENT_TASKS` | `300` / `16` | 任务闸门 |
|
||
| `AGENTHUB_CONNECTOR_RPC_TIMEOUT_S` | `60` | 走 Gateway 的 RPC 超时 |
|
||
| `AGENTHUB_EVENT_BUFFER_SIZE` / `AGENTHUB_FRAME_AUDIT_LIMIT` | `2000` / `500` | 事件与帧审计环形窗口 |
|
||
| `AGENTHUB_PERSIST_TASK_EVENTS` | `true` | 事件是否落库 |
|
||
| `AGENTHUB_CORS_ORIGINS` | `*` | 生产建议收敛到控制台域名 |
|
||
|
||
Key 有两种 scope:`admin` / `read`。控制台面写操作和 `POST /deploy/plan {record:true}` 都要 admin。
|
||
|
||
前端两个**构建期**变量:`NEXT_PUBLIC_HUB_URL`(hub 地址,默认 `http://127.0.0.1:8100`)、
|
||
`CSP_CONNECT_SRC`(hub 不在 localhost 时补 CSP 的 connect-src)。`next.config.ts` 用 `output: "standalone"`,
|
||
并把 `NEXT_PUBLIC_HUB_URL` 的 origin 自动并进 `connect-src`。
|
||
|
||
## CLI
|
||
|
||
```
|
||
agenthub serve [--host --port --reload]
|
||
agenthub init | seed [--no-team] | status | agents | doctor | presence
|
||
agenthub probe <agent> | task <agent> <prompt> | run <team> <objective>
|
||
agenthub agent add --name X [--driver --type --connection --kind --base-url --role --labels K=V --show-token]
|
||
agenthub agent rotate <agent>
|
||
agenthub config --name X [--kind bridge|nanobot|dsh|claw] [--driver]
|
||
```
|
||
|
||
`init/doctor/status/config/agent add/agent rotate` 都能脱机跑(不依赖 HTTP 服务)。**没有** `agenthub token` 子命令。
|
||
|
||
## 数据与凭证
|
||
|
||
12 张表:`agents, tasks, task_events, teams, team_members, runs, run_steps, blackboard_entries,
|
||
inter_agent_messages, api_keys, credential_issuances, audit_logs`。启动/`agenthub init` 时按增量列清单自动
|
||
`ALTER TABLE`,老库不用手工迁移。
|
||
|
||
- Agent 凭证库里存**哈希**(认证只读哈希),另存一份 seal 过的可读副本 `token_cipher` 用于回看;
|
||
签发存档 `credential_issuances.payload_cipher` 同样是 `seal(secret_key, …)`。换过 `secret_key` 后这些副本读不回明文,
|
||
哈希认证不受影响。
|
||
- 模型只用跨库安全的类型(JSON / String / DateTime + UTC),换库基本是改 URL:
|
||
|
||
```bash
|
||
pip install -e ".[postgres]" # 或 ".[mysql]"
|
||
export AGENTHUB_DATABASE_URL="postgresql+asyncpg://hub:hub@127.0.0.1:5432/agenthub"
|
||
# mysql+aiomysql://hub:hub@127.0.0.1:3306/agenthub
|
||
agenthub init && agenthub serve
|
||
```
|
||
|
||
HTTP 面都在 `/api/v1` 下:`/agents`(CRUD、`credentials` 签发与回看、probe、describe、command、tasks、presence)、
|
||
`/tasks`(+ `events/stream/cancel/raw`)、`/teams` `/playbooks` `/runs` `/blackboard` `/messages`、
|
||
`/deploy/{templates,plan,issuances}`、`/gateway/{heartbeat,deregister,status,frames,ws,stream,purge}`、
|
||
`/meta` `/stats` `/keys` `/audit` `/presence`、`/collab/{blackboard,messages,context}`。
|
||
|
||
## Docker 部署
|
||
|
||
```bash
|
||
cd deploy
|
||
docker compose up -d --build # hub + console
|
||
docker compose exec hub cat /var/lib/agenthub/hub-credentials.json # 取 API Key
|
||
```
|
||
|
||
`hub`(`agenthub:latest`,8100,`AGENTHUB_HUB_PUBLIC_URL` + `AGENTHUB_DATA_DIR=/var/lib/agenthub` +
|
||
volume `agenthub-data`)+ `console`(3100,build args `NEXT_PUBLIC_HUB_URL` / `CSP_CONNECT_SRC`)。
|
||
只有这两个服务,**没有 `--profile`**。再纳管 Agent 走各自的接入件(nanobot 用
|
||
`deploy/nanobot-gateway/docker-compose.yml`)。容器里的 Agent 用 `http://hub:8100` 连 hub,浏览器仍用 `http://127.0.0.1:8100`。
|
||
|
||
## 开发与测试
|
||
|
||
```bash
|
||
cd backend && .venv/bin/python -m pytest -q # 142 passed
|
||
cd frontend && pnpm typecheck && pnpm lint && pnpm build
|
||
```
|
||
|
||
| 测试 | 锁住的行为 |
|
||
| --- | --- |
|
||
| `test_db_portability.py` | 建表/索引语句在 sqlite / postgresql / mysql 三种方言下都能编译(类型、索引长度、约束命名可移植;不需要装 asyncpg / aiomysql) |
|
||
| `test_gateway_ws.py` | 真实 WebSocket 帧格式:派活、探活、**一次取消只下发一条 `task.cancel`**、控制台断线用 `?since=` 补发 |
|
||
| `test_api_teams.py` | Run 取消会打断正在跑的 step(step 在建任务时就绑定 task_id)。`test_cancelling_a_run_stops_the_step_in_flight` 偶发 flaky |
|
||
| `test_driver_plugins.py` | 外部包用 entry-point `agenthub.drivers` 注册驱动即可被派活;坏插件不拖垮内置驱动;未知 driver 只让该任务失败 |
|
||
| `test_cli.py` | `init/doctor/status/config/agent add/agent rotate` 脱机可跑 |
|
||
| `test_snippets.py` | 接入向导的字面量契约:`app/connect/page.tsx` 的 `STEPS`、`AccessType`、`TARGETS` 与 hub 侧片段 kinds 必须对得上(**改向导文案会红**);片段的文件名/占位符/`next_steps`;签发存档的 `active` 语义;并且扫 `README.md` 与 `docs/*.md`,不许把已删的接入机制当现状重新写回来 |
|
||
| `test_interop_nanobot.py` | 对着真实 nanobot 包的 `create_app()` 跑 |
|
||
| `test_driver_nanobot_ws.py` | 脚本化 nanobot WebSocket peer 锁协议:`ready`→`message`→`delta`/`reasoning_delta`/`tool_hint`/`stream_end`/`turn_end`、`session_key`→`chat_id` |
|
||
| `test_driver_openclaw.py` | 脚本化 gateway peer 锁帧:`connect.challenge`→`connect`→`req/res`、流式 `agent` 事件、`chat` 终态、`chat.abort` 取消 |
|
||
|
||
驱动:`mock`、`openai_compatible`、`nanobot`、`nanobot_ws`、`connector`、`openclaw`,外加 entry-point group
|
||
`agenthub.drivers`。成熟度:`connector` / `nanobot` / `nanobot_ws` / `openai_compatible` 稳定,
|
||
`mock` 只用于打通链路(`delay_s` 模拟耗时),`openclaw` 是**实验**——上游 PyPI 包只发 CLI 二进制,
|
||
测试里起不了真网关,所以用脚本化 peer 锁协议;`method_send` / `method_abort` / `session_key` / `protocol`
|
||
都可在 Agent `config` 里覆盖,换网关版本不用改代码。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
backend/ FastAPI + SQLAlchemy(async) 控制面 + registry/gateway/tasks/deploy;CLI:agenthub
|
||
frontend/ Next 16 + React 19 + Tailwind 4 控制台(AgentTown 像素 HUD)
|
||
deploy/ Dockerfile.backend / .console / .nanobot + docker-compose.yml
|
||
nanobot-gateway/ nanobot 渠道 + 两容器样例(零桥接进程、零入站端口)
|
||
cli-bridge/ bridge.py + adapters/(codex / claude / workbuddy)
|
||
plugins/ dsh-agenthub(@nex/dsh-agenthub),不进后端构建
|
||
scripts/ dev.sh(一键起 hub+console)· attach.sh(按 task_id 进原生 CLI 会话)
|
||
data/ agenthub.db + hub-credentials.json(已 .gitignore,默认位置与启动目录无关)
|
||
docs/ PLAN.md(功能规划、API 契约、里程碑)+ AGENT_REGISTRATION.md(注册与身份规范)
|
||
soucecode/ 参考 clone(nanobot、agent-town),已 gitignore,不参与构建
|
||
```
|
||
|
||
## 常见坑
|
||
|
||
- **控制台一片 `TypeError: Failed to fetch`**:请求没离开浏览器。
|
||
`curl -sI http://127.0.0.1:3100/ | grep -i content-security` 看 `connect-src` 里有没有 hub 的 origin
|
||
(改过 `NEXT_PUBLIC_HUB_URL` 要重新 `pnpm build`);再确认右上角 API Key 是当前 `data/hub-credentials.json` 里那把。
|
||
- **改了 `NEXT_PUBLIC_HUB_URL` 没生效**:它是构建期常量,`dev` 要重启、`build` 要重新构建。
|
||
- **`pnpm start` 提示 standalone**:生产跑 `node .next/standalone/server.js`(先 `pnpm build`)。
|
||
- **Agent 连不上(外拨)**:看它自己日志有没有 `dialing …` / `已上线`;hub 侧看
|
||
`GET /api/v1/gateway/status` 的 connections。凭证被轮换过就 401/403——`agenthub agent rotate <name>`
|
||
重新签一把填回去。
|
||
- **`POST /deploy/plan` 403 `this hub key is read-only`**:这把 key 是 `read` scope。签发记录走
|
||
`record:true`,必须 admin key。
|
||
- **换目录启动后 Agent 全没了 / API Key 变了**:`AGENTHUB_DATA_DIR` 被显式设成了**相对路径**。默认值锚定仓库根的 `data/`。
|
||
- **DSH 装完插件起不来**:cordis.patch.yml 里那行占位 `[]` 没删(两个根节点,YAML 直接失败);
|
||
或者 profile 是默认模板建的,只有 `dsh-base`,没有常驻进程去拨 hub。
|
||
- **派活立刻失败 `no live connector session`**:外拨 Agent 不在线,等它重连。
|
||
- **nanobot 回 400 `Only a single user message…` / `Only configured model …`**:这个 Agent 被登记成了
|
||
`openai_compatible`,带上了 system 消息或写死的模型名。换成 `nanobot` driver:它把上下文折叠成一条
|
||
user 消息,并从 `/v1/models` 取模型。
|