# 故障排查与最佳实践

本文档涵盖常见问题解决方案和使用优化建议。


## 常见问题

### 额度共享

CLI、CodeBuddy IDE 和 CodeBuddy Plugin 共享同一账号的资源配额。

### JetBrains IDE 中 ESC 键不生效

JetBrains 终端对 ESC 键处理不同，改用 `Ctrl+ESC` 或 `Shift+ESC`。

| 操作 | 标准终端 | JetBrains 终端 |
|-----|---------|---------------|
| 退出/取消 | `ESC` | `Ctrl+ESC` 或 `Shift+ESC` |

### 模型切换

```
/model              # 交互式选择
/model [模型名称]    # 直接切换
/status             # 查看当前模型
```

### --serve 模式网络访问问题

#### 局域网 IP 访问报 `ERR_EMPTY_RESPONSE`

**症状**：使用 `codebuddy --serve` 启动后，通过局域网 IP（如 `http://10.31.110.26:52477`）访问时，浏览器报 `ERR_EMPTY_RESPONSE`（未发送任何数据）。

**原因**：HTTP 服务默认监听 `127.0.0.1`（本地回环地址），只接受本机连接。使用局域网 IP 访问时，请求到达了机器但被服务拒绝。

**解决方案**：启动时添加 `--host 0.0.0.0` 参数，使服务监听所有网络接口：

```bash
codebuddy --serve --host 0.0.0.0 --port 8080
```

> 非回环地址启动时会自动启用密码认证，密码在控制台输出中可见。

#### 确认服务监听状态

可以通过以下命令检查服务是否正确监听：

```bash
# macOS / Linux
lsof -i :PORT_NUMBER

# 或
netstat -an | grep PORT_NUMBER
```

- 若显示 `127.0.0.1:PORT` — 只接受本机连接
- 若显示 `0.0.0.0:PORT` 或 `*:PORT` — 接受所有网络连接

---

## 更新

### 自动更新

默认开启，下次启动时自动应用新版本。通过 `/config` 管理开关。

### 手动更新

```bash
codebuddy update                                    # 内置命令（推荐）
npm install -g @tencent-ai/codebuddy-code@latest   # npm 更新
```

### 版本检查

```bash
codebuddy --version                                 # 当前版本
npm view @tencent-ai/codebuddy-code version        # 最新版本
```

---

## 从 Claude Code 迁移

### 迁移内容

| 目录/文件 | 说明 |
|----------|------|
| `agents/` | 自定义 agents 配置 |
| `commands/` | 斜杠命令定义 |
| `skills/` | 专业技能定义 |
| `CLAUDE.md` → `CODEBUDDY.md` | AI 指令和记忆文档 |

### 方案一：符号链接（推荐）

共享配置，修改一处两边生效。

```bash
# macOS/Linux
cd ~/.codebuddy
ln -s ~/.claude/agents agents
ln -s ~/.claude/commands commands
ln -s ~/.claude/skills skills
ln -s ~/.claude/CLAUDE.md CODEBUDDY.md
```

```powershell
# Windows (需管理员权限)
cd $env:USERPROFILE\.codebuddy
New-Item -ItemType SymbolicLink -Path agents -Target $env:USERPROFILE\.claude\agents
New-Item -ItemType SymbolicLink -Path commands -Target $env:USERPROFILE\.claude\commands
New-Item -ItemType SymbolicLink -Path skills -Target $env:USERPROFILE\.claude\skills
New-Item -ItemType SymbolicLink -Path CODEBUDDY.md -Target $env:USERPROFILE\.claude\CLAUDE.md
```

### 方案二：复制文件

独立配置，互不影响。

```bash
# macOS/Linux
cp -r ~/.claude/agents ~/.codebuddy/agents
cp -r ~/.claude/commands ~/.codebuddy/commands
cp -r ~/.claude/skills ~/.codebuddy/skills
cp ~/.claude/CLAUDE.md ~/.codebuddy/CODEBUDDY.md
```

```powershell
# Windows
Copy-Item -Recurse $env:USERPROFILE\.claude\agents $env:USERPROFILE\.codebuddy\agents
Copy-Item -Recurse $env:USERPROFILE\.claude\commands $env:USERPROFILE\.codebuddy\commands
Copy-Item -Recurse $env:USERPROFILE\.claude\skills $env:USERPROFILE\.codebuddy\skills
Copy-Item $env:USERPROFILE\.claude\CLAUDE.md $env:USERPROFILE\.codebuddy\CODEBUDDY.md
```

### 插件 Skills 一键安装

Claude Code 插件中的 Skills 支持一键安装，安装后自动加载。

### 验证迁移

```bash
codebuddy         # 启动
/skills           # 检查 Skills
/config           # 查看配置
```

---

## 成本优化

### 核心原则

- 新任务用 `/clear` 开启新会话
- 长对话用 `/compact` 压缩历史
- 用 `@filename` 引用文件，避免粘贴代码

### 会话管理命令

| 命令 | 功能 |
|-----|------|
| `/cost` | 查看 Token 消耗 |
| `/clear` | 开启新会话 |
| `/compact` | 压缩历史 |
| `/resume` | 恢复旧对话 |

### 成本对比

| 方式 | 输入 Token | 相对成本 |
|-----|-----------|---------|
| 单会话连续 10 个任务 | ~50,000 | 高 |
| 每个任务新会话 | ~15,000 | 低 |
| 定期 `/compact` | ~25,000 | 中 |

### 推荐做法

- ✓ 新任务开新会话
- ✓ 每 20-30 轮用 `/compact`
- ✓ 用 `@filename` 引用文件
- ✓ 精简提问

### 避免做法

- ✗ 同一会话处理多个无关任务
- ✗ 对话超过 30 轮不清理
- ✗ 重复粘贴已知代码

---

**更多帮助**：[快速入门指南](./quickstart.md)
