agenthub/plugins/dsh-agenthub/README.md

15 KiB
Raw Permalink Blame History

@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(connector driver),不需要 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)

  1. 隔离实例: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。
  2. 本机现役实例:把插件 insert 进 ~/.dsh/profiles/web/cordis.patch.yml 后没有重启, 5 秒内 hub 里出现 dsh-web(deepseek_harness / embedded / online / live), 控制台可以直接派活。
  3. 加固后复测(隔离实例 DSH_HOME=/tmp/dsh-e2e3,真 hub + 真模型):冷启动派活通过; 连改三次 patch 文件,每次只有 1 个 agent.deregister + 1 个 agent.hello,进程到 hub 的 TCP 连接恒为 1,每次重载后派活都拿到 completed。
  4. 本机现役实例(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)。
  5. 身份即配置落地后(2026-09-25):server 字段生效、不再写 ~/.agenthub/agent-<name>.json (老文件被读一次并打印迁移片段);hub 里 dsh-web 的 model 变成自省上报的 deepseek-v4.1-flash-expires-on-0910(harness 默认模型),派活仍 completed。
  6. 只剩一条路之后(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 — 已废弃:老身份文件只被读一次(读到会打印可粘贴的迁移片段),不再写入