智能体委派桥 Zhucy123/dsh-delegation

简体中文 · English

dsh-delegation

让任意编码智能体把活派给本机的 DeepSeek Harness（DSH）：新建对话、持续追问、发截图、取回回答。

零依赖 · Node 18+ · 桌面端与 dsh web 都支持

快速开始 · 命令参考 · 库 API · 设计原理 · 故障排查

它是什么

DSH 没有官方的「从别的程序调我」API。但它的 UI 本身就是走 loopback 上 HTTP RPC 的客户端，所以这个工具直接调同一套 RPC —— 不用浏览器自动化，不用点界面，不用截图。

你的 agent ──► dsh_cli.mjs ──► HTTP RPC ──► DSH 宿主 ──► 一个真实的 DSH 对话（或 WebSocket，用于推送式取回）

因为对话落在真实的 DSH 工作区里，你可以在 DSH 侧边栏看着它、手动插话、事后接着聊，它不是一个藏起来的旁路通道。

为什么不是「起两次命令行」

因为对话有记忆。new 建一次会话，后续都用 send --session 发给同一个会话，上下文就完整保留 —— 「先看看这块代码，再改，再跑测试」这种多轮任务才做得像人做的。每次调用只返回最终回答，思维链和工具过程在协议层就被滤掉了。

特性

| 会话可持续 | new 之后反复 send 进同一个会话 |
| 端点自动发现 | 探测桌面端与 dsh web，并校验对面确实是 DSH |
| 推送式取回答 | 订阅事件流，turn/end 一到即返回（约 2 秒，不是轮询节奏） |
| 原生发图 | PNG / JPEG / WebP / GIF 作为真实内容块发送，模型真的看得见 |
| 插入 vs 排队 | --steer 注入当前轮；--queue（默认）排到下一轮 |
| 截断自动续写 | 撞到输出上限时自动续发「继续」并拼接片段 |
| 如实报告失败 | 能识别权限/审批受阻，报告而不是假装成功或盲目重试 |
| 零依赖 | 只用 Node 内置模块，手写了极简 WebSocket 客户端 |

依赖

- Node 18+（用全局 fetch）
- 一个在跑的 DSH：桌面端应用或 dsh web
- DSH 自己的凭据文件 ~/.dsh/.credentials.yaml

安装

方式一：把仓库地址丢给你的 AI，让它自己装

最省事的方式。复制下面这段，连同仓库地址一起发给你正在用的编码智能体（Codex / Claude Code / DSH 本身都行）：

帮我安装 https://github.com/Zhucy123/dsh-delegation

要求：
1. 先读仓库里的 README.md 和 SKILL.md，弄清它是什么、需要什么环境。
2. clone 到我的 agent skills 目录，Windows 上是 %USERPROFILE%\.codex\skills\dsh-delegation：
git clone https://github.com/Zhucy123/dsh-delegation "%USERPROFILE%\.codex\skills\dsh-delegation"
3. 确认 node 版本 >= 18（node --version）。
4. 跑自检并把它输出的内容贴给我：
node "%USERPROFILE%\.codex\skills\dsh-delegation\dsh_cli.mjs" doctor
5. 如果 doctor 报「找不到正在运行的 DSH 端点」，告诉我该开桌面端还是跑 dsh web，不要自己改用浏览器去操作 DSH 界面。
6. 不要修改仓库里的任何文件，也不用装任何 npm 依赖（它零依赖）。

方式二：手动装

Windows / Codex
git clone https://github.com/Zhucy123/dsh-delegation "$env:USERPROFILE\.codex\skills\dsh-delegation"
node "$env:USERPROFILE\.codex\skills\dsh-delegation\dsh_cli.mjs" doctor

macOS / Linux
git clone https://github.com/Zhucy123/dsh-delegation ~/.local/share/dsh-delegation
node ~/.local/share/dsh-delegation/dsh_cli.mjs doctor

也可以把目录放到任何位置，用绝对路径调用 —— 没有安装步骤，没有构建步骤。
SKILL.md 是给智能体读的行为规范；如果你的智能体支持技能，把整个目录放进它的技能目录即可。

快速开始

$cli = "$env:USERPROFILE\.codex\skills\dsh-delegation\dsh_cli.mjs"

node $cli doctor # 环境自检
node $cli new --cwd "C:\my-project" --prompt "讲讲这个构建脚本" --json
node $cli send --session <id> --prompt "现在优化它" --json
node $cli messages --session <id> --limit 20 # 把整段对话读回来

doctor 会打印端点、认证方式、工作区 id 和默认模型路由：

OK DSH 连接正常 origin : http://127.0.0.1:19387 （自动发现）认证方式 : persistent-secret 工作区 id : workspace-... 默认路由 : provider/model

命令行参考

| 子命令 | 作用 |
| doctor | 连通性、认证方式、工作区 id、默认模型路由 |
| new | 在指定工作区（--cwd）新建对话，可选地发第一条消息 |
| send | 往已有对话里发消息（--session） |
| status | DSH 现在是否在回答？决定插入还是排队 |
| messages | 读对话历史 |

| 参数 | 说明 |
| --cwd <绝对路径> | 决定会话归入哪个工作区（GUI 侧边栏可见的位置） |
| --prompt / --prompt-file | 消息内容（二选一） |
| --image <路径> | 附图片（可重复），原生发给模型 |
| --session <id> | 复用对话（send / status / messages 必需） |
| --steer / --queue | 插入当前轮 / 排到下一轮（默认 queue） |
| --no-wait | 只发不等，适合长任务 |
| --timeout-ms | 等待上限，默认 180000 |
| --max-continues <n> / --no-auto-continue | 截断自动续写上限，默认 3 |
| --poll | 强制轮询（默认推送式） |
| --progress | 增量文本实时写 stderr（stdout 保持干净） |
| --origin <URL> | 显式指定端点，跳过发现 |
| --limit <n> | messages 条数，默认 50 |
| --preset <名称> | 新建会话的 agent 预设 |
| --json | 结构化输出 |

返回结构：

{
"sessionId": "session-...", "workspaceId": "...",
"status": "done", "text": "最终回答", "turn": 3, "reason": { "kind": "completed" }, "elapsedMs": 1888, "via": "stream", "mode": "queue", "imageCount": 0, "continued": 0, "truncated": false }

permission / streamError 只在相应情况出现。按 status 分支（done / empty / timeout / sent），不要只看 text。

退出码：0 成功 · 2 认证/环境 · 3 参数或会话错误 · 4 回答为空 · 5 超时。

插入还是排队

DSH 正在回答（status 显示 running: true）时：

- 要打断 / 纠正 / 补充当前这件事 → --steer，下一个 step 边界生效
- 要另起一件不相关的事 → --queue（默认），等当前轮跑完

DSH 空闲时两者等价，用默认值即可。不要凭猜测 steer —— 猜错会破坏进行中的工作。

发图片

node $cli send --session <id> --prompt "这个姿势哪里不对" --image ".\shot.png"
node $cli send --session <id> --image ".\before.png" --image ".\after.png" --json

- 按 magic bytes 嗅探，不信扩展名：png / jpeg / webp / gif
- 单图 20 MB、单条 20 张、8192 px、6400 万像素
- 只发图不带文本也可以
- 模型必须支持视觉。这一点无法预检（Remote 面不暴露该能力）；DSH 会拒掉整条消息，工具据此给出带当前路由的可读报错。换模型后重发。

图已经在工作区、DSH 自己读得到时，在提示词里给路径更省 token（大图/多图尤其如此）。

库 API

命令行只是薄壳，自定义需求直接调库：

import {
connectDsh, createSession, sendPrompt, sendSmart,
readMessages, askWithAutoContinue,
} from './dsh_bridge.mjs'

const client = await connectDsh() // 自动发现 + 认证
const { sessionId } = await createSession(client, { cwd: 'D:\\proj' })

const reply = await sendPrompt(client, {
sessionId,
text: '你好',
onDelta: ({ text }) => process.stderr.write(text), // 可选：实时增量
})
// → { status, text, turn, seq, reason, elapsedMs, sessionId, via, mode, imageCount }

// 按忙碌状态自动选 steer / queue（preferSteer=true 时忙碌则插入） await sendSmart(client, { sessionId, text: '...', preferSteer: true })

// 截断感知：自动续写并拼接成完整回答js await askWithAutoContinue(client, { sessionId, text: '写一篇长文', maxContinues: 3 })

const history = await readMessages(client, { sessionId, limit: 50 })
// → [{ role, text, seq, time }]

底层订阅（自己决定何时结束）： js const handle = await followSession(client, { sessionId,
onEvent: (e) => { if (e.type === 'turn/end') handle.close() },
})

followSession 的 handle 必须 close()，否则连接挂着、进程不退出。
sendPrompt 内部已自动收尾。

环境变量

| 变量 | 作用 |
| DSH_BRIDGE_URL | 固定端点，如 http://127.0.0.1:19387（跳过发现） |
| DSH_COOKIE | 直接提供 dsh-auth- cookie，跳过解析 |
| DSH_BRIDGE_CACHE | 派生 cookie 的缓存位置 |
| DSH_BOOT_LOG | launch token 兜底用的 dsh-web-boot.log 路径 |

安全与隐私

- 只连 loopback，没有任何外部网络请求，不做遥测。
- 认证是读取 ~/.dsh/.credentials.yaml 后用 HMAC 在本地签一个会话 cookie ——密钥不上网，也只要求对该文件的读权限。
- cookie 缓存里只有派生出的 cookie，没有密钥本身。
- 凭据、cookie、token 一律不打印。
- 只会碰你用 --cwd 明确指定的那个 DSH 工作区。

故障排查

| 现象 | 处理 |
| 找不到正在运行的 DSH 端点（退出码 2） | 两个入口都没起来。开桌面端或跑 dsh web。 |
| 你自己终端能跑，在智能体里不行 | 智能体的沙箱封了 loopback（Codex 离线沙箱就有一条防火墙规则）。不是端口问题 —— 换允许网络的执行模式。 |
| doctor 退出码 2，提示认证 | DSH 没在跑，或 ~/.dsh/.credentials.yaml 不存在。 |
| 会话在 DSH 侧边栏看不到 | --cwd 不是已注册的工作区路径。用精确的绝对路径重跑 new。 |
| status: "timeout" | 任务太长：用 --no-wait + messages，或加大 --timeout-ms。 |
| 命令跑完进程不退出 | 有 followSession handle 没 close。 |
| 回答「不对」，像是上一轮的 | 先怀疑提示词有歧义，不是工具串轮。用自包含、无指代的提示词复验。 |

协议层细节（每条设计决定的原因、踩过的坑）见 docs/DESIGN.md。

测试 bash
node --test "tests/.test.mjs"

覆盖纯逻辑（图片嗅探、文本提取、权限受阻识别、截断判定），不需要 DSH 在跑。

许可证

MIT。