DeepSeek Harness 開發環境與貢獻指南

想從原始碼開發 DeepSeek Harness，需要先備妥受支援的 Node.js、Corepack、pnpm 與 Git。官方目前要求 Node.js 22.19 以上，也支援 Node.js 24；CI 測試矩陣涵蓋 22.19、24 與 26。這篇教學不逐句搬運官方文件，而是依照「安裝、檢查、建置、試跑、送出變更」的實際流程重新整理。

本文依據 DeepSeek Harness 官方中文開發文件 改寫。專案仍在 Developer Preview 階段，準備貢獻程式碼前，請再次查看官方原文。

開發 DeepSeek Harness 要準備哪些工具

建議先安裝：

• Node.js 22.19 以上，日常開發可選 Node.js 24；
• Corepack，用來啟用專案指定的套件管理器版本；
• Git 2.26 以上；
• 只有試跑 Agent 展示功能時，才需要模型供應商 API 金鑰。

先確認本機版本：

node --version
corepack --version
git --version

儲存庫鎖定 pnpm@11.7.0。建議交給 Corepack 按照專案宣告啟用，不要任意混用另一套全域 pnpm，否則容易產生無關的 lockfile 差異，甚至出現本機通過、CI 失敗的情況。

Clone 儲存庫並安裝相依套件

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
corepack enable
pnpm install

pnpm install 後的 postinstall 還會設定 Lefthook，以及翻譯檔案所需的 Git merge driver。套件下載完成後，接著執行：

pnpm run typecheck

若全新 Clone 的工作區在這裡失敗，先比對 Node.js 與 pnpm 版本，不要急著修改產生檔或 lockfile 來掩蓋問題。工具鏈不相容通常是第一個該排除的原因。

Host、Client、Web 為何要依序建置

DeepSeek Harness 根目錄的建置流程具有相依順序：

1. 編譯 Host TypeScript；
2. 封裝 Host；
3. 編譯 Client TypeScript；
4. 封裝 Client；
5. 建置 Web 應用程式。

修改跨越 Host 與 Client 的遠端介面時，Client 顯示的錯誤未必來自前端，也可能是 Host descriptor 或產生型別沒有更新。開始改 Remote Method 前，先讀 API Gateway 遠端呼叫指南；不確定功能該放在哪個 Package，則可參考 DeepSeek Harness 架構解析。

安全設定模型 API 金鑰

試跑 Agent Demo 時，可以用環境變數提供金鑰：

export DEEPSEEK_API_KEY="你的金鑰"

若使用相容的自訂端點，可依官方說明設定 DEEPSEEK_BASE_URL。不要把金鑰寫入原始碼、範例、準備公開的終端機紀錄，或可能被 Git commit 的環境檔。送出變更前，應檢查 diff 是否含有本機路徑、私人對話與存取憑證。

推送前要跑哪些檢查

專案透過 Lefthook 設定 pre-commit、pre-merge 與 pre-push 檢查。推送前可以主動執行完整驗證：

pnpm run check:all

開發途中可先執行與變更範圍最相關的檢查，準備送審時再跑完整流程。Hook 失敗時，應先釐清原因，不要把略過檢查當作預設做法。

原始碼註記也有明確語意：FIXME 是已知缺陷，TODO 是後續工作，XXX 用來提醒反直覺或風險較高的行為。維持一致，維護者才能透過搜尋快速判斷問題類型。

選擇可驗證改動的 Demo

型別檢查通過並設定好金鑰後，挑選最能涵蓋本次改動的 Demo。官方文件列出：

pnpm dsh --profile headless "summarize this workspace"
pnpm run demo:cordis
pnpm run demo:acp

請在可隨時刪除的測試工作區執行 Agent。靜態建置成功，不代表工具權限、事件順序和串流輸出在 Runtime 都正確。任務要小而明確，逐一查看工具呼叫，再檢查結果 diff。

貢獻程式碼前的檢查清單

• pnpm 版本符合儲存庫宣告，lockfile 只有預期變更；
• pnpm run typecheck 與相關 Package 測試通過；
• Host 變更已先於 Client、Web 完成驗證；
• diff 沒有 API 金鑰、本機絕對路徑或私人紀錄；
• 新行為位於正確的 Plugin、Capability Seam 或應用層；
• 至少一個聚焦的 Runtime Demo 覆蓋本次行為。

接著可閱讀 Agent 生命週期詳解，了解一項任務為何可能產生多個模型請求與工具階段。

官方原文

本文根據 DeepSeek Harness 官方開發文件（中文） 獨立整理，查核日期為 2026-08-20。支援版本、Script、Git Hooks 與貢獻規範以官方儲存庫最新內容為準。