Cursor CLI Agent Skill
本技能提供使用 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：
export PATH="$HOME/.local/bin:$PATH"
重启终端，或运行 source ~/.zshrc（或 ~/.bashrc）。要求 macOS 10.15 或更高版本，Intel 与 Apple Silicon Mac 均可使用。
Linux/Ubuntu：重启终端，或 source 你的 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 "Add error handling to this 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 'Run tests and report coverage'
# 或
agent --print 'Refactor this file to use async/await'
输出格式：
# 纯文本（默认）
agent -p 'Analyze code' --output-format text
# 结构化 JSON
agent -p 'Find bugs' --output-format json
# 实时流式 JSON
agent -p 'Run tests' --output-format stream-json --stream-partial-output
强制模式（无需确认自动应用变更）：
agent -p 'Fix all linting errors' --force
媒体支持：
agent -p 'Analyze this screenshot: 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 'Your task here'" 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 需要交互式终端能力；直接从 subprocess/exec 调用 agent 在无 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 'Review the changes in the current branch against main. Focus on security and performance.'
重构：
agent -p 'Refactor src/utils.ts to reduce complexity and improve type safety.'
调试：
agent -p 'Analyze the following error log and suggest a fix: [paste log here]'
Git 集成：
agent -p 'Generate a commit message for the staged changes adhering to conventional commits.'
批处理（CI/CD）：
# 在 CI 环境中设置 API 密钥
export CURSOR_API_KEY=$CURSOR_API_KEY
# 以 JSON 输出运行安全审计
agent -p 'Audit this codebase for security vulnerabilities' --output-format json --force
# 生成测试覆盖率报告
agent -p 'Run tests and generate coverage report' --output-format text
多文件分析：
使用上下文选择分析多个文件：
agent
# 然后在交互模式中：
@src/api/
@src/models/
Review the API implementation for consistency with our data models
适用场景
适用于软件工程中的代码评审、重构、调试、Git 操作自动化、CI/CD 批处理与多文件分析，以及从 AI 代理或脚本等自动化环境调用 Cursor CLI 的场景。
限制
- 从自动化环境调用时需要真实 TTY，直接执行（如无 TTY 的 agent、agent -p、subprocess.run、script -c）会无限期挂起，需借助 tmux。
- macOS 需 10.15 或更高版本。
- Homebrew 安装仅限 macOS。
- 价格、收费与平台等资料暂未提供。