编辑器支持

本项目支持多种编辑器，包括 Cursor 和 Visual Studio Code。本文档介绍如何在项目中使用这些编辑器，以及如何充分利用它们的特性来提升开发效率。

Cursor 编辑器

Cursor 是一款基于 VS Code 的 AI 代码编辑器，内置强大的 AI 辅助功能，可以显著提升开发效率。

自动配置

项目根目录下的 AGENTS.md 文件会自动被 Cursor 编辑器读取，作为 AI 辅助功能的上下文。该文件包含了完整的开发规范、代码生成原则和最佳实践，确保 AI 生成的代码符合项目标准。

重要提示

Cursor 官方已明确推荐使用 AGENTS.md 替代已废弃的 .cursorrules 文件。新项目应优先使用 AGENTS.md，以避免未来版本的兼容性问题。

核心功能

1. 智能代码补全

Cursor 会根据项目上下文提供智能代码补全建议：

• Tab 补全：在编码时，Cursor 会根据上下文自动提供代码补全建议，按 Tab 键即可接受
• 上下文感知：AI 会分析当前文件、项目结构和相关代码，提供更准确的建议

2. AI 对话功能

使用以下快捷键与 AI 进行交互：

• Cmd/Ctrl + K：内联代码编辑，可以直接在代码中与 AI 对话
• Cmd/Ctrl + L：打开 AI 聊天面板，可以询问代码相关问题、获取解释或实现新功能
• Cmd/Ctrl + I：打开统一的 AI 界面，支持更复杂的交互

3. 代码生成

在 Cursor 中，你可以：

• 选中代码后使用 Cmd/Ctrl + K 让 AI 重构或优化代码
• 在聊天面板中描述需求，让 AI 生成完整的函数或组件
• 使用 @ 符号引用项目中的文件，让 AI 基于这些文件生成代码

使用建议

1. 充分利用 AGENTS.md：

   • Cursor 会自动读取项目根目录下的 AGENTS.md 文件
   • AI 会自动遵循该文件中的规范生成代码
   • 如需修改规范，直接编辑 AGENTS.md 文件即可

2. 引用项目文件：

   • 在 AI 对话中使用 @文件名 引用项目中的文件
   • 例如：@AGENTS.md 可以让 AI 参考完整的开发规范
   • 例如：@src/models/user.mts 可以让 AI 了解用户模型的结构

3. 代码审查：

   • 使用 AI 对话功能审查代码，询问潜在问题
   • 让 AI 检查代码是否符合项目规范

4. 快速开发：

   • 描述需求，让 AI 生成符合项目规范的代码
   • 利用 AI 的上下文理解能力，生成与现有代码风格一致的代码

与 VS Code 的兼容性

Cursor 基于 VS Code 构建，完全兼容 VS Code 的配置：

• 配置文件：.vscode/ 目录下的所有配置都会被 Cursor 读取
• 扩展支持：大部分 VS Code 扩展可以在 Cursor 中使用
• 代码片段：.vscode/*.code-snippets 文件中的代码片段在 Cursor 中同样可用

推荐工作流程

1. 开始新功能：

   • 在 AI 聊天中描述需求：@AGENTS.md 帮我创建一个用户管理页面
   • AI 会根据项目规范生成符合要求的代码

2. 代码优化：

   • 选中需要优化的代码
   • 使用 Cmd/Ctrl + K 让 AI 重构或优化

3. 问题排查：

   • 使用 Cmd/Ctrl + L 打开聊天面板
   • 描述遇到的问题，AI 会提供解决方案

4. 代码审查：

   • 让 AI 检查代码是否符合项目规范
   • 询问潜在的性能或安全问题

更多资源

• Cursor 官方文档
• 项目结构说明

---

Visual Studio Code

为了方便开发，我们针对 Visual Studio Code 专门编写了一些代码片段（snippet），可以用于加速开发。这些代码片段定义在 .vscode/*.code-snippets 文件中，用 VS Code 打开项目时，编辑器会自动读取这些代码片段。之后你就可以通过键盘输入 prefix 字段定义的前缀，来触发对应的代码片段。

提示

你可以参考现有的例子自行添加其他代码片段定义。定义规则如下：

• scope：指定代码片段的作用范围，例如 typescript、javascript 等。若同时支持多个作用范围，用英文逗号隔开。
• prefix：指定代码片段的触发前缀，例如 createTableIfNotExist。
• description：指定代码片段的描述，例如 Create table if not exist。
• body：指定代码片段的内容，支持变量替换。

示例：

{
  "Print to console": {
    "scope": "javascript,typescript",
    "prefix": "log",
    "body": ["console.log('$1');", "$2"],
    "description": "Log output to console"
  }
}

预置的代码片段

createTable

创建数据库表（如果不存在）

{
  "createTableIfNotExist": {
    "scope": "typescript",
    "prefix": "createTable",
    "description": "Create table if not exist",
    "body": [
      "import { createTableIfNotExist } from \"#scripts/DatabaseUtils\";",
      "",
      "// ${1:创建表（如果不存在）}",
      "export async function createTable${2:大写表名}IfNotExist(): Promise<void> {",
      "  await createTableIfNotExist({",
      "    tableName: '${3:下划线连接的小写表名}',",
      "    createTable: (table) => {",
      "      ${4:// table.integer(\"user_id\").unsigned().references(\"user.id\");}",
      "    },",
      "    afterCreated: async (${5:knex}) => {",
      "      ${6:// do something after created table}",
      "    },",
      "  });",
      "}"
    ]
  }
}