Cursor CLI 与 Headless 自动化

Cursor CLI 的价值不是"换个地方聊天"，而是把 Agent 放进 terminal、git、scripts、CI、PR review 和自动化流水线。Headless（无界面 / 非交互）模式更进一步，让任务可以非交互执行。边界也更严格：非交互越多，权限、输出和回退越要明确。

1. 安装与第一次启动

官方安装命令：

# macOS / Linux / WSL
curl https://cursor.com/install -fsS | bash

# Windows PowerShell
irm 'https://cursor.com/install?win32=true' | iex

# 安装完成后直接启动交互
agent

agent 是 Cursor CLI 的可执行命令。第一次启动会要求登录，认证完毕后即可在终端直接对话。

2. CLI 适合什么

编辑器适合边看代码边协作；CLI 适合贴近工程命令和自动化系统。

CLI 适合：

• 终端里快速问项目结构。
• 对当前 git diff 做只读 review。
• 批量生成报告。
• 在 CI 中输出检查结果。
• 通过 script 固定 prompt 和 output format。
• 把任务 handoff 到 Cloud Agent。

不适合：

• 需要大量视觉交互的 UI 调整。
• 需要人工逐步审查的复杂改动却没有 review gate。
• 生产部署、删除、数据库迁移这类高风险自动写入。

3. 三种模式仍然重要

Cursor CLI 支持 Agent、Plan、Ask。和编辑器一样，模式决定风险。

agent --mode=ask "explain how billing is initialized"
agent --plan "plan a safe migration from REST to GraphQL"
agent "fix the failing checkout parser test and show the diff"

判断：

• 只读理解：--mode=ask。
• 复杂任务先方案：--plan 或 --mode=plan。
• 明确小任务：默认 Agent。

很多 CLI 事故来自把 Ask 任务用 Agent 执行，或者把 Plan 任务直接写入。

把任务推到 Cloud Agent（mid-conversation handoff）

在交互会话中，把消息开头加 & 可以把任务推到 Cloud Agent 继续跑——本地终端关掉它也不会停。适合长任务边喝咖啡边跑：

& 把整个 auth module 重构为 JWT，并补完整测试

跑起来之后可以在 cursor.com/agents 网页端或移动端继续跟进。

恢复历史会话（Sessions）

agent ls                  # 列所有历史对话
agent resume              # 恢复最近一个
agent --continue          # 继续上一个会话
agent --resume="chat-id"  # 指定 chat id 恢复

会话恢复保留了完整上下文，适合长任务跨天继续，或者本地切到不同终端窗口接着干。

4. Headless 是自动化入口，不是无监管入口

Headless 的核心是 print mode（打印模式，非交互输出到 stdout 而非进入 REPL）：agent -p 或 agent --print。它适合 scripts、CI、批处理和自动报告。

只读示例：

agent -p --output-format text \
  "Review the current git diff for correctness and security risks. Do not edit files."

可写示例需要显式边界：

agent -p --force --output-format text \
  "Only edit src/public-api.ts. Add missing JSDoc for exported functions. Do not edit any other file."

关键点：

• agent -p 适合输出建议或报告。
• 写入脚本必须显式使用 --force 或 --yolo（you-only-live-once，跳过所有确认的极简写入开关，比 --force 更激进），并限制文件范围。
• 只读脚本要明确写 Do not edit files。
• 写入脚本前检查 git 工作区。

5. 输出格式决定能否自动化

官方 Headless 文档支持 text、json、stream-json：

机器消费不要靠字符串截取。要么要求 JSON schema，要么用 jq 或正式 parser 处理。

agent -p --output-format json \
  "Return exactly JSON with keys: findings, riskLevel, recommendedCommands."

6. 只读审查脚本

第一阶段建议只做 review，不写文件。

#!/usr/bin/env bash
set -euo pipefail

agent -p --output-format text \
  "Review the current git diff for:
  - correctness risks
  - security risks
  - missing tests

  Do not edit files.
  Return concise findings with file paths when possible."

这个脚本适合放在本地 pre-review、人工触发的 CI job 或 PR 辅助评论。它的价值是稳定产出风险清单，而不是替代测试。

7. 小范围写入脚本

写入必须更严格。

#!/usr/bin/env bash
set -euo pipefail

test -z "$(git status --short)"

agent -p --force --output-format text \
  "Only edit src/public-api.ts.
  Add JSDoc comments to exported functions.
  Do not change runtime behavior.
  After editing, summarize exact changes."

git diff -- src/public-api.ts

上线标准：

• 工作区干净。
• 文件范围固定。
• 禁止触碰 secrets、lockfile、配置和无关模块。
• 运行后展示 diff。
• 跑 focused test、lint 或 build。
• 失败时能丢弃分支或 revert commit。

8. GitHub Actions：先 restricted autonomy

官方 GitHub Actions 文档有 full autonomy 和 restricted autonomy 两种思路。

生产 CI 默认用 restricted autonomy：

• Agent 负责分析和有限文件修改。
• deterministic workflow step（确定性工作流步骤，命令行为可预测、不依赖 AI 推理的固定 step）负责 branch、commit、push、PR comment。
• CURSOR_API_KEY 只走 GitHub Secrets。
• permissions 明确 allow / deny。
• 默认 deny Shell(git)、Shell(gh) 和 .env* 写入。

不要一开始就让 Agent 在 CI 里同时负责理解问题、修改文件、提交、推送和评论 PR。职责拆开，日志和回退才清楚。

9. 商业级上线清单

把 CLI / headless 放进团队流程前，确认：

• 安装来源、PATH、版本验证可复现。
• 本地、CI、团队成员的认证边界分开。
• Ask、Plan、Agent 使用场景写清楚。
• agent -p 默认只读。
• 写入脚本要求干净 Git 工作区。
• 输出格式固定，机器消费用 JSON。
• CI secrets 不进日志和 prompt。
• Git / gh / deploy 由 deterministic step 执行。
• 每个自动化都有日志、退出码和人工 gate。

官方来源

• Cursor CLI Overview：官方 CLI 总览、interactive / print mode、Cloud Agent handoff、sessions、sandbox 和 sudo prompt。
• Using Headless CLI：官方 print mode、--force / --yolo、输出格式、API key 和脚本示例。
• Cursor GitHub Actions：官方 CI 安装、CURSOR_API_KEY、full autonomy、restricted autonomy 和 permissions。
• Cursor CLI Output Format：官方 text、json、stream-json 输出格式。

接下来去哪