修改README.md
parent
892e666acf
commit
b71c292e1a
701
README.md
701
README.md
|
|
@ -1,98 +1,171 @@
|
|||
# AgentHub
|
||||
|
||||
多 Agent 协作控制面:把**本地进程、Docker 容器、云端实例**里的各种 Agent 统一纳管起来,
|
||||
用一个 Gateway 通信,用一套 Playbook 编排协作。nanobot 是第一个被管理的 Agent,但不是唯一一个
|
||||
——OpenClaw、任何 OpenAI 兼容服务、甚至一个 shell 脚本都能接进来。
|
||||
用一条 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),不参与构建。
|
||||
规划文档见 [`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 登记 / 身份 / 能力
|
||||
├ Registry 登记 / 身份 / 能力 / 凭证
|
||||
├ Gateway Frame 协议 + 事件总线 + 帧审计
|
||||
├ Tasks 单 Agent 任务(流式事件)
|
||||
├ Collab 团队 / Playbook / Run / 黑板 / 交接
|
||||
└ Registry Agent 登记 / 凭证签发
|
||||
└ Deploy 接入片段渲染 + 签发存档
|
||||
│ 唯一一条通道:Gateway 的 Frame 协议(JSON 帧 + 流式事件)
|
||||
┌──────────────┴──────────────┐
|
||||
▼ 外拨(push) ▼ 直拨(direct)
|
||||
Agent 自己连 hub hub 拨 Agent 的 HTTP/WS
|
||||
nanobot channel / dsh 插件 本机 nanobot serve / OpenClaw
|
||||
nanobot 渠道 / dsh 插件 / 桥接 nanobot serve / OpenAI 兼容 / OpenClaw
|
||||
```
|
||||
|
||||
**只有 Gateway 一个通信进程**:任务下发、流式事件、心跳、探测、取消全走同一套 Frame 协议,
|
||||
两种形态的差别只在「谁发起这条连接」,协议本身一模一样。**接入件随 Agent 走**:
|
||||
每个 Agent 类型写一个专门的接入件(nanobot 是渠道、DeepSeek Harness 是插件),hub 不替它们做部署。
|
||||
**只有 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` | Agent 进程里的接入件往外拨 WS | 装接入件 + 写一段 config | 能改 Agent 的镜像 / 依赖,想一个容器就是一个 Agent |
|
||||
| **直拨** | `direct` | hub 直接拨 Agent 的 HTTP/WS | 0 改动 | hub 能直达 Agent:本机进程、同网段、带 key 的公网端点。**「接入」向导不提供这一类**,只能手工登记 |
|
||||
| **外拨**(推荐) | `embedded` / `connector` | Agent 进程里的接入件往外拨 WS | 装接入件 + 写一段 config | 能改 Agent 的镜像 / 依赖;NAT 后、只有出网权限的容器和云主机 |
|
||||
| **直拨** | `direct` | hub 直接拨 Agent 的 HTTP/WS | 0 改动 | hub 能直达 Agent。**「接入」向导不提供这一类**,只能手工登记 |
|
||||
|
||||
连入只有两类(详见 [`docs/AGENT_REGISTRATION.md`](docs/AGENT_REGISTRATION.md)):**插件 / 渠道**
|
||||
(Agent 里贴一段配置:DeepSeek Harness 插件、nanobot 渠道、OpenClaw 渠道)和**桥接**
|
||||
(Agent 只有一套 CLI:codex / claude / WorkBuddy,旁边跑一个桥接进程)。两类要填的一字不差 ——
|
||||
hub 给这把 `ag_…`,Agent 侧只填两样:**hub 的地址** + **这把凭证**,连上就算注册验证完成。
|
||||
`agent_id` 由 hub 在连接建立时告诉 Agent;**Agent 侧没有身份文件,也没有第二种凭证**;
|
||||
签过的凭证随时能查回来(控制台「查看凭证」/ `agenthub config`),不必为看一眼明文而轮换。
|
||||
|
||||
**外拨**是 Agent 出站连 hub,所以 NAT 后面、只有出网权限的容器和云主机一样能纳管;
|
||||
只有**直拨**要求 hub 能拨进 Agent,因此它需要 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 seed # 可选:灌演示 Agent / 团队,方便先看效果
|
||||
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
|
||||
```
|
||||
|
||||
登录控制台需要 hub API Key:首次启动写在项目根目录的 `data/hub-credentials.json`(也可在
|
||||
serve 日志里看到)。在页面右上角「配置 API KEY」粘贴即可,Key 只存在浏览器 localStorage。
|
||||
控制台右上角「配置 API KEY」粘贴 hub 的 API Key(首次启动写在 `data/hub-credentials.json`),Key 只存浏览器 localStorage。
|
||||
|
||||
## 接入一个 Agent
|
||||
## 接入:三步向导
|
||||
|
||||
接入只有一种凭证:hub 签发一把 `ag_…`,Agent 那边填「hub 地址 + 这把凭证」
|
||||
(完整规范见 [`docs/AGENT_REGISTRATION.md`](docs/AGENT_REGISTRATION.md)):
|
||||
只有两类接入:**插件 / 渠道**(Agent 里本来就有可以装东西的地方)和**桥接**(Agent 只有一套 CLI,
|
||||
旁边跑一个进程替它拨 hub)。向导就三步,按钮只有**下一步 / 上一步 / 完成**:
|
||||
|
||||
**codex / claude / WorkBuddy 这类无头 CLI 走桥接**:不动它一行代码,在它所在机器上跑一个桥接进程,
|
||||
它自己往外拨 hub(`deploy/cli-bridge/README.md`):
|
||||
| 步骤 | 内容 |
|
||||
| --- | --- |
|
||||
| ① 选择类型 | 插件 / 渠道 · 桥接 |
|
||||
| ② 选择 Agent | DeepSeek Harness、nanobot、OpenClaw / codex、claude、WorkBuddy;填「Agent 名字」。只有桥接多问两个:**工作目录** + **权限**(`readonly` / `write`) |
|
||||
| ③ 生成凭证 | **走到这一步就已经签好了**:直接显示 `ag_…` 明文和那段配置原文,各自带 COPY。想换一把点右侧小号「重新签发」;点「完成」回到第 ① 步 |
|
||||
|
||||
```bash
|
||||
agenthub agent add --name codex-1 --driver connector --connection 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
|
||||
页面顶部只有一行 `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 }
|
||||
```
|
||||
|
||||
其余 Agent(nanobot / DeepSeek Harness / OpenClaw / 自研)做的是同一件事:**控制台「接入」页选类型
|
||||
→ 选 Agent → 点「生成凭证」→ 把片段贴过去**,那一格里装的就是刚签出来的 `ag_…`。命令行等价:
|
||||
### 四种片段
|
||||
|
||||
```bash
|
||||
agenthub agent add --name nanobot-1 --driver nanobot --connection embedded --show-token
|
||||
agenthub config --name nanobot-1 --kind nanobot # 或 bridge / dsh / claw
|
||||
`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
|
||||
```
|
||||
|
||||
- **凭证就是身份**:只有那一格(`agent_token` / `agentToken` / `--token`),`agent_id` 不用抄,
|
||||
hub 在 `hub.hello` 里给;「验证」= 控制台 Agents 页看到它 online。
|
||||
- **身份不落盘**:配置里那一把凭证就是它的全部状态。老版本留下的身份文件只被读一次,
|
||||
日志会打印可粘贴的迁移片段。
|
||||
- **同名不顶号**:建档时同名直接 409 —— 先决定是复用那一行(拿它现有的凭证)还是换名字。
|
||||
- hub 不生成"跑一个 Agent/桥接进程"的编排:`agenthub config` 只给"粘到哪一行"的接入片段。
|
||||
```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" } } }
|
||||
|
||||
### 内嵌接入:把 Gateway 客户端塞进 Agent 进程(推荐)
|
||||
// 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" } }
|
||||
```
|
||||
|
||||
`deploy/nanobot-gateway/channel/agenthub/agenthub_client.py` 是一个**单文件、只用标准库 + websockets**
|
||||
的 Gateway 客户端。任何 Python Agent 接进去只要三步:
|
||||
```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
|
||||
|
|
@ -101,7 +174,7 @@ 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
|
||||
await emit("delta", text=chunk) # status / delta / reasoning / tool / log
|
||||
return turn.answer
|
||||
|
||||
async def describe() -> dict: # 可选:能力自述,控制台会显示
|
||||
|
|
@ -110,9 +183,8 @@ async def describe() -> dict: # 可选:能力自述
|
|||
client = GatewayClient(
|
||||
GatewayConfig(
|
||||
hub_url="http://127.0.0.1:8100",
|
||||
agent_token=os.environ["AGENTHUB_AGENT_TOKEN"], # 密钥只从环境读,不进代码也不进镜像
|
||||
agent_token=os.environ["AGENTHUB_AGENT_TOKEN"], # 密钥只从环境读,不进代码也不进镜像
|
||||
name="my-agent",
|
||||
driver="openclaw",
|
||||
deployment_kind="docker",
|
||||
),
|
||||
on_task,
|
||||
|
|
@ -121,187 +193,49 @@ client = GatewayClient(
|
|||
await client.run() # 断线重连 + 心跳 + 取消,都在里面
|
||||
```
|
||||
|
||||
身份**不落盘**:配置里那一把 `agent_token` 就是它的全部身份,进程重建之后填的还是同一把,
|
||||
`agent_id` 自然也不变。任务从这条 WS 进来,
|
||||
`delta / reasoning / status / tool / completed` 原样回到 hub 的事件流,
|
||||
所以不管是哪种接入件,在控制台里长得一模一样。
|
||||
身份**不落盘**:配置里那一把 `agent_token` 就是它的全部身份,进程重建之后填的还是同一把,`agent_id` 自然不变。
|
||||
`delta / reasoning / status / tool / completed` 原样回到 hub 的事件流。取消也是真的:
|
||||
客户端收到 `task.cancel` 调 `runner.cancel()`,事件流以 `cancelled` 收场(DSH 插件走 `agent.cancel`)。
|
||||
|
||||
**nanobot 就用这条路**:`channel/agenthub/` 是一个 nanobot channel 包。装进 nanobot 的安装树之后
|
||||
`channels.agenthub` 就是一个普通渠道(和 telegram、websocket 同级),nanobot 自己外拨,
|
||||
它的代码和启动方式都不用改:
|
||||
### nanobot 渠道
|
||||
|
||||
`deploy/nanobot-gateway/channel/agenthub/` 是一个 nanobot channel 包。nanobot 只扫
|
||||
`nanobot.channels.__path__`,没有外部插件目录,所以装一次进安装树:
|
||||
|
||||
```bash
|
||||
# 1) 装渠道(一次):nanobot 只扫 nanobot.channels.__path__,没有外部插件目录
|
||||
cp -R deploy/nanobot-gateway/channel/agenthub \
|
||||
"$(python -c 'import nanobot.channels as p; print(list(p.__path__)[0])')/agenthub"
|
||||
```
|
||||
|
||||
```jsonc
|
||||
// 2) ~/.nanobot/config.json —— 和其它渠道一样的写法。
|
||||
// 只放「连到哪 + 我是谁」:模型在 agents.defaults.model 里,角色是 hub 侧概念。
|
||||
// ~/.nanobot/config.json —— 和 telegram、websocket 同级的普通渠道
|
||||
{ "channels": { "agenthub": {
|
||||
"enabled": true, "server": "http://127.0.0.1:8100", "name": "alpha",
|
||||
"display_name": "阿尔法",
|
||||
"agent_token": "ag_xxxxxxxx" // 控制台「接入」页签发,只有这一格是凭证
|
||||
"agent_token": "ag_xxxxxxxx" // 只有这一格是凭证
|
||||
}}}
|
||||
```
|
||||
|
||||
```bash
|
||||
nanobot gateway --foreground # 3) 起进程,渠道拨上 hub 就上线
|
||||
nanobot gateway --foreground # 渠道拨上 hub 就上线,nanobot 的代码和启动方式都不改
|
||||
```
|
||||
|
||||
- 配置字段全在 `channels.agenthub` 下,config.json 是正规来源;只有
|
||||
`AGENTHUB_AGENT_TOKEN` 这一把凭证 env 优先级更高(compose 注入用),
|
||||
其余字段 env 只在没写配置文件时兜底。旧字段名(`hubUrl` 等)一个版本内仍可读。
|
||||
- 想要现成的容器:`cd deploy/nanobot-gateway && ./bootstrap.sh`,为两个容器各签一把凭证
|
||||
(写进 `.env` 的 `AGENT_TOKEN_ALPHA` / `AGENT_TOKEN_BETA`)→ build → up -d,两个容器、零桥接进程、零入站端口。
|
||||
- `bootstrap.sh` 里的模型密钥默认从 `~/.nanobot/config.json` 取,要换 `export DASHSCOPE_API_KEY=... NANOBOT_MODEL=...` 再跑。
|
||||
- 镜像 `nanobot:agenthub`(`deploy/Dockerfile.nanobot`)已经把 channel 软链进安装树,compose 又把
|
||||
`channel/` bind-mount 进容器,所以容器里不用拷;起栈后 `docker compose ps` 是
|
||||
`agenthub-gw-alpha` / `agenthub-gw-beta`。
|
||||
- **没有身份文件**:凭证写在 config.json(或 env)里;`docker compose restart` 之后 `agent_id` 不变
|
||||
(同名认领)。老实例留下的 `~/.nanobot/agenthub-state.json` 只被读一次,日志会打印可粘贴的迁移片段。
|
||||
- compose 里**没有任何 ports**:healthcheck 打的是容器内的 `127.0.0.1:18790`(nanobot gateway 自己的健康端点),hub 拨不进容器,也不需要拨进去。
|
||||
- 字段全在 `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`。
|
||||
|
||||
> **建档时同名会被拒(409)**:hub 不做静默认领,也不许第二把凭证顶掉第一台 Agent。
|
||||
> 要么用那一行现有的凭证,要么先删掉旧的登记行:
|
||||
>
|
||||
> ```bash
|
||||
> curl -X DELETE http://127.0.0.1:8100/api/v1/agents/<agent_id> -H "X-API-Key: $KEY"
|
||||
> ```
|
||||
### DeepSeek Harness 插件(`plugins/dsh-agenthub`)
|
||||
|
||||
### 需要桥接进程时:贴一份 SDK(不再是一个产品)
|
||||
|
||||
`deploy/nanobot-gateway/channel/agenthub/agenthub_client.py` 就是那个单文件客户端(只用标准库 +
|
||||
websockets)。给"改不动、也拨不进"的 Agent 做桥时,import 它写十几行即可 —— 原来那个
|
||||
`agenthub-connector` 进程产品(CLI / Dockerfile / 四容器演示 / 部署产物生成器)已经删掉,
|
||||
只把这份能力保留成 SDK,字段和别的接入件完全一致。
|
||||
|
||||
```python
|
||||
from agenthub_client import GatewayClient, GatewayConfig
|
||||
|
||||
client = GatewayClient(
|
||||
GatewayConfig(hub_url="http://127.0.0.1:8100", name="bridge-agent",
|
||||
agent_token="ag_xxxxxxxx"), # 控制台「接入」页签发的那一把
|
||||
on_task,
|
||||
)
|
||||
await client.run() # 断线重连 + 心跳 + 取消
|
||||
```
|
||||
|
||||
> **为什么内嵌是插件而不是 Agent 的一个 skill?** nanobot 的 skill(cron / github / memory / tmux)
|
||||
> 是模型按需调用、跑完就退出的工具,而 Gateway 客户端必须常驻 + 断线自动重连 + 秒级心跳,生命周期对不上;
|
||||
> nanobot 的常驻扩展点是 channel,所以内嵌接入就是一个 channel。别的 Agent 没有 channel 机制也没关系,
|
||||
> 它们只需要 `agenthub_client.py` + 一个 `on_task` 回调。
|
||||
>
|
||||
> **Agent 改不动、又拨不进去怎么办?** 用同一个客户端贴一份 SDK:拿
|
||||
> `agenthub_client.py` 起个小进程,或者干脆 import 进你自己的宿主进程。它不再是独立产品
|
||||
> (CLI / Dockerfile / 演示栈都删了),能力一点没少。
|
||||
|
||||
## 纳管 nanobot
|
||||
|
||||
nanobot 自带 OpenAI 兼容服务(`nanobot serve`),但它比通用 OpenAI 服务器严格。AgentHub 的
|
||||
`nanobot` driver / provider 按真实实现对齐,并且有一组互测直接跑上游 `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;`nanobot-docker` 产物按这个约定生成 |
|
||||
| 健康 | `GET /health` → `{"status":"ok"}`,**不鉴权** | probe 与在线状态走它 |
|
||||
| 模型 | `GET /v1/models` 只列出它自己配置的那一个;请求里的 `model` 不匹配就 400 | driver 先探测一次并缓存;探测不到就不传 `model` 字段。**hub 显示的模型一律由 Agent 自省上报**(心跳里的 `capabilities.model`),不在渠道配置里配 |
|
||||
| 消息 | `messages` 只允许**一条 user 消息**,多条直接 400(它自己维护会话) | 协作指令和队友上下文折叠进同一条 user 消息,prompt 放最后 |
|
||||
| 会话 | `session_id` 对应服务端会话 `api:<session_id>` | 任务的 `session_key` 原样传下去,同一轮协作复用 nanobot 自己的记忆 |
|
||||
|
||||
两条路指向同一个 nanobot,按「能不能改镜像 / 网络可不可达」二选一:
|
||||
|
||||
```bash
|
||||
# A. 外拨(推荐):装 agenthub 渠道,配置里只写 server + name + 凭证(见上一节)
|
||||
# 容器现成栈:cd deploy/nanobot-gateway && ./bootstrap.sh
|
||||
|
||||
# B. 直拨:hub 能访问到 nanobot serve 的端点
|
||||
curl -X POST http://127.0.0.1:8100/api/v1/agents -H "X-API-Key: $KEY" -H 'content-type: application/json' -d '{"name":"nanobot-1","driver":"nanobot","base_url":"http://127.0.0.1:8900/v1","auth":{"type":"bearer","token":"<api_key>"}}'
|
||||
```
|
||||
|
||||
两种写法的 `base_url` 用 `http://host:8900` 或 `http://host:8900/v1` 都可以。接完验一下:
|
||||
|
||||
```bash
|
||||
curl -H "X-API-Key: $KEY" http://127.0.0.1:8100/api/v1/agents/nanobot-1 # status / live / capabilities.models
|
||||
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:agenthub` 由 `deploy/Dockerfile.nanobot` 构建,
|
||||
渠道已经软链进安装树)。
|
||||
|
||||
```bash
|
||||
cd deploy/nanobot-gateway && ./bootstrap.sh # 两个容器、零桥接进程、零入站端口
|
||||
```
|
||||
|
||||
compose 里的 `AGENTHUB_SERVER`(旧名 `AGENTHUB_HUB_URL` 仍可读)取的是 hub 的对外地址:
|
||||
容器内要能访问到它,host 网络下保留 `127.0.0.1` 即可,macOS / Windows 换成
|
||||
`http://host.docker.internal:8100`,或和 hub 共用一个 compose 网络后用服务名 `http://hub:8100`。
|
||||
|
||||
### 真实 nanobot 互测(可选)
|
||||
|
||||
```bash
|
||||
cp -R soucecode/nanobot /tmp/nanobot-build
|
||||
uv venv .nanobot-venv
|
||||
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 包起一个临时 API 服务(只把 agent loop 换成假的,避免调用真大模型),跑完自动关。
|
||||
没有 nanobot 环境时整组自动 skip,不影响主测试套件;也可以
|
||||
`AGENTHUB_NANOBOT_PYTHON=/path/to/python` 指向任何能 `import nanobot` 的解释器。
|
||||
|
||||
## 顺着 WebUI 那条路接 nanobot(`nanobot_ws`)
|
||||
|
||||
`nanobot gateway` 自带一条 WebSocket 渠道(默认 `127.0.0.1:8765`),而 **nanobot 官方 WebUI 只是它的一个
|
||||
客户端**:一条 socket 多会话,派活是一个 `{"type":"message","chat_id":…,"content":…}` 信封,回复按
|
||||
`delta` / `stream_end` / `reasoning_delta` / `message(kind=tool_hint)` / `file_edit` / `turn_end`
|
||||
流回来(协议见 `soucecode/nanobot/docs/websocket.md`,帧形状见 `nanobot/webui/outbound_wire.py`)。
|
||||
`nanobot_ws` driver 复用的就是这条通道,没有第二套协议:hub 派活 = 发一个 `message`,
|
||||
Agent 的推理与工具调用原样变成任务事件流。
|
||||
|
||||
```bash
|
||||
# nanobot 侧不用改代码;要 token 就配 channels.websocket.token
|
||||
nanobot gateway # ws://127.0.0.1:8765/
|
||||
|
||||
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"},"model":"qwen3.6-plus"}'
|
||||
```
|
||||
|
||||
- `base_url` 写 `http://host:8900/v1`(nanobot serve 的写法)也认得,默认端口按 8765 推;路径不同给
|
||||
`config.path`,TLS / 反代给 `config.ws_url`(`wss://…`)。
|
||||
- **`session_key` 就是 nanobot 会话**:driver 把 hub 的 session_key 换成 `agenthub-<key>` 形态的
|
||||
`chat_id`(非法字符或超长则取哈希),同一个 key 永远落进 nanobot 的同一个 session,所以「工作台」里
|
||||
连续追问能续上上下文。
|
||||
- 轮次终点认 `turn_end`(带 usage / outcome),不是"一段时间没消息":多段回答、中间穿插工具调用都不会
|
||||
提前收尾;`outcome=failed` 会让任务失败并把 `failure_message` 带回来。
|
||||
- nanobot 的渠道协议**没有中止信封**,所以这个 driver 的 `cancel()` 老实返回 false:控制台取消会让任务
|
||||
停在 `cancelled`,但不会假装已打断 nanobot 那一轮(和 `nanobot` HTTP driver 一样)。
|
||||
|
||||
## Agent 类型与像素小人
|
||||
|
||||
Agent 行上有一个**类型**字段(`agent_type`),和 `driver`(怎么通信)、`deployment_kind`(跑在哪)是
|
||||
三个正交的维度。四个具名类型各自一套形象,办公室里的像素小人按它取配色和头饰:
|
||||
|
||||
| 类型 | 值 | 形象 | 典型 driver |
|
||||
| --- | --- | --- | --- |
|
||||
| nanobot | `nanobot` | 金色工装 + 头顶天线 | `nanobot`(HTTP)、`nanobot_ws`(WebSocket) |
|
||||
| DeepSeek Harness | `deepseek_harness` | 靛蓝工装 + 青色护目镜 | 内嵌插件(`connection_mode=embedded`) |
|
||||
| OpenClaw | `openclaw` | 钢蓝工装 + 鸭舌帽 | `openclaw`(gateway 帧 RPC) |
|
||||
| Hermes | `hermes` | 琥珀工装 + 羽翼头环 | 待接入(先占类型与形象) |
|
||||
| 其它 | `custom` | 沿用按 driver 取色的老规则 | `mock` / `openai_compatible` / … |
|
||||
|
||||
留空即"跟着 driver 走",换 driver 类型自动跟着变;显式选了某个类型就钉住不动。
|
||||
`GET /api/v1/agents?agent_type=hermes` 可按类型过滤。老库升级不用手工迁移:
|
||||
启动/`agenthub init` 时会自动 `ALTER TABLE agents ADD COLUMN agent_type`(见 `db/init_db.py` 的增量列
|
||||
清单),老行按 driver 解析出类型。
|
||||
|
||||
## 接入 DeepSeek Harness(`plugins/dsh-agenthub`)
|
||||
|
||||
DSH(`npx @deepseek-ai/dsh web`)是"一切皆插件"的 Agent Harness,所以接入方式是**给它写一个插件**,
|
||||
而不是让 hub 去理解它内部:插件与 DSH 同进程,往 hub 拨一条出站 socket,说的还是那套 Frame 协议。
|
||||
DSH 是「一切皆插件」的 Harness,所以接入方式是给它写一个插件,而不是让 hub 去理解它内部:
|
||||
插件与 DSH 同进程,往 hub 拨一条出站 socket。
|
||||
|
||||
```
|
||||
hub ◀── 出站 WS ── @nex/dsh-agenthub(DSH 插件,Host 半)
|
||||
|
|
@ -312,109 +246,207 @@ hub ◀── 出站 WS ── @nex/dsh-agenthub(DSH 插件,Host 半)
|
|||
```
|
||||
|
||||
```bash
|
||||
# 1) 装进 DSH profile(用 dsh 自己的命令;-w 因为 profile 目录是 pnpm workspace 根)
|
||||
dsh plugin --profile web add -w link:/Users/jiliu/WorkSpace/nex_agenthub/plugins/dsh-agenthub
|
||||
|
||||
# 2) 在 ~/.dsh/profiles/web/cordis.patch.yml 的顶层数组里 insert 一条(web profile 是 patchReload: live,存盘即生效):
|
||||
# - insert:
|
||||
# - id: dsh-agenthub
|
||||
# name: '@nex/dsh-agenthub'
|
||||
# config: { server: http://127.0.0.1:8100, name: dsh-web, agentToken: ag_xxxxxxxx }
|
||||
|
||||
# 3) 插件自带离线自检(打桩 hub + 伪 Cordis ctx,不需要 DSH 运行时,也不需要真 hub)
|
||||
# 装插件必须用 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
|
||||
```
|
||||
|
||||
插件注册出来的 Agent 是 `driver=deepseek_harness` + `connection_mode=embedded` + 类型
|
||||
**DeepSeek Harness**,在控制台里和别的 Agent 完全一样地派活、看流、取消。
|
||||
配置项、会话语义与排查表见 [`plugins/dsh-agenthub/README.md`](plugins/dsh-agenthub/README.md)。
|
||||
两个真机坑: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)
|
||||
|
||||
- **投递要走 `ctx.sessionController`**(WebUI 同一条路),不能直接把文本塞给 `ctx.agents.create()` 出来的
|
||||
agent:后者没人装模型选择,`{{model}}` 变量在提示词装配阶段就会报错。组合里没有
|
||||
sessionController 时插件会退回 `agents.create/resume` 并自己补上装配监听。
|
||||
- **插件自己的 HTTP 接口别用 `connection.rpc.handle()`**(注册时它会去访问调用方 context 的
|
||||
`webServer`,dsh 0.1.5 里从 `ctx.inject(['connection','webServer'], …)` 的子 context 调用照样抛
|
||||
`cannot get property "webServer" without inject`)。走 `ctx.connection.fetch.register()` 在
|
||||
`/api` 下挂精确路由:既有 Host/Origin + 浏览器鉴权围栏,也不需要 webServer。
|
||||
- **改插件代码要重启 `dsh web`**:patch 文件增删条目是热生效的,但模块本身被 Node ESM 缓存住了。
|
||||
- **热重载会把同一个 entry 应用两遍**(见插件 README 的「热重载」一节):插件自己按进程做了单例,
|
||||
新实例上手先停掉上一份,旧实例不会再占着 hub 的 channel。
|
||||
- 本机现役实例(`~/.dsh/profiles/web`)已经按上面接好:hub 里是 `dsh-web`,`deepseek_harness` /
|
||||
`embedded` / `online`,派活能跑完整一轮(status → reasoning → delta → completed)。
|
||||
不动 CLI 一行代码,在它所在机器上跑一个桥接进程(`bridge.py` 只需要 Python 3,不装任何依赖;
|
||||
旁边 `adapters/` 里一个 CLI 一个适配器,新增一家就加一个文件)。
|
||||
|
||||
## 目录结构
|
||||
|
||||
```
|
||||
backend/ FastAPI + SQLAlchemy(async) 控制面 + registry/gateway/tasks;CLI:agenthub
|
||||
frontend/ Next.js 16 + React 19 + Tailwind 4 控制台(沿用 AgentTown 的像素 HUD)
|
||||
deploy/ Dockerfile.backend / .console / .nanobot + docker-compose.yml
|
||||
nanobot-gateway/ nanobot 接入样例(2 容器、零桥接进程、零入站端口)
|
||||
cli-bridge/ 无头 CLI(codex / claude / WorkBuddy)的桥接进程 bridge.py
|
||||
plugins/ 可选插件包(如 DeepSeek Harness 的 dsh 插件),不进后端构建
|
||||
data/ 运行数据:agenthub.db + hub-credentials.json(已 .gitignore,默认位置与启动目录无关)
|
||||
docs/ PLAN.md(功能规划、API 契约、里程碑)+ AGENT_REGISTRATION.md(注册与身份规范)
|
||||
soucecode/ 参考实现:nanobot、agent-town
|
||||
```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` | ❌ 同左 |
|
||||
|
||||
顶栏右上角有 **暗 / 亮** 主题切换:默认暗色(AgentTown 的夜景像素 HUD),点一下换成白天的纸面 HUD。
|
||||
选择记在浏览器 `localStorage`,首帧由 `app/layout.tsx` 里的内联脚本按它写好 `data-theme`,所以刷新不会闪;
|
||||
办公室画布的房间配色(墙、地板、窗外天色、机柜、看板纸面)跟着同一个开关走,见 `lib/office-palette.ts`。
|
||||
参数:`--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 判定来源、最后一帧 |
|
||||
| 办公室 | 像素办公室(参照 Star-Office-UI):每个 Agent 一个工位,屏幕写正在跑的 prompt、人偶走位对应状态,墙上只有一块看板——左栏在岗状态、右栏任务队列(待办/在途/完成),右侧机柜有告警时闪红灯;**产出只出现在右边控制台,画面里不重复**;点工位选中后可直接下指令。画布按「显示宽度 × devicePixelRatio」渲染(拉宽/换 2x 屏都不糊),工位像素块边长由 `lib/office-layout.ts` 算出 |
|
||||
| 工作台 | 通用派活面板:左边是全部 Agent(本地/容器/远端一视同仁),右边是一条按 `session_key` 延续的对话——同一条 SSE 事件流,reasoning / 工具调用 / 产出都在里面,正在跑的还能取消 |
|
||||
| Agents | 注册表**只管管理**:列表筛选、逐行删除(注销登记)、派活、探活、凭证查看与轮换、详情。**没有登记入口** —— 建档与签发都在「接入」页 |
|
||||
| 任务 | 单 Agent 任务列表与流式事件(delta / reasoning / tool / log) |
|
||||
| 团队 | 成员与角色、Playbook、Run 时间线、共享黑板、Agent 间消息 |
|
||||
| 接入 | 顶部是在线通道数与 hub 地址(Agent 侧那一格 `server` 就抄它);**三步向导**:**① 选类型**(插件 / 渠道 · 桥接)→ **② 选是哪套 Agent**(渠道:DeepSeek Harness、nanobot、OpenClaw;桥接:codex / claude / WorkBuddy)→ **③ 生成凭证**(建档 + 当场签发 `ag_…`,片段里的凭证已是真值,贴过去之后这一行跟着 presence 变绿;签过的凭证点「查看凭证」随时读回,不必轮换) |
|
||||
| 设置 | Hub 与 Gateway 状态、控制台面 API 密钥管理、帧窗口、审计日志 |
|
||||
| 办公室 | 像素办公室:一 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`,刷新不闪。
|
||||
|
||||
- **尺寸只有两档**:`md` = 32px(页面/卡片的主操作、表单行),`sm` = 26px(工具条、表格行内动作、chip)。
|
||||
边框统一 2px、圆角 6px、字体 ArkPixel(11px / 10px)、焦点环统一 2px 金色;token 在
|
||||
`frontend/app/globals.css` 的 `--ctl-*`,所以同一行里的按钮、输入框、下拉、chip 永远一样高。
|
||||
- **页面只用原语**:`PixelButton / LinkButton / Input / Select / Textarea / SearchInput / Chip / Tabs /
|
||||
Field / Modal / Badge / Empty / ErrorNote / Spinner / KV / JsonBlock / CopyButton`(都在
|
||||
`frontend/components/ui.tsx`)。页面里不再出现 `className="pixel-input"` 这类裸类名,也没有裸 `<button>`。
|
||||
- **提示窗体只有两种**:要用户点头的用 `useConfirm()`(统一确认弹窗,危险动作默认焦点落在"取消",
|
||||
红色确认按钮);只报结果或失败的用 `useToast()`(右下角轻提示,错误停 8s、成功 3.2s,可手动关)。
|
||||
代码里**不允许**再出现 `window.confirm / window.alert / window.prompt` —— 这三种原生弹窗的样式、
|
||||
按钮文案和键盘行为都不受控制。
|
||||
- **弹窗外壳统一**:`size="sm|md|lg"`(420 / 640 / 920px),头部 8×12、主体 12、脚部 12 且动作右对齐
|
||||
—— 取消在左、危险动作居中、主操作最右。
|
||||
四种 Playbook:`sequential`(A→B→C)、`parallel`(并行后汇总)、`round_robin`(N 轮讨论)、
|
||||
`handoff`(Agent 输出交接块决定下一步交给谁)。Agent 侧零改造:hub 把 hub 地址、run id、
|
||||
短期 run grant、「你是这队伍里的哪一个」写进 prompt,Agent 想协作时按提示 curl 一下 `/collab/*` 即可。
|
||||
交给自己的交接块会被忽略并结束本次 Run,避免原地打转。
|
||||
|
||||
四种内置 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_` 前缀环境变量(也支持 `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_HUB_PUBLIC_URL` | 同监听地址 | 写进接入片段与协作 briefing 的对外地址 |
|
||||
| `AGENTHUB_DATA_DIR` | `<仓库根>/data` | SQLite 文件与 `hub-credentials.json` 位置;默认值锚定仓库位置,与启动目录无关 |
|
||||
| `AGENTHUB_DATABASE_URL` | 由 data_dir 推导 | 换库只改这里 |
|
||||
| `AGENTHUB_API_KEY` / `AGENTHUB_SECRET_KEY` | 自动生成 | 显式指定可省掉凭据文件 |
|
||||
| `AGENTHUB_AUTH_ENABLED` | `true` | `false`(配合 `AGENTHUB_DEV_DISABLE_AUTH`)仅供本地调试 |
|
||||
| `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` | `*` | 生产建议收敛到控制台域名 |
|
||||
|
||||
前端有两个**构建期**变量:`NEXT_PUBLIC_HUB_URL`(hub 地址,默认 `http://127.0.0.1:8100`)、
|
||||
`CSP_CONNECT_SRC`(hub 不在 localhost 时补充 CSP 的 connect-src)。
|
||||
Key 有两种 scope:`admin` / `read`。控制台面写操作和 `POST /deploy/plan {record:true}` 都要 admin。
|
||||
|
||||
## 换到 PostgreSQL / MySQL
|
||||
前端两个**构建期**变量:`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`。
|
||||
|
||||
模型只用了跨库安全的类型(JSON、String、DateTime + UTC),换库基本是改 URL:
|
||||
## 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]"
|
||||
|
|
@ -423,63 +455,80 @@ export AGENTHUB_DATABASE_URL="postgresql+asyncpg://hub:hub@127.0.0.1:5432/agenth
|
|||
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 + 控制台
|
||||
docker compose --profile managed-agent up -d --build # 再加一个示例被纳管 Agent
|
||||
docker compose up -d --build # hub + console
|
||||
docker compose exec hub cat /var/lib/agenthub/hub-credentials.json # 取 API Key
|
||||
```
|
||||
|
||||
容器里的 Agent 用 `AGENTHUB_HUB_URL: http://hub:8100` 连 hub;浏览器仍用
|
||||
`http://127.0.0.1:8100`(`AGENTHUB_HUB_PUBLIC_URL`)。
|
||||
`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 tests -q # 141 passed
|
||||
cd backend && .venv/bin/python -m pytest -q # 142 passed
|
||||
cd frontend && pnpm typecheck && pnpm lint && pnpm build
|
||||
```
|
||||
|
||||
后端测试里有几组是「契约级」的,改动这些行为时它们会拦住你:
|
||||
|
||||
| 测试 | 锁住的行为 |
|
||||
| --- | --- |
|
||||
| `test_db_portability.py` | 12 张表的建表/索引语句能在 sqlite / postgresql / mysql 三种方言下编译通过,类型、索引长度、约束命名都可移植(不需要装 asyncpg / aiomysql,纯编译验证) |
|
||||
| `test_gateway_ws.py` | 真实 WebSocket 帧格式:connector 派活、探活、**一次取消只下发一条 `task.cancel`**、控制台断线用 `?since=` 补发 |
|
||||
| `test_api_teams.py` | Run 取消会打断正在跑的 step(step 在创建任务时就绑定 task_id,否则取消只是改个状态) |
|
||||
| `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` | `agenthub init/doctor/status/token/agent add/agent rotate/config` 脱机可跑(不依赖 HTTP 服务) |
|
||||
| `test_interop_nanobot.py` | 对着真实 nanobot 包的 `create_app()` 跑,保证 driver/provider 没跑偏 |
|
||||
| `test_driver_nanobot_ws.py` | 用一个脚本化 nanobot WebSocket peer 锁住 WebUI 那条协议:`ready`→`message`→`delta`/`reasoning_delta`/`tool_hint`/`stream_end`/`turn_end`,以及 `session_key`→`chat_id` 映射 |
|
||||
| `test_driver_openclaw.py` | 用一个脚本化 gateway peer 锁住 OpenClaw 帧协议:`connect.challenge`→`connect`→`req/res`、流式 `agent` 事件、`chat` 终态、错误状态、`chat.abort` 取消 |
|
||||
| `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` 里覆盖,换网关版本不用改代码。
|
||||
|
||||
| driver | 状态 | 怎么验的 |
|
||||
| --- | --- | --- |
|
||||
| `connector` | 稳定 | 所有外拨接入件(embedded 也走它)的 hub 侧驱动;真实 WebSocket 帧见 `test_gateway_ws.py` |
|
||||
| `nanobot` | 稳定 | 上游真实包互测;单 user 消息、只认自己配的模型等约束都有断言 |
|
||||
| `nanobot_ws` | 稳定 | 直连 nanobot 网关自带的 WebSocket 渠道(就是 WebUI 用的那条协议);脚本化 peer 锁帧,见「顺着 WebUI 那条路接 nanobot」 |
|
||||
| `openai_compatible` | 稳定 | 假 OpenAI 服务(流式 / 错误 / 鉴权) |
|
||||
| `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.config.ts` 会按
|
||||
`NEXT_PUBLIC_HUB_URL` 自动加,改过 env 要重新 `pnpm build`);再确认右上角 API Key 是当前
|
||||
`data/hub-credentials.json` 里的那把——换过 data dir 后旧 key 只会让 WS 一直 403,页面显示「未配置 API Key」。
|
||||
|
||||
- **改了 `NEXT_PUBLIC_HUB_URL` 没生效**:它是构建期常量,`dev` 需要重启、`build` 需要重新构建。
|
||||
- **`pnpm start` 提示 standalone**:`next.config.ts` 用了 `output: "standalone"`,生产跑
|
||||
`node .next/standalone/server.js`(先 `pnpm build`)。
|
||||
- **Agent 连不上(外拨)**:看它自己的日志有没有 `dialing …` / `[agenthub] 已上线`;hub 侧看
|
||||
`GET /api/v1/gateway/status` 的 connections。凭证被轮换过就会 401/403 ——
|
||||
`agenthub agent rotate <name>` 重新签发,再把新那把填回 Agent 配置那一格。
|
||||
- **换目录启动后 Agent 全没了 / API Key 变了**:只有显式把 `AGENTHUB_DATA_DIR` 设成相对路径时才会
|
||||
发生——相对路径是相对当前工作目录解析的。默认值锚定在仓库根目录的 `data/`,
|
||||
`cd backend && agenthub serve` 和 `cd . && agenthub serve` 用的是同一个库。
|
||||
- **nanobot 回 400 `Only a single user message is supported` 或 `Only configured model ... is available`**:这个 Agent 走的是 `openai_compatible` driver(或 `openai` provider),带上了 system 消息或写死的模型名。换成 `nanobot` driver / provider:它把上下文折叠成一条 user 消息,并从 /v1/models 取模型。
|
||||
- **控制台一片 `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` 取模型。
|
||||
|
|
|
|||
Loading…
Reference in New Issue