Cursor CLI 代理技能

本技能提供了利用 Cursor CLI 工具的全面指南和工作流程集，包含 2026 年 1 月更新的所有功能。

安装

标准安装 (macOS, Linux, Windows WSL)

curl https://cursor.com/install -fsS | bash

Homebrew (仅限 macOS)

brew install --cask cursor-cli

安装后设置

macOS:

• 在以下文件中添加到 PATH~/.zshrc(zsh) 或~/.bashrc(bash):

  export PATH="$HOME/.local/bin:$PATH"

• 重启终端或运行source ~/.zshrc(或~/.bashrc)
• 需要 macOS 10.15 或更高版本
• 适用于 Intel 和 Apple Silicon 芯片的 Mac

Linux/Ubuntu:

• 重启终端或重新加载 shell 配置
• 使用以下命令验证agent --version

两个平台:

• 命令:agent(主要) 和cursor-agent(向后兼容)
• 验证安装:agent --version或cursor-agent --version

认证

通过浏览器认证:

代理登录

或使用 API 密钥：

export CURSOR_API_KEY=your_api_key_here

更新

保持您的 CLI 为最新版本：

agent update
# 或者
agent upgrade

命令

交互模式

启动与代理的交互式会话：

agent

使用初始提示启动：

agent "为此 API 添加错误处理"

向后兼容性： cursor-agent仍然有效，但agent现在是主要命令。

模型切换

列出所有可用模型：

agent models
# 或
agent --list-models

使用特定模型：

agent --model gpt-5

在会话期间切换模型：

/models

会话管理

管理您的代理会话：

• 列出会话： agent ls
• 恢复最近的会话： agent resume
• 恢复特定会话： agent --resume="[chat-id]"

上下文选择

在对话中包含特定文件或文件夹：

@filename.ts
@src/components/

斜杠命令

在交互式会话期间可用：

• /models- 在 AI 模型之间交互式切换
• /compress- 总结对话并释放上下文窗口
• /rules- 直接从命令行界面创建和编辑规则
• /commands- 创建和修改自定义命令
• /mcp enable [server-name]- 启用一个 MCP 服务器
• /mcp disable [server-name]- 禁用一个 MCP 服务器

键盘快捷键

• Shift+Enter- 为多行提示添加换行符
• Ctrl+D- 退出命令行界面（出于安全考虑需按两次）
• Ctrl+R- 查看更改（按i查看说明，使用方向键导航）
• 向上箭头- 循环查看之前的消息

非交互式 / CI 模式

在非交互式模式下运行代理，适用于 CI/CD 流水线：

agent -p '运行测试并报告覆盖率'
# 或者
agent --print '重构此文件以使用 async/await'

输出格式：

# 纯文本（默认）
agent -p '分析代码' --output-format text

# 结构化 JSON
agent -p '查找错误' --output-format json

# 实时流式 JSON
agent -p '运行测试' --output-format stream-json --stream-partial-output

强制模式（无需确认自动应用更改）：

agent -p '修复所有 lint 错误' --force

媒体支持：

agent -p '分析此截图：screenshot.png'

⚠️ 与 AI 代理 / 自动化一起使用（需要 tmux）

重要：在自动化环境（AI 代理、脚本、子进程调用）中运行 Cursor CLI 时，CLI 需要一个真实的 TTY。直接执行将无限期挂起。

解决方案：使用 tmux

# 1. 如果尚未安装，请安装 tmux
sudo apt install tmux  # Ubuntu/Debian
brew install tmux      # macOS

# 2. 创建一个 tmux 会话
tmux kill-session -t cursor 2>/dev/null || true
tmux new-session -d -s cursor

# 3. 导航到项目目录
tmux send-keys -t cursor "cd /path/to/project" Enter
sleep 1

# 4. 运行 Cursor 代理
tmux send-keys -t cursor "agent '你的任务在这里'" Enter

# 5. 处理工作区信任提示（首次运行）
sleep 3
tmux send-keys -t cursor "a"  # 信任工作区

# 6. 等待完成
sleep 60  # 根据任务复杂度调整

# 7. 捕获输出
tmux capture-pane -t cursor -p -S -100

# 8. 验证结果
ls -la /path/to/project/

为什么这有效：

• tmux 提供了一个持久的伪终端（PTY）
• Cursor 的 TUI 需要交互式终端功能
• 直接代理来自子进程/exec的调用在没有TTY时会挂起

无效的方法：

# ❌ 这些会无限期挂起：
agent "task"                    # 无TTY
agent -p "task"                 # 无TTY  
subprocess.run(["agent", ...])  # 无TTY
script -c "agent ..." /dev/null # 可能导致Cursor崩溃

规则与配置

代理自动从以下位置加载规则：

• .cursor/rules
• AGENTS.md
• CLAUDE.md

使用/rules命令直接从CLI创建和编辑规则。

MCP集成

MCP服务器自动从mcp.json配置加载。

动态启用/禁用服务器：

/mcp enable server-name
/mcp disable server-name

注意：完全支持带空格的服务器名称。

工作流

代码审查

对当前更改或特定分支执行代码审查：

agent -p '审查当前分支相对于main分支的更改。重点关注安全性和性能。'

重构

重构代码以提高可读性或性能：

agent -p '重构src/utils.ts以降低复杂度并改进类型安全性。'

调试

分析日志或错误信息以找到根本原因：

agent -p '分析以下错误日志并建议修复方案：[粘贴日志]'

Git集成

通过上下文感知自动化git操作：

agent -p '为已暂存的更改生成符合约定式提交规范的提交消息。'

批处理（CI/CD）

在CI流水线中运行自动化检查：

# 在CI环境中设置API密钥
export CURSOR_API_KEY=$CURSOR_API_KEY

# 运行安全审计并输出JSON格式
agent -p '审计此代码库的安全漏洞' --output-format json --force

# 生成测试覆盖率报告
agent -p '运行测试并生成覆盖率报告' --output-format text

多文件分析

使用上下文选择来分析多个文件：

agent
# 然后在交互模式下：
@src/api/
@src/models/
审查API实现与数据模型的一致性