2026 DeepSeek Harness Python SDK 部署到雲端 Mac

資料點：官方 Python SDK 目前分成 deepseek-harness-sdk 與同版本的 deepseek-harness-runtime-bin 兩個套件。這代表你可以用 Python 調度 Harness，卻不必把整個原始碼工作區和 Node.js 建置鏈一併搬到雲端 Mac；正確做法是先隔離工作區完成單任務驗證，再鎖定 SDK、runtime、會話目錄與進程責任，最後才接入長時間執行。資料核對自 官方 Python SDK README 與 runtime wheel 說明，截至 2026 年 8 月 18 日。

症狀：把本地開發目錄整包複製到雲端 Mac 後，Python 能啟動，但工作區、會話、憑據或重啟後的任務邊界說不清楚。 最快解法：先用可丟棄工作區跑通一個最小任務，固定 SDK、runtime、session_root 和憑據注入方式，再由獨立的進程管理器負責啟動、停止、逾時與恢復。

這篇適合三類人：需要用 Python 調度 DeepSeek Harness 程式碼任務的自動化開發者；準備在雲端 Mac 持續執行 SDK 會話的平台工程師；以及需要驗收第三方交付環境是否可恢復的專案負責人。

先把部署目標分成三種

在輸入第一條 Prompt 以前，先決定你要交付的是一次性腳本、定時任務，還是長期 Agent。三者對工作區、會話目錄和進程責任的要求不同，混在一起會讓「程式已啟動」被誤認為「服務可交付」。

<

部署類型	工作區策略	會話策略	進程責任
一次性腳本	使用臨時或複製出的測試專案	每次新建會話，完成後保存輸出	呼叫端負責結束與錯誤處理
定時任務	每個任務使用明確版本的專案快照	預設新會話，避免上一輪狀態污染	排程器負責觸發、逾時與重試
長期 Agent	固定專案目錄，限制可寫入範圍	連續任務才復用既有 session id	launchd 或其他管理層負責啟停、日誌與重啟

官方目前把 DeepSeek Harness 定義為 developer preview，並明確警告可能出現相容性破壞變更；因此正式部署前至少要記錄 Git 來源、Python 套件版本、runtime wheel 版本、macOS 版本與安裝日期，而不是只保存一條 pip install 指令。[官方主專案 README](https://github.com/deepseek-ai/deepseek-harness/blob/master/README.md)

雲端 Mac 先做三項環境核對

1. 確認處理器架構：

   uname -m

官方 runtime wheel 的 macOS 標籤包含 macosx_14_0_arm64，所以 Apple Silicon 雲端 Mac 是明確支援的部署方向；若結果不是 arm64，不要直接假定相同 wheel 能使用。官方 runtime 平台說明

1. 確認 Python 來源與版本：

   python3 --version
   which python3

任務書沒有提供一個可直接照抄的固定 Python 小版本，因此部署時應以當日官方 Python SDK 指南與套件 metadata 為準，並把實際輸出寫進交付紀錄。

1. 確認模型端點與權限：

   printenv DEEPSEEK_BASE_URL
   test -n "$DEEPSEEK_API_KEY" && echo "API key is set"

SDK runtime 會讀取 DEEPSEEK_API_KEY、DEEPSEEK_BASE_URL 等環境變數；這些變數應在進程啟動環境注入，而不是寫入程式碼、Git 設定或會話日誌。

第一步：只建立一個最小隔離環境

不要先安裝 Node.js、複製完整 monorepo、連接正式 Git 儲存庫，再期待一次成功。官方預構建 runtime 的設計是把單檔 runtime 放進 wheel；原始碼建置流程和 Python SDK 的使用流程不是同一件事。

先建立三個互相分離的目錄：

mkdir -p "$HOME/dsh-deploy/app"
mkdir -p "$HOME/dsh-deploy/workspaces/smoke"
mkdir -p "$HOME/dsh-deploy/state"
cd "$HOME/dsh-deploy/app"

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install deepseek-harness-sdk
python -m pip freeze > requirements.lock.txt

venv 的目的，是讓這個部署只使用自己的 Python 套件與執行檔；Python 官方也提醒虛擬環境通常不可直接搬移，若路徑改變，應在新位置重新建立，而不是複製整個 .venv。[Python venv 官方文件](https://docs.python.org/3.14/library/venv.html)

首輪安裝成功的信號不是「pip 沒有報錯」，而是：

• python -m pip show deepseek-harness-sdk 能顯示套件；
• 同版本的 deepseek-harness-runtime-bin 已被安裝；
• python -c "import deepseek_harness; print('import ok')" 能正常退出；
• 尚未接入正式 Repository、正式 API key 或長期 session。

如果 import 成功但啟動失敗，先保存完整錯誤、uname -m、Python 版本與 pip freeze；回退到官方目前的預構建 wheel，不要立刻改用原始碼建置。開發用 Node carrier 只適合 repository-local development 和 verification，不會自動成為正式 wheel 的執行方案。 <

選項	優點	隱性成本	部署判斷
預構建 Python SDK + runtime wheel	不必在目標主機另裝 Node.js；安裝面較小	仍需管理 Python、憑據、權限與進程	**正式雲端部署優先**
從 Harness 原始碼建置	可修改 runtime 或插件	需要 Node.js、套件管理器、建置產物與更多回退點	只有在需要改 runtime 時採用
直接複製本地 .venv	初期看似最快	絕對路徑、架構、依賴與啟動環境可能不一致	**不作為交付方式**

第二步：用可丟棄工作區驗證三條鏈

完成安裝後，先在 "$HOME/dsh-deploy/workspaces/smoke" 建立一個不含機密的測試專案。第一條任務不要要求 Agent 修改正式程式，而應要求它完成可核驗的三段操作：

1. 回傳一段模型文字，確認端點和 API key 可用；
2. 在工作區建立一個指定檔案，確認 cwd 沒有偏移；
3. 執行一個低風險 Bash 指令，確認工具鏈真的由預期目錄啟動。

最小 Python 入口可保持簡單：

from pathlib import Path
from deepseek_harness import DeepSeekHarness

workspace = Path.home() / "dsh-deploy" / "workspaces" / "smoke"
session_root = Path.home() / "dsh-deploy" / "state" / "smoke"

with DeepSeekHarness(
    cwd=str(workspace),
    session_root=str(session_root),
) as harness:
    result = harness.run(
        "在目前工作區建立 smoke-result.txt，寫入一行固定文字，"
        "然後回報工作區絕對路徑、檔案內容與執行結果。"
    )
    print(result.final_response)
    print("session_id:", result.session_id)
    print("session_root:", result.session_root)

這裡的重點不是 Prompt 本身，而是驗收證據必須同時包含：

• 實際送出的任務文字；
• cwd 對應的工作區絕對路徑；
• result.final_response；
• session_id 和 session_root；
• smoke-result.txt 的實際內容；
• git diff 或檔案清單所顯示的真實變更。

官方 SDK 是以 subprocess 驅動 Harness，並透過 stdio 上的 newline-delimited **JSON-RPC** 通訊；所以「Python import 成功」不等於 runtime、模型端點、檔案工具和 Bash 都已成功串起來。若你需要進一步比對雲端環境和本地流程，可先閱讀 [MACGPU 繁體中文雲端 Mac 入口](https://macgpu.com/zh-Hant/index.html)，但仍應以你實際執行的最小任務作為驗收證據。

若任務失敗，按這個順序回退：先移除正式 cwd 和自訂設定，再用可丟棄工作區；接著只保留模型回應測試；最後才逐一恢復檔案工具、Bash 和持久化。不要在同一輪同時更換 SDK、runtime、Prompt 和工作區，否則你無法知道是哪個變更造成錯誤。

第三步：把程式碼與會話狀態拆開

cwd、session_root 和 session_id 不是三個可互換的路徑參數：

• cwd 決定 Agent 執行檔案操作與 Bash 時的工作區；
• session_root 是持久會話資料的根目錄；
• session_id 決定要建立新會話，還是找回既有對話與持久 Bash 狀態。

session_root 應放在程式碼目錄之外、由服務帳戶可讀寫的專用狀態目錄；cwd 則要指向明確的工作區。兩者若混在一起，備份、清理和權限盤點都會變得困難。

建議採用下列規則：

$HOME/dsh-deploy/
├── app/                         # Python 程式與鎖定檔
├── workspaces/
│   ├── smoke/                   # 可丟棄驗證專案
│   └── project-a/               # 正式專案工作區
└── state/
    ├── smoke/                   # smoke session_root
    └── project-a/               # project-a 的會話狀態

獨立任務一律建立新的 session id；只有「同一專案、同一工作區、同一流程仍在延續」時才復用舊 id。不要把不同客戶、不同 Repository 或不同排程輪次共用一個 session_root，因為這會讓模型看到不應延續的上下文，也可能延續上一輪留下的 Bash 狀態。

FAQ：部署時最容易被誤判的四件事

在 Mac 上使用 Python SDK，還需要 Node.js 嗎？

使用官方預構建 runtime wheel 時，目標主機通常不需要另裝 Node.js；runtime wheel 內含對應平台的單檔 Node executable。可是從原始碼建置、使用開發用 node carrier，或要修改 Harness runtime 時，Node.js 仍會重新出現在建置依賴中。不要把 Web UI 的安裝流程套到 Python SDK。

session_root 應該放在雲端 Mac 哪裡？

放在程式碼目錄之外、固定且可備份的狀態目錄，並以專案或租戶分隔。不要放在 /tmp、Git repository 或所有服務共用的資料夾。恢復時除了讀到檔案，還要確認 cwd、SDK 版本與設定一致，否則「會話可讀」仍不代表可以安全繼續。

同一個 session id 能跨進程繼續嗎？

可以，但前提是新的程序能讀到相同 session_root，並使用相容的工作區、環境變數與 runtime 設定。上一個程序尚未結束時不要並行打開同一 session；對於會修改檔案或執行 Bash 的任務，先用唯讀檢查判斷上一輪是否已提交結果，再決定是否繼續。

雲端 Mac 重啟後怎樣恢復會話？

先檢查主機架構、虛擬環境、工作區和狀態目錄，再注入憑據，最後啟動 Python 程式並指定原有 session id。不要把「程序重新啟動」當成「任務自動恢復」；SDK 本身不等於完整的守護和工作流編排系統，重試、去重與人工確認仍需由你的平台層負責。

第四步：把憑據和進程責任補齊

長期執行時，真正容易出問題的通常不是 Python API，而是啟動環境不完整：

• SSH 登入時有環境變數，背景服務啟動時沒有；
• API key 寫在 shell script 或 Repository，權限擴大後難以追蹤；
• 進程退出後沒有人知道，遠端連線中斷被誤認為任務完成；
• 主機重啟後工作區仍在，但 session_root 沒掛載；
• 重試邏輯沒有辨識「已完成但回應遺失」的情況，造成寫入任務重複執行。

你可以把非機密設定寫入受控環境檔，把 API key 交給雲端平台的秘密注入機制或權限受限檔案；啟動時檢查檔案擁有者和權限，並禁止把完整環境變數輸出到日誌。若使用 macOS 的 launchd，它只是一個進程啟動與管理層，不代表 DeepSeek Harness SDK 自帶守護、重試、備份或並發控制能力。[Apple launchd 文件](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html)

進程責任至少要寫成一份 runbook：

• 誰負責啟動與停止；
• 單次任務的逾時值；
• stdout、stderr 和會話日誌如何輪換；
• 進程退出後由誰判斷可否重試；
• 主機重啟後是否自動恢復；
• 恢復前如何確認上一個任務沒有完成一半；
• SDK 或 runtime 升級後由誰執行回退。

第五步：用清單完成重啟與回退驗收

正式交付前，至少做一次人為終止、一次遠端連線中斷和一次主機重啟。每次測試都要保存時間、程序輸出、session id、工作區狀態與恢復決策。

• [ ] uname -m、macOS 版本、Python 版本已記錄。
• [ ] deepseek-harness-sdk 與 deepseek-harness-runtime-bin 的實際版本已鎖定。
• [ ] 安裝來源、pip freeze 和部署日期已保存。
• [ ] 測試工作區與正式工作區完全分離。
• [ ] session_root 位於固定狀態目錄，不在 Git 追蹤範圍。
• [ ] 新任務會建立新 session id，連續任務才復用舊 id。
• [ ] API key 不出現在 Repository、啟動腳本正文和會話日誌。
• [ ] Python 程式被終止後，能分辨未開始、執行中、已完成三種狀態。
• [ ] 遠端連線中斷不會直接觸發重複寫入。
• [ ] 主機重啟後，工作區、session_root 和憑據能按順序恢復。
• [ ] 升級前已有舊版套件、鎖定檔、狀態資料和回退命令。
• [ ] 未通過恢復驗收前，不擴大並發、不接正式 Repository、不延長租期。

評分時不要只看「能不能跑」： <

驗收項目	0 分	1 分	2 分
架構與 runtime	依賴未確認	能啟動但來源未鎖定	架構、wheel、版本均有紀錄
工作區隔離	直接使用正式目錄	有測試目錄但規則不明	每個任務的 cwd 可追蹤
會話恢復	只保存 Prompt	能讀取舊資料	能判斷是否可安全續跑
憑據管理	寫入程式碼或 log	使用環境變數	有權限、輪換與撤銷流程
進程責任	SSH 視窗維持執行	有簡單啟動腳本	有啟停、逾時、日誌與重啟 runbook

總分若低於 **8 分**，先修復部署責任邊界，不要用增加記憶體、增加並發或更換模型來掩蓋流程缺口。這個分數是本文的驗收工具，不是 DeepSeek Harness 官方性能評級。

目前方案與 MACGPU 雲端 Mac 的取捨

如果你把長期 Agent 留在本地 Mac，常見缺點是本機需要持續開機、SSH 或遠端連線中斷後缺乏可交接的執行環境，而且正式任務會和日常開發共用工作區、憑據與系統套件。改用一般 Linux 雲主機，則可能失去 macOS arm64 的原生測試條件；自行購買一台專用 Mac，又要承擔硬體閒置、升級週期和故障替換。

對需要短期驗證、專案制 Agent 或固定租期的團隊，較合理的順序是先完成本文的最小 SDK 驗收，再依工作區、狀態目錄和重啟清單檢查交付環境。若你需要的是可連線的 Apple Silicon 雲端主機，可以先查看 MACGPU 的繁體中文雲端 Mac 入口 與 M4 Mac 交付選項；不要在未通過恢復測試前直接把正式 Agent 搬上長租節點。若需要特定地區的雲端 Mac，應按實際網路延遲、資料位置與租期向交付方確認可用方案。