JSON Output and Error Contract zh CN

JSON 输出与错误契约

语言： English · 简体中文

LWC 以 JSON 作为自动化契约：成功命令在标准输出返回结构化 JSON，失败命令则在标准错误返回稳定的错误信封。用错误码选择恢复分支，用消息理解本次故障，再从详情判断是否可重试，以及 canonical 状态是否已经发生变化。

错误信封

{
  "error": {
    "code": "store_not_found",
    "message": "no project Wiki was found from the current directory",
    "details": {}
  }
}

进程会以非零状态退出，并把信封写到标准错误。details 的字段随错误码变化，可能包含标识符、路径、限制、重试提示、Work 元数据、安全检查点或恢复命令。

自动化不要依赖消息文本。后续版本可能改善措辞或增加详情，而不改变错误码的含义。

Canonical 部分成功

部分恢复或发布错误发生在 SQLite canonical 状态已经改变之后。这类错误会明确给出 canonical_committed、checkpoint_restored 或 rolled_back 等事实，以及恢复命令。

一旦这些标记为真：

1. 不要重新执行原始逻辑编辑；
2. 保留错误 JSON 和返回的标识符；
3. 在同一项目、同一作用域执行准确的恢复命令；
4. 等待返回的 Work；
5. 若已启用图，最后执行 lint 和 graph verify。

没有部分成功标记，只能说明“尚未证明”，不能据此认定完全没有变更。手工重试前应先检查 canonical 状态。

作用域与 Store

错误码	含义	正确处理
store_not_found	所选作用域没有 Wiki	进入目标项目，或初始化准确的作用域
scope_not_supported	该命令不支持当前作用域	使用 project 或 global；all 只用于受支持的读取
project_root_invalid	显式项目根不可用	修正或移除 LWC_PROJECT_ROOT
project_root_mismatch	当前目录不在显式根内	切换目录，或选择正确的根
project_root_escape	解析后的路径越过授权项目	将路径留在项目内，或使用有文档约束的确认参数
project_scope_conflict	发现边界内存在冲突的项目 Wiki	从精确的项目边界执行命令
invalid_store_path	Store 管理的路径不安全、不存在或类型错误	检查符号链接和所有权，不要盲目替换状态
unsupported_store_version	数据库版本更新或不受支持	升级 LWC，不要强制用旧版本写入
corrupt_store	必需的表结构或不变量损坏	停止写入，并按检查点恢复流程处理
database_busy	有界写事务或恢复锁正在占用	遵循重试详情，稍后重试同一命令

输入、Source、Page 与摄取

错误码	含义	正确处理
invalid_input	某字段违反命令契约	修正错误中指出的字段
invalid_limit、invalid_offset	分页参数超出范围	使用命令报告的边界
input_too_large	CLI 输入超过有界读取限制	拆分或缩小输入
invalid_utf8	文本输入不是有效 UTF-8	摄取前先转换编码
possible_secret_detected	输入疑似包含凭据或秘密	移除秘密；不要为了真实凭据绕过扫描
external_source_requires_acknowledgement	Source 位于项目外	确认授权后，再显式传入确认参数
source_not_found	指定的不可变 Source ID 不存在	通过 source list 刷新 ID
source_in_use	仍有 Page 引用该 Source	用 source refs 检查，先更新 Page
source_status_unstable	检查过程中跟踪文件又发生变化	等写入者结束后重试
source_diff_too_large	Diff 输入超出安全比较预算	比较更小的修订，或进行外部有界审查
page_not_found	Page slug 不存在	检查作用域、changeset 选择器和 slug
page_in_use	其他 Page 仍链接到目标 Page	删除前先修复入站链接
invalid_provenance	溯源值不在支持范围	使用文档列出的 provenance 值
ingest_job_not_found	对应 Source 没有摄取任务	检查 ingest list 和 Source 状态
invalid_ingest_state	当前状态不允许这次迁移	按返回的当前状态继续
ingest_integration_required	尚未满足完成门槛	写带引用的来源摘要，并整合知识或说明无需派生 Page

Changeset 与 checkpoint

错误码	含义	正确处理
changeset_exists	同名草稿已经存在	继续、丢弃，或换一个合法名称
changeset_not_found	找不到指定草稿	查看 changeset list
changeset_empty	草稿没有可发布变更	丢弃草稿，或加入预期更新
changeset_lint_failed	草稿 lint 阻止发布	在草稿内修复报告的问题
changeset_conflict	被触及的身份在 live 中已推进	对照 live 与草稿，并从最新基线重建草稿
changeset_rollback_conflict	后续 live 写入使逆操作不再安全	保留后续工作，改用新的明确变更
changeset_corrupt	草稿、绑定或 inverse 数据未通过完整性检查	停止操作并保留现场
changeset_committed_cleanup_failed	Canonical 提交成功，但草稿清理失败	执行返回的恢复命令，不要重新发布内容
changeset_committed_materialization_failed	Canonical 提交成功，但 Markdown 投影失败	按恢复详情处理，然后执行 lint
changeset_rolled_back_graph_projection_failed	回滚成功，但图修复失败	重新执行返回的回滚恢复，并验证图
checkpoint_not_found	指定检查点不存在	查看 checkpoint list
checkpoint_invalid	检查点未通过身份、结构或完整性校验	不要恢复它，改用已验证的检查点
checkpoint_restored_materialization_failed	数据库恢复成功，但文件未重建	执行准确的恢复命令并重新验收
checkpoint_restored_projection_failed	数据库恢复成功，但图投影失败	恢复项目作用域的投影并执行 graph verify

Work 与投影

错误码	含义	正确处理
work_not_found	当前运行时找不到该 Work ID	检查作用域和 changeset 选择器
work_busy	另一个 Work 正占用变更通道	等待活动 Work，或稍后重试
work_cancelled	协作式取消已到达终态	仅在 Work 可恢复且任务仍需要时执行 resume
work_not_resumable	当前 Work 状态不能恢复	查看结果，并发起合适的新操作
work_invalid	持久 Work 元数据未通过校验	保留运行时现场，不要手改文件
artifact_busy	受管产物暂时无法安全替换	关闭读取者，或等待占用进程结束
artifact_write_failed	Canonical 状态有效，但生成产物失败	执行物化恢复并校验路径所有权
graph_disabled	尚未选择文档图引擎	只有获得用户授权后才启用目标引擎
graph_node_not_found	图中没有指定节点	验证图，并确认标识符格式
graph_projection_failed	Canonical 变更成功，但投影无法排队或执行	遵循详情、等待 Work，再验证图
grafeo_error、surrealdb_error	所选嵌入式引擎拒绝了操作	先确认 canonical 健康，再决定是否重投影

CodeGraph、转换与集成

错误码	含义	正确处理
codegraph_runtime_missing	固定版本运行时尚未安装	获得授权后再执行 cg init
codegraph_index_missing	项目没有可用代码索引	执行项目作用域的 cg init 并检查状态
codegraph_download_failed	无法下载运行时资产	检查网络并重试，不要替换成未验证二进制
codegraph_checksum_mismatch	下载内容未通过校验和	立即停止，丢弃资产并调查来源
codegraph_command_failed	CodeGraph 命令执行失败	查看其结构化标准错误和项目状态
trans_disabled	尚未选择转换适配器	有意配置 MarkItDown 或 AnyDoc
trans_executable_missing	PATH 中没有所选适配器	安装对应上游工具，或调整配置
trans_unsafe_args	已保存的适配器参数违反安全策略	移除不安全的位置、输出、Shell 或凭据参数
trans_timeout	转换超过配置的截止时间	检查输入，只有确有必要才提高有界超时
trans_publish_race	另一写入者抢先创建了输出	换用新输出；LWC 不会覆盖已有文件
unknown_agent_target	请求的 Agent 适配器未注册	用 lwc agent status --target all --location global 查看准确名称
agent_config_conflict	宿主配置发生了不兼容变化	审查冲突，不要盲目覆盖用户配置
hook_input_too_large	Agent 事件信封超过 Hook 预算	缩小宿主负载，或使用受支持信封
invalid_project_path	MCP 收到相对路径、文件系统根或非法工作区	传入项目的绝对目录
view_bind_failed	Viewer 无法绑定回环端口	使用 --port 0，或释放指定端口

升级为缺陷报告前

先收集：

lwc --version
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

报告中应包含准确命令、错误 JSON、操作系统、命令是否使用草稿，以及移除秘密后的最小复现。另见故障排查和恢复与维护。