DeepSeek Harness AI Agent 開發指南

這是一篇面向個人開發者、AI 工程師與小型團隊的落地教學。文章以時間軸組織實作流程，從準備環境、跑通最小 Agent 閉環，到接入工具、拆分長任務及部署驗收，協助讀者判斷何時適合留在本地，何時應轉移到可重置的雲端算力環境。

判斷：適合先用最小任務閉環開始，不適合一開始就堆疊多 Agent、記憶與大量插件。 先驗證模型適配器、工具註冊、會話狀態與終止條件，再逐步擴展；若需要長時間執行、環境隔離或多人共享，則應轉移到可重複交付的雲端算力環境。

這篇適合首次接觸 DeepSeek Harness、需要在第一個小時內跑通示例的 AI 開發者，也適合準備把本地原型遷移至持續執行環境的研發團隊。若您負責驗收工具呼叫可靠性與任務完成率，本文的測試順序也可直接用作初版驗收表。

最後更新於 2026 年 8 月 17 日；資料核實自官方 DeepSeek Harness 倉庫、README、安裝文件、最新提交狀態與 API 文件。截至覆核時，官方資料能確認的是 DeepSeek API 的模型介面、函式呼叫、工具參數模式與結果回傳。2026 年 9 月官方倉庫 deepseek-ai/deepseek-harness 與 CLI dsh 已公開；要裝官方執行階段、跑 Web / headless，請改讀 DeepSeek Harness dsh 安裝教學。本文仍只講自建迴圈與工具驗收，不替代官方 CLI 文件。

開始前先劃定任務邊界

DeepSeek Harness 目前仍是 developer preview，官方 README 明確提醒可能出現相容性破壞變更。官方倉庫採用「Everything is a Plugin」架構，並以 Cordis 作為底層設計的一部分。這代表它適合研究插件組合與 Agent 執行流程，但不應被當成介面已完全穩定的成熟平台。可先閱讀官方倉庫 README 與目前執行方式再決定是否投入正式專案。(github.com)

我們建議先把任務寫成四欄：

• 輸入：例如一個 Git issue、單一資料夾或一份待整理的文字。
• 工具：第一輪只保留一個低風險工具，例如讀取檔案或執行測試。
• 輸出：明確指定要產生的檔案、摘要或結構化結果。
• 終止條件：工具成功回傳、輸出通過格式驗證，或遇到需要人工確認的狀態。

不要把「建立一個能處理所有工作的通用助手」當成第一個任務。無限循環、上下文膨脹、重複執行與權限失控，通常不是模型單一問題，而是任務邊界沒有先定義。

第一個小時的最小閉環

官方 README 提供兩條主要路徑。從 npm 執行時，需要先準備 Node.js，再使用 npx @deepseek-ai/dsh web 啟動 Web UI；預設服務位址是 http://127.0.0.1:3080。若從原始碼執行，官方步驟是複製倉庫、執行 pnpm install、建立專案及啟動 pnpm dsh web。(github.com)

第一輪不要急著修改插件。先確認四個角色各自正常：

1. 模型適配器：負責把 Agent 請求送到模型介面，並接收文字或工具呼叫結果。
2. Agent Loop：根據模型回覆判斷下一步是繼續思考、呼叫工具，還是結束任務。
3. 訊息歷史：保存使用者指令、模型回覆、工具呼叫與工具結果。
4. 任務入口：負責接收任務、建立工作上下文，並在完成或失敗時回報狀態。

最小測試可以是「讀取指定檔案並回傳檔案大小」。這個任務沒有寫入副作用，卻能驗證完整鏈路：

使用者輸入
→ Agent 產生工具呼叫
→ 執行器驗證參數
→ 工具回傳結果
→ 結果寫回訊息歷史
→ Agent 判斷完成

若模型能產生呼叫，但工具結果沒有寫回歷史，流程並未完成。若工具成功執行，Agent 卻持續重試，問題通常出在結果格式或終止條件，而不是「模型不夠聰明」。

DeepSeek Harness 如何建立第一個 AI Agent

第一個 AI Agent 不應以介面是否漂亮作為成功標準，而應以能否重現一次完整任務作為標準。建立時可按以下順序操作：

1. 準備隔離的專案目錄，不要直接把家目錄或正式程式碼庫交給 Agent。
2. 依官方 README 選擇 npm 或原始碼方式啟動，並記錄當日的提交版本。官方目前沒有可供依賴的正式 Release 頁面，因此更需要自行鎖定提交狀態。(github.com)
3. 設定模型介面與密鑰。密鑰只放在環境變數或密鑰管理服務，不要寫入提示詞、日誌或 Git。
4. 建立只有一個工具的測試任務，要求輸出固定格式。
5. 保存每次任務的輸入、模型回覆、工具結果、錯誤訊息與結束原因。
6. 連續重跑相同任務，確認成功與失敗都能被辨識，而不是只截取一次成功畫面。

這個順序能把「環境問題」、「模型問題」、「工具問題」與「狀態問題」分開。否則一開始加入檔案編輯、Shell、瀏覽器及子 Agent，任何一個環節出錯，都很難定位。

工具呼叫的註冊與回傳

DeepSeek API 的工具呼叫目前以 function tool 為主。工具需要提供名稱、用途說明與 JSON Schema 參數；官方文件也指出，模型本身不會直接執行函式，實際執行仍由您的程式負責。(api-docs.deepseek.com)

工具描述會直接影響模型決策。以下四點不可省略：

• 名稱要能表達動作：例如 read_file 比 helper 更容易被正確選用。
• 參數要限制範圍：路徑、檔案類型、數值上限都應寫進 Schema 或執行器。
• 權限要在工具層驗證：提示詞寫著「只能讀取」不等於作業系統真的禁止寫入。
• 錯誤要結構化回傳：區分參數錯誤、權限拒絕、檔案不存在、逾時與工具內部失敗。

官方 API 目前列出的工具函式上限是 128 個；但「可以註冊」不等於「適合一次提供」。工具數量過多會增加選擇干擾，也會讓排查變得困難。(api-docs.deepseek.com)

經驗提醒： 每次工具呼叫至少保存工具名稱、原始參數、驗證後參數、開始與結束時間、輸出摘要及失敗原因。不要只保存最後一段自然語言答案，否則出錯後沒有足夠證據重建現場。

工具與方案的取捨

評分不是框架效能測試，而是我們用來判斷落地風險的簡化工具。第一階段分數最高，因為變數最少；進入多人共享後，真正困難的部分往往變成權限、狀態與資源管理。

長任務的狀態管理

Agent 執行任務時保存狀態，不能只把所有歷史訊息不斷塞回上下文。至少要分成三層：

• 短期會話狀態：目前對話、最近一次工具呼叫、等待中的人工確認。
• 任務產物：修改後的檔案、測試報告、差異檔與結構化結果。
• 長期知識：專案規範、工具使用說明、固定決策規則。

長任務應拆成可檢查階段，例如：

分析需求 → 讀取檔案 → 產生修改計畫 → 人工確認
→ 執行修改 → 執行測試 → 保存報告 → 結束

每個階段都要定義：

• 成功條件；
• 可重試的錯誤；
• 必須暫停的錯誤；
• 是否允許人工確認；
• 恢復時從哪一個產物繼續。

例如測試命令失敗可以重試一次，但權限拒絕不應讓 Agent 無限重試。這也是 AI Agent 與普通聊天機器人的差異：任務需要可恢復，而不是只追求一次回答看起來合理。

本地原型到持續執行環境

當 DeepSeek Harness 只由一位開發者短時間測試時，本地 Mac 通常已足夠。可是出現以下任一情況，就應評估遠端、可重置的獨立環境：

• 任務需要長時間執行，不能依賴個人電腦持續開機；
• Agent 需要執行 Shell、編譯或測試，必須與日常工作環境隔離；
• 多人需要共享同一套依賴、工作目錄與日誌；
• 任務失敗後需要快速還原乾淨環境；
• 需要從遠端連線查看執行中的 Agent。

部署時至少完成五項準備：

1. 鎖定 Node.js、套件管理器、依賴與 DeepSeek Harness 的提交版本。
2. 以環境變數或密鑰服務注入 API 金鑰，禁止寫入程式碼庫。
3. 為每個任務建立獨立工作目錄，限制可讀寫路徑。
4. 將事件日誌持久化，至少保留任務 ID、工具呼叫與錯誤原因。
5. 設定並發數、單任務逾時、重試次數與磁碟使用上限。

如果團隊打算在 Mac 上執行編碼 Agent，還要確認遠端連線、工作目錄及重置方式；可先參考Mac 遠端使用與環境管理說明。需要多人共享時，也應先了解ZekVPS 的服務範圍與使用條件，避免把開發測試環境誤當成沒有邊界的正式生產環境。

部署驗收與決策條件

不要用一次成功示範判斷 Agent 已經可以上線。至少準備一組真實任務集，檢查以下項目：

• 任務是否在明確條件下正常結束；
• 工具名稱與參數是否符合預期；
• 工具失敗後是否能分類並採取正確策略；
• 任務中斷後是否能由產物恢復；
• 相同輸入重跑時，結果是否維持可接受的一致性；
• 日誌是否足以重建一次失敗；
• CPU、記憶體、儲存空間及 API 使用量是否受控。

可以按以下條件作決定：

• 若只測試單一工具、執行時間短、沒有共享需求，選本地環境，先完成最小閉環。
• 若需要加入檔案修改或 Shell 工具，選隔離工作區，並先加入權限與逾時限制。
• 若任務會跨越多個階段，或需要中斷後恢復，選可持久化日誌與產物的遠端環境。
• 若多人共用、需要長時間運行或頻繁重置，選可遠端存取、可重建的獨立算力環境；不要繼續依賴某位開發者的本地電腦。
• 若需要實體 USB、特殊硬體或長期固定滿載運算，先確認租用方案是否符合條件；不符合時，自購設備或專用伺服器可能更合適。

以目前官方資料看，DeepSeek Harness 適合拿來建立與驗證 Agent 執行流程，但仍處於快速迭代階段。官方倉庫已提供 npm 啟動、原始碼建置、插件主題與架構文件入口；至於社群插件、未合併功能及第三方封裝，應一律視為社群實作或待驗證能力，不要直接當成穩定介面。(github.com)

如果現在把 Agent 放在個人電腦上長時間執行，常見缺點是工作目錄與日常檔案混在一起、電腦休眠或關機會中斷任務，以及多人接手時無法重現相同依賴。完成最小閉環後，若您的任務確實需要持續執行、隔離或遠端接手，租用 ZekVPS 的 Mac 環境會比臨時改造個人電腦更容易重置與交付；但若只是短時間單機測試，留在本地反而更簡單。您也可以先從ZekVPS 的 Mac 環境選擇頁開始比較，再依任務時長、並發量與隔離要求決定是否遷移。