# 故障排查与最佳实践

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


## 常见问题

### 额度共享

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` — 接受所有网络连接

---

## 权限确认框无响应 / ESC 才能关

**症状**：TUI 弹出工具权限确认框，按数字键 / 回车确认后弹框不消失，但 ESC 能正常关闭，且关闭后任务实际已在执行。

### 日志位置

```bash
ls -t ~/.codebuddy/logs/codebuddy-*.log | head -1   # 最新一份
```

可通过 `CODEBUDDY_CONFIG_DIR` 环境变量整体迁移配置目录。

### 关键 TAG（按时序）

正常确认走完应该看到这一串（`grep -E '\[Approve\]|\[Reject\]|\[dequeue\]|\[tool-permission\]'`）：

| TAG | 含义 |
|---|---|
| `[tool-permission] ASK ...` | 工具被拦下来要审批 |
| `[HandleInterruptions] Approval dialog shown` | TUI 已显示弹框 |
| `[Approve] User approved tool: <name>` | 用户点了确认 |
| `[Approve] Deferred resolved` | 后端 promise 已 resolve（任务此时开始执行）|
| `[dequeue] Queue empty, clearing interruptionSubject` | `pending$` 清空，弹框应消失 |
| `[Approve] Success: ... interruption dequeued` | 全流程结束 |

ESC 路径把 `[Approve]` 替换为 `[Reject]`。

### 现象 → 推断

| 看到 | 推断 |
|---|---|
| 整套 TAG 都有但弹框不消失 | UI 渲染卡住（如 IDE closeTab RPC 阻塞 await）|
| 有 `[Approve] User approved` 但缺 `[dequeue]` | `findSessionByItem` 失败，附近会有 `[Approve] Failed: Cannot find session` |
| 有 `dequeue Start` 但没 `Queue empty` | `interruptionQueues` 拿不到队列（多 session 错位）|
| 完全没有 `[tool-permission] ASK` | 该工具未走审批，可能 `BypassPermissions` 或被 allow 规则放行 |
| 有 `[tool-permission] ASK` 但没 `Approval dialog shown` | TUI 没订阅到 `pending$`（teammate 并发 session 错位）|
| `[Approve] Failed: No pending deferred found` | deferred 被重复消费 |

### 反馈给开发的最小信息

`[Approve]` / `[Reject]` / `[dequeue]` 三个 TAG 出现时间附近的连续 30 行日志即可定位是 UI 没刷、后端没出队、还是 IDE RPC 卡住。

---

## 更新

### 自动更新

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

### 手动更新

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

### 版本检查

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

### 更新不到最新版

如果 `codebuddy update` 或 `npm install -g @tencent-ai/codebuddy-code@latest` 始终拉取不到最新版本，通常是 npm 镜像源缓存延迟所致。可指定官方源重试：

```bash
npm install -g @tencent-ai/codebuddy-code@latest --registry=https://registry.npmjs.org/
```

确认本地 npm 配置的镜像源：

```bash
npm config get registry
```

若长期使用第三方镜像，可在更新命令中临时指定官方源，无需修改全局配置。

---

## 从 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)
