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

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（推荐，面板一键挂载）

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

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

```yaml
- 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 一起配）

```bash
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

## 正确调试流程

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

## 文档

- [docs/adapter-contract.md](docs/adapter-contract.md) —— DAP 运行契约与坑
- [docs/hybridclr-debugging.md](docs/hybridclr-debugging.md) —— HybridCLR 热更断点实战

## 仓库

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