企业官网建设流程全解析

现在很多团队用 Claude Code 写业务代码，最头疼的不是模型能力不够，而是两件事：一是 AI 上来就写，设计不讨论、测试不写、写完就说搞定了；二是换个会话它就把上次的决策忘干净，两周后想查某个功能为什么这么设计，聊天记录翻到底也找不到。Superpowers 和 OpenSpec 就是冲着这两个痛点来的，一个用技能框架强制 AI 走「先设计、再计划、后编码、必验证」的流程，一个用 specs/ 和 changes/ 双目录把变更决策沉淀成 Git 里的 Markdown。这篇不聊概念，直接以 TaoToken 统一 Key 和 API 通道为接入背景，把两者装进同一个项目里跑一遍，交付可复制的配置片段和逐步验证动作，最后给出这套组合到底值不值得落地的判断依据。

1. 原问题与场景：AI 编码为什么需要「纪律 + 记录」双保险

先说清楚这两个框架各自解决什么，不然后面配置会装得莫名其妙。

Superpowers 是给 AI 编码代理用的结构化工作流框架，作者 Jesse Vincent，核心思路是「不让 AI 直接写代码」。它把开发拆成头脑风暴、写计划、git worktree 隔离、子代理执行、强制 TDD、验证后才算完这几个阶段，每个阶段由独立的 Skill 驱动，AI 不能跳步。最关键的机制是子代理派发：主代理把任务派给实现者写代码，再派给另一个完全独立的审查者审代码，两边互不知道对方干了什么，审查结果相对客观。它擅长的是代码质量，弱项是知识持久化——设计文档写完丢在docs/superpowers/specs/下，没有系统维护机制，换会话就断片。

OpenSpec 是规范驱动开发框架，作者 Tabish Bidiwale，背后公司进了 Y Combinator。它的核心是双文件夹模型：openspec/specs/记录系统当前真实状态，按「能力」组织；openspec/changes/放活跃变更提案，每个变更一个文件夹，里面有 proposal.md（为什么改）、design.md（技术方案）、tasks.md（实现清单）和增量 specs。变更完成后归档，增量合并回主规格。它擅长跨会话的知识持久化和变更审计，弱项是代码质量——不强制 TDD、不做独立审查、不自动开隔离分支。

所以问题就很清楚了：Superpowers 管「代码写得对不对」，OpenSpec 管「为什么做这个变更」。一个在执行层，一个在知识和决策层。真正要验证的是：把它们串在同一个项目里，流程会不会打架、Token 成本能不能接受、产出物能不能对得上。

我试过的场景是一个中等规模的 Node.js 服务，已有代码库，需要加 OAuth 登录。这个场景同时具备「要改现有系统」和「要保证新代码质量」两个特征，正好能压测两者的配合。接入层统一走 TaoToken 的 API 通道，这样模型调用只有一个 Base URL 和一个 Key，排障时不用在多个供应商之间来回切。

需要提前说明的是平台限制：Superpowers 最核心的子代理派发能力，目前主要在 Claude Code 和 Cursor 上效果最好，不是所有工具都支持。OpenSpec 支持 25+ 工具，Claude Code、Cursor、GitHub Copilot、Codex、Windsurf、Gemini CLI 基本都覆盖。所以这套组合的推荐运行环境是 Claude Code，下面所有配置都以它为准。

2. TaoToken 前置：统一 Key 与 API 通道的准备工作

在装两个框架之前，先把模型调用通道理顺。这一步很多人会跳过，结果后面报 401 或者 local proxy failed 的时候，分不清是框架配置问题还是 Key 问题。

TaoToken 在这里的角色很单纯：提供一个统一的 API 入口，让你在 Claude Code 里配置一次 Base URL 和 Key，后续所有模型请求都走这个通道。官网是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 端点是 https://taotoken.net/api ，注意 API 地址不带 UTM 参数，配置时别把查询串抄进去。

第一步，拿 Key。打开 https://taotoken.net/api-keys ，创建一个 API Key，复制出来存好。这个 Key 只显示一次，丢了只能重建。建议按项目建不同的 Key，方便后面看用量。

第二步，确认你要用的模型 ID。这一步很关键，因为 Superpowers 的子代理派发会并发发起多个请求，如果模型 ID 写错，报错信息往往藏在子代理的日志里，主会话只显示一个笼统的失败。在 https://taotoken.net/models 或者模型对话页面 https://taotoken.net/chat 里确认可用的模型标识，记下来。

第三步，配置 Claude Code 的环境变量。Claude Code 读取的是ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN这两个变量。在~/.zshrc或~/.bashrc里加上：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_AUTH_TOKEN="sk-你的TaoToken密钥"

改完执行source ~/.zshrc生效。这里有个坑：如果你之前配过别的 Base URL，一定要确认新变量覆盖了旧值，可以用echo $ANTHROPIC_BASE_URL检查。

第四步，验证通道本身是通的。先别急着装框架，用一条最简单的请求确认 Key 和端点没问题：

curl -s https://taotoken.net/api/v1/messages \ -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "你的模型ID", "max_tokens": 64, "messages": [{"role": "user", "content": "回复 OK 两个字母"}] }'

返回体里能看到content数组且有文本内容，说明通道正常。如果返回 401，先查 Key 是否复制完整、有没有多余空格；如果返回 404，检查 Base URL 是不是多写了/v1或者少了/api。

第五步，长期编码场景可以考虑 Coding Plan。如果你打算把 Superpowers 的多代理流程跑在真实项目上，Token 消耗会比单代理高不少，按量计费容易失控。Coding Plan 页面在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite ，适合这种高频、长会话的编码场景。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，配置细节以文档为准。

这一步做完，你应该有一个能跑通的 API 通道、一个确认可用的模型 ID、以及 Claude Code 里生效的环境变量。后面两个框架的所有请求都会复用这套配置，不需要各自再配一遍。

3. 可复制配置：Superpowers 与 OpenSpec 的安装与 settings 片段

这一节是全文的操作核心，所有片段都可以直接复制。顺序上建议先装 OpenSpec 再装 Superpowers，因为 OpenSpec 的初始化会生成 AGENTS.md，Superpowers 的会话加载会读这个文件，顺序反了可能要手动补。

3.1 安装 OpenSpec 并初始化目录

OpenSpec 需要 Node.js >= 20.19.0，先确认版本：

node -v

低于要求就先升级。然后全局安装：

npm install -g @fission-ai/openspec@latest

在项目根目录执行初始化：

cd /path/to/your-project openspec init

初始化完成后，项目根目录会多出一个openspec/文件夹，里面有AGENTS.md（AI 代理行为指引）、project.md（项目信息）和config.yaml（配置文件）。同时会生成specs/和changes/两个子目录。目录结构大致是这样：

openspec/ ├── AGENTS.md ├── project.md ├── config.yaml ├── specs/ │ └── auth/ │ └── spec.md └── changes/ └── add-oauth/ ├── proposal.md ├── design.md ├── tasks.md └── specs/

config.yaml里可以指定默认工具和模型相关参数。一个最小可用的配置片段如下，注意路径和字段名以你本地生成的文件为准，不要整段覆盖，只改需要改的项：

# openspec/config.yaml version: 1 tools: - claude-code defaults: change_dir: changes spec_dir: specs

project.md里写清楚项目背景，这段内容会被 AI 在生成提案时读取，写得越具体，proposal 的质量越高。比如：

# 项目信息 - 技术栈：Node.js 20 + Express + PostgreSQL - 认证现状：仅支持邮箱密码登录，session 存 Redis - 本次目标：新增 OAuth 登录，保留原有登录方式 - 约束：不引入新的认证中间件，复用现有 session 机制

3.2 安装 Superpowers 插件

Claude Code 里直接输入插件安装命令：

/plugin install superpowers@claude-plugins-official

装完之后每次新开会话会自动加载，不需要手动启动。它支持 Cursor、Codex、Gemini CLI 等，但子代理派发能力在 Claude Code 和 Cursor 上最完整。

3.3 Claude Code settings 片段

Claude Code 的项目级配置在.claude/settings.json，这个文件可以跟 Git 走，团队共享。一个包含 TaoToken 通道和两个框架协作的配置片段如下：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "sk-你的TaoToken密钥" }, "permissions": { "allow": [ "Bash(git worktree:*)", "Bash(npm test:*)", "Bash(openspec:*)" ] }, "includeCoAuthoredBy": false }

这里三个点要注意。第一，env里的 Key 不要提交到公开仓库，团队协作时用环境变量注入或者本地覆盖文件。第二，permissions.allow里放行git worktree是因为 Superpowers 会自动创建隔离工作树，不放行会卡在权限确认上。第三，放行openspec命令是为了让/opsx:*系列命令能顺利执行。

如果你用 Cline 或者带 MCP 的客户端，配置思路一样，Base URL 填https://taotoken.net/api，Key 填同一个，Model ID 填你在模型列表里确认的那个。三件套缺一不可：Base URL、Key、Model ID，少一个都会在请求阶段报错。

3.4 两个框架的协作约定

装完之后要在项目里明确分工，否则两个框架都会抢「需求探索」和「设计」阶段。建议在AGENTS.md里加一段约定：

## 工作流约定 - 需求探索与变更提案：使用 OpenSpec 的 /opsx:explore 和 /opsx:propose - 代码实现与质量保障：使用 Superpowers 的 brainstorming 和子代理执行 - 变更收尾：使用 OpenSpec 的 /opsx:verify 和 /opsx:archive - 禁止在 OpenSpec 提案未确认前直接进入编码阶段

这段约定是给 AI 看的，也是给团队看的。没有它，AI 很可能在 OpenSpec 还没生成 proposal 的时候就被 Superpowers 拉去写代码，两边产出物对不上。

4. 验证请求与成功结果：跑一遍 OAuth 变更的完整流程

配置装好只是开始，真正要验证的是流程能不能跑通、产出物对不对得上。这一节按三段式走一遍：OpenSpec 想清楚要做什么，Superpowers 保证做得对，OpenSpec 收尾归档。

4.1 第一段：用 OpenSpec 生成变更提案

在 Claude Code 会话里输入：

/opsx:explore 我想给现有服务加 OAuth 登录，先看看当前认证相关的代码结构

这一步 AI 会去读openspec/specs/auth/spec.md和相关源码，输出一份现状梳理，不会直接改代码。确认现状描述准确后，进入提案：

/opsx:propose add-oauth

然后快进生成所有规划文档：

/opsx:ff

执行完检查openspec/changes/add-oauth/目录，应该有四个文件。proposal.md里能看到「为什么改、改什么」的说明，design.md里有技术方案，tasks.md里是实现清单，specs/下是增量规格，标注了 ADDED / MODIFIED / REMOVED。成功的结果是：tasks.md 里的任务粒度足够细，每条能对应到具体文件和函数，而不是「实现登录功能」这种笼统描述。

这一步的验证动作很简单：打开tasks.md，数一下任务条数。如果只有三五条，说明拆得不够细，回到/opsx:propose补充约束条件重新生成；如果有二三十条且每条都能落地，说明提案质量合格。

4.2 第二段：切到 Superpowers 执行

拿到 proposal 和 design 之后，进入 Superpowers 的流程：

参考 openspec/changes/add-oauth/design.md 和 tasks.md，进入 brainstorming 阶段

AI 会先问一堆问题：OAuth 提供商选哪个、已有用户怎么迁移、session 怎么兼容、安全要求是什么。回答完之后它会给出 2-3 种方案让你选。这里有个门禁：设计没通过，一行代码都不许写。

方案确认后，让它拆计划：

把选定的方案拆成 2-5 分钟粒度的执行步骤，每步写清楚改哪个文件的哪段代码

然后进入子代理执行阶段。Superpowers 会自动创建 git worktree 隔离分支，主代理把任务派给实现者写代码，写完派给审查者审。审查分两轮：先看代码符不符合 design.md 的规格，再看代码质量。不通过就打回重做。

这一步的成功结果有几个可观察的信号。第一，git worktree list能看到一个新的隔离工作树，分支名类似superpowers/add-oauth。第二，测试文件先于实现文件出现，因为强制 TDD，没有失败测试就不能写生产代码。第三，审查阶段会有独立的审查输出，指出具体哪一行不符合规格，而不是笼统说「有问题」。

4.3 第三段：回到 OpenSpec 收尾

代码写完、测试通过之后，回到 OpenSpec 验证一致性：

/opsx:verify

这一步检查代码实现是否和design.md、增量 specs 对得上。如果实现过程中偏离了设计（比如临时换了一个库），verify 会指出来，你要么改代码，要么回头改 design.md 并说明原因。

确认一致后归档：

/opsx:archive add-oauth

归档会把changes/add-oauth/specs/下的增量合并回specs/auth/spec.md，变更文件夹移到归档区。成功的结果是：specs/auth/spec.md里能看到 OAuth 相关的条目，changes/下不再有活跃的 add-oauth 文件夹。

4.4 验证结果对照表

整条链路跑通之后，你手上会有三样东西：一份可追溯的变更记录（proposal → design → specs → tasks）、一个隔离分支上的高质量代码（TDD + 独立审查）、以及合并回主规格的系统状态更新。这三样正好对应开头说的两个痛点。

5. 本篇常见错排查：401、local proxy failed、reading choices 与 OAuth 报错

这一节按真实报错来，每个都给出定位路径和修复动作。排障时记住一个原则：先确认是通道问题还是框架问题，再往下查。

5.1 401 Unauthorized

最常见的报错，出现在 curl 验证或者 Claude Code 首次请求时。原因通常是三类：Key 复制不完整、Key 前后有空格、环境变量没生效。

定位动作：先echo $ANTHROPIC_AUTH_TOKEN看值对不对，注意有没有换行符混进去。然后用 curl 单独测一次，排除框架干扰。如果 curl 通但 Claude Code 报 401，检查.claude/settings.json里的env是否覆盖了 shell 里的变量，两者冲突时以配置文件为准。

修复：重新在 https://taotoken.net/api-keys 复制 Key，粘贴时确认没有多余字符，改完重启 Claude Code 会话。

5.2 local proxy failed

这个报错通常出现在请求发不出去的时候，本质是网络层或端点配置问题。先检查ANTHROPIC_BASE_URL是不是写成了https://taotoken.net/api/带尾斜杠，某些客户端对尾斜杠敏感。再确认没有把 UTM 查询串抄进 Base URL，API 地址就是干净的https://taotoken.net/api。

如果端点没问题，检查本地是否有其他工具占用了同名环境变量。用env | grep ANTHROPIC看一遍，有重复的清理掉。修复后重开会话再试。

5.3 reading choices 相关报错

这类报错一般出现在响应解析阶段，提示读取 choices 字段失败。原因多半是模型 ID 写错，返回体结构和你预期的不一致。回到模型列表确认准确的 Model ID，注意大小写和版本后缀。在.claude/settings.json或者请求参数里统一改成确认过的 ID。

还有一种情况是请求参数里max_tokens设得过大，超出模型限制，返回体里没有正常内容。把max_tokens降到合理范围（比如 4096）再试。

5.4 OAuth 流程中的授权报错

这个不是通道问题，是业务代码问题，但在验证阶段容易和框架问题混淆。典型表现是/opsx:verify报实现与规格不一致，追下去发现是 OAuth 回调地址配错或者 state 参数没校验。

定位动作：先看design.md里写的回调地址和实际代码里的是否一致，再看tasks.md里有没有「校验 state 参数」这一条被跳过。Superpowers 的审查阶段通常会抓这类问题，但如果审查被跳过（比如手动改了代码没走流程），就会漏到 verify 阶段。

修复：按 design.md 补齐实现，或者如果设计本身有问题，回头改 design.md 并在 proposal 里补充说明，然后重新走 verify。

5.5 子代理派发失败

Superpowers 的子代理执行阶段如果卡住或者报错，先确认平台支持。Claude Code 和 Cursor 支持子代理派发，其他工具可能不支持，会退化成单代理模式或者直接失败。检查.claude/settings.json的permissions.allow里有没有放行git worktree，没放行会卡在创建隔离分支这一步。

还有一个隐蔽的坑：Token 预算不足时，子代理请求会被限流，表现为部分任务完成、部分任务超时。这时候去 Coding Plan 页面确认额度，或者临时降低并发任务数。

5.6 规格漂移

不是报错，但比报错更麻烦：你在工作流之外直接改了代码，specs/和实际代码对不上。表现是下次/opsx:verify报一堆不一致，或者 AI 基于过时的 spec 生成错误的提案。

修复习惯比修复动作重要：任何代码改动都走/opsx:propose起头，哪怕是小改动。如果已经漂移了，先跑/opsx:verify拿到差异清单，逐条决定是改代码还是改 spec，然后/opsx:archive重新对齐。

6. 语义一致 CTA：这套组合到底值不值得落地

跑完一遍之后，判断标准其实很具体，不用纠结概念。

如果你是全新项目、用 Claude Code、Token 预算宽裕，Superpowers 单独上就够，从第一天起代码质量有保障，TDD 和独立审查是实打实的。如果你是在已有代码库上持续迭代、团队人多、有合规审计需求，OpenSpec 单独上更实用，变更记录和知识库在大型项目里的价值会随时间放大。两个一起用的前提是你能接受更高的 Token 消耗——OpenSpec 本身很省，但叠加 Superpowers 的多代理架构后，整体消耗大概是单独用 OpenSpec 的 4-6 倍，这个成本要提前算进去。

还有一个提醒：别过度使用。修个小 bug、改个配置、做个快速原型，不需要上这套工作流。杀鸡用牛刀只会拖慢节奏。这两个框架解决的是「AI 编码缺乏系统性」的问题，不是所有场景都需要系统化。

如果你决定落地，接入层建议统一走 TaoToken，一个 Key 一个 Base URL 管住所有模型请求，排障时不用在多个供应商之间切换。API Key 在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 创建，接入细节看 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，长期高频编码场景走 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。配置过程中想快速验证模型是否可用，直接用模型对话页面 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=chat&utm_campaign=rewrite 发一条消息，比在项目里反复试错快得多。

最后说一个实操细节：两个框架的产出物都在 Git 里，建议在 CI 里加一条检查，确认openspec/changes/下没有长期未归档的活跃变更，以及specs/和代码的 diff 不超过阈值。这条检查能防止规格漂移悄悄积累，等发现的时候已经对不上了。