stage-03-extend-cursor

扩展 Cursor

Agent 模式深入

Agent 模式是 Composer 中最强大的工作模式。它赋予 AI 完全的自主权和工具访问权限：读写文件、搜索代码库、运行终端命令、使用 MCP 工具、搜索网络。

启用 Agent 模式

1. 按 Cmd+I 打开 Composer
2. 在 Composer 头部的模式选择器中切换为 Agent
3. 用自然语言描述你的任务

Agent 的工具

工具	描述
读取文件	读取项目中的任何文件
写入文件	创建或编辑文件
删除文件	从项目中移除文件
搜索代码库	使用代码库索引进行语义搜索
终端	运行 shell 命令并观察输出
MCP 工具	使用已配置的 MCP 服务器提供的工具
网络搜索	搜索网络获取文档和解决方案

Yolo 模式

Yolo 模式让 Agent 自动执行所有操作而不需要确认。适合可信的、理解充分的工作流，追求最大速度。

在 Composer 设置中启用，或者告诉 Agent"使用 Yolo 模式"。

注意： Yolo 模式跳过所有确认对话框。只在信任 Agent 操作且有版本控制可以回退时使用。

安全护栏

在普通（非 Yolo）模式下，Agent 在执行前会展示计划：

1. 计划展示 — Agent 显示它打算执行的操作
2. 确认 — 你批准或拒绝每个操作
3. 执行 — 被批准的操作被执行
4. 审查 — 查看结果并继续或调整

终端集成

Agent 可以运行终端命令并观察输出。这使它能够：

• 运行测试验证修改
• 安装依赖
• 构建项目
• 执行脚本
• Git 操作

Agent 看到命令输出后可以响应错误或失败。

最佳实践

保持任务聚焦——一次给 Agent 一个清晰的任务：

好：添加一个包含邮箱和密码字段的登录表单组件
避免：同时添加登录、注册、密码重置和个人资料页

提供上下文——使用 @ 符号给 Agent 相关上下文：

@src/types/auth.ts 添加一个登录 API 端点，使用这些类型进行验证

审查变更——始终通过 diff 视图审查 Agent 的修改。

使用版本控制——让 Agent 修改前先提交你的工作，给你一个干净的回退点。

迭代——如果 Agent 的首次尝试不理想，描述需要修改的地方而不是重新开始。

MCP 集成

MCP（Model Context Protocol）让 Cursor 连接外部工具和数据源。MCP 服务器提供 AI Agent 在 Composer 会话中可以使用的工具。

传输类型

STDIO——MCP 服务器作为本地进程运行，通过标准输入/输出通信：

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["path/to/server.js"],
      "env": {
        "API_KEY": "your-key"
      }
    }
  }
}

HTTP (SSE)——MCP 服务器作为远程 HTTP 服务运行：

{
  "mcpServers": {
    "my-remote-server": {
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-token"
      }
    }
  }
}

在 Composer 中使用 MCP

在 Agent 模式中，Agent 会自动使用 MCP 工具。你也可以明确要求使用特定工具：

使用数据库工具检查 users 表的 schema，然后创建一个添加 email 列的迁移

安全考虑

• MCP 服务器以你的用户权限运行
• 谨慎配置有文件系统或网络访问权限的 MCP 服务器
• 只配置你信任的 MCP 服务器
• 在 Yolo 模式外审查 MCP 工具操作

Skills

Skills 为 Cursor 提供专业化的能力。它们用领域特定的知识和工作流扩展基础功能。

使用 Skills

Skills 在 Composer 或 Chat 中通过 @ 引用：

@skill-name 帮我实现用户认证

AI 加载 skill 的指令作为上下文，然后按照指令完成任务。

创建自定义 Skill

在项目的 .cursor/skills/ 目录中创建 Skill 文件：

---
name: api-endpoint
description: 按照项目规范创建新的 REST API 端点
---

# API 端点 Skill

创建新 API 端点时：

1. 在 `src/schemas/` 中定义 Zod 输入 schema
2. 在 `src/routes/` 中创建路由处理器
3. 在 `tests/integration/` 中添加集成测试
4. 更新 `docs/api.yaml` 中的 OpenAPI 规范

## 命名规范
- 路由：`src/routes/{resource}.ts`
- Schema：`src/schemas/{resource}.schema.ts`
- 测试：`tests/integration/{resource}.test.ts`

提交到版本控制后，整个团队共享相同的 Skills。

@-symbols 高级用法

组合多个上下文

@src/types/user.ts @src/api/users.ts @Codebase 用户认证流程 创建一个新的用户注册端点

使用 @Web 查找外部信息

@Web Zod 4 有什么新特性？用最新 API 重写我们的验证逻辑

使用 @Git 对比变更

@Git 跟上一个版本相比，认证模块有什么变化？

使用 @Docs 引用外部文档

@Docs Next.js App Router 中 server actions 怎么用？