1. Cursor 规则设置踩坑记为什么你的 .mdc 规则总是不生效刚接触 Cursor 的时候我一度以为规则功能是个玄学。明明在 User Rules 里写了「所有函数必须加 JSDoc 注释」结果补全出来的代码还是光秃秃一片明明在项目里建了.cursor/rules目录对话时 AI 却像没看见一样继续按自己的风格输出。后来才搞明白Cursor 的规则体系其实是分层的User Rules、Project Rules、.mdc文件三者各管一段搞混了层级就会出现「写了等于没写」的情况。这篇文章要解决的就是这个问题。我会把 Cursor 规则设置与使用的完整链路拆开讲清楚User Rules 管什么、Project Rules 管什么、.mdc文件里的alwaysApply、globs、description这些字段到底怎么配以及怎么把 Cursor 的 Base URL 切到 TaoToken 的统一通道后验证规则在补全和对话两个场景里都按预期触发。适合已经在用 Cursor 但规则总是「时灵时不灵」的开发者也适合想给团队统一代码风格的 Tech Lead。核心检索词先摆出来Cursor 规则设置、User Rules、Project Rules、.mdc 配置。这四个词贯穿全文你跟着操作一遍就能把规则体系跑通。先说结论Cursor 的规则不是「写一条就全局生效」而是按作用域和触发方式分成了四类模式。User Rules 是账号级的跟着你走换项目也在Project Rules 是仓库级的放在.cursor/rules下跟着项目走.mdc文件是 Project Rules 的载体里面的 frontmatter 决定了这条规则是「始终应用」还是「按文件类型自动附加」。把这四类模式搞清楚规则命中率能从「碰运气」变成「可预期」。我实测下来最容易出问题的环节是.mdc的 frontmatter 写错。比如把alwaysApply写成always或者globs忘了加引号导致 YAML 解析失败Cursor 不会报错只会静默忽略这条规则。所以下面我会给出可直接复制的模板你照着改就行。2. TaoToken 前置准备把 Cursor 的 Base URL 切到统一通道在讲规则之前得先把模型通道打通。因为规则验证需要实际发请求如果 Base URL 还是默认的你没法确认规则到底有没有被带上。这里用 TaoToken 做统一入口官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。为什么要在规则教程里插这一步因为 Cursor 的规则触发依赖模型请求而请求走哪个通道会影响你排查问题的路径。如果你用的是默认通道规则不生效你分不清是规则写错了还是通道问题切到统一通道后请求和响应都可控排查起来干净。操作步骤很简单。打开 Cursor进入 Settings找到 Models 或 API 配置区域。不同版本的 Cursor 入口略有差异但核心就三个字段Base URL、API Key、Model ID。这三个字段必须成套配置缺一个都会报错。Base URL 填https://taotoken.net/api注意结尾不要多加斜杠。API Key 去 TaoToken 控制台生成地址是 https://taotoken.net/api-keys 生成后复制粘贴到 Cursor 的 API Key 字段。Model ID 根据你要用的模型填比如claude-sonnet-4-20250514或gpt-4o这类具体以控制台模型列表为准。这里有个坑要提醒Cursor 的 API Key 字段有时候会缓存旧值改完之后建议重启一次 Cursor或者在设置里点一下 Verify 按钮确认连通。如果报 401先检查 Key 有没有多余空格再检查 Base URL 是不是写成了https://taotoken.net/api/带斜杠的版本。配置完成后你可以先在 Cursor 的对话窗口发一句「你好确认通道正常」看能不能收到回复。能收到就说明通道通了接下来再配规则才有意义。如果这一步就卡住先解决通道问题别急着写.mdc。TaoToken 的接入文档在 https://taotoken.net/doc 里面有各客户端的详细配置说明Cursor 的配置也在里面。如果你用的是 Claude Code 或 Cline 这类工具配置逻辑类似都是 Base URL Key Model ID 三件套。3. 可复制配置User Rules 与 Project Rules 的 .mdc 模板这一节是全文的核心给出可直接复制的配置片段。先讲 User Rules再讲 Project Rules 的目录结构和.mdc模板。User Rules 在 Cursor 设置里直接编辑路径是 Settings → Rules → User Rules。它是纯文本不需要 frontmatter写进去就对所有项目生效。适合放「个人编码习惯」类的规则比如注释风格、命名偏好、回复语言。示例始终用中文回复代码注释用英文。 函数必须加 JSDoc 注释参数和返回值都要写。 变量命名用 camelCase常量用 UPPER_SNAKE_CASE。 不要生成 console.log 调试语句用 logger 替代。这四条是我自己常用的你可以按需增删。注意 User Rules 不要写太长超过 20 条之后模型容易忽略后面的内容建议控制在 10 条以内把最重要的放前面。Project Rules 放在项目根目录的.cursor/rules下每个规则一个.mdc文件。目录结构长这样your-project/ ├── .cursor/ │ └── rules/ │ ├── api-convention.mdc │ ├── frontend-style.mdc │ └── test-rule.mdc ├── src/ └── package.json每个.mdc文件由 frontmatter 和正文两部分组成。frontmatter 用 YAML 语法决定这条规则的触发方式。四种模式对应四个字段组合模式frontmatter 写法使用场景AlwaysalwaysApply: true每个文件都适用的规则比如注释规范Auto Attachedglobs: *.ts按文件类型触发比如所有 TS 文件Agent Requesteddescription: ...让 Agent 自己判断是否用Manual无特殊字段靠规则名调用特殊场景手动触发下面给一个完整的.mdc模板文件名api-convention.mdc放在.cursor/rules/下--- description: API 层代码规范适用于所有 service 文件 globs: src/services/**/*.ts alwaysApply: false --- # API 层编码规范 ## 请求封装 所有 HTTP 请求必须通过 src/utils/request.ts 封装禁止直接使用 fetch 或 axios。 ## 错误处理 每个 API 函数必须返回 PromiseResultT 类型错误码统一用 ErrorCode 枚举。 ## 命名 API 函数名以动词开头如 getUserInfo、createOrder、updateProfile。 ## 注释 每个导出的 API 函数必须写 JSDoc包含 param 和 returns。这个模板的关键点globs用了src/services/**/*.ts表示只有 services 目录下的 TS 文件被引用时才附加这条规则。alwaysApply: false表示不强制全局应用。description是给 Agent Requested 模式用的当模型需要判断是否应用时会读这段描述。再给一个 Always 模式的模板文件名comment-rule.mdc--- description: 全局注释规范 alwaysApply: true --- # 注释规范 每个导出的函数、类、接口都必须写注释。 注释用英文格式为 JSDoc。 复杂逻辑块内部要加行内注释说明「为什么」而不是「做什么」。这个规则会对所有文件生效因为alwaysApply: true。注意 Always 模式的规则不要写太多否则会占用大量上下文影响模型对其他规则的理解。如果你用的是 Cline 或 Claude Code配置逻辑类似但文件位置不同。Cline 的 MCP 配置在cline_mcp_settings.jsonClaude Code 的配置在~/.claude/settings.json或项目的.claude/settings.json。Codex 的配置在~/.codex/auth.json里面同样需要 Base URL、Key、Model ID 三件套。这些工具的规则文件格式和 Cursor 不完全一样但核心思路一致分层 按需触发。4. 验证请求确认规则在补全与对话中按预期触发配置写完不算完得验证规则真的生效了。这一节给出具体的验证动作分补全和对话两个场景。先验证补全场景。打开一个src/services/下的 TS 文件输入一个函数名比如getUserInfo然后触发补全默认是 Tab 或 CtrlEnter看你设置。如果规则生效补全出来的代码应该带上 JSDoc 注释并且用request.ts封装而不是直接 fetch。如果补全结果没有注释说明globs没匹配上检查文件路径是不是在src/services/下。再验证对话场景。在 Cursor 对话窗口输入api-convention然后写需求「帮我写一个获取用户列表的 API 函数」。如果规则生效返回的代码应该符合模板里的规范函数名以动词开头、返回PromiseResultT、带 JSDoc。如果返回的代码风格不对说明规则没被附加检查.mdc文件名和后面的名字是否一致。这里有个细节规则名调用的是 Manual 模式不管 frontmatter 里写了什么手动调用都会附加。所以你可以用这个方式强制触发某条规则测试规则内容本身有没有问题。验证通道是否正常可以在对话里问「你当前使用的 Base URL 是什么」模型不一定能准确回答但你可以通过响应速度和质量间接判断。更可靠的方式是看 Cursor 的日志或者用 TaoToken 控制台的请求记录地址是 https://taotoken.net/console 里面能看到每次请求的模型、token 消耗和时间戳。如果你想单独验证模型通道可以用模型对话功能地址是 https://taotoken.net/chat 发一条测试消息确认通道正常。这个和 Cursor 里的通道是同一个验证通过说明 Key 和 Base URL 没问题。实测下来规则不生效的原因八成是这三个frontmatter 格式错误、globs 路径不匹配、规则内容太长被模型忽略。前两个可以通过检查文件解决第三个需要精简规则把不重要的条目删掉。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节对照真实报错给出排查路径。这些报错我在配置过程中都遇到过按顺序排查基本能解决。401 Unauthorized最常见原因是 API Key 无效或过期。排查步骤去 https://taotoken.net/api-keys 确认 Key 还在有效期内检查 Cursor 设置里的 Key 有没有多余空格或换行确认 Base URL 是https://taotoken.net/api而不是其他地址。如果 Key 刚生成等 10 秒再试有时候有缓存延迟。local proxy failed这个报错通常出现在 Cursor 尝试走本地代理但代理没启动时。排查步骤检查 Cursor 设置里有没有开启代理选项如果有关掉确认 Base URL 直接填的是 TaoToken 地址没有经过本地转发重启 Cursor。这个报错和网络环境有关但不需要任何特殊网络工具直连即可。reading choices 报错这个通常出现在模型返回格式不符合预期时。排查步骤确认 Model ID 填的是 TaoToken 支持的模型不要填 Cursor 内置的模型名检查请求体里有没有多余的参数比如stream: true在某些模型上会出问题换一个模型试试比如从gpt-4o换成claude-sonnet-4-20250514。OAuth 相关报错如果你在 Cursor 里登录了账号又同时配了自定义 API Key可能会冲突。排查步骤在 Cursor 设置里退出账号登录只用 API Key 模式或者反过来只用账号登录不配自定义 Key。两者选其一不要混用。Claude Code 的 OAuth 配置在~/.claude/settings.json如果报 OAuth 错误检查这个文件里的apiKey字段和baseUrl字段是否匹配。再补充一个规则相关的报错.mdc文件不生效但没有任何报错。这种情况九成是 frontmatter 的 YAML 语法错了。检查项---必须是文件第一行前后不能有空行globs的值如果有特殊字符要加引号alwaysApply的值是布尔值true或false不要写成字符串true。如果你用的是 CC Switch 或 Cline MCP配置里同样需要 Base URL、Key、Model ID 三件套。CC Switch 的配置文件在~/.cc-switch/config.jsonCline 的在cline_mcp_settings.json。这三个字段任何一个写错都会导致请求失败排查时逐个确认。6. 语义一致 CTA把规则和通道一起用起来规则配好、通道打通之后接下来的动作就顺了。如果你主要是做日常编码补全和对话建议先把 API Key 和接入文档过一遍地址是 https://taotoken.net/api-keys 和 https://taotoken.net/doc 里面有各客户端的完整配置示例。如果你要验证某个模型在规则约束下的表现可以用模型对话功能单独测试地址是 https://taotoken.net/chat 发一条带规则描述的消息看模型是否按规则输出。这个方式比在 Cursor 里反复试快得多。如果你是长期做编码或 Agent 开发规则体系会越来越复杂建议上 Coding Plan地址是 https://taotoken.net/coding-plan 里面有更完整的通道管理和用量统计适合团队协作场景。最后说一个实用技巧.mdc规则文件建议纳入 Git 版本管理放在.cursor/rules/下一起提交。这样团队成员拉取代码后规则自动生效不需要每个人手动配。User Rules 是个人的不纳入版本管理但可以把常用规则整理成文档放在项目 README 里方便新人参考。规则写完之后定期回顾一下。项目演进过程中有些规则会过时比如早期要求「所有函数加注释」后期可能改成「只对导出函数加注释」。过时的规则不仅没用还会干扰模型判断。建议每个 Sprint 检查一次.cursor/rules/目录删掉不再适用的条目。