cursor-collab

不依賴 UI 的 Codex → Cursor Agent 多 Agent CLI（npm 套件名與命令皆為 cursor-collab）。 每次呼叫都必須用絕對路徑 --workspace 指向目標專案。以 work/runs/ 下的精簡 summary／handoff 為準；完整 stdout／stderr 僅供診斷，不要貼進協調對話。

安裝

npm install -g cursor-collab
# 或：npx cursor-collab --help

需要 Node.js 20 以上，以及本機已安裝並登入的 Cursor Agent CLI。

前置

cursor-agent status

Windows 上 orchestrator 用 where.exe 找 cursor-agent。標準 Cursor Agent 安裝會直接解析最新且完整的 node.exe + index.js，跳過更新中留下的 incomplete version，避免 PowerShell 5.1 重新解析含 JSON 雙引號／換行的 prompt；自訂命令則優先 .ps1、再看 .cmd／.bat sibling .ps1，可辨識的 Node forwarder 會直接呼叫 Node，否則才 fallback 到 wrapper。若解析不對，用環境變數 CURSOR_AGENT_COMMAND 覆寫；自訂 wrapper 上線前要用含引號／換行的 prompt 做回歸測試，不要假設某種 shim 一定被選中；CURSOR_AGENT_COMMAND 覆寫值必須是絕對路徑。

運算子必對的旗標

| 旗標 | 語意 | |------|------| | --workspace <abs-path> | 必要。 一律傳絕對路徑到目標 Git root（或 staging copy）。不要依賴目前工作目錄。 | | --trust | plan／run／workflow 都要帶。 子程序非互動，無法回答 workspace trust 提示。 | | --force | 與 --trust 分開。授權非互動的命令與檔案修改；寫入型 run 使用，唯讀 plan／ask 預設不加。不能取代 --trust。 | | --timeout-ms <n> | 每個 child 的逾時上限，預設 1,800,000 ms；範圍為 0–2,147,483,647，0 僅在明確需要無限等待時停用。 | | --allow-dirty-integration | 明確允許整合 Agent 在已有未提交變更的 Git workspace 寫入。 | | --inherit-env | 傳入完整父程序環境。預設過濾（見下）通常已足夠。 |

--trust／--force 只能在 CLI 設定，task manifest 無法偷渡。寫入型 task 強制 worktree；plan／ask 為唯讀、不建 worktree，且不會收到 --force。 CLI 會拒絕未知或重複旗標、錯誤 command 的旗標、缺少值的參數，以及把開關寫成 --force true 這類帶值形式，避免拼錯 --parallel 後意外啟動全部 workers。

預設環境過濾

未加 --inherit-env 時，子程序只收到小型 runtime/config allowlist（PATH／Path、 Windows runtime 目錄、temp/home 基本變數、locale、NO_COLOR，以及指定的 CURSOR_* 設定）。CURSOR_API_KEY 等憑證不會預設傳給 worker；不要假設任意父程序 變數會傳入。需要完整父環境時才用 --inherit-env，並先確認不會把機密帶給 worker。

快速開始

cursor-collab workflow `
  --workspace "C:\github\my-project" `
  --goal "Implement login, tests, and API docs" `
  --parallel 3 `
  --trust `
  --force

流程：

1. planner（唯讀）在 run directory 寫出 tasks.json。
2. workers 平行執行；省略 --parallel 時會同時啟動所有 tasks。寫入型 task 使用獨立 worktree。
3. 除非 --no-integrate，integration Agent 會被要求審查成功 worktree、謹慎合併， 並跑專案相關檢查。Orchestrator 記錄 Agent 結果，不會自行再驗一次那些檢查。

只有互相獨立且寫入範圍不重疊的 tasks 才放在同一輪平行執行。有依賴的修改放進單一 task，或在前一輪整合完成後再啟動下一輪；--parallel 1 只會降低同時執行數，不會把 前一個隔離 worktree 的修改交給下一個 worker。manifest 的 dependsOn、dependencies、 after、requires 會直接報錯，避免依賴被靜默忽略。

每台 Cursor 電腦預設最多保留 25 個 managed worktree；設定大量寫入 tasks 時要計入其他 repo 的既有 worktree、API 與機器容量。詳見 Cursor Worktrees 文件。

分階段

只規劃：

cursor-collab plan `
  --workspace "C:\github\my-project" `
  --goal-file .\goal.txt `
  --trust

執行既有 manifest：

cursor-collab run `
  --workspace "C:\github\my-project" `
  --tasks .\tasks.json `
  --parallel 3 `
  --trust `
  --force

ChatGPT／Codex 已拆好任務時，優先 run，讀精簡摘要而非 raw log。目標專案不必把 本套件加進 monorepo 或跨專案 import。

在另一台電腦啟用

每台電腦都要分別安裝並登入 Cursor Agent CLI，再安裝本套件：

npm install -g cursor-collab
Get-Command cursor-collab
cursor-collab --help
cursor-agent status

本機開發此 repo 時可用 npm link 或 npm install -g . 指向工作副本。

run --integrate

cursor-collab run `
  --workspace "C:\github\my-project" `
  --tasks "C:\path\to\tasks.json" `
  --parallel 3 `
  --trust `
  --force `
  --integrate `
  --goal "Integrate successful workers and run relevant checks"

行為：

• workers 階段一律寫入 summary.json 與 codex-handoff.json（kind: "run"）。
• 加上 --integrate（且必須有 --goal 或 --goal-file）後再跑 integration Agent （目標、Git 狀態與乾淨工作目錄會在 workers 啟動前檢查；workers 執行期間若主目錄 出現新變更，會阻止 integration 並記錄 blocked，不另啟 Agent。需要在髒目錄整合時， 先檢查 diff 再明確加上 --allow-dirty-integration；這會略過保護檢查）。
• integrate 結束後，orchestrator 會一致改寫 summary.json 與 codex-handoff.json（寫入 integration），並另寫 workflow-summary.json。 成功整合時 handoff kind 為 "workflow"。合併狀態可從這三個檔（與 stdout）讀取。

workflow 若要跳過整合，使用 --no-integrate。

多小任務迴圈：continue 與 integrate

適合「很多小任務 → 失敗／特例再下新指令 → 成功線先整合 → 回 Codex」：

# 1) 第一輪：多小任務（通常先不 integrate）
cursor-collab run `
  --workspace "C:\github\my-project" `
  --tasks .\many-small.json `
  --parallel 4 `
  --trust `
  --force

# 2) 讀 work/runs/<id>/summary.json 與 codex-handoff.json（不要貼 stdout）

# 3) 失敗或特例：接續（預設重跑 failed|blocked；可用 --ids 指定）
cursor-collab continue `
  --workspace "C:\github\my-project" `
  --from-run ".\work\runs\<run-id>" `
  --instruction "依 blockers 補測後重試；勿擴大範圍" `
  --trust --force

# 4) 成功線先整合（不重跑工人；省略 --ids＝該 run 內 ok 的 tasks）
cursor-collab integrate `
  --workspace "C:\github\my-project" `
  --from-run ".\work\runs\<含成功寫入的 run>" `
  --goal "合併成功 worktree，跑相關檢查，回 compact handoff" `
  --trust --force

• continue 會寫新的 run directory、continue-manifest.json、tasks.json；handoff kind 為 "continue"，並記錄 fromRun。寫入 task 沿用同一 id／worktree 名。
• integrate 只開 integration Agent，handoff kind 為 "integrate"；沒有成功 task 時為 blocked。
• 狀態在檔案 handoff，不是 Cursor 討論串 resume。多輪 continue 後，對最後一輪含成功寫入的 run做 integrate，或以 --ids 明示。

Task manifest

未指定 mode → 寫入／agent task，且 worktree: true。plan／ask → 唯讀、無 worktree。

{
  "tasks": [
    {
      "id": "api",
      "prompt": "Implement the API endpoint and tests. Report paths and verification.",
      "worktree": true
    },
    {
      "id": "audit",
      "mode": "plan",
      "prompt": "Read-only: list API risks and concrete recommendations."
    }
  ]
}

每 task 產物：work/runs/<run-id>/<task-id>/（handoff.json、result.json、 stdout.ndjson、stderr.log）。

task id 和 worktree name 必須是單一路徑名稱；不接受 .、..、路徑分隔符、Windows 保留名稱或句點結尾。ID 大小寫不同仍視為重複。未知 mode 與依賴欄位會報錯，不會靜默 降級成可寫入 task。

真相來源 vs 診斷用 log

預設 run directory 是呼叫端目前目錄下的 work/runs/<run-id>；run id 含時間、PID 與 隨機尾碼以避免同一毫秒建立目錄衝突。可用 --run-directory 指定新路徑；目錄必須尚未 存在，避免覆寫上一次 run 的 summary、handoff 或 task log。

| 產物 | 用途 | |------|------| | summary.json | run 精簡狀態；--integrate 後會改寫並含 integration | | workflow-summary.json | workflow 結果，或 run --integrate 合併狀態 | | codex-handoff.json | 給協調端的彙總 compact handoff（--integrate 後一併改寫） | | <task-id>/handoff.json | 單一 task 的 compact JSON handoff | | stdout.ndjson／stderr.log | 僅診斷——失敗時再開，勿貼進協調對話 |

健康路徑：讀 summary／handoff 的 ok、路徑、verification、blockers。完整 transcript 不是運算子契約。

stdout／stderr 會串流保存到完整 log。摘要最多擷取每條 stream 1,000,000 個字元； stdoutTruncated 或 stderrTruncated 表示摘要有截斷，完整內容仍在 task log。planner 原始 stdout 超過 1,000,000 bytes 會失敗，避免從不完整回應建立 tasks。 worker／integration 缺少有效 JSON handoff 時一律視為失敗。

已知限制

• 寫入隔離需要 Git。 任一 task 帶 worktree 時，目標必須是 Git workspace。 workflow 預設整合及 run --integrate 也需要 Git，且會先檢查；整合預設要求乾淨的 tracked／untracked 工作目錄，並在 workers 結束後再檢查一次。純唯讀且不整合的 run 可不要求 Git。
• 非 Git 目標： 不要為了委派而在使用者真實目錄 git init。若變更可忠實搬回， 用暫時的 Git staging copy 執行，再審查並拷回；否則該片段留在協調端處理。
• worktree 建立／命名由 Cursor Agent CLI 管理；integration prompt 會要求檢查 git worktree list 與路徑。
• 自動合併品質取決於 integration Agent；寫入後請檢查 summary.json、 codex-handoff.json、workflow-summary.json（--integrate／workflow 後應一致） 與主 workspace diff。
• Windows 以 argv 陣列 spawn（shell: false）；標準 Cursor 安裝優先直接呼叫完整 node.exe／index.js，自訂 .ps1／.cmd／.bat 才依 wrapper fallback。若 fallback wrapper 會自行用 PowerShell 5.1 或 %* 再轉交 argv，含 JSON 雙引號／換行 的 prompt 仍可能被拆解；請改用可辨識的 direct Node entry 或先通過對應回歸測試。