2026 DeepSeek Harness 外掛更新怎麼做灰度發布？

發布前的版本證據

只記錄外掛名稱，無法支援可靠回退。真正可恢復的單位應是「完整外掛組合」，至少包括以下內容：

• Harness 版本、提交識別碼或 Release 標籤。
• 每個外掛的來源、版本、提交識別碼與安裝方式。
• 鎖定檔及其雜湊值。
• Host、Client、Cordis 介面版本與啟動方式。
• 設定檔入口、環境變數名稱及非機密設定差異。
• 目前可以完成的基準任務、工具清單與權限邊界。
• macOS、執行階段、套件管理器及必要系統工具的版本證據。

不應把真實 API 金鑰、客戶資料或不可逆任務複製到驗證環境。對於設定檔，可先移除機密值，再保留鍵名、型別與預設行為，讓測試能檢查設定契約，而不是暴露正式憑據。

在更新前，先停止沒有回退路徑的自動更新。若目前使用 Git 管理來源，可在現行環境保存狀態：

git status --short
git rev-parse HEAD
git diff -- package.json package-lock.json pnpm-lock.yaml yarn.lock
shasum -a 256 package-lock.json

輸出應能回答三個問題：目前執行的是哪一個提交、依賴是否有未提交變更、回退時是否能取得完全相同的鎖定檔。若使用的是封裝安裝而非原始碼，則應改為保存套件清單、解析後版本與安裝目錄快照，不要只保存安裝指令。

驗證面的隔離條件

灰度發布的第一個硬條件不是「有沒有測試指令」，而是「有沒有第二個可丟棄的執行面」。這個執行面可以是獨立工作區、獨立使用者設定，或一台不承擔正式任務的雲端 Mac 驗證環境。

驗證環境應與正式環境保持相同的安裝路徑邏輯與啟動方式。若正式環境透過某個工作目錄載入外掛，驗證環境不應改用完全不同的相對路徑；若正式環境透過啟動腳本注入設定，驗證時也應使用同一入口。否則測到的可能只是「另一種部署方式」，不能證明正式切換安全。

建立驗證面時，可依照以下順序操作：

1. 複製必要的非機密設定與工作區結構。
2. 移除客戶憑據、正式 API 金鑰及外部服務寫入權限。
3. 固定與正式環境相同的啟動命令和工作目錄。
4. 將目前已知正常的外掛組合先部署一次，取得基準結果。
5. 再只替換本次要驗證的完整組合。
6. 確認舊執行面仍能獨立啟動，且沒有被新安裝覆寫。
7. 為驗證環境設定清楚的工作區、會話與日誌位置。

若無法並行保留舊環境，例如唯一一台遠端 Mac 同時承擔正式 Agent 和測試工作，就不應直接更新。這不是測試不足，而是回退條件不存在。此時應先增加第二執行面，或把低風險驗證移到臨時環境，再安排正式切換。

載入與設定契約

第一輪只驗證外掛能否被發現、設定能否讀取，以及 Host 與 Client 能否完成啟動。不要在這個階段執行檔案寫入、刪除、推送或其他外部副作用工具。

可先保存啟動日誌：

mkdir -p logs
<正式啟動命令> 2>&1 | tee logs/plugin-load-$(date +%Y%m%d-%H%M%S).log

成功證據不應只是畫面「看起來正常」，而應包括：

• 外掛被發現，沒有名稱衝突或重複註冊。
• 設定鍵被讀取，必要欄位缺失時能明確報錯。
• Host 與 Client 成功完成啟動。
• 工具註冊清單符合預期。
• 日誌沒有未處理例外、循環載入或設定覆寫警告。
• 外掛設定卡片若能顯示，欄位名稱、預設值與儲存行為均符合目前文件或原始碼。

Cordis 的存在不代表任何外掛都能自動相容；組件能否載入，仍取決於實際介面、生命週期與設定結構。設定鍵和行為應以官方開發指南、官方外掛介面定義及目標外掛原始碼交叉核對，不應根據套件名稱、社群貼文或「看起來相似」的外掛推斷相容性。

如果載入失敗，先區分三類錯誤：外掛根本沒有被發現、外掛已被發現但設定解析失敗，或外掛啟動後與 Host/Client 介面握手失敗。這三類問題的修復路徑不同，不能只重新安裝同一個套件。

最小任務與權限邊界

載入成功後，第二輪才進入行為驗證。測試應至少包含一個只讀任務和一個可回退的寫入任務，兩者都要有明確的預期結果。

只讀任務可檢查：

• 外掛工具是否成功註冊。
• 工具描述、參數型別與回傳格式是否改變。
• Host 是否能把工具結果交還 Client。
• 會話日誌是否記錄工具呼叫與結果。
• 不需要寫入權限的 Agent 是否仍只看到只讀工具。

可回退寫入任務則應限制在測試工作區，例如建立一個暫存檔、修改可刪除的測試內容，再以版本控制或檔案雜湊確認結果。不要用真實客戶目錄作為第一個寫入樣本。

更新前後應保存能力清單：

before:
  tools: [read, search]
  permissions: [workspace-read]
  external_access: disabled

after:
  tools: [...]
  permissions: [...]
  external_access: [...]

如果更新後新增寫入、網路、外部服務或程序執行能力，不能把它視為普通版本差異。權限擴大應單獨審批，並在切換批次中標記為高風險。社群對外掛相容性的聲明只能當作待驗證線索，不能取代原始碼和最小任務結果。

對於 dsh-plugin，尤其要檢查工具註冊時機、設定載入時機，以及外掛是否在啟動階段要求額外權限。某些問題只會在完整 Host 啟動後出現，單獨執行外掛測試並不足以證明組合可以在正式工作區使用。

會話持久化與重啟回歸

第三輪要驗證的是「更新後能否維持工作狀態」，而不是只有「程式能重新啟動」。這兩件事必須分開記錄。

建議按以下五步執行：

1. 使用舊版本建立一個可辨識的測試會話。
2. 在驗證環境啟動新版本，確認新會話能正常建立。
3. 關閉並重新啟動 Harness，檢查設定是否持久化。
4. 嘗試恢復一個已完成工具呼叫的會話。
5. 再檢查長任務是否能從正確的檢查點繼續，而不是重新執行已完成的副作用。

可用以下方式保存重啟前後的基本證據：

<停止命令>
<啟動命令> 2>&1 | tee logs/restart-regression.log
<會話列出或恢復命令>

成功條件包括：新舊會話狀態可區分、設定沒有回到預設值、工具註冊一致、工作區路徑正確、恢復後不重複執行不可逆動作。長任務只有在載入、最小任務和權限測試通過後才進入這一輪。

「服務重新啟動成功」不能作為「原任務能夠續跑」的證據。兩者使用不同的驗收項目，也應有不同的回退動作。若會話資料位於本地硬碟、共享工作區或外部儲存，還要分別驗證檔案權限、路徑持久性和重啟後的掛載狀態。

遠端 Mac 的分批切換

在遠端 Mac 上進行 DeepSeek Harness 外掛灰度發布 時，切換單位應是「一台執行面或一組低風險任務」，而不是一個套件。推薦採用以下時間軸：

• 準備階段： 保存目前組合、鎖檔、設定差異與基準任務結果。若任一項缺失，停留在準備階段，不進入更新。
• 驗證階段： 在隔離工作區完成載入、只讀任務、可回退寫入、權限、持久化與重啟測試。所有成功證據可取得後，才進入切換。
• 第一批： 先切換低風險、無共享會話、無長任務的執行面。觀察期間檢查啟動日誌、工具錯誤、權限變化及任務結果。
• 第二批： 才擴大到共享工作區或較長任務，但仍保留舊組合可立即啟動的路徑。
• 正式批次： 在前一批沒有新錯誤、會話恢復正常且能力清單無未審批變化時，才處理剩餘執行面。

若第一批出現載入失敗、工具結果格式不符、權限突然擴大、設定遺失或會話不能恢復，應立即停止後續批次。回退操作包括：

1. 停止新版本執行面。
2. 還原 Harness、外掛與依賴的完整鎖定組合。
3. 還原設定檔和啟動入口。
4. 重新啟動舊組合。
5. 以基準任務確認工具、工作區和會話恢復。
6. 保存失敗日誌、版本差異與回退結果。

外掛灰度發布驗收清單

• [ ] 已保存 Harness 版本與提交識別碼。
• [ ] 已保存每個外掛的來源、版本與依賴解析結果。
• [ ] 已保存鎖檔、設定入口與啟動命令。
• [ ] 已停止沒有回退路徑的自動更新。
• [ ] 已建立不含正式憑據的獨立驗證環境。
• [ ] 驗證環境使用與正式環境相同的安裝及啟動邏輯。
• [ ] 已完成外掛發現、設定讀取與 Host/Client 啟動測試。
• [ ] 已完成只讀任務及可回退寫入任務。
• [ ] 已比較更新前後的工具與權限清單。
• [ ] 已完成設定持久化、服務重啟與會話恢復測試。
• [ ] 已指定每一批的負責人、觀察條件與停止條件。
• [ ] 已準備可立即恢復的完整舊組合。

團隊是否要統一鎖定外掛版本，答案取決於執行面是否共享。共享 Agent、共同工作區或同一套自動化流程，通常應鎖定完整組合，否則不同成員可能得到不同工具清單和設定行為。個人隔離環境可以保留較寬鬆的更新策略，但仍應在正式任務前留下可重建的鎖檔與基準測試。

dsh-plugin 更新失敗時，最快的回退方式不是重新安裝「上一個看似相近的版本」，而是恢復更新前保存的 Harness、外掛、依賴與設定整組快照；若缺少第二執行面，則先恢復舊執行面，再分析新版本，不要在唯一生產環境反覆試錯。

每逢官方 Harness 候選版、外掛 API、Cordis 介面或設定目錄變更，都應重新核對目標外掛原始碼、Release 記錄與鎖檔。外掛名稱相同、版本號接近或社群宣稱「已支援」都不能直接視為相容證據。

對於缺少本地第二台 Mac、需要短期複製正式啟動方式，或要在不影響長期 Agent 的情況下完成驗證的團隊，可先閱讀雲端 Mac 穩定與驗證雙軌環境，再按實際工作區隔離需求選擇遠端 Mac 算力方案。

當前方案與 Mac 驗證方案

直接在唯一的本地環境更新，常見缺點是：沒有並行舊版本、共享工作區容易被重啟打斷、權限變更不容易被察覺，而且失敗後只能在同一個故障面上繼續排查。純雲端執行面則可能遇到連線、頻寬、權限交接或環境重建成本，未必適合長期固定重負載。

因此，若目標只是短期驗證、外掛相容性測試或遠端 Mac 分批切換，先保留一套舊組合，再用獨立 Mac 執行面完成回歸，通常比直接改動唯一環境更容易控制風險。若工作負載長期穩定、需要固定實體介面或必須完全掌握硬體，則自購 Mac 仍可能更合適；若只是需要臨時算力或測試環境，NodeMini 的遠端 Mac 可作為第二執行面，讓正式工作區不必為一次外掛更新承擔全部中斷風險。