排错与兼容

先体检 #

artifact-graph doctor --format markdown

请使用 artifact-chain-setup 检查制品链环境是否就绪，不要修改项目。

多数问题会直接报出来：CLI 找不到、配置缺字段或类型不对、Node 版本不够、原生构建 better-sqlite3 被 pnpm 跳过。把体检输出对照下面的症状。配置结构错误带字段路径；未知键保留并给出兼容提示，不一律拒绝扩展。

常见症状 #

• 第一次跑 context / packet 就非零退出：多半是 context.universal_baseline 默认开启，而项目缺少约定的基线文件。轻量项目在配置里显式关闭该门槛，或把缺的文件补上。
• 安装后报 missing binding 或原生模块缺失：原生构建被拦了。在 pnpm 10.26+ 用 allowBuilds，更早的 10.x 用 onlyBuiltDependencies，允许 better-sqlite3。装完用 doctor 复核。
• 关系锁漂移：源文件或关系变了但锁没刷。先验收受影响的内容，确认关系仍成立，再更新锁。日常工作树用 artifact-graph version-lock refresh --changed-only --worktree 只刷已确认的受影响锁；提交前改用 --staged。--all 重建全量基线。锁和源一起提交。禁止在 hook 里跑 version-lock bootstrap --force。
• validate 报断头边：某制品声称被一份设计实现，但那份设计不存在或 id 写错。补上缺失制品，或修正标记里的 id。
• validate 报 DISALLOWED_EDGE：这条关系不在有效 allowedEdges 里。先核对 from/to/kind 是否写对；项目若要用自定义关系，把该三元组写进配置，不要指望扫描结果自动放行。只有 []、null 或 YAML 空值才会回到内置默认表。
• 已有 artifact-graph.config.yaml 但缺 allowedEdges：加载失败，错误路径是 allowedEdges。补 allowedEdges: [] 采用默认表，或列出项目自己的严格清单。没有配置文件仍是未接入，doctor 不会替项目造一份有效配置。
• CLI 报 unknown command：多半敲了文档里的占位命令。以 --help 为准。例如 hook 是 hooks install-git 而不是 hooks install。
• setup 表达服务配置缺项或凭据值为空：该项 WARN，只影响可读性优化，图查询和其他检查继续。
• SKILL_FAMILY_DOCS_CREDENTIAL_ENV 不是合法环境变量名：该项 FAIL，仍然不阻断图功能，也不会打印凭据值。
• loadConfig（配置加载入口）或 doctor 报 Invalid types.*.paths / displayName / idRanges.*.*.prefix：对应字段类型或缺失 paths 的新类型；内建类型局部覆盖可以继承 paths。

CI 红、本地绿 #

常见只有两类原因：

• 原生构建差异：CI 的 pnpm 版本或缓存策略跳过了 better-sqlite3。对照本地 doctor 输出，确认 CI 镜像也带白名单。
• 基线门槛差异：CI 是干净 checkout，universal_baseline 发现缺文件直接非零退出，本地恰好有这些文件所以没报。在项目配置里显式声明：要么补齐文件，要么关掉该门槛。

排查时把 CI 的命令复制到本地，加 --warning-only 再跑一遍，通常能立刻复现。validate --warning-only 退出 0 仍要读 issues。

把问题缩到最小 #

症状不直观时，先做最小复现：新建一个只含一份需求与一份设计的仓库，跑 init → validate。能复现，说明是配置或能力本身的问题；不能复现，说明是当前项目某份制品把图带歪了。这时用 query 把关系拉出来看，比猜测快。

兼容 #

版本配对写在插件的 compatibility.json：Node、CLI 与插件版本。升级前先看该文件，避免本地能跑、CI 挂。能力是否随版本变化，以决策文件为准，不凭路线图注释判断。插件当前源版本是 1.2.0。