升级与更新
本文介绍 Wesclaw 的版本更新流程、v0.2 到 v1.0 迁移指南、数据兼容性说明和回滚方案。
版本更新流程
桌面版更新
自动更新（推荐）
Wesclaw 桌面版内置自动更新机制：
- 启动时自动检查新版本
- 发现新版本后，后台下载更新包
- 下载完成后提示用户安装
- 点击「立即更新」，应用重启完成更新
更新过程中的数据安全：更新时会等待 Go 后端安全关闭（释放数据库锁和 WAL checkpoint），确保数据完整性。
手动更新
如果自动更新不可用：
- 从官方网站下载最新版本
- 关闭当前运行的 Wesclaw
- 安装新版本（覆盖安装）
- 启动新版本
# macOS：下载新版 DMG 后
# 1. 关闭 Wesclaw
# 2. 将新版本拖入应用程序文件夹（替换旧版本）
# 3. 重新打开
Linux 更新
# Debian / Ubuntu
sudo dpkg -i wesclaw_latest_amd64.deb
# AppImage 模式
# 下载新的 AppImage 替换旧文件即可
云端版更新
云端版由服务端自动更新，用户无需操作。刷新浏览器页面即可使用最新版本。
v0.2 到 v1.0 迁移
架构变化概述
v1.0 是一次重大架构升级：
| 变化 | v0.2 | v1.0 |
|---|---|---|
| 引擎架构 | 单实例 wesgine.New() | Hypervisor + Cell 二层 |
| 数据隔离 | 所有数据在同一个实例 | 每个 Cell 独立隔离 |
| 外设管理 | 引擎级 Attach | CellSpec 声明式 per-Cell |
| Provider | 全局共享 | Cell 内独立配置 |
| 用户身份 | OwnerID | Actor（一等字段） |
| 治理模式 | 无 | govern-v2（open / locked） |
自动迁移
Wesclaw v1.0 包含自动迁移工具。首次启动 v1.0 时，会自动执行：
- 检测旧数据：扫描 v0.2 数据目录
- 提示迁移：告知用户将要执行的迁移操作
- 执行迁移：自动完成数据转换
- 验证结果：确认迁移成功
手动迁移
如果自动迁移失败或需要手动控制，可以使用迁移命令：
# 查看迁移计划（不执行）
wesclaw migrate v0.2-to-v1.0 --dry-run
# 执行迁移
wesclaw migrate v0.2-to-v1.0
# 强制在已 v1.0 化的目录上重跑
wesclaw migrate v0.2-to-v1.0 --force
迁移内容
| 数据 | 迁移方式 | 说明 |
|---|---|---|
| 对话历史 | 自动迁移 | 从 wesclaw.db 迁移到新结构 |
| AI 记忆 | 自动迁移 | 迁移到 Cell 内存储 |
| 技能 | 重新安装 | 技能目录迁移到 cells/main/skills/ |
| 知识库 | 目录搬迁 | 移至 cells/main/knowledge/ |
| 登录凭证 | 保留 | 保留在 db/wesclaw.db |
| 模型配置 | 需手动 | API Key 需重新配置 |
迁移前准备
- 备份数据：在迁移前备份整个数据目录
cp -r ~/Library/Application\ Support/wesclaw/ ~/wesclaw-v0.2-backup/
-
记录当前配置：
- 已配置的模型和 API Key
- IM 渠道配置（企业微信等）
- 定时任务设置
-
确认磁盘空间：迁移过程中需要额外空间存储旧数据备份
迁移后验证
迁移完成后，检查以下内容：
- 能正常启动 Wesclaw
- 历史对话可以查看
- AI 记忆正常（检查记忆中心）
- 模型配置正常（发送一条测试消息）
- IM 渠道正常（如已配置）
- 定时任务正常（如已配置）
数据兼容性
向前兼容
- v1.0 可以读取 v0.2 的数据（通过迁移）
- 迁移后的数据不能回退到 v0.2 格式
版本间兼容
- 小版本更新（如 1.0.1 → 1.0.2）：完全兼容，无需迁移
- 中版本更新（如 1.0 → 1.1）：自动 schema 迁移
- 大版本更新（如 1.0 → 2.0）：可能需要手动迁移
Schema 迁移机制
Wesclaw 使用 PRAGMA user_version 跟踪数据库 schema 版本：
- 启动时自动检测当前版本
- 逐步执行未应用的迁移步骤
- 每步在事务内执行，保证原子性
- 迁移失败时自动降级：归档旧文件，创建全新数据库
引擎数据
引擎侧（wesgine）数据由引擎自身的迁移机制管理：
sessions.db、state.db、meta.db由引擎升级时自动迁移- 迁移过程遵循 INV-RESIL-10（迁移全幂等）
回滚方案
桌面版回滚
如果新版本出现问题，可以回退到旧版本：
- 关闭当前版本
- 安装旧版本
# macOS：使用之前备份的旧版本
cp -r ~/wesclaw-old-version.app /Applications/Wesclaw.app
- 恢复数据（如需要）
# 如果新版本修改了数据结构，需要恢复备份
rm -rf ~/Library/Application\ Support/wesclaw/
cp -r ~/wesclaw-v0.2-backup/ ~/Library/Application\ Support/wesclaw/
注意事项
- 降级有风险：旧版本可能无法读取新版本创建的数据
- 建议保留备份：每次升级前都备份数据目录
- 引擎版本匹配：Wesclaw 版本需要与内置的引擎版本匹配
- 不要用旧二进制读新数据：版本降级可能导致数据被错误解析
紧急恢复
如果数据损坏且没有备份：
- 删除数据目录
- 重新启动（会创建全新数据）
- 重新配置模型和设置
# ⚠️ 最后手段：完全重置
rm -rf ~/Library/Application\ Support/wesclaw/
引擎数据有韧性保护机制：
- 三层 SQLite 数据库物理隔离
- 自动快照和损坏检测
- Boot 永远成功（降级启动）
更新日志查看
查看当前版本
在 Wesclaw 中：
/version
或在「设置 → 关于」中查看版本信息。
更新日志
每次版本更新都附带更新日志（Changelog），说明：
- 新功能（feat）：新增的功能和能力
- 修复（fix）：已修复的问题
- 改进（improve）：性能和体验优化
- 破坏性变更（breaking）：需要注意的不兼容变化
查看方式：
- 自动更新提示中查看
- 官方网站的更新日志页面
- GitHub Releases 页面
版本命名规则
v1.0.3
│ │ │
│ │ └── 补丁版本（bug 修复）
│ └──── 次版本（新功能，向下兼容）
└────── 主版本（重大变化，可能不兼容）
升级检查清单
在进行任何升级前，建议按照以下清单操作：
升级前
- 阅读目标版本的更新日志
- 确认是否有破坏性变更
- 备份数据目录
- 记录当前配置（模型、渠道等）
- 确保磁盘空间充足
升级中
- 关闭所有 Wesclaw 实例
- 执行安装/更新
- 等待自动迁移完成
升级后
- 验证应用正常启动
- 检查历史对话完整性
- 测试 AI 对话功能
- 验证 IM 渠道（如已配置）
- 验证定时任务（如已配置）
- 确认模型配置正常
- 检查日志中是否有错误
常见升级问题
启动时报错
错误：数据库版本不兼容
解决方案：
- 检查是否从更高版本降级
- 尝试删除
-wal和-shm文件 - 如有备份，恢复后重新升级
迁移中断
如果迁移过程中断（如电脑意外关机）：
- 查看日志确认中断位置
- 使用
--force参数重新执行迁移 - 如果仍然失败，恢复备份后重新升级
配置丢失
升级后部分配置可能需要重新设置：
- API Key 需要重新输入
- IM 渠道可能需要重新配置
- 自定义 Agent 设置需要检查
引擎版本记录
每次启动时，日志中会记录引擎版本：
boot: engine version sdk_version=1.0.3
如果发现版本不匹配，请确保使用正确的 Wesclaw 发行版。
注意事项
- 定期备份：建议每月备份一次数据目录
- 逐级升级：不建议跨多个大版本升级，建议逐级升级
- 阅读日志：升级前务必阅读更新日志中的破坏性变更
- 测试验证：升级后进行基本功能验证
- 保留旧版本：升级后不要立即删除旧版本安装包