企业官网建设流程全解析

1. 前端项目里 Cursor 三类配置到底怎么分工

Cursor IDE 的 Rules、Skills、Subagents 是三个不同层级的能力，很多前端同学第一次接触时容易混在一起配，结果 Rules 写成了 Skill、Skill 又当 Subagent 用，最后 AI 行为完全不受控。我先把三者的边界讲清楚，再落到 settings.json 的可复制骨架上。

Rules 是「编码宪法」，它约束 AI 输出的风格、架构、安全红线，属于强制层，AI 每次生成代码都要过一遍。Skills 是「工具插件」，它给 AI 挂载专项能力，比如代码审查、测试生成、性能分析，属于按需调用层。Subagents 是「专职子助手」，主 AI 把复杂任务拆给子代理并行处理，比如组件开发、Bug 排查、文档生成，属于任务路由层。

这三类配置在前端项目里落地时，最容易被忽略的是「统一出口」问题。Rules 里如果硬编码了 API Key，Skills 里又写了一份，Subagents 再写一份，密钥就散落在多个文件里，既不好轮换也不好审计。所以本篇的核心思路是：三类配置全部走同一个 Key/API 通道，也就是在 settings.json 里集中声明一次，其余模块引用它。

适合谁看：正在用 Cursor 做 React/Vue/TS 项目、想让 AI 输出稳定符合团队规范、又不想把密钥写得到处都是的前端开发者。下面从环境准备开始，一步步给出可复制的配置。

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

在写 settings.json 之前，先把 Key 和通道准备好。TaoToken 的作用是给 Cursor 提供一个统一的模型调用出口，Rules、Skills、Subagents 三类配置都指向同一个 base URL 和同一个 Key，这样后续维护只需要改一处。

第一步，打开官网 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 注册并登录。登录后进入控制台，地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，在控制台里可以看到账户余额、调用统计和 Key 管理入口。

第二步，进入 API Keys 页面创建密钥，地址是 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。点击创建后，系统会生成一串以 sk- 开头的 Key，复制下来先存到本地密码管理器，页面刷新后就不再完整显示。

第三步，确认 API 通道地址。TaoToken 的 API 基址是 https://taotoken.net/api ，注意这个地址不带任何查询参数，配置时直接填这个即可。模型对话、Coding Plan、接入文档分别对应下面几个入口，后面 CTA 会分流用到：

• 模型对话体验：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
• Coding Plan 长期编码方案：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=
• 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=

注意：Key 只创建一次就够，Rules/Skills/Subagents 共用同一个。不要为每个模块单独建 Key，否则轮换时你会疯掉。

环境变量建议这样设，避免明文写进仓库：

# macOS / Linux，写入 ~/.zshrc 或 ~/.bashrc export TAOTOKEN_API_KEY="sk-你的实际Key" export TAOTOKEN_BASE_URL="https://taotoken.net/api"

# Windows PowerShell，写入 $PROFILE $env:TAOTOKEN_API_KEY="sk-你的实际Key" $env:TAOTOKEN_BASE_URL="https://taotoken.net/api"

设完后执行echo $TAOTOKEN_API_KEY（Windows 用$env:TAOTOKEN_API_KEY）确认能打印出来。这一步做完，settings.json 里就可以用变量引用，而不是硬编码。

3. settings.json 可复制骨架：Rules / Skills / Subagents 三合一

Cursor 的 settings.json 位置分两级：用户级在~/.cursor/settings.json，项目级在项目根目录.cursor/settings.json。前端项目推荐用项目级，这样团队 clone 下来就有一致配置。下面给出完整骨架，你可以直接复制后替换 Key 引用。

{ "taotoken.provider": { "baseUrl": "https://taotoken.net/api", "apiKey": "${env:TAOTOKEN_API_KEY}", "defaultModel": "claude-sonnet-4-20250514", "timeoutMs": 60000 }, "cursor.rules": { "enabled": true, "scope": "always", "files": [ ".cursor/rules/frontend-convention.md", ".cursor/rules/architecture-constraint.md" ] }, "cursor.skills": { "enabled": true, "autoTrigger": true, "items": [ { "name": "frontend-code-review", "path": ".cursor/skills/code-review.md", "triggers": ["代码审查", "review 代码", "检查代码"] }, { "name": "frontend-test-gen", "path": ".cursor/skills/test-gen.md", "triggers": ["生成测试用例", "写测试", "单元测试"] } ] }, "cursor.subagents": { "enabled": true, "routeBy": "task-type", "items": [ { "name": "component-dev", "path": ".cursor/subagents/component-dev.md", "taskTypes": ["component", "ui"] }, { "name": "bug-hunter", "path": ".cursor/subagents/bug-hunter.md", "taskTypes": ["bugfix", "debug"] } ] } }

这份骨架的关键点有三个。第一，taotoken.provider是唯一出口，Rules/Skills/Subagents 都隐式走它，不需要各自再声明 baseUrl。第二，apiKey用${env:TAOTOKEN_API_KEY}引用环境变量，仓库里看不到明文。第三，三类配置都用files或path指向独立的 markdown 文件，settings.json 只做索引，规则内容单独维护，改起来不碰 JSON。

对应的目录结构长这样：

your-frontend-project/ ├── .cursor/ │ ├── settings.json │ ├── rules/ │ │ ├── frontend-convention.md │ │ └── architecture-constraint.md │ ├── skills/ │ │ ├── code-review.md │ │ └── test-gen.md │ └── subagents/ │ ├── component-dev.md │ └── bug-hunter.md ├── src/ └── package.json

Rules 文件里写前端通用规范，比如禁止 any、组件必须函数式、useEffect 依赖完整、导入顺序第三方→内部→样式。Skills 文件里写触发条件和执行流程，比如代码审查 Skill 要覆盖规范、性能、安全、架构四个维度。Subagents 文件里写角色定位和约束，比如组件开发子代理必须输出 Props 类型定义和测试用例。

提示：如果你用的是 monorepo，把.cursor放在每个子包根目录，而不是仓库根，这样 Rules 不会互相污染。

4. 验证请求：重启 Cursor 后确认三类配置生效

配置写完不验证等于没写。下面这套验证动作按顺序做，每一步都有明确的成功标志。

第一步，重启 Cursor。settings.json 的改动不会热加载，必须完全退出再打开。macOS 用Cmd+Q，Windows 用任务管理器确认进程结束。

第二步，验证 Rules 生效。在 Cursor 里新建一个.tsx文件，故意写一行const data: any = {}，然后让 AI 补全或修改这段代码。如果 Rules 生效，AI 会提示 any 类型不合规并给出明确类型定义。如果 AI 照单全收，说明 Rules 没加载，检查cursor.rules.files路径是否正确、文件是否存在。

第三步，验证 Skills 可调用。在聊天框输入「代码审查」，观察 AI 是否按 Skill 定义的结构输出报告，包含合规项、待优化项、严重问题三段。如果 AI 只是泛泛回答，说明触发词没匹配上，检查triggers数组里是否有你输入的词。

第四步，验证 Subagents 路由。输入一个组件开发需求，比如「帮我写一个带搜索防抖的 Select 组件」，观察 AI 是否按 component-dev 子代理的流程走：先输出 API 设计，再给代码，再给测试。如果 AI 直接甩代码，说明routeBy没生效，检查taskTypes是否覆盖了你的任务类型。

第五步，核对请求经 TaoToken 通道发出。打开 TaoToken 控制台的调用记录页面 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，看是否有刚才几次对话的调用记录，模型名、时间戳、token 消耗是否对得上。如果控制台没有记录，说明请求没走 TaoToken，大概率是 baseUrl 写错或环境变量没读到。

可以用一条 curl 命令单独验证通道连通性：

curl -X POST "https://taotoken.net/api/v1/chat/completions" \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-20250514", "messages": [{"role": "user", "content": "回复 ok"}], "max_tokens": 10 }'

返回里能看到choices字段和内容，就说明 Key 和通道都没问题。这一步过了，Cursor 里的配置基本不会因为通道问题失败。

5. 本篇常见错排查：Rules 不生效 / Skills 不触发 / Subagents 不路由

配置过程中最容易踩的坑集中在下面几类，我按现象、原因、修复三步给出排查路径。

现象一：Rules 完全不生效，AI 输出还是老样子。原因通常是scope设成了manually而不是always，或者files路径写成了相对路径但 Cursor 的工作目录不是项目根。修复：把scope改成always，路径统一用相对于项目根的写法，比如.cursor/rules/frontend-convention.md，不要写./rules/xxx.md。

现象二：Skills 触发词命中了但没执行。原因多半是 Skill 文件里缺少「触发条件」段落，或者autoTrigger设成了 false 但你又没手动调用。修复：确保 Skill markdown 里有明确的触发条件描述，且autoTrigger为 true；手动调用时在聊天框输入/frontend-code-review这种带斜杠的格式。

现象三：Subagents 不路由，主 AI 自己干了。原因是routeBy设成了manual，或者taskTypes里的类型和实际任务对不上。修复：把routeBy改成task-type，并在taskTypes里补全你常用的任务类型，比如refactor、test、docs。

现象四：请求没走 TaoToken，控制台无记录。原因可能是环境变量没生效（重启终端后没重新 source），或者 settings.json 里 baseUrl 写成了带路径的https://taotoken.net/api/v1。修复：baseUrl 只写到/api，具体路径由 Cursor 内部拼接；环境变量用source ~/.zshrc重新加载后重启 Cursor。

现象五：Key 泄露到 git 历史。原因是早期把 Key 明文写进了 settings.json 并提交了。修复：立刻在 API Keys 页面 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 吊销旧 Key 重建，然后用git filter-repo清理历史，后续统一用${env:TAOTOKEN_API_KEY}引用。

现象六：Skills 和 Subagents 同时触发导致输出混乱。原因是触发词重叠，比如「代码审查」既在 Skill 触发词里又在 Subagent 任务类型里。修复：把审查类任务只挂在 Skill，把开发类任务只挂在 Subagent，两者触发词不要有交集。

注意：排查时优先看 Cursor 的输出面板（Output Panel）里的日志，它会打印配置加载路径和请求目标地址，比猜快得多。

6. 长期编码与 Agent 场景的接入建议

如果你只是偶尔用 Cursor 补全代码，上面这套配置已经够用。但如果你打算把 Cursor 当长期编码主力，尤其是跑 Agent 类任务（多文件重构、端到端测试生成、跨模块联调），建议把通道和计费方式也规划一下。

长期编码场景的特点是调用量大、模型切换频繁、对稳定性敏感。这时候可以看下 Coding Plan 方案 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，它针对持续编码做了额度优化，比按次调用更划算。接入方式不变，还是同一个 baseUrl 和 Key，只是计费模型不同。

另外，Agent 场景下 Subagents 的并行度会拉高，建议在 settings.json 里给taotoken.provider加一个maxConcurrency字段控制并发，避免瞬时打满额度：

"taotoken.provider": { "baseUrl": "https://taotoken.net/api", "apiKey": "${env:TAOTOKEN_API_KEY}", "defaultModel": "claude-sonnet-4-20250514", "timeoutMs": 60000, "maxConcurrency": 4 }

模型选择上，Rules 校验类任务用轻量模型就够，Subagents 里的复杂重构再切到强模型。可以在 Subagent 文件里单独指定模型，覆盖全局默认值。接入文档 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 里有完整的参数说明和模型列表，配之前扫一眼能省不少试错时间。

最后提醒一句：settings.json 里的${env:TAOTOKEN_API_KEY}语法依赖 Cursor 版本，老版本可能不支持环境变量插值。如果你的 Cursor 版本较旧，先在设置里确认是否支持，不支持就升级，别硬写明文。配置这东西，一次写对，后面几个月都省心。