refactor: 拆分 claude-dev-stack 为 windows-dev-stack 和 wsl-dev-stack

将原 claude-dev-stack 目录拆分为独立的 Windows 和 WSL 部署栈，便于分别维护和使用。 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-05-29 01:11:20 +08:00
parent e8693dad2a
commit dd3eb24d0f
488 changed files with 33927 additions and 0 deletions
--- a/wsl-dev-stack/README.md
+++ b/wsl-dev-stack/README.md
@@ -0,0 +1,729 @@
+# Claude Dev Stack
+
+WSL2 + Claude Code CLI + GitHub Copilot CLI + Unity MCP + **Godot MCP Pro** + Rust Token Killer **全栈一键部署方案**，适用于 Windows 11 开发环境。
+
+支持 **WSL2 镜像网络模式**（`autoProxy=true`），WSL2 自动继承 Windows 代理状态，无需脚本干预。
+
+## 组件清单
+
+| 组件 | 说明 | 安装位置 |
+|------|------|---------|
+| **WSL2** | Windows Subsystem for Linux 2 | Windows 功能 |
+| **Claude Code CLI** | `@anthropic-ai/claude-code` | WSL2 npm global |
+| **GitHub Copilot CLI** | `gh` + `github/gh-copilot` 扩展 | WSL2 apt + gh extension |
+| **Unity MCP Server** | `AnkleBreaker-Studio/unity-mcp-server` — Claude ↔ Unity Editor 双向集成 | WSL2 独立 Node.js 服务 + Unity Plugin |
+| **Godot MCP Pro** | 本地 ZIP 包（v1.14.1）— Claude ↔ Godot Editor 双向集成，170+ 工具 | `~/godot-mcp-pro/`（Win）+ `~/.mcp-servers/godot-mcp-pro/`（WSL2） |
+| **Rust** | rustup stable 工具链 | WSL2 `~/.cargo` |
+| **RTK** | Rust Token Killer (`rtk`) — LLM token 统计与上下文优化 | WSL2 cargo bin |
+
+## 目录结构
+
+```
+claude-dev-stack/
+├── deploy.ps1                    # Windows 一键部署（PowerShell 5.1+）
+├── wsl-setup.sh                  # WSL2 内部安装脚本（可单独运行）
+├── .env.example                  # 配置模板
+├── godot-mcp-pro-v1.14.1/        # Godot MCP Pro 本地包（付费，随仓库分发）
+│   ├── server/                   # Node.js MCP Server（build/ 已预编译）
+│   ├── addons/godot_mcp/         # Godot 插件（手动复制到各项目）
+│   └── INSTALL.md
+└── README.md
+```
+
+---
+
+## 快速开始
+
+### ℹ️ GitHub Copilot CLI 共存说明
+
+本方案安装的是 **WSL2 Linux 原生 GitHub CLI + gh-copilot 扩展**。  
+即使 Windows 已经安装了 GitHub Copilot CLI / GitHub CLI，也**不会覆盖 Windows 版本**。
+
+- Windows 继续使用 Windows 自己的 `gh`
+- WSL2 继续使用 WSL2 自己的 `gh`
+- 两边各自维护独立的登录状态和配置，互不冲突
+- `deploy.ps1` 会额外写入 PowerShell 快捷命令 `gh-copilot-wsl`，用于**显式调用 WSL2 版本**，避免误用 Windows 侧命令
+
+### ℹ️ WSL2 默认用户
+
+本方案使用 **root** 作为 WSL2 默认用户（通过 `/etc/wsl.conf` 配置）。  
+WSL2 Ubuntu 首次启动若弹出用户创建提示，可直接跳过或按提示操作，deploy.ps1 会自动将默认用户切换为 root。
+
+---
+
+### 场景一：全新 Windows 系统（首次安装 WSL2）
+
+> 需要**管理员权限**启用 WSL2 Windows 功能
+
+```powershell
+# 1. 以管理员身份运行 PowerShell
+cd path\to\claude-dev-stack
+
+# 2. 复制配置文件，填写灵眸 API Key（推荐）或 Anthropic API Key
+cp .env.example .env
+notepad .env
+
+# 3. 运行部署脚本
+pwsh .\deploy.ps1
+```
+
+脚本会自动在 **WSL2 内** 安装以下组件：
+
+1. Claude Code CLI
+2. GitHub CLI (`gh`)
+3. GitHub Copilot CLI 扩展 (`github/gh-copilot`)
+4. Unity MCP Server
+5. Godot MCP Pro（从本地 `godot-mcp-pro-v1.14.1/` 复制）
+6. Rust + RTK
+
+首次安装 WSL2 特性后可能需要**重启系统**，重启后重新执行脚本。
+
+### 场景二：已有 WSL2，跳过 WSL2 安装
+
+```powershell
+pwsh .\deploy.ps1 -SkipWSL
+```
+
+### 场景三：仅在 WSL2 内安装（无 Windows 脚本）
+
+```bash
+# 在 WSL2 Ubuntu 终端中执行
+cp .env.example .env
+nano .env
+bash wsl-setup.sh
+```
+
+---
+
+## 代理说明
+
+### WSL2 镜像模式自动继承 Windows 代理
+
+> **注意**：镜像网络模式仅支持 **Windows 11 22H2（Build 22621）及以上版本**。Windows 10 用户脚本会自动跳过此配置，WSL2 使用默认 NAT 模式，需在 WSL2 内手动配置代理。
+
+脚本自动配置 `~/.wslconfig` 启用 WSL2 镜像网络模式：
+
+```ini
+[wsl2]
+networkingMode=mirrored
+autoProxy=true
+```
+
+`autoProxy=true` 下，WSL2 自动继承 Windows 系统代理状态。  
+**是否使用代理由 Windows 侧决定**（例如通过 v2rayN「设为系统代理」），无需脚本干预。
+
+---
+
+## 配置说明（`.env`）
+
+### 推荐：灵眸 AI（国内直连，无需代理）
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `ANTHROPIC_AUTH_TOKEN` | _(必填)_ | 灵眸 API Key，从 [lmuai.com](https://lmuai.com) 获取 |
+| `ANTHROPIC_BASE_URL` | `https://api.lmuai.com` | 灵眸 API 基础 URL |
+| `CLAUDE_MODEL` | `claude-sonnet-4-6` | 可选：`claude-sonnet-4-6` / `claude-opus-4-7` / `claude-sonnet-4-5` / `claude-haiku-4-5` |
+
+> **灵眸模式自动写入 `settings.json` 的 env 参数**：
+> | 参数 | 值 | 说明 |
+> |------|----|------|
+> | `ANTHROPIC_BASE_URL` | `https://api.lmuai.com` | API 端点 |
+> | `ANTHROPIC_AUTH_TOKEN` | _(你的 Key)_ | 认证凭据 |
+> | `API_TIMEOUT_MS` | `3000000` | 超时 50 分钟，防止长任务中断 |
+> | `CLAUDE_CODE_ATTRIBUTION_HEADER` | `0` | 关闭来源标识，提高缓存命中率 |
+> | `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | `1` | 关闭遥测/自动更新检查 |
+>
+> - Token 写入 `settings.json` 的 `env` 块（不写入 `~/.bashrc`，避免与 `ANTHROPIC_API_KEY` 冲突）
+> - 旧 `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL` 变量从 `~/.bashrc` 自动清除
+
+### 备选：Anthropic 官方 API
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `ANTHROPIC_API_KEY` | _(空)_ | Anthropic API Key，从 [console.anthropic.com](https://console.anthropic.com) 获取 |
+| `ANTHROPIC_BASE_URL` | `https://api.anthropic.com` | API 基础 URL；DeepSeek 等中转可改为对应 URL |
+| `CLAUDE_MODEL` | `claude-sonnet-4-6` | 默认使用的模型 |
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `WSL_DISTRO` | `Ubuntu` | WSL2 发行版名称 |
+| `SKIP_WSL_INSTALL` | `false` | `true` 跳过 WSL2 安装步骤 |
+
+---
+
+## Unity MCP 完整安装教程
+
+> **MCP Server 仓库**：[AnkleBreaker-Studio/unity-mcp-server](https://github.com/AnkleBreaker-Studio/unity-mcp-server)  
+> **Unity Plugin 仓库**：[AnkleBreaker-Studio/unity-mcp-plugin](https://github.com/AnkleBreaker-Studio/unity-mcp-plugin)  
+https://github.com/AnkleBreaker-Studio/unity-mcp-plugin.git
+> **要求**：Unity 2021.3+ + Node.js 18+
+
+### 架构原理
+
+Unity MCP 由**两个独立仓库**组成，各自独立安装：
+
+```
+Claude Code CLI
+      │  MCP 协议 (stdio)
+      ▼
+Node.js MCP Server                    ← 克隆自 unity-mcp-server，WSL2 中运行
+(~/.mcp-servers/unity-mcp-server/)    ← deploy.ps1 自动完成克隆 + npm install
+      │  WebSocket / HTTP
+      ▼
+Unity Editor Plugin (C#)              ← Package Manager 安装 unity-mcp-plugin
+      │
+      ▼
+Unity 场景 / 对象 / 脚本 / 测试...
+```
+
+- **unity-mcp-server**：独立 Node.js MCP 服务，部署脚本自动克隆并安装依赖
+- **unity-mcp-plugin**：Unity C# 插件，需要手动通过 Package Manager 安装
+
+---
+
+### Step 1：运行部署脚本（自动完成服务器安装）
+
+```powershell
+pwsh .\deploy.ps1
+```
+
+脚本会自动：
+1. 克隆 `unity-mcp-server` 到 WSL2 `~/.mcp-servers/unity-mcp-server/`
+2. 执行 `npm install` 安装依赖
+3. 将 MCP Server 注册到 `%USERPROFILE%\.claude\claude_desktop_config.json`
+
+---
+
+### Step 2：在 Unity Editor 安装 unity-mcp-plugin
+
+1. 打开 Unity Editor
+2. 菜单：**Window → Package Manager**
+3. 点击左上角 **"+"** 按钮 → **"Add package from git URL..."**
+4. 输入以下 URL，点击 **Add**：
+   ```
+   https://github.com/AnkleBreaker-Studio/unity-mcp-plugin.git
+   ```
+5. 等待包下载安装完成
+
+安装完成后，菜单栏会出现 **Tools → Unity MCP** 选项。
+
+---
+
+### Step 3：启动 Unity Editor 端 MCP 服务
+
+每次使用 Claude Code 操作 Unity 之前，需要先在 Unity 中启动服务：
+
+1. 打开 Unity Editor，确保项目已加载
+2. 菜单：**Tools → Unity MCP → Start Server**（具体菜单项名称以插件实际为准）
+3. 状态变为绿色 / Connected 表示服务就绪
+
+---
+
+### Step 4：确认 MCP 配置
+
+部署脚本已自动写入 Windows Claude Code 配置。确认内容：
+
+```powershell
+cat "$env:USERPROFILE\.claude\claude_desktop_config.json"
+```
+
+应包含类似如下内容：
+
+```json
+{
+  "mcpServers": {
+    "unity-mcp": {
+      "command": "wsl",
+      "args": ["-d", "Ubuntu", "--", "node", "/home/用户名/.mcp-servers/unity-mcp-server/src/index.js"]
+    }
+  }
+}
+```
+
+WSL2 内的配置（`~/.config/Claude/claude_desktop_config.json`）直接使用 `node`：
+
+```json
+{
+  "mcpServers": {
+    "unity-mcp": {
+      "command": "node",
+      "args": ["/home/用户名/.mcp-servers/unity-mcp-server/src/index.js"]
+    }
+  }
+}
+```
+
+---
+
+### Step 5：在 Claude Code 中使用 Unity MCP
+
+```bash
+# 启动 Claude Code（WSL2 内）
+claude
+
+# 验证 Unity MCP 连接
+> /mcp
+
+# 示例：操作 Unity 场景
+> 在场景中创建一个名为 Player 的空 GameObject
+> 给 Player 添加 Rigidbody 组件，质量设为 5
+> 创建一个新场景 Level1，保存到 Assets/Scenes/
+> 运行所有 EditMode 测试
+```
+
+---
+
+### 可用 MCP 工具列表
+
+AnkleBreaker Unity MCP 采用**两级工具架构**，共 **288 个工具**：
+
+- **核心工具（~70个）**：直接暴露，无需中转
+- **高级工具（200+）**：通过 `unity_advanced_tool` 代理访问（避免 MCP 客户端工具过多失效）
+
+#### 核心工具（直接可用）
+
+| 分类 | 工具名 | 功能 |
+|------|--------|------|
+| **编辑器状态** | `unity_editor_ping` / `unity_editor_state` / `unity_project_info` | 检测连接、获取编辑器/项目状态 |
+| **场景** | `unity_scene_info/open/save/new/hierarchy/stats` | 场景完整生命周期管理 |
+| **GameObject** | `unity_gameobject_create/delete/info/set_transform/duplicate/set_active/reparent` | 对象增删改查 |
+| **组件** | `unity_component_add/remove/get_properties/set_property/set_reference/batch_wire` | 组件与属性操作 |
+| **资产** | `unity_asset_list/import/delete/create_prefab/instantiate_prefab` | 资产管理 |
+| **脚本** | `unity_script_create/read/update` + `unity_execute_code` | C# 脚本读写与运行时执行 |
+| **材质** | `unity_material_create` / `unity_renderer_set_material` | 材质创建与赋值 |
+| **构建/运行** | `unity_build` / `unity_play_mode` | 多平台构建、Play Mode 控制 |
+| **控制台** | `unity_console_log/clear` + `unity_get_compilation_errors` | 日志读取与编译错误 |
+| **编辑器操作** | `unity_execute_menu_item` / `unity_undo/redo/undo_history` | 菜单执行、撤销重做 |
+| **选择/搜索** | `unity_selection_*` / `unity_search_by_*` / `unity_search_assets` | 对象查找与选中 |
+| **截图** | `unity_screenshot_game/scene` + `unity_graphics_*_capture` | 场景/游戏视图截图 |
+| **Prefab** | `unity_prefab_info` / `unity_set_object_reference` | Prefab 信息与引用 |
+| **包管理** | `unity_packages_list/add/remove/search/info` | Package Manager 操作 |
+| **Multi-Agent** | `unity_queue_info` / `unity_agents_list` / `unity_agent_log` | 多代理会话管理 |
+| **高级工具代理** | `unity_list_advanced_tools` / `unity_advanced_tool` | 访问 200+ 高级工具 |
+| **Unity Hub** | `unity_hub_list_editors/available_releases/install_editor/install_modules` | Hub 版本管理 |
+| **多实例** | `unity_list_instances` / `unity_select_instance` | 多 Unity 实例切换 |
+| **项目上下文** | `unity_get_project_context` | AI 代理项目文档注入 |
+
+#### 高级工具分类（通过 `unity_advanced_tool` 访问）
+
+动画、Prefab 模式、物理、光照、音频、地形、导航网格、粒子、UI、标签与层、输入系统、Shader Graph、VFX Graph、Amplify Shader Editor、性能分析器、帧调试器、内存分析器、ScriptableObject、约束、LOD、MPPM 多人 PlayMode、UMA Avatar 等 30+ 分类。
+
+```bash
+# 列出所有高级工具
+> 使用 unity_list_advanced_tools 查看所有高级工具
+
+# 按分类过滤
+> unity_list_advanced_tools { "category": "animation" }
+> unity_list_advanced_tools { "category": "terrain" }
+
+# 执行高级工具
+> unity_advanced_tool { "tool": "unity_animation_create_controller", "params": {...} }
+```
+
+`deploy.ps1` 会自动将所有工具写入 `~/.claude/settings.json` 的 `allowedTools` 白名单，**无需每次手动确认**。
+
+---
+
+### 防火墙放行（Bridge 端口）
+
+`deploy.ps1` 会自动创建防火墙规则，放行 TCP **7890–7899**（Bridge Port 范围）。
+
+手动放行：
+
+```powershell
+New-NetFirewallRule -DisplayName "Unity MCP Bridge Inbound" `
+    -Direction Inbound -Protocol TCP -LocalPort 7890-7899 -Action Allow -Profile Any
+New-NetFirewallRule -DisplayName "Unity MCP Bridge Outbound" `
+    -Direction Outbound -Protocol TCP -LocalPort 7890-7899 -Action Allow -Profile Any
+```
+
+验证 Bridge 是否可用：
+
+```powershell
+# Unity Editor 打开后
+Invoke-WebRequest http://127.0.0.1:7890/api/ping
+# 返回 200 OK 表示 Bridge 正常
+```
+
+---
+
+### 故障排查
+
+**问题：Unity MCP 连接失败**
+```
+解决：
+1. 确认 Unity Editor 已打开，且 unity-mcp-plugin 已启动服务
+2. 测试 Bridge: Invoke-WebRequest http://127.0.0.1:7890/api/ping
+3. 确认防火墙 TCP 7890 已放行
+4. 确认 MCP Server 进程正常：wsl -d Ubuntu -- node ~/.mcp-servers/unity-mcp-server/src/index.js
+5. 重新执行 deploy.ps1 重新克隆并注册 MCP Server
+```
+
+**问题：更新 unity-mcp-server 后连接失败**
+```
+解决：
+wsl -d Ubuntu -- bash -c "cd ~/.mcp-servers/unity-mcp-server && git pull && npm install"
+```
+
+**问题：npm install 安装超时（国内网络）**
+```bash
+# 方案一：在 Windows 侧开启系统代理（v2rayN「设为系统代理」），WSL2 自动继承
+# 方案二：WSL2 内配置镜像
+npm config set registry https://registry.npmmirror.com
+```
+
+**问题：WSL2 无法访问外网**
+```
+解决：
+1. 确认 Windows 侧代理已开启系统代理（v2rayN → 参数设置 → 勾选「允许来自局域网的连接」）
+2. 确认 ~/.wslconfig 包含 networkingMode=mirrored 和 autoProxy=true
+3. 重启 WSL2：wsl --shutdown，再重新启动
+```
+
+**问题：Unity 版本兼容性**
+```
+请参考 unity-mcp-plugin 仓库的 README 了解所需 Unity 最低版本要求
+```
+
+---
+
+## Godot MCP Pro 完整安装教程
+
+> **版本**：v1.14.1（付费本地包，随本仓库分发）  
+> **要求**：Godot 4.x + Node.js 18+  
+> **组成**：`server/`（Node.js MCP 服务端）+ `addons/godot_mcp/`（Godot 编辑器插件）
+
+### 架构原理
+
+```
+Claude Code CLI / Claude Desktop / Cursor / Windsurf / VS Code
+      │  MCP 协议 (stdio)
+      ▼
+Node.js MCP Server                          ← deploy.ps1 自动安装
+(~/.mcp-servers/godot-mcp-pro/             ←   WSL2 侧
+ %USERPROFILE%\godot-mcp-pro\              ←   Windows 侧（供非 WSL 客户端）
+ server/build/index.js)
+      │  WebSocket
+      ▼
+Godot Editor Plugin (GDScript)             ← 手动复制到各 Godot 项目
+(addons/godot_mcp/                         ←   须在 Project Settings → Plugins 启用)
+      │
+      ▼
+Godot 场景 / 节点 / 脚本 / 运行时测试...
+```
+
+> ⚠️ **端口说明**：MCP 服务端自动扫描 **6505–6509** 寻找可用端口，**不要**在配置中固定 `GODOT_MCP_PORT`，让 Godot 插件自动连接所有候选端口即可。
+
+---
+
+### Step 1：运行部署脚本（自动安装服务端）
+
+```powershell
+pwsh .\deploy.ps1
+```
+
+脚本会自动：
+1. 将 `godot-mcp-pro-v1.14.1/server/` 同步到 `%USERPROFILE%\godot-mcp-pro\`（Windows）
+2. 将 `server/` 复制到 WSL2 `~/.mcp-servers/godot-mcp-pro/`
+3. 在两侧执行 `npm install` 安装依赖（`build/` 目录已预编译，无需编译步骤）
+4. 将 `godot-mcp-pro` 条目写入 Claude Desktop / Cursor / Windsurf / VS Code / Claude Code CLI
+
+---
+
+### Step 2：在 Godot 项目中安装插件（每个项目一次）
+
+部署脚本**不会**自动安装 Godot 插件，因为它需要逐项目手动操作：
+
+1. 打开文件管理器，进入本仓库目录：
+   ```
+   claude-dev-stack\godot-mcp-pro-v1.14.1\addons\
+   ```
+2. 将 `godot_mcp/` 目录整体复制到你的 **Godot 项目根目录** 下的 `addons/` 中：
+   ```
+   你的Godot项目/
+   └── addons/
+       └── godot_mcp/      ← 从 godot-mcp-pro-v1.14.1\addons\godot_mcp\ 复制过来
+   ```
+3. 在 Godot 编辑器中：**Project → Project Settings → Plugins**，找到 **Godot MCP Pro** 并勾选 **Enable**
+4. 插件启用后，状态栏显示连接端口（如 `MCP listening on :6505`）
+
+---
+
+### Step 3：确认 MCP 配置
+
+部署脚本已自动写入各客户端配置。Windows 侧确认：
+
+```powershell
+cat "$env:APPDATA\Claude\claude_desktop_config.json"
+```
+
+应包含（Windows 侧条目，供 Claude Desktop / Cursor / Windsurf / VS Code）：
+
+```json
+{
+  "mcpServers": {
+    "godot-mcp-pro": {
+      "command": "node",
+      "args": ["C:/Users/YourName/godot-mcp-pro/build/index.js"]
+    }
+  }
+}
+```
+
+WSL2 内的条目（供 Claude Code CLI）：
+
+```bash
+claude mcp list --scope user
+# 应包含: godot-mcp-pro  node  /root/.mcp-servers/godot-mcp-pro/build/index.js
+```
+
+---
+
+### Step 4：在 Claude Code 中使用 Godot MCP Pro
+
+> ⚠️ **重要区分**：Editor 工具（场景/节点/脚本操作）**随时可用**；Runtime 工具（游戏运行时状态/截图/输入模拟）**必须先调用 `play_scene` 启动游戏**。
+
+```bash
+# 启动 Claude Code（WSL2 内）
+claude
+
+# 验证 Godot MCP 连接
+> /mcp
+# 应看到 godot-mcp-pro 及其工具列表
+
+# ── 示例：场景搭建 ──
+> 创建一个名为 Player 的 CharacterBody2D 节点，添加 CollisionShape2D 和 Sprite2D 子节点
+
+# ── 示例：脚本操作 ──
+> 读取 res://scripts/player.gd，帮我添加跳跃逻辑
+
+# ── 示例：运行测试 ──
+> play_scene 后截图，检查 Player 是否出现在屏幕中央
+
+# ── 示例：批量修改 ──
+> 将场景中所有 Label 节点的字体大小统一改为 24
+```
+
+---
+
+### 可用工具分类（170+ 工具）
+
+| 分类 | 代表工具 | 说明 |
+|------|----------|------|
+| **项目/文件系统** | `get_project_info`, `get_filesystem_tree`, `search_files` | 项目概览与文件搜索 |
+| **场景** | `get_scene_tree`, `create_scene`, `open_scene`, `save_scene` | 场景生命周期 |
+| **节点** | `add_node`, `update_property`, `connect_signal`, `batch_set_property` | 节点增删改 |
+| **脚本** | `read_script`, `create_script`, `edit_script`, `validate_script` | GDScript 读写验证 |
+| **编辑器** | `get_editor_screenshot`, `get_editor_errors`, `get_output_log` | 编辑器状态截图 |
+| **3D** | `add_mesh_instance`, `setup_lighting`, `setup_camera_3d`, `setup_collision` | 3D 场景搭建 |
+| **动画** | `create_animation`, `add_animation_track`, `create_animation_tree` | 动画与状态机 |
+| **Audio** | `add_audio_bus`, `add_audio_player`, `get_audio_bus_layout` | 音频系统 |
+| **导航** | `setup_navigation_region`, `bake_navigation_mesh` | NavMesh 导航 |
+| **粒子** | `create_particles`, `apply_particle_preset` | 粒子特效 |
+| **Shader** | `create_shader`, `edit_shader`, `assign_shader_material` | 着色器编写 |
+| **Tilemap** | `tilemap_set_cell`, `tilemap_fill_rect` | 瓦片地图 |
+| **分析** | `analyze_scene_complexity`, `detect_circular_dependencies`, `find_unused_resources` | 项目分析 |
+| **运行时** | `play_scene`, `get_game_screenshot`, `simulate_key`, `run_test_scenario` | 运行时控制与测试 |
+
+---
+
+### 故障排查 — Godot MCP Pro
+
+**问题：`/mcp` 中看不到 godot-mcp-pro**
+```
+解决：
+1. 重新运行 deploy.ps1（幂等，可多次执行）
+2. 检查 claude mcp list --scope user 是否有 godot-mcp-pro 条目
+3. 重启 Claude Code：exit → claude
+```
+
+**问题：工具调用失败，Godot 插件未响应**
+```
+解决：
+1. 确认 Godot 编辑器已打开，且插件已在 Project Settings → Plugins 中启用
+2. 确认插件状态栏显示 "MCP listening on :650X"
+3. 不要设置 GODOT_MCP_PORT 环境变量；让服务端自动扫描
+```
+
+**问题：WSL2 侧 npm install 超时**
+```bash
+# 设置国内镜像后重试
+npm config set registry https://registry.npmmirror.com
+cd ~/.mcp-servers/godot-mcp-pro && npm install
+```
+
+---
+
+## 使用方式
+
+### Claude Code CLI
+
+```bash
+# 进入 WSL2
+wsl -d Ubuntu
+
+# 启动 Claude Code
+claude
+
+# 或从 PowerShell 快捷命令（由 deploy.ps1 写入 profile）
+claude-wsl
+```
+
+### GitHub Copilot CLI（WSL2 原生）
+
+首次使用前，需要在 **WSL2 内单独登录 GitHub**：
+
+```bash
+gh auth login
+```
+
+验证 gh-copilot 扩展已安装：
+
+```bash
+gh extension list | grep gh-copilot
+```
+
+常用命令：
+
+```bash
+# 命令建议
+gh copilot suggest "写一个 bash 脚本，递归统计当前目录下最大的 20 个文件"
+
+# 命令解释
+gh copilot explain "find . -type f -name '*.log' -mtime +7 -delete"
+```
+
+如果你人在 Windows PowerShell 中，但想**强制调用 WSL2 版本**，使用部署脚本写入的快捷函数：
+
+```powershell
+gh-copilot-wsl suggest "生成一个 bash 命令，列出 Git 仓库中最近修改的 10 个文件"
+gh-copilot-wsl explain "tar -czf backup.tar.gz ~/project --exclude node_modules"
+```
+
+这两个入口的职责建议固定：
+
+- 在 Windows PowerShell 里直接输入 `gh ...`，默认走 Windows 版本
+- 在 Windows PowerShell 里输入 `gh-copilot-wsl ...`，明确走 WSL2 版本
+- 在 WSL2 终端里输入 `gh ...`，明确走 WSL2 版本
+
+### RTK (Rust Token Killer)
+
+RTK 支持多种 AI 编程助手集成，过滤噪音、压缩输出，减少 60–90% token 消耗。
+
+#### Claude Code 集成
+
+RTK 作为 Claude Code 的 **PreToolUse hook** 运行，自动将 bash 命令重写为 `rtk` 等效命令。
+
+`deploy.ps1` 会自动执行 `rtk init -g` 注册 hook，**重启 Claude Code 后即生效**。
+
+#### GitHub Copilot 集成
+
+RTK 通过 `.github/copilot-instructions.md` 文件集成 GitHub Copilot（VS Code / Copilot Chat）。  
+本仓库已包含此文件，Copilot 读取后会自动在终端命令前添加 `rtk` 前缀。
+
+```bash
+# 生成 copilot-instructions 模板（如需在其他项目中集成）
+rtk init -g --copilot
+```
+
+生成的 `.github/copilot-instructions.md` 内容示例：
+
+```markdown
+<!-- rtk-instructions v2 -->
+# RTK — Token-Optimized CLI
+
+Always prefix shell commands with `rtk`:
+- rtk git status   (instead of git status)
+- rtk cargo test   (instead of cargo test)
+- rtk docker ps    (instead of docker ps)
+```
+
+> 对已有 `copilot-instructions.md` 的项目，可手动追加 RTK 规则块，避免覆盖原有内容。
+
+```bash
+# 验证 hook 安装状态
+rtk init --show
+
+# 查看 token 节省统计（需先在 Claude Code 中运行一些命令）
+rtk gain
+rtk gain --graph       # ASCII 图表
+rtk gain --history     # 最近命令历史
+
+# 手动使用（无需 hook）
+rtk git status         # 压缩 git status 输出
+rtk cargo test         # 只显示失败的测试
+rtk grep "pattern" .   # 分组搜索结果
+```
+
+### 故障排查 — gh copilot 使用 Windows 版本
+
+**现象**：在 WSL2 中执行 `gh copilot` 报错 `exec: .../copilot.bat: not found`
+
+**原因**：VS Code GitHub Copilot Chat 扩展将其 `copilotCli` 目录加入了 Windows 系统 PATH，WSL2 继承该路径后，`gh copilot` 内置命令从 PATH 找到了 Windows 的 `.bat` wrapper，在 Linux 下无法执行。
+
+```bash
+# 方法一：重新运行 wsl-setup.sh（已自动写入 PATH 修复）
+bash /mnt/g/Works/server-deploy/claude-dev-stack/wsl-setup.sh
+
+# 方法二：手动修复（写入 ~/.bashrc 并立即生效）
+cat >> ~/.bashrc << 'EOF'
+
+# 排除 VS Code Copilot Chat Windows wrapper（gh copilot 在 WSL2 中会误调用 .bat 文件）
+PATH="$(echo "$PATH" | tr ':' '\n' | grep -Fv 'copilotCli' | tr '\n' ':' | sed 's/:$//')"
+EOF
+source ~/.bashrc
+
+# 验证
+gh copilot --version
+```
+
+---
+
+### 故障排查 — rtk 安装失败
+
+```bash
+# 手动安装
+cargo install --git https://github.com/rtk-ai/rtk
+
+# 手动初始化 hook
+rtk init -g
+```
+
+---
+
+## 环境检测逻辑
+
+脚本对每个组件均先检测是否已安装，**已安装则跳过**，实现幂等执行：
+
+```
+WSL2         → wsl --list 检测发行版
+Node.js      → node --version
+Claude Code  → claude --version
+Rust         → rustc --version
+rtk          → rtk --version
+Unity MCP    → 检测 ~/.mcp-servers/unity-mcp-server/
+```
+
+---
+
+## 故障排查
+
+### WSL2 安装失败
+
+```powershell
+Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux -NoRestart
+Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform -NoRestart
+# 重启后
+wsl --update
+wsl --install -d Ubuntu
+```
+
+### Rust/cargo 安装慢
+
+在 `.env` 或 `~/.bashrc` 中添加 RsProxy 镜像：
+
+```bash
+export RUSTUP_DIST_SERVER=https://rsproxy.cn
+export RUSTUP_UPDATE_ROOT=https://rsproxy.cn/rustup
+```
+