1. 为什么 OpenSpec 和 Superpowers 装在一起还是各干各的你可能也遇到过这个场景花半小时跟 AI 把需求聊清楚OpenSpec 规规矩矩产出了 proposal、specs、design、tasks 四份文档看着挺像回事。然后你切到 Superpowers 开始执行TDD 铁律、Review Gate 一个不少代码质量确实比裸写高。但三天后功能上线回头翻那份 design.md里面写的「响应时间控制在 200ms 以内」「这个模块要支持水平扩展」代码里一条都没兑现。问题不在于哪个工具不好。OpenSpec 管的是「写什么」它把规划文档从给人看的变成给 AI 看的Delta Spec 格式既有人类可读性又有机器可解析性58k star 不是白来的。Superpowers 管的是「怎么写」TDD 先写测试、SDD 子代理做规格检查、Review Gate 卡住合并245k star 证明了执行纪律是刚需。两个都是神级项目但你把它们放进同一个项目目录得到的是「一头老虎 一双翅膀」不是「一头会飞的老虎」。断层出在哪OpenSpec 生成完 tasks.md 就熄火了它不关心执行阶段怎么落地。Superpowers 需要一个已经定义好的任务清单作为起点但这份清单从哪来、里面的约束怎么强制兑现它不管。两个工具通过文件系统交换数据但彼此对对方的内部状态一无所知。OpenSpec 不知道 Superpowers 执行到一半测试失败了要不要回头改规划Superpowers 不知道 OpenSpec 那份 spec 里哪些约束是硬性的必须卡住。你作为开发者就成了两个人之间的翻译官每次状态不对齐就得手动调停。这就是 SDDSpec-Driven Development工作流当前最大的结构性缺陷规划和执行是断层的。你在规划阶段花了 30% 的精力但这些产出物对后续 70% 的执行阶段毫无约束力。规划文档写完的那一刻它就成了历史文件。spec-superflow 这个项目要解决的就是这个衔接问题。它不是一个新框架而是把 OpenSpec 和 Superpowers 的引擎做源码级融合中间加了一个叫 contract-builder 的契约桥接层把两端串成一条自洽的 9-skill 工作流。下面我会给出可复制的目录结构、配置片段并演示一次从规格到执行的串联验证动作。同时说明 TaoToken 作为统一 Key/API 通道怎么让这条流水线里的模型调用不因为换工具而断掉。2. TaoToken 前置给整条 SDD 流水线一个统一入口在讲配置之前先说清楚 TaoToken 在这条工作流里扮演什么角色。OpenSpec 做规划、Superpowers 做执行、spec-superflow 做编排这三者本身都是工作流层面的东西但它们最终都要调用大模型。规划阶段要调模型生成 proposal 和 specs执行阶段要调模型写测试写代码评审阶段要调模型做 code review。如果你每个工具配一个 Key、每个平台换一次 Base URL光是环境变量就能把你绕晕更别说排查「到底是工作流的问题还是 Key 的问题」。TaoToken 在这里的作用是统一 Key/API 通道。你只需要在官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 拿到一个 Key然后在所有需要调模型的地方填同一个 Base URL 和同一个 Key。这样当 spec-superflow 的某个 skill 报错时你能快速判断是工作流状态机的问题还是模型调用的问题而不是在三个不同的配置里来回猜。具体来说TaoToken 提供的是兼容 OpenAI 风格的 API 接口Base URL 是 https://taotoken.net/api模型 ID 按你实际使用的填。对于 Claude Code 这类工具它支持通过环境变量注入 Base URL 和 Key所以 spec-superflow 在 Claude Code 里跑的时候底层模型调用走的就是 TaoToken 这条通道。这里要强调一点TaoToken 不是替代 OpenSpec 或 Superpowers 的东西它不参与规划逻辑也不参与执行纪律它只负责把模型调用这一层统一掉。工作流该怎么走还是怎么走状态机该怎么卡还是怎么卡。它的价值在于当你把 OpenSpec 和 Superpowers 焊进同一条流水线之后模型调用这一层不会成为新的断层。如果你还没拿 Key可以去模型对话页面先试一下接口通不通确认能正常返回再往下配。拿 Key 的入口在 console 的 api-keys 页面文档在 doc 页面。这几个入口我都放在文末的 CTA 里了这里先不展开。3. 可复制配置目录结构 settings 片段 契约文件这一节是整篇的核心我给你一套可以直接抄的目录结构和配置片段。spec-superflow 的安装本身很简单Claude Code 用户两条命令/plugin marketplace add MageByte-Zero/spec-superflow /plugin install spec-superflowspec-superflowCursor 或 Copilot 用户走安装脚本node /path/to/spec-superflow/scripts/install-cursor.mjs装完之后项目根目录会生成一个.spec-superflow.yaml和工作流目录。我建议你手动确认一下目录结构因为后面 contract-builder 生成的契约文件要放在固定位置路径错了状态机就找不到。推荐的目录结构是这样your-project/ ├── .spec-superflow.yaml # 工作流主配置 ├── .spec-superflow/ │ ├── state.json # 状态机当前状态 │ ├── specs/ # OpenSpec 产出的规划文档 │ │ ├── proposal.md │ │ ├── specs.md │ │ ├── design.md │ │ └── tasks.md │ ├── contracts/ │ │ └── execution-contract.md # contract-builder 产出的执行契约 │ └── archive/ # release-archivist 归档目录 └── src/ # 你的业务代码然后是.spec-superflow.yaml的关键配置。这个文件控制状态机行为、契约校验开关、以及模型调用通道。下面这段是我实测能跑通的配置你可以直接复制后改项目名# .spec-superflow.yaml project: your-project-name language: zh-CN # 支持中英双语规划文档和契约都能用中文 state_machine: enforce_hash_check: true # 开启 SHA256 契约校验规划改了契约过期会直接报错 decision_points: true # 开启 8 个 DP 决策点AI 不能自己拍板 max_batch_size: 3 # 每批执行最多 3 个 task防止一次改太多 model: provider: openai-compatible base_url: https://taotoken.net/api api_key: ${TAOTOKEN_API_KEY} # 从环境变量读不要硬编码 model_id: your-model-id # 按你实际使用的模型填 contract: builder: contract-builder output: .spec-superflow/contracts/execution-contract.md intent_lock: true # 意图锁执行阶段偏离意图会被拦截 constraint_checklist: true # 约束清单硬性指标变成可验证检查项环境变量在 shell 里配一次就行Claude Code 和 Cursor 都能读到export TAOTOKEN_API_KEY你的Key export OPENAI_BASE_URLhttps://taotoken.net/api如果你用的是 Claude Code 的 settings 文件可以写进~/.claude/settings.json这样不用每次开终端都 export{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: 你的Key, ANTHROPIC_MODEL: your-model-id } }注意这里三件套要写全Base URL、Key、Model ID。少任何一个spec-superflow 在执行阶段调模型时都会失败。我见过最常见的错误就是只填了 Base URL 和 KeyModel ID 留空结果 build-executor 跑到一半报模型不存在。配置好之后contract-builder 生成的execution-contract.md长这样这是规划到执行的桥接核心# Execution Contract ## Intent Lock 修复 3 个边界条件 bug不改变现有 API 签名。 ## Constraint Checklist - [ ] API 响应时间 200ms来源design.md 第 42 行 - [ ] 不新增外部依赖来源proposal.md 约束段 - [ ] 现有测试全部通过来源tasks.md 验收标准 ## Acceptance Criteria - task-1: 边界条件 A 的测试用例通过 - task-2: 边界条件 B 的测试用例通过 - task-3: 边界条件 C 的测试用例通过 ## SHA256 planning_hash: a1b2c3d4e5f6... contract_hash: f6e5d4c3b2a1...这份契约里的 Intent Lock 是意图锁执行阶段的 AI 做任何决策都要对齐它。Constraint Checklist 是从四份规划文档里提取的硬性约束变成可勾选的检查项。SHA256 是契约签署时对规划文档算的哈希执行前状态机会重新算一遍不一致就锁定执行。这个机制解决了一个很实际的问题你以为在按规划写代码但规划其实悄悄变了。4. 验证请求从规格到执行的串联验证动作配置好之后怎么确认整条流水线真的串起来了我给你一个最小验证动作走一遍从规格到执行的完整链路大概 10 分钟能跑完。第一步在项目根目录运行 workflow-start初始化状态机# 在 Claude Code 里直接输入 workflow-start它会检测当前状态如果.spec-superflow/state.json不存在就初始化然后告诉你下一步该做什么。正常输出会显示当前状态是exploring建议进入 need-explorer。第二步跑 need-explorer 澄清需求。这一步会触发 DP-0 决策点AI 把需求理解结果呈现给你你确认后才进入 spec-writer。你可以故意在需求里埋一个约束比如「这个接口响应时间必须控制在 200ms 以内」看它会不会被写进规划文档。第三步spec-writer 生成四份规划文档。跑完之后检查.spec-superflow/specs/目录确认 proposal.md、specs.md、design.md、tasks.md 都在而且你埋的那个 200ms 约束出现在 design.md 里。第四步跑 contract-builder 生成执行契约contract-builder这一步是验证的重点。跑完之后打开.spec-superflow/contracts/execution-contract.md检查三件事Intent Lock 是不是一句话锁定了核心意图Constraint Checklist 里有没有你埋的 200ms 约束SHA256 字段有没有值。如果约束没被提取出来说明规划文档的格式有问题contract-builder 解析不到。第五步手动改一下 design.md比如把 200ms 改成 300ms然后尝试进入执行阶段build-executor这时候状态机应该直接报错提示哈希不匹配拒绝进入执行。这就是内容级状态检测在起作用。错误信息会告诉你哪个文件变了你确认是误改就回滚是故意改就重新跑 contract-builder 更新契约。第六步回滚 design.md重新跑 contract-builder然后跑 build-executor。这次应该能正常进入执行AI 会按批次执行 task每批执行前后触发 DP-6 批次确认。执行完跑 code-reviewer 做评审最后 release-archivist 收尾归档。整个流程走下来如果每一步的状态转换都符合预期说明 OpenSpec 的规划、contract-builder 的桥接、Superpowers 的执行纪律已经串成一条线了。我实测下来一个中等复杂度的需求从规划到合并大约 40 到 60 分钟其中人类决策时间占 15 分钟左右主要花在 8 个 DP 确认点上。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节我列几个实际会撞到的报错以及怎么对照排查。这些错误大多不是 spec-superflow 本身的问题而是模型调用通道或配置的问题。401 Unauthorized。这个最常见基本是 Key 没配对。检查三件事环境变量TAOTOKEN_API_KEY有没有 export 成功用echo $TAOTOKEN_API_KEY确认settings.json 里的 Key 有没有写错Base URL 是不是https://taotoken.net/api注意结尾不要多加斜杠。如果 Key 是对的还报 401去 console 的 api-keys 页面确认这个 Key 还有效、额度没用完。local proxy failed。这个报错通常出现在你本地配了某种转发但没启动或者 Base URL 指向了本地地址。检查.spec-superflow.yaml里的base_url是不是被改成了 localhost 之类。正确做法是直接指向https://taotoken.net/api不要经过本地中间层。如果你之前配过别的工具留下的环境变量用env | grep -i proxy清一下。reading choices 相关报错。这个一般出现在模型返回格式不符合预期的时候比如你填的 Model ID 不支持某些接口格式。检查model_id是不是你实际能用的模型去模型对话页面确认这个模型能正常返回。如果模型对话页面能通但工作流里报错可能是 spec-superflow 的某个 skill 用了特定的返回字段换个兼容性更好的模型 ID 试试。OAuth 相关报错。如果你用的是 Claude Code 并且之前登录过官方账号可能会和 TaoToken 的 Key 冲突。检查~/.claude/settings.json里是不是同时存在 OAuth token 和 API Key。正确做法是走 API Key 模式把 OAuth 相关的配置清掉确保ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY都指向 TaoToken。契约哈希不匹配。这个不是报错是状态机主动拦截说明规划文档在契约签署后被改了。错误信息会告诉你哪个文件变了。如果你确认改动是有意的重新跑 contract-builder 更新契约如果是误改回滚文件。这个机制是特性不是 bug别想着关掉它。状态机卡在某个状态出不来。检查.spec-superflow/state.json里的当前状态对照 8 个状态的流转顺序exploring → specifying → bridging → approved-for-build → executing → reviewing → merging → closing。如果卡在 bridging说明 contract-builder 没跑成功卡在 approved-for-build说明 DP-5 契约确认没过。手动跑一次对应的 skill 通常能解决。排查的时候记住一个原则先确认模型调用通道通不通再确认工作流状态对不对。模型通道的问题去模型对话页面验证工作流的问题看 state.json 和契约文件。两层分开排查比混在一起猜快得多。6. 把两端焊死之后SDD 流水线才真正跑起来回到最开始那个比喻。OpenSpec 是猛虎Superpowers 是双翼spec-superflow 做的是把翅膀焊在老虎身上。这个「焊」不是物理堆叠而是源码级融合加契约桥接层加内容级状态机让规划阶段的约束真正流到执行阶段。我自己的使用体验是这套工作流最大的价值不在于帮你写出更漂亮的代码而在于帮你避免那些传统工作流下大概率会漏掉的元层面问题。比如规划文档改了但契约没更新、执行阶段顺手重构偏离了本次意图、token 估算和实际注入不一致。这些问题都不在「代码写没写对」的检查范围内而在「事情做没做对」的检查范围内。如果你想把这条流水线跑起来路径是这样的先去官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 拿一个统一 Key把模型调用这一层固定下来然后按第 3 节的配置把.spec-superflow.yaml和 settings 配好接着按第 4 节的六步验证动作走一遍确认从规格到执行的串联是通的遇到报错就对照第 5 节排查。几个入口我放这里按你的需求选要拿 Key 配通道去 API Keys 页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite想先验证模型能不能正常返回去模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite要接 Claude Code 或看完整接入步骤去接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite长期跑编码和 Agent 任务看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewriteAI 编程的下一个阶段不是让 AI 写得更快而是让 AI 写得更稳。SDD 工作流是通往这个目标的必经之路而把 OpenSpec 和 Superpowers 真正焊进同一条流水线是这条路上绕不开的一步。