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. 复制配置文件，填写 ANTHROPIC_API_KEY
cp .env.example .env
notepad .env

# 3. 运行部署脚本（自动检测 v2rayN 代理）
pwsh .\deploy.ps1

# 手动指定代理端口
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`）

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `ANTHROPIC_API_KEY` | _(空)_ | Anthropic API Key，从 [console.anthropic.com](https://console.anthropic.com) 获取 |
| `ANTHROPIC_BASE_URL` | `https://api.anthropic.com` | API 基础 URL；中转代理可改为 DeepSeek 等兼容接口 |
| `CLAUDE_MODEL` | `claude-opus-4-5` | 默认使用的模型 |
| `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 工具列表

| 工具 | 功能 |
|------|------|
| `execute_menu_item` | 执行 Unity 菜单项 |
| `select_gameobject` | 选中场景中的 GameObject |
| `update_gameobject` | 更新/创建 GameObject 属性 |
| `update_component` | 更新/添加组件 |
| `add_package` | 通过 Package Manager 安装包 |
| `run_tests` | 运行 Unity Test Runner 测试 |
| `add_asset_to_scene` | 将 Asset 添加到场景 |
| `create_prefab` | 创建 Prefab |
| `create_scene` / `load_scene` / `delete_scene` | 场景管理 |
| `get_gameobject` | 获取 GameObject 详细信息 |
| `get_console_logs` | 读取 Unity Console 日志 |
| `recompile_scripts` | 重新编译脚本 |
| `create_material` / `assign_material` | 材质管理 |
| `move/rotate/scale_gameobject` | Transform 操作 |
| `batch_execute` | 批量执行多个操作 |

---

### 防火墙放行（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
```