企业官网建设流程全解析

1. CurSor 智能补全与代码生成：新手第一次上手最容易踩的坑

刚装好 CurSor 的人，十有八九会经历同一个心理落差：听说它补全很神，结果敲了两行代码，发现跟 VS Code 的 IntelliSense 差不多，于是心里嘀咕“就这？”。问题不在工具，在于没搞懂 CurSor 的补全分两层——一层是传统 LSP 给的语法级建议，另一层才是它真正的杀手锏：基于上下文的整段预测。这两层触发方式、接受方式、适用场景完全不同，混在一起用就会觉得“时灵时不灵”。

先把这个核心检索词说清楚：CurSor 是一款基于 VS Code 分支构建的 AI 编辑器，能做什么？它把大模型能力嵌进了编辑、补全、对话、跨文件改写四个环节；适合谁？适合已经会写代码、但想把重复劳动和查文档时间压下去的开发者。它不是替你写项目的魔法棒，而是一个“你起头、它续写、你审校”的协作搭子。

我自己的习惯是这样：新建一个demo.py，先手写函数签名和一句注释，比如# 计算列表平均值，然后回车换行停住。这时候 CurSor 的补全会以灰色幽灵文本（ghost text）形式给出整段实现，按Tab接受，按Esc拒绝，继续打字则自动忽略。注意这里的关键动作是“停住”——很多人敲完注释立刻继续敲代码，补全还没来得及请求就被打断了，自然看不到效果。

补全和生成是两件事，别混淆。补全（Tab 触发）是在你光标处续写，粒度小、频率高；生成（Ctrl/Command + K触发）是你在行内或选中区域内输入自然语言指令，让它重写或新建一段代码，粒度大、需要你明确描述意图。新手最常见的错误，是用Ctrl+K去干补全的活，或者反过来指望 Tab 帮你重构整个文件，两者都会让你觉得“不好用”。

还有一个隐藏设置值得早点打开：在设置里搜索cursor tab，确认自动补全处于开启状态，并留意“接受建议的快捷键”是否被其他插件占用。我试过装了一堆 VS Code 插件后，Tab 键被某个 snippet 插件抢走，补全死活按不出来，排查了半小时才发现是快捷键冲突。这类问题不涉及任何网络配置，纯粹是本地键位打架，遇到先查键位。

补全效果的好坏，很大程度取决于你给的上下文。同样是写一个读取 CSV 的函数，如果你文件顶部已经import pandas as pd，补全会直接给你pd.read_csv(...)；如果没有任何 import，它可能给你一个用标准库csv模块的实现。所以想让补全准，先把依赖和类型标注写清楚，这比反复重试有效得多。

代码生成这块，Ctrl/Command + K的指令写法有讲究。别说“帮我写个函数”，要说“写一个函数，入参是文件路径字符串，返回 DataFrame，遇到文件不存在抛 FileNotFoundError”。指令里包含输入、输出、异常行为，生成质量立刻上一个台阶。生成后别急着接受，用Ctrl+Enter可以看多个候选，挑最贴合项目风格的那个。

实测下来，补全在写样板代码、单元测试、类型转换这类模式化场景里收益最大；在业务逻辑复杂、需要结合领域知识的地方，它给的代码只能当草稿。把预期放对位置，CurSor 的日常体验会顺很多。下一节讲怎么把项目上下文喂给它，也就是 @ 标记和 Rules，这两块才是让它“懂你项目”的关键。

2. CurSor @标记 与 CurSor Rules 前置准备：把项目上下文喂对

在讲具体配置之前，得先建立一个认知：大模型本身不知道你的项目长什么样，它看到的只有你主动塞给它的内容。@ 标记解决的是“这一次对话要引用哪些文件/代码/文档”，Rules 解决的是“以后每次对话都默认遵守哪些约定”。一个是单次上下文，一个是长期约束，配合起来用才完整。

前置准备其实很轻量，不需要任何额外账号或网络工具。你只需要：一个本地项目目录、CurSor 已打开该目录、以及确认 AI 功能在设置里处于可用状态。打开项目后，左侧资源管理器能看到文件树，这就够了。@ 标记的检索是基于当前打开的工作区索引的，所以务必用“打开文件夹”的方式打开项目，而不是单独拖几个文件进来，否则@Codebase这类全局检索会失效。

关于 Rules 的存放位置，这里要区分清楚，很多人第一次配就放错地方。User Rules 是全局的，存在 CurSor 的设置里，对所有项目生效；Project Rules 是项目级的，放在项目根目录的.cursor/rules文件夹下，只对当前项目生效。如果你把项目规范写进了 User Rules，换个项目还在生效，就会互相打架；反过来把通用偏好写进每个项目的.cursor/rules，又得重复维护。判断标准很简单：跟具体技术栈、目录结构、命名约定相关的，放 Project Rules；跟个人表达习惯相关的（比如“回答用中文”“解释要简短”），放 User Rules。

这里插一句模型接入的通用思路。CurSor 自身内置了模型选项，但很多团队会希望统一走自己的模型网关，方便计费和审计。如果你属于这种情况，可以在支持自定义 Base URL 的地方填入统一入口，Key 和 Model ID 三件套要配套填全，缺一个都会报鉴权或模型不存在的错。具体填法以你所用工具的设置为准，核心是 Base URL、Key、Model ID 三者一致。

Project Rules 的文件格式是.mdc，本质是带 frontmatter 的 Markdown。frontmatter 里可以声明这条规则的作用范围（比如只对某类文件生效），正文就是自然语言写的约束。这个设计的好处是规则可读、可版本控制，团队里谁改了规则，git diff 一目了然。相比之下，把规则塞进设置面板的文本框里，改了什么根本追溯不了，所以项目级规范强烈建议用.cursor/rules文件管理。

还有一点容易被忽略：@ 标记和 Rules 不是互斥的。你可以在一次对话里既用@Files引用具体文件，又依赖 Rules 里定义的编码风格，两者叠加。Rules 提供“默认底色”，@ 标记提供“本次重点”，这样模型既有全局约束，又有局部细节，输出质量最稳。

准备阶段最后确认一件事：项目根目录下有没有.cursor/rules这个文件夹。没有就手动建一个，注意是.cursor目录下的rules子目录，别写成.cursorrules单文件（那是旧版写法，新版本已转向目录形式）。建好之后，下一节直接给可复制的配置片段。

3. 可复制配置：CurSor Rules 片段与 @标记 使用示例

这一节给能直接抄的东西。先看 Project Rules 的目录结构和文件内容，再看 @ 标记的实际输入方式，最后给一份 settings 层面的参考片段。

项目级规则目录长这样：

your-project/ ├── .cursor/ │ └── rules/ │ ├── coding-style.mdc │ └── api-conventions.mdc ├── src/ └── package.json

coding-style.mdc的内容可以这样写，frontmatter 用 YAML：

--- description: 项目通用编码风格约束 globs: ["src/**/*.ts", "src/**/*.tsx"] alwaysApply: true --- - 所有导出函数必须写 JSDoc，包含 @param 和 @returns - 使用 2 空格缩进，禁止分号结尾 - 异步操作统一用 async/await，禁止 .then 链式调用 - 错误处理必须捕获并记录日志，禁止空 catch - 组件文件名用 PascalCase，工具函数用 camelCase

api-conventions.mdc针对接口层单独约束：

--- description: API 请求层约定 globs: ["src/api/**/*.ts"] alwaysApply: false --- - 所有请求必须经过统一的 request 封装，禁止直接调用 fetch - 请求参数类型必须显式声明，禁止 any - 接口返回统一解构为 { data, error } 结构 - 超时时间默认 10000ms，可在调用处覆盖

frontmatter 里globs决定这条规则对哪些文件生效，alwaysApply: true表示无论当前打开什么文件都注入，false则只在匹配 globs 的文件被引用时注入。这个粒度控制是 Project Rules 比 User Rules 强的地方。

User Rules 在设置面板里填，内容偏个人偏好，例如：

- 回答使用中文，代码注释也用中文 - 解释代码时先给结论再给理由，控制在 5 行以内 - 不确定的地方明确说“不确定”，不要编造 API

@ 标记的输入方式很直接，在聊天框或Ctrl/Command + K的输入区敲@，会弹出候选菜单，方向键选择、回车确认。几个高频用法：

引用整个文件：输入@Files后继续敲文件名，比如@Files src/utils/format.ts，选中后该文件全文注入上下文。如果文件很大，可以用Ctrl/Command + M切换完整读取和摘要读取，摘要模式只取关键部分，省 token。

引用代码块：输入@Code然后敲函数名或关键词，从索引里选具体片段。这个依赖你本地语言服务的索引质量，TypeScript、Python 这类支持好的语言识别很准。

引用整个代码库检索：@Codebase后面跟你的问题，比如@Codebase 这个项目的鉴权逻辑在哪实现的，它会先做相关性检索再回答，适合“我不知道代码在哪”的场景。

引用目录：@Folders src/components，适合排查路径相关问题，比如“为什么这个组件的相对导入报错”。

引用文档：@Docs需要先在设置里添加文档源，把在线文档地址登记进去，之后才能引用。自己本地写的 JSDoc 不会被它读取，这点要有预期。

引用 Git 信息：@Git可以拉取提交记录和 diff，排查“这次改动引入了什么回归”时有用。

settings 层面，如果你走自定义模型入口，参考片段如下（字段名以实际界面为准，核心是三件套齐全）：

{ "aiProvider": { "baseUrl": "https://taotoken.net/api", "apiKey": "sk-你的密钥", "modelId": "claude-sonnet-4-5" } }

Base URL、Key、Model ID 三者必须来自同一套配置，混用会直接报 401 或模型不存在。填完保存，重启编辑器让配置生效。下一节验证是否真的通了。

4. 验证请求与成功结果：补全、生成、@标记、Rules 四项逐一确认

配置写完不算完，得逐项验证，否则出了问题不知道是哪一环。按补全、生成、@标记、Rules 的顺序来，每项都有明确的成功标志。

补全验证：新建test_completion.py，输入以下内容后停住不动：

def calculate_average(numbers): # 计算平均值

光标停在注释下一行，等一到两秒，应该出现灰色幽灵文本，内容大致是求和除以长度的实现。按Tab接受，代码变成实体。如果没出现，先检查 Tab 补全开关，再检查文件是否已保存到磁盘（未保存的临时文件有时不触发索引）。

生成验证：选中一段代码或空行，按Ctrl/Command + K，输入“把这个函数改成支持传入空列表时返回 0”，回车。成功标志是出现 diff 预览，绿色新增、红色删除，按Accept应用。如果只弹出一个输入框没反应，多半是模型请求没发出去，去看下一节的报错排查。

@标记验证：打开聊天面板（Ctrl/Command + L），输入@Files选中你项目里的某个工具文件，然后问“这个文件导出了哪些函数”。成功标志是回答里准确列出了该文件的导出项，而不是泛泛而谈。如果它答非所问，说明文件没被正确注入，检查文件名是否选对、文件是否在索引范围内。

Rules 验证：这是最容易被跳过但最重要的一项。在.cursor/rules/coding-style.mdc里写一条显眼且可验证的规则，比如“所有函数必须带 JSDoc”。然后让 AI 生成一个新函数，观察输出是否自动带上 JSDoc。如果带了，说明规则生效；如果没带，检查 frontmatter 的globs是否匹配当前文件类型，以及alwaysApply是否为 true。

四项都通过后，做一次综合验证：在一个真实的小需求上走完整流程。比如“给现有的 formatDate 函数加一个时区参数”，先用@Files引用该文件，依赖 Rules 里的风格约束，用Ctrl+K生成改动，最后人工审校。整个过程不需要切换工具，这就是可复用的日常开发工作流。

成功结果的判断标准要具体：补全看幽灵文本是否出现并可接受；生成看 diff 是否可应用；@标记看回答是否引用了正确内容；Rules 看输出是否遵守约定。任何一项不达标，都对应下一节的具体报错。

5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth 逐条对照

这一节按真实报错来，遇到哪个查哪个。

401 Unauthorized：最常见的原因是 Key 填错、Key 过期、或者 Base URL 和 Key 不属于同一套配置。排查顺序是先确认 Key 没有多余空格，再确认 Base URL 末尾没有多余斜杠，最后确认 Model ID 在该入口下确实可用。三件套里任何一个对不上都会 401。如果用的是自定义入口，确认地址填的是 API 地址而不是网页地址，两者路径不同。

local proxy failed：这个报错通常出现在请求根本没发出去的时候，原因可能是本地网络配置、端口占用、或者编辑器代理设置和系统代理冲突。先检查编辑器设置里有没有残留的代理配置，清空后重启。如果公司网络有统一出口，确认该出口允许访问你配置的 API 地址。这个报错和模型本身无关，纯粹是链路问题。

reading choices 相关报错：这类错误一般出现在响应格式不符合预期时，比如返回体里没有 choices 字段，或者返回的是错误对象被当成正常响应解析。常见诱因是 Model ID 填了一个该入口不支持的模型，服务端返回了错误结构。解决方法是换一个确认可用的 Model ID 重试，同时检查请求是否被中间层改写。

OAuth 相关报错：如果你用的是需要 OAuth 授权的模型入口，报错通常提示 token 失效或未授权。处理方式是重新走一遍授权流程，确认授权账号和当前使用的 Key 对应。注意 OAuth token 和 API Key 是两套东西，别混用。授权完成后重启编辑器，让新 token 加载。

@标记 不生效：输入@没弹菜单，或者选了文件但回答没引用。先确认是用“打开文件夹”方式打开的项目，单文件模式索引不全。再确认文件在.gitignore之外，被忽略的文件通常不进索引。最后确认文件已保存，未保存的缓冲区内容可能不被检索。

Rules 不生效：写了规则但 AI 不遵守。检查三点：文件是否放在.cursor/rules目录下、扩展名是否为.mdc、frontmatter 的globs是否匹配当前文件。如果alwaysApply是 false 且 globs 没匹配上，规则就不会注入。另外规则内容要具体可执行，“写好代码”这种描述模型无法落地。

补全不触发：Tab 按了没反应。先查快捷键冲突，禁用可疑插件；再查文件类型是否被排除；最后确认补全开关是开的。如果只有某些文件不触发，多半是语言服务没起来，等索引完成再试。

生成结果质量差：不是报错但很常见。根因通常是上下文不足或指令模糊。补上下文用@Files引用相关文件，补指令就按“输入、输出、异常、风格”四要素写清楚。Rules 里定义好风格约束，能减少每次重复描述。

6. 把 CurSor 用顺的下一步：从单次对话到可复用工作流

四项基础能力跑通之后，真正拉开效率差距的是把它们串成固定动作。我的日常流程是这样的：接到一个小需求，先@Codebase问“相关逻辑在哪些文件”，拿到文件列表后用@Files逐个引用，让 AI 给出改动方案，再用Ctrl+K在具体文件里落地，最后靠 Rules 保证风格统一。整个过程对话和编辑不分离，省掉了复制粘贴到外部聊天工具的来回。

Rules 的维护要有节奏。项目初期规则少，随着踩坑增多逐步补充，比如“这个库的某个 API 有坑，禁止直接调用”。规则文件进版本控制，团队 review 时一起看，比口头约定靠谱。规则别写太多太细，否则模型注意力被稀释，核心约束反而被忽略，控制在十条以内、每条都可验证最合适。

@标记 有个进阶用法值得练：组合引用。一次对话里同时@Files引用实现文件、@Docs引用官方文档、@Git拉最近改动，让模型在“代码现状 + 官方约定 + 近期变更”三重上下文下回答，准确率明显高于只给一个文件。这个组合在排查回归问题时尤其好用。

模型入口这块，如果团队要统一管理，把 Base URL、Key、Model ID 三件套固化到团队配置模板里，新人入职直接填，避免各填各的导致行为不一致。需要生成密钥或查看接入文档时，从统一入口进，别在多个地方散落配置。长期做编码和 Agent 类任务的，可以考虑走 Coding Plan 这类按量方案，把日常补全和批量改写的成本分开核算。

最后说个心态问题。CurSor 的价值不在于“全自动写代码”，而在于把“查、写、改、验”四个动作压缩到一个界面里。补全省打字，生成省草稿，@标记省翻文件，Rules 省反复交代风格。四项各司其职，别指望任何一项包打天下。把今天这套配置跑一遍，再挑一个真实小需求走完整流程，你对它的手感就建立起来了。