回退QoderWake版本需确保数据库向下兼容：一、检查目标版本支持的schema_version与engine_type；二、用qoderwake db migrate --down安全降级；三、删除新版本特有表及扩展元数据并VACUUM。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在执行QoderWake版本回退操作时发现数字员工无法加载历史记忆、技能库报校验失败或Connector同步提示“schema mismatch”，则很可能是新旧版本间数据库结构发生不兼容变更，导致SQLite/LevelDB存储层读取异常。以下是确保数据库格式向下兼容的关键要点：
一、确认回退目标版本的存储引擎与Schema版本号
QoderWake自v2.0.0起引入Schema版本控制机制，所有本地状态数据库（含memory.db、skills.ldb、governance.sqlite3）均嵌入version字段，回退前必须验证目标版本是否支持当前数据库的逻辑结构，避免强制加载引发数据截断或索引错位。
1、在终端中进入QoderWake数据目录：Linux/macOS执行cd ~/.qoderwake/data，Windows执行cd %APPDATA%\QoderWake\data。
2、运行命令qoderwake db inspect --all，输出各数据库文件的当前schema_version（如memory.db: v3.2.1）及engine_type（sqlite3/leveldb）。
3、查阅官方兼容性矩阵文档，确认目标回退版本（如v1.2.7）所声明支持的最高schema_version为v2.8.0，且engine_type必须严格匹配。
4、若检测到memory.db schema_version为v3.2.1而目标版本仅支持至v2.8.0，则不可直接启动，必须先执行降级迁移。
二、执行Schema安全降级迁移（管理员权限必需）
QoderWake提供内置迁移工具qoderwake db migrate --down，该命令基于预置的逆向迁移脚本（如v3.2.1→v3.2.0→v3.1.0…→v2.8.0），逐层剥离新增字段、约束与索引，保留原始业务数据完整性，不触发全量重建。
1、停止所有QoderWake服务：执行qoderwake stop --force。
2、备份原始数据库：cp memory.db memory.db.backup_$(date +%Y%m%d_%H%M)。
代码编辑 CLI 工具集合：Cursor CLI（agent）和 Qoder CLI（qodercli），用于代码修改、重构、Code Review 及自动化代码任务。
3、执行逆向迁移至目标兼容版本：qoderwake db migrate --down --to v2.8.0 --db memory.db。
4、迁移完成后运行校验：qoderwake db verify --db memory.db，输出必须显示“✅ Schema version matches declared target”且无warning。
三、禁用新版本特有持久化模块并清除残留元数据
部分新版本引入的后台持久化模块（如v3.x中的event_log_v2、async_snapshot_queue）会在数据库中创建独立表或写入扩展元数据标记，这些结构在旧版本中无对应解析逻辑，将导致初始化失败或静默跳过关键状态。
1、使用SQLite CLI打开memory.db：sqlite3 memory.db。
2、执行SELECT name FROM sqlite_master WHERE type='table' AND name LIKE 'event_log%';，确认是否存在event_log_v2等非目标版本表。
3、若存在，执行DROP TABLE event_log_v2; DROP TABLE async_snapshot_queue;（注意：此操作仅删除结构，不影响主memory表数据）。
4、清除数据库中version_info表内的扩展标记：UPDATE version_info SET metadata = json_remove(metadata, '$.feature_flags.async_snapshot') WHERE key = 'core';。
5、退出CLI后，执行VACUUM;命令回收空闲页，确保数据库体积与v2.8.0兼容规格一致。
