####################################
Tutorial 3: Cursor 命令与快捷键
####################################
.. include:: ../links.ref
.. include:: ../tags.ref
.. include:: ../abbrs.ref
============ ==========================
**Abstract** Cursor 的核心命令和快捷键
**Authors** Walter Fan
**Status** WIP
**Updated** |date|
============ ==========================
.. contents::
:local:
Cursor 核心功能
===============
Cursor 提供了三种主要的 AI 交互方式：
.. code-block:: text
Cursor AI 交互方式
┌─────────────────────────────────────────────────────────────────┐
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Chat │ │ Inline Edit │ │ Composer │ │
│ │ Cmd+L │ │ Cmd+K │ │ Cmd+I │ │
│ ├─────────────┤ ├─────────────┤ ├─────────────┤ │
│ │ • 对话式 │ │ • 代码内 │ │ • 多文件 │ │
│ │ • 问答 │ │ • 快速修改 │ │ • 大型任务 │ │
│ │ • 解释代码 │ │ • 重构 │ │ • 新功能 │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Chat (Cmd+L)
============
Chat 是最基本的 AI 交互方式，适合问答、解释、讨论。
打开 Chat
---------
- **快捷键**: ``Cmd+L`` (Mac) / ``Ctrl+L`` (Windows/Linux)
- **或者**: 点击侧边栏的聊天图标
Chat 的基本用法
---------------
**1. 简单问答**
::
什么是 Python 的装饰器？
**2. 解释代码**
选中代码后按 ``Cmd+L``，代码会自动添加到上下文::
请解释这段代码的作用
**3. 代码生成**
::
帮我写一个 Python 函数，实现：
- 读取 CSV 文件
- 过滤掉空行
- 按指定列排序
- 输出到新文件
@ 符号引用
----------
Chat 支持使用 ``@`` 引用各种上下文：
.. list-table::
:header-rows: 1
:widths: 20 40 40
* - 引用类型
- 语法
- 说明
* - 文件
- ``@filename.py``
- 引用整个文件
* - 文件夹
- ``@folder/``
- 引用文件夹下所有文件
* - 符号
- ``@symbolName``
- 引用函数、类等
* - 代码库
- ``@codebase``
- 搜索整个代码库
* - 文档
- ``@docs``
- 引用文档
* - Web
- ``@web``
- 搜索网络
* - Git
- ``@git``
- 引用 Git 历史
**示例**::
@main.py @utils.py
这两个文件中有重复的代码，请帮我重构
@codebase
项目中哪里使用了 Redis？
@web
Python 3.12 有什么新特性？
Chat 模式
---------
Chat 有不同的模式，可以通过下拉菜单切换：
- **Normal**: 普通对话模式
- **Long Context**: 支持更长的上下文
- **Agent**: AI 可以自主执行任务（运行命令、创建文件等）
Inline Edit (Cmd+K)
===================
Inline Edit 是在代码中直接进行修改的方式，非常高效。
打开 Inline Edit
----------------
1. 将光标放在要修改的位置
2. 按 ``Cmd+K`` (Mac) / ``Ctrl+K`` (Windows/Linux)
3. 输入指令
4. 按 Enter 执行
基本用法
--------
**1. 生成代码**
在空行按 ``Cmd+K``::
写一个快速排序函数
**2. 修改代码**
选中代码后按 ``Cmd+K``::
添加错误处理
**3. 重构代码**
选中代码后按 ``Cmd+K``::
使用列表推导式重写
实用示例
--------
**添加文档字符串**
选中函数，按 ``Cmd+K``::
添加 docstring
**添加类型注解**
::
添加类型注解
**优化性能**
::
优化这段代码的性能
**修复 Bug**
::
修复这个 bug：当输入为空时会报错
快捷操作
--------
在 Inline Edit 中：
- **Enter**: 执行
- **Esc**: 取消
- **Tab**: 接受建议
- **Cmd+Enter**: 在新文件中生成
Composer (Cmd+I)
================
Composer 是 Cursor 最强大的功能，支持多文件编辑和复杂任务。
打开 Composer
-------------
- **快捷键**: ``Cmd+I`` (Mac) / ``Ctrl+I`` (Windows/Linux)
- **或者**: 点击右下角的 Composer 按钮
Composer vs Chat
----------------
.. list-table::
:header-rows: 1
:widths: 25 35 40
* - 特性
- Chat
- Composer
* - 文件编辑
- 单文件
- 多文件
* - 创建文件
- 需手动
- 自动创建
* - 执行命令
- 不支持
- 支持（Agent 模式）
* - 适用场景
- 问答、解释
- 开发新功能、重构
Composer 模式
-------------
**1. Normal 模式**
普通的多文件编辑::
创建一个 Flask API，包含：
- app.py: 主应用
- models.py: 数据模型
- routes/: 路由文件夹
**2. Agent 模式**
AI 可以自主执行任务：
- 运行终端命令
- 创建/删除文件
- 安装依赖
- 运行测试
::
创建一个 Python 项目：
1. 初始化虚拟环境
2. 安装 flask 和 pytest
3. 创建基本的项目结构
4. 写一个简单的测试
5. 运行测试确保通过
实用示例
--------
**创建完整功能**
::
@codebase
为这个项目添加用户认证功能：
1. 使用 JWT
2. 支持注册、登录、登出
3. 添加认证中间件
4. 写单元测试
**重构项目结构**
::
@src/
重构这个文件夹：
1. 按功能模块划分
2. 每个模块有自己的 __init__.py
3. 添加类型注解
4. 更新 import 语句
Tab 补全
========
Tab 补全是 Cursor 的智能代码补全功能。
基本用法
--------
1. 正常编写代码
2. 当看到灰色的建议时，按 ``Tab`` 接受
3. 按 ``Esc`` 忽略建议
Tab 补全的特点
--------------
- **多行补全**: 可以补全整个函数
- **上下文感知**: 根据文件内容和项目结构补全
- **智能推断**: 根据函数名推断实现
示例
----
输入函数签名::
def calculate_fibonacci(n: int) -> int:
按 Tab，AI 会补全整个实现。
配置 Tab 补全
-------------
在 Settings → Features → Cursor Tab 中可以配置：
- 启用/禁用
- 补全触发延迟
- 补全长度限制
常用快捷键总览
==============
核心快捷键
----------
.. list-table::
:header-rows: 1
:widths: 30 35 35
* - 功能
- Mac
- Windows/Linux
* - 打开 Chat
- ``Cmd+L``
- ``Ctrl+L``
* - Inline Edit
- ``Cmd+K``
- ``Ctrl+K``
* - 打开 Composer
- ``Cmd+I``
- ``Ctrl+I``
* - 接受建议
- ``Tab``
- ``Tab``
* - 拒绝建议
- ``Esc``
- ``Esc``
* - 新建 Chat
- ``Cmd+Shift+L``
- ``Ctrl+Shift+L``
编辑相关
--------
.. list-table::
:header-rows: 1
:widths: 30 35 35
* - 功能
- Mac
- Windows/Linux
* - 接受 Diff
- ``Cmd+Y``
- ``Ctrl+Y``
* - 拒绝 Diff
- ``Cmd+N``
- ``Ctrl+N``
* - 接受全部
- ``Cmd+Shift+Y``
- ``Ctrl+Shift+Y``
* - 拒绝全部
- ``Cmd+Shift+N``
- ``Ctrl+Shift+N``
导航相关
--------
.. list-table::
:header-rows: 1
:widths: 30 35 35
* - 功能
- Mac
- Windows/Linux
* - 命令面板
- ``Cmd+Shift+P``
- ``Ctrl+Shift+P``
* - 快速打开文件
- ``Cmd+P``
- ``Ctrl+P``
* - 符号搜索
- ``Cmd+Shift+O``
- ``Ctrl+Shift+O``
* - 全局搜索
- ``Cmd+Shift+F``
- ``Ctrl+Shift+F``
实战练习
========
练习 1：使用 Chat 理解代码
--------------------------
1. 打开一个你不熟悉的代码文件
2. 按 ``Cmd+L`` 打开 Chat
3. 输入：``请解释这个文件的整体结构和主要功能``
4. 针对不理解的部分继续提问
练习 2：使用 Inline Edit 重构
-----------------------------
1. 找一段可以优化的代码
2. 选中代码，按 ``Cmd+K``
3. 尝试以下指令：
- ``使用更 Pythonic 的方式重写``
- ``添加错误处理``
- ``提取为单独的函数``
练习 3：使用 Composer 创建功能
------------------------------
1. 按 ``Cmd+I`` 打开 Composer
2. 输入以下需求::
创建一个简单的命令行 TODO 应用：
- todo.py: 主程序
- storage.py: 数据存储（使用 JSON 文件）
- 支持：添加、删除、列出、标记完成
3. 观察 AI 如何创建多个文件
4. 检查并运行生成的代码
高级技巧
========
1. 组合使用
-----------
- 先用 Chat 讨论方案
- 用 Composer 实现功能
- 用 Inline Edit 微调细节
2. 上下文管理
-------------
- 使用 ``@`` 精确引用需要的文件
- 避免引用太多无关文件
- 使用 ``@codebase`` 让 AI 自己搜索
3. 迭代优化
-----------
- 不要期望一次完美
- 分步骤完成复杂任务
- 及时反馈问题让 AI 修正
4. 利用 Agent 模式
------------------
对于需要执行命令的任务，使用 Composer 的 Agent 模式：
- 自动安装依赖
- 运行测试
- 执行构建命令
小结
====
本教程介绍了 Cursor 的核心命令：
- **Chat (Cmd+L)**: 对话式交互，适合问答和解释
- **Inline Edit (Cmd+K)**: 代码内快速修改
- **Composer (Cmd+I)**: 多文件编辑和复杂任务
- **Tab 补全**: 智能代码补全
关键要点：
1. 选择合适的工具完成任务
2. 善用 ``@`` 引用提供上下文
3. 组合使用不同功能提高效率
下一步
------
在下一个教程中，我们将学习如何配置 Cursor Rules 来定制 AI 的行为。
练习
====
1. 使用 Chat 解释一个复杂的开源项目
2. 使用 Inline Edit 重构 10 段代码
3. 使用 Composer 从零创建一个完整的小项目
4. 记录你最常用的快捷键组合
参考资源
========
- `Cursor 官方文档 - Features `_
- `Cursor 快捷键参考 `_
- `Cursor Tips and Tricks `_