Cursor 使用心得：ask 模式配合 md 文件与权限配置的实战记录

1. 为什么我把 Cursor 的 ask 模式当成项目里的“第二大脑”Cursor 的 ask 模式简单说就是只读不写的对话模式它不会直接改你的代码而是先读你指定的文件、理解上下文然后给出分析、计划或建议。适合谁适合手上有一堆需求文档、原型图、接口约定但不想让 AI 上来就乱改代码的前端或全栈同学。我这次的真实场景是一个政务类后台系统 P1.1.0 版本迭代涉及法治审核、立法管理、普法管理、政务服务、营商环境、通知公告六大模块前后端分工明确权限配置又特别碎。如果直接把需求丢给 Cursor 让它改大概率会改错文件、漏掉权限判断甚至把 mock 数据写进生产逻辑里。所以我的做法是先在需要改动的目录下写一份.md文件把每个模块要改的点、状态、前后端分工全部列清楚然后用 ask 模式让 Cursor 读一遍这份文档让它先输出修改计划再让它二次整理文档把逻辑理得更顺。等文档稳定后再拆成“功能”和“权限”两个文件分别发给产品和测试。整个过程里ask 模式负责“读文档、理逻辑、出计划”真正的代码改动我另开对话或切到 agent 模式去做。这样既保留了 AI 的理解能力又不会让它越权动代码。下面我把这套工作流完整拆开包括.cursorrules、settings.json骨架、ask 模式提问模板、mock 数据调试方法以及权限配置里最容易踩的坑。2. TaoToken 前置给 Cursor 配一个稳定的模型入口Cursor 本身可以接自己的模型也可以走兼容 OpenAI 协议的第三方入口。我这边习惯用 TaoToken 做统一入口原因是它同时提供模型对话、Coding Plan 和 API Keys 管理切换模型不用改代码只改配置就行。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意 API 地址后面不加 UTM 参数。如果你只是想在 Cursor 里用 ask 模式读文档、做规划其实用模型对话页面就够但如果你要长期做编码、跑 Agent 任务建议直接上 Coding Plan额度更稳。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API Keys 在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。拿到 Key 之后在 Cursor 的模型设置里填 Base URL 和 Key模型名按文档里支持的填。这里有个细节Cursor 的 ask 模式对上下文长度比较敏感如果你把整个项目的.md文件都塞进去容易超限。我的做法是只把当前模块的文档放进对话其他模块用引用按需加载。TaoToken 的模型对话页面可以先用长上下文模型把文档整体读一遍确认逻辑没问题再回到 Cursor 里做局部 ask。3. 可复制配置.cursorrules 与 settings.json 骨架3.1 .cursorrules 骨架.cursorrules放在项目根目录作用是给 Cursor 一个全局行为约束。我的版本重点放在“先读文档、再出计划、不擅自改代码”上# .cursorrules ## 角色 你是一个只读分析助手默认使用 ask 模式。不要直接修改任何文件除非我明确说“开始改代码”。 ## 工作流 1. 每次任务开始前先读取我指定的 .md 文档复述你理解到的改动点。 2. 输出修改计划按模块分组标注前端/后端/权限三类。 3. 如果文档里有状态标记 ⬜保留这些标记并解释含义。 4. 发现文档里前后矛盾的地方先提问不要自己假设。 5. 涉及权限的改动必须单独列出角色-权限对照表。 ## 禁止 - 禁止直接写代码到文件。 - 禁止把 mock 数据当成真实接口。 - 禁止跳过文档直接看代码。这个规则的核心是“先文档后代码”。我试过如果不写这条Cursor 会习惯性地去扫代码库然后给你一堆基于旧代码的猜测反而干扰判断。3.2 settings.json 骨架.vscode/settings.json里主要控制 Cursor 的索引范围和文件排除避免它把 mock 数据、构建产物、日志文件都读进去{ cursor.chat.contextFiles: [ docs/p1.1.0-features.md, docs/p1.1.0-permissions.md ], cursor.chat.excludeFiles: [ **/node_modules/**, **/dist/**, **/*.log, **/mock/**/*.json ], cursor.indexing.maxFileSize: 500000, cursor.indexing.exclude: [ **/coverage/**, **/.git/** ], files.associations: { *.md: markdown } }注意cursor.chat.contextFiles不是官方字段不同版本可能叫法不同你可以把它当成一个“约定字段”实际使用时在对话里用docs/p1.1.0-features.md手动引用更稳。excludeFiles里的mock/**/*.json很重要因为 mock 数据经常是临时占位让 AI 读到容易误判接口已经存在。3.3 文档拆分结构我最终把一份大文档拆成了两个文件docs/ p1.1.0-features.md # 功能改动、联调进度、待办 p1.1.0-permissions.md # 角色-权限对照、按钮可见性 mock/ zffggkxt-permission-spec.md # 权限 mock 配置发给后端参考功能文档里只写“做什么”权限文档里只写“谁能做”。这样 ask 模式读的时候不会把两件事混在一起。比如“审核反馈”这个功能功能文档里写“审核通过需回传审核意见书查看和审核页面都显示审核相关信息”权限文档里写“政法处审核通过需回传处室可查看、下载”。分开之后前端改页面、后端改接口、测试写用例各拿各的文档不会互相干扰。4. ask 模式提问模板与 mock 数据调试4.1 ask 模式提问模板我常用的模板分三步你可以直接复制第一步读文档 docs/p1.1.0-features.md docs/p1.1.0-permissions.md 请先读这两个文件不要看代码。读完后告诉我 1. 一共有几个模块每个模块下有几个改动点。 2. 哪些改动点标记为 待后端哪些标记为 权限待后端。 3. 有没有前后矛盾的地方。 第二步出计划 基于你读到的内容按模块输出修改计划。每个改动点写清楚 - 前端要改什么文件如果文档里没写就写“待确认” - 后端要提供什么接口或字段 - 权限由谁控制 - 验收标准是什么 第三步二次整理 把上面的计划整理成一份更清晰的 .md 文档保留状态标记按“功能”和“权限”分开。整理完后告诉我哪些地方还需要我补充。这个模板的关键是“不要看代码”。因为一旦让 Cursor 看代码它就会基于现有实现去推断而现有实现可能本身就是错的。先纯读文档保证理解的是需求不是现状。4.2 mock 数据调试文档里经常有“接口没有的先 mock 数据”这种要求。我的做法是在src/mock/下建一个zffggkxt-permission-spec.md用表格形式写清楚每个按钮的权限# 权限 mock 配置供后端 meta.auths 参考 | 模块 | 按钮 | 政法处 | 处室 | 其他用户 | |------|------|--------|------|----------| | 法治审核-审核反馈 | 审核通过 | | | | | 法治审核-审核反馈 | 查看 | | | | | 法治审核-审核反馈 | 下载 | | | | | 立法管理-年度计划 | 创建 | | | | | 立法管理-年度计划 | 更新进度 | | | | | 普法管理-普法素材 | 新增 | | | | | 普法管理-普法素材 | 编辑自己 | | | | | 普法管理-普法素材 | 编辑他人 | | | |这份文件发给后端后端可以直接照着改meta.auths。前端在 mock 阶段用这份表控制按钮显隐联调时再换成真实权限字段。注意 mock 数据不要写进settings.json的索引范围否则 ask 模式会把它当成真实配置。4.3 权限配置避坑权限这块最容易出三类问题第一类是“按钮隐藏了但接口没拦”。比如“删除按钮只有政策法规处可见”前端把按钮藏了但后端接口没做角色校验处室用户直接调接口还是能删。所以权限文档里一定要写清楚“前端隐藏 后端校验”两件事。第二类是“查看权限和下载权限不一致”。文档里写“审核通过可下载下载权限与查看权限一致”但实际实现时查看走了 A 接口下载走了 B 接口B 接口漏了权限判断。ask 模式读文档时如果发现这种描述会主动提问这就是先读文档的好处。第三类是“多选回显问题”。比如“负责处室可多选”接口对接后回显有问题文档里标了 。这种问题 ask 模式帮不上忙但可以在文档里写清楚“已对接待联调回显有问题”让测试知道这是已知问题不用重复提。5. 验证请求与成功结果配置完成后怎么验证 ask 模式真的按预期工作我一般跑三个检查。第一个检查在 Cursor 里输入docs/p1.1.0-features.md 请复述这份文档里所有标记为 的改动点。如果它准确列出“年度回显有问题”“成果列表时间有问题”“查看成果权限有问题”这几条说明文档读取正常。第二个检查输入docs/p1.1.0-permissions.md 请输出政法处和处室在普法素材模块的权限差异。正确结果应该是政法处显示所有列表所有按钮处室只能新增和查看各账号仅能维护自己提交的素材。如果它把“其他部门上传的仅可查看”漏掉说明权限文档的表格它没读全需要检查文件是否被 exclude。第三个检查用 TaoToken 的模型对话页面发一条测试请求确认 API 连通。请求体大概是这样{ model: 你配置的模型名, messages: [ {role: user, content: 请用一句话说明 ask 模式和 agent 模式的区别} ], stream: false }返回结果里如果有正常文本说明 Key 和 Base URL 没问题。如果报 401去 API Keys 页面重新生成如果报 404检查 Base URL 是不是写成了https://taotoken.net/api而不是带其他路径。成功的结果是ask 模式能稳定读文档、出计划、标出矛盾点mock 数据能按权限表控制按钮后端拿到权限 spec 后能直接改meta.auths。整个过程不需要 AI 碰代码代码改动由我自己控制。6. 本篇常见错排查错误一ask 模式读不到 .md 文件。现象是输入docs/xxx.md后 Cursor 说找不到文件。先检查文件是否在项目根目录下的docs/里再检查settings.json的excludeFiles有没有误伤。如果文件在.gitignore里Cursor 默认不索引需要手动引用。错误二文档里状态标记被 AI 忽略。比如 权限待后端 被当成普通文字。解决方法是把状态说明表格放在文档最前面并在.cursorrules里写明“保留状态标记并解释含义”。如果还是不行在提问模板里加一句“请逐条列出所有 标记的改动点”。错误三mock 数据被当成真实接口。ask 模式读到src/mock/下的 JSON 后可能会说“接口已存在”。解决方法是把 mock 目录排除索引并在文档里明确写“以下接口为 mock待后端提供”。权限 mock 用.md表格而不是.json也能降低被误读的概率。错误四权限配置前后端不一致。前端按文档隐藏了按钮后端没改meta.auths导致处室用户调接口能拿到数据。排查方法是让 ask 模式输出一份“角色-按钮-接口”对照表然后拿这份表去对后端代码。如果后端说“接口没做权限”那就是文档里没写清楚“后端校验”这一条补上即可。错误五年度回显、多选回显这类联调问题被反复提。这类问题不是配置问题是接口字段问题。文档里标 并写清楚“已对接待联调回显有问题”ask 模式读到时不会重复分析测试也知道是已知问题。如果 AI 反复问就在提问模板里加一句“ 标记的问题已记录不需要重复分析”。错误六TaoToken 请求 401 或 404。401 一般是 Key 失效或没带Authorization: Bearer头404 一般是 Base URL 写错。API 地址是https://taotoken.net/api不要在后面加/v1或其他路径具体以接入文档为准。如果用的是 Coding Plan确认额度是否用完额度不足也会报错。排障和接入相关的问题可以直接看 API Keys 页面和接入文档验证模型是否正常用模型对话页面发一条测试消息最快长期编码和 Agent 任务建议直接开 Coding Plan避免频繁换 Key。