Headless 模式

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

1. Headless 和互動式 CLI 的區別

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. 輸出格式

不同場景選擇不同輸出格式。

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，把只讀審查也變成可寫任務。

本章自檢

完成本章後，用這 3 個問題檢查自己是否真正理解：

1. agent -p 和 agent -p --force 的落盤行為有什麼差異？
2. 為什麼機器消費結果應該優先用 json 或 stream-json？
3. 寫入型 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 認證參考。

接下來去哪