本地工作區看得到，但 Agent 開始修改錯誤專案；模型顯示已配置，請求卻回報憑據不存在；舊會話日誌也在，卻無法安全續跑。
最快解法是：不要整個目錄無差別複製。請先在雲端 Mac 建立可回退的新環境，再把工作區、Harness 配置、憑據引用、插件依賴與會話日誌分層遷移，最後用新會話逐項驗收。DeepSeek Harness 目前仍是開發者預覽版，官方明確提醒可能出現相容性破壞，不能把跨版本無損恢復當成既定能力。官方根 README
這篇適合三類讀者：
- 已在本地試用，準備把短期實驗轉為持續線上任務的人員。
- 需要保留可審計會話與插件組合的 Agent 運維人員。
- 需要在遷移前決定哪些狀態必須保留、哪些應重新產生的專案負責人。
最後更新於 2026 年 8 月 18 日；行為核實自官方根 README、架構文件、模型設定指南與 Python SDK 說明。
[ SECTION_01 ] 先把遷移資產分成五層
整目錄複製最容易造成「看似完成、實際不可恢復」的狀態。原因是不同檔案承擔的責任不同：專案檔案描述工作內容，配置決定插件樹，憑據只提供授權，執行依賴決定能否開機，會話日誌則保存上下文與工具事件。
官方架構文件指出，模型 Adapter、工具註冊、Session Log、Agent Loop 都是可替換插件；Profile 會按層級組合 Bundle、Profile patch 與 Home-level patch。因此，同一個設定檔搬到另一台 Mac，不代表啟動後仍會得到相同的插件樹。官方架構文件
| 資產層 | 典型內容 | 建議動作 | 完成標準 |
|---|---|---|---|
| 工作區 | 原始碼、文件、版本庫 | 重新檢出或複製 | 絕對路徑、分支與未提交變更一致 |
| Harness 配置 | Profile、Bundle、patch、模型預設 | 匯出後審閱，再重建 | --dump-config 結果符合預期 |
| 憑據引用 | Provider ID、環境變數名稱 | 複製引用，不複製明文密鑰 | 目標進程讀到正確來源 |
| 執行依賴 | Node.js、Python、插件套件 | 記錄版本後逐項安裝 | 基礎 Profile 可啟動 |
| 歷史狀態 | 會話日誌、工具呼叫、審計事件 | 原始備份，副本測試 | 可讀則查閱；不可確認則新建會話 |
這張表的重點不是「全部搬過去」，而是先決定每項資產要複製、重建，還是放棄續接。例如，程式碼通常應透過版本控制重新取得；憑據應重新注入；舊會話則要保留查閱價值，但不應直接成為新版本的執行入口。
[ SECTION_02 ] 工作區路徑錯位，會讓 Agent 操作錯誤專案
問題表現通常很隱蔽。Agent 能夠列出檔案，甚至成功完成讀取任務，但實際看到的是另一個同名資料夾、錯誤分支，或雲端 Mac 上殘留的舊副本。
官方 Web UI 指南說明，dsh 會以啟動它的目錄作為預設檔案位置；新 Web UI 在選定工作區前，並沒有可用的工作區。官方 Web UI 指南
遷移時應核對：
- 本地與雲端 Mac 的工作區絕對路徑。
- Git 遠端、目前分支、HEAD 版本與未提交變更。
.gitignore、環境檔案與生成目錄是否被錯誤排除或一併帶入。- Agent 可見的根目錄是否比專案範圍更大。
- Shell、檔案系統與工作區是否指向同一個執行世界。
第一個驗收任務必須是只讀操作，例如要求 Agent 列出專案主套件、目前分支與測試入口。此時不要開放檔案修改，也不要允許任意命令執行。只有當輸出與本地記錄一致，才進入受控修改階段。
若以 Python SDK 啟動，官方範例把 cwd 作為 Agent 可用工作區，並將 session_root 指向會話資料夾；這兩個路徑不應混用。Python SDK 工作區與會話說明
[ SECTION_03 ] Provider ID 與模型預設值不能隨意改名
配置搬過去後，最常見的錯誤不是 YAML 格式，而是「Provider 看起來存在，已保存會話卻不認得」。
官方模型指南指出，Provider ID 是永久識別值，請求、已保存會話、模型預設與憑據引用都可能使用它。若要改名，官方建議新增 Provider，再刪除舊 Provider，而不是直接修改原 ID。官方模型配置指南
因此，配置應拆成四個檢查面：
- 一般設定：例如模型顯示名稱、端點、協定與非敏感參數，可按目標環境調整。
- Provider 身份：Provider ID 先保持不變，尤其是有歷史會話的環境。
- 模型預設值：新會話使用的模型可以重新選擇，但不能假設舊會話會跟著切換。
- 環境變數引用：配置只記錄引用名稱，目標進程必須真的取得對應變數。
模型修改通常在下一次請求生效，不必把「未重啟」誤判成配置失敗。相反地，已經送出請求的會話會保留日誌中的模型記錄；要測試新模型，應建立新會話，不要拿舊會話作為唯一判斷依據。
[ SECTION_04 ] 憑據要重新注入，不要跟著搬遷檔案走
憑據遷移有兩種風險。第一是失效：本地密鑰可能只存在本地 Shell、密鑰管理工具或特定使用者環境。第二是外洩：密鑰可能進入壓縮檔、終端歷史、Shell 日誌、備份目錄或交付文件。
官方文件說明，DeepSeek API 密鑰以不可回讀方式保存，設定中只留下憑據引用；文件並列出 $DSH_HOME/.credentials.yaml 作為密鑰保存位置。官方憑據配置說明
安全動作應保持以下邊界：
- 搬遷包只放 Provider ID、環境變數名稱與非敏感配置。
- API 密鑰在雲端 Mac 目標環境重新注入。
- 驗證執行進程的實際使用者、
HOME與DSH_HOME。 - 檢查終端歷史、Shell 設定、壓縮檔、會話日誌與交付材料。
- 若密鑰曾經進入未受控檔案，先撤銷並重新建立，不要只刪除文字檔。
提醒： 配置檔中出現「憑據名稱」不等於模型已經能呼叫。必須從新會話發出一次受控模型請求，才能確認雲端進程讀到的來源、Provider 路由與模型 ID 都正確。
[ SECTION_05 ] 插件先恢復基礎組合，再逐項加入
本地插件搬到遠端後無法啟動，通常涉及四個邊界：作業系統架構、執行時版本、插件依賴與 Profile 層級。若一次全量重裝，錯誤訊息會被大量安裝輸出掩蓋，最後只知道「啟動失敗」，卻不知道是哪個插件造成。
遷移前應記錄：
- DeepSeek Harness 版本或提交版本。
- Node.js、Python 與套件管理工具版本。
- Profile 使用的 Bundle 順序。
- 外部插件清單與其設定檔位置。
- Home-level patch、Profile patch 與命令列 overlay。
- 插件是否依賴本地路徑、可執行檔、Shell 或實體介面。
目標環境的處理順序應是：
- 安裝與源環境相符的基礎執行時。
- 以官方基礎 Profile 啟動 Web UI。
- 只加入模型 Provider，完成只讀工作區測試。
- 每次加入一個插件，重新啟動並記錄錯誤。
- 發現不相容時，移除最後加入的插件，回退到上一個可啟動狀態。
官方根 README 的預設 Web UI 位址是 http://127.0.0.1:3080；若透過 SSH 或其他遠端方式使用，還要另外核對連線轉發、監聽介面與權限，不要把本機回環位址直接暴露到公網。官方啟動說明
[ SECTION_06 ] DeepSeek Harness 會話日誌應先保留，再決定是否續跑
DeepSeek Harness 會話日誌不是普通聊天紀錄。官方架構文件指出，Session Log 是模型所見上下文的來源，Fork、Resume、轉錄、遙測與持久化都由這條事件流衍生；模型可見的輸入必須能從日誌重建。官方 Session Log 架構說明
Python SDK 文件則說明，範例會在指定的會話目錄寫入 JSONL，內容包含組裝後的模型請求與工具呼叫；同一會話 ID 可能保留工作目錄、環境變數與 Shell 狀態。官方 Python SDK 會話說明
這代表會話日誌同時具備上下文價值與安全風險：
- 它可協助追溯 Agent 看過什麼、呼叫過什麼工具。
- 它可能含有提示詞、檔案內容、命令輸出與敏感上下文。
- 它可能引用舊 Provider ID、舊模型與舊工作區。
- 新版本未必能直接讀取舊格式，尤其官方已明確標示開發者預覽版會出現相容性破壞。
建議保留原始檔案作為唯讀備份，再複製一份到雲端 Mac 測試。能夠讀取不等於能夠安全續跑；若工作區、Provider、插件或模型記錄無法完全對應，應把日誌當作審計與查閱資料，另開新會話完成工作。
[ SECTION_07 ] 遷移問答：四個容易被誤判的狀態
換 Mac 後，舊會話是否一定能接續？
不一定。會話日誌可能完整，但它依賴的 Provider ID、模型、工作區與插件樹未必相同。開發者預覽期間，不應把跨版本恢復當作保證。正確做法是保留原始日誌，使用副本測試讀取；無法確認上下文與工具狀態一致時，建立新會話。
哪些配置可以直接帶走？
可攜式的通常是非敏感模型設定、插件清單、Profile 結構與可重建 patch。Provider ID 要先保留，因為它可能被會話與憑據引用。密鑰、短期 Shell 狀態、絕對路徑與本地可執行檔則應在目標環境重新建立。
API 密鑰可以一起複製嗎？
不應該。即使密鑰位於 $DSH_HOME/.credentials.yaml，也不應將該檔案直接放入跨環境搬遷包。目標環境應透過受控方式重新注入，並檢查日誌、終端歷史與共享資料夾，避免明文殘留。
插件為什麼「檔案都在」仍然啟動不了？
插件是否能啟動，取決於版本、依賴、Profile 層級與執行環境，不只是檔案是否存在。先以基礎組合啟動，再逐項加入插件。這種方式能夠把問題縮小到單一組件，也保留明確回退點。
[ SECTION_08 ] 雲端 Mac 遷移驗收清單
以下清單應逐項勾選，未完成時不要切換持續 Agent 任務：
- [ ] 已保存本地工作區、配置、插件清單與 DeepSeek Harness 版本記錄。
- [ ] 已記下本地 Git 分支、HEAD、未提交變更與工作區絕對路徑。
- [ ] 已在雲端 Mac 建立獨立、可刪除、可回退的目標環境。
- [ ] 已確認目標進程的使用者、
HOME、DSH_HOME與工作目錄。 - [ ] 已用基礎 Profile 啟動，並確認 Web UI 或命令列能正常運作。
- [ ] 已在不修改檔案的情況下完成倉庫摘要、分支與專案範圍檢查。
- [ ] 已保持 Provider ID，不以顯示名稱取代永久識別值。
- [ ] 已在目標環境重新注入憑據，沒有把明文密鑰放入搬遷包。
- [ ] 已用新會話完成一次模型請求，並確認模型與 Provider 路由。
- [ ] 已逐項加入插件，記錄每次啟動結果與依賴錯誤。
- [ ] 已用受控檔案修改測試 Agent 的工作區邊界。
- [ ] 已測試命令審批、工具呼叫與錯誤回退。
- [ ] 已備份 DeepSeek Harness 會話日誌，並在副本上測試讀取或恢復。
- [ ] 已重啟雲端進程，確認配置、憑據引用與工作區仍然有效。
- [ ] 已寫下失敗回切條件，並保留本地環境至目標環境穩定驗收完成。
[ SECTION_09 ] 端到端恢復要以「新會話可控」為標準
完成遷移後，不要只看 Web UI 能否開啟。建議依序驗證：
第一階段：只讀倉庫分析。
Agent 只能讀取工作區，輸出專案結構、目前分支與主要套件。若路徑或分支不符，立即回退。
第二階段：受控檔案修改。
指定一個可丟棄檔案，要求 Agent 修改後查看差異。確認修改範圍沒有越出工作區。
第三階段：命令審批。
執行低風險命令，再測試需要人工核准的命令。若審批策略與本地不同，先調整政策，不要直接開放全權限。
第四階段：模型呼叫。
使用新會話確認 Provider、模型、憑據與回應格式。舊會話可以作為對照，但不能替代新會話驗收。
第五階段：重啟後狀態。
停止雲端進程並重新啟動，重新檢查工作區、模型預設、插件與會話索引。重啟後仍能完成前述測試，才具備交付條件。
最後應形成一份驗收紀錄，至少包含源環境版本、目標環境版本、配置差異、插件狀態、會話日誌處理方式、重啟結果與失敗回切條件。若持續任務涉及長時間執行，還應保留本地環境一段觀察期，而不是在第一次模型請求成功後立即刪除。
[ SECTION_10 ] 本地方案與雲端 Mac 的取捨
直接沿用本地方案，常見缺點是工作被綁定在個人電腦、長時間任務容易受睡眠或網路中斷影響，插件與憑據也分散在個人環境，團隊難以重現。若改用一般遠端主機，則可能遇到 macOS 工具鏈不一致、Apple 專用依賴缺失，以及本地與遠端執行結果難以對照的問題。
在選擇目標環境前，可先查看 NOVAKVM 雲端 Mac 方案與地區說明，再依遷移演練的隔離需求選擇合適環境。對已完成本地試用、但需要獨立驗收環境的團隊，先租用 NOVAKVM 的雲端 Mac 進行遷移演練通常更穩妥。這樣可以保留原本環境作為回退點，先完成工作區、模型、插件與會話日誌驗收，再決定是否轉為長期任務。若只是短期測試、臨時算力或需要隔離現有設定，可先參考 NOVAKVM 雲端 Mac 方案；若任務需要長期穩定重負載、固定的實體介面或完全由團隊自行維護，則自購 Mac 仍可能更合適。