# 决策 002：搭建 Claude Code 开发环境，建立"重活"工具链

- **日期**：2026-06-30
- **触发**：社区调研后确认 Claude Code 为编程重活最优工具，决定从仅用 Copilot 扩展到双工具组合
- **状态**：已完成 ✅（2026-06-30 搭建完成，2026-07-01 接入扣子平台）

---

## 核心决策

**不追求"全都要"，按社区最优实践精准补位**——保留 Copilot 做日常主力，新增 Claude Code 专攻复杂重构/调试/多文件修改，通过 DeepSeek 官方的 Anthropic 兼容端点直连绕开限流 + 控制成本。

---

## 选型逻辑

| 维度 | 方案 | 为什么 |
|------|------|--------|
| 运行环境 | WSL2（Windows 内嵌 Linux） | Claude Code 原生 Linux 工具，WSL2 体验最稳；秒级启动、动态内存、数据隔离 |
| Claude Code 后端 | DeepSeek V4 Pro（Anthropic 兼容端点直连） | 避开了 Claude 官方订阅 $20/月 + 15-30 分钟限流的致命伤；DS 价格 ~1/29，已通过扣子日常使用 |
| 日常主力 | 保持不变：Copilot | 社区共识"Cursor 日常 + Claude Code 重活"；我目前 Copilot 够用，不需要一步到位换 Cursor |
| 按需使用 | 开 WSL2 终端 → 跑 Claude Code → 关终端 | WSL2 休眠机制天然防后台偷跑 token，社区"重活利器按需开用完关"的最佳实践 |

---

## 环境架构图

```
Windows 11
├── VS Code + Copilot（日常主力，一直开着）
└── WSL2（Ubuntu，按需启动）
    └── Claude Code（CLI 工具）
        └── DeepSeek V4 Pro（Anthropic 兼容端点直连）（后端，不限流）
```

---

## 面试可讲点

- **环境搭建能力**：Windows + WSL2 + Claude Code CLI + 第三方模型切换，整个工具链是自己调研/选型/搭建的
- **成本意识**：知道 Claude Code 官方版限流严重，主动利用 DeepSeek 官方 Anthropic 兼容端点直连，无需中间层（ccswitch），成本降到 ~1/29
- **安全边界**：WSL2 数据隔离、CLI 按需启动不跑后台、不盲目信任任何工具自动行为
- **社区验证**：不是拍脑袋选型，是搜了掘金/V2EX/Reddit/HN 多源社区反馈后做的决策

---

## 已完成

- [x] WSL2 安装（Ubuntu 22.04 LTS）
- [x] 安装 Claude Code（DeepSeek Anthropic 兼容端点直连，无需 ccswitch）
- [x] 配置 DeepSeek API Key 环境变量（`apiKeyHelper` + `ANTHROPIC_BASE_URL`）
- [x] 在旅游搭子项目目录下跑通首条指令
- [x] 接入扣子平台（本地 Claude Code Agent，2026-07-01）

---

## 一句话

**Copilot 管日常 + Claude Code 管硬活，用社区最优方案而非最贵方案。这套环境搭建过程本身就是 AI 应用岗的加分项。**

---

## 扩展：接入扣子平台（2026-07-01）

将本地 Claude Code 接入扣子，实现手机遥控 Claude Code、团队协作共用。

### 前置条件

- Claude Code 已在 WSL2 中安装并可用（`claude --version` 有输出）
- 已安装 `@agentclientprotocol/claude-agent-acp`（ACP wrapper）：
  ```bash
  npm install -g @agentclientprotocol/claude-agent-acp
  ```

### 架构原理

> **与本地终端用法的区别**：本地终端里 Claude Code 通过 `ANTHROPIC_BASE_URL` + `apiKeyHelper` 直连 DeepSeek 的 Anthropic 兼容端点；接入扣子后，ACP wrapper 直接 spawn Claude Code 进程，模型调用仍受本地配置影响，但实际行为取决于 ACP wrapper 的实现——本地环境变量是否生效需要在实践中验证。

```
扣子云端 ←→ coze-bridge（npm 守护进程）←→ ACP wrapper（claude-agent-acp）←→ Claude Code
                ↑                              ↑
          WebSocket 隧道              JSON-RPC 2.0 ↔ CLI 调用互译
```

- **coze-bridge**：扣子提供的轻量桥接程序，在本地和扣子云端之间建立加密隧道
- **ACP wrapper**（`@agentclientprotocol/claude-agent-acp`）：翻译官角色——Claude Code 是 CLI 工具而非常驻服务，ACP wrapper 将其包装成能持续通信的 Agent 服务
- 数据流：你的代码/文件始终在本地，只有任务指令和执行结果在云端流转

### 接入步骤

1. 扣子网页点击 **新建 Agent → 接入本地 Agent**
2. 复制系统生成的连接命令（token 有效期 60 分钟，必须在此期间完成配对）
3. 在 WSL2 终端执行：
   ```bash
   npx -y --registry=https://registry.npmmirror.com coze-bridge@latest --pat-token=xxx --pair-code=xxx
   ```
4. 终端回显 `已配对连接完成，请返回到 coze 平台上点击"我已执行"` 表示配对成功
5. 回扣子点 **已粘贴执行**，系统自动扫描本地 Agent
6. 勾选 Claude Code（免费版限 1 个），设置名称，点击 **创建 Agent**

### 后台常驻（tmux 方案）

coze-bridge 是前台进程，关终端就断。用 tmux 让它后台常驻：

```bash
# 安装 tmux
sudo apt install tmux -y

# 创建后台会话并运行 bridge
tmux new -s coze-bridge
# 粘贴 bridge 命令，配对成功后：
# Ctrl+B → D 脱离会话（bridge 继续后台跑，关终端也不断）
```

日常开机后看一眼：`tmux attach -t coze-bridge`

### 断连重连

**不需要重新创建 Agent**，只需在扣子中操作：

1. 点 Agent 头像 → **Agent 设置 → 重新连接**
2. 复制新命令，进 WSL2 执行
3. 回扣子点 **我已执行**

> 电脑关机/休眠/断网会导致 bridge 断开，重新开机后按上述流程重连即可。

### 记忆机制

| 层 | 管理者 | 范围 |
|---|---|---|
| 会话上下文 | 扣子平台 | 同一条对话内历史消息自动传递 |
| CLAUDE.md 注入 | 扣子平台 | 从工作区读取，相当于出厂设定 |
| 长期记忆文件 | Claude Code 自己 | `~/.claude/projects/.../memory/`，跨会话存活 |

- **同一扣子对话内**：Claude Code 能"记住"之前说了什么（扣子把历史消息一起发过去）
- **新开扣子对话**：全新上下文，想跨会话回忆需依赖持久化记忆文件

> **Claude Code 自己的解释**（2026-07-01）：Coze 平台只管你能在聊天界面看到的内容（消息文本、session_id、CLAUDE.md），而工具调用结果、分析结论、运行时状态由 Claude Code 本地进程自行维护。这解释了为什么 coze-bridge 断连后同 session 内记忆不受影响——聊天历史在 Coze 后端，bridge 只是管道。但跨 session 或 Claude Code 进程被杀，就只有持久化记忆文件能救命。详见 [对话记录](https://www.coze.cn/s/6hqTvayhXz8/)。

### 常见坑

| 问题 | 解法 |
|------|------|
| Token 过期（"连接已过期"） | 点重新创建，生成新命令，60 分钟内执行 |
| 已配对但"自动识别"失败 | 检查 `@agentclientprotocol/claude-agent-acp` 是否已安装 |
| 终端路径警告 | 确保在 WSL2 内执行，不要在 Windows PowerShell/CMD 跑 |
| 同一对话内不记得之前内容 | 正常（扣子会传历史消息），见上方记忆机制说明；跨会话才需要写 CLAUDE.md 持久化 |

### 套餐限制

| 套餐 | 本地 Agent 数量 |
|------|----------------|
| 个人免费版 | 1 个（限时免费） |
| 个人进阶版 | 1 个 |
| 个人高阶版 | 3 个 |
| 个人旗舰版 | 10 个 |
| 个人尊享版 | 不限 |

### 参考

- [扣子本地 Agent 官方文档](https://docs.coze.cn/api/open/docs/cozespace/local_agent)
- [扣子常见问题 - 本地 Agent 掉线处理](https://docs.coze.cn/api/open/docs/cozespace/coze_app_faq#eda5f9ac)