工具呼叫沒有被攔下，或 Hook 腳本一出錯，Agent 仍然繼續執行。
最快解法：DeepSeek Harness Hooks 配置先只做一個可觀察的 PreToolUse 拦截點，預設失敗時拒絕放行；完成允許、拒絕、異常與恢復四類測試後，再增加其他工具與自動化動作。
這篇適合三類讀者：
- Agent 開發者：需要在工具呼叫前後加入校驗或回饋。
- 平台工程師：需要統一專案級與環境級 Hook 的交付方式。
- 遠端環境維護人員：需要確認 Hook 在斷線、重啟及無人值守場景下仍可觀察、可回退。
截至 2026 年 8 月 18 日，官方儲存庫仍把 DeepSeek Harness 標示為 Developer Preview，並明確提醒可能出現相容性破壞變更。因此，本文不把其他 Agent 工具的欄位名稱、設定檔位置或失敗行為直接套用到 DeepSeek Harness。所有可執行鍵名，都應以當日原始碼、最新 Release 及實際事件記錄為準。(github.com)
[ SECTION_01 ] 先定義 Hook 只負責一件事
Hook 常被誤用成「所有安全功能的總開關」。這會讓排錯變得困難，也容易在錯誤時錯誤放行。
第一版應從以下四種目標中只選一種：
- 權限拦截：工具執行前檢查工具名稱、工作區或參數。
- 結果記錄：工具完成後保存成功、失敗、輸出摘要及工作階段識別。
- 停止門禁：Agent 準備結束時，確認必要檔案或驗證流程已完成。
- 上下文補充：在工作階段開始或特定事件後，向 Agent 注入必要背景。
若目標是阻止危險命令，第一版就只做權限拦截，不要同時加入結果改寫、通知、重試及自動修復。
還要劃清邊界：Hook 能控制 Agent 的事件鏈路，但不能取代作業系統沙箱、檔案權限、憑據隔離或網路出口控制。官方架構將 DeepSeek Harness 定義為以插件組成的 Agent Harness；這代表 Hook 是執行流程中的控制點，不等於完整的系統級隔離層。(github.com)
DeepSeek Harness Hooks 配置檔案放在哪裡？
目前官方使用指南公開說明了工作區選擇、模型設定及執行方式，但沒有在穩定使用者指南中固定宣告一個可長期依賴的 Hook 設定檔路徑。官方指南指出，dsh 會以啟動它的目錄作為預設檔案系統位置，而工作區仍需在 Web UI 中選取。(github.com)
因此，配置前應先做三項核對：
- 在目前版本原始碼中搜尋 Hook 事件型別與註冊入口。
- 搜尋
PreToolUse、tool_call、hook等字串，確認事件是否已由實際執行管線觸發。 - 檢查最新 Release 或變更記錄，確認配置目錄、輸入欄位及輸出契約沒有改名。
若原始碼沒有明確提供穩定設定鍵，就不要先建立一個看似合理的 JSON 或 TOML。格式能被解析，不代表事件真的會觸發。
[ SECTION_02 ] 第一輪只驗證一個低風險匹配規則
最小接入點應選擇低風險工具。例如先觀察讀取類工具，或在不會修改檔案的測試工作區中記錄一次工具呼叫。
第一輪只需要取得三種證據：
- 命中輸入：Hook 實際收到的事件名稱、工具名稱、工作目錄及參數摘要。
- 處理結果：腳本是否完成，輸出是否能被 Harness 解析。
- 未命中結果：其他工具或不符合條件的呼叫是否維持原本流程。
不要把其他 Agent 的 PreToolUse 設定格式複製過來。不同工具可能在事件名稱大小寫、匹配方式、輸入欄位及錯誤處理上完全不同。即使外部工具常見 PreToolUse 這個名稱，也不能據此推斷 DeepSeek Harness 的 Hook Protocol 已採用相同語意。
可採用以下驗收門檻：
- 同一工作區連續觸發相同測試任務，命中結果一致。
- 不符合匹配條件的工具不被攔截。
- Hook 不會把敏感參數原文寫入終端或長期日誌。
- 關閉 Hook 後，基準任務仍可正常完成。
官方 Web UI 指南目前把「選取工作區」列為可以開始工作的重要前置條件；這也說明工作目錄不是裝飾欄位，而是 Hook 判斷範圍時必須記錄的上下文。(github.com)
[ SECTION_03 ] 用四類結果確認失敗策略
設定檔文字本身不能證明失敗時 Agent 會不會繼續。這必須從會話事件、執行記錄或實際測試取得。
Hook 腳本失敗後 Agent 會繼續嗎？
不能預先假設會繼續，也不能預先假設一定停止。DeepSeek Harness 目前仍處於快速變更階段，Hook 的失敗預設值應以當前原始碼和事件執行結果為準。若輸出契約不清晰，安全做法是暫停放行，不擴大工具權限。(github.com)
第一輪放行測試應分成四組：
- 明確放行：符合低風險條件，Hook 回傳可解析的允許結果，工具正常執行。
- 明確拒絕：使用測試用危險條件，Hook 回傳拒絕結果，工具沒有真正執行。
- 腳本異常：讓測試 Hook 回傳錯誤或非預期輸出，記錄 Agent 是否停止、重試或繼續。
- 超時處理：使用短時間、可控的測試腳本，觀察超時後的實際事件及後續工具狀態。
測試時不要使用真實密鑰、破壞性命令或客戶資料路徑。拒絕測試只需要讓 Hook 判斷一個無害的測試標記，確認拦截鏈路存在即可。
若四類結果中有任何一類無法判讀，版本應停留在試點。此時最合理的分數不是「功能完整度」，而是可觀察性：
- 觸發可重現：2 分
- 放行與拒絕可區分：2 分
- 異常後有清晰回退：2 分
- 日誌不洩漏敏感資料：2 分
- 可在不刪除工作區的情況下停用：2 分
低於 8 分，不應進入 Bash 或檔案修改場景。
[ SECTION_04 ] 對比表：不同 Hook 目標的上線次序
| 方案 | 主要事件 | 可控制範圍 | 初次部署風險 | 適合時機 |
|---|---|---|---|---|
| 結果記錄 | 工具完成後 | 執行結果、耗時、輸出摘要 | 低 | 最早建立觀測基線 |
| PreToolUse 拦截 | 工具執行前 | 工具名稱、參數、工作區 | 中 | 需要阻止危險命令時 |
| 停止門禁 | Agent 結束前 | 驗證是否完成、是否允許停止 | 中至高 | 已有穩定事件記錄後 |
| 上下文補充 | 工作階段或訊息事件 | 注入提示及工作狀態 | 中 | 需要跨回合維持規則時 |
| 完整腳本集合 | 多個事件混合 | 權限、記錄、通知、重試 | 高 | 試點通過且有版本管理後 |
這個次序的重點不是功能多少，而是每增加一個事件，就增加一條可能失敗的執行鏈路。先記錄，再拦截；先單點，再擴展。
[ SECTION_05 ] 第二輪再加入 Bash 與檔案修改
當低風險匹配已經可以重複觸發，才進入 Bash、檔案修改或外部工具。
此時至少收緊三個邊界：
- 工作區邊界：只允許專案目錄及明確的暫存目錄。
- 憑據邊界：Hook 不讀取密鑰檔，不把環境變數完整寫入日誌。
- 參數邊界：命令、檔案路徑及外部工具參數必須逐項檢查，不以整段字串的模糊關鍵字判斷。
匹配器過寬，會把正常測試、讀取及版本控制操作一併攔截。匹配器過窄，則可能漏過工具別名、參數變體或同一功能的另一個執行入口。
因此，每次只增加一類操作：
- 先加入 Bash 觀察。
- 再加入 Bash 拒絕條件。
- 接著加入檔案寫入拦截。
- 最後才接入外部工具或自動修復。
每一輪都保留上一個可用版本。若新規則造成正常任務無法完成，先回退，而不是在同一個腳本中疊加例外。
[ SECTION_06 ] 遠端 Mac 部署要重新確認執行責任
本機成功不代表遠端 Mac 一定成功。遠端環境常見的差異包括：
- Node.js 或其他執行時版本不同。
- Hook 腳本沒有執行權限。
- 工作目錄由啟動目錄變成另一個專案路徑。
- 非互動工作階段沒有載入互動式 Shell 的環境變數。
- 斷線或重啟後，暫存路徑、日誌路徑或工作區狀態改變。
官方開發文件列出目前儲存庫的 Node.js 前置條件為 22.19 以上或 24 以上，CI 也涵蓋 22.19、24 及 26；文件同時指定 Corepack 管理的 pnpm 版本為 11.7.0，Git 需求為 2.26 或更新版本。這些是官方儲存庫開發環境的核對資料，不應直接當成所有遠端執行環境的最低需求。(github.com)
部署到遠端 Mac 後，按以下順序操作：
- 記錄遠端主機的 Node.js、pnpm、Git 及腳本執行時版本。
- 確認 Hook 腳本以絕對或可驗證的工作區相對路徑存在。
- 以非互動方式啟動一次，檢查環境變數是否真的可見。
- 用低風險工具觸發一次，保存事件摘要及退出結果。
- 執行一次明確拒絕測試，確認工具沒有越過拦截點。
- 重啟遠端 Mac，再重複允許與拒絕測試。
- 檢查工作目錄變化、日誌連續性及回退版本是否仍可用。
遠端 Mac 重啟後 Hooks 是否仍生效？
只有在重啟後重新觸發事件並取得證據，才能回答「仍然生效」。不能只看腳本檔案還在不在。需要重新確認執行時、權限、工作目錄、環境變數及 Hook 註冊狀態。
敏感輸出只保留必要摘要。例如記錄工具類型、結果狀態、工作階段識別及回退版本，不記錄 API 金鑰、完整環境變數或客戶路徑。
若需要先準備一個可控的遠端工作區，可參考 NOVAKVM 的雲端 Mac 方案說明，但 Hook 的事件契約仍須由 DeepSeek Harness 當前版本自行核對。
[ SECTION_07 ] 上線前完成端到端放行驗收
正式開放持續任務前，應建立四類驗收證據：
- 允許任務：符合規則的工具呼叫可以完成，並留下結果記錄。
- 拒絕任務：不符合規則的工具呼叫被擋下，Agent 收到可理解的原因。
- 異常 Hook：腳本錯誤、輸出不完整或執行時不可用時，系統採取已確認的安全策略。
- 恢復任務：修復腳本或回退配置後，正常工具呼叫恢復，且沒有殘留錯誤狀態。
每一筆驗收記錄至少保留：
- Hook 版本或提交識別。
- 工作區名稱及執行環境。
- 觸發事件與匹配工具。
- 輸入摘要及處理結果。
- 失敗原因與回退動作。
- 重啟後的復測結果。
官方指南目前把 dsh 的安裝、建置、Web UI 啟動及工作區選擇分開說明；這種分層也適合用於 Hook 驗收：先確認執行環境，再確認工作區，最後確認事件鏈路，而不是一次把所有問題歸因到配置檔。(github.com)
可把上線判斷簡化成三個條件：
- 四類測試全部有可保存證據：保留試點或擴大一個工具類別。
- 只有允許與拒絕可確認，異常策略不清楚：維持拒絕放行。
- 重啟後事件消失或日誌中斷：先修復遠端交付，不開放持續任務。
[ SECTION_08 ] 本機方案與遠端 Mac 的取捨
本機部署的優點是檔案距離近、權限容易理解，也方便快速改腳本。但長時間執行時，常見缺點是本機重啟會中斷工作、開發者環境差異會污染驗收結果，而且多人共用時很難維持相同的執行時與日誌規則。
一般雲端主機則可能遇到 macOS 工具鏈不完整、遠端桌面與檔案權限分散，以及重啟後工作區與憑據載入順序不一致等問題。對需要 Xcode、macOS 原生工具或遠端持續任務的團隊，這些不是單一腳本能補上的缺口。
較穩妥的做法是先在可控的遠端 Mac 工作區完成四類驗收，再決定是否擴大 Hook 覆蓋面。若需要臨時算力、短期測試環境或重現另一台 Mac 的執行條件，使用 NOVAKVM 的遠端 Mac 會比直接改動長期工作機更容易保留版本、重啟及回退邊界。相關交付前，也可先查看 遠端 Mac 交付條件 與 雲端 Mac 選型說明，再把 Hook 腳本依賴、重啟恢復及日誌留存逐項對照。