Maintenance and Diagnostics zh CN

维护与诊断

语言： English · 简体中文

诊断先判断故障属于规范知识、持久 Work，还是派生投影；maintenance 负责重建或压缩派生产物，不改变 Source 或 Page 知识；recovery 则在故障后恢复预期状态。应从能够修复已证实问题的最窄命令开始。

恢复阶梯

按以下顺序选择：

1. 规范状态正确、执行中断时，等待或 resume Work；
2. Markdown、FTS、文档图或 CodeGraph stale 时，只重建对应派生投影；
3. 撤销一项已提交逻辑更新且保留之后无关写入时，使用 changeset rollback；
4. 整个 Wiki 数据库必须回到旧时间点时，使用 checkpoint restore。

生成文件缺失或 graph edge stale 时，不要直接做完整 restore。

修复前检查

lwc --scope project lint --limit 100
lwc --scope project work list
lwc --scope project graph status
lwc --scope project graph verify
lwc --scope project cg status
lwc --scope project checkpoint list

记录当前 revision、operation ID、active Work、graph engine 和准确异常 artifact。没有前置条件与验收项的修复无法审计。

物化 Markdown

SQLite 读取正确，但 .lwc/wiki/、.lwc/raw/、schema.md、purpose.md、index.md、overview.md 或 log.md 缺失/stale 时使用：

lwc --scope project maintenance materialize
lwc --scope project work watch <work-id>
lwc --scope project lint

Materialization 会重建整套 owned projection。只有 manifest-owned artifact 会被替换或删除；LWC ownership 外的 user file 与 raw asset 会保留。

禁止直接修改生成文件充当修复。

重建检索索引

只有 lint 报告 FTS row 缺失、重复、orphan，或文档化 tokenizer migration 之后才使用：

lwc --scope project maintenance reindex
lwc --scope project work watch <work-id>
lwc --scope project lint
lwc --scope project search "known answer" --limit 5 --explain

Reindex 会根据 immutable Sources 与 current Pages 在 transaction 内重建 document FTS 与 span index，再刷新 Markdown operation log。它不会改写 Page knowledge 或 retrieval adjustment。

压缩 SQLite

在空闲维护窗口运行：

lwc --scope project maintenance compact
lwc --scope project work watch <work-id>

Compaction 会优化 FTS，并尝试 WAL TRUNCATE checkpoint。检查 Work result 中的 busy、before_bytes 与 after_bytes。busy=true 表示 active reader 阻止完整截断，不代表可以杀 reader 或删除 WAL file。

重投影文档图

规范 Wiki 与 search 健康，但 graph verify 报告 drift 时，显式设置目标引擎排入全量投影：

lwc --scope project config set --graph grafeo
lwc --scope project work watch <work-id>
lwc --scope project graph verify

如果选择的是 surrealdb，整个决策链都使用它。不要为了修复一个引擎而切换到另一个，应重建并校验原目标引擎。

Draft graph recovery 必须保留同一 changeset selector。Live 与 draft Work root、graph sidecar 是刻意隔离的。

Resume Work

lwc --scope project work status <work-id>
lwc --scope project work resume <work-id>
lwc --scope project work watch <work-id>

只有修复原因后才 resume。Failed、cancelled 或 stale interrupted Work 可以恢复，succeeded 或新鲜 active Work 返回 work_not_resumable。

Parent command 如果返回 canonical partial-success recovery command，应执行它，而不是盲目 resume。系统可能需要先重建缺失 graph document 或完成 cleanup。

Changeset 恢复

Commit failure 大致分两类：

• canonical merge 未发生：修复 conflict 或 draft issue 后重新 commit；
• canonical_committed=true：不要重新暂存写入，应重复文档化的幂等 commit recovery，并保留 draft 到 cleanup 成功。

回滚已提交更新：

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

Touched entity 被后续写入修改时，rollback 会拒绝，没有 force option。Rollback 报告 canonical partial success 时，根据 details 重复同一准确命令。

Checkpoint 恢复

只有整个 database 必须回到已知边界时才使用 checkpoint restore：

lwc --scope project checkpoint restore <checkpoint-name>
lwc --scope project work watch <graph-work-id>
lwc --scope project lint
lwc --scope project graph verify

Restore 会先创建 pre-restore-* safety checkpoint。在 canonical、Markdown、retrieval 与 graph acceptance 全部通过前保留它。

无法安全准备的 checkpoint 会返回 checkpoint_restored=false。Canonical restore 成功但 projection 失败时，details 会包含 checkpoint_restored=true、安全 checkpoint 与准确 recovery command。

CodeGraph 恢复

lwc --scope project cg status
lwc --scope project cg sync

普通项目文件变化使用 cg sync。项目索引从未初始化时，经明确同意再使用 cg init。LWC 会复用已校验 global runtime，同时保持 project index 本地归属。

不要通过 lwc cg 调用被阻止的 CodeGraph global lifecycle command，不要把 .codegraph state 移入项目，也不要注册独立 CodeGraph MCP server。

Schema 迁移

打开旧版但受支持的 Store 时，原请求之前可能运行或排入 migration。长迁移通过 shadow-copy Work 完成，并保留安全 checkpoint。

Watch 返回 Work 并检查 result。遇到未知新格式时返回 unsupported_store_version；应使用兼容 LWC，而不是编辑 PRAGMA user_version。

恢复验收

每项恢复都要根据事故类型完成对应检查：

lwc --scope project lint
lwc --scope project search "expected wording" --limit 5
lwc --scope project search "natural paraphrase" --limit 5
lwc --scope project graph verify
lwc --scope project work list

还要直接 read back 受影响 Page、Source path head、tag membership 或 checkpoint state。事故包含 partial success 时，仅看 command exit status 不够。

禁止的捷径

• 删除 wiki.db-wal 或 wiki.db-shm；
• 编辑 SQLite、FTS、Work JSON、graph sidecar 或 generated Markdown；
• 未诊断就 discard failed draft；
• 使用 lint override 隐藏新问题；
• 把一份 draft runtime 强行复制到另一份；
• Restore 后不保留、不记录自动 safety checkpoint；
• 没找到 drift 来源就反复 full rebuild。

下一篇：安全与隐私