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

# Claude Dev Stack

WSL2 + Claude Code CLI + Unity MCP + Rust Token Killer **全栈一键部署方案**，适用于 Windows 11 开发环境。

支持 **v2rayN 代理自动检测**、**WSL2 代理透传**、**防火墙自动放行**。

## 组件清单

| 组件 | 说明 | 安装位置 |
|------|------|---------|
| **WSL2** | Windows Subsystem for Linux 2 | Windows 功能 |
| **Claude Code CLI** | `@anthropic-ai/claude-code` | WSL2 npm global |
| **Unity MCP Server** | `AnkleBreaker-Studio/unity-mcp-server` — Claude ↔ Unity Editor 双向集成 | WSL2 独立 Node.js 服务 + Unity Plugin |
| **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      # 配置模板
└── README.md
```

---

## 快速开始

### ℹ️ 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

# 手动指定代理端口（使用官方 Anthropic API 时需要）
pwsh .\deploy.ps1 -ProxyPort 10809

# 不使用代理（直连）
pwsh .\deploy.ps1 -ProxyPort -1
```

首次安装 WSL2 特性后可能需要**重启系统**，重启后重新执行脚本。

### 场景二：已有 WSL2，跳过 WSL2 安装

```powershell
pwsh .\deploy.ps1 -SkipWSL
```

### 场景三：仅在 WSL2 内安装（无 Windows 脚本）

```bash
# 在 WSL2 Ubuntu 终端中执行
cp .env.example .env
nano .env
# 如需代理（端口由 deploy.ps1 写入 ~/.mcp-proxy.env，或手动指定）
PROXY_PORT=10809 bash wsl-setup.sh
```

---

## 代理说明（v2rayN）

### 自动检测顺序

1. Windows 系统代理注册表（v2rayN「设为系统代理」时写入）
2. v2rayN 配置文件（`%APPDATA%\v2rayN\guiNConfig.json`）
3. 探测常用端口：`10809, 10808, 7890, 1080, 8080`

### WSL2 代理透传原理

```
WSL2 Ubuntu
  → [Windows 主机 vEthernet(WSL) IP]:10809
  → v2rayN
  → 互联网
```

**必须**在 v2rayN 中开启：
> 参数设置 → **「允许来自局域网的连接」** ✅

脚本自动完成：
- 写入 WSL2 `~/.mcp-proxy.env`（每次 shell 启动自动生效）
- 配置 WSL2 `git` + `npm` 代理
- `apt-get` 安装阶段同样走代理

### 代理覆盖范围

| 操作 | 是否走代理 |
|------|-----------|
| Windows `git clone` / `npm install` | ✅ |
| WSL2 `apt-get` / `git clone` / `npm install` / `cargo install` | ✅ |
| MCP Server ↔ AI 客户端（stdio） | ❌ 本地通信，无需代理 |
| MCP Server ↔ Unity Plugin（localhost） | ❌ 本地通信，无需代理 |

---

## 配置说明（`.env`）

### 推荐：灵眸 AI（国内直连，无需代理）

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `ANTHROPIC_AUTH_TOKEN` | _(必填)_ | 灵眸 API Key，从 [lmuai.com](https://lmuai.com) 获取 |
| `ANTHROPIC_BASE_URL` | `https://api.lmuai.com` | 灵眸 API 基础 URL |
| `CLAUDE_MODEL` | `claude-opus-4-7` | 可选：`claude-opus-4-7` / `claude-sonnet-4-5` / `claude-haiku-4-5` |

> **灵眸模式行为**：
> - API Token 自动写入 `~/.claude/settings.json` 的 `env` 块（不写入 `~/.bashrc`，避免冲突）
> - 部署脚本自动跳过代理检测（国内直连无需代理）
> - 旧 `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-opus-4-7` | 默认使用的模型 |

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `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
# 方案一：通过 v2rayN 代理（推荐）
pwsh .\deploy.ps1 -ProxyPort 10809

# 方案二：WSL2 内配置镜像
npm config set registry https://registry.npmmirror.com
```

**问题：WSL2 无法连接 v2rayN 代理**
```
解决：
1. v2rayN → 参数设置 → 勾选「允许来自局域网的连接」
2. 确认防火墙未拦截 v2rayN 监听端口
3. WSL2 内测试：curl -I https://github.com --proxy http://$(ip route | grep default | awk '{print $3}'):10809
```

**问题：Unity 版本兼容性**
```
请参考 unity-mcp-plugin 仓库的 README 了解所需 Unity 最低版本要求
```

---

## 使用方式

### Claude Code CLI

```bash
# 进入 WSL2
wsl -d Ubuntu

# 启动 Claude Code
claude

# 或从 PowerShell 快捷命令（由 deploy.ps1 写入 profile）
claude-wsl
```

### RTK (Rust Token Killer)

RTK 作为 Claude Code 的 **PreToolUse hook** 运行，自动将 bash 命令重写为 `rtk` 等效命令，过滤噪音、压缩输出，减少 60–90% token 消耗。

`deploy.ps1` 会自动执行 `rtk init -g` 注册 hook，**重启 Claude Code 后即生效**。

```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" .   # 分组搜索结果
```

### 故障排查 — 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
```