本地源码安装

本页适合贡献者、维护者或需要验证未发布改动的团队。普通使用者优先阅读 安装指南，直接安装 npm 发布包。

本地源码安装的核心目标是验证“当前源码能否被打包成真实 CLI，再投影到目标项目的宿主 runtime”。Claude Code 与 Codex 是主要支持面；Cursor、Kiro、Qoder、OpenCode 需要按当前 source catalog 显式 opt-in，并保留各自 preview / degraded 边界。不要把源码仓库直接当作宿主插件目录，也不要手改 generated runtime copies。

适用场景

场景	是否适合
验证 skills/（含 skill-local references/agents）、templates/ 或 CLI 改动	适合
在发布前跑一次完整 install / init / doctor 链路	适合
普通项目第一次接入 spec-first	不需要，直接用 npm 发布包
临时修复某个目标项目里的 .claude/ 或 .agents/skills/	不适合，应从 source 重新 init

前置要求

要求	说明
Node.js >=20	与当前 package.json 的 engines.node 保持一致
npm >=8 / npx	用于 npm pack、全局安装 tarball 和 provider warmup
Git	用于仓库识别、变更边界和 workflow evidence
至少一个目标宿主	Claude Code、Codex，或显式 opt-in 的 Cursor、Kiro、Qoder、OpenCode

打包并安装本地 tarball

在 spec-first 源码仓库中执行：

git clone https://github.com/sunrain520/spec-first.git
cd spec-first
npm pack
npm install -g ./spec-first-<version>.tgz

<version> 替换为 npm pack 生成的实际文件名，例如 spec-first-1.14.0.tgz。

安装后确认 shell 没有继续缓存旧路径：

hash -r
which spec-first
spec-first --version
spec-first doctor

如果 which spec-first 指向旧目录，先打开新 shell，或清理旧的全局安装路径，再重新检查。

初始化目标项目

切换到要使用 spec-first 的目标 Git repo 根目录，再运行 init：

spec-first init

交互式流程会让你选择一个或多个目标宿主；脚本场景可用 -y 配合显式 host flag，例如 spec-first init -y --claude --codex -u <name> --lang zh。只使用默认宿主时也可以运行 spec-first init -y -u <name> --lang zh。Cursor、Kiro、Qoder、OpenCode 属于显式 opt-in preview，不会因为 -y 自动加入默认宿主集。

init 会从已安装的本地 tarball 读取 source assets，并生成项目内 runtime：

Host	主要生成物
Claude Code	.claude/commands/spec-*.md、.claude/skills/、.claude/spec-first/workflows/、.claude/agents/、CLAUDE.md managed block
Codex	.agents/skills/、.codex/agents/、.codex/spec-first/、AGENTS.md managed block
Cursor（preview）	.cursor/skills/、.cursor/agents/、.cursor/spec-first/、项目级 .cursor/mcp.json；仅证明 generated runtime 投影
Kiro（preview）	.kiro/skills/、.kiro/agents/、.kiro/spec-first/、受管 .kiro/settings/；IDE 实机 smoke 仍需单独验证
Qoder（degraded preview）	.qoder/commands/spec-*.md、.qoder/skills/、.qoder/agents/、.qoder/spec-first/；本机 CLI 能力取决于 Qoder 环境
OpenCode（preview）	.opencode/commands/spec-*.md、.opencode/skills/、.opencode/agents/、.opencode/spec-first/；宿主 user journey 仍需单独验证

这些目录是 generated runtime assets。源码修复应回到 skills/（含 skill-local references/agents）、templates/、src/cli/ 或 docs source，再重新打包和 init。

重启宿主并验证入口

init 写入文件后，需要完全重启宿主进程。关闭窗口通常不够，推荐退出应用后重新打开。

进入目标项目的新会话后，先跑 runtime setup：

spec-runtime-setup

Codex 兼容别名：

spec-runtime-setup

验证目标不是“目录存在”，而是宿主能发现当前入口，并且 doctor / setup 能解释当前 runtime readiness。完整 spec-runtime-setup 会验证 CodeGraph / Graphify baseline；若本次只做子集或 setup 降级，必须明确标注未完成，并仍以 bounded direct source reads、rg、ast-grep、git diff、测试日志和用户证据作为语义事实。

开发循环

修改 spec-first 源码后，重新执行：

npm run typecheck
npm run test:unit
npm run build
npm pack
npm install -g ./spec-first-<version>.tgz

然后回到目标项目重新：

spec-first doctor
spec-first init

只验证一个宿主时，在交互式 init 中只选择对应宿主；脚本场景可追加 --claude、--codex、--cursor、--kiro、--qoder 或 --opencode。影响 MCP/helper/provider setup 的改动还需要在宿主内重新运行 spec-runtime-setup。

常见问题

症状	处理
spec-first --version 还是旧版本	新开 shell，运行 hash -r，再检查 which spec-first
宿主看不到新 workflow	确认目标项目重新跑过 init，并完全重启当前宿主
修改 runtime copy 后又被覆盖	这是预期行为；runtime copy 不是 source-of-truth
provider evidence 不 ready	先跑宿主内 spec-runtime-setup，确认是否显式启用 provider pack；未启用时按 bounded direct reads 降级
本地安装后测试失败	回到源码仓库跑最窄失败测试，修 source 后重新 pack/install

源码校准

本页对齐当前 spec-first source：

• package.json：Node requirement、测试脚本、npm pack --dry-run 构建口径。
• src/cli/commands/init.js：supported-host runtime projection 行为。
• src/cli/adapters/*.js：宿主 runtime 目录与 preview 边界。
• docs/05-用户手册/06-本地源码安装.md：本地安装流程基线。

下一步

• 安装指南：查看发布包安装和平台注意事项
• CLI Reference：查看 doctor、init、clean、tasks 和 session 命令
• Provider Pack：理解 CodeGraph / Graphify readiness 与证据边界