故障排除

本文档提供 Claude Code SOLO 系统的常见问题解决方案和调试指南。

快速诊断

系统健康检查

bash

# 一键诊断
/solo__status diagnose

# 详细系统信息
/solo__status detailed --include-env

输出示例：

🔍 SOLO 系统诊断报告
═══════════════════════════════════════

✅ Claude Code 连接正常
✅ SOLO 工作区结构完整
✅ 所有代理配置有效
⚠️  发现 3 个潜在问题

问题详情：
1. .solo/contexts/ 目录权限不正确 (755 → 700)
2. engineer 代理超时配置过低 (30s → 推荐 60s)
3. git 状态不同步，有未提交更改

建议修复命令：
chmod 700 .solo/contexts/
claude config set agents.engineer.timeout 60000
git status

安装问题

1. 命令不可用

问题：/solo 命令无法识别

Error: Command '/solo' not found

解决方案：

bash

# 检查安装
ls -la claude-settings/commands/
ls -la ~/.claude/

# 重新安装命令
cp claude-docs/commands/* claude-settings/commands/
cp claude-docs/agents/* claude-settings/agents/

# 验证安装
claude refresh

2. 权限问题

问题：文件权限被拒绝

Error: Permission denied: '.solo/config/solo-settings.json'

解决方案：

bash

# 修复 .solo 目录权限
chmod -R 755 .solo/
chmod 700 .solo/contexts/
chmod 600 .solo/.solo-metadata.json

# 修复 claude-settings 权限
chmod -R 755 claude-settings/
chmod 644 claude-settings/commands/*.md
chmod 644 claude-settings/agents/*.md

3. 路径配置问题

问题：找不到配置文件

Error: CLAUDE.md not found in expected location

解决方案：

bash

# 检查路径配置
cat CLAUDE.md | grep -E "claude-settings|\.claude"

# 更新路径引用
sed -i 's/\.claude\//claude-settings\//g' CLAUDE.md

# 验证配置
claude config validate

运行时问题

1. 代理超时

问题：代理执行超时

Error: Agent 'engineer' timed out after 30000ms

解决方案：

bash

# 增加超时时间
claude config set agents.engineer.timeout 60000

# 或在 .solo/config/solo-settings.json 中设置
{
  "agents": {
    "engineer": {
      "timeout": 60000
    }
  }
}

2. 上下文污染

问题：代理响应不相关或重复之前的内容

解决方案：

bash

# 清理工作上下文
rm -rf .solo/contexts/*

# 重置当前会话
/solo__switch product --reset

# 或使用恢复命令重新开始
/solo__resume deep

3. 内存不足

问题：处理大型项目时出现内存错误

Error: Out of memory while processing large codebase

解决方案：

bash

# 减少并发代理数量
claude config set concurrency.maxAgents 1

# 启用增量处理模式
claude config set processing.incremental true

# 清理临时文件
rm -rf .solo/temp/

# 使用文件过滤
echo "node_modules/\ntarget/\nbuild/" > .solo/.gitignore

工作流问题

1. 阶段切换失败

问题：无法从一个阶段切换到另一个阶段

Error: Cannot switch from 'product' to 'architect': incomplete deliverables

解决方案：

bash

# 检查当前阶段状态
/solo__status brief

# 查看缺失的交付物
/solo__status detailed --include-deliverables

# 强制切换（谨慎使用）
/solo__switch architect --force

# 或完成当前阶段工作
/solo  # 继续当前阶段工作

2. 状态不同步

问题：系统状态与实际工作不匹配

解决方案：

bash

# 同步状态
/solo__resume verify

# 重建状态
/solo__status refresh

# 手动修复状态文件
edit .solo/.solo-metadata.json

3. 重复工作

问题：代理重复执行已完成的任务

解决方案：

bash

# 检查状态检测机制
/solo__status brief --show-completed

# 更新完成状态
# 编辑 .solo/.solo-metadata.json
{
  "completedTasks": [
    "prd-creation",
    "api-design", 
    "database-schema"
  ]
}

# 使用智能恢复
/solo__resume quick

性能问题

1. 响应缓慢

问题：代理响应时间过长

诊断：

bash

# 检查系统资源
/solo__status performance

# 查看代理执行时间
cat .solo/logs/performance.log

解决方案：

bash

# 优化配置
claude config set model "claude-3.5-sonnet"  # 使用更快的模型
claude config set maxTokens 2048              # 减少 token 限制
claude config set processing.parallel true    # 启用并行处理

# 清理缓存
rm -rf .solo/cache/

2. 频繁 API 调用

问题：超出 API 速率限制

解决方案：

bash

# 启用请求缓存
claude config set cache.enabled true
claude config set cache.ttl 3600

# 增加请求间隔
claude config set rateLimit.delay 1000

# 使用批处理模式
claude config set processing.batchSize 5

数据问题

1. 工作区损坏

问题：.solo 目录结构损坏

诊断：

bash

# 检查目录结构
find .solo -type f -name "*.json" | xargs -I {} sh -c 'echo "=== {} ===" && jq . {} || echo "Invalid JSON"'

修复：

bash

# 备份现有数据
cp -r .solo .solo.backup.$(date +%Y%m%d_%H%M%S)

# 重建工作区结构
/solo__switch product --rebuild

# 从备份恢复关键数据
cp .solo.backup.*/docs/* .solo/docs/ 2>/dev/null || true

2. 元数据不一致

问题：.solo-metadata.json 内容不正确

解决方案：

bash

# 验证元数据
jq . .solo/.solo-metadata.json

# 重建元数据
rm .solo/.solo-metadata.json
/solo__status refresh

3. 配置文件损坏

问题：配置文件格式错误

解决方案：

bash

# 验证配置文件
claude config validate

# 恢复默认配置
claude config reset --create-backup

# 从模板重建
cp claude-docs/config-templates/default.json .solo/config/solo-settings.json

集成问题

1. Git 集成问题

问题：Git 操作失败

解决方案：

bash

# 检查 Git 状态
git status
git config --list | grep user

# 修复 Git 配置
git config user.name "Your Name"
git config user.email "your.email@example.com"

# 解决冲突
git add .
git commit -m "Resolve SOLO integration conflicts"

2. IDE 集成问题

问题：IDE 无法识别 SOLO 配置

解决方案：

bash

# 生成 IDE 配置
/solo__status export --format=vscode
/solo__status export --format=intellij

# 添加到 .gitignore
echo "claude-settings/\n.solo/" >> .gitignore

3. CI/CD 集成问题

问题：持续集成管道失败

解决方案：

yaml

# .github/workflows/solo-check.yml
name: SOLO Quality Check
on: [push, pull_request]
jobs:
  solo-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Validate SOLO structure
        run: |
          test -f CLAUDE.md
          test -d claude-settings
          test -f .solo/.solo-metadata.json || echo "No active SOLO workspace"

调试技巧

1. 启用详细日志

bash

# 全局启用调试
claude config set debug.enabled true
claude config set debug.level "debug"

# SOLO 特定调试
export SOLO_DEBUG=true
export SOLO_LOG_LEVEL=debug

2. 检查系统环境

bash

# 环境信息
/solo__status system

# 依赖检查  
claude doctor

# 网络连接测试
curl -I https://api.anthropic.com/v1/health

3. 性能分析

bash

# 启用性能监控
claude config set performance.monitoring true

# 查看性能报告
cat .solo/logs/performance-$(date +%Y%m%d).log

# 分析瓶颈
grep "slow" .solo/logs/*.log

获取帮助

1. 内置帮助

bash

# Claude Code 帮助
claude --help

# SOLO 特定帮助
/solo --help
/solo__status --help
/solo__switch --help
/solo__resume --help

2. 生成支持报告

bash

# 生成完整诊断报告
/solo__status diagnose --export > solo-diagnostic-report.txt

# 包含系统信息
/solo__status system --include-env >> solo-diagnostic-report.txt

# 匿名化敏感信息
sed -i 's/your-api-key/[REDACTED]/g' solo-diagnostic-report.txt

3. 社区支持

4. 企业支持

如果您是企业用户，可以通过以下方式获得优先支持：

企业支持邮箱：enterprise-support@anthropic.com
支持工单系统：支持门户
专属客户成功经理

预防措施

1. 定期维护

bash

# 每周执行
claude config cleanup
/solo__status health-check

# 每月执行
claude config optimize
/solo maintenance

2. 备份策略

bash

# 自动备份配置
claude config set backup.enabled true
claude config set backup.interval "daily"
claude config set backup.retention 30

# 手动备份
cp -r .solo .solo.backup.$(date +%Y%m%d)
cp -r claude-settings claude-settings.backup.$(date +%Y%m%d)

3. 监控设置

bash

# 启用健康监控
claude config set monitoring.enabled true
claude config set monitoring.alerts true

# 设置告警阈值
claude config set monitoring.thresholds.responseTime 5000
claude config set monitoring.thresholds.errorRate 0.1

常见错误代码

错误代码	描述	解决方案
SOLO_001	工作区初始化失败	检查目录权限，重新初始化
SOLO_002	代理配置无效	验证 agents 配置文件
SOLO_003	阶段切换被阻止	完成当前阶段或使用 --force
SOLO_004	上下文存储失败	检查磁盘空间和权限
SOLO_005	API 调用失败	验证网络连接和 API 密钥
SOLO_006	状态同步错误	使用 /solo__resume verify
SOLO_007	配置文件损坏	恢复备份或重建配置
SOLO_008	内存不足	增加系统内存或启用增量模式
SOLO_009	权限被拒绝	检查文件和目录权限
SOLO_010	版本不兼容	升级到兼容版本

如果您遇到本文档未涵盖的问题，请通过 GitHub Issues 报告，我们会及时更新文档。

故障排除 ​

快速诊断 ​

系统健康检查 ​

安装问题 ​

1. 命令不可用 ​

2. 权限问题 ​

3. 路径配置问题 ​

运行时问题 ​

1. 代理超时 ​

2. 上下文污染 ​

3. 内存不足 ​

工作流问题 ​

1. 阶段切换失败 ​

2. 状态不同步 ​

3. 重复工作 ​

性能问题 ​

1. 响应缓慢 ​

2. 频繁 API 调用 ​

数据问题 ​

1. 工作区损坏 ​

2. 元数据不一致 ​

3. 配置文件损坏 ​

集成问题 ​

1. Git 集成问题 ​

2. IDE 集成问题 ​

3. CI/CD 集成问题 ​

调试技巧 ​

1. 启用详细日志 ​

2. 检查系统环境 ​

3. 性能分析 ​

获取帮助 ​

1. 内置帮助 ​

2. 生成支持报告 ​

3. 社区支持 ​

4. 企业支持 ​

预防措施 ​

1. 定期维护 ​

2. 备份策略 ​

3. 监控设置 ​

常见错误代码 ​

故障排除

快速诊断

系统健康检查

安装问题

1. 命令不可用

2. 权限问题

3. 路径配置问题

运行时问题

1. 代理超时

2. 上下文污染

3. 内存不足

工作流问题

1. 阶段切换失败

2. 状态不同步

3. 重复工作

性能问题

1. 响应缓慢

2. 频繁 API 调用

数据问题

1. 工作区损坏

2. 元数据不一致

3. 配置文件损坏

集成问题

1. Git 集成问题

2. IDE 集成问题

3. CI/CD 集成问题

调试技巧

1. 启用详细日志

2. 检查系统环境

3. 性能分析

获取帮助

1. 内置帮助

2. 生成支持报告

3. 社区支持

4. 企业支持

预防措施

1. 定期维护

2. 备份策略

3. 监控设置

常见错误代码