dsh-unity-debug-bridge（合并包）

August 18, 2026 · View on GitHub

DSH ↔ Unity Editor 断点调试桥，一个包同时提供：

  • MCP server（server/mcp-server-stdio.mjs）：把 Unity Editor 托管代码（Mono，含 HybridCLR 热更源码）调试能力暴露给 DSH agent —— 下断点、单步、读栈、求值，Hook 触发式。
  • 调试面板（lib/client.js，浏览器侧）：侧边栏「Unity 调试」入口 + 断点/停住/放行/单步/调用栈/变量树，经 server/bridge-http.mjs（HTTP+SSE）与 agent 共享同一 DAP 会话。

架构：agent → MCP(薄代理) ─HTTP→ bridge-http(唯一 DAP 会话) ─DAP→ UnityDebug.exe → Unity Editor；面板经 SSE 实时同步断点/状态。

特性（v0.3）

  • Hook 触发：unity_continue 非阻塞；命中自动登记队列 + 自动快照；unity_wait_hit 秒回
  • 断点保活：周期重设，域重载自动恢复，attach 后与 Play 状态无关
  • 多实例安全：按 Editor pid 精确路由命令/响应
  • 优雅退出：/api/shutdown + SIGTERM 先 detach 再退出（防污染 Unity 一次性调试端口）
  • HybridCLR 热更可断：编辑器模式热更源码断点正常（见 docs/hybridclr-debugging.md）
  • 面板与 agent 同步：agent 下断点 → 面板实时显示 ✓

工具（MCP）

unity_attach / unity_diagnose / unity_set_breakpoint / unity_continue / unity_wait_hit / unity_hits / unity_play / unity_snapshot / unity_step / unity_step_in / unity_step_out / unity_pause / unity_stack / unity_scopes / unity_variables / unity_evaluate / unity_detach

安装

方式 A：dsh plugin（推荐，面板一键挂载）

dsh plugin --profile web add github:goesByhc/dsh-unity-debug-bridge
# 重启 DSH：侧边栏出现「Unity 调试」面板（bundle patch 自动挂载）

MCP server 再手动配（~/.dsh/cordis.patch.yml 或 /mcp 设置）：

- insert:
    - id: mcp-unity-debug-bridge
      name: "@deepseek-ai/dsh-mcp-client"
      config:
        serverName: unity-debug-bridge
        transport: stdio
        command: node
        args: ["<profile>/node_modules/dsh-unity-debug-bridge/server/mcp-server-stdio.mjs"]
        cwd: "<含 vendor/vscode-unity-debug 的目录>"
        toolCallTimeoutMs: 120000

方式 B：install.mjs（全自动，面板 + MCP 一起配）

node install.mjs
# 复制 lib/server 到 profile node_modules，追加面板 + MCP entry 到 ~/.dsh/cordis.patch.yml
# 重启 DSH 生效

前置条件

  • Node.js ≥ 18
  • Unity Editor（已打开目标项目），脚本调试已启用
  • DAP adapter：已随包内置（server/adapter/，UnityDebug.exe + 运行依赖，约 8.9MB，master 源码构建）
    • 支持 Unity 2020~2023+（含 2022.3，已验证）；2019 及更早需官方 Release 2.7.2（见 docs/adapter-contract.md）
    • adapter 解析顺序：显式参数 > env UNITY_DAP_ADAPTER > 包内 server/adapter/ > cwd/vendor > 工程上级 vendor
    • 如自定义构建：用 UNITY_DAP_ADAPTER 指向你的 UnityDebug.exe

正确调试流程

1. Unity 打开工程 → 进 Play 走到目标界面（先 Play 后 attach）
2. unity_attach(projectPath) → unity_set_breakpoint(file, line)
3. 游戏触发代码路径 → unity_wait_hit → 命中快照（栈+变量）
4. Agent 决策：求值/单步/换断点 → unity_continue({resumeAfterStop:true}) 放行

文档

仓库

源码/开发：https://github.com/goesByhc/dsh-UnityDebugBridge（根仓库含 ui-plugin 开发源码与验证工程）