Cursor Agent 模式：AI 编程助手的进化

需求理解 → 代码库探索 → 方案规划 → 代码实现 → 测试验证 → 迭代修复

// Cursor 内部的代码库索引结构（简化）
{
  "project": "my-web-app",
  "files_indexed": 847,
  "index_config": {
    "embedding_model": "cursor-code-embed-v2",
    "chunk_strategy": "ast-aware",  // 基于语法树的智能分块
    "chunk_size": "adaptive",       // 函数/类边界对齐
    "index_types": ["semantic", "symbol", "dependency"]
  },
  "symbols": {
    "classes": 156,
    "functions": 1243,
    "components": 89,
    "api_endpoints": 34
  }
}

# Cursor Agent 内部规划流程（概念模型）
class AgentPlanner:
    def plan(self, request: str, codebase: Codebase):
        # Step 1: 理解需求
        intent = self.understand_intent(request)
        
        # Step 2: 定位相关代码
        relevant_files = codebase.semantic_search(intent.keywords)
        dependencies = codebase.analyze_dependencies(relevant_files)
        
        # Step 3: 生成实现计划
        plan = {
            "files_to_create": [],
            "files_to_modify": [],
            "files_to_read": [],
            "tests_to_write": [],
            "commands_to_run": [],
        }
        
        # Step 4: 验证计划可行性
        validated_plan = self.validate(plan, codebase)
        
        return validated_plan

// Cursor Agent 实际执行示例
// 用户请求："给用户管理模块添加批量导入功能"

// Agent 会：
// 1. 读取现有用户管理代码
// 2. 创建 CSV 解析工具
// 3. 修改路由添加导入端点
// 4. 编写测试
// 5. 运行测试验证

// === Agent 创建的新文件 ===
// src/utils/csv-parser.ts
import { parse } from 'csv-parse';
import { Readable } from 'stream';

export interface UserImportRow {
  name: string;
  email: string;
  department: string;
  role: string;
}

export async function parseUserCSV(buffer: Buffer): Promise<UserImportRow[]> {
  const records: UserImportRow[] = [];
  const parser = parse({
    columns: true,
    skip_empty_lines: true,
    trim: true,
    delimiter: ',',
  });

  Readable.from(buffer).pipe(parser);

  for await (const record of parser) {
    // 验证必填字段
    if (!record.email || !record.name) {
      throw new Error(`缺少必填字段: 行 ${records.length + 2}`);
    }
    records.push({
      name: record.name,
      email: record.email.toLowerCase(),
      department: record.department || '未分配',
      role: record.role || 'member',
    });
  }

  return records;
}

// === Agent 修改的路由文件 ===
// src/routes/users.ts (修改部分)
router.post('/users/import', 
  upload.single('file'),
  requireRole('admin'),
  async (req, res) => {
    try {
      const users = await parseUserCSV(req.file.buffer);
      const result = await User.bulkCreate(users, {
        ignoreDuplicates: true,
        validate: true,
      });
      
      res.json({
        imported: result.length,
        total: users.length,
        skipped: users.length - result.length,
      });
    } catch (error) {
      res.status(400).json({ error: error.message });
    }
  }
);

# .cursorrules
project_type: "react-typescript-frontend"

conventions:
  styling: "tailwind"
  state_management: "zustand"
  testing: "vitest"
  api_client: "axios"
  
agent_config:
  auto_run_tests: true
  test_command: "pnpm test"
  auto_format: true
  format_command: "pnpm format"
  
  # 文件操作权限
  permissions:
    create_files: true
    modify_files: true
    delete_files: false  # 禁止删除文件
    run_commands: true
    blocked_commands:
      - "rm -rf"
      - "git push"
      - "npm publish"
  
  # 代码风格
  code_style:
    indentation: 2
    quotes: "single"
    semicolons: true
    import_order: ["react", "third-party", "internal", "relative"]
  
  # 上下文偏好
  context:
    include_readme: true
    include_tsconfig: true
    max_files_in_context: 20
    prefer_recent_files: true

# .cursor/prompts/custom.md

## 代码审查 Agent
当我说 "review" 时，请：
1. 检查当前文件的类型安全
2. 查找潜在的性能问题
3. 验证错误处理是否完整
4. 检查是否有未使用的导入
5. 建议可提取的可复用组件

## 重构 Agent
当我说 "refactor" 时，请：
1. 识别重复代码
2. 建议设计模式改进
3. 简化复杂函数（圈复杂度 > 10）
4. 确保向后兼容

用户输入：
"为这个 Express 项目添加 JWT 认证，包括注册、登录、密码重置功能"

Agent 执行过程：
[1/12] 🔍 探索项目结构...
  - 发现 package.json, src/, routes/, models/
  - 检测到使用 TypeScript + Express + Prisma

[2/12] 📦 安装依赖...
  - jsonwebtoken, bcryptjs, @types/jsonwebtoken, @types/bcryptjs

[3/12] 📝 创建 src/config/auth.ts...
  - JWT 密钥配置
  - Token 过期时间设置

[4/12] 📝 创建 src/middleware/auth.ts...
  - JWT 验证中间件
  - 角色权限检查

[5/12] 📝 创建 src/services/auth.service.ts...
  - register: 用户注册
  - login: 用户登录
  - resetPassword: 密码重置
  - verifyToken: Token 验证

[6/12] ✏️ 修改 src/models/user.model.ts...
  - 添加 password 字段
  - 添加密码哈希钩子

[7/12] 📝 创建 src/routes/auth.routes.ts...
  - POST /auth/register
  - POST /auth/login
  - POST /auth/reset-password
  - GET /auth/me

[8/12] ✏️ 修改 src/app.ts...
  - 挂载 auth 路由

[9/12] 📝 创建 tests/auth.test.ts...
  - 注册流程测试
  - 登录流程测试
  - Token 验证测试
  - 权限检查测试

[10/12] 🧪 运行测试...
  ✅ 8/8 测试通过

[11/12] 🔍 代码审查...
  - 检查安全最佳实践
  - 确认无敏感信息泄露

[12/12] ✅ 完成！

<!-- README.md 中添加 Agent 友好的项目描述 -->
## 项目结构
- `src/api/` - API 路由层
- `src/services/` - 业务逻辑层
- `src/models/` - 数据模型
- `src/utils/` - 工具函数
- `tests/` - 测试文件（与 src/ 镜像）

## 约定
- 所有 API 返回 { code, data, message } 格式
- 使用 Zod 进行输入验证
- 错误使用自定义 AppError 类
- 数据库操作通过 Prisma Client

✅ 好的做法：
"先创建 User 类的数据模型"
"现在添加 CRUD API 路由"
"为每个 API 端点编写测试"
"运行测试并修复失败"

❌ 不好的做法：
"帮我构建整个用户管理系统"（范围太大，容易出错）

# .cursorignore
node_modules/
dist/
.env*
*.lock
coverage/
.github/