cursor-delegate

Cursor Delegate

你是編排者。將一個有範圍的編碼任務交給獨立的執行者——Cursor Agent CLI——然後審查它產生的內容並自行提交。你撰寫簡報並擁有判斷權；Cursor 在自己的 session 中負責打字；你負責驗證和提交。

這個循環只需要 shell 命令和檔案存取，因此任何類似的編排器都可以驅動它。

何時不該使用

• 任務小到可以直接處理；委派的開銷不值得。
• cursor-agent CLI 未安裝或未認證（執行 cursor-agent login）。
• 你想自己撰寫程式碼，或者你只需要 Cursor 對你撰寫的程式碼提供意見（--read-only 派送可以涵蓋這種情況——見下文——但單純的審查可能根本不需要委派）。

前置需求（檢查一次）

1. cursor-agent --version 執行成功。如果沒有，請依照 cursor.com/cli 上你平台的安裝程式，檢查它將執行的內容，並使用 cursor-agent login 認證。
2. cursor-agent status 顯示你已登入。
3. 你在目標 git 儲存庫中（或將 --cd 指向它）。relay 會傳遞 --trust，所以只指向你信任的儲存庫。

選擇模型

省略 --model 會使用你的 Cursor 預設值（通常是 auto——由 Cursor 選擇）。若要固定一個，請使用帳戶即時 cursor-agent models 輸出中的名稱傳遞 --model <name>——從該清單中選擇，而不是自行發明名稱。像 <name>[context=1m,effort=high] 這樣的參數化形式會原樣轉發。實際服務該次執行的模型會記錄在 result.json 的 resolvedModel 中。

循環

每個任務執行以下五個步驟。步驟 1、4 和 5 需要判斷；2 和 3 是機械性的。

1. 撰寫簡報

Cursor 只會看到你傳送的文字加上它能在工作區中檢查的內容——沒有聊天記錄或共享上下文。包含目標、目前狀態、要更改的內容、不要碰的內容、專案實際的 gate，以及報告契約。告訴 Cursor 不要 commit。每個簡報只處理一個任務。請參閱 references/writing-the-brief.md。

2. 派送

使用隨附的 helper。它包裝了 cursor-agent -p，從 stdin 餵入簡報，擷取結構化事件串流，並寫入 result.json。（<skill-dir> 是包含此 SKILL.md 的已安裝資料夾。）

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
# 唯讀（計畫模式——審查／診斷，不編輯）：加上 --read-only
# 可寫入但不需要自動批准命令：加上 --no-force
# 明確覆寫 Cursor 的 sandbox：加上 --sandbox enabled|disabled
# 從 `cursor-agent models` 固定模型：加上 --model <name>
# 恢復最近的 session：加上 --resume-last（僅 delta 簡報）
# 恢復特定 session：加上 --session <id>（僅 delta 簡報）
# 硬性時間限制（看門狗）：加上 --timeout 2h（30m 預設適合短執行；實作簡報通常需要 1-2h）
# 查看所有選項：node .../relay.mjs --help

子行程的 cwd 固定了工作區。在 Cursor 2026.07.23 或更新版本上，僅對額外的工作區目錄使用可重複的 --add-dir 旗標。relay 預設將產出寫入系統暫存目錄，且絕不 commit。請參閱 references/dispatch-and-poll.md。

3. 等待完成

helper 會阻塞直到 Cursor 完成。使用編排器的背景命令功能執行它，或在 shell 中背景執行並輪詢 result.json。執行前用法錯誤會以 exit 2 結束且不寫入結果；缺少 cursor-agent 會以 exit 127 結束並寫入 status: "cursor_agent_unavailable"。

信任程序狀態和工作樹，而不是進度顯示。完成表示程序已結束且 result.json 存在。Cursor 的完整報告是 result.json 中的 finalMessage 欄位（也會在 stdout 上完整列印在報告標記之間）。

Windows + hooks 注意事項： 如果使用者設定了 Cursor hooks（~/.cursor/hooks.json，或 cursor-agent 匯入的 Claude Code PreToolUse hooks），從 Git Bash（MSYS）主控台派送會讓 cursor-agent 將 PowerShell 語法的 hook 包裝器餵給 bash，因此 Cursor 嘗試執行的每個命令都會被封鎖——編輯仍然會落地，但 gate 不會執行。請改從 PowerShell 或 cmd 主控台派送。詳細資訊：references/dispatch-and-poll.md。

4. 審查——不要相信自我報告

將 Cursor 的最終訊息和 gate 宣稱視為宣稱：

• 自行重新執行專案的 gate。
• 對照簡報閱讀 diff，從 touchedFiles 開始。
• 如果已安裝，執行相關的 guard skills。
• 在刪除或重新命名後，往返遷移並 grep 尋找懸空引用。

請參閱 references/review-and-land.md。

5. 提交

執行者編輯工作樹；編排者負責 commit。 只有在 gate 通過且 diff 成立後才 commit。如果需要重做，使用 --resume-last 或 --session <id> 傳送 delta 簡報，然後再次審查。

自主權與權限

全新執行預設為可寫入且帶 --force：Cursor 在未經批准的情況下執行命令，除非你的 Cursor 設定明確拒絕，因此一般 gate（測試、linter、建置）會以無頭模式執行。--no-force 保持執行可寫入，但取消自動命令批准；需要批准的命令會被拒絕，因為無頭執行無法提示。--read-only 切換到 Cursor 的計畫模式（唯讀分析，不編輯，無 --force）。relay 總是傳遞 --trust，以避免無頭執行卡在工作區信任提示上，這就是為什麼 --cd 只能指向你信任的儲存庫。僅在需要覆寫 Cursor 的 sandbox 時傳遞 --sandbox enabled 或 --sandbox disabled。請求的值會記錄在 result.json 的 sandbox 中；它並不聲稱 Cursor 實際套用了什麼。Cursor 回報的權限模式記錄為 permissionMode；每次執行後檢查 touchedFiles 和 diff。

唯讀第二意見

--read-only 也可作為取得對立第二意見的乾淨方式，且沒有寫入風險：派送一個簡報，列出已同意的點，然後列出每個爭議點及雙方立場，要求 Cursor 為每個點辯護或讓步——交付物在其最終訊息中，不觸碰任何檔案。

授權模型

委派是人類選擇加入的事情。一旦他們選擇了（「執行這個佇列」、「繼續」），提交已驗證且通過 gate 的工作就是約定的契約。仍有兩個限制：呈現，不要吸收（回報 Cursor 的設計決策、可辯護但未要求的方向，以及非阻塞性的小問題）和遇到範圍變更時停止（如果正確完成需要超出簡報範圍，請詢問而不是擴大授權）。請參閱 references/review-and-land.md。

參考資料

• references/writing-the-brief.md — 結構、報告契約、實際 gate 和 delta 簡報。
• references/dispatch-and-poll.md — 旗標、產出、result.json、輪詢和失敗恢復。
• references/review-and-land.md — 審查清單、commit 邊界，以及透過 Cursor sessions 重做。
• references/multi-task-queues.md — 順序佇列、約束延續、進度追蹤和最終一致性檢查。