Runtime Setup 指南

spec-runtime-setup 是当前唯一公开的 Runtime Setup 入口（Claude/Qoder 命令拼写 runtime-setup）。不提供任何历史兼容别名。官网主路径统一写 spec-runtime-setup。

它负责准备 deterministic runtime facts，不负责证明代码理解结论。后续 plan、work、review、debug 仍要用 bounded direct source reads、rg、ast-grep、git diff、tests/logs 和用户证据确认任务结论。

使用方式

宿主	当前入口	宿主拼写 / 预览说明
Claude Code	spec-runtime-setup	命令拼写 runtime-setup（/spec:runtime-setup 为 Claude 命令面）
Codex	spec-runtime-setup	skill 名 spec-runtime-setup（$spec-runtime-setup 为 Codex skill 面）
Kiro	spec-runtime-setup	opt-in preview，setup runtime surface 会 pin MCP_SETUP_HOST=kiro
Qoder	spec-runtime-setup	命令拼写 runtime-setup；opt-in preview，pin MCP_SETUP_HOST=qoder
Cursor	spec-runtime-setup	generated_runtime_preview，只证明 generated runtime，不证明 loader/user journey
OpenCode	spec-runtime-setup	generated_runtime_preview，只证明 generated runtime，不证明版本匹配的 loader/user journey；pin MCP_SETUP_HOST=opencode

先运行 package CLI 的 spec-first doctor 和 spec-first init，重启宿主后再进入本 workflow。

执行逻辑图

用户运行 spec-runtime-setup
  |
  v
读取共置 setup-registry.json（source of truth）
  |
  v
检查 required baseline MCP servers、helper tools、host config、repo target
  |
  +-- 裸入口
  |     |
  |     v
  |   展示完整 baseline（含 CodeGraph / Graphify）计划并要求一次确认
  |
  +-- --check / --plan / --verify-only
  |     |
  |     v
  |   只读检查或刷新 setup facts，不安装 provider
  |
  +-- --only codegraph,graphify
        |
        v
      高级子集修复（仅修复所选 provider）
        |
        v
      写 .spec-first/config/* setup-owned facts

Required Baseline MCP Servers

当前 skills/spec-runtime-setup/setup-registry.json 声明的 required baseline MCP servers 是：

MCP server	包 / 启动方式	作用
Sequential Thinking	npx -y @modelcontextprotocol/server-sequential-thinking@latest	动态反思式问题拆解
Context7	npx -y @upstash/context7-mcp@latest	查询当前框架与库文档

这些 server 需要写入当前宿主的 host MCP config。setup 会按宿主路径、权限和 preview 成熟度输出 ready、blocked 或 degraded。

Required Helpers

完整 setup 还会检查 helper readiness：

Helper	当前边界
ffmpeg	baseline-blocking；缺失时完整 setup 不能报告 ready
ast-grep	结构化搜索能力检查；下游可按结果选择 direct rg 降级
agent-browser	保持 report-only / non-blocking；依赖可安装不等于 exact-origin 执行能力已验证

Full Setup 的 Provider Readiness

当前完整 spec-runtime-setup 的 required baseline 包括 Sequential Thinking、Context7、ffmpeg、CodeGraph 与 Graphify。裸入口会先展示完整计划并请求一次确认；--only codegraph、--only graphify 或 --only codegraph,graphify 只是高级子集修复，不代表完整 setup 已完成。

Provider	安装来源	主要写入	边界
CodeGraph	@colbymchenry/codegraph@1.5.0	.codegraph/codegraph.db、host MCP config	提供 impact / call graph candidates
Graphify	PyPI graphifyy@0.9.29（Python ≥3.10，uv/pipx）	当前产物 graphify-out/；legacy .graphify/ 仅作迁移/旧证据	提供 architecture map / path / explain candidates

裸 spec-runtime-setup 会展示 provider、project/provider runtime writes、host config writes、first-generation commands、refresh hooks 和明确 non-actions，并要求用户对整批操作做一次确认。--only codegraph、--only graphify 或 --only codegraph,graphify 是 headless/subset apply 路径，不需要第二次确认；子集成功仍需用 --verify-only 检查完整 setup readiness。

产物边界

目录 / 文件	作用
.spec-first/config/tool-facts.json	setup-owned tool/helper/provider readiness facts
.spec-first/config/runtime-capabilities.json	direct evidence posture、host readiness pointer、fallback 能力
.spec-first/workspace/scenario-fingerprint-setup.json	parent workspace 或复杂场景下的 advisory setup fingerprint
.codegraph/codegraph.db	CodeGraph provider-native local database
graphify-out/	Graphify provider-native 当前项目图谱产物
.graphify/	旧版 Graphify 适配目录（legacy；setup 会在它单独存在时迁移到 graphify-out/）

这些 facts 和 provider outputs 都不是 source truth。它们帮助 workflow 决定证据是否充足；具体实现、影响面和风险仍要回到当前源码、diff、测试和日志。

常见失败

症状	常见原因	下一步
host config 写入失败	Claude managed config 或 Codex user config 没有写权限	按 setup 输出修复权限或切换 target
provider pack 未安装	用户未确认，或只跑了 --check / --plan	需要 provider 时显式运行 --only codegraph,graphify
Graphify first generation 失败	workspace override 非法、CLI 缺失、hook 安装失败	先看 setup 输出的 reason code，再回退到 direct evidence
helper 缺失	本机未安装 agent-browser、ast-grep 等	相关 workflow 标注 degraded；必要时按 setup next action 修复

下一步

• Provider Evidence Overview：理解 provider 与 direct evidence 的优先级
• Provider Pack：查看 CodeGraph / Graphify 的边界
• Control-plane Artifacts：查看 setup 和 workflow run 写入哪些文件