server-deploy/wsl-dev-stack/README.md

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