Changesets zh CN

Changeset 原子变更

语言： English · 简体中文

Changeset 会在隔离的稀疏草稿中暂存多项相关 Wiki 变更，把它们叠加到 live Wiki 完成验证，再一次性原子发布。一个逻辑更新不能暴露部分知识时就应使用它。

单条 source、page 或 tag 命令本身已经是事务操作。只有多条命令必须一起成功时，changeset 才有价值。

合适场景

• 加入多份 Source，并一起整合到共享页面；
• 同时修订页面和强标签策略；
• 把 Purpose、Schema 与依赖页面作为一项契约变更；
• 一次发布多篇互相链接的页面，避免临时断链；
• 为大范围替换建立一个准确回滚边界。

单命令写入不需要 changeset；草稿生命周期只会增加审核成本，无法改善原子性。

稀疏叠加模型

live Wiki 保持可读且不变
          +
只保存触及实体与基线指纹的小草稿
          =
用于草稿验证的叠加读取

changeset begin 不会复制或 checkpoint 整个 live Wiki，只创建一份与 live store identity 和 base revision 绑定的小型稀疏数据库。草稿读取会在 live 基线上看到暂存变更，live SQLite 与 Markdown 保持不变。

每个草稿都有独立数据库、Work 目录和图 sidecar，Work ID 与图节点不能跨草稿泄漏。

开始并暂存

lwc --scope project changeset begin architecture-refresh
lwc --scope project --changeset architecture-refresh source add-manifest sources.json
lwc --scope project --changeset architecture-refresh ingest claim <source-id>

所有依赖读写都应使用同一 --changeset selector。不要同时直接修改草稿即将触及的 live 实体。

项目与全局 changeset 彼此独立，mutation 不支持 --scope all。

支持的稀疏变更

当前准确 patch 集支持：

• Source add；
• ingest claim、analyze、complete、fail 与 retry；
• Page put 与 remove；
• Purpose 与 Schema 整体替换；
• tag set、remove、delete 与 autoload 策略；
• 记录到操作历史的搜索。

其他规范变更只有具备准确 inverse 与 merge 规则后才能安全发布。不支持的动作会返回 changeset_sparse_unsupported 或命令特有的 changeset_command_not_supported，不会产生部分提交。

Deployment-local 配置、init、maintenance、checkpoint 和嵌套 changeset 命令不能在草稿中执行。只有这种分离符合预期原子边界时，才把本身事务安全但不受支持的 mutation 放在 changeset 外部执行。

验证草稿

lwc --scope project --changeset architecture-refresh lint
lwc --scope project --changeset architecture-refresh search "expected answer" --limit 5
lwc --scope project --changeset architecture-refresh search "natural paraphrase" --limit 5
lwc --scope project changeset show architecture-refresh

show 会报告基线与草稿 revision、暂存操作数、action count、状态和冲突元数据，但不会执行 lint。

稀疏 lint 检查的是 live 基线 + 草稿增量。草稿页面可以继续链接未修改的 live 页面，纯标签草稿也无需复制页面正文、依赖或搜索索引。

验证应包括：

• 草稿没有引入 lint 问题；
• 原始问题和自然改写都在前五名返回预期页面；
• 引用与 provenance 完整；
• 图状态相关时，草稿图 Work 为 succeeded 且 graph verify ok=true。

原子发布

lwc --scope project changeset commit architecture-refresh

Commit 会：

1. 拒绝空草稿；
2. 验证草稿绑定与完整性；
3. 检查每个 touched Page、meta record、tag 和 Source path 的指纹；
4. 对叠加视图运行 lint；
5. 冻结已审核草稿；
6. 为触及实体创建带 checksum 的 inverse patch；
7. 在 live write lock 内应用 merge；
8. 启用图时排入 live 图投影；
9. 删除草稿状态并刷新生成 Markdown。

无关 live 写入会保留。某个 touched entity 在草稿首次观察后发生变化时，commit 返回 changeset_conflict，两侧都不会被覆盖。系统不存在 force merge。

草稿与 live 写入在无关路径上独立分配了相同 Source ID 时，commit 会重新映射冲突 ID。页面引用、ingest 状态、路径 head、图文档、指纹和 rollback 数据都会跟随映射。

Lint 例外

禁止用 --allow-lint-issues 隐藏草稿错误。它只适用于已经审核、且并非本草稿引入的 live 旧债，并必须提供原因：

lwc --scope project changeset commit architecture-refresh \
  --allow-lint-issues \
  --reason "Reviewed pre-existing debt; this draft introduces no new issue"

应当优先修复问题。原因只负责记录例外，不能让破损知识变得有效。

冻结草稿与重试

Commit 会在 live 发布前冻结经过审核的草稿，后续暂存写入返回 changeset_frozen。

结构化错误显示规范提交已经成功，但图排队、清理或物化失败时，不要重复执行知识 mutation，应运行 error details 中准确的 recovery_command。重复同一 changeset commit <name> 具备幂等恢复能力，可以在清理前重新排入图投影，也能兼容旧版 commit 元数据。

丢弃草稿

lwc --scope project changeset discard architecture-refresh

Discard 会删除一份未提交草稿及其隔离 Work/图运行目录，绝不会修改 live 知识。诊断或恢复仍需要草稿内容时，不要提前丢弃。

回滚已提交 Changeset

Commit 会返回稳定 changeset_id 和提交前 checkpoint 名称：

lwc --scope project changeset rollback <changeset-id>
lwc --scope project work watch <graph-work-id>
lwc --scope project graph verify

Rollback 只恢复 inverse patch 触及的实体。如果其中任何实体后来被 live 写入修改，它会拒绝回滚并保留新工作。Source path head、重映射 ID、页面引用、标签和文档图投影会保持一致恢复。

Rollback 幂等。规范回滚已经成功但后续物化或图排队失败时，根据结构化 recovery details 重复同一 rollback 命令。

发布后验收

在 live 状态重复相同验收：

lwc --scope project lint
lwc --scope project search "expected answer" --limit 5
lwc --scope project search "natural paraphrase" --limit 5
lwc --scope project graph verify

草稿检查干净不能证明 live 物化和图投影已经完成。

完成证据

Changeset 生命周期只有满足以下条件才算完成：

• 所有依赖操作使用同一草稿 selector；
• 叠加 lint 与预声明检索通过；
• commit 返回一个稳定 changeset ID 和 inverse checkpoint；
• 相关图 Work 达到 succeeded，live 图校验通过；
• live 检索重复通过草稿阶段验收；
• 冲突或部分成功错误按照 typed recovery contract 处理；
• 只有规范发布或显式 discard 后才清理草稿运行目录。

下一篇：Work 系统