Hooks
Hooks 在 Agent 生命週期事件上執行配置的動作。EvoX 擴展中的 Hooks 頁面用於查看、診斷和重新掃描配置,幫助確認執行來源與 shell 風險;它不是 Hook 編輯器或運行中熱重載入口。
查看實際來源
打開 擴展 > Hooks,按事件、匹配條件和作用域檢查條目。頁面讀取桌面所用的 Claude Code 風格生命週期配置,包括用戶、項目與管理員管理範圍。
| 來源 | 檢查重點 |
|---|---|
| 用戶配置 | Agent 目錄下的 settings.json,影響該用戶範圍 |
| 項目配置 | 對應項目範圍的 settings.local.json,核對實際項目目錄 |
| 管理配置 | 管理員部署的系統配置,應用內按只讀方式檢查 |
界面顯示事件、匹配條件、作用域、解析狀態以及命令的 shell 風險。命令展示經過長度限制和脱敏;展示文本不能替代對原配置及腳本的檢查。
判斷是否適合使用
適合 Hook 的動作包括在明確事件後運行範圍受控的檢查或記錄。需要人工判斷、外部寫入、發佈或消費的操作,仍保留各自的授權與驗證流程。
在配置動作前確認:
- 事件是
PreToolUse、PostToolUse、UserPromptSubmit、Stop等生命週期中的哪一個。 - 匹配條件會覆蓋哪些調用,是否意外擴大到所有工具。
- 命令讀取哪些輸入、寫到哪裏、訪問哪些網絡資源。
- 超時、失敗和重複觸發如何影響後續任務。
- 日誌是否包含提示、文件內容或憑證。
這些 Hook 具備 shell 執行影響。來源不明的命令不因出現在配置列表中就變成可信動作。
示例:檢查一次文件編輯後的語法
下面是項目配置中的 Hook 結構,放入負責該項目的配置文件。把命令中的兩個路徑替換為實際 Node.js 可執行文件與待檢查文件的絕對路徑,並保留該文件中的其他配置:
{
"hooks": {
"PostToolUse": [{
"matcher": "Write|Edit",
"hooks": [{
"type": "command",
"command": "\"/absolute/path/to/node\" --check \"/absolute/path/to/project/src/example.mjs\""
}]
}]
}
}
本例在匹配的文件寫入或編輯工具事件後檢查固定文件的 JavaScript 語法,不自動檢查每個被編輯文件,也不執行該模塊。路徑含空格時按所用 shell 正確引用。先在目標運行環境中手動執行這條命令,確認文件存在且 Node 可用,再交給 Hook。
保存後重新掃描,在條目中核對 PostToolUse、Write|Edit、來源和命令。按 Agent 的加載流程重啓或加載配置,再讓它對測試文件完成一次編輯,核對該次處理命令的實際輸出。掃描列表出現條目只證明配置被發現。
| 故障 | 檢查位置 |
|---|---|
| 掃描解析失敗 | 對應來源文件的 JSON 與 Hook 結構 |
| 發現條目但沒有觸發 | 運行中的配置是否已加載,事件與工具名稱是否匹配 |
| 命令退出失敗 | 絕對路徑、shell、依賴和語法錯誤輸出 |
| 每次調用都被觸發 | matcher 是否寫得過寬,以及事件是否選錯 |
測試結束後移除這條示例 Hook 並重新加載對應 Agent,避免後續編輯繼續檢查同一個演示文件。
修改後分別驗證磁盤與運行時
修改由該配置的所有者完成;Hooks 頁面不負責寫回配置文件。修改前保留原內容,先檢查格式、命令和腳本,再保存到正確作用域。
選擇重新掃描後,頁面重新讀取磁盤,並更新發現條目與解析診斷。重新掃描不重載正在運行的 Agent Hook 表。 按承載該 Agent 的啓動流程重新加載或重啓,再用一個範圍明確的事件檢查實際效果。
不要把 /hooks reload 當作已經可用的運行時重載接口。配置已保存、掃描成功與動作實際生效需要分別確認。
處理異常與停用
解析失敗時先檢查失敗作用域;不能把列表缺項當作沒有 Hook。重新掃描失敗時,核對最後成功掃描時間,舊列表不代表新配置讀取成功。
停用時修改真實來源配置,並按運行時加載流程驗證。停止某條 Hook 不等於撤銷它已產生的文件、網絡操作或外部授權。需要恢復時使用修改前保留的配置及任務記錄。