1. 为什么要在本地工程里认真配置 Spec-kitSpec-kit 是 GitHub 开源的一套规范驱动开发Spec-Driven Development简称 SDD工具包。它做的事情说白了就一句话在让 AI 写代码之前先把「原则 → 需求 → 计划 → 任务 → 实现」这条链路用结构化文档固定下来再让 Coding Agent 按文档分阶段落地。它适合谁适合那些需求里有明确业务规则、又不想每次对话都从头解释上下文的开发者尤其是多模块、有表约束、有幂等要求的后端功能。很多人装完 Specify CLI、跑通specify init就以为完事了结果真正开始用的时候发现两个问题一是 Agent 每次都要重新问「你用什么模型、走哪个通道」二是settings.json这类配置文件到底该放什么、怎么和统一 Key 对接全靠猜。我试过在几个项目里反复初始化最后发现真正决定「能不能稳定复现」的不是命令敲得多熟而是配置文件骨架有没有一次搭对。这篇就聚焦 Spec-kit 在本地工程中的落地配置围绕settings.json骨架与 TaoToken 统一 Key/API 通道接入展开。你会拿到可复制的配置片段、逐步验证动作以及从安装到跑通首个 spec 流程的完整闭环。核心检索词先摆在这Spec-kit 是什么、能做什么、适合谁——它是一套把 AI 编码从即兴对话升级为可评审流水线的工具适合有规则约束的功能开发不适合纯 UI 微调。2. TaoToken 前置统一 Key 与 API 通道Spec-kit 本身不绑定模型供应商它通过 Agent 去调用模型。问题在于如果你在 Cursor、Claude Code、Codex CLI 之间来回切换每个工具都要单独配 Key、单独记 Base URL配置一多就容易乱。TaoToken 在这里的角色是提供一个统一的 Key 和 API 通道让 Spec-kit 工作流里的模型调用走同一个入口配置一次、多处复用。你需要先拿到两样东西一个 API Key以及 API 通道地址。Key 在控制台的 API Keys 页面创建通道地址用https://taotoken.net/api注意这个地址不加任何查询参数。创建 Key 的时候建议按项目或按工具命名比如spec-kit-cursor、spec-kit-claude后面排查问题时能一眼看出是哪个环境在用。拿到 Key 之后先别急着往 Spec-kit 里塞。建议单独用一次最小请求验证通道是否通避免后面配置出错时分不清是 Spec-kit 的问题还是 Key 的问题。验证方式很简单用 curl 打一次模型列表或对话接口即可具体命令在下一节给。这里有个容易踩的坑有人把 Key 直接写进项目仓库的配置文件然后提交这是大忌。settings.json里应该只放环境变量引用或占位符真实 Key 放在本地环境变量或不被追踪的.env里。Spec-kit 的配置文件通常会被 Agent 读取一旦进 Git 历史就很难清理。3. 可复制配置settings.json 骨架与 Specify CLI 安装3.1 前置依赖与 Specify CLI 安装Spec-kit 的 Specify CLI 需要 Python 3.11 和 Git。推荐用 uv 做工具隔离安装比全局 pip 干净。Windows 下先装 uvpowershell -c irm https://astral.sh/uv/install.ps1 | iex uv --version装完 uv 后安装 Specify CLI。把vX.Y.Z换成 Releases 页里的具体标签想尝鲜就直接装 main 分支uv tool install specify-cli --from githttps://github.com/github/spec-kit.gitvX.Y.Z specify self checkspecify self check会告诉你当前版本和是否有更新。升级用specify self upgrade想先看它要执行什么就加--dry-run。3.2 settings.json 骨架Spec-kit 初始化后会在项目里生成.specify/目录Agent 侧的配置入口因集成方式不同而不同。以 Cursor 集成为例配置通常落在.cursor/下的规则或命令目录而模型通道相关的settings.json建议放在项目根目录的.specify/下统一管理内容骨架如下{ specKit: { version: 1.0, integration: cursor-agent, artifactsDir: .specify, templatesDir: .specify/templates, overridesDir: .specify/templates/overrides }, model: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKeyEnv: TAOTOKEN_API_KEY, defaultModel: claude-sonnet-4-5, timeoutMs: 120000 }, workflow: { requireConstitution: true, requireTasksBeforeImplement: true, confirmBeforeDestructive: true } }几个字段值得说明。baseUrl固定写https://taotoken.net/api不要带 UTM 或其它查询串否则部分客户端会拼接出错。apiKeyEnv指向环境变量名而不是 Key 本身这样配置文件可以安全提交。defaultModel按你实际用的模型填Spec-kit 的 plan 和 tasks 阶段对上下文长度要求较高选长上下文模型更稳。workflow里的三个开关是护栏强制先有 constitution、强制先出 tasks 再 implement、破坏性操作前确认能显著减少 AI 跳过流程直接改代码的情况。环境变量在 PowerShell 里这样设当前会话有效$env:TAOTOKEN_API_KEY 你的Key想持久化就写进用户环境变量或者用.env配合 dotenv 加载。注意别把.env提交进仓库。3.3 项目初始化新建项目直接specify init my-app --integration cursor-agent在已有仓库里初始化Brownfield 场景specify init . --force --integration cursor-agent如果本机没装对应 Agent CLI只想先拉模板加--ignore-agent-toolsspecify init . --force --integration cursor-agent --ignore-agent-tools初始化完用specify check验证出现Specify CLI is ready to use!就说明 CLI 可用。想看当前版本支持哪些集成跑specify integration list。4. 验证请求从通道连通到首个 spec 流程4.1 先验证 API 通道在跑 Spec-kit 之前先用 curl 确认 TaoToken 通道通curl -s https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json返回模型列表就说明 Key 和通道都正常。如果返回 401检查 Key 是否复制完整、环境变量是否在当前终端生效返回 404 通常是 baseUrl 写错确认没有多余路径或查询串。4.2 跑通首个 spec 流程进入项目在 Agent 对话里按顺序执行。第一步确立原则/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements. 本项目为 Spring Boot Vue3 全栈接口契约需保持稳定。第二步写需求规格注意命令是specify不是specite/speckit.specify 请为「阅读商城」编写需求用户阅读满 10 分钟可打卡领书币 用书币购买称号。输出 Spec 接口字段说明 关键业务规则 边界条件。第三步技术计划/speckit.plan 技术栈Spring Boot 3.x Java 17 MyBatis-Plus JWT Vue3 Vite。 给出 Controller/Service/DTO/Entity 分层方案与数据库表设计 并与现有阅读日历模块对齐。第四步拆任务/speckit.tasks 请把「阅读商城」拆成可执行任务并生成 tasks.md 覆盖表与唯一约束、打卡规则、前端并行加载策略。第五步实现/speckit.implement 按 tasks.md 实现阅读商城。要求 1最小修改复用现有架构 2奖励计算、幂等、余额扣减变更前先确认 3SQL 仅限本功能表不破坏既有契约。每步的产物会写进.specify/或项目内的specs/、tasks.md以初始化时的模板为准。跑完 implement 后检查代码变更是否与 tasks.md 逐项对应这是验证流程是否真正闭环的关键动作。4.3 成功结果长什么样一次健康的流程结束后你应该能看到.specify/下有 constitution、spec、plan 三类制品tasks.md里任务被拆成可勾选条目代码变更集中在目标模块没有动全局配置。如果 implement 阶段 AI 直接开始写代码而没引用 tasks.md说明requireTasksBeforeImplement没生效回去检查 settings.json 是否被正确读取。5. 本篇常见错排查配置类问题大多集中在几个点上对照下表处理现象可能原因处理uv tool install慢或失败未配镜像或网络问题配 uv 的 config.toml 镜像检查 Git 可用性specify check失败Python 版本低或 PATH 未刷新确认 Python 3.11装完重启终端Cursor 里没有/speckit命令集成未生成或目录缺失重新specify init . --integration cursor-agent --force检查.cursor/API 返回 401Key 未生效或复制不全重新设环境变量确认当前终端能读到API 返回 404baseUrl 写错确认是https://taotoken.net/api无多余路径AI 跳过 tasks 直接写代码护栏未开或提示不明确检查 settings.json 的 workflow 开关提示里明确「只输出 tasks.md」代码风格与项目不符constitution 未写栈约定在 constitution 里写明目录与分层约定implement 强调复用现有风格Windows 脚本异常cmd 与 PowerShell 混用init 时选 ps统一在 PowerShell 里操作还有一个隐蔽的坑settings.json里apiKeyEnv写的是环境变量名但你在 Agent 里跑的时候Agent 进程可能读不到你终端里临时设的变量。解决办法是把变量设到系统级或者在 Agent 的启动配置里显式注入。排查时先单独用 curl 验证通道再验证 Agent 能否读到变量分层定位比一股脑改配置快得多。6. 把配置沉淀成可复用的起点Spec-kit 的价值不在于命令多而在于它把「先想清楚再动手」变成了可执行的流水线。settings.json骨架搭对之后新项目初始化只需要复制这份配置、改一下integration和defaultModel通道和护栏都是现成的。我自己的习惯是把这份骨架放在一个模板仓库里每次specify init之后直接覆盖过去省掉重复配置的时间。如果你还在选模型通道可以先到模型对话页面确认可用模型需要长期跑编码和 Agent 任务Coding Plan 更适合高频调用场景Key 的创建和管理在控制台完成接入细节可以对照接入文档。把这几步走完Spec-kit 的配置就不再是一次性的折腾而是能反复复用的工程起点。