1. 前端项目里 Cursor 三类配置到底怎么分工Cursor IDE 的 Rules、Skills、Subagents 是三个不同层级的能力很多前端同学第一次接触时容易混在一起配结果 Rules 写成了 Skill、Skill 又当 Subagent 用最后 AI 行为完全不受控。我先把三者的边界讲清楚再落到 settings.json 的可复制骨架上。Rules 是「编码宪法」它约束 AI 输出的风格、架构、安全红线属于强制层AI 每次生成代码都要过一遍。Skills 是「工具插件」它给 AI 挂载专项能力比如代码审查、测试生成、性能分析属于按需调用层。Subagents 是「专职子助手」主 AI 把复杂任务拆给子代理并行处理比如组件开发、Bug 排查、文档生成属于任务路由层。这三类配置在前端项目里落地时最容易被忽略的是「统一出口」问题。Rules 里如果硬编码了 API KeySkills 里又写了一份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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册并登录。登录后进入控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 在控制台里可以看到账户余额、调用统计和 Key 管理入口。第二步进入 API Keys 页面创建密钥地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。点击创建后系统会生成一串以 sk- 开头的 Key复制下来先存到本地密码管理器页面刷新后就不再完整显示。第三步确认 API 通道地址。TaoToken 的 API 基址是 https://taotoken.net/api 注意这个地址不带任何查询参数配置时直接填这个即可。模型对话、Coding Plan、接入文档分别对应下面几个入口后面 CTA 会分流用到模型对话体验https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentCoding Plan 长期编码方案https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注意Key 只创建一次就够Rules/Skills/Subagents 共用同一个。不要为每个模块单独建 Key否则轮换时你会疯掉。环境变量建议这样设避免明文写进仓库# macOS / Linux写入 ~/.zshrc 或 ~/.bashrc export TAOTOKEN_API_KEYsk-你的实际Key export TAOTOKEN_BASE_URLhttps://taotoken.net/api# Windows PowerShell写入 $PROFILE $env:TAOTOKEN_API_KEYsk-你的实际Key $env:TAOTOKEN_BASE_URLhttps://taotoken.net/api设完后执行echo $TAOTOKEN_API_KEYWindows 用$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.jsonRules 文件里写前端通用规范比如禁止 any、组件必须函数式、useEffect 依赖完整、导入顺序第三方→内部→样式。Skills 文件里写触发条件和执行流程比如代码审查 Skill 要覆盖规范、性能、安全、架构四个维度。Subagents 文件里写角色定位和约束比如组件开发子代理必须输出 Props 类型定义和测试用例。提示如果你用的是 monorepo把.cursor放在每个子包根目录而不是仓库根这样 Rules 不会互相污染。4. 验证请求重启 Cursor 后确认三类配置生效配置写完不验证等于没写。下面这套验证动作按顺序做每一步都有明确的成功标志。第一步重启 Cursor。settings.json 的改动不会热加载必须完全退出再打开。macOS 用CmdQWindows 用任务管理器确认进程结束。第二步验证 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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_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_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里有完整的参数说明和模型列表配之前扫一眼能省不少试错时间。最后提醒一句settings.json 里的${env:TAOTOKEN_API_KEY}语法依赖 Cursor 版本老版本可能不支持环境变量插值。如果你的 Cursor 版本较旧先在设置里确认是否支持不支持就升级别硬写明文。配置这东西一次写对后面几个月都省心。