agenthub/README.md

535 lines
33 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.

# 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` 取模型。