企业官网建设流程全解析

1. OpenSpec 规范驱动开发到底解决什么问题

OpenSpec 是一个面向 AI 编程的规范驱动开发工具，核心作用是在你每次让 Claude Code 写代码之前，先把项目规范、变更流程、业务上下文注入到对话里。它适合已经在用 Claude Code、Cursor、Trae 这类 AI 编程工具，但总觉得 AI “记不住项目规则”“改代码前不问清楚就动手”的开发者。

我试过直接让 Claude Code 改一个已有项目的接口层，结果它上来就把旧的字段名全改了，理由是“更规范”。问题在于，它根本不知道这个字段名是上游系统约定死的。OpenSpec 要解决的就是这类问题：让 AI 在动手前先读规范、先提变更提案，而不是凭感觉写代码。

它的工作方式可以理解成给 AI 装了一个“项目入职手册”。每次对话开始时，AI 先读根目录的 AGENTS.md，判断你这句话是不是涉及提案、变更、架构调整。如果是，它再去加载 openspec/AGENTS.md 里的详细规范，按三阶段流程走：创建变更提案、实现变更、归档变更。整个过程不是靠 AI 自觉，而是靠文件结构和关键词触发机制来约束。

对个人开发者来说，OpenSpec 的价值在于减少“AI 改错方向”的返工；对团队来说，它把变更提案变成了可审查、可归档的文档，而不是散落在聊天记录里。下面从安装、目录结构、TaoToken 接入、验证流程到排错，一步步走完。

2. 安装 OpenSpec 并初始化项目规范目录

OpenSpec 通过 npm 全局安装，命令很短，但初始化时的选择会影响后续目录结构，这一步需要留意。

2.1 全局安装与版本确认

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

安装完成后，openspec --version能输出版本号就说明 CLI 可用。如果提示 command not found，先检查 npm 全局 bin 目录是否在 PATH 里，这是最常见的环境问题。

2.2 在项目目录下初始化

cd /path/to/your-project openspec init

初始化时 OpenSpec 会提示你选择使用的 AI 工具，选项包括 Claude Code、Cursor、Trae、Qoder 以及 Other Tools。选择不同工具，生成的目录结构会有差异。以 Claude Code 为例，初始化后目录大致如下：

.claude/ ├── commands/ │ └── openspec/ │ ├── apply.md │ ├── archive.md │ └── proposal.md ├── AGENTS.md └── CLAUDE.md openspec/ ├── AGENTS.md ├── project.md ├── specs/ └── changes/

commands/openspec下三个文件分别对应执行已批准变更、归档已完成变更、发起新变更提案。你在 Claude Code 里输入/openspec:proposal，就会触发 proposal.md 里定义的规范，让 AI 按格式创建变更提案。

2.3 核心文件 AGENTS.md 的作用

根目录的 AGENTS.md 是 Claude Code 每次对话的“第一课”，里面有一段被<!-- OPENSPEC:START -->和<!-- OPENSPEC:END -->包裹的托管块，告诉 AI：当请求里出现提案、规范、变更、计划等字眼时，去打开@/openspec/AGENTS.md。这个托管块不要手动删，openspec update会刷新它。

openspec/project.md则是项目知识库，放项目目标、核心业务术语、技术栈说明、文档索引。它不会每次对话都加载，只有触发 OpenSpec 规范后才会被间接读取。所以通用编码风格放根目录 AGENTS.md，业务上下文放 project.md，这个分层要分清。

如果你用的是 Trae 且版本较老，初始化时选 Other Tools，然后手动把 AGENT.md 内容粘贴到 Trae 的“项目规则”里。较新版本已经能自动读取 AGENT.md，可以先试自动加载，不生效再手动配。

3. 把 API endpoint 改到 TaoToken 统一 Key 通道

OpenSpec 本身不绑定模型服务，它负责规范注入，真正执行编码的还是 Claude Code 这类工具。如果你希望 Claude Code 走统一的 Key 通道，需要改的是 Claude Code 的 API 配置，而不是 OpenSpec 的配置。这一步把 Base URL、Key、Model ID 三件套写全。

3.1 Claude Code 的 settings 配置片段

Claude Code 读取的配置文件通常在用户目录下，路径为~/.claude/settings.json。你可以把 API endpoint 指向 TaoToken 的统一通道，配置片段如下：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "你的 TaoToken API Key", "ANTHROPIC_MODEL": "claude-sonnet-4-20250514" } }

三个字段对应关系要记牢：Base URL 是https://taotoken.net/api，Key 从 TaoToken 控制台的 API Keys 页面生成，Model ID 按你实际要用的模型填。改完后重启 Claude Code，让它重新读取配置。

3.2 用环境变量方式临时切换

如果你不想改全局 settings，也可以在启动 Claude Code 前用环境变量覆盖：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_AUTH_TOKEN="你的 TaoToken API Key" export ANTHROPIC_MODEL="claude-sonnet-4-20250514" claude

这种方式适合多项目切换，但每次开新终端都要重新 export。长期用还是写进 settings.json 更省事。

3.3 获取 Key 与查看可用模型

Key 在 TaoToken 控制台的 API Keys 页面创建，创建后复制保存，页面不会再次完整显示。可用模型列表可以在模型对话页面里试跑确认，也可以查阅接入文档里的模型说明。如果你主要做长期编码和 Agent 任务，Coding Plan 页面有对应的套餐说明，按自己的调用量选。

配置完成后，Claude Code 的请求会走 TaoToken 通道，OpenSpec 的规范注入流程不受影响，两者是叠加关系：OpenSpec 管“AI 该读什么规范”，TaoToken 管“AI 的请求发到哪里”。

4. 一次完整规范驱动编码流程的验证

配置好之后，需要跑一次完整流程确认 OpenSpec 和 TaoToken 通道都正常工作。下面用一个“给用户接口加分页参数”的变更来演示。

4.1 发起变更提案

在 Claude Code 里输入：

/openspec:proposal 给 /api/users 接口增加 page 和 pageSize 分页参数

预期行为：Claude Code 读取根目录 AGENTS.md，识别到“提案”关键词，加载 openspec/AGENTS.md，然后按 proposal.md 的规范在openspec/changes/下创建一个变更目录，里面包含提案说明、影响的 spec 文件、任务清单。你会看到类似输出：

Created change: add-user-pagination openspec/changes/add-user-pagination/proposal.md openspec/changes/add-user-pagination/tasks.md openspec/changes/add-user-pagination/specs/users/spec.md

4.2 校验变更

openspec validate add-user-pagination

预期输出是校验通过，没有格式错误。如果提案里缺少必要字段，这里会报具体哪一行不符合规范。

4.3 实现变更

提案确认后，在 Claude Code 里输入：

/openspec:apply add-user-pagination

AI 会读取 tasks.md，按任务清单逐项改代码。因为规范里已经写清了接口路径、参数名、默认值，AI 不会自己发明字段名。改完后你可以用git diff检查改动范围是否和提案一致。

4.4 归档变更

openspec archive add-user-pagination

归档后，变更从changes/移到归档区，对应的 spec 更新到specs/下，成为项目当前能力的正式规范。下次再有 AI 对话涉及 users 接口，它会读到已经包含分页参数的 spec。

整个流程跑通，说明 OpenSpec 的规范注入和 TaoToken 的请求通道都在工作。如果中间某一步 AI 没有按规范走，先看第 5 节的排错对照。

5. 常见报错与触发失败排查

这一节按真实报错来对照，遇到问题先定位是通道问题还是规范触发问题。

5.1 401 报错

API Error: 401 Unauthorized

这是 Key 无效或没带上。检查ANTHROPIC_AUTH_TOKEN是否复制完整，有没有多余空格。如果用的是环境变量方式，确认当前终端确实 export 了。Key 泄露或删除后要重新在控制台生成。

5.2 local proxy failed

Error: local proxy failed to connect

这类报错通常是 Base URL 写错或网络不通。确认ANTHROPIC_BASE_URL是https://taotoken.net/api，不要多加路径或斜杠。如果公司网络有出口限制，换网络环境再试。

5.3 reading choices 相关报错

Error: reading choices: unexpected end of JSON input

这通常是响应体不完整，可能和模型 ID 写错有关。确认ANTHROPIC_MODEL是 TaoToken 支持的模型 ID，不要填一个不存在的名字。模型 ID 可以在模型对话页面确认。

5.4 OAuth 相关报错

Error: OAuth token expired

如果你之前用 OAuth 方式登录过 Claude Code，旧的凭证可能还在生效，和新的 Key 通道冲突。清理旧的凭证缓存，确保 settings.json 里只有 TaoToken 的配置。

5.5 AI 不触发 OpenSpec 规范

如果请求发出去了、模型也回了，但 AI 没有走提案流程，通常是触发词没命中。OpenSpec 靠关键词匹配，你的请求里没有“提案”“变更”“规范”这类词，它就不会加载 openspec/AGENTS.md。解决办法是明确说“帮我创建一个变更提案”，或者直接指定“先阅读 openspec/project.md 再回答”，也可以用/openspec:proposal斜杠命令强制触发。

5.6 project.md 业务知识不生效

project.md 只在触发 OpenSpec 规范后才被读取，普通对话不会加载。如果你希望业务知识在日常对话里也生效，把索引写在根目录 AGENTS.md 里，或者在对话中明确要求 AI 先读某个文档。

6. 把 OpenSpec 用顺手的几个实操建议

OpenSpec 的规范文件不是生成完就不能动。初始化出来的 AGENTS.md、project.md、proposal.md 都可以按团队流程改。比如你们要求每个变更提案必须写回滚方案，就在 proposal.md 的模板里加一个回滚章节，AI 下次生成提案时会自动带上。

触发机制这块，建议在根目录 AGENTS.md 里维护一份业务知识索引，把常用文档路径列出来。这样即使没触发 OpenSpec 规范，AI 也能通过索引找到该读的文件。关键词触发是双刃剑，命中就加载、不命中就跳过，所以日常对话里养成“先读某文档再回答”的习惯，比指望 AI 自动想起来更可靠。

归档这一步别省。openspec archive之后 spec 才更新，下次对话 AI 读到的才是最新能力边界。如果只改代码不归档，规范文件和实际代码会逐渐脱节，OpenSpec 的价值就打折了。

最后，TaoToken 的 Key 通道和 OpenSpec 是两层配置，排错时先分清是请求发不出去（通道问题）还是 AI 没按规范走（触发问题）。通道问题看 401、proxy、choices、OAuth 这几类报错；触发问题看关键词和文件路径。两层都确认正常，规范驱动编码的流程就能稳定跑起来。