前言¶
在 DeepSeek Harness（DSH）裏跑智能體會話時，工具調用失敗、權限彈窗、上下文壓縮等事件往往在終端或 Web UI 裏一閃而過。若只靠肉眼盯屏，很難在合適時機觸發通知、Webhook 或本機腳本。社區裏也有用外部進程輪詢日誌的做法，但和 Session 生命週期脫節，也難以按項目區分策略。
下面介紹 dsh-notice-hooks：在 DSH 內爲「用戶級」和「項目級」兩個作用域註冊命令型 Hook，在 session、tool、permission、context-compaction 等事件上執行你聲明的命令；是否在運行時真正執行，需在 Hooks setting（簡體中文界面爲 Hooks 設置）裏顯式授權。插件由 oliverCJ 維護，在 SkillHub 目錄中歸類爲工作流；當前 npm 包版本爲 0.1.2，許可證 MIT。
這是什麼¶
dsh-notice-hooks 的定位是：爲 DeepSeek Harness 配置自動化 Hook，在用戶與項目兩個作用域下，於生命週期事件觸發時運行外部命令，並在設置界面中手工管理每條命令的授權指紋。
它不替代 DSH 自帶的工具執行或權限模型；Hook 命令以當前 DSH 進程權限運行，安裝與啓用前應自行查看 GitHub 倉庫 源碼與許可證。
核心功能¶
依據官方 README，插件提供的能力可概括爲以下幾點。
事件與命令型 Hook¶
配置項 hooks 按受支持的事件名分組。每個事件下可配置多組 matcher（可選、大小寫不敏感的正則）；組內可掛多條 type: "command" 的 Hook，指定 command、timeoutMs（默認 10000，範圍 100–60000）、maxConcurrent（默認 1，範圍 1–4）等。
文檔示例在工具失敗場景使用 PostToolUseFailure，並用 matcher 限定 bash、edit 等工具名。
用戶作用域與項目作用域¶
- 用戶配置固定爲
~/.dsh/hook.json，對所有項目生效；文件不存在時，用戶 Store 會創建空配置（無已啓用 Hook）。 - 項目配置固定爲
<workspace-root>/.dsh/hook.json，僅對已註冊的 DSH 工作區根目錄生效；插件不會自動創建項目側hook.json或.dsh目錄。
在已註冊工作區的會話中，先執行匹配的用戶 Hook，再執行匹配的項目 Hook；同一文件內保持文檔順序。用戶與項目配置獨立校驗：某一作用域 JSON 無效時，僅該作用域 Hook 停止，不影響 Agent 或工具執行。
顯式授權與配置熱加載¶
在配置裏寫 enabled: true 只表示「允許被啓用」，不等於已授權執行；授權須在 Hooks setting 或會話審查對話框中由用戶明確確認當前命令指紋。
插件監視配置文件並自動重載。無效 JSON、無效正則、重複 id 等會失敗關閉：該作用域內 Hook 在配置恢復有效前不運行。
Profile 與可選能力¶
| Profile | 安裝方式 | Host Hooks | Web Settings |
|---|---|---|---|
web |
CLI dsh plugin --profile web add ... |
是 | 是 |
desktop |
僅 Electron Settings → Plugins | 是 | 是（內嵌 Web UI） |
tui |
CLI dsh plugin --profile tui add ... |
是 | 否 |
headless |
CLI dsh plugin --profile headless add ... |
是 | 否 |
Desktop 配置不能用普通 dsh plugin --profile desktop 管理（該命令會被拒絕）。
workspaceRegistry 可選：有則暴露已註冊項目作用域，無或無效時僅用戶作用域。@deepseek-ai/dsh-session 的 plugin-record 運行時可選；無法解析時 Hook 與授權仍可用，僅緊湊的 Chat 活動行會禁用並出現一條 Host 警告。
推薦搭配：CC Notice¶
README 建議可與 CC Notice 配合：本插件負責生命週期 Hook 與命令授權，CC Notice 可將 DSH 事件轉爲桌面通知、聲音、Webhook 或硬件反饋；命令授權仍由你在 Hooks setting 中控制。
環境與依賴¶
啓用前請確認目標 Host profile 具備可用的 Session 與持久化棧，並滿足：
- DeepSeek Harness 與 Node.js ≥ 24.9.0
@deepseek-ai/dsh-session：>=0.2.1-rc.1 <0.2.2或>=0.2.2-0 <0.3.0（Chat 活動反饋需要官方 plugin-record API）- 從源碼構建時需要 pnpm 11.28.5
DSH 生態採用「一切皆插件」思路；SkillHub 插件目錄 爲社區站點，與 DeepSeek / 幻方無官方從屬關係。目錄頁與 GitHub 上該倉庫星標均爲 0（以你訪問時頁面爲準）。
安裝與啓用¶
各 DSH profile 的插件安裝相互獨立，請裝在實際使用的 profile 上。
Desktop¶
- 在 DeepSeek Harness 中打開 Settings → Plugins。
- 搜索
dsh-notice-hooks。 - 從 npm 安裝並啓用。
- 打開 Hooks setting。
CLI profile（web / headless / tui）¶
命令使用用戶配置的 npm registry；鏡像若滯後於官方 npm，勿單獨向鏡像發佈該包。
dsh plugin --profile web add dsh-notice-hooks
dsh plugin --profile headless add dsh-notice-hooks
dsh plugin --profile tui add dsh-notice-hooks
安裝之後¶
- 參考倉庫內
examples/hook.json創建或編輯~/.dsh/hook.json。 - 在 Hooks setting 中重新加載配置。
- 啓用需要的 Hook 配置項。
- 檢查命令內容，並對當前執行指紋顯式授權。
從 npm 安裝非 Desktop 場景時，無需自行 git clone；若你已有官方發佈的 tarball，可按 README 用 dsh plugin --profile web add ./dsh-notice-hooks-0.1.2.tgz 等形式安裝（版本號以包文件名爲準）。
典型配置示例¶
下面步驟說明如何聲明一條在工具失敗時運行的命令 Hook。請將示例中的絕對路徑換成你本機真實腳本路徑，啓用前在設置裏完成授權。
配置文件頂層 version 必須爲 1。id 在同一文件內必填且唯一；用戶與項目文件可複用相同展示用 id，但各自文件內不能重複。
{
"version": 1,
"hooks": {
"PostToolUseFailure": [
{
"matcher": "^(bash|edit)$",
"hooks": [
{
"id": "notify-tool-failure",
"type": "command",
"command": "node \"/absolute/path/to/notify.mjs\" --failed",
"enabled": true,
"timeoutMs": 10000,
"maxConcurrent": 1
}
]
}
]
}
}
matcher 省略或爲空時匹配所有值。未知字段在通過 Settings 修改 enabled 時會被保留。
需要項目級策略時，在已註冊工作區根目錄編寫 .dsh/hook.json，結構與用戶級相同；不要在未註冊目錄指望插件向上掃描父路徑。
適用場景與注意¶
適合誰：希望在 DSH 生命週期事件（會話、工具、權限、上下文壓縮等）上掛接本機腳本或通知鏈路，且願意在 UI 裏逐條授權命令指紋的開發者與團隊。
務必注意：
- Hook 命令與 DSH 同進程權限運行；只配置你信任的命令，並覈對
command與授權指紋。 - 配置錯誤時該作用域 Hook 全部暫停，直到修復 JSON/正則/
id等問題。 - TUI、headless 無 Web Settings，但仍可使用 Host Hooks；項目級 Hook 在 headless 下需要 workspace provider。
- 僅當需要 Chat 活動緊湊行等能力時，再關心
dsh-session版本區間是否滿足 README 要求。
結尾¶
dsh-notice-hooks 把「何時跑什麼命令」收口到 hook.json 與 Hooks setting，用用戶/項目雙作用域和顯式授權，在 DSH 工作流裏補齊事件驅動的自動化入口。查閱目錄說明可打開 SkillHub：dsh-notice-hooks；安裝命令、配置字段與 Profile 表格以 GitHub：oliverCJ/dsh-notice-hooks README 爲準。
