升级指南

本文档提供 Claude Code SOLO 系统的版本升级指南，包括新功能介绍、破坏性变更说明和迁移步骤。

版本历史

v2.1.0 (当前版本) - 2024-01-15

🚀 新功能

智能状态检测：/solo 命令现在能够检测并避免重复工作
多维度状态分析：/solo__status 支持角色视图和仪表板模式
智能中断恢复：/solo__resume 提供深度分析和环境验证
风险评估切换：/solo__switch 包含安全检查和风险提示
增强的代理系统：新增 general-purpose 和 data-scientist 代理

🔧 改进

配置文件夹从 .claude/ 重命名为 claude-settings/
优化了代理协作机制和工具权限管理
改进了错误处理和用户反馈
增强了文档结构和安装指引

🐛 修复

修复了状态同步问题
解决了上下文污染问题
改进了并发代理的稳定性

⚠️ 破坏性变更

.claude/ 目录重命名为 claude-settings/
命令行参数格式调整
配置文件结构更新

v2.0.0 - 2023-12-01

🚀 重大更新

全新的 SOLO 四阶段工作流
专业化子代理系统
自定义命令支持
工作区状态持久化

⚠️ 破坏性变更

完全重写的命令系统
新的配置文件格式
代理接口变更

v1.x 版本

基础的 Claude Code 功能
简单的项目生成
基本的 TDD 支持

升级准备

升级前检查清单

bash

# 1. 检查当前版本
claude --version

# 2. 备份现有配置
cp -r .claude .claude.backup.$(date +%Y%m%d)
cp -r .solo .solo.backup.$(date +%Y%m%d)

# 3. 检查项目状态
git status
git stash  # 如果有未提交的更改

# 4. 检查依赖兼容性
npm list claude-code
pip list | grep claude-code

兼容性矩阵

SOLO 版本	Claude Code 版本	Node.js	Python	Java
v2.1.x	≥ 1.5.0	≥ 16.0	≥ 3.8	≥ 11
v2.0.x	≥ 1.3.0	≥ 14.0	≥ 3.7	≥ 8
v1.x	≥ 1.0.0	≥ 12.0	≥ 3.6	≥ 8

升级步骤

从 v2.0.x 升级到 v2.1.0

1. 更新 Claude Code

bash

# NPM 方式
npm update -g claude-code

# Homebrew 方式 (macOS)
brew upgrade claude-code

# 手动下载方式
curl -L https://github.com/anthropics/claude-code/releases/latest/download/claude-code-linux.tar.gz -o claude-code.tar.gz
tar -xzf claude-code.tar.gz
sudo mv claude-code /usr/local/bin/

2. 迁移配置文件

bash

# 自动迁移脚本
claude migrate --from=2.0 --to=2.1

# 手动迁移（如果自动迁移失败）
if [ -d ".claude" ]; then
    mv .claude claude-settings
    echo "配置目录已从 .claude/ 迁移到 claude-settings/"
fi

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

3. 更新项目配置

bash

# 更新 .gitignore
if grep -q "\.claude/" .gitignore; then
    sed -i 's/\.claude\//claude-settings\//g' .gitignore
fi

# 更新 CI/CD 配置
find .github -name "*.yml" -exec sed -i 's/\.claude\//claude-settings\//g' {} \;

4. 验证升级

bash

# 检查版本
claude --version

# 验证命令可用性
/solo --help
/solo__status --help
/solo__switch --help
/solo__resume --help

# 测试基本功能
/solo__status brief

从 v1.x 升级到 v2.1.0

这是一个重大版本升级，需要更多的迁移工作。

1. 全新安装

bash

# 卸载旧版本
npm uninstall -g claude-code-v1

# 清理旧配置
rm -rf ~/.claude-v1

# 安装新版本
npm install -g claude-code@latest

2. 项目重新初始化

bash

# 备份现有工作
mkdir migration-backup
cp -r src/ migration-backup/
cp -r test/ migration-backup/
cp package.json migration-backup/

# 初始化新的 SOLO 工作区
/solo "迁移现有项目：[描述你的项目]"

3. 代码和测试迁移

bash

# 逐步迁移代码
# 1. 先迁移核心业务逻辑
# 2. 然后迁移测试用例
# 3. 最后迁移配置文件

# 运行迁移验证
npm test
npm run build

新功能使用指南

智能状态检测

v2.1.0 的 /solo 命令现在更加智能：

bash

# 以前：总是重新开始整个流程
/solo "用户管理系统"

# 现在：自动检测已完成的工作，继续未完成的部分
/solo "用户管理系统"  # 自动检测到 PRD 已存在，直接进入架构设计阶段

检测逻辑：

检查 .solo/docs/PRD.md 是否存在且完整
检查 .solo/docs/PROJECT_PLAN.md 是否存在
检查源代码目录结构
检查测试覆盖率和质量指标

多维度状态分析

bash

# 新的状态分析选项
/solo__status brief           # 简要概览
/solo__status detailed        # 详细分析
/solo__status dashboard       # 可视化仪表板
/solo__status role:dev        # 开发者视角
/solo__status role:pm         # 产品经理视角
/solo__status role:qa         # QA 视角

智能中断恢复

bash

# 新的恢复选项
/solo__resume deep            # 深度分析后恢复
/solo__resume quick           # 快速恢复
/solo__resume verify          # 验证环境一致性
/solo__resume diagnose        # 诊断中断原因

增强的代理系统

bash

# 新增的代理
general-purpose    # 复杂任务协调和研究
data-scientist     # 数据分析和 ROI 计算

# 使用新代理
claude agent invoke general-purpose "复杂的多步骤任务"
claude agent invoke data-scientist "分析用户行为数据"

配置迁移详解

命令配置迁移

bash

# v2.0.x 配置位置
.claude/commands/solo.md
.claude/commands/solo__status.md

# v2.1.0 配置位置  
claude-settings/commands/solo.md
claude-settings/commands/solo__status.md

代理配置迁移

bash

# 旧的代理配置
.claude/agents/product-manager.md
.claude/agents/architect.md
.claude/agents/engineer.md
.claude/agents/qa-engineer.md

# 新的代理配置
claude-settings/agents/product-manager.md
claude-settings/agents/architect.md
claude-settings/agents/engineer.md
claude-settings/agents/qa-engineer.md
claude-settings/agents/general-purpose.md    # 新增
claude-settings/agents/data-scientist.md     # 新增
claude-settings/agents/code-reviewer.md      # 新增  
claude-settings/agents/debugger.md           # 新增

CLAUDE.md 迁移

markdown

# 旧的 CLAUDE.md 引用
- 配置目录：`.claude/`
- 命令目录：`.claude/commands/`
- 代理目录：`.claude/agents/`

# 新的 CLAUDE.md 引用  
- 配置目录：`claude-settings/`
- 命令目录：`claude-settings/commands/`
- 代理目录：`claude-settings/agents/`

故障排除

升级后常见问题

1. 命令不可用

bash

# 问题：/solo 命令无法识别
Error: Command '/solo' not found

# 解决方案
# 检查配置目录
ls -la claude-settings/commands/

# 刷新 Claude Code 配置
claude refresh

# 重新启动终端

2. 配置文件路径错误

bash

# 问题：找不到配置文件
Error: Configuration file not found at .claude/config.json

# 解决方案
# 检查是否完成了路径迁移
find . -name "*.md" -exec grep -l "\.claude/" {} \;

# 批量更新路径引用
find . -name "*.md" -exec sed -i 's/\.claude\//claude-settings\//g' {} \;

3. 代理权限问题

bash

# 问题：代理工具权限不足
Error: Agent 'engineer' does not have permission to use tool 'Bash'

# 解决方案
# 检查代理配置
cat claude-settings/agents/engineer.md

# 确保包含必要的工具权限
allowed-tools: ["Read", "Write", "Edit", "MultiEdit", "Bash", "Grep", "Glob", "TodoWrite"]

4. 工作区状态不一致

bash

# 问题：工作区状态与实际不符
Error: SOLO state inconsistent with project files

# 解决方案
# 重置工作区状态
/solo__resume verify

# 或强制重建状态
/solo__switch product --reset

回滚指南

如果升级后出现严重问题，可以回滚到之前版本：

bash

# 1. 恢复配置备份
rm -rf claude-settings/
mv .claude.backup.YYYYMMDD .claude

# 2. 降级 Claude Code 版本
npm install -g claude-code@2.0.15

# 3. 恢复 CLAUDE.md
git checkout HEAD~1 CLAUDE.md

# 4. 验证回滚
claude --version
/solo --help

未来升级计划

v2.2.0 (计划 2024-03-01)

🚀 多项目工作区支持
🔧 图形化配置界面
🎯 AI 辅助代码重构
📊 高级分析和报告

v3.0.0 (计划 2024-06-01)

🌐 云端工作区同步
🤝 实时团队协作
🔌 丰富的第三方集成
🎨 可视化工作流编辑器

功能预览

多项目工作区 (v2.2.0)

bash

# 管理多个项目
claude workspace create microservices-platform
claude workspace switch user-service
/solo "用户服务 API"

claude workspace switch order-service  
/solo "订单服务 API"

# 跨项目依赖分析
claude workspace analyze --dependencies

云端同步 (v3.0.0)

bash

# 同步工作区到云端
claude sync enable
claude sync push

# 团队成员同步
claude sync pull --team=backend-team

获取帮助

升级支持资源

升级最佳实践

总是备份：升级前备份所有配置和工作区
渐进升级：不要跨多个主版本升级
测试验证：升级后在测试项目中验证功能
团队同步：确保团队成员同时升级
文档更新：及时更新团队文档和流程

升级检查清单

markdown

## 升级后验证清单

### 基础功能
- [ ] Claude Code 版本正确
- [ ] 所有 SOLO 命令可用
- [ ] 配置文件路径正确
- [ ] 代理权限配置正常

### 项目功能
- [ ] 现有项目工作区正常
- [ ] 状态检测功能正常
- [ ] 代理协作正常
- [ ] 测试和构建正常

### 团队协作
- [ ] Git 集成正常
- [ ] CI/CD 管道正常
- [ ] 代码审查流程正常
- [ ] 文档生成正常

### 高级功能
- [ ] 性能监控正常
- [ ] 错误处理改进
- [ ] 新功能可用
- [ ] 自定义配置生效

重要提醒：升级是一个重要的操作，建议在非生产环境先进行测试，确认无问题后再在生产环境执行。如果遇到问题，可以随时参考本文档或联系支持团队。

升级指南 ​

版本历史 ​

v2.1.0 (当前版本) - 2024-01-15 ​

🚀 新功能 ​

🔧 改进 ​

🐛 修复 ​

⚠️ 破坏性变更 ​

v2.0.0 - 2023-12-01 ​

🚀 重大更新 ​

⚠️ 破坏性变更 ​

v1.x 版本 ​

升级准备 ​

升级前检查清单 ​

兼容性矩阵 ​

升级步骤 ​

从 v2.0.x 升级到 v2.1.0 ​

1. 更新 Claude Code ​

2. 迁移配置文件 ​

3. 更新项目配置 ​

4. 验证升级 ​

从 v1.x 升级到 v2.1.0 ​

1. 全新安装 ​

2. 项目重新初始化 ​

3. 代码和测试迁移 ​

新功能使用指南 ​

智能状态检测 ​

多维度状态分析 ​

智能中断恢复 ​

增强的代理系统 ​

配置迁移详解 ​

命令配置迁移 ​

代理配置迁移 ​

CLAUDE.md 迁移 ​

故障排除 ​

升级后常见问题 ​

1. 命令不可用 ​

2. 配置文件路径错误 ​

3. 代理权限问题 ​

4. 工作区状态不一致 ​

回滚指南 ​

未来升级计划 ​

v2.2.0 (计划 2024-03-01) ​

v3.0.0 (计划 2024-06-01) ​

功能预览 ​

多项目工作区 (v2.2.0) ​

云端同步 (v3.0.0) ​

获取帮助 ​

升级支持资源 ​

升级最佳实践 ​

升级检查清单 ​

升级指南

版本历史

v2.1.0 (当前版本) - 2024-01-15

🚀 新功能

🔧 改进

🐛 修复

⚠️ 破坏性变更

v2.0.0 - 2023-12-01

🚀 重大更新

⚠️ 破坏性变更

v1.x 版本

升级准备

升级前检查清单

兼容性矩阵

升级步骤

从 v2.0.x 升级到 v2.1.0

1. 更新 Claude Code

2. 迁移配置文件

3. 更新项目配置

4. 验证升级

从 v1.x 升级到 v2.1.0

1. 全新安装

2. 项目重新初始化

3. 代码和测试迁移

新功能使用指南

智能状态检测

多维度状态分析

智能中断恢复

增强的代理系统

配置迁移详解

命令配置迁移

代理配置迁移

CLAUDE.md 迁移

故障排除

升级后常见问题

1. 命令不可用

2. 配置文件路径错误

3. 代理权限问题

4. 工作区状态不一致

回滚指南

未来升级计划

v2.2.0 (计划 2024-03-01)

v3.0.0 (计划 2024-06-01)

功能预览

多项目工作区 (v2.2.0)

云端同步 (v3.0.0)

获取帮助

升级支持资源

升级最佳实践

升级检查清单