15 KiB
@nex/dsh-agenthub — 把 DeepSeek Harness 接进 AgentHub
一个 DSH 插件(dsh-plugin),让 dsh(DeepSeek Harness)作为可被纳管的 Agent 出现在
AgentHub 控制台里:能派活、能看到 delta / reasoning / 工具调用事件、能取消。
用的是同一条接入网关——deploy/nanobot-gateway/channel/agenthub/agenthub_client.py 说的那套
Frame 协议,所以 DSH、nanobot 渠道、cli-bridge 桥接进程在 hub 眼里是同一类东西:
Agent 往外拨一条 WebSocket,hub 不保存 Agent 的密钥,也没有任何入站端口。
AgentHub hub ◀── 出站 WS + Frame 协议 ── @nex/dsh-agenthub (Host 半)
│ │
├ task.run ─────────────────────────────────▶ agent.followup(createUserMessage)
◀─ agent.event(delta|reasoning|tool|status) ── agent/assistant-stream + session/event
◀─ res{ok,text} ────────────────────────────── turn/end
└ task.cancel ───────────────────────────────▶ agent.cancel({kind:'user'})
装到 DSH profile 里
最省事的路:hub 控制台「接入」页选 DeepSeek Harness → 填 profile 名 → 点「签发凭证」。
页面上直接给出下面这四步(带这台机器的绝对路径)和一段已填好真值的 cordis.patch.yml 片段,
照抄即可。下面是同样四步的手写版 —— 每一步都是真机上撞过的,跳过任何一步都会「注册不上来」:
# 0) 在 hub 上为这台 DSH 建档签发一个 ag_ 凭证(控制台「接入」页)。它是身份,长期有效。
# 1) 建 profile —— 模板必须是 web。
# profile 不存在时 `dsh plugin add` 也会顺手建一个,但那个默认只有 dsh-base:
# 它是「答一条任务就退出」的一次性进程,没有常驻进程去拨 hub,于是 hub 永远等不到它。
dsh --profile web --from-default-profile web --dump-config # 已经建过就跳过
# 2) 装插件(用 dsh 自己的命令,别手改 profile 的 package.json;-w:profile 是 pnpm workspace 根)
dsh plugin --profile web add -w link:/Users/jiliu/WorkSpace/nex_agenthub/plugins/dsh-agenthub
然后编辑 ~/.dsh/profiles/web/cordis.patch.yml:先把文件里那行占位的 [] 删掉,
再把这段接到末尾([] 和 insert 列表是两个根节点,接在 [] 后面 YAML 直接报
document separator is expected,整个 profile 起不来):
# ~/.dsh/profiles/web/cordis.patch.yml(示意:insert 列表可以有多项)
- insert:
- id: dsh-agenthub
name: '@nex/dsh-agenthub'
config:
server: http://127.0.0.1:8100 # hub 的 IP + 端口
name: dsh-1
displayName: DSH 开发机
emoji: 🧭
# 这台 Agent 的身份凭证:hub 控制台「接入」页签发,长期有效
agentToken: ag_xxxxxxxx # 只有这一格就够;hub 从 token 反查 agent_id
# 3) 起进程(不想开浏览器加 --no-open,换端口加 --port 3399)
dsh --profile web --no-open
# 日志出现 [@nex/dsh-agenthub] dialing http://127.0.0.1:8100 as "dsh-1" 就是在拨 hub 了;
# 回 hub 的 Agents 页应看到它 online —— 那一步就是注册验证(WS 建好即凭证有效)。
第一次派活若报
no API key for provider route:接入链路已经通了,缺的是模型凭证 —— 在这个 DSH 的 web 界面 Settings → Models 存 key(或起进程前export DEEPSEEK_API_KEY=…)。
改插件代码要重启
dsh。 改cordis.patch.yml是热生效的(web profile 是patchReload: live,增删条目即可上/下线),但插件模块本身被 Node 的 ESM 缓存住了, 同进程内不会重新求值。所以「装/卸插件」不用重启,「更新插件版本」要重启一次。
配置也可以全部走环境变量(插件 config 优先级更高):
AGENTHUB_SERVER / AGENTHUB_AGENT_TOKEN / AGENTHUB_AGENT_ID / AGENTHUB_NAME /
AGENTHUB_DISPLAY_NAME / AGENTHUB_DEPLOYMENT_KIND / AGENTHUB_WORKSPACE /
AGENTHUB_TASK_TIMEOUT_S。
老配置里如果还留着
enrollment/hubId/takeOver,插件加载时会明确报一行「已取消」, 不会默默忽略 —— 接入只剩「hub 地址 +ag_凭证」一条路。
它在 hub 里长什么样
注册时自报 driver=deepseek_harness、connection_mode=embedded、deployment_kind=local
(可用 config.deploymentKind 改成 docker/cloud),于是:
- 控制台「Agent 类型」一栏是 DeepSeek Harness,办公室里的像素小人戴青色护目镜;
- 派活走 Gateway 的出站 socket(
connectordriver),不需要 hub 能拨进 DSH; - 过程事件和别家 Agent 一样落在任务事件流里:
status/reasoning/delta/tool/completed。
会话与记忆
hub 上一次对话 = 一个 session_key(控制台默认 console-<agent name>)。插件把它哈希成稳定的
DSH sessionId,交给 ctx.sessionController.create({ sessionId, cwd }):它就是 WebUI 的入口,
会「有就认领、没有就新建」,顺带把这个会话的 agent preset 与模型选择装好——
所以同一段对话跨 DSH 重启后还能接着聊,不同 session_key 之间互不串味。
为什么非走 sessionController? 直接
ctx.agents.create()也能开出会话,但模型选择没人装, 系统提示词里的{{model}}变量会在装配阶段直接报prompt variable "{{model}}" has no value for this assembly。 这是本插件在真机上踩过的坑:派活不是「把文本塞给 agent」,而是「走应用同一条投递路径」。 好处是一并拿到取消(sessionController.cancel)、冷会话 resume、附件准入这些策略。 组合里没有 sessionController(例如 headless/sdk profile)时插件会退回agents.create/resume并自己装system-prompt/assemble+agent/request两个监听补上模型选择。
投递用 sessionController.prompt({requestId, sessionId, mode:'queue', content})(轮次上限之外还要求
一个 AbortSignal,插件每轮带一个)。连发两个任务不会互相打断:DSH 的 inbox 本来就会排队,
第二个在这一轮结束后自动开始。
面板(Client 半)
lib/client.js 是浏览器 bundle,在 设置 → AgentHub 里注册一个 section。它有两个状态:
未上线 —— 填「地址 + 这台 Agent 的凭证」点「上线」,和桥接进程 --token、nanobot 的 agent_token
是同一件事:
| 字段 | 例子 | 从哪来 |
|---|---|---|
| Hub 服务器地址 | http://127.0.0.1 |
你跑 hub 的地址 |
| 端口 | 8100 |
hub 监听端口 |
| 这台 Agent 的凭证 | ag_1kfPGGeO… |
hub 控制台「接入」页签发 |
| 名字(可选) | dsh-1 |
hub 上的唯一名;留空用插件 config 里的名字 |
点「上线」→ 插件直接拿 ag_ 凭证拨 WebSocket → hub 里立刻出现这台 DSH,凭证只在内存。
地址和名字会存到 ~/.dsh/agenthub.json(不含凭证),下次启动自动上线;点「下线」断开但保留配置。
面板不再问 Hub ID。 hub 的 id 不是 Agent 的凭证,Agent 侧只需要「地址 +
ag_」。 粘错格子会被当场拦下并指路:粘ah_→ 那是 hub 的 API Key,只有控制台和管理 API 用; 粘enr_/hub_→ 已取消的旧机制,回「接入」页签发ag_。
已上线 —— 显示 hub 地址 / agent_id / 名字 / 在跑数量 / 凭证来源和最近被派的活,
8 秒自动刷一次。想换身份,改插件 config 即可(config 优先级高于面板)。
凭证来源只有三种:插件 config(写了 agentToken)、面板里填的(只在内存)、
老身份文件(迁移期兜底,看到就该挪进 config 后删掉)。
它取数走的是 POST /api/agenthub/status(同源 fetch,带 dsh 自己的会话 cookie),这条路由由
Host 半用 ctx.connection.fetch.register() 挂在 /api 共享通道上 —— 在 Host/Origin 与浏览器鉴权
围栏之内(无凭证直接 401),也就是 dsh 自己的 client-file-upload / api-session-controller 用的那条路。
别用
connection.rpc.handle('/agenthub', …)。 它在注册时会去访问调用方 context 的webServer: dsh 0.1.5 里即使从ctx.inject(['connection','webServer'], …)的子 context 调用,仍然抛cannot get property "webServer" without inject(错误会被 cordis 吞掉,表现为路由根本没挂上、 POST 打到静态 fallback 拿 405)。/api下的精确 Fetch 路由不需要 webServer。
热重载:一个进程只留一份网关
DSH 的 web profile 是 patchReload: live,改 cordis.patch.yml 存盘即生效。但改一次会把这个
entry 应用两遍:真机实测(hub 帧审计)每存一次 patch 文件,会看到一个 agent.deregister 加
两个 agent.hello,也就是同一进程里起了两份网关、各拨一条 socket。
两份实例抢同一个 hub channel 的后果很隐蔽:被取代的那份如果还挂着通道,派进来的任务会落到一个
已经被 dispose 的 context 上,报 cannot get required service "agents" in inactive context。
所以插件在模块层做了单例(LIVE.gateway):新实例上手先 stop() 上一份,自己再登记为唯一在册的
那份;stop() 本身也是终态(清心跳、清退避定时器、关 socket),被取代的实例既不会再重连,
也不会再吃任务(会明确回一条「已被热重载取代」而不是那个谜之 inactive context)。
修完再测:每存一次 patch 文件只有一个 agent.deregister + 一个 agent.hello,进程到 hub 的 TCP
连接数稳定在 1,连存三次后派活依旧正常。
排查
| 现象 | 看哪里 |
|---|---|
| 控制台看不到这个 Agent | DSH 日志里有没有 [agenthub] 已上线 / [agenthub] 没连上:<原因>;先看 config 里的 agentToken 是不是这个 hub 签的那份(换过 hub / 轮换过凭证都会让旧的失效) |
| 只连上收不到活 | hub「Agents」页的 connection_mode 是否为 embedded/connector,live 是否为真 |
派活后立刻失败 session/model-unavailable |
这个 DSH 实例没配默认模型:Settings → Models 里选一个 |
派活报 ... in inactive context |
进程里有多份网关抢通道:确认插件是当前版本(单例 + 终态 stop),然后重启一次 dsh web |
| 设置 → AgentHub 面板读不到数据 | DSH 日志里有没有 面板 RPC /api/agenthub/status 已挂载;curl -X POST /api/agenthub/status 带 cookie 应为 200、不带应为 401 |
| 想从模型侧自查 | 让 DSH 调 agenthub_status 工具,或看「设置 → AgentHub」面板 |
自检(不需要 DSH 运行时)
node plugins/dsh-agenthub/selfcheck.mjs
它用一个打桩的 hub(假 fetch + 假 WebSocket)和伪 Cordis ctx 跑通全链路:
注册 → hub.hello → agent.hello → task.run → agent.followup →
assistant-stream/tool/turn/end → agent.event 帧 → res{ok,text} → task.cancel → 卸载清理。
另外还覆盖:热重载只留一份网关(旧实例让位、不吃任务)、无 sessionController 的回退路径、
客户端 bundle 能在伪 ModuleLoader 下加载并打对接口。帧格式或接线一旦跑偏,这里就红。
真机验证记录(2026-09-24)
- 隔离实例:
DSH_HOME=/tmp/dsh-agenthub-e2e dsh --profile web --port 3095+ 本机假 OpenAI 端点, hub 侧派活拿到完整一轮:status → delta × 3 → completed,答案文本回到任务里;agent.describe返回{runtime: deepseek-harness, streaming, reasoning, tools, sessions, workspace},agent.ping回 rtt。 - 本机现役实例:把插件 insert 进
~/.dsh/profiles/web/cordis.patch.yml后没有重启, 5 秒内 hub 里出现dsh-web(deepseek_harness/embedded/online/live), 控制台可以直接派活。 - 加固后复测(隔离实例
DSH_HOME=/tmp/dsh-e2e3,真 hub + 真模型):冷启动派活通过; 连改三次 patch 文件,每次只有 1 个agent.deregister+ 1 个agent.hello,进程到 hub 的 TCP 连接恒为 1,每次重载后派活都拿到completed。 - 本机现役实例(
dsh-web,真模型):重启加载新代码后,hub 侧派活completed, 任务事件流完整(53 条:status→reasoning× 43 →delta× 6 →completed);POST /api/agenthub/status带会话 cookie 返回连接快照(200),不带凭证 401;/plugins/??@nex/dsh-agenthub/client.js正常下发(200)。 - 身份即配置落地后(2026-09-25):
server字段生效、不再写~/.agenthub/agent-<name>.json(老文件被读一次并打印迁移片段);hub 里dsh-web的model变成自省上报的deepseek-v4.1-flash-expires-on-0910(harness 默认模型),派活仍completed。 - 只剩一条路之后(2026-10-14):新建隔离 profile,
config里只有server+agentToken,dsh --profile hub-e2e --port 3399起来后 hub 里dsh-e2e变online/live, 派活completed(答案原样回到任务result);旧的register/join/enrollment路由在 hub 侧全 404。 顺带修掉一个真机撞出来的 bug:只配agentToken时,~/.agenthub/agent-<name>.json里上一世的agent_id会被拼到新凭证上导致 401 —— 现在 config 里有凭证就完全不读老文件。
配置项
| 字段 | 默认 | 说明 |
|---|---|---|
server |
http://127.0.0.1:8100 |
hub 地址(也认 env AGENTHUB_SERVER;旧名 hubUrl / AGENTHUB_HUB_URL 兼容读) |
agentToken |
— | 日常只填这个:这台 Agent 的身份(ag_…,控制台「接入」页签发,env AGENTHUB_AGENT_TOKEN)。优先级最高,不落盘 |
agentId |
— | 可省:hub 从 token 反查。填了只是让日志/帧里的 agent_id 更好读(env AGENTHUB_AGENT_ID) |
name / displayName |
dsh |
hub 上的 Agent 名(唯一)与显示名 |
deploymentKind |
local |
local / docker / cloud,只影响控制台展示 |
provider / model |
空 | 回退路径(没有 sessionController)时的模型;留空取 harness 默认模型 |
cwd |
进程 cwd | 新会话的工作目录(env AGENTHUB_WORKSPACE) |
timeoutS |
900 |
一轮 turn 的超时,超时即取消该轮 |
statePath |
— | 已废弃:老身份文件只被读一次(读到会打印可粘贴的迁移片段),不再写入 |