AI 客户端桥接 ganmayou2333/dsh-ai-bridge

dsh-ai-bridge

把外部 AI 客户端和本机 DeepSeek Harness（DSH）接起来的两件小工具，零依赖，不动 DSH 本体。

两件零依赖工具，把外部 AI 客户端和本机 DeepSeek Harness（DSH）接起来：一个 MCP server，让任何支持 MCP 的客户端把消息发进 DSH；一个 CDP 驱动，把任务下发进豆包桌面版。

外部 AI 客户端 ──MCP──▶ dsh-mcp-connector ──▶ dsh --profile headless ──▶ DSH (Claude Code / Cursor / VS Code / Codex / Kimi Code / CodeBuddy / Qoder / TRAE / ZCode / Step Code / MiniMax Code / Coze …)

DSH / 脚本 / HTTP ──入队──▶ tasks.jsonl ──task_claim──▶ 任意 MCP 客户端（拉取式任务队列）

脚本 / DSH ──CDP──▶ doubao-cdp ──▶ 豆包桌面版（把任务下发进它的聊天框）

为什么需要它

DSH 随发行体只带了 MCP 客户端（dsh-mcp-client），没有 MCP server 半区；它的 Web API 又需要浏览器 cookie 与 Host/Origin 围栏，第三方程序难以直接持有。所以「让别的 AI 给 DSH 发消息」必须有一个独立桥——这就是本仓库的第一个工具。

反方向（把任务下发给别家 AI）没有任何官方入站 API，只能走 GUI 自动化——这是第二个工具。

而 MCP 工具只在客户端自己的回合里执行，推送不进去；所以真正能自动化的派活方式是拉取：生产者入队，客户端领取。这部分已经做进第一个工具（task_claim / task_complete / task_publish / task_list + POST /tasks）。

目录

| 路径 | 作用 |
| dsh-mcp-connector/ | MCP server（stdio + Streamable HTTP 双传输），暴露 dsh_ask / dsh_cli_info / connector_status 与四个任务队列工具，驱动 dsh --profile headless |
| doubao-cdp/ | 用 Chrome DevTools Protocol 驱动豆包桌面版（Electron）：cdp.mjs 下发并读回，dispatch.mjs 带副作用校验的派发（拒绝相信客户端的自述） |
| skills/dsh-mcp-connector/ | 给 AI agent 用的技能包：17 个 MCP 客户端的配置矩阵、陷阱表、以及「未证实项」清单 |
| docs/design-notes.md | 设计说明：为什么必须有独立的桥、DSH 的五个机器入口面、队列为何是拉取式、两个方向的合规结论、已知失败模式 |
| scripts/register.mjs | 注册助手：把连接器写进各 MCP 客户端的配置文件，不用手抄 JSON/TOML |

各自的使用方法见对应 README。

快速开始

git clone https://github.com/ganmayou2333/dsh-ai-bridge
cd dsh-ai-bridge

npm test # 两套密封测试：不需要 DSH，也不需要豆包

cd dsh-mcp-connector
node selftest.mjs # 完整自测（多跑两项需要本机 DSH 的检查）

然后在你的 MCP 客户端里加一条 stdio server：命令: node 参数: <你的路径>/dsh-ai-bridge/dsh-mcp-connector/server.mjs 环境: DSH_BIN=<dsh 可执行文件> DSH_WORKSPACE=<DSH 会话工作目录> 逐客户端配置见 dsh-mcp-connector/README.md

用注册助手代替手抄配置

node scripts/register.mjs --list # 看每个客户端的配置文件位置与注册状态
node scripts/register.mjs --client cursor --dry-run # 只打印将要写入的内容，不落盘
node scripts/register.mjs --client vscode # 写入（已存在的文件会先备份成 .bak）
node scripts/register.mjs --client all --dry-run # 一次看全部

支持的客户端与各自的坑都编码在里面（ZCode 的 mcp.servers、Step Code 的 TOML、CodeBuddy/MiniMax 必须显式 type: stdio、VS Code 的 servers）。claude-code 是 CLI 管理的，脚本不写文件，只打印该运行的 claude mcp add 命令。

写入前建议先 --dry-run 看一眼；测试用 --root/--project 重定向到临时目录，不会碰你的真实配置。

要求：Node ≥ 20（本机用 v24 验证）、一个可用的 DSH 安装（dsh 命令）。

验证状态

| 项 | 证据 |
| dsh-mcp-connector 自测 | 61 项断言全过，退出码 0（密封 DSH_HOME 下 headless profile 首次初始化、stdio 往返、HTTP 鉴权 401/403/404/405/202、生产者路由 201、队列语义与 6 路并发领取无碰撞、自观测与流水线握手闸门） |
| 离线自测（CI 用） | 58 项通过 / 2 项跳过，退出码 0；跳过的两项需要本机装好 DSH。工作流见 .github/workflows/ci.yml，矩阵为 Ubuntu/Windows × Node 20/24 |
| 真实模型调用 | 一条消息 3.7 秒返回，拿到 sessionId；带该 id 再发一条成功续接同一会话 |
| 真实 MCP 客户端握手 | Claude Code 2.1.226 完成握手并协商到协议 2025-11-25，证据是连接器自己记录的 clients.json（该客户端当时未登录，故工具调用未执行） |
| doubao-cdp 真实往返 | 连续 3 次下发-回传成功，最后一次为 send + wait 单次调用完成 |
| dispatch.mjs 校验逻辑 | 成功路径（队列完成 → 退出 0 VERIFIED）与失败路径（客户端嘴上说做了、队列仍 pending → 退出 2 UNVERIFIED）双向实测；密封测试 15 项断言全过（含发送前预检），不需要豆包与 CDP |
| 豆包启动确认 | 14 项断言全过：端口关闭 / 端口通但无匹配页面 / 就绪 / --no-preflight 逃生门 四种状态，外加「确认失败不得留下孤儿任务」。用假 CDP 端点密封测，不需要豆包 |
| 状态回报 | 28 项断言全过：固定词表与别名、ini 开关、被关掉的状态静默 no-op、限流（关键状态永不丢）、截断、终态不可覆盖、崩溃半行、时间线排序、忙闲与疑似卡死 |
| 调用前五维识别 | 23 项断言全过：连通 / 模式 / 命令能力 / 忙闲 / 通道，三态区分（0 可发 / 3 未就绪 / 8 无法识别），模式不匹配与忙闲都拒绝，--force 放行并留 override 记录 |
| 状态推送（P2） | 16 项断言全过：只推阶段转换（progress 不推）、游标幂等、新增事件会推、缺会话时明确报错、--create-session 只建一次会话 |
| 统一入口 | 仓库根 npm test = 连接器离线自测 + 派发器 + 豆包确认 + 状态 + 状态推送 + 注册助手，共六套，退出码 0 |

自测默认不产生模型费用；DSH_MCP_CONNECTOR_LIVE=1 node selftest.mjs 会追加一次真实调用。

安全须知

- dsh-mcp-connector 的 stdio 模式由客户端进程本身充当信任边界；HTTP 模式强制 Bearer token，默认只绑 127.0.0.1，未列入白名单的 Origin 一律 403。要上公网请再套 TLS 反向代理并换掉示例 token。
- 外部投递的消息在 DSH 内以 {kind:"user"} 进入会话，与真人输入不可区分——请让下游在任务文本里自带来源标记。
- 不要相信任何 AI 客户端的"我已经调用了工具"。实测：豆包在连接器未启用时会回复「已调用 task_claim，status 为 ok」，而队列里那条任务仍是 pending。核实副作用（队列事件、文件、日志）才是唯一证据——doubao-cdp/dispatch.mjs 就是按这个原则写的。
- doubao-cdp 需要给豆包加 --remote-debugging-port，这意味着本机任何进程都能接管你的豆包（读聊天、以你身份发消息）。不用时退出并正常启动。
- 两者都只做消息投递：不要把外部订阅凭证当作 DSH 的模型后端，那违反各家消费者条款。

许可

MIT，见 LICENSE。