前言¶

在 DeepSeek Harness（DSH）裏做智能體開發時，常見需求是：會話開始寫日誌、工具執行前做本地校驗、空閒時發桌面通知。這些動作往往靠外部腳本或硬件橋接，配置分散，也不一定能對齊 DSH 自身的工具執行時機。

@abworks/dsh-hooks（倉庫 abworks-dev/dsh-hooks）是維護者 abworks-dev 發佈的工作流類插件：在 Host 內按會話事件管理本地自動化命令，提供顯式啓停、工具前置攔截（僅 PreToolUse）與有限執行記錄，不依賴 AU05、Ulanzi Studio 等硬件。界面目前以中文爲主；0.1.0 爲早期版本，README 建議在非生產會話先試用。

這是什麼¶

插件包名 @abworks/dsh-hooks，許可證 MIT，要求 Node.js ≥ 22。它在 DSH 的 賬號菜單 → 設置 → 鉤子 提供事件分組、命令編輯、全局與單項開關、最近執行記錄。配置保存在插件自有 storage domain；執行記錄僅存內存，最多 100 條，重啓後丟失。

與 @abworks/dsh-studio-hook（硬件/Studio 橋）相互獨立：本插件不讀取舊硬件綁定或配對配置；只需本地自動化時可單獨安裝，兩者可共存，但應避免重複轉發同一通知。

核心功能¶

七類會話事件¶

只有 PreToolUse 能阻止工具：命令正常結束且退出碼非 2 時不阻斷；退出碼 2 或超時、輸出超限、啓動失敗等執行異常在該事件上會拒絕工具。其餘事件僅通知。

執行邊界與安全取向¶

• 默認不執行：全局與新規則默認關閉；修改規則後需重新啓用。
• 命令協議：絕對路徑 + argv，shell: false；Windows 不接受 .cmd/.bat，需明確指定解釋器。工具名匹配爲簡單 glob（*、?），區分大小寫，不是 Codex 正則。
• stdin：JSON 對象，含 hook_event_name、session_id、tool_name 等；當前不傳提示正文、工具參數、結果或憑據，腳本無法做基於具體命令內容的 Codex 式策略檢查。
• 限制：超時 100–30000 ms；stdout/stderr 合計上限 256–65536 字節；全局最多同時 4 個命令；子進程環境清空，不繼承 Host 憑據；cwd 未切到會話項目目錄。
• 模型側：不向模型提供創建、啓用或執行鉤子的工具，不自動批准權限。管理接口僅允許 Host 所連本地所有者瀏覽器。

借鑑 Codex Hooks 的事件命名與設置頁分組體驗，但不是 Codex 插件；正式文檔列出的 14 個事件中，本版實現上表 7 個，且僅支持 command 類型 handler，無 hooks.json 導入、正則 matcher、JSON 決策重寫等。詳見 README「與 Codex 對齊的範圍」。

安裝與啓用¶

方式一：Release 包（推薦）¶

1. 打開 Releases，下載 abworks-dsh-hooks-0.1.0.tgz。
2. 在 DSH 插件管理器中，用本地包路徑安裝該 TGZ 並啓用插件。
3. 進入 賬號菜單 → 設置 → 鉤子；若入口未出現，刷新當前 DSH 頁面。

方式二：從 GitHub 安裝¶

在 DSH 插件管理器的安裝輸入中填寫：

github:abworks-dev/dsh-hooks#v0.1.0

源碼可直接運行，無需編譯；項目目前通過 GitHub 分發，尚未發佈 npm，不能假定只填 npm 包名即可安裝。README 記載參考驗證環境爲 Windows / DSH 0.2.1-rc.5；其他系統與 DSH 版本尚未現場驗證。

第一次配置¶

1. 保持全局執行關閉，選擇事件並「添加」。
2. 填寫可信可執行文件的絕對路徑、JSON 字符串數組參數、簡單 glob 匹配、超時和輸出上限。
3. 保存後審閱腳本內容，顯式啓用該鉤子，再打開全局執行開關。
4. 在真實會話觸發事件後刷新，查看最近執行記錄。保存、刷新均不會試跑命令。

關閉全局執行可停止後續觸發；卸載或禁用插件會取消運行中的子進程。

典型用法：最小 hook 腳本¶

可執行文件填本機 Node 的絕對路徑，參數填腳本絕對路徑，例如 ["/absolute/path/hook.mjs"]。腳本從 stdin 讀 JSON，在 PreToolUse 上可用退出碼 2 拒絕工具。

// hook.mjs：只演示協議，不是安全策略模板
let text = '';
for await (const chunk of process.stdin) text += chunk;
const event = JSON.parse(text);
console.log(`${event.hook_event_name}: ${event.tool_name}`);

stdin 示例形態：

{"hook_event_name":"PreToolUse","session_id":"agent-id","tool_name":"ops_bash","timestamp":0,"source":"dsh","payload_version":1}

stdout/stderr 僅供設置頁記錄查看，不注入模型上下文。

適用場景與注意¶

適合：需要在 DSH 生命週期節點（會話起止、入隊、工具前後、idle、權限請求觀察）觸發本機通知、日誌或集成腳本，且希望用 UI 統一管理規則與開關的開發者。

務必注意：

• 鉤子以 Host 用戶身份運行，可讀本機文件、訪問網絡；空環境不是沙箱。安裝前請閱讀源碼與 SECURITY.md，不要運行不可信腳本。
• 鉤子只覆蓋 DSH 公開工具執行通道，不是完整安全沙箱或所有插件副作用的邊界。
• 腳本文件在外部變更不會自動檢測，需自行審閱後再啓用。

社區目錄頁：skillhub.cn/plugins/abworks-dev/dsh-hooks（獨立站點，與 DeepSeek / 幻方無官方從屬關係）。問題反饋見 Issues，請勿公開令牌與會話正文。

結尾¶

dsh-hooks 把「按事件跑本地命令」收進 DSH 設置頁：默認關閉、顯式啓用、PreToolUse 可攔截工具，其餘事件只做通知。若你已在用 DSH 做智能體工作流且不想綁硬件，可先按 Release 或 GitHub 引用安裝，在非生產會話裏配一條無副作用規則驗證執行記錄，再逐步擴展腳本。

• 目錄：https://www.skillhub.cn/plugins/abworks-dev/dsh-hooks
• 源碼：https://github.com/abworks-dev/dsh-hooks