Cursor AI编辑器深度实战与高效工作流构建指南：从基础配置到多文件重构与Agent模式全解析

引言

在2026年的软件开发领域，AI辅助编程已经从可有可无的辅助工具演变为开发者日常工作流中不可或缺的核心生产力引擎。Cursor作为一款基于VS Code内核深度改造的AI原生代码编辑器，凭借其强大的代码理解能力、上下文感知补全、多文件重构以及Agent模式等特性，迅速成为全球开发者最青睐的AI编程工具之一。本文将从Cursor的安装配置开始，逐步深入到Composer多文件编辑、Agent自主任务执行、自定义规则配置、@上下文引用机制等核心功能，通过大量实际可运行的代码示例，帮助读者构建一套完整的Cursor高效开发工作流。无论你是刚接触AI编程工具的新手，还是希望进一步挖掘Cursor潜力的资深开发者，本文都能为你提供系统性的实战指导。

一、Cursor概述与核心架构设计理念

Cursor是由Anysphere公司开发的一款AI原生代码编辑器，其底层基于VS Code的内核构建，因此可以完美兼容VS Code的插件生态系统，但在AI集成层面做了深度定制。与传统的VS Code + Copilot组合不同，Cursor从设计之初就将AI作为编辑器的核心交互范式，而非附加功能。这意味着AI能力被渗透到了编码的每一个环节，从代码补全、代码生成、错误修复到代码审查，AI都是第一公民。Cursor的核心架构包含以下几个关键模块：代码索引引擎，负责对整个代码库建立语义索引，使得AI能够理解项目结构和跨文件依赖关系；上下文管理器，负责在用户与AI交互时动态收集相关上下文，包括当前打开的文件、光标位置、选中的代码片段、以及通过@语法显式引用的文件或符号；多模型路由层，支持在不同场景下智能选择最合适的AI模型，例如在代码补全时使用低延迟的模型，在复杂推理任务时使用更强的模型。

Cursor的另一个核心理念是"AI原生交互"。传统编辑器中，开发者通过键盘输入代码，AI仅作为旁路辅助。而Cursor将AI对话、代码生成、多文件编辑整合到了统一的交互流中。开发者可以通过自然语言描述意图，Cursor会理解这些意图并结合代码库上下文生成或修改代码。这种交互方式的转变，使得开发者的角色从"逐行编写代码"向"定义意图、监督AI、优化结果"转变。在实际使用中，这种转变可以显著提升开发效率，尤其是在处理重复性代码、样板代码和跨文件重构等任务时。

二、安装与环境配置

2.1 系统要求与下载安装

Cursor支持macOS、Windows和Linux三大主流操作系统。在macOS上，可以通过Homebrew进行安装，也可以直接从官网下载dmg安装包。以下是使用Homebrew安装的命令：

# 使用Homebrew Cask安装Cursor
brew install --cask cursor

# 验证安装是否成功
cursor --version

安装完成后，首次启动Cursor会引导你完成初始配置。如果你之前使用的是VS Code，Cursor会自动检测并提示你导入VS Code的配置、插件和快捷键设置。这个过程是自动化的，只需要点击确认即可。导入完成后，你会发现Cursor的界面布局、快捷键、已安装的插件都与VS Code保持一致，迁移成本几乎为零。这也是Cursor能够快速吸引大量VS Code用户的重要原因之一。

2.2 AI模型配置与API Key管理

Cursor默认提供了内置的AI模型订阅服务（Cursor Pro），包括GPT-4、Claude 3.5 Sonnet、Claude 3.5 Haiku等主流模型的访问权限。如果你有自己的API Key，也可以在设置中配置自定义模型端点。以下是配置自定义API的步骤：

打开Cursor设置（Cmd+, 或 Ctrl+,），搜索"Models"，在Models配置页面中，你可以看到默认支持的模型列表。勾选或取消勾选你需要的模型。如果你需要使用自定义的OpenAI兼容端点（例如自建的vLLM推理服务），可以按照以下格式配置：

// .cursor/settings.json
{
  "cursor.general.modelChoice": "claude-3.5-sonnet",
  "cursor.general.enableAIReview": true,
  "cursor.completion.model": "cursor-small",
  "openai.apiBase": "https://your-vllm-endpoint.com/v1",
  "openai.apiKey": "your-api-key-here"
}

2.3 代码库索引配置

Cursor的代码索引功能是其AI能力的基石。索引完成后，AI可以理解整个项目的结构和语义。对于大型项目，索引可能需要一些时间，但这是一次性的成本。你可以通过以下方式优化索引配置：

// .cursor/config.json
{
  "indexing": {
    "enabled": true,
    "excludePatterns": [
      "node_modules/**",
      "dist/**",
      ".git/**",
      "*.lock",
      "package-lock.json"
    ],
    "maxFileSize": "500KB"
  }
}

三、Tab补全深度实战

3.1 Cursor Tab的核心机制

Cursor Tab（又称Cursor Completions）是Cursor最基础也是使用频率最高的AI功能。与传统的基于语法的自动补全不同，Cursor Tab不仅考虑当前光标位置的上下文，还会参考最近编辑过的文件、跨文件的类型定义、以及项目中的代码模式。这使得它能够在合适的场景下生成多行甚至整个函数的代码补全建议。当你按下Tab键时，Cursor会接受当前的补全建议。如果补全建议跨越了多行，Cursor会在行号区域用特殊标记显示即将插入的代码，你可以通过Tab确认或Esc取消。

以下是一个实际的TypeScript项目中的补全示例。假设我们有一个电商项目的用户服务模块，当我们开始编写一个新的订单处理函数时，Cursor会根据项目中已有的模式自动补全：

// src/services/orderService.ts
import { User } from '../models/User';
import { Product } from '../models/Product';
import { Database } from '../utils/database';

export class OrderService {
  private db: Database;

  constructor(db: Database) {
    this.db = db;
  }

  // 当你输入到 "async create" 时，Cursor Tab会自动补全整个函数
  async createOrder(userId: string, products: Product[]): Promise<Order> {
    const user = await this.db.users.findById(userId);
    if (!user) {
      throw new Error(`User ${userId} not found`);
    }

    const totalPrice = products.reduce((sum, p) => sum + p.price, 0);
    const order: Order = {
      id: crypto.randomUUID(),
      userId: user.id,
      items: products.map(p => ({ productId: p.id, price: p.price })),
      totalPrice,
      status: 'pending',
      createdAt: new Date(),
    };

    await this.db.orders.insert(order);
    return order;
  }
}

3.2 多行跳转补全

Cursor Tab的一个强大特性是多行跳转补全。当你在某个位置接受补全后，如果Cursor认为在文件的其他位置（例如几行下方）也有需要同步修改的代码，它会继续提供补全建议。你只需要继续按Tab就可以逐个接受。这在修改函数签名后同步更新调用处、添加新字段后同步更新构造函数等场景中特别有用。

// 假设你在User接口中添加了一个新字段 email
interface User {
  id: string;
  name: string;
  email: string;  // 刚添加的字段
  // Cursor会在这里提示你下一个需要修改的位置
}

// 在User类的构造函数中，Cursor会自动补全 email 的赋值
class UserImpl implements User {
  id: string;
  name: string;
  email: string;  // Cursor Tab自动补全

  constructor(data: Partial<User>) {
    this.id = data.id ?? crypto.randomUUID();
    this.name = data.name ?? '';
    this.email = data.email ?? '';  // Cursor Tab自动补全
  }
}

四、Cmd+K内联编辑实战

4.1 基本用法

Cmd+K（Windows上为Ctrl+K）是Cursor的内联编辑快捷键。选中一段代码后按下Cmd+K，会弹出一个输入框，你可以用自然语言描述你想要的修改。例如，你可以输入"将这个函数改为异步并添加错误处理"、“添加参数验证”、"将这个回调风格改为Promise风格"等。Cursor会理解你的意图并直接在编辑器中生成修改后的代码，你可以通过Diff视图查看变更并决定接受或拒绝。

# 原始代码 - 同步文件读取
def read_config(path):
    with open(path, 'r') as f:
        return f.read()

# 选中上方代码后按Cmd+K，输入"改为异步读取并添加类型注解和错误处理"
# Cursor生成以下代码：

import aiofiles
from typing import Optional
import logging

logger = logging.getLogger(__name__)

async def read_config(path: str) -> Optional[str]:
    """异步读取配置文件内容，失败时返回None并记录日志。"""
    try:
        async with aiofiles.open(path, 'r') as f:
            return await f.read()
    except FileNotFoundError:
        logger.error(f"Config file not found: {path}")
        return None
    except Exception as e:
        logger.error(f"Failed to read config {path}: {e}")
        return None

4.2 复杂重构示例

Cmd+K也可以处理更复杂的重构任务。以下是一个将JavaScript回调风格代码重构为现代async/await风格的示例：

// 原始代码 - 回调地狱
function fetchUserData(userId, callback) {
  database.connect(function(err, db) {
    if (err) return callback(err);
    db.query('SELECT * FROM users WHERE id = ?', [userId], function(err, rows) {
      if (err) return callback(err);
      if (rows.length === 0) return callback(new Error('User not found'));
      const user = rows[0];
      db.query('SELECT * FROM orders WHERE user_id = ?', [userId], function(err, orders) {
        if (err) return callback(err);
        user.orders = orders;
        cache.set(userId, user, function(err) {
          if (err) console.error('Cache error:', err);
          callback(null, user);
        });
      });
    });
  });
}

// 选中后Cmd+K输入"重构为async/await并添加完善的错误处理"
async function fetchUserData(userId) {
  const db = await database.connect();
  try {
    const [userRows] = await db.query('SELECT * FROM users WHERE id = ?', [userId]);
    if (!userRows || userRows.length === 0) {
      throw new Error(`User ${userId} not found`);
    }
    const user = userRows[0];
    const [orders] = await db.query('SELECT * FROM orders WHERE user_id = ?', [userId]);
    user.orders = orders || [];
    try {
      await cache.set(userId, user);
    } catch (cacheErr) {
      console.error('Cache error:', cacheErr.message);
    }
    return user;
  } finally {
    if (db && db.release) db.release();
  }
}

五、Chat对话与@上下文引用

5.1 @引用机制详解

Cursor的Chat功能（Cmd+L）支持通过@语法引用代码库中的文件、符号、文档或外部资源。这是Cursor区别于其他AI编程工具的核心差异化能力之一。通过精确的@引用，你可以为AI提供高度相关的上下文，避免其在不相关的代码中"幻觉"。

常用的@引用类型包括：

• @file：引用特定文件，例如@file src/services/auth.ts
• @symbol：引用函数、类或变量定义，例如@symbol OrderService
• @folder：引用整个目录
• @web：搜索网络资源
• @docs：引用第三方库的官方文档

以下是一个使用@引用进行复杂代码分析的示例对话：

用户输入：
@file src/services/orderService.ts @file src/models/Order.ts @symbol PaymentGateway

请分析当前订单服务中的支付流程，找出潜在的竞态条件问题，并给出修复方案。

Cursor分析结果：
经过分析orderService.ts和Order.ts的代码，我发现以下竞态条件问题：

1. 问题定位：在createOrder方法中，先插入订单再调用PaymentGateway.charge()，
   如果支付失败但订单已入库，会导致数据不一致。
2. 修复方案：引入事务和幂等性检查。

基于上述分析，Cursor会生成修复后的代码：

async createOrder(userId: string, products: Product[]): Promise<Order> {
  const session = await this.db.startSession();
  try {
    session.startTransaction();

    const user = await this.db.users.findById(userId).session(session);
    if (!user) throw new Error(`User ${userId} not found`);

    const totalPrice = products.reduce((sum, p) => sum + p.price, 0);
    const orderId = crypto.randomUUID();

    // 先创建支付，成功后再创建订单
    const paymentResult = await this.paymentGateway.charge({
      idempotencyKey: orderId,
      amount: totalPrice,
      currency: 'CNY',
      userId: user.id,
    });

    if (!paymentResult.success) {
      throw new Error(`Payment failed: ${paymentResult.message}`);
    }

    const order: Order = {
      id: orderId,
      userId: user.id,
      items: products.map(p => ({ productId: p.id, price: p.price })),
      totalPrice,
      paymentId: paymentResult.paymentId,
      status: 'paid',
      createdAt: new Date(),
    };

    await this.db.orders.insert(order, { session });
    await session.commitTransaction();
    return order;
  } catch (error) {
    await session.abortTransaction();
    throw error;
  } finally {
    session.endSession();
  }
}

5.2 @docs引用第三方文档

@docs功能允许Cursor直接参考第三方库的官方文档来生成代码。这在面对不熟悉的API或新版本库时特别有用。例如：

用户输入：
@docs prisma 请用Prisma ORM实现一个博客系统的数据模型，包含User、Post、Comment三个表，
支持一对多关系，并生成对应的CRUD服务代码。

Cursor会参考Prisma官方文档生成以下代码：

// prisma/schema.prisma
generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model User {
  id        String   @id @default(cuid())
  email     String   @unique
  name      String
  posts     Post[]
  comments  Comment[]
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

model Post {
  id        String    @id @default(cuid())
  title     String
  content   String
  published Boolean   @default(false)
  author    User      @relation(fields: [authorId], references: [id])
  authorId  String
  comments  Comment[]
  createdAt DateTime  @default(now())
  updatedAt DateTime  @updatedAt
}

model Comment {
  id        String   @id @default(cuid())
  content   String
  post      Post     @relation(fields: [postId], references: [id])
  postId    String
  author    User     @relation(fields: [authorId], references: [id])
  authorId  String
  createdAt DateTime @default(now())
}

// src/services/blogService.ts
import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();

export class BlogService {
  async createUser(email: string, name: string) {
    return prisma.user.create({ data: { email, name } });
  }

  async createPost(authorId: string, title: string, content: string) {
    return prisma.post.create({
      data: { title, content, authorId, published: false },
      include: { author: true },
    });
  }

  async publishPost(postId: string) {
    return prisma.post.update({
      where: { id: postId },
      data: { published: true },
    });
  }

  async getPostsWithComments(postId?: string) {
    return prisma.post.findMany({
      where: postId ? { id: postId } : { published: true },
      include: {
        author: true,
        comments: { include: { author: true }, orderBy: { createdAt: 'desc' } },
      },
      orderBy: { createdAt: 'desc' },
    });
  }

  async addComment(postId: string, authorId: string, content: string) {
    return prisma.comment.create({
      data: { postId, authorId, content },
      include: { author: true },
    });
  }

  async deletePost(postId: string) {
    await prisma.comment.deleteMany({ where: { postId } });
    return prisma.post.delete({ where: { id: postId } });
  }
}

六、Composer多文件编辑

6.1 Composer核心概念

Composer是Cursor中最强大的功能之一，它允许AI同时在多个文件中进行编辑。传统的AI编程工具通常只能一次修改一个文件，而Composer可以理解跨文件的依赖关系，一次性创建或修改多个相关文件。这对于实现新功能、大规模重构或搭建项目脚手架等任务极为高效。Composer的触发方式是Cmd+I（Windows上为Ctrl+I），在弹出的输入框中描述你的需求，Composer会分析代码库并生成涉及多个文件的修改方案。你可以通过Diff视图逐一审阅每个文件的变更，选择接受或拒绝。

6.2 实战：使用Composer实现完整功能模块

以下是一个使用Composer一次性创建完整用户认证模块的示例。我们在Composer输入框中输入：“创建一个完整的JWT认证模块，包含用户注册、登录、令牌刷新、密码重置功能，使用TypeScript和Express。”

Cursor Composer会同时创建以下文件：

// src/auth/types.ts
export interface AuthConfig {
  jwtSecret: string;
  jwtExpiresIn: string;
  refreshExpiresIn: string;
  saltRounds: number;
}

export interface RegisterDTO {
  email: string;
  password: string;
  name: string;
}

export interface LoginDTO {
  email: string;
  password: string;
}

export interface AuthResponse {
  accessToken: string;
  refreshToken: string;
  user: UserInfo;
}

export interface UserInfo {
  id: string;
  email: string;
  name: string;
  role: string;
}

export interface JwtPayload {
  sub: string;
  email: string;
  role: string;
  iat: number;
  exp: number;
}

// src/auth/jwtService.ts
import jwt from 'jsonwebtoken';
import crypto from 'crypto';
import { AuthConfig, JwtPayload, UserInfo } from './types';

export class JwtService {
  constructor(private config: AuthConfig) {}

  generateAccessToken(user: UserInfo): string {
    const payload: Omit<JwtPayload, 'iat' | 'exp'> = {
      sub: user.id,
      email: user.email,
      role: user.role,
    };
    return jwt.sign(payload, this.config.jwtSecret, {
      expiresIn: this.config.jwtExpiresIn as any,
    });
  }

  generateRefreshToken(userId: string): string {
    return crypto.randomBytes(40).toString('hex');
  }

  verifyAccessToken(token: string): JwtPayload {
    return jwt.verify(token, this.config.jwtSecret) as JwtPayload;
  }

  decodeExpiredToken(token: string): JwtPayload | null {
    try {
      return jwt.decode(token) as JwtPayload;
    } catch {
      return null;
    }
  }
}

// src/auth/authService.ts
import bcrypt from 'bcryptjs';
import { JwtService } from './jwtService';
import { UserRepository } from './userRepository';
import { RegisterDTO, LoginDTO, AuthResponse, UserInfo } from './types';

export class AuthService {
  private jwtService: JwtService;
  private userRepo: UserRepository;

  constructor(jwtService: JwtService, userRepo: UserRepository) {
    this.jwtService = jwtService;
    this.userRepo = userRepo;
  }

  async register(dto: RegisterDTO): Promise<AuthResponse> {
    const existing = await this.userRepo.findByEmail(dto.email);
    if (existing) {
      throw new Error('Email already registered');
    }

    const passwordHash = await bcrypt.hash(dto.password, 10);
    const user = await this.userRepo.create({
      email: dto.email,
      passwordHash,
      name: dto.name,
      role: 'user',
    });

    return this.generateAuthResponse(user);
  }

  async login(dto: LoginDTO): Promise<AuthResponse> {
    const user = await this.userRepo.findByEmail(dto.email);
    if (!user) {
      throw new Error('Invalid credentials');
    }

    const valid = await bcrypt.compare(dto.password, user.passwordHash);
    if (!valid) {
      throw new Error('Invalid credentials');
    }

    return this.generateAuthResponse(user);
  }

  async refreshToken(refreshToken: string): Promise<AuthResponse> {
    const stored = await this.userRepo.findRefreshToken(refreshToken);
    if (!stored || stored.expiresAt < new Date()) {
      throw new Error('Invalid or expired refresh token');
    }

    const user = await this.userRepo.findById(stored.userId);
    if (!user) {
      throw new Error('User not found');
    }

    await this.userRepo.deleteRefreshToken(refreshToken);
    return this.generateAuthResponse(user);
  }

  async requestPasswordReset(email: string): Promise<string> {
    const user = await this.userRepo.findByEmail(email);
    if (!user) return '';

    const resetToken = crypto.randomBytes(32).toString('hex');
    const expiresAt = new Date(Date.now() + 3600000);
    await this.userRepo.saveResetToken(user.id, resetToken, expiresAt);
    return resetToken;
  }

  async resetPassword(token: string, newPassword: string): Promise<void> {
    const userId = await this.userRepo.findResetToken(token);
    if (!userId) {
      throw new Error('Invalid or expired reset token');
    }

    const passwordHash = await bcrypt.hash(newPassword, 10);
    await this.userRepo.updatePassword(userId, passwordHash);
    await this.userRepo.deleteResetToken(token);
  }

  private async generateAuthResponse(user: any): Promise<AuthResponse> {
    const userInfo: UserInfo = {
      id: user.id,
      email: user.email,
      name: user.name,
      role: user.role,
    };

    const accessToken = this.jwtService.generateAccessToken(userInfo);
    const refreshToken = this.jwtService.generateRefreshToken(user.id);
    await this.userRepo.saveRefreshToken(user.id, refreshToken, new Date(Date.now() + 7 * 86400000));

    return { accessToken, refreshToken, user: userInfo };
  }
}

// src/auth/authController.ts
import { Request, Response } from 'express';
import { AuthService } from './authService';
import { RegisterDTO, LoginDTO } from './types';

export class AuthController {
  constructor(private authService: AuthService) {}

  register = async (req: Request, res: Response): Promise<void> => {
    try {
      const dto: RegisterDTO = req.body;
      if (!dto.email || !dto.password || !dto.name) {
        res.status(400).json({ error: 'Missing required fields' });
        return;
      }
      const result = await this.authService.register(dto);
      res.status(201).json(result);
    } catch (error: any) {
      if (error.message.includes('already registered')) {
        res.status(409).json({ error: error.message });
      } else {
        res.status(500).json({ error: 'Registration failed' });
      }
    }
  };

  login = async (req: Request, res: Response): Promise<void> => {
    try {
      const dto: LoginDTO = req.body;
      const result = await this.authService.login(dto);
      res.json(result);
    } catch (error: any) {
      res.status(401).json({ error: 'Invalid credentials' });
    }
  };

  refresh = async (req: Request, res: Response): Promise<void> => {
    try {
      const { refreshToken } = req.body;
      if (!refreshToken) {
        res.status(400).json({ error: 'Refresh token required' });
        return;
      }
      const result = await this.authService.refreshToken(refreshToken);
      res.json(result);
    } catch (error: any) {
      res.status(401).json({ error: 'Invalid refresh token' });
    }
  };

  requestReset = async (req: Request, res: Response): Promise<void> => {
    const { email } = req.body;
    await this.authService.requestPasswordReset(email);
    res.json({ message: 'If the email exists, a reset link has been sent' });
  };

  resetPassword = async (req: Request, res: Response): Promise<void> => {
    try {
      const { token, newPassword } = req.body;
      await this.authService.resetPassword(token, newPassword);
      res.json({ message: 'Password updated successfully' });
    } catch (error: any) {
      res.status(400).json({ error: error.message });
    }
  };
}

// src/auth/authMiddleware.ts
import { Request, Response, NextFunction } from 'express';
import { JwtService } from './jwtService';
import { JwtPayload } from './types';

export function createAuthMiddleware(jwtService: JwtService) {
  return (req: Request, res: Response, next: NextFunction): void => {
    const authHeader = req.headers.authorization;
    if (!authHeader || !authHeader.startsWith('Bearer ')) {
      res.status(401).json({ error: 'Authorization header missing' });
      return;
    }

    const token = authHeader.substring(7);
    try {
      const payload = jwtService.verifyAccessToken(token);
      (req as any).user = payload;
      next();
    } catch (error) {
      res.status(401).json({ error: 'Invalid or expired token' });
    }
  };
}

export function requireRole(role: string) {
  return (req: Request, res: Response, next: NextFunction): void => {
    const user = (req as any).user as JwtPayload;
    if (!user || user.role !== role) {
      res.status(403).json({ error: 'Insufficient permissions' });
      return;
    }
    next();
  };
}

// src/auth/userRepository.ts
import { Database } from '../utils/database';

export class UserRepository {
  constructor(private db: Database) {}

  async create(data: { email: string; passwordHash: string; name: string; role: string }) {
    const id = crypto.randomUUID();
    await this.db.query(
      'INSERT INTO users (id, email, password_hash, name, role) VALUES ($1, $2, $3, $4, $5)',
      [id, data.email, data.passwordHash, data.name, data.role]
    );
    return this.findById(id);
  }

  async findById(id: string) {
    const rows = await this.db.query('SELECT * FROM users WHERE id = $1', [id]);
    return rows[0] ?? null;
  }

  async findByEmail(email: string) {
    const rows = await this.db.query('SELECT * FROM users WHERE email = $1', [email]);
    return rows[0] ?? null;
  }

  async saveRefreshToken(userId: string, token: string, expiresAt: Date) {
    await this.db.query(
      'INSERT INTO refresh_tokens (user_id, token, expires_at) VALUES ($1, $2, $3)',
      [userId, token, expiresAt]
    );
  }

  async findRefreshToken(token: string) {
    const rows = await this.db.query('SELECT * FROM refresh_tokens WHERE token = $1', [token]);
    return rows[0] ?? null;
  }

  async deleteRefreshToken(token: string) {
    await this.db.query('DELETE FROM refresh_tokens WHERE token = $1', [token]);
  }

  async saveResetToken(userId: string, token: string, expiresAt: Date) {
    await this.db.query(
      'INSERT INTO password_reset_tokens (user_id, token, expires_at) VALUES ($1, $2, $3)',
      [userId, token, expiresAt]
    );
  }

  async findResetToken(token: string) {
    const rows = await this.db.query('SELECT user_id FROM password_reset_tokens WHERE token = $1 AND expires_at > NOW()', [token]);
    return rows[0]?.user_id ?? null;
  }

  async deleteResetToken(token: string) {
    await this.db.query('DELETE FROM password_reset_tokens WHERE token = $1', [token]);
  }

  async updatePassword(userId: string, passwordHash: string) {
    await this.db.query('UPDATE users SET password_hash = $1 WHERE id = $2', [passwordHash, userId]);
  }
}

七、Agent模式与自主任务执行

7.1 Agent模式概述

Cursor的Agent模式（在Composer中激活）是最高级别的AI自主能力。在Agent模式下，AI不仅能编辑代码，还能自主执行终端命令、运行测试、根据测试结果迭代修复代码。这使得AI可以完成完整的开发循环：理解需求→编写代码→运行测试→修复错误→验证通过。Agent模式特别适合于实现明确的小型功能、修复已知bug、以及编写测试用例等任务。

7.2 Agent模式实战：实现并测试一个API端点

在Composer中输入以下指令并启用Agent模式：“为Express应用创建一个产品管理API，包含CRUD操作、输入验证、分页查询和错误处理，并编写完整的Jest测试。”

Cursor Agent会自主创建以下文件并运行测试：

// src/products/productRoutes.ts
import { Router } from 'express';
import { body, query, validationResult } from 'express-validator';

interface Product {
  id: string;
  name: string;
  description: string;
  price: number;
  stock: number;
  category: string;
  createdAt: Date;
  updatedAt: Date;
}

class ProductStore {
  private products = new Map<string, Product>();

  create(data: Omit<Product, 'id' | 'createdAt' | 'updatedAt'>): Product {
    const id = crypto.randomUUID();
    const now = new Date();
    const product: Product = { ...data, id, createdAt: now, updatedAt: now };
    this.products.set(id, product);
    return product;
  }

  findById(id: string): Product | undefined {
    return this.products.get(id);
  }

  findAll(opts: { page: number; limit: number; category?: string }): { items: Product[]; total: number } {
    let items = Array.from(this.products.values());
    if (opts.category) {
      items = items.filter(p => p.category === opts.category);
    }
    const total = items.length;
    const start = (opts.page - 1) * opts.limit;
    items = items.slice(start, start + opts.limit);
    return { items, total };
  }

  update(id: string, data: Partial<Omit<Product, 'id' | 'createdAt'>>): Product | null {
    const existing = this.products.get(id);
    if (!existing) return null;
    const updated = { ...existing, ...data, updatedAt: new Date() };
    this.products.set(id, updated);
    return updated;
  }

  delete(id: string): boolean {
    return this.products.delete(id);
  }
}

const store = new ProductStore();
const router = Router();

const validateProduct = [
  body('name').trim().notEmpty().withMessage('Name is required'),
  body('description').trim().notEmpty().withMessage('Description is required'),
  body('price').isFloat({ min: 0 }).withMessage('Price must be non-negative'),
  body('stock').isInt({ min: 0 }).withMessage('Stock must be non-negative integer'),
  body('category').trim().notEmpty().withMessage('Category is required'),
];

router.post('/', validateProduct, (req, res) => {
  const errors = validationResult(req);
  if (!errors.isEmpty()) {
    return res.status(400).json({ errors: errors.array() });
  }
  const product = store.create(req.body);
  res.status(201).json(product);
});

router.get('/', (req, res) => {
  const page = parseInt(req.query.page as string) || 1;
  const limit = Math.min(parseInt(req.query.limit as string) || 20, 100);
  const category = req.query.category as string | undefined;
  const result = store.findAll({ page, limit, category });
  res.json({
    items: result.items,
    total: result.total,
    page,
    limit,
    totalPages: Math.ceil(result.total / limit),
  });
});

router.get('/:id', (req, res) => {
  const product = store.findById(req.params.id);
  if (!product) return res.status(404).json({ error: 'Product not found' });
  res.json(product);
});

router.put('/:id', validateProduct, (req, res) => {
  const errors = validationResult(req);
  if (!errors.isEmpty()) {
    return res.status(400).json({ errors: errors.array() });
  }
  const product = store.update(req.params.id, req.body);
  if (!product) return res.status(404).json({ error: 'Product not found' });
  res.json(product);
});

router.delete('/:id', (req, res) => {
  const deleted = store.delete(req.params.id);
  if (!deleted) return res.status(404).json({ error: 'Product not found' });
  res.status(204).send();
});

export { router as productRoutes, ProductStore };

// src/products/productRoutes.test.ts
import express from 'express';
import request from 'supertest';
import { productRoutes, ProductStore } from './productRoutes';

const app = express();
app.use(express.json());
app.use('/products', productRoutes);

describe('Product API', () => {
  describe('POST /products', () => {
    it('should create a product with valid data', async () => {
      const res = await request(app)
        .post('/products')
        .send({
          name: 'Laptop',
          description: 'High-performance laptop',
          price: 999.99,
          stock: 50,
          category: 'Electronics',
        });
      expect(res.status).toBe(201);
      expect(res.body).toHaveProperty('id');
      expect(res.body.name).toBe('Laptop');
      expect(res.body.price).toBe(999.99);
    });

    it('should reject invalid price', async () => {
      const res = await request(app)
        .post('/products')
        .send({ name: 'Test', description: 'Test', price: -1, stock: 1, category: 'Test' });
      expect(res.status).toBe(400);
      expect(res.body.errors).toBeDefined();
    });

    it('should reject missing name', async () => {
      const res = await request(app)
        .post('/products')
        .send({ description: 'Test', price: 10, stock: 1, category: 'Test' });
      expect(res.status).toBe(400);
    });
  });

  describe('GET /products', () => {
    it('should return paginated products', async () => {
      for (let i = 0; i < 25; i++) {
        await request(app).post('/products').send({
          name: `Product ${i}`,
          description: 'Test product',
          price: 10,
          stock: 100,
          category: 'Test',
        });
      }
      const res = await request(app).get('/products?page=1&limit=10');
      expect(res.status).toBe(200);
      expect(res.body.items).toHaveLength(10);
      expect(res.body.total).toBeGreaterThanOrEqual(25);
      expect(res.body.totalPages).toBeGreaterThanOrEqual(3);
    });

    it('should filter by category', async () => {
      await request(app).post('/products').send({
        name: 'Phone', description: 'Smartphone', price: 500, stock: 30, category: 'Mobile',
      });
      const res = await request(app).get('/products?category=Mobile');
      expect(res.status).toBe(200);
      expect(res.body.items.every((p: any) => p.category === 'Mobile')).toBe(true);
    });
  });

  describe('GET /products/:id', () => {
    it('should return 404 for non-existent id', async () => {
      const res = await request(app).get('/products/non-existent-id');
      expect(res.status).toBe(404);
    });
  });

  describe('PUT /products/:id', () => {
    it('should update an existing product', async () => {
      const create = await request(app).post('/products').send({
        name: 'Original', description: 'Original', price: 10, stock: 5, category: 'Test',
      });
      const res = await request(app)
        .put(`/products/${create.body.id}`)
        .send({ name: 'Updated', description: 'Updated', price: 20, stock: 10, category: 'Test' });
      expect(res.status).toBe(200);
      expect(res.body.name).toBe('Updated');
      expect(res.body.price).toBe(20);
    });
  });

  describe('DELETE /products/:id', () => {
    it('should delete a product', async () => {
      const create = await request(app).post('/products').send({
        name: 'ToDelete', description: 'Test', price: 10, stock: 1, category: 'Test',
      });
      const del = await request(app).delete(`/products/${create.body.id}`);
      expect(del.status).toBe(204);
      const get = await request(app).get(`/products/${create.body.id}`);
      expect(get.status).toBe(404);
    });
  });
});

Agent模式在生成这些文件后，会自动运行npx jest src/products/productRoutes.test.ts，如果测试失败会自动分析错误并修复，直到所有测试通过。

八、自定义规则与.cursorrules配置

8.1 项目级规则文件

Cursor支持通过.cursorrules文件为AI提供项目特定的编码规范和上下文。这个文件放在项目根目录下，AI在进行代码生成和编辑时会自动参考这些规则。一个精心编写的.cursorrules文件可以显著提高AI生成代码的质量和一致性。

# .cursorrules

## Project Context
This is a TypeScript monorepo using pnpm workspaces. The main packages are:
- `apps/web`: Next.js 14 frontend application
- `apps/api`: Express.js backend API
- `packages/shared`: Shared types and utilities
- `packages/ui`: Shared component library

## Code Style Rules
- Always use TypeScript with strict mode enabled
- Use functional components with hooks for React, no class components
- Prefer named exports over default exports
- Use `import type` for type-only imports
- Error handling: always use try-catch with typed errors, never swallow errors
- Use `zod` for runtime validation at API boundaries
- Database queries must use the repository pattern
- All public functions must have JSDoc comments
- Use `const` by default, `let` only when reassignment is needed, never `var`

## Naming Conventions
- Files: kebab-case (e.g., `user-service.ts`)
- Types/Interfaces: PascalCase with descriptive suffix (UserService, OrderDTO)
- Functions: camelCase (getUserById, createOrder)
- Constants: UPPER_SNAKE_CASE (MAX_RETRY_COUNT)
- Environment variables: UPPER_SNAKE_CASE prefixed with APP_

## Testing Rules
- Use Jest for backend, Vitest for frontend
- Test files should be co-located with source: `user-service.ts` → `user-service.test.ts`
- Each public function must have at least one test
- Use describe/it blocks, not test()
- Mock external dependencies at the module level

8.2 规则生效验证

配置了上述规则后，当你让Cursor生成代码时，它会自动遵循这些规范。例如，如果你让Cursor"创建一个用户服务"，它会自动使用kebab-case文件名、命名导出、JSDoc注释、zod验证等。以下是根据上述规则生成的一个符合规范的示例文件：

// packages/shared/src/services/user-service.ts
import { z } from 'zod';
import type { User, UserCreateDTO, UserUpdateDTO } from '../types/user';
import { UserRepository } from '../repositories/user-repository';

const userCreateSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1).max(100),
  role: z.enum(['admin', 'user', 'guest']).default('user'),
});

const userUpdateSchema = z.object({
  email: z.string().email().optional(),
  name: z.string().min(1).max(100).optional(),
  role: z.enum(['admin', 'user', 'guest']).optional(),
});

/**
 * Service for managing user operations including CRUD and business logic.
 */
export class UserService {
  constructor(private readonly repo: UserRepository) {}

  /**
   * Creates a new user after validation.
   * @param dto - User creation data
   * @returns The created user
   * @throws {Error} If email already exists or validation fails
   */
  async createUser(dto: UserCreateDTO): Promise<User> {
    const validated = userCreateSchema.parse(dto);
    const existing = await this.repo.findByEmail(validated.email);
    if (existing) {
      throw new Error(`User with email ${validated.email} already exists`);
    }
    return this.repo.create(validated);
  }

  /**
   * Updates an existing user by ID.
   * @param id - User ID
   * @param dto - Update data
   * @returns The updated user or null if not found
   */
  async updateUser(id: string, dto: UserUpdateDTO): Promise<User | null> {
    const validated = userUpdateSchema.parse(dto);
    return this.repo.update(id, validated);
  }

  /**
   * Retrieves a user by ID.
   * @param id - User ID
   * @returns The user or null if not found
   */
  async getUserById(id: string): Promise<User | null> {
    return this.repo.findById(id);
  }

  /**
   * Deletes a user by ID.
   * @param id - User ID
   * @returns true if deleted, false if not found
   */
  async deleteUser(id: string): Promise<boolean> {
    return this.repo.delete(id);
  }
}

九、Cursor与Git工作流集成

9.1 AI辅助代码审查

Cursor的Chat功能可以用于代码审查。当你有一个Git diff时，可以在Chat中输入"@git diff 请审查这个PR的变更，检查是否有安全漏洞、性能问题或代码风格问题。"Cursor会分析diff并给出审查意见。

9.2 智能Commit消息生成

Cursor可以根据暂存区的变更自动生成规范的Commit消息。在终端中使用Cursor的CLI工具或者在Chat中输入"@git staged 请生成符合Conventional Commits规范的commit消息。"以下是自动生成的commit消息示例：

# Cursor生成的commit消息
git commit -m "feat(auth): add JWT refresh token rotation and password reset

- Implement refresh token rotation on each refresh call
- Add password reset flow with expiry tokens
- Add input validation using zod schemas
- Include integration tests for all auth endpoints

Closes #142"

十、Cursor性能优化与最佳实践

10.1 大型项目索引优化

对于大型项目，索引可能会消耗较多资源。以下是一些优化建议。首先，合理配置排除模式，将不需要索引的目录排除。其次，利用Cursor的"Reindex"功能在大量文件变更后手动触发重新索引。最后，对于monorepo项目，确保工作区配置正确，避免索引不相关的子项目。

// .cursor/indexing.json
{
  "exclude": [
    "**/node_modules/**",
    "**/dist/**",
    "**/build/**",
    "**/.next/**",
    "**/coverage/**",
    "**/*.min.js",
    "**/*.map",
    "**/vendor/**"
  ],
  "include": [
    "src/**",
    "packages/*/src/**"
  ]
}

10.2 上下文管理策略

Cursor在每次AI交互时都会收集上下文。合理的上下文管理可以提升AI响应质量和速度。建议在不需要全项目上下文的场景下，使用@file精确引用而非依赖自动上下文收集。在进行跨模块修改时，先在Chat中用@file引用相关文件让AI"预读"一遍，再使用Composer进行修改。避免同时打开过多文件，因为打开的文件都会被纳入上下文。定期清理Cursor的缓存（设置→General→Clear Cache）以保持最佳性能。

十一、Cursor与其他AI工具对比

11.1 对比GitHub Copilot

GitHub Copilot主要聚焦于单文件内的代码补全和有限的Chat功能。Cursor在以下方面具有优势：多文件编辑能力（Composer）、Agent自主执行能力、@上下文引用机制、以及更深度的代码库理解。Copilot的优势在于与GitHub生态的深度集成和更广泛的IDE支持。但在纯编码效率和复杂任务处理能力上，Cursor明显领先。

11.2 对比Windsurf

Windsurf（前Codeium）也是一款AI原生编辑器，其Cascade功能类似于Cursor的Composer。两者在核心功能上较为接近，但Cursor在模型选择灵活性（支持更多模型）、社区生态（更丰富的规则模板和教程）、以及Agent模式的成熟度上略胜一筹。

11.3 选择建议

如果你主要进行Web全栈开发，Cursor是当前综合体验最好的选择。如果你需要深度集成GitHub生态，Copilot仍有价值。如果预算有限，Windsurf的免费额度更多。实际上，许多开发者会同时使用多个工具，在不同场景下选择最合适的。

十二、Cursor在团队协作中的应用

12.1 共享.cursorrules

在团队中，将.cursorrules文件纳入版本控制是提升AI生成代码一致性的最佳实践。这样所有团队成员在使用Cursor时都会遵循相同的编码规范。建议将.cursorrules与ESLint/Prettier配置保持一致，形成多层次的代码质量保障。

12.2 Cursor与CI/CD集成

虽然Cursor本身是一个编辑器，但其AI能力可以辅助CI/CD流程。例如，可以在PR审查阶段使用Cursor的CLI工具自动生成代码审查意见。以下是一个GitHub Actions集成示例：

# .github/workflows/ai-review.yml
name: AI Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get diff
        id: diff
        run: |
          git diff origin/${{ github.base_ref }}...HEAD > pr_diff.txt
          echo "diff<<EOF" >> $GITHUB_OUTPUT
          cat pr_diff.txt >> $GITHUB_OUTPUT
          echo "EOF" >> $GITHUB_OUTPUT

      - name: AI Review
        env:
          CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }}
        run: |
          cursor-cli review --diff pr_diff.txt --output review.md

      - name: Post review comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const review = fs.readFileSync('review.md', 'utf8');
            github.rest.issues.createComment({
              ...context.repo,
              issue_number: context.issue.number,
              body: `## AI Code Review\n\n${review}`,
            });

总结

Cursor作为2026年最主流的AI原生代码编辑器，其核心价值在于将AI能力深度融入编码的每一个环节。从Tab补全的日常编码辅助，到Cmd+K的内联编辑，再到Composer的多文件大规模重构，最后到Agent模式的自主任务执行，Cursor构建了一个从轻量到重量级的完整AI开发工具链。本文通过大量实际代码示例，详细展示了Cursor的各项核心功能及其在实际项目中的应用方式。关键要点包括：合理配置索引和排除规则以优化大型项目性能；善用@引用机制为AI提供精确上下文；利用.cursorrules确保AI生成代码符合项目规范；在团队中共享配置以保持一致性；善用Agent模式处理测试驱动的开发任务。掌握这些能力后，Cursor不仅是一个代码编辑器，更是一个能够显著提升开发效率的AI编程伙伴。随着AI模型能力的持续提升和Cursor功能的不断迭代，AI原生开发的工作方式将成为行业标配，而Cursor的使用经验将成为每一位开发者的重要竞争力。