故障排查与最佳实践

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

---

安装问题

Node.js 版本要求

CodeBuddy Code 需要 Node.js v18.20 或更高版本。

node -v          # 检查版本

升级地址：https://nodejs.org/en/download/

Windows 平台

Git Bash 依赖

Windows 平台必须安装 Git Bash。

• 下载：https://git-scm.com/downloads/win
• 安装时勾选 "Git Bash" 组件

自定义路径（非标准安装位置）：

# CMD
set CODEBUDDY_CODE_GIT_BASH_PATH=C:\Program Files\Git\bin\bash.exe

# PowerShell
$env:CODEBUDDY_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"

"codebuddy 不是内部或外部命令"

npm 全局目录未加入 PATH。

npm config get prefix    # 查找安装路径

将路径添加到系统 PATH（默认：%USERPROFILE%\AppData\Roaming\npm），重启终端。

搜索工具 (Ripgrep)

CodeBuddy 自动处理 ripgrep 依赖，无需手动安装。如需最佳性能：

# macOS
brew install ripgrep

# Windows
choco install ripgrep

# Ubuntu/Debian
sudo apt install ripgrep

---

常见问题

额度共享

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

JetBrains IDE 中 ESC 键不生效

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

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

模型切换

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

---

更新

自动更新

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

手动更新

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

版本检查

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

---

从 Claude Code 迁移

迁移内容

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

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

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

# 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

# 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

方案二：复制文件

独立配置，互不影响。

# 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

# 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 支持一键安装，安装后自动加载。

验证迁移

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 轮不清理
• ✗ 重复粘贴已知代码

---

更多帮助：快速入门指南