更新升级
了解 Wesclaw 的版本管理、升级流程、数据迁移和兼容性处理，确保每次更新顺利进行。
版本历史
版本号规则
Wesclaw 使用语义化版本号 主版本.次版本.修订号：
| 版本号 | 含义 | 影响 |
|---|---|---|
| 主版本（X.0.0） | 重大更新，可能有不兼容变更 | 需要关注数据迁移 |
| 次版本（1.X.0） | 新功能添加，向后兼容 | 正常升级即可 |
| 修订号（1.0.X） | Bug 修复和小改进 | 建议及时更新 |
版本变更类型
| 标记 | 含义 |
|---|---|
| 🆕 新增 | 新功能或新特性 |
| 🔧 修复 | Bug 修复 |
| ⚡ 优化 | 性能或体验优化 |
| ⚠️ 变更 | 行为变更，需要注意 |
| 🔒 安全 | 安全漏洞修复 |
查看当前版本
桌面端：设置 → 关于 → 版本信息
命令行：wesclaw --version
升级流程
桌面端升级
自动更新（推荐）
Wesclaw 桌面端支持自动检查更新：
设置 → 关于 → 自动更新
☑ 自动检查更新
☑ 有新版本时提示安装
☐ 自动安装更新（需重启）
当有新版本时：
- 收到更新通知
- 点击「查看更新」了解版本变化
- 点击「立即更新」开始下载
- 下载完成后，应用会自动重启并安装
手动更新
- 前往官网下载最新版本安装包
- 关闭当前运行的 Wesclaw
- 运行新版本安装包
- 安装完成后启动
手动更新不会丢失数据。安装包会自动保留现有数据目录。
SaaS 版升级
SaaS 版自动升级，无需用户操作。后端服务更新时可能有短暂不可用（通常几分钟内完成）。
数据迁移
自动迁移
大多数版本升级时，数据迁移是自动完成的：
启动新版本
↓
检测数据库版本
↓
自动执行迁移脚本
↓
迁移成功 → 正常启动
↓ (失败)
归档旧数据 → 创建新数据库 → 启动（丢失应用层数据，引擎数据保留）
迁移机制
Wesclaw 使用 PRAGMA user_version 追踪数据库 schema 版本：
| 数据库 | 迁移方式 | 失败处理 |
|---|---|---|
wesclaw.db（应用数据） | MigrationStep 链 | 归档旧文件 → 新建 |
wesclaw_auth.db（登录） | CREATE IF NOT EXISTS | 重新登录 |
引擎数据库（cells/main/） | 引擎自动迁移 | 降级启动 |
引擎数据迁移
引擎侧（wesgine）的数据迁移由引擎自动处理：
sessions.db：会话和记忆数据state.db：运行时状态meta.db：Cell 元数据
引擎迁移的原则是Boot 永远成功——即使数据有损坏，也会降级启动，不会阻止你使用。
手动迁移场景
以下场景可能需要手动操作：
从旧版本（v0.x）升级到 v1.0：
# 使用内置迁移工具
wesclaw migrate v0.2-to-v1.0
# 迁移内容：
# - 旧 wesclaw.db → legacy-YYYYMMDD.db.bak
# - 创建新的 cells/main/ 结构
# - 搬迁技能和知识库文件
兼容性
系统兼容性
| 操作系统 | 最低版本 | 推荐版本 |
|---|---|---|
| macOS | 12 Monterey | 14 Sonoma+ |
| Windows | 10 (64-bit) | 11 |
| Ubuntu | 20.04 LTS | 22.04 LTS+ |
引擎兼容性
Wesclaw 桌面端内嵌 wesgine 引擎，版本对应关系：
Wesclaw 1.x → wesgine v1.0
引擎版本升级通常包含在 Wesclaw 更新中，无需单独升级。
数据兼容性
| 数据类型 | 向前兼容 | 向后兼容 |
|---|---|---|
| 对话记录 | ✅ 新版本能读旧数据 | ⚠️ 旧版本可能无法读新数据 |
| 记忆 | ✅ | ⚠️ |
| 技能 | ✅ | ✅（格式稳定） |
| 知识库 | ✅ | ✅ |
| 配置文件 | ✅（自动合并新字段） | ⚠️ |
Provider 兼容性
AI 模型 Provider 的 API 变更可能影响功能：
- Wesclaw 会尽快适配主流 Provider 的 API 变更
- 建议保持 Wesclaw 更新以获得最佳 Provider 支持
- 如遇到特定 Provider 不可用，检查是否需要更新
回滚方案
何时需要回滚
- 新版本有严重 Bug 影响正常使用
- 新版本与你的系统不兼容
- 新版本改变了你依赖的某个行为
回滚步骤
步骤一：备份当前数据
# 关闭 Wesclaw
cp -r ~/Library/Application\ Support/wesclaw/ ~/Desktop/wesclaw-current-backup/
步骤二：卸载当前版本
macOS：将 Wesclaw.app 移到废纸篓
Windows：控制面板 → 卸载程序 → Wesclaw
Linux：根据安装方式卸载
步骤三：安装旧版本
- 从官网下载历史版本安装包
- 安装旧版本
步骤四：恢复数据
# 如果旧版本能兼容当前数据，直接使用
# 如果不兼容，恢复之前的备份
cp -r ~/Desktop/wesclaw-old-backup/ ~/Library/Application\ Support/wesclaw/
回滚注意事项
-
引擎版本只升不降
- 引擎数据库 schema 可能已经升级
- 旧版引擎可能无法正确读取新 schema 的数据
- 建议在升级前备份
-
不要交叉使用
- 避免在同一数据目录上交替运行新旧版本
- 可能导致数据不一致
-
配置文件
- 新版本可能添加了新的配置项
- 旧版本会忽略不认识的配置项（不影响使用）
升级最佳实践
升级前
- 阅读更新说明：了解新版本的变更内容
- 备份数据：尤其是主版本升级时
- 检查兼容性：确认系统满足新版本要求
- 选择合适时间：避免在紧急工作时升级
升级时
- 关闭 Wesclaw：确保所有数据保存完毕
- 安装更新：按照提示完成安装
- 等待迁移：首次启动可能需要执行数据迁移
- 验证功能：检查核心功能是否正常
升级后
- 检查设置：确认设置没有被重置
- 测试对话：发送一条消息确认 AI 正常工作
- 检查渠道：如果配置了 IM 渠道，确认渠道正常
- 清理旧文件：确认一切正常后，可以删除旧备份
常见升级问题
升级后启动失败
排查：
- 查看崩溃日志
crashes/目录 - 检查数据库迁移是否成功
- 尝试清理缓存后重启
- 如无法解决，回滚到上一版本
升级后数据丢失
可能原因：
- 应用层数据库迁移失败，被归档为
.migration-failed文件 - 引擎数据不受影响
恢复：
# 查看是否有迁移失败的归档
ls ~/Library/Application\ Support/wesclaw/db/*.migration-failed
# 如果有，可以尝试手动恢复
cp wesclaw.db.migration-failed wesclaw.db
升级后配置丢失
新版本会自动合并（deep-merge）配置文件。如果某些设置丢失：
- 检查
config.yaml是否被覆盖 - 新增的配置项会使用默认值
- 如有旧配置备份，可以手动合并
自动更新失败
现象：更新通知显示后，下载或安装失败。
解决：
- 检查磁盘空间是否充足（至少需要 500MB 可用空间）
- 检查网络连接
- 尝试手动下载安装包更新
- macOS 用户确认 Wesclaw 有写入
/Applications/的权限
版本支持策略
| 版本类别 | 支持期限 | 说明 |
|---|---|---|
| 最新版本 | 持续支持 | 所有 Bug 修复和新功能 |
| 上一个次版本 | 安全补丁 | 仅修复安全漏洞 |
| 更早版本 | 不再支持 | 建议尽快升级 |
始终建议使用最新版本以获得最佳体验和安全保障。