Troubleshooting and FAQ zh CN

故障排查与常见问题

语言： English · 简体中文

排查 LWC 时应从外向内：先确认 binary 与 scope，再看规范状态、持久 Work，最后检查可选索引。不要一上来就删除 .lwc。

最小诊断信息

只对受影响 scope 运行；分享前先脱敏 path 与 content：

lwc --version
lwc --scope project context --limit 1
lwc --scope project config show
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 agent status --target auto --location global

记录准确 command、exit status、error JSON、current directory、operating system、LWC version，以及故障发生在 canonical mutation 之前还是之后。

除非诊断确实需要且已经授权，不要粘贴 Source content、Page body、stored conversion argument、host config 或 private path。

先读错误契约

命令失败时会在标准错误返回结构化 JSON：

{
  "error": {
    "code": "database_busy",
    "message": "another short Wiki write is active; retry this exact operation",
    "details": {
      "retryable": true,
      "retry_after_ms": 100,
      "work_command": "lwc work list"
    }
  }
}

程序应根据 code 分支，而不是匹配英文 message。检查 details 中的 retryability、canonical partial success、Work ID、safety checkpoint 和准确 recovery command。

Wiki 错误或 Store 缺失

典型现象包括 store_not_found、出现意外 Page，或 database path 位于目标仓库之外。

pwd
lwc --scope project context --limit 1
lwc --scope global context --limit 1

在项目目录或子目录运行。移除日常 shell 中 export 的 LWC_PROJECT_ROOT。该变量只用于一次刻意选择的 root，并且当前目录必须在其中。

出现 project_scope_conflict 说明显式边界中有多份 Wiki。应进入真正的项目目录，而不是继续扩大 root。

数据库或 Work Busy

database_busy 表示短 SQLite writer 或 restore boundary 正在活动。按照 retry_after_ms 等待，检查 Work 后重试同一操作。

work_busy 表示一个 state-changing Work 正占用所选运行目录：

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

不要删除 active marker。只有确实需要停止时才 cancel，并继续 watch 到 cancelled。

Lint 问题

lwc --scope project lint --limit 100

常见类型包括：

• 缺少 summary 或 provenance；
• Page 没有 citation；
• orphan Page 或 dangling Wiki link；
• completed ingest 没有 shared derived Page，也没有 audited reason；
• FTS row 缺失、重复或 orphan。

知识问题应修规范内容。只有 index-integrity issue 才使用 maintenance reindex，只有生成 Markdown 问题才使用 maintenance materialize。

稀疏 changeset 中的 lint 必须检查 live baseline 加 draft delta。不要把未改 live Page 复制进草稿，也不要用 --allow-lint-issues 隐藏 overlay bug。

Search 找不到目标 Page

lwc --scope project search "exact wording" --limit 10 --explain
lwc --scope project search "natural paraphrase" --limit 10 --explain

依次检查：

1. Page 是否存在于所选 scope；
2. title 与 summary 是否使用用户真正会问的 term；
3. query 规范化后是否仍有 searchable term；
4. target、kind 与 granularity filter 是否正确；
5. auto mode 是否因为 source-summary Page 而有意隐藏 paired raw Source；
6. manual weight 或 feedback 是否降低结果；
7. lint 是否报告 search-index inconsistency。

不要在修复陈旧或含糊内容之前添加全局正向 weight。

文档图不可用或不一致

lwc --scope project config show
lwc --scope project graph status
lwc --scope project work list
lwc --scope project graph verify

• graph_disabled：只有获得明确项目同意后才启用；
• Work 仍活动：继续 watch；
• Verify 出现 missing、mismatched 或 stale：显式设置目标引擎排入全量投影，watch 后再次 verify；
• Draft graph 问题：所有 Work 与 graph 命令都加上同一 --changeset selector。

禁止直接编辑 Grafeo 或 SurrealDB 文件。

CodeGraph 不可用

cg status 会区分 runtime installation 与 project initialization：

lwc --scope project cg status

• runtime 缺失：只有明确同意后，cg init 才下载固定 Release；
• runtime 已安装、project 未初始化：在该项目运行 cg init；
• index stale：使用受支持的 forward cg sync 命令；
• external path 被拒绝：进入目标项目并只使用项目内 path。

CodeGraph 不是第二个 MCP entry。如果 Agent 中仍显示 codegraph，refresh LWC AgentTarget integration，并检查 owned legacy-entry migration。

转换失败

lwc --scope project config show
lwc --scope project trans input.docx --output converted/input.md

• trans_disabled：先选择引擎；
• trans_executable_missing：在 LWC 外安装所选 optional engine，再重试；
• timeout：提高有界 timeout 前先检查文件大小和 adapter behavior；
• trans_unsafe_args：从 stored arguments 中移除 path、output 或 credential override；
• output 已存在：换新 path，create-new safety 不允许覆盖。

转换成功不等于 Source ingest。执行 source add 前必须审核 Markdown。

Agent 集成 Drift

lwc agent status --target codex,claude,pi --location global

modified 表示某个 tracked path 与安装 receipt 不同。Refresh 前先检查，它可能是有效用户编辑。

使用 --print-config 做只读审核。无 drift 时 refresh 应保持 byte-idempotent，uninstall 必须保留 foreign content。禁止通过复制维护者私有工具或 HOME 中的文件修 adapter。

Viewer 问题

• 固定端口占用时使用 --port 0；
• 平台浏览器启动失败时使用 --no-open；
• Code Graph 必须先在 Viewer 外显式初始化；
• Word Graph 需要一到八个 searchable term，并且始终分页；
• 数据 stale 时，通过 CLI 修复，再用新 Viewer process 检查。

Viewer 请求不能修改持久状态，写方法应返回 HTTP 405。

规范部分成功

graph_projection_failed、checkpoint_restored_materialization_failed 或 committed changeset cleanup failure 等错误可能表示规范状态已经改变。

检查以下字段：

• canonical_committed；
• checkpoint_restored；
• safety_checkpoint；
• graph_work；
• recovery_command 或 recovery_commands。

执行准确 recovery command，再重复 live acceptance。契约确认安全之前，不要重做业务 mutation，也不要 discard draft。

何时报告 Bug

以下情况应提交可复现问题：

• typed state 与 canonical readback 矛盾；
• 文档声明幂等的 retry 创建重复数据；
• live 与 draft selector 泄漏 Work 或 graph state；
• Viewer 或 MCP 产生未声明的持久写入；
• 成功执行文档化 rebuild 后 graph verify 仍不一致；
• install、refresh 或 uninstall 覆盖 foreign host content；
• 受支持平台 package 无法通过 checksum 或 version verification。

提交最小、非敏感复现，并说明 cleanup 是否安全。维护者确认不再需要之前，应保留失败 draft 或 checkpoint。

常见问题

每条命令都要导出 LWC_PROJECT_ROOT 吗？

不需要。直接从项目目录或其子目录执行 lwc 即可。只有在确实要把发现范围限制到指定根时，才设置该变量。

每个项目都会重新下载 CodeGraph 吗？

不会。固定版本 runtime 按用户安装一次，升级前持续复用。每个项目仍维护独立索引，因为源码树和 revision 状态属于项目自身。

CodeGraph 应该注册成第二个 MCP server 吗？

不应该。LWC 在 lwc_explore 的 code 或 all mode 内融合 CodeGraph；Agent 宿主只注册 lwc MCP server。

命令返回 Work 就算执行完成了吗？

不算。它只表示持久任务已经排队。必须通过 work watch 等到成功终态，再进行验收。

生成的 Markdown 可以直接手改修复吗？

不可以。SQLite 才是 canonical。应执行 maintenance materialize，再验证投影。

自动检测到 Agent 就等于授权安装吗？

不等于。检测只会预选可能已经安装的宿主；交互确认或显式 --yes 才决定安装。

下一篇：恢复与维护