---
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="/zh-Hant/docs/cursor/official/03-cli-automation/36-github-actions" />
  <Card title="Output Format" description="繼續學習 text、json、stream-json 的機器消費邊界。" href="/zh-Hant/docs/cursor/official/03-cli-automation/42-output-format" />
</Cards>
