名称： cursor-agent
版本： 2.1.0
描述： 一个用于执行各种软件工程任务的 Cursor CLI 代理综合技能（已更新至 2026 年功能，包含 tmux 自动化指南）。
作者： Pushpinder Pal Singh

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:
- 在 ~/.zshrc (zsh) 或 ~/.bashrc (bash) 中添加 PATH：
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

身份验证

通过浏览器进行身份验证：

agent login

或使用 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 - 直接从 CLI 创建和编辑规则
• /commands - 创建和修改自定义命令
• /mcp enable [server-name] - 启用 MCP 服务器
• /mcp disable [server-name] - 禁用 MCP 服务器

键盘快捷键

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

非交互式 / 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 '修复所有 linting 错误' --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 需要交互式终端能力
- 没有 TTY 时，直接从子进程/exec 调用 agent 会挂起

无效的方法：

# ❌ 这些命令将无限期挂起：
agent "任务"                    # 无 TTY
agent -p "任务"                 # 无 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 实现与我们的数据模型的一致性