跨智能体任务派发 semantic-craft/dsh-grokbot-dispatch

dsh-grokbot-dispatch

DeepSeek Harness（DSH >=0.2.0-rc.2）官方 Cordis 插件，用于在 DSH 与其他智能体之间双向派发任务（Grok Bot、通过 zcode-dispatch 接入的 ZCode，或任何能对接下面这套小型 HTTP API 的东西）：进来的任务会变成 DSH 桌面端可见的会话，出去的 /dispatch- 命令把任务发出去，任务完成后会回报结果。

前置条件

- DSH >=0.2.0-rc.2（桌面应用用于显示可见会话；无头运行器需要 PATH 里有 dsh，或配置 dshBin），Node >=20。
- 项目文件夹放在 projectsRoot 下（默认 ~/Projects/<project>）；名字匹配 denyProjects（默认 finance）的会被拒绝。
- 调用方能通过网络访问 host:port（局域网、VPN、Tailscale、SSH 隧道……）。监听端是明文 HTTP：靠来源 IP 白名单加共享 Bearer key 保护，没有 TLS。请放在可信网络里，或者前面加一层 TLS 代理／隧道。
- 不需要：Yobiru / tailmsg、Tailscale、macOS / launchd。这些是可选项（见下表）。

功能 × 依赖

| 功能 | 默认（transport: "direct"） | 可选（transport: "yobiru"） |
| 入站：调用方 → POST /v1/jobs → DSH 会话 | key 文件 + host + allowedIps | 相同 |
| 拉取结果：GET /v1/jobs/<id> | ✅ | ✅ |
| 完成后推送结果 | callback_peer / callback_url → 向该 peer 发 HTTP POST（/v1/callbacks） | tailmsg request respond / send --reply-to |
| 出站 /dispatch-grok、/dispatch-zcode、POST /v1/outbound | peers.<name> 的 {url, keyFile} → peer 的 POST /v1/jobs | grokbotPeer / zcodePeer 的 Yobiru 地址 + tailmsg 命令行 |
| 主机／白名单自动发现 | 可选：装了 Tailscale 就跑 tailscale status --json | 相同 |
| 自动启动的兜底主机 | 可选（比如 macOS launchd；私有部署配置不在本仓库里——见你自己的部署文档／mesh） | 相同 |

最小可用配置（direct）

umask 077; mkdir -p ~/.config/dsh-grokbot-dispatch
openssl rand -hex 32 > ~/.config/dsh-grokbot-dispatch/key # callers send this as "Authorization: Bearer <key>"
key of each peer you dispatch to (the peer's own inbound key), e.g. zcode:
cp /path/from/zcode-host/key ~/.config/dsh-grokbot-dispatch/zcode.key; chmod 600 ~/.config/dsh-grokbot-dispatch/.key

~/.config/dsh-grokbot-dispatch/config.json：

{
"host": "192.168.1.20",
"port": 7790,
"allowedIps": ["192.168.1.30"],
"selfName": "dsh",
"peers": {
"zcode": { "url": "http://192.168.1.30:7791", "keyFile": "~/.config/dsh-grokbot-dispatch/zcode.key" }
}
}

然后 cd /tmp && dsh plugin --profile desktop add "link:$PWD/plugin"（从一份 checkout 里执行）。启动时插件会打一条兼容性检查日志（key 文件存在且 chmod 600、host/allowedIps 非空、projectsRoot 存在、能找到 dsh、transport 前置条件满足），GET /health 返回同样的内容，形如 {ok, transport, checks:{errors, warnings}}；不会静默失败。
需要把结果推回给你的对端，得把你写进它 peers 里的 selfName 下（或者发 callback_url，指向它已配置的某个对端）。callback_url 如果不以已配置对端的 url 开头，会被拒绝（不允许任意出站 POST）。

transport: "yobiru" 是可选的，只给已经在跑 Yobiru/tailmsg 的 mesh 用：加上 "transport": "yobiru"，再配上 grokbotPeer / zcodePeer（Yobiru 地址），可选再加 "yobiru": {"python", "script", "home", "path"}（默认值：从 PATH 取 python3、~/.tailmsg/tailmsg.py、~/.tailmsg、继承 PATH）。所有 tailmsg 调用都在 plugin/transport.js 里。

架构与官方 DSH 插件接口

- 官方 DSH Bundle 与元数据（plugin/package.json）：
- dsh.manifestVersion: 1、dsh.bundle.patch: "./cordis.patch.yml"、dsh.harnessRange: ">=0.2.0-rc.2"。
- 导出 .（./index.js）、./package.json，以及 ./locale/.json（plugin/locale/en.json、plugin/locale/zh-CN.json），这样 DSH 的 readPluginMeta（@deepseek-ai/dsh-app-boot）就能在 Desktop Plugin Inventory 里显示本地化的标题和描述。
- 主宿主 = DSH 桌面应用：
- 链接进 ~/.dsh/profiles/desktop/package.json（dependencies + dsh.profile.bundles）。
- 在 ctx.effect 里开一个 HTTP 监听，只绑定 host（取配置，或者装了 Tailscale 时取本机的 tailnet IP；host，默认端口 7790），并写入 ~/.local/state/dsh-grokbot-dispatch/primary.pid。
- 备用宿主（无头 runner）：
- 可选。示例（macOS launchd；私有部署模板不在这个公开仓库里）：独立配置档 grokbot-dispatch，带 DISPATCH_STANDBY=1 DISPATCH_RUNNER=headless。桌面应用占着 7790 时它安静等待；应用一关，它就接管端口，用 dsh --profile headless --json 跑任务；应用回来且它空闲时，它让出端口。
- 可见会话（应用 runner）：
- 每个进来的任务都会在 DSH 桌面应用左侧面板里，对应项目下建一个可见会话，标题里嵌 [Job: <16-hex>]（[Grok Bot] [Job: <id>] <task…> 或 [Yobiru] [Job: <id>] <task…>）：
workspaceController.create({path}) → sessionController.create({workspaceId}) → permissionPresets.set(agents.get(id).session, mode) → sessionController.rename({sessionId, title}) → sessionController.follow({address:{kind:'session',sessionId}}, signal) → sessionController.prompt({requestId: job.id, sessionId, mode:'queue', content:[{type:'text', text}]}, signal)。
- 出站斜杠命令（plugin/commands.js）：
- 通过 DSH 官方的 ctx.commands.register（@deepseek-ai/dsh-commands）注册：
- /dispatch-grok <project> <task…> —— 校验 <projectsRoot>/<project>（denyProjects 里的拒绝），把 [Project: <project>] <task…> 发给对端 grok-bot（直连：POST <url>/v1/jobs；yobiru：tailmsg.py request send <grokbotPeer> --as dsh --wake now），并记录 sessionId <-> jobId 映射。
- /dispatch-zcode <project> <task…> — 用同样的方式派发给对端 zcode，并记录映射关系。
- /dispatch-status [job-id] — 查看活跃任务和最近的 sessionId <-> jobId 映射。

- 持久化 sessionId <-> jobId 映射与自动上报（plugin/job-map.js、plugin/hooks/）：
- JobMapStore 把 byJob 和 bySession 映射持久化到 ~/.local/state/dsh-grokbot-dispatch/job-map.json（权限 0600，原子重命名）。
- 如果创建或继续会话时，标题或提示词里带有 [Job: <16-hex>] 或 [Yobiru-ID: <16-hex>]，resolveForSession 会自动绑定 sessionId <-> jobId。
- 一轮结束时（runAppJob 完成、Cordis session/event 的 turn/end、agent/turn-stopping，或 Claude-Code 钩子桥 plugin/hooks/hooks.json → plugin/hooks/stop-report.mjs），reportJob 会幂等地推送结构化载荷 dsh-job-report-v1，走传输层（direct：向 callback_url 或 <peers[callback_peer].url>/v1/callbacks POST JSON；yobiru：tailmsg.py request respond <id> <payload> --state <completed|failed> + ack <id>，或 tailmsg.py send <callback_peer> <payload> --as dsh --reply-to <jobId> --wake now）。跨进程由独占的 <jobId>.report.lock 预留保护（发送失败则释放以便重试；超过 10 分钟未释放则接管），进程内由 Map 保护。
- 上报路由策略：只有 Grok Bot 派发的任务（source: "grok-bot" / "grok"）才回退到 grokbotPeer；source: "yobiru" 的请求只通过 request respond 回复给请求方。来自 zcode、dsh 或本地/手动会话的任务，绝不回退或上报给 Grok：如果显式提供了 callback_peer，指向它们的非 Grok 来源（例如 ZCode），上报就发往该来源；否则不发送 Yobiru 回调，结果只持久化到本地磁盘。

配置（代码里不含主机、IP 或用户路径）

每项设置都按 环境变量 > ~/.config/dsh-grokbot-dispatch/config.json > tailscale 发现（若已安装）> 默认值 的顺序解析（plugin/config.js、plugin/transport.js）：

| 设置 | 环境变量 | config.json | 未设置时的发现结果 |
| 绑定主机 | DISPATCH_HOST | host | 本节点的 tailnet IPv4（tailscale status --json）；绝不用 0.0.0.0 —— 若解析不出任何值，监听器保持关闭 |
| 端口 | DISPATCH_PORT | port | 7790 |
| Grok Bot 对端 | GROKBOT_PEER | grokbotPeer | 无 —— 未设置前，出站 /dispatch-grok 和 Grok 上报保持禁用 |
| ZCode 对端 | ZCODE_PEER | zcodePeer | 本节点的 MagicDNS 名称 + /zcode |
| 允许的来源 IP | DISPATCH_ALLOWED_IPS（逗号分隔列表） | allowedIps | grokbotPeer 节点的 tailnet IP（会跟随机器重新登录后的 IP 变化） |
| 传输 | DISPATCH_TRANSPORT | transport | direct |
| direct 对端 | — | peers {name: {url, keyFile}} | 无 |
| 回调时我们自己的名称 | — | selfName | dsh |
| 显式回调 URL | — | callbackUrl | 无（发送 callback_peer: selfName） |
| dsh 二进制 | DSH_BIN | dshBin | PATH 上的 dsh |
| 项目根目录 / 拒绝列表 | DISPATCH_PROJECTS_ROOT | projectsRoot / denyProjects（正则） | ~/Projects / finance |
| Yobiru 命令行（仅 yobiru） | TAILMSG_PYTHON / TAILMSG_SCRIPT / TAILMSG_HOME | yobiru.python / .script / .home / .path | python3 / ~/.tailmsg/tailmsg.py / ~/.tailmsg / 继承的 PATH |

用 DSH_DISPATCH_CONFIG=<file> 指向另一个文件，用 DSH_DISPATCH_DISCOVERY=0 关闭发现，如果命令行不在 PATH 上，用 TAILSCALE_BIN。

非公开 Host 接口与升级说明

- 用到的官方接口：package.json（dsh.manifestVersion、dsh.bundle.patch、dsh.harnessRange、exports["./locale/.json"]）、ctx.effect、ctx.commands.register，以及 Claude-Code 钩子格式（plugin/hooks/hooks.json）。
- 用到的 Host 内部服务（DSH 0.2.0-rc.2 没有公开 SDK 能替代进程内可见会话创建）：
- ctx.get('workspaceController')、ctx.get('sessionController')、ctx.get('permissionPresets')、ctx.get('agents')，以及 Cordis 事件 session/event / agent/turn-stopping。
- 如果未来的 DSH 版本改了这些服务的签名，pickRunner / getServices 会降级，也可以用 DISPATCH_RUNNER=headless 强制走命令行回退。

API

| 路由 | 请求体 / 结果 |
| GET /health | {ok, running, runner, transport, checks:{errors,warnings}, uptime_s}（仅 IP 检查） |
| POST /v1/jobs | {project, text, timeout_seconds?, permission_mode?, source?: "grok-bot"\|"yobiru"\|"zcode"\|"dsh", job_id?, yobiru_id?, callback_peer?, callback_url?, report_via_yobiru?} → 202 {id, runner:"app"\|"headless", state:"running", ...} |
| GET /v1/jobs/<id> | {state: running/completed/failed, runner, session_id, title, tools, result, error, reported?, report_method?, ...} |
| POST /v1/callbacks | 对端推来 dsh-job-report-v1 / {job_id, state, result, error}，对应我们发给它的任务 → 存到出站 job-map 条目上（见 /dispatch-status <id>） |
| POST /v1/outbound | {target: <peer name>, project, task, session_id?} → 202 {ok, jobId, target, peer, sessionId, ...} |
| GET /v1/job-map | {entries: [...]} |

Shell 客户端（任何有 curl 的机器）：DSH_DISPATCH_URL=http://host:7790 DSH_DISPATCH_KEY=... client/dsh-dispatch.sh send myproj "[Project: myproj] ..."，然后 client/dsh-dispatch.sh wait <id>。

安装 / 运维

见上文 Minimal working config。私有部署配置（Yobiru 传输、launchd 回退主机、自检）不在本仓库里 —— 见你自己的部署文档 / mesh。

可靠性、日志、自检

- 自动启动 / 重启（可选的 launchd 示例）：智能体带 RunAtLoad 和 KeepAlive（ThrottleInterval 30 s）。
- 休眠 / tailnet 断开：supervise 每 30 秒重试一次 bind 错误，并每 30 秒对 <host>:<port> 做一次 TCP 探测。在主（桌面）主机上，它从不调用 process.exit，并会重置 downSince，因此在长时间休眠期间会持续重新绑定。
- 日志（~/.local/state/dsh-grokbot-dispatch/logs/）：dispatch.log（达到 2 MB 时轮转，保留 5 份）和 launchd.log。
- 自检：GET /health（兼容性检查）；可选的本地自检脚本（未包含在这个公开仓库中）可以打印 launchd 状态、/health、最近的日志事件和最近的作业。