Agent的hub管理,准备接入esp32的桌面设备。
 
 
 
 
 
Go to file
mula.liu b71c292e1a 修改README.md 2026-10-15 14:05:20 +08:00
backend v 0.1.0 2026-10-15 13:02:36 +08:00
deploy v 0.1.0 2026-10-15 13:02:36 +08:00
docs v 0.1.0 2026-10-15 13:02:36 +08:00
frontend v 0.1.0 2026-10-15 13:02:36 +08:00
plugins/dsh-agenthub v 0.1.0 2026-10-15 13:02:36 +08:00
scripts v 0.1.0 2026-10-15 13:02:36 +08:00
.gitignore v 0.1.0 2026-10-15 13:02:36 +08:00
README.md 修改README.md 2026-10-15 14:05:20 +08:00

README.md

AgentHub

多 Agent 协作控制面:把本地进程、Docker 容器、云端实例里的各种 Agent 统一纳管起来, 用一条 Gateway 通信,用一套 Playbook 编排协作。nanobot 是第一个被纳管的 Agent,但不是唯一一个 ——DeepSeek Harness、codex / claude / WorkBuddy 这类无头 CLI、OpenClaw、任何 OpenAI 兼容服务都能接进来。

规划文档见 docs/PLAN.md;跨 Agent 类型的注册与身份规范见 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 只说明背后跑的是什么。

快速开始

./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。

手工两步:

# 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。

# 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
// 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" } }
# 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> 占位)。

签在「可回看」之前的老凭证读不回明文(库里只有哈希),点「重新签发」换一把之后就能反复查看。

命令行等价(绕开向导时用):

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 它写十几行:

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__,没有外部插件目录,所以装一次进安装树:

cp -R deploy/nanobot-gateway/channel/agenthub \
  "$(python -c 'import nanobot.channels as p; print(list(p.__path__)[0])')/agenthub"
// ~/.nanobot/config.json —— 和 telegram、websocket 同级的普通渠道
{ "channels": { "agenthub": {
  "enabled": true, "server": "http://127.0.0.1:8100", "name": "alpha",
  "display_name": "阿尔法",
  "agent_token": "ag_xxxxxxxx"    // 只有这一格是凭证
}}}
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 半:身份 / 连接 / 最近任务)
# 装插件必须用 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。

无头 CLI:桥接(codex / claude / WorkBuddy)

不动 CLI 一行代码,在它所在机器上跑一个桥接进程(bridge.py 只需要 Python 3,不装任何依赖; 旁边 adapters/ 里一个 CLI 一个适配器,新增一家就加一个文件)。

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。

派完活想回到那套 CLI 的原生会话里接着看:

./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 零改动、零凭证。向导不提供这一类,手工登记:

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 自己的记忆
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 复用的就是这条通道,没有第二套协议。

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:
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 部署

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。

开发与测试

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