前言¶
在 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 为准。
