工作一轉到自動執行就看不到計劃與審批，改用整合協定又要自行處理會話與錯誤。

最快的選法是：日常互動與人工審批用 Web；一次性、腳本及 CI 任務用 Headless；只有在上層工具需要建立和管理 Agent 會話時，才評估 ACP。截至 2026 年 8 月 18 日，DeepSeek Harness 仍屬開發者預覽，命令、參數與相容性可能變更，正式採用前應重新核對官方文件。(官方專案 README)

這篇文章適合三類讀者：獨立開發者要找最省維護的日常入口；自動化工程師要把任務變成可重複命令；平台或工具開發者則需要評估 ACP 整合、權限映射與多入口治理成本。

最後更新於 2026 年 8 月 18 日，資料核實自官方 README、使用指南、CLI 文件、Python SDK 指南及架構文件；由於專案仍在預覽期，部署前應逐項執行當日版本的官方示例。(官方使用指南)

先按責任範圍決定主入口

DeepSeek Harness Web 和 Headless 的核心差異，不是模型突然變強或變弱，而是「誰負責觀察與確認」。Web 將工作計劃、工具呼叫、檔案修改與需要核准的操作放在可見介面中；官方指南也明確指出，Web UI 會按照當前權限政策，在執行部分操作前要求確認。

Headless 則把一次任務包裝成命令：輸入任務後輸出最後結果並結束，適合由腳本、排程器或 CI 工作流程接手。官方 CLI 文件提供 dsh --profile headless "job" 形式，並說明啟動目錄會作為預設工作區。(官方 CLI 文件)

ACP 的責任邊界再往上移。它不是單純把 Web UI 隱藏起來，而是讓編輯器或上層 Agent 系統建立會話、傳送任務、接收更新，並處理取消、權限請求與生命週期。相關協定文件把會話更新、工具呼叫與權限請求視為需要客戶端處理的事件，因此整合成本通常高於直接執行命令。(ACP 客戶端連線文件)

三種模式各自對應的主責任如下：

  • Web：人負責判斷計劃是否合理，系統負責呈現過程。
  • Headless：腳本負責提供輸入、保存日誌、判定成功與重試。
  • ACP：上層客戶端負責會話管理、事件消費、權限映射與錯誤傳遞。

因此，偶爾才執行一次的任務，不值得一開始便建造完整 ACP 入口；而涉及檔案寫入、套件更新或資料庫變更的工作，也不應因為 Headless 沒有畫面就自動視為安全。

先看個人開發者的日常互動需求

日常寫程式時，若任務需要反覆修正方向，Web 通常是較穩妥的起點。官方 Web 指南要求先選擇工作區，之後才能建立工作階段；模型設定儲存後，下一個請求即可使用，不必重新啟動服務。

這種入口適合以下工作：

  • 先閱讀專案，再決定是否修改檔案；
  • 觀察 Agent 如何拆解計劃與呼叫工具；
  • 在刪除、寫入或執行高風險命令前保留人工審批；
  • 需要看到差異、錯誤訊息和中途產物；
  • 任務目標仍可能改變，尚未適合固定成腳本。

需要注意的是，可見介面只增加可觀察性，不代表模型能力天然更高。Web 的真正價值是讓人能在錯誤擴大前介入，而不是替代測試、版本控制或部署門禁。

日常寫程式應選哪種運行模式？
如果工作是「讀取專案、提出修改、等待確認、再繼續」，先選 Web；如果工作是「固定輸入、固定檢查、固定產物」，才把它移到 Headless。個人開發者可以先用 Web 穩定任務流程，連續幾次都能用同一輸入與驗收條件完成後，再抽取成命令。

官方目前的 Web 啟動方式是 npx @deepseek-ai/dsh web，預設服務於本機 127.0.0.1:3080；這些命令與預設行為屬於預覽版本的一部分，升級後應重新驗證。(官方 Web 與啟動說明)

再按可重複性拆解 Headless 責任

DeepSeek Harness 能不能在腳本裡呼叫？
可以，官方提供 Headless profile，也提供 Python SDK 作為程式化入口。CLI 可執行一次任務後輸出最終回覆並離開；Python 示例則以工作區、工作階段根目錄及工作階段 ID 執行任務，並把模型請求與工具呼叫寫入 JSONL 日誌。(官方 Python SDK 指南)

不過，Headless 並不是「沒有畫面，所以不需要治理」。腳本維護者至少要自行處理四件事：

  1. 參數邊界：任務內容、工作區路徑與模型選項應分開傳入，避免把未驗證的外部字串直接拼進命令。
  2. 秘密管理：API 金鑰應放在環境變數或受保護的設定中，不能寫入版本庫；官方開發指南使用 DEEPSEEK_API_KEY，並提醒不要提交真實憑證。
  3. 結果判定：不能只看程式是否啟動成功，還要檢查退出狀態、預期檔案、測試結果或結構化產物。
  4. 失敗恢復：要決定哪些錯誤可以重試、哪些錯誤必須停止，以及重試會否重複寫入或覆蓋檔案。

Python SDK 指南還列出一個示例組合的具體限制，包括 300 秒 Bash 逾時、16,000 個字元的編輯器輸出上限，以及未壓縮的 JSONL 工作階段保存方式。這些數值是該示例組合的行為，不應被誤當成所有 profile 的永久預設值。(官方 Python SDK 指南)

注意：高風險寫入即使改成 Headless，也應保留外部審批、測試分支、沙盒或合併門禁；退出狀態只能表示命令流程結束，不能單獨證明修改內容正確。

Headless 特別適合：

  • 每次都以同一格式輸入的程式碼檢查；
  • 可由測試命令驗證的重構；
  • 夜間排程、CI 觸發的一次性任務；
  • 只產生報告、不直接寫入正式環境的流程；
  • 需要保存完整命令輸出與工作階段記錄的批次工作。

若任務需要中途問人「是否刪除這批檔案」，Headless 就不是完整方案，除非外部系統先把審批結果轉成明確的輸入狀態。

用一張表分開三種運行責任

評估項目 Web Headless ACP
最適合的使用者 個人開發者、需要人工觀察的人員 自動化工程師、CI 維護者 編輯器、平台及上層 Agent 開發者
啟動方式 dsh web 或 Web profile dsh --profile headless "job" 官方 ACP automation 示例或相容客戶端
人工介入 直接可見，適合逐步審批 預設由外部流程處理 由客戶端接收權限事件並決定
主要產物 互動工作階段、檔案差異、操作紀錄 最終輸出、退出狀態、腳本日誌 會話事件、結構化更新、錯誤與生命週期狀態
維護責任 工作區、模型設定、遠端連線與權限 參數、環境變數、日誌、重試與門禁 相容性、會話建立、取消、錯誤傳播與權限映射
不宜直接使用的情況 完全無人值守的高頻批次 需要即時人工判斷的破壞性操作 既有 Web 或命令流程已穩定，卻沒有明確整合需求

表中的命令與入口來自官方目前的 README、CLI 文件及開發示例；ACP 的會話與權限責任則按照協定客戶端文件理解，不能把不同版本的 ACP 實作視為完全相同。

只有在上層工具需要會話時才導入 ACP

什麼情況需要使用 ACP 模式？
當編輯器、內部平台或另一個 Agent 系統需要自行建立工作階段、傳送多輪任務、顯示工具進度、接收權限要求，或在中途取消與恢復工作時，ACP 才有清晰價值。官方開發指南把 ACP automation server 描述為透過 JSON-RPC over stdio 提供新的 Agent 工作階段，並以 pnpm run demo:acp 啟動示例。(官方開發指南)

導入前應先驗證：

  • 客戶端是否真的支援 DeepSeek Harness 使用的 ACP 版本與傳輸方式；
  • new session、訊息發送、工具更新、取消及關閉是否能完整走通；
  • 權限請求能否映射到客戶端的核准、拒絕與取消狀態；
  • Agent 錯誤、進程退出和無效輸入能否傳回上層，而不是只剩一個逾時；
  • 會話 ID、工作區、環境變數及日誌是否能在重連後保持一致。

ACP 的靈活性會把原本由 Web UI 承擔的工作轉移到整合者身上。若只是想從腳本啟動任務，Headless 更直接；若只是需要人查看過程，Web 更容易排查。不要只因為 ACP 聽起來更標準，就替換已經穩定的入口。

小型團隊應統一配置，不必統一畫面

團隊可以同時使用 Web 和自動化入口，也可以讓工具開發者試用 ACP，但以下設定應集中管理：

  • 模型路由、API 端點及版本鎖定；
  • 工作區邊界、檔案權限與可用工具；
  • 外掛版本、profile 組成及升級時間；
  • 日誌格式、保存位置與敏感資料遮罩；
  • 成功驗收、回滾條件與人工審批門檻。

相反，以下偏好可以保留給個人：

  • Web 的介面習慣；
  • 是否先建立計劃再執行；
  • 日常任務使用互動模式或短命令；
  • 編輯器中的通知方式與檢視位置。

這樣做的目標不是讓每個人看到完全相同的畫面，而是確保同一任務不會因入口不同，就失去審計、回滾或責任追蹤證據。官方採用 profile 與插件組合的架構，並允許 Web、Headless 及 ACP 由不同啟動方式載入；因此團隊更應把共同政策放在配置與驗收層，而不是靠口頭規定。(官方架構文件)

以同一基準任務完成五步驗證

不要用功能打勾表直接決定入口，應讓三種模式執行同一個低風險任務，例如「讀取測試專案、找出失敗測試、產生修復建議，但不得修改正式分支」。可按以下步驟操作：

  1. 固定任務輸入：鎖定相同工作區、相同模型、相同權限及相同提示內容。
  2. 先跑 Web：記錄啟動、選擇工作區、查看計劃、人工介入及取得差異所需的步驟。
  3. 再跑 Headless：把同一任務放入命令或腳本，保存標準輸出、錯誤輸出、退出狀態及產物。
  4. 最後跑 ACP：由測試客戶端建立新會話，檢查任務事件、工具更新、權限要求、取消及錯誤傳遞。
  5. 故意中斷一次：停止進程或切斷連線，再比較哪個入口最容易恢復，並確認是否會重複寫入。
  6. 寫成三行決策：指定主入口、備用入口，以及明確禁止使用的場景。

驗收時至少勾選：

  • [ ] 任務輸入可被版本控制或保存，下一次能重現；
  • [ ] 工作區和模型設定在三種入口中一致；
  • [ ] 高風險工具有外部審批或測試門禁；
  • [ ] 日誌包含足夠的任務、工具與錯誤上下文；
  • [ ] 失敗後能判斷重試是否安全；
  • [ ] 中斷後可找到工作階段、產物及最後狀態；
  • [ ] 升級後已重新執行 Web、Headless 及 ACP 的最小示例；
  • [ ] 文件已寫明主入口、備用入口及禁止場景。

平台團隊還要額外考慮進程托管、遠端訪問、並發工作階段、健康檢查、資源上限及版本回滾。官方開發文件列出目前 CI 覆蓋的 Node.js 22.19、24 及 26，並要求生產執行先完成建置；這說明升級驗證不能只測 API 是否能回應，還要確認編譯產物、profile 與客戶端整合仍可運作。(官方開發與 CI 文件)

把結論落到主入口與備用入口

對獨立開發者，建議以 Web 作主入口，Headless 作為少量重複任務的備用入口；尚未有編輯器或平台整合需求時，不必先維護 ACP。

對自動化工程師，應以 Headless 作主入口，但先建立輸入驗證、工作區隔離、日誌保存、退出狀態判定與失敗重試規則；需要人工審批的寫入工作，則回退到 Web 或外部審批流程。

對工具開發者及平台負責人，只有當上層系統需要統一建立會話、接收結構化事件與映射權限時，ACP 才適合作為主入口。開發者預覽期應採用可回滾的雙軌試點：原有 Web 或 Headless 保持可用，ACP 先在隔離工作區驗證，而不是一次過替換整條工具鏈。

如果目前方案只是把 DeepSeek Harness 長時間跑在個人電腦上，通常會遇到本機需要持續開機、遠端連線與權限設定分散、多人共享工作區不易隔離等問題；Windows 或 Linux 主機也可能因環境差異、套件版本與進程托管方式而增加排查成本。對需要臨時算力、短期測試或遠端驗收的情況，租用一個預先準備好的 Mac 環境，通常比臨時改造現有主機更容易控制工作區、連線與回滾責任。RUVCLOUD 可先從繁體中文服務入口了解遠端 Mac 使用方式，再按測試週期評估對應的 Mac 方案；但若是長期固定重負載、需要實體介面，或已有成熟本地機房治理，直接自購與自管 Mac 仍可能更合適。