Migration and Compatibility zh CN

迁移与版本兼容

语言： English · 简体中文

LWC 升级时优先保护规范知识；必要时重建派生状态；迁移 Agent 配置时，也只处理能够证明属于自己的片段。所谓兼容，并不代表旧 binary 可以安全写入新版 Store。

兼容层次

层次	兼容规则
CLI JSON	已有 code 和 field 保持机器可读，允许增加新字段
SQLite Store	受支持的旧 schema 通过事务迁移到当前格式
Config	可识别的旧配置继续可读，并在后续写入时升级
Markdown、FTS、span、graph	派生状态可以从 canonical SQLite 重建
Changeset 与 checkpoint	受支持版本之间仍能验证完整性信息与 inverse payload
Agent 集成	只迁移受管 legacy fragment，保留外部内容或报告冲突
CodeGraph	固定 runtime 升级与项目 index 兼容分别处理

实际运行的 binary 与当前源码才是最终依据。内部 version number 属于实现细节，不应成为外部自动化依赖。

升级前

使用拥有该 Wiki 的同一项目和用户账号：

lwc --version
lwc --scope project lint
lwc --scope project work list
lwc --scope project graph verify
lwc --scope project checkpoint create pre-upgrade

切换 binary 前应等待活动 mutation 完成。Checkpoint 保护的是 canonical SQLite，不包含外部 Source 文件或用户拥有的 Agent 配置；有需要时应通过各自原生机制备份。

升级 binary

沿用最初安装 LWC 的发行渠道。升级后执行：

lwc --version
lwc --scope project context --limit 1
lwc agent refresh --target auto --location global
lwc agent status --target all --location global

第一条遇到受支持 legacy Store 的命令，会先协调一次专用的可写事务迁移，再继续原操作。当前格式的 Store 在读取命令中保持只读；只有跨越旧格式边界时，才进入专门的迁移路径。

WAL 活跃或正在写入时，不要跨机器复制 wiki.db。迁移期间也不要让两个版本的 LWC 同时操作同一 Store。

Store 迁移保证

成功迁移必须满足：

• 转换前先验证来源 schema；
• 所有 schema 与 metadata 变更原子提交；
• 保留不可变 Source 内容和当前 Page 知识；
• 派生索引通过重建或失效处理，不能冒充 canonical；
• 全部步骤成功后才记录当前格式；
• 两个进程同时发现同一 legacy Store 时仍然安全。

如果 Store 比 binary 更新，LWC 会返回 unsupported_store_version。此时应升级 binary，绝不能强迫旧 executable 写入。

Source path 历史

旧 Store 中的 Source 可能没有可信的跟踪路径修订历史。迁移会有意保留“未跟踪”状态，而不是猜测文件系统来源。今后确实需要路径状态和差异比较时，应把当前文件作为新的 Source 加入。

这样可能出现两份内容相关的不可变 Source snapshot。如果它们分别支撑不同历史结论，就应保留两者 ID；不要为了让 lineage 看起来整洁而改写旧证据。

Config 迁移

受支持的旧配置会被解析到当前分层模型。后续执行 config set 或 config unset 时，再以当前格式原子写回。

lwc --scope global config show
lwc --scope project config show

迁移后应检查 effective value 与 origin。继承值和显式 disabled 的语义并不相同。

派生图迁移

文档图 sidecar 可重建。Store migration 可能移除过时的 inline graph table，也可能需要全量投影。任何影响图的升级完成后，都应执行：

lwc --scope project graph status
lwc --scope project graph verify

如果 canonical lint 干净但验证失败，应为当前已经选定的 engine 排队一次全量投影并等待 Work。不要为了让检查通过而临时切换引擎。

CodeGraph 会报告过时的项目本地 runtime，但不会静默删除。cg init 会安装或复用固定的用户级 runtime，并建立当前项目索引。只有新状态和查询都通过后，才考虑移除旧文件。

Agent 集成迁移

agent refresh 只有在旧 LWC 或独立 CodeGraph 片段符合已知受管形态时才会接管。它会把 CodeGraph MCP 能力合并到 lwc server，更新带 marker 的 Instructions 和规范 Skills，并记录新的所有权 receipt。

如果用户或其他工具已经替换同名条目，LWC 会报告冲突，而不是强行认领。应通过 --print-config 审查，不能删除整个宿主配置文件。

Changeset 与 checkpoint 兼容

稀疏 inverse payload 使用 checksum。新增的可选字段在为空时仍不序列化，因此旧 payload 字节可以继续通过验证。旧 operation record 缺少新版派生 Work 详情时，重试已提交的 changeset 仍可重建图投影文档。

升级后的 binary 完成文档规定的重试前，应保留失败 draft 和 pre-commit checkpoint。绝不能手改其中 SQLite 或 JSON sidecar 来绕过完整性检查。

降级策略

LWC 不承诺旧 binary 可以向新版 Store 反向写入。确实需要回到旧版本时：

1. 停止全部 LWC process；
2. 恢复由兼容版本创建的 checkpoint，或恢复完整外部备份；
3. 必要时同步恢复对应 Agent 集成与可选索引状态；
4. 用旧 binary 验证后再恢复写入。

把新 executable 覆盖成旧版本，并不等于完成数据库降级。

升级后验收

lwc --scope project lint
lwc --scope project search "known project fact" --limit 5 --explain
lwc --scope project graph verify
lwc --scope project cg status
lwc agent status --target all --location global

规范状态读取、固定检索、已启用图的验证、项目 CodeGraph 状态与目标 Agent 能力面必须分别通过。发布流水线本身参见测试与发布流程。