📋 阶段八：全套避坑清单 + 能力验收体系

#1 CRITICAL claude: command not found

现象：终端输入 claude 提示命令不存在

根因：npm 全局 bin 目录不在 PATH 中；或未安装

🔧 修复方案：

# 诊断
npm bin -g                           # 查看 npm bin 路径
echo $PATH | grep "$(npm bin -g)"    # 检查是否在 PATH 中

# 修复（临时）
export PATH="$(npm bin -g):$PATH"

# 修复（永久）
echo "export PATH=\"$(npm bin -g):\$PATH\"" >> ~/.bashrc
source ~/.bashrc

# 如果未安装
npm install -g @anthropic-ai/claude-code

#2 CRITICAL Node.js version too old

现象：安装时提示 Node.js < 18

🔧 修复方案：

# 检查当前版本
node --version

# 升级（NodeSource 方式）
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# 或使用 nvm
nvm install 20 && nvm use 20 && nvm alias default 20

#3 CRITICAL Permission denied (EACCES)

现象：npm 全局安装时报 EACCES 权限错误

🔧 修复方案：

# 方案A：修复 npm 全局目录权限（推荐）
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm install -g @anthropic-ai/claude-code

# 方案B：使用 sudo（不推荐，可能引发其他权限问题）
sudo npm install -g @anthropic-ai/claude-code

#4 HIGH Authentication failed / Invalid API key

现象：执行 claude 命令时报认证失败

🔧 修复方案：

# 检查登录状态
claude whoami

# 重新登录
claude logout && claude login

# 检查 API 密钥格式（必须以 sk-ant-api03- 开头）
echo $ANTHROPIC_API_KEY | cut -c1-20

# 重新设置 API 密钥
export ANTHROPIC_API_KEY="sk-ant-api03-你的密钥"
# 确认设置成功
echo $ANTHROPIC_API_KEY

#5 HIGH Context window overflow (上下文溢出)

现象：长对话中 Claude 响应截断、报错、或"失忆"

🔧 修复方案：

# 方案1：压缩上下文（保留关键信息）
/compact

# 方案2：清空重来
/clear

# 方案3：新建会话
/exit
claude   # 重新启动

# 预防：
# - 创建 .claudeignore 过滤无关文件
# - 控制单次会话范围，一个会话一个模块
# - 定期使用 /cost 检查 token 使用量

#6 HIGH npm network timeout / fetch failed

现象：npm install 超时或连接失败

🔧 修复方案：

# 切换到国内镜像
npm config set registry https://registry.npmmirror.com

# 或临时使用
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

# 增加超时时间
npm config set timeout 120000

# 清除缓存重试
npm cache clean --force
npm install -g @anthropic-ai/claude-code

#7 MEDIUM Tool call permission denied

现象：Claude 尝试执行操作时被权限系统拒绝

🔧 修复方案：

# 查看当前权限配置
cat ~/.claude/settings.json

# 手动添加允许规则
# 编辑 settings.json，在 permissions.allow 中添加对应规则
# 例如允许 npm test：
# "Bash(npm:test)"

# 或使用 /permissions 命令在交互模式中管理

#8 MEDIUM Module not found after update

现象：升级后执行 claude 报 Cannot find module

🔧 修复方案：

# 彻底重装
npm uninstall -g @anthropic-ai/claude-code
npm cache clean --force
npm install -g @anthropic-ai/claude-code

# 清理残留
sudo rm -f /usr/local/bin/claude /usr/bin/claude 2>/dev/null
claude --version

#9 MEDIUM File not found in project scope

现象：Claude 看不到某些文件

🔧 修复方案：

# 检查是否在正确的目录启动
pwd

# 检查文件权限
ls -la <文件名>

# 检查 .claudeignore 或 .gitignore
cat .claudeignore 2>/dev/null
cat .gitignore 2>/dev/null

# 手动让 Claude 读取
/read <文件路径>

#10 MEDIUM Write/Edit failed (文件写入失败)

现象：Claude 修改文件时报错

🔧 修复方案：

# 检查父目录是否存在
ls -la "$(dirname <目标文件>)"

# 检查文件权限
ls -la <目标文件>

# 检查磁盘空间
df -h .

# 如果文件是只读的
chmod +w <目标文件>

#11 MEDIUM .bashrc changes not taking effect

现象：修改 ~/.bashrc 后 PATH 仍不生效

🔧 修复方案：

# 必须执行 source
source ~/.bashrc

# 或重新登录
exit  # 退出 SSH
ssh user@server  # 重新连接

# 如果使用 zsh，应该改 ~/.zshrc
echo $SHELL  # 查看你用的什么 shell

# 确认配置已写入
grep "claude\|npm.*global" ~/.bashrc

#12 HIGH SSH session killed mid-task

现象：SSH 断开导致 Claude 任务中断

🔧 修复方案：

# 预防方案1：使用 tmux（推荐）
tmux new -s claude-session
claude
# Ctrl+B, D 分离
# tmux attach -t claude-session 重新连接

# 预防方案2：使用 screen
screen -S claude
claude
# Ctrl+A, D 分离
# screen -r claude 重新连接

# 预防方案3：使用 nohup（后台运行）
nohup claude -p "长任务描述" > task-output.txt 2>&1 &

#13 MEDIUM Rate limit / Too many requests

现象：报 429 Too Many Requests

🔧 修复方案：

# 等待 30-60 秒后重试
# 减少并发请求
# 如果是 API 密钥模式，检查用量配额
# 升级 API plan 或切换到 Pro 订阅

#14 MEDIUM Output truncated mid-response

现象：Claude 回复到一半突然截断

🔧 修复方案：

# 让 Claude 继续
/continue
# 或简写
/c

# 如果是 token 限制，先压缩上下文
/compact
# 然后重新提问

#15 HIGH Git conflicts caused by Claude edits

现象：Claude 做的修改与 git 状态冲突

🔧 修复方案：

# 查看当前 git 状态
git status
git diff

# 如果改动满意，提交
git add -A && git commit -m "changes by Claude"

# 如果改动不满意，回退
git checkout -- .  # 回退所有未暂存的修改
git reset --hard HEAD  # 完全回退到上次提交

# 预防：修改前创建分支
git checkout -b claude-experiment

#16 MEDIUM Package lock / node_modules corrupt

现象：npm 安装后 claude 行为异常

🔧 修复方案：

# 清理并重装
npm uninstall -g @anthropic-ai/claude-code
rm -rf $(npm root -g)/@anthropic-ai/claude-code
npm cache clean --force
npm install -g @anthropic-ai/claude-code

#17 MEDIUM Claude can't see newly created files

现象：新创建的文件 Claude 看不到

🔧 修复方案：

# 使用 /add-dir 手动添加
/add-dir <目录路径>

# 或让 Claude 重新扫描
"请重新扫描当前目录的文件结构"

# 检查 .claudeignore 是否误过滤
cat .claudeignore

#18 HIGH Accidental file deletion / overwrite

现象：Claude 误删或覆盖了重要文件

🔧 修复方案：

# 立即使用 /undo
/undo

# 使用 git 恢复
git checkout -- <文件名>
git log  # 查看历史

# 使用 /checkpoint 恢复快照
/checkpoint --list
/checkpoint --restore <snapshot-id>

# 预防：在 settings.json 中限制 Write/Edit
# "deny": ["Write(**)", "Edit(**)"]
# 需要时再放开

#19 MEDIUM Interactive mode input issues

现象：交互模式下输入异常、多行粘贴格式错乱

🔧 修复方案：

# 多行输入：用 Shift+Enter 换行
# 粘贴多行代码：用 ``` 包裹
# 特殊字符：用单引号包裹

# 如果交互界面卡死：
# Ctrl+C 中断当前操作
# Ctrl+D 退出
# 然后重新启动 claude

#20 MEDIUM WSL2 specific: PATH issues with Windows

现象：WSL2 下安装后 claude 命令可用但行为异常

🔧 修复方案：

# WSL2 特别注意：
# 1. 不要在 /mnt/c/ 下操作项目（性能差，权限问题）
# 2. 项目放 ~/ 下（Linux 原生文件系统）
# 3. 确保 npm 安装在 WSL 内部（不要用 Windows 的 npm）

# WSL2 环境验证
echo $HOME  # 应该是 /home/xxx 而不是 /mnt/c/...
df -h .     # 确认用的不是 drvfs
which node  # 应该在 /usr/ 或 ~/.nvm/ 下