1. 为什么 AI 写代码总在“自由发挥”OpenSpec 需求驱动开发到底解决什么问题如果你用 Claude Code、Cursor 或者 Copilot 写过稍微复杂一点的功能大概率遇到过这种场景你在对话框里说“帮我加一个按角色和团队筛选个人资料的功能”AI 噼里啪啦给你生成一堆代码看起来像那么回事跑起来也能用但仔细一看——筛选逻辑写死了、边界条件没处理、接口参数跟现有系统对不上。你让它改它改了一版又引入新的问题。来回几轮之后你发现自己花在“收拾烂摊子”上的时间比手写还多。这个问题的根源不在于模型不够聪明而在于对话上下文不等于需求规格。聊天记录是线性的、易失的、模糊的而软件开发需要的是结构化的、可追溯的、有验收标准的规格说明。AI 在缺乏明确约束的情况下只能根据概率“猜”你想要什么猜对了是运气猜错了是常态。OpenSpec 这个命令行工具做的事情就是把“需求先行”这个理念工程化。它不替代你的 AI 编程助手而是在你和 AI 之间插入一层结构化的规格文件。你先写 proposal为什么做、tasks怎么做、specs改哪里、验收标准是什么确认无误后再让 AI 按图施工。AI 从“自由发挥的实习生”变成“照着图纸干活的施工队”。SDDSpec-Driven Development规格驱动开发的核心价值就在这里在敲下第一行代码之前人和 AI 先就“要做什么”达成书面共识。这个共识不是聊天记录里的一句“好的”而是一组可版本控制、可评审、可归档的 Markdown 文件。但这里有个现实问题OpenSpec 本身不绑定任何模型服务它需要调用 AI 来生成和修改规格文件。如果你用的是 Claude Code 或者 Cursor 内置的模型可能会遇到额度限制、网络波动、或者多个工具之间 Key 管理混乱的情况。我试过同时维护三四个工具的 API Key每次切换都要改配置烦得很。后来统一用 TaoToken 做 Key 接入一个 Base URL 管所有工具省事不少。这篇文章会带你跑通一个完整的闭环安装 OpenSpec、配置 TaoToken 统一 Key、生成需求提案、让 AI 按规格写代码、验证输出是否受控。每一步都有可复制的命令和配置片段照着做就能跑起来。2. OpenSpec 安装与 TaoToken 统一 Key 前置配置auth.json 和 Base URL 怎么改2.1 安装 OpenSpec 命令行工具OpenSpec 的安装非常轻量前提是你机器上有 Node.js 20.19 或更高版本。打开终端执行node -v # 确认版本 20.19 npm install -g fission-ai/openspeclatest安装完成后进入你的项目根目录执行初始化cd my-project openspec init这个命令会在项目下创建openspec/目录并自动检测你使用的 AI 编程工具Cursor、Claude Code、Copilot 等写入对应的命令集成文件。如果你用的工具不在自动检测列表里也没关系后面手动配置一样能跑。初始化完成后目录结构大致是这样openspec/ ├── changes/ # 存放每次变更的提案、任务、规格 │ └── archive/ # 归档后的历史变更 ├── specs/ # 项目主需求库唯一真相源 └── project.md # 项目上下文说明2.2 为什么需要 TaoToken 统一 KeyOpenSpec 在工作过程中会调用 AI 来生成 proposal、tasks 和 specs 文件。如果你用的是 Claude Code它默认走 Anthropic 的 API如果你用 Cursor它走自己的模型服务。问题在于多个工具各自维护 Key切换成本高某些工具的额度用完后需要临时换模型配置改来改去团队协作时每个人本地配置不一致容易出玄学问题TaoToken 的做法是提供一个统一的 API 入口兼容 Anthropic 和 OpenAI 两种协议格式。你只需要在 TaoToken 控制台创建一个 Key然后把各个工具的 Base URL 指向https://taotoken.net/api就能用同一个 Key 调用不同的模型。2.3 Claude Code 的 auth.json 配置改法如果你用 Claude Code 配合 OpenSpec需要修改 Claude Code 的配置文件。在 macOS/Linux 下路径通常是~/.claude/auth.jsonWindows 下在%USERPROFILE%\.claude\auth.json。打开这个文件改成如下结构{ baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, model: claude-sonnet-4-20250514 }注意三个关键点Base URL填https://taotoken.net/api不要加多余的路径后缀API Key从 TaoToken 控制台的 API Keys 页面获取格式通常是sk-开头Model ID填你实际要用的模型标识比如claude-sonnet-4-20250514或gpt-4o如果你用的是 Cline 或者 Roo Code 这类 VS Code 插件配置方式类似在插件的设置面板里找到 “API Provider”选择 “OpenAI Compatible” 或 “Anthropic”然后填入Base URL: https://taotoken.net/api API Key: sk-你的TaoToken密钥 Model ID: claude-sonnet-4-202505142.4 验证 Key 是否生效配置完成后先别急着跑 OpenSpec用一条最简单的 curl 命令验证 Key 能不能通curl -X POST https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: sk-你的TaoToken密钥 \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-20250514, max_tokens: 100, messages: [{role: user, content: 回复OK}] }如果返回的 JSON 里有content字段且内容正常说明 Key 和 Base URL 都配对了。如果返回 401检查 Key 是否复制完整如果返回 404检查 Base URL 是否多写了/v1后缀TaoToken 的 Base URL 就是https://taotoken.net/api具体路径由客户端自动拼接。3. 可复制的 OpenSpec 配置片段与需求提案生成从 proposal.md 到 specs 的完整流程3.1 OpenSpec 项目级配置在openspec/目录下可以放一个config.yaml来指定默认的 AI 行为和规格模板。虽然 OpenSpec 不强制要求这个文件但加上之后能让团队协作更一致# openspec/config.yaml version: 1 ai: provider: anthropic baseUrl: https://taotoken.net/api model: claude-sonnet-4-20250514 spec: language: zh-CN requireAcceptanceCriteria: true archiveOnComplete: true这个配置的作用是告诉 OpenSpec 在生成规格文件时使用中文、强制要求验收标准、完成后自动归档。baseUrl和model字段会被 OpenSpec 传递给底层 AI 调用确保走的是 TaoToken 的统一入口。3.2 生成第一份需求提案假设我们要给一个用户管理系统加“按角色和团队筛选个人资料”的功能。在项目根目录下对 Claude Code 说帮我写一份 OpenSpec 需求提案要实现按角色和团队筛选个人资料的功能。Claude Code 会调用 OpenSpec 的命令生成如下目录结构openspec/changes/add-profile-filters/ ├── proposal.md ├── tasks.md └── specs/ └── profile/ └── spec.md打开proposal.md内容大致如下# 变更提案添加个人资料筛选功能 ## 背景 当前用户列表页面不支持按角色和团队筛选管理员需要手动滚动查找效率低下。 ## 目标 - 支持按角色admin/user/guest筛选 - 支持按团队team-a/team-b/team-c筛选 - 筛选条件可组合使用 ## 非目标 - 不做全文搜索 - 不做排序功能tasks.md则是具体的开发步骤# 任务清单 - [ ] 在 User 模型上添加 role 和 team 字段的索引 - [ ] 开发 GET /api/users?roleteam 接口 - [ ] 前端添加角色下拉框和团队下拉框 - [ ] 编写接口单元测试 - [ ] 更新 API 文档specs/profile/spec.md是核心的规格说明包含验收标准# 个人资料筛选规格 ## 需求按角色和团队筛选 系统必须允许用户通过角色和团队两个维度筛选个人资料列表。 ### 场景按单一角色筛选 - 当用户选择角色 admin - 系统返回所有 role 为 admin 的个人资料 ### 场景按角色和团队组合筛选 - 当用户选择角色 admin 且团队 team-a - 系统返回同时满足两个条件的个人资料 ### 场景无筛选条件 - 当用户未选择任何筛选条件 - 系统返回全部个人资料3.3 评审与修改规格生成初版后你可以继续对 AI 说能不能给角色和团队筛选功能加上分页参数的验收标准AI 会更新spec.md在场景部分追加分页相关的描述。这个过程可以反复进行直到规格文件完全符合你的预期。关键点是所有修改都落在 Markdown 文件里而不是聊天记录里。你可以用 Git 来追踪每一次规格变更谁改了什么、为什么改一目了然。3.4 让 AI 按规格写代码规格确认后在 Claude Code 中输入/openspec:apply add-profile-filters这个命令会触发 OpenSpec 读取tasks.md和spec.md然后让 AI 严格按照规格生成代码。AI 不会跳过任务清单里的任何一项也不会添加规格里没有提到的功能。生成完成后你可以对照tasks.md逐项检查User 模型的索引加了吗API 接口的参数和返回格式对了吗前端下拉框的选项值跟规格一致吗如果发现偏差直接修改规格文件重新执行/openspec:applyAI 会基于更新后的规格重新生成。4. 验证请求与成功结果一次需求变更后 AI 输出受控的完整演示4.1 场景设定假设我们已经完成了“按角色和团队筛选”功能的开发现在需要新增一个需求筛选结果需要支持按创建时间倒序排列。这是一个典型的需求变更如果不走 SDD 流程直接对 AI 说“加个排序”它可能会把排序逻辑写在前端、写在后端、或者两边都写导致行为不一致。4.2 走 OpenSpec 流程的变更第一步对 AI 说帮我创建一个 OpenSpec 变更提案给个人资料筛选功能添加按创建时间倒序排列的支持。OpenSpec 会生成一个新的变更目录openspec/changes/add-profile-sort/ ├── proposal.md ├── tasks.md └── specs/ └── profile/ └── spec.mdspec.md里会包含明确的验收标准### 场景按创建时间倒序排列 - 当用户请求个人资料列表且未指定排序参数 - 系统默认按 createdAt 字段倒序返回 ### 场景显式指定排序 - 当用户请求 ?sortcreatedAt:desc - 系统按 createdAt 倒序返回 - 当用户请求 ?sortcreatedAt:asc - 系统按 createdAt 升序返回第二步执行应用命令/openspec:apply add-profile-sortAI 会根据规格生成代码。假设它修改了UserController和对应的查询逻辑。4.3 验证输出是否受控代码生成后用 curl 验证接口行为是否符合规格# 不带排序参数期望默认倒序 curl -s http://localhost:3000/api/users?roleadmin | jq .data[].createdAt # 显式指定升序 curl -s http://localhost:3000/api/users?roleadminsortcreatedAt:asc | jq .data[].createdAt如果第一次返回的时间戳是递减的第二次是递增的说明 AI 严格按照规格实现了排序逻辑。如果发现默认排序没生效或者参数解析有问题回到spec.md检查验收标准是否写清楚了然后重新执行/openspec:apply。4.4 归档变更测试通过后执行/openspec:archive add-profile-sort这个命令会把changes/add-profile-sort/目录移动到changes/archive/下同时把spec.md里的需求合并到openspec/specs/profile/spec.md主需求库中。从此以后项目的主需求库就包含了“按创建时间排序”这条规格后续任何 AI 生成的代码都必须遵守它。4.5 成功结果的判断标准一次受控的 AI 编码输出应该满足以下条件tasks.md里的每一项都被完成没有遗漏spec.md里的每个场景都有对应的代码实现接口的实际行为与验收标准一致没有引入规格之外的功能或副作用如果 AI 生成了规格里没提到的“额外优化”比如自动加了缓存或者改了返回结构这就算失控。你需要检查是不是规格写得太模糊给了 AI 自由发挥的空间。5. 本篇常见错误排查401、local proxy failed、reading choices、OAuth 报错怎么处理5.1 401 Unauthorized报错信息Error: 401 Unauthorized {error:{type:authentication_error,message:invalid x-api-key}}原因TaoToken 的 API Key 没有正确配置或者 Key 已失效。排查步骤检查auth.json或插件设置里的apiKey字段是否以sk-开头有没有多余空格登录 TaoToken 控制台确认 Key 状态是“启用”用 curl 直接测试 Key 是否有效参考 2.4 节的命令如果 curl 能通但 Claude Code 报 401检查 Claude Code 是否读取了正确的配置文件路径5.2 local proxy failed报错信息Error: local proxy failed: connection refused原因客户端配置了本地代理端口但代理服务没有启动或者端口被占用。排查步骤检查 Claude Code 或 Cline 的设置里是否开启了 “Use Local Proxy”如果开启了确认代理服务是否在运行如果不需要代理直接关闭该选项让请求直连https://taotoken.net/api检查系统环境变量里是否有HTTP_PROXY或HTTPS_PROXY指向了一个不存在的端口5.3 reading choices 报错报错信息Error: reading choices: unexpected end of JSON input原因AI 返回的响应格式不符合预期通常是模型 ID 写错了或者 Base URL 路径拼接有问题。排查步骤确认model字段填的是 TaoToken 支持的模型 ID比如claude-sonnet-4-20250514不要填claude-3这种模糊名称确认 Base URL 是https://taotoken.net/api不要写成https://taotoken.net/api/v1如果用的是 OpenAI 兼容协议检查请求路径是否正确拼接为/v1/chat/completions用 curl 测试一次完整请求看返回的 JSON 结构是否正常5.4 OAuth 相关报错报错信息Error: OAuth token exchange failed原因Claude Code 默认走 OAuth 登录流程但如果你用的是 API Key 模式OAuth 流程会失败。排查步骤确认 Claude Code 的认证模式设置为 “API Key” 而不是 “OAuth”在auth.json里确保有apiKey字段且没有oauthToken字段如果之前登录过 OAuth先执行claude logout清除旧凭证重新配置auth.json后执行claude login --api-key走 Key 模式5.5 OpenSpec 命令不识别报错信息Unknown command: /openspec:apply原因OpenSpec 没有正确初始化或者 AI 工具没有加载对应的命令集成。排查步骤确认在项目根目录执行过openspec init检查.claude/commands/或.cursor/commands/目录下是否有openspec:apply.md等文件如果没有手动执行openspec init --force重新生成重启 AI 编程工具让命令列表刷新6. 用 TaoToken 统一 Key 跑通 OpenSpec 需求驱动闭环6.1 完整流程回顾把前面的步骤串起来一个典型的需求驱动开发闭环是这样的在项目里执行openspec init生成规格目录结构配置 TaoToken 的 Base URL 和 API Key确保 AI 调用走统一入口对 AI 说“帮我写一份 OpenSpec 需求提案要实现 XXX 功能”评审proposal.md、tasks.md、spec.md反复修改直到满意执行/openspec:apply 变更名让 AI 按规格生成代码用 curl 或单元测试验证输出是否符合验收标准执行/openspec:archive 变更名归档变更并更新主需求库这个闭环的核心价值在于每一次 AI 生成的代码都有对应的规格文件作为依据。出了问题可以追溯到是哪条验收标准没写清楚而不是在聊天记录里翻半天。6.2 什么时候该走 SDD什么时候不该走SDD 不是银弹不是所有改动都值得走一遍规格流程。根据我的经验建议走 SDD 的情况新增功能模块涉及多个文件或接口架构调整比如从单体拆分成微服务接口变更影响前后端契约性能优化或安全增强且能量化出具体指标不建议走 SDD 的情况改一个按钮的颜色或文案临时调试、POC 验证修复 bug 且不改变系统规则样式调整、日志格式修改判断标准很简单如果这个改动需要跟别人解释“为什么改”和“改成什么样”那就值得写规格。如果只是自己顺手改一下走 SDD 反而是负担。6.3 TaoToken 在其中的角色TaoToken 在这个流程里扮演的是“统一接入层”的角色。OpenSpec 本身不关心你用什么模型它只负责生成和解析规格文件。但规格文件的生成质量取决于底层模型的能力。通过 TaoToken你可以用同一个 Key 在 Claude Code、Cursor、Cline 之间切换在模型额度紧张时快速切换到备用模型团队共享一个 Key统一管理用量和权限配置方式就是前面说的三件套Base URL 填https://taotoken.net/apiAPI Key 从控制台获取Model ID 按需选择。改完auth.json或插件设置后用 curl 验证一次确认通了再跑 OpenSpec。6.4 一个实用技巧如果你在团队里推广 OpenSpec建议把openspec/config.yaml提交到 Git 仓库但把auth.json加入.gitignore。这样规格模板和项目上下文是共享的但每个人的 API Key 是独立的。新成员加入时只需要在 TaoToken 控制台申请一个 Key填到本地配置里就能直接跑通整个流程。另外openspec/changes/archive/目录建议保留在 Git 里。它是项目需求演进的完整历史比任何会议纪要都靠谱。半年后回头看你能清楚地知道每个功能是什么时候、因为什么原因加进去的。