Headless 模式

Headless 模式是把 Cursor CLI 放进 scripts 和 automation workflows。它的核心入口是 print mode：-p 或 --print。

阅读目标：读完本章，你应该能写出一个只读审查脚本、一个可落盘修改脚本，并解释 --force、输出格式、API key 和日志审计边界。

1. Headless 和交互式 CLI 的区别

项目	交互式 CLI	Headless CLI
入口	`agent`	`agent -p` 或 `agent --print`
使用场景	人机协作、review、逐步修改	脚本、CI、批处理、自动报告
输入方式	会话中持续输入	单次 prompt 或脚本循环
输出方式	终端 UI	text、json、stream-json
风险	人可以实时拦截	容易被脚本放大，需要更严格边界

Headless 的正确思路不是“无人值守让 Agent 自己发挥”，而是把任务、输入、输出、权限、失败码和日志都固定下来。

2. Print mode

只读或建议型任务可以直接使用 -p：

agent -p "What does this codebase do?"
agent --print "Review the current diff for security risks. Do not edit files."

如果需要脚本中实际修改文件，官方 Headless 文档要求结合 --force 或 --yolo：

agent -p --force "Refactor this code to use modern ES6+ syntax"
agent -p --yolo "Add focused tests for the checkout parser"

这里有一个容易混淆的点：Cursor 的 CLI 文档要求把 non-interactive 场景按可写风险治理；Headless 文档又说明不加 --force 时改动只会被提出而不会直接落盘。实践上应同时满足两点：

只读脚本明确写 Do not edit files。
写入脚本必须显式使用 --force / --yolo，并在干净 git 工作区运行。

判断一个 headless 任务能不能自动化时，先问它是否能被明确验收。能用测试、lint、截图、结构化 JSON 或固定文件 diff 验收的任务，才适合进入脚本；只能靠主观感觉判断好坏的任务，应该保留人工审查。

3. 安装和认证

Headless 仍然依赖 CLI 安装和认证。

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

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

脚本环境通常使用 API key：

export CURSOR_API_KEY=your_api_key_here
agent -p "Analyze this code"

上线时不要把 key 写进脚本、仓库、CI log 或 markdown 教程。用 CI secret、环境变量或受管凭据系统注入。

4. 输出格式

不同场景选择不同输出格式。

输出格式	适合
`text`	人读总结、PR comment、日志摘要
`json`	机器解析最终结果
`stream-json`	实时进度、工具调用流、长任务观察

agent -p --output-format text "Summarize the current repo structure"
agent -p --output-format json "Return the top 5 security risks as JSON"
agent -p --output-format stream-json "Analyze this project and report progress"

如果要实时消费 delta，可结合 --stream-partial-output：

agent -p --output-format stream-json --stream-partial-output \
  "Analyze this project structure and create a summary report"

脚本消费 stream-json 时要用 jq 或正式 JSON parser，不要用脆弱的字符串截取。

如果输出要进入后续程序，prompt 里也要写清字段、错误状态和空结果处理方式。否则 Agent 即使完成了分析，脚本也可能因为一句自然语言变化而误判成功或失败。

5. 只读审查脚本

第一阶段建议先做只读审查。

#!/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、PR 辅助或人工触发的 CI job。它不需要写文件，风险小，输出也容易审查。

6. 可落盘修改脚本

写文件脚本必须在更严格的边界内运行。

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

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

agent -p --force --output-format text \
  "Add JSDoc comments to src/public-api.ts.
  Only edit src/public-api.ts.
  After editing, summarize the exact changes."

git diff -- src/public-api.ts

商业级写入脚本至少做到：

运行前检查 git 工作区是否干净。
明确允许编辑的文件或目录。
禁止触碰 secrets、lockfile、配置和无关模块。
运行后展示 git diff。
再跑 focused tests 或 lint。

不要用 find src -name "*.js" | while read file 一口气让 Agent 批量改全仓，除非你已经有分批、日志、失败恢复和人工 review 机制。

7. 图片和二进制文件

Headless CLI 可以在 prompt 里引用图片、视频或其他文件路径，Agent 会在需要时通过工具读取。

agent -p "Analyze this screenshot and list visible layout issues: ./screenshot.png"
agent -p "Compare these two screenshots: ./before.png ./after.png"

文件路径可以是相对路径或绝对路径。脚本里要先检查文件存在，避免 Agent 把“读不到文件”当成业务问题分析。

test -f ./screenshots/ui-mockup.png
agent -p --output-format json \
  "Describe layout issues in ./screenshots/ui-mockup.png"

8. 常见失败点

把 headless 当成“自动写代码”，但没有 --force、git diff 和测试。
脚本 prompt 没写范围，导致 Agent 扫描或修改过多文件。
用 text 输出接机器解析，稍微变一句话脚本就坏。
把 API key、文件路径、日志和模型输出直接暴露到公开 CI。
对所有任务使用 --force，把只读审查也变成可写任务。

深读：什么时候才应该使用 --yolo

--yolo 语义上就是更少人工确认的高权限路径。它只适合低风险、范围很小、验证充分、可自动回滚的任务。

对公开仓库、生产代码、带 secrets 的环境和团队共享 runner，默认不要用 --yolo。即使使用，也要放在临时分支、干净工作区和严格 allowlist 里。

本章自检

完成本章后，用这 3 个问题检查自己是否真正理解：

agent -p 和 agent -p --force 的落盘行为有什么差异？
为什么机器消费结果应该优先用 json 或 stream-json？
写入型 headless 脚本运行前为什么要检查 git 工作区干净？

通过标准：你能写出一个只读审查脚本和一个小范围写入脚本，并能解释它们的权限、输出、日志和回退策略。

官方来源

Using Headless CLI —— 官方说明 print mode、--force / --yolo、安装认证、输出格式、脚本示例、stream-json 和图片路径。
Using Agent in CLI —— 官方 non-interactive mode 背景。
Cursor Output Format —— 官方输出格式说明。
Cursor CLI Authentication —— 官方 CLI 认证参考。