Cursor 3 后台Agent异步编程工作流

// 通过快捷键启动 Agent 的等效操作
// Cursor 内部的 Agent 启动逻辑简化示意

interface AgentTask {
  id: string;
  description: string;
  model: 'composer-2' | 'claude-sonnet' | 'gpt-4.1';
  worktree: string;
  status: 'queued' | 'running' | 'completed' | 'failed';
  createdAt: Date;
}

function launchBackgroundAgent(task: AgentTask): void {
  // 1. 创建独立 worktree
  const worktree = createIsolatedWorktree(task.id);
  
  // 2. 在隔离环境中启动 Agent
  const agent = spawnAgent({
    model: task.model,
    cwd: worktree.path,
    instructions: task.description,
    autoFix: true,     // 测试失败自动修复
    autoPR: true,      // 完成后自动提 PR
  });
  
  // 3. 注册完成回调
  agent.onComplete(() => {
    notifyUser(task.id, 'Task completed');
  });
}

# 创建新后台任务
/background "实现用户头像上传功能，支持裁剪和压缩"

# 在隔离 worktree 中执行
/worktree "尝试用 Rust 重写这个解析模块"

# 多模型竞速
/best-of-n composer, sonnet, gpt "修复这个 flaky test"

# 暂停/恢复 Agent
/pause agent-id-xxx
/resume agent-id-xxx

# 查看 Agent 日志
/logs agent-id-xxx

{
  "setup": {
    "commands": [
      "nvm install 20",
      "npm ci",
      "npx prisma generate",
      "npm run build:deps"
    ]
  },
  "services": {
    "database": "postgres:16",
    "cache": "redis:7",
    "search": "elasticsearch:8.12"
  },
  "env_file": ".env.agent",
  "secrets": ["DATABASE_URL", "OPENAI_API_KEY"],
  "test_command": "npm test",
  "lint_command": "npm run lint"
}

FROM node:20-slim

# 系统依赖
RUN apt-get update && apt-get install -y \
    python3 \
    chromium \
    && rm -rf /var/lib/apt/lists/*

# 项目依赖
WORKDIR /workspace
COPY package*.json ./
RUN npm ci

# Playwright 浏览器
RUN npx playwright install chromium

# 环境变量
ENV CI=true
ENV NODE_ENV=test

## 代码规范
- 使用 TypeScript strict mode
- 组件使用函数式 + Hooks
- API 路由使用 zod 校验入参
- 测试文件与源文件同目录，命名为 *.test.ts

## Git 规范  
- commit message 使用 conventional commits
- 每个 PR 只解决一个问题

## 禁止事项
- 不使用 any 类型
- 不使用 class 组件
- 不直接操作 DOM

{
  "repositories": [
    {
      "url": "github.com/your-org/shared-types",
      "path": "./packages/shared-types",
      "branch": "main"
    },
    {
      "url": "github.com/your-org/api-sdk",
      "path": "./packages/api-sdk",
      "branch": "v2"
    }
  ]
}

# 示例：批量重构 API 路由（分配给 Background Agent 的任务描述）

"""
任务：将所有 Express 路由迁移到 Fastify

要求：
1. 保持所有路由路径和 HTTP 方法不变
2. 将 Express middleware 转换为 Fastify 插件
3. 将 req.body 验证从手动检查改为 JSON Schema
4. 确保所有现有测试通过
5. 更新 package.json 依赖

范围：src/routes/ 目录下所有文件
参考：docs/migration-guide.md 中的 Fastify 迁移规范
"""

// 并行 Agent 启动脚本示例
const modules = ['auth', 'payment', 'notification', 'user'];

const tasks = modules.map(mod => ({
  description: `
    为 src/modules/${mod}/ 编写单元测试：
    - 目标覆盖率 > 80%
    - 使用 vitest + @testing-library/react
    - mock 所有外部 API 调用
    - 包含边界条件和错误路径
  `,
  model: 'composer-2',
  worktree: `test-sprint-${mod}`,
}));

// 每个 Agent 独立的 worktree，互不冲突
tasks.forEach(task => launchBackgroundAgent(task));

# Agent 审查预处理任务描述

"""
任务：审查 PR #287 并生成报告

审查维度：
1. 安全性：是否有注入风险、敏感信息泄露
2. 性能：是否有 N+1 查询、内存泄漏风险
3. 可维护性：命名是否清晰、是否有魔数
4. 测试覆盖：新增代码是否有对应测试

输出格式：
- 每个问题标注严重等级（Critical/Warning/Info）
- 提供修复建议的代码片段
- 总结一句话评价

完成后将报告作为 PR comment 发布。
"""

# 实验：用不同状态管理方案重写购物车模块
/worktree "用 Zustand 重写购物车状态管理，替换现有的 Redux Toolkit 实现"

# 实验：尝试新的数据库方案
/worktree "将用户模块从 Prisma/PostgreSQL 迁移到 Drizzle/Turso"

# 实验：架构重构
/worktree "将单体 API 拆分为 auth、billing、core 三个微服务"

/best-of-n composer, sonnet, gpt "
实现一个高性能的 JSON diff 算法：
- 支持嵌套对象和数组
- 输出 RFC 6902 JSON Patch 格式
- 对 10MB JSON 文件的处理时间 < 500ms
- 包含完整的单元测试
"

// GitHub Issue 自动触发 Agent 的 Webhook 处理逻辑
interface GitHubIssueEvent {
  action: 'opened' | 'labeled';
  issue: {
    title: string;
    body: string;
    labels: Array<{ name: string }>;
  };
}

// 当 Issue 被打上 "cursor-agent" 标签时自动触发
function handleIssueLabeled(event: GitHubIssueEvent): void {
  if (event.issue.labels.some(l => l.name === 'cursor-agent')) {
    launchBackgroundAgent({
      description: `Fix: ${event.issue.title}\n\n${event.issue.body}`,
      model: 'composer-2',
      autoPR: true,
      targetBranch: 'main',
    });
  }
}

@Cursor 修复 #auth-service 中的 JWT 过期判断逻辑，
用户反馈 token 刷新后仍然报 401。
相关代码在 src/middleware/auth.ts

{
  "permissions": {
    "network": ["api.stripe.com", "*.amazonaws.com"],
    "filesystem": {
      "read": ["src/", "tests/", "docs/"],
      "write": ["src/", "tests/"]
    },
    "shell": {
      "allow": ["npm test", "npm run lint", "npx prisma"],
      "deny": ["rm -rf", "DROP TABLE", "curl * | bash"]
    }
  }
}

## 目标
[一句话说清楚要做什么]

## 上下文
[为什么要做这个？有什么前置背景？]

## 具体要求
1. [具体要求 1]
2. [具体要求 2]
3. [具体要求 3]

## 范围
- 需要修改：[列出文件/目录]
- 不要修改：[明确排除项]

## 完成标准
- [ ] 所有测试通过
- [ ] lint 无报错
- [ ] [其他验收条件]

## 参考
- [相关文档链接]
- [示例代码位置]

# 推荐的 Agent 使用渐进策略

TASK_COMPLEXITY = {
    "simple": {
        "examples": ["修改错误提示文案", "添加日志语句", "更新依赖版本"],
        "strategy": "直接 /background，无需额外指导",
        "success_rate": "~90%"
    },
    "medium": {
        "examples": ["实现新 API 端点", "添加表单验证", "编写测试套件"],
        "strategy": "提供明确规范 + 参考示例",
        "success_rate": "~70%"
    },
    "complex": {
        "examples": ["跨模块重构", "性能优化", "新架构引入"],
        "strategy": "先用前台 Agent 验证思路，拆分为多个子任务后并行委派",
        "success_rate": "~55%"
    },
    "exploratory": {
        "examples": ["技术选型", "架构设计", "方案对比"],
        "strategy": "使用 /worktree 或 /best-of-n，人工最终决策",
        "success_rate": "取决于评估标准"
    }
}