你在 Cursor 里改src/api/user.ts明明.cursor/rules下有一条.mdc规则把globs写成了src/api/**/*.ts可 Agent 还是按自己的习惯生成代码——这就是典型的“规则没按 globs 生效”。先别急着加alwaysApply: true这条排障线要拆成两层Cursor Agent 是否判断到了规则以及 Cursor 的模型请求是否稳定走通了通道。要拿 Key、看模型广场和用量从 TaoToken 进入TaoToken 只提供统一 API 通道不读也不写你的.cursor/rules真正核对 frontmatter 与 globs 的是 Cursor Agent。规则本身是给智能体用的系统级指令。它把提示词、脚本、模板打包在一起让同一条约束能在多个对话、多个文件里复用也方便团队共享工作流。Cursor 里常见的规则入口有四类项目规则放在.cursor/rules跟着 Git 走用户规则跟着你的 Cursor 环境走团队规则由 Team 或 Enterprise 在控制台集中管理AGENTS.md则是更轻的 Markdown 替代方案。规则没触发时问题通常不在“模型不会写代码”而在 Cursor Agent 有没有把这条规则加进本次模型上下文。1. Cursor 规则没按 globs 生效时先把.mdc和通道分开查1.1 规则是系统级指令但加载动作在 Cursor Agent 一侧大语言模型在不同补全、不同对话之间不会保留长期记忆。规则的作用是在提示级别提供持久、可复用的上下文。应用规则时Cursor 会把规则内容放到模型上下文的起始位置让模型在生成代码、解释编辑、处理工作流时看到同一套指导。所以“规则没按 globs 生效”首先要看的是这条规则有没有被 Cursor 判断为相关而不是先怀疑模型不听话。项目规则以 Markdown 文件存在.cursor/rules中纳入版本控制可以通过路径模式限定适用范围、手动调用也可以根据相关性自动包含。它适合放三类内容和你代码库相关的领域知识、项目特有的工作流或模板、需要统一的风格与架构决策。比如“所有 API service 必须走内部 RPC 模式”“React 组件文件名和测试文件保持同目录”这类约束放在项目规则里比每次聊天重复说要稳。但这里有个边界必须说清楚TaoToken 只负责模型请求的 API 通道不读.cursor/rules也不会帮你写 frontmatter。规则是否注入由 Cursor Agent 根据 description、globs、alwaysApply 和当前上下文判断。排查顺序应该是先确认 Cursor 能正常请求模型再让 Agent 去核对规则文件如果请求层都不通规则写得再标准也到不了模型上下文。1.2 在 Cursor 模型设置里把 Base URL 填成 TaoToken 通道在开始排查规则之前建议先把 Cursor 的模型通道接稳。打开 TaoToken 注册账号进入控制台创建 API Key这个 Key 在下面的配置里统一写成YOUR_API_KEY不要直接贴到文章、截图或公开仓库。在 Cursor 的模型设置里选择 OpenAI 兼容的 API Key 配置入口按下面字段填写配置项填写内容API KeyYOUR_API_KEYBase URLhttps://taotoken.net/apiModelYOUR_MODEL_ID以 TaoToken 模型广场当时列表为准注意两个细节。第一填进 Cursor 的 Base URL 是https://taotoken.net/api末尾不要加/v1也不要带任何查询参数。第二模型 ID 不要凭记忆写去模型广场复制当前可用的 ID再填到 Cursor 的自定义模型或 OpenAI 兼容模型位置。不同 Cursor 版本入口名称可能略有差异但核心就是“Key Base URL 模型 ID”三件事。配置保存后新建一个 Chat让 Agent 做一个很轻的动作比如解释当前打开文件的作用。如果请求正常返回说明通道已经通了。接下来规则没触发才值得回到.cursor/rules继续查如果这里就报模型请求失败先去控制台确认 Key 和模型 ID而不是继续改 globs。2..cursor/rules里的 frontmatterdescription、globs、alwaysApply 的真实分工2.1 项目规则文件结构与.md、.mdc差异项目规则放在.cursor/rules目录下每条规则是一个 Markdown 文件文件名可以自己定。Cursor 支持.md和.mdc两种扩展名但带 frontmatter 的.mdc更灵活因为你可以通过description和globs控制它什么时候生效。一个常见的目录可能长这样.cursor/rules/ react-patterns.mdc api-guidelines.md frontend/ components.md hooks.mdc.md可以写简单规则适合纯文字说明.mdc带 frontmatter适合需要按文件路径或按相关性触发的规则。也不要把所有规则都塞进一个巨大文件后面讲最佳实践时会展开但在排障阶段先确认你改的文件确实位于.cursor/rules而不是放在.cursor其他子目录或者被编辑器保存成了.md.txt。2.2 四种应用方式对应的 frontmatter 组合Cursor 设置里能看到规则的应用类型不同选项本质上是在改description、globs、alwaysApply这三个属性。可以对照下面这张表应用方式触发逻辑frontmatter 重点Always Apply每个聊天会话都应用alwaysApply: trueApply IntelligentlyAgent 根据描述判断是否相关写好descriptionApply to Specific Files当前文件匹配指定模式时应用写好globsApply Manually在聊天里被提到时应用规则名可被my-rule引用如果你的规则写了globs但应用类型却停留在 Always Apply 或 Apply Intelligently行为可能和预期不一致。反过来如果选了 Apply to Specific Files但globs写得太窄Cursor Agent 也不会在每次对话里强行加载它。排障时要同时看“应用类型下拉菜单”和“文件里的 frontmatter”两边不一致时以实际保存的 frontmatter 为准。2.3 globs 没匹配当前文件时的典型写法globs最常出问题的地方是路径层级。比如--- description: 修改 src/api 下的 TypeScript 服务时遵循内部 RPC 模式 globs: src/api/*.ts alwaysApply: false --- - 定义服务时使用内部 RPC 模式 - 服务名使用 snake_casesrc/api/*.ts只匹配src/api这一层下的.ts文件。如果你改的是src/api/user/detail.ts它不会被匹配。要递归匹配子目录应该写成src/api/**/*.ts。同理**/*.vue会匹配任意目录下的 Vue 文件而frontend/**会匹配frontend下的所有内容。另一个容易忽略的点是“当前上下文里有没有匹配文件”。Apply to Specific Files 的规则通常要在匹配文件进入上下文时才应用。你只打开了一个 README却期望一条只匹配src/api/**/*.ts的规则生效Cursor Agent 没有充分理由把它当成相关规则。排查时先打开一个真正匹配 globs 的文件再重新发起对话。3. 让 Cursor Agent 复现规则不触发的对话模板3.1 先新开聊天不要接着旧上下文猜规则每次被应用时会加到模型上下文开头。旧聊天里已经累积了大量无关上下文继续在里面追问“你为什么没按规则来”很容易把问题搅浑。更稳的做法是保存当前工作新开一个 Chat只打开需要验证的目标文件比如src/api/user.ts再让 Agent 做一次只读排查。这一步也顺便验证了模型通道。如果新 Chat 连普通解释都失败先回到 Cursor 模型设置确认https://taotoken.net/api和YOUR_API_KEY是否填对如果新 Chat 正常但 Agent 依然看不到规则就进入下一步。3.2 给 Agent 的核对提问模板不要问“规则为什么不生效”这种问题太大Agent 容易泛泛而谈。可以给它一个边界清楚的排查任务请只做排查不要改业务代码。 1. 读取 .cursor/rules 下所有 .mdc 和 .md 文件。 2. 列出每条规则的 description、globs、alwaysApply。 3. 对照我当前打开的文件 src/api/user.ts判断哪些规则的 globs 能匹配。 4. 如果某条规则无法匹配指出是路径层级、扩展名还是 frontmatter 写错。 5. 最后给出最多三条修改建议先不要直接写文件。这个模板的关键是让 Agent 把frontmatter和当前文件路径对照起来。Cursor Agent 能读取项目文件、解释规则内容但最终是否修改规则、要不要提交仍然由你决定。规则文件属于你的代码库不属于 API 通道TaoToken 不会替你读写。3.3 用/create-rule反向生成一条可触发规则如果原规则已经被改乱也可以让 Agent 重新生成一份。在 Agent 里输入/create-rule并描述你的真实需求例如“为src/api/**/*.ts创建一条规则要求新增 service 使用内部 RPC 模式服务名使用 snake_case并给出一个短示例。” Agent 会生成带 frontmatter 的规则文件保存到.cursor/rules。另一种方式是在 Cursor Settings 里进入 Rules、Commands点击添加规则。它同样会在.cursor/rules中创建文件。生成后不要直接信打开文件检查三件事description是否让人一看就知道何时相关globs是否覆盖你实际修改的目录alwaysApply是否符合预期。如果只是偶尔手动调用保留alwaysApply: false在聊天里用规则名触发即可。4. 项目规则、团队规则、用户规则、AGENTS.md 的优先级与排障顺序4.1 优先级团队规则 → 项目规则 → 用户规则Cursor 的规则来源不止项目规则。用户规则在 Cursor Settings 里定义作用于整个 Cursor 环境由 Agent 聊天使用适合设定沟通风格或通用编码偏好。团队规则由 Team 和 Enterprise 管理员在控制台集中管理可以配置为对成员必选。项目规则则在每个仓库的.cursor/rules中维护。当多类规则同时存在时优先级大致是团队规则、项目规则、用户规则。所有适用规则会被合并指导冲突时较前的来源优先。所以你的项目规则没按 globs 生效也可能是团队规则先覆盖了同类约束或者用户规则里的全局偏好影响了 Agent 的判断。排查时不要只看当前仓库还要看设置里的用户规则和 Team Rules。4.2AGENTS.md作为简单替代适合不复杂指令AGENTS.md是放在项目根目录或子目录中的纯 Markdown 文件不带元数据也不走.cursor/rules的 frontmatter 结构。它适合那种只需要简单、易读指令的项目比如统一代码风格、说明架构分层而不需要按文件类型精细触发。如果你同时有AGENTS.md和.cursor/rules排查规则没生效时要把两者都看一遍。Agent 可能读到了AGENTS.md里的简单指令也可能因为.cursor/rules的 globs 没匹配而没读到某条专门规则。不要因为AGENTS.md内容短就认为它一定优先或一定不生效实际行为取决于 Cursor Agent 如何合并上下文。4.3 远程导入规则后路径和 globs 会变Cursor 支持从 GitHub 仓库导入远程规则。入口通常在 Cursor Settings 的 Rules、Commands 里添加规则时选择远程规则来源粘贴你有权限访问的仓库 URLCursor 会扫描仓库中的.mdc文件并同步到项目中。导入后的文件一般会放在.cursor/rules/imported/repoName下并保留相对路径。这一步最容易踩的坑是导入后globs仍然按原仓库的目录写但你的项目目录结构不同。比如原规则匹配packages/api/**/*.ts你的项目却把 API 放在src/server/api/**/*.ts那它当然不会触发。导入完成后打开.cursor/rules/imported下的文件把globs改成你项目里的真实路径再重新发起对话验证。5..mdc格式、globs 写法和规则最佳实践5.1description要写成 Agent 能判断“何时相关”的句子如果规则使用 Apply Intelligentlydescription就是 Agent 判断相关性的主要依据。不要写“前端规则”“API 规则”这种太短的话尽量写成一句可判断的场景描述。例如--- description: 当修改 src/api 下的 TypeScript service 时要求使用内部 RPC 模式并保持服务名 snake_case alwaysApply: false --- - 新增 service 时先定义接口再写实现 - 服务名使用 snake_case - 对外返回结构保持统一这样 Agent 看到当前文件是src/api/user.ts更容易判断这条规则相关。描述含糊时它可能选择不加载表现就像“规则没按 globs 生效”。如果规则已经写了精确globsdescription可以更短但仍然建议写清楚触发场景。5.2globs的目录层级与文件类型写globs时可以从窄到宽逐步验证。先用一个具体文件试比如src/api/user.ts确认规则能在这个文件上触发再扩大成src/api/**/*.ts覆盖整个 API 目录最后再考虑是否要覆盖.tsx、测试文件或其他扩展名。不要一上来就写**/*那样等于每次对话都加载规则会变得很重也容易和其他规则冲突。还要注意编辑器里的工作区根目录。Cursor 通常以当前打开的文件夹为根如果你的项目是 monorepo.cursor/rules可能只在某个子包下生效或者根目录规则需要写packages/web/**/*.ts。路径写法和你项目在 Cursor 里的打开方式直接相关拿不准时就让 Agent 读出当前工作区结构再对照修改。5.3 规则正文控制在 500 行以内引用文件而非复制好的规则应该聚焦、可操作、范围清晰。官方建议把规则控制在 500 行以内大型规则拆成多个可组合的小规则并提供具体示例或引用文件。不要在规则里整份复制风格指南这类工作更适合 linter也不要试图穷举所有命令Agent 已经熟悉常见的 npm、git、pytest 等工具。为极少出现的边缘情况写一大堆说明通常只会稀释真正重要的约束。更稳的做法是引用文件路径而不是复制代码。例如写“参考src/api/user.service.ts里的 RPC 定义方式”比把整个 service 文件贴进规则更耐维护。代码一变复制内容就过时引用文件仍然有效。规则保持短Agent 判断相关性的负担也更小。5.4 提交 Git并在 Agent 重复犯错后更新项目规则放在.cursor/rules中跟着版本控制走。把规则提交到 Git团队成员拉取后就能受益。不要等规则完美才提交先从简单规则开始只有当你发现 Agent 一再犯同样的错误时再新增或更新规则。在真正理解项目模式之前不要过度优化。如果你在 GitHub 的 issue 或 PR 里看到 Agent 又犯了老问题也可以让 Cursor Agent 帮你更新对应规则。更新后重新发起对话确认 globs 和描述仍然匹配当前文件。规则不是一次写完就结束它更像代码库里的约束文档会随着架构和约定变化。6. globs 看似匹配但 Cursor 不加载的排障清单6.1 文件位置、扩展名、frontmatter 是否合法先看文件到底在哪。它必须在.cursor/rules下而不是.cursor/rules-backup、.cursor/commands或项目根目录。扩展名必须是.md或.mdc.mdc文件开头要有合法的 frontmatter。---必须成对出现description、globs、alwaysApply的缩进和冒号不要写错。YAML 对大小写敏感alwaysApply不要写成always_apply或alwaysapply。再看规则有没有被设置里的应用类型覆盖。有时候文件里写着alwaysApply: false但设置下拉菜单被改成了 Always Apply有时候文件里写了globs但下拉菜单选了 Manual。两边不一致时重新保存一次规则文件或者在 Settings 里重新选择应用类型再刷新 Cursor。6.2 globs 与当前上下文文件是否一致打开一个你认为应该匹配的文件确认它的完整路径。比如你打开的是src/api/v2/user.ts规则写的是src/api/*.ts那就不匹配规则写的是src/api/**/*.ts才匹配。再确认文件扩展名.ts和.tsx、.js和.jsx是不同模式。monorepo 里还要确认工作区根目录src/api/**/*.ts可能只覆盖当前子包不会覆盖整个仓库。如果 globs 本身没问题就新开 Chat只保留目标文件上下文再让 Agent 读取.cursor/rules并列出匹配结果。不要在一个已经聊了几十轮的旧会话里验证旧上下文会干扰判断。6.3alwaysApply、手动、Apply Intelligently 的混淆alwaysApply: true的规则会应用到每个聊天会话。alwaysApply: false时Cursor 会把描述发给 Agent由它决定是否需要应用如果你选择 Apply to Specific Files则更依赖globs匹配如果选择 Apply Manually需要在聊天里用规则名提及。很多人把“我有 globs”误解成“每次都会自动加载”实际上只有当前文件匹配并且规则被判断为相关时它才会进入上下文。所以当规则没有触发时先确认你想要的是自动触发还是手动触发。如果是手动触发就在聊天里输入my-rule如果是按文件触发就打开匹配文件如果是希望每个会话都带上再考虑alwaysApply: true。不要为了省事把所有规则都设成 Always Apply上下文会变得很重。6.4 模型通道异常与规则不生效的区分规则不生效和模型请求失败是两回事。模型通道有问题时Cursor 可能报请求错误Agent 根本拿不到完整上下文规则文件有问题时Agent 能正常回答只是没有按.mdc里的约束执行。排查时先用一个普通问题确认 Cursor 能正常请求模型比如让它解释当前文件。如果这里就失败回到 Cursor 模型设置检查https://taotoken.net/api、YOUR_API_KEY和模型 ID。如果普通问题正常但一改代码就不按规则来再回到.cursor/rules检查 frontmatter、globs、应用类型和优先级。也可以去 TaoToken 控制台看一下这次调用是否记录成功用它来确认通道层没有断。通道层和规则层分开看排障会快很多。7. 规则生效后用 TaoToken 控制台核对这次 Cursor 调用7.1 用同一把 Key 在模型对话里发测试消息规则能触发之后建议做一次交叉验证。回到 TaoToken 模型对话用 Cursor 里那把YOUR_API_KEY发一条测试消息确认模型 ID 和 Base URL 没填错。这里只看两件事请求能不能正常返回以及当前模型是不是你在模型广场选的那个。如果模型对话正常Cursor 里却偶尔失败再检查 Cursor 的模型设置有没有被切换回默认通道。这一步不读你的.cursor/rules只是验证 API 通道。规则文件仍然由 Cursor Agent 在本地项目里读取和判断。把通道验证和规则验证分开后面遇到问题时就不会乱。7.2 看用量、切套餐、创建新 Key如果你要让 Cursor Agent 长时间做代码审查、规则生成、批量重构可以打开 Coding Plan 看当前套餐是否够用。需要给团队或另一台机器分开发 Key 时在 控制台 API Keys 里创建新 Key仍然用YOUR_API_KEY这种占位方式管理不要把真实 Key 写进.cursor/rules或提交到 Git。最后再提醒一句.mdc规则没按 globs 生效时先让 Cursor Agent 把.cursor/rules下的 frontmatter、globs、alwaysApply 列出来再打开一个真正匹配的文件重新发起对话。TaoToken 负责让模型请求走通不负责替你判断规则相关性真正决定规则是否进入上下文的是 Cursor Agent。