Troubleshooting ​

本页按症状排查。先用 CLI 确认安装与 runtime，再用宿主 workflow 修复 MCP、helper tools 和 provider readiness。

Node 版本过低 ​

症状：npm install -g spec-first 或 spec-first doctor 提示 Node 不支持。

可能原因：当前代码要求 Node.js >=20.0.0。

检查命令

bash
node -v
npm -v

修复方式：用 nvm、fnm、Volta 或系统包管理器升级到 Node 20+。

是否需要重跑：需要重跑 spec-first doctor；如果之前 init 中断，再重跑 spec-first init 并选择目标宿主。

不是 Git 仓库 ​

症状：init 或 setup 无法写项目级 facts。

可能原因：当前目录不是 Git repo 根目录，或在父 workspace 下没有明确 child repo。

检查命令

bash
git rev-parse --show-toplevel
git status --short

修复方式：进入目标 repo 根目录；如果是在父 workspace 初始化，运行交互式 spec-first init 并选择目标 child 或全部 child。setup 场景下可使用对应 workflow 的 --repo <child>。

是否需要重跑：需要重跑 spec-first init，然后重启宿主。

spec-first 找不到 ​

症状：spec-first: command not found。

可能原因：全局 npm bin 不在 PATH，或全局安装失败。

检查命令

bash
npm prefix -g
npx -y spec-first@latest --help

修复方式：把全局 npm bin 目录加入 shell profile，或使用 npx 临时运行。

是否需要重跑：修复 PATH 后重跑 spec-first doctor。

Claude Code 未安装或入口不可用 ​

症状：doctor --claude 报 host readiness 问题，或重启后没有 spec-* workflow 入口。

可能原因：Claude Code 未安装、未重启、runtime assets 缺失或被清理。

检查命令

bash
spec-first doctor --claude
ls .claude/commands/spec
ls .claude/spec-first

修复方式

bash
spec-first init

在交互中选择 Claude Code，重启 Claude Code 后再试 spec-runtime-setup。

是否需要重跑：需要重跑 spec-first init 并选择 Claude Code；MCP/provider facts 缺失时继续跑 setup。

Codex 未安装或入口不可用 ​

症状：doctor --codex 报 host readiness 问题，或重启后没有 spec-* workflow skills。

可能原因：Codex 未安装、未重启、.agents/skills/ 或 .codex/agents/ 缺失。

检查命令

bash
spec-first doctor --codex
ls .agents/skills
ls .codex/agents

修复方式

bash
spec-first init

在交互中选择 Codex，重启 Codex 后再试 spec-runtime-setup。

是否需要重跑：需要重跑 spec-first init 并选择 Codex；MCP/provider facts 缺失时继续跑 setup。

权限问题 ​

症状：npm 全局安装失败、host config 写入失败或 generated runtime 目录无法更新。

可能原因：npm 全局目录、Claude managed config、Codex config 或项目目录权限不一致。

检查命令

bash
npm prefix -g
ls -ld .
spec-first doctor --json

修复方式：优先修 Node/npm 用户级安装路径；避免长期使用 sudo npm install -g。host config 权限失败时按 spec-runtime-setup 输出选择 user/managed target。

是否需要重跑：权限修好后重跑 doctor、spec-first init 并选择对应宿主，再跑 setup。

Windows PowerShell 执行策略 ​

症状：PowerShell 阻止脚本执行。

可能原因：ExecutionPolicy 限制。

检查命令

powershell
Get-ExecutionPolicy -List

修复方式：按团队安全策略调整当前用户范围，例如 RemoteSigned；企业设备先遵循 IT 管理策略。

是否需要重跑：需要重跑失败的 npm / setup 命令。

npx 执行失败 ​

症状：npx -y spec-first@latest ... 或 provider warmup 失败。

可能原因：网络、registry、代理、缓存或 npm 权限问题。

检查命令

bash
npm config get registry
npx -y spec-first@latest --help

修复方式：修复 registry / proxy / cache；团队环境建议全局安装 spec-first，减少每次 npx 解析。

是否需要重跑：需要重跑失败命令；provider warmup 失败后重跑 spec-runtime-setup。

better-sqlite3 native build 失败 ​

症状：看到 better-sqlite3 编译失败。

可能原因：当前 spec-first npm 包不依赖 better-sqlite3。错误多半来自业务项目依赖、其他本地工具或某个 provider 的内部依赖。

检查命令

bash
npm ls better-sqlite3
cat package.json

修复方式：确认失败发生在哪个包；如果来自 provider，按 provider 文档修复 native build 环境。不要把它当成 spec-first package postinstall 失败。

是否需要重跑：如果 provider 失败，修复后重跑 spec-runtime-setup，并确认是否仍要显式启用 provider pack。

Provider evidence 不可用 ​

症状：setup 或 workflow 输出 provider blocked / degraded，或提示 provider evidence 不可用。

可能原因：setup facts 缺失、provider package projection stale、npx 不可用、网络失败，或只执行了 provider 子集 / 用户拒绝了完整 setup 计划。

检查命令

bash
ls .spec-first/config
cat .spec-first/config/runtime-capabilities.json
cat .spec-first/config/provider-artifacts.json

修复方式：重跑完整 spec-runtime-setup；如果当前任务必须继续且 provider 仍不可用，按 bounded direct source reads 降级，同时保留 setup 的 degraded / incomplete 状态。

是否需要重跑：需要重跑 spec-runtime-setup。

CodeGraph query 失败 ​

症状：CodeGraph provider 已启用，但查询失败或数据库不可读。

可能原因：@colbymchenry/codegraph@1.5.0 安装失败、.codegraph/codegraph.db 不存在、索引尚未覆盖当前代码，或当前任务没有启用 provider pack。

检查命令

bash
ls .codegraph
ls .codegraph/codegraph.db

修复方式：重跑 spec-runtime-setup 并确认 opt-in；仍失败时记录 degraded，让 workflow 直接读源码。

是否需要重跑：通常需要重跑 spec-runtime-setup；期间下游 workflow 以 bounded direct repo reads 降级。

Graphify analyze 失败 ​

症状：Graphify 输出目录缺失，或 analyze log 报包、权限或仓库读取错误。

可能原因：PyPI graphifyy@0.9.29 安装失败（缺 Python≥3.10 / uv 或 pipx）、仓库路径不可读、host config 或 hook 问题。

检查命令

bash
ls graphify-out
graphify --version
# legacy only: ls .graphify

修复方式：确认 Python≥3.10 与 uv/pipx 可用，修复 PyPI graphifyy@0.9.29 安装与 repo 权限；仍失败时记录 degraded 并让 workflow 直接读源码。

是否需要重跑：修复后重跑 spec-runtime-setup，并确认是否仍要显式启用 provider pack。

MCP 服务未启动 ​

症状：宿主里调用 Context7 / Sequential Thinking 失败，或 provider MCP 调用失败。

可能原因：host MCP config 未写入、宿主未重启、server warmup 失败。

检查命令

bash
spec-first doctor --claude --json
spec-first doctor --codex --json

修复方式：重跑 spec-runtime-setup，按输出修复 host config。

是否需要重跑：需要重启宿主，并重跑 setup。

.spec-first 产物缺失 ​

症状：下游 workflow 找不到 .spec-first/config/*，或 provider pack 输出缺失。

可能原因：还没跑 setup、目录被清理、在错误 repo 中运行，或 provider pack 未显式启用。

检查命令

bash
pwd
git rev-parse --show-toplevel
find .spec-first -maxdepth 3 -type f | sort

修复方式：在目标 repo 根目录运行 setup；provider evidence 不是必须前置，不可用时按 direct reads 降级。

是否需要重跑：缺 config 跑 setup；缺 provider 输出时确认 opt-in 后重跑 setup。

init 后没有生成预期文件 ​

症状：没有 .claude/commands/spec-*.md、.agents/skills/、.codex/agents/ 或目标 host 入口。

可能原因：选择了另一个宿主、取消了交互确认、非交互场景未传 -y、命令不在 repo 根，或 parent workspace target 不符合预期。

检查命令

bash
spec-first doctor --claude
spec-first doctor --codex
git status --short

修复方式：在目标 repo 根目录重跑 init，并在交互中选择缺失的宿主：

bash
spec-first init

是否需要重跑：需要重跑 init，然后重启宿主。自动化脚本需要限定宿主时，再使用 CLI reference 中的显式宿主参数。

下一步 ​