升級依賴並跑完整測試

run_command 的 120 秒上限，在日常修復夠用，但遇到「裝依賴要三分鐘、測試套件要十分鐘」的升級任務就徹底不夠用。這篇範例示範 CatDesk 處理長任務的三件套：start_command 起工、poll_command 用 cursor 一段段收輸出、出事時 cancel_command 連子程序整棵砍掉。

情境

order-service 用的 HTTP client 套件出了一個大版本。你需要升級到最新版，並確認全套測試（共 214 個案例，歷史紀錄要跑八分鐘以上）全綠才能合併。壞訊息是：團隊以前遇過升級後測試卡死在連線重試的狀況。

目標

完成升級、跑完整套測試；如果測試卡住，把卡住的程序乾淨地收掉並回報，而不是掛在終端機裡占資源。

步驟：給 ChatGPT 的 prompt

Upgrade @corp/http-client to the latest major version:

1. Update package.json, then run npm install as a background job.
2. Poll until install finishes. Show me any peer dependency
   warnings from the output.
3. Then run the full test suite as another background job.
4. Poll incrementally. If no new output arrives for a long time
   while the job is still running, cancel it and tell me exactly
   where it hung.
Do not use run_command for the install or the test suite; both
exceed the 120-second cap.

CatDesk 工具呼叫序列

1. catdesk_instruction
2. edit(path: "package.json", ...)        // bump the version
3. start_command(command: "npm install")
   -> jobId: "job_a1", cursor: c0
4. poll_command(jobId: "job_a1", cursor: c0)  // repeat until done
5. start_command(command: "npm test")
   -> jobId: "job_b7", cursor: c0
6. poll_command(jobId: "job_b7", cursor: c1)
7. poll_command(jobId: "job_b7", cursor: c2)
   -> hasMoreOutput: true, status: still running, 3/214 tests
8. cancel_command(jobId: "job_b7")        // detected a hang
9. run_command(command: "git diff --stat package.json")

排空（drain）與取消，兩個關鍵細節

cursor 排空：poll_command 的每次回應有大小上限。如果 hasMoreOutput 是 true，代表緩衝區裡還有沒交完的輸出，即使指令已經到達結束狀態，也要帶著 nextCursor 繼續輪詢直到排空，否則會漏看最後幾百行的錯誤堆疊。第 6、7 步就是在做這件事。

整棵取消：第 7 步之後輸出停滯、狀態卻還在 running，符合你 prompt 裡定義的「卡死」。cancel_command 不只砍掉 npm test 本身，而是停止它與它的整棵子程序樹（child process tree），不會留下孤兒程序繼續占著 CPU 和 port。

結果與重點

測試卡在對新版本 client 的重試迴圈。ChatGPT 取消工作後回報：卡死點是 retryLoop() 對新版本預設逾時的誤判，建議在升級時一併把 retry 上限設成有限值。修正後重新用 start_command 跑測試，這次十分鐘內全綠。

三個重點帶走：

安裝、建置、完整測試套件、開發伺服器，一律走 start_command 加 poll_command，這是 README 點名的四類長工。
hasMoreOutput 為 true 就繼續用 nextCursor 排空，指令結束後也一樣，這是看全輸出的鐵律。
cancel_command 砍的是整棵子程序樹，處理卡死任務時放心用它，不會留屍體。