排错与兼容

先体检 #

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。
• CLI 报 unknown command：多半敲了文档里的占位命令。以 --help 为准。例如 hook 是 hooks install-git 而不是 hooks install。

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 挂。能力是否随版本变化，以决策文件为准，不凭路线图注释判断。插件当前源版本是 0.13.0。