---
title: "Headless 模式"
description: "基于 Cursor 官方 Headless CLI 文档解释 print mode、--force、输出格式、脚本审查、stream-json、图片路径和自动化安全边界。"
verifiedAt: "2026-05-09"
---

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

> [!NOTE]
> **阅读目标**：读完本章，你应该能写出一个只读审查脚本、一个可落盘修改脚本，并解释 `--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`：

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

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

```bash
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 工作区运行。

## 3. 安装和认证

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

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

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

脚本环境通常使用 API key：

```bash
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` | 实时进度、工具调用流、长任务观察 |

```bash
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`：

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

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

## 5. 只读审查脚本

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

```bash
#!/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. 可落盘修改脚本

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

```bash
#!/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 会在需要时通过工具读取。

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

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

```bash
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`，把只读审查也变成可写任务。

<details>
<summary>深读：什么时候才应该使用 `--yolo`</summary>

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

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

## 本章自检

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

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

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

## 官方来源

- [Using Headless CLI](https://cursor.com/docs/cli/headless.md) —— 官方说明 print mode、`--force` / `--yolo`、安装认证、输出格式、脚本示例、stream-json 和图片路径。
- [Using Agent in CLI](https://cursor.com/docs/cli/using.md#non-interactive-mode) —— 官方 non-interactive mode 背景。
- [Cursor Output Format](https://cursor.com/docs/cli/reference/output-format.md) —— 官方输出格式说明。
- [Cursor CLI Authentication](https://cursor.com/docs/cli/reference/authentication.md) —— 官方 CLI 认证参考。

## 接下来去哪

<Cards>
  <Card title="GitHub Actions" description="继续学习把 headless CLI 放进 GitHub workflow。" href="/docs/cursor/official/03-cli-automation/36-github-actions" />
  <Card title="Output Format" description="继续学习 text、json、stream-json 的机器消费边界。" href="/docs/cursor/official/03-cli-automation/42-output-format" />
</Cards>
