前言¶
在 DSH（DeepSeek Harness）里，生命周期钩子通常写在 hooks.json 里：哪个事件触发、matcher 怎么配、实际执行什么命令、超时多少，都要靠读文件或对照文档才能核对。Codex Desktop 一类客户端会在设置页把钩子按事件分组展示；纯 CLI 或只开 JSON 时，改错 matcher、漏配事件往往要到运行时才暴露。
下面介绍社区插件 dsh-hook（维护者 mikazuhe13-ui，GitHub 仓库 mikazuhe13-ui/dsh-hook）。它在 DSH 图形界面的设置侧栏增加一级「钩子」入口，读取本机已配置的 hooks.json，按固定顺序列出七种生命周期事件及每条钩子的命令、matcher、超时与状态信息。插件本身不负责拦截工具调用，只解决「看得见、对得上配置」这一层；要让钩子真正生效，仍需配合 DSH 官方的钩子桥包。
这是什么¶
dsh-hook 是 DSH 的 lifecycle hooks 设置面板插件（分类：工作流）。定位可以概括为：在 GUI 里列出 hooks.json 中的钩子，展示风格对齐 Codex Desktop 的钩子页；自动探测常见路径，也支持在插件配置里显式指定文件位置。
当前仓库版本为 0.3.2，许可证 MIT；要求 DSH 内核 @deepseek-ai/dsh >=0.2.0-rc.1，Node ^22.19.0 || >=24.0.0。
核心功能¶
七种事件全覆盖¶
面板按固定顺序展示以下事件；未配置的事件会以灰色提示，避免误以为「没有这类钩子」：
- SessionStart（README 提到含会话上下文注入的示例脚本场景）
- PreToolUse
- PostToolUse
- UserPromptSubmit
- Stop
- SubagentStart
- SubagentStop
每条钩子展示什么¶
对已经写入 hooks.json 的条目，界面会显示 statusMessage、完整命令、matcher、timeout 以及类型等字段，便于和文件内容逐项对照。
hooks.json 从哪里来¶
默认按顺序自动探测：
$DSH_HOME/hooks.json~/.claude/hooks.json~/.codex/hooks.json
若你的钩子文件不在上述路径，可在插件的 cordis.patch.yml 里设置 hooksPath（见下文「配置」）。
性能与主题¶
- 零后台常驻开销：宿主侧按需读文件（README 描述为约 1 KB 级）；客户端仅在设置页打开时以 15 秒间隔轮询刷新。
- 主题跟随：颜色使用
color-mix(in srgb, currentColor)，浅色、深色、透明主题均可适配。
设置页集成¶
通过 settings.section 槽位注册，侧栏设置页会出现一级 「钩子」 section；与 @linxin666/dsh-usage 等同类 settings 插件可共存（本插件 order 为 152，排在 usage 之后）。
安装与启用¶
安装方式以仓库 README 为准：在 DSH profile 目录（<dsh-home>/profiles/<name>/）里改依赖并启用 bundle，而不是凭插件名拼接 CLI 命令。
方式一：从 GitHub（推荐）¶
- 在 profile 的
package.json的dependencies中加入（将<你的用户名>换成实际 fork 或上游用户名；若直接使用维护者仓库，则为github:mikazuhe13-ui/dsh-hook）：
"dsh-hook": "github:<你的用户名>/dsh-hook"
-
在
dsh.profile.bundles数组中加入"dsh-hook"。 -
在 profile 目录执行：
pnpm install
- 重启 DSH。
方式二：本地 link 开发¶
"dsh-hook": "link:D:/path/to/dsh-hook"
README 提醒：pnpm 对 scope 名与 link: 组合可能报 ERR_PNPM_INVALID_DEPENDENCY_NAME，请使用无 scope 的包名 dsh-hook。
配置¶
在插件自带的 cordis.patch.yml 中，可通过 patch 插入 hooksPath，覆盖自动探测：
- insert:
- id: hooks-panel
name: 'dsh-hook'
config:
hooksPath: 'D:\my\dsh-home\hooks.json'
不写 hooksPath 时，行为即为前述三条路径的顺序探测。
典型用法与配套组件¶
面板只负责显示¶
README 明确：本插件只做显示。若要在工具调用前真正拦截（例如守卫规则），需要安装 DSH 官方的钩子桥，并与内核版本 tag 对齐：
仓库 examples/hook-guard.ps1 提供守卫脚本示例（README 举例：拦截递归删除、C 盘写入、环境变量枚举等），可与 hooks.json 中的命令字段配合使用；具体 matcher 与命令以你本机配置为准。
架构上如何工作（便于排查）¶
宿主半 lib/index.js 读取 hooks.json（显式路径或自动探测），注册 GET /api/dsh-hook/overview。客户端半 lib/client.js 在设置页打开时 fetch 该接口并做纯 DOM 渲染（React ref 挂载，插件不走 TypeScript 构建链）。理解这一点有助于区分「面板空白是文件路径问题还是 API/客户端问题」。
适用场景与注意¶
适合谁
- 已在 Claude/Codex/DSH 生态里维护
hooks.json，希望在 DSH GUI 里统一查看七种事件与每条规则细节的开发者。 - 需要与 Codex Desktop 钩子页类似的信息密度，又不想每次手开 JSON 编辑器的场景。
务必注意
- 权限与安全：插件以当前 DSH 进程权限读取本机
hooks.json并展示其中的 shell 命令；安装前应阅读源码与 MIT 许可证，确认来源为 GitHub 仓库 或你信任的 fork。 - 显示 ≠ 执行：未安装
@deepseek-ai/dsh-hooks-claude-code（或等价钩子桥）时，面板仍可能列出配置，但运行时拦截行为取决于 DSH/客户端实际加载的钩子链路。 - 社区生态：DSH 社区插件目录托管在独立站点（如 SkillHub 目录页），与 DeepSeek / 幻方无官方从属关系；星标、下载量等以各站点当时数据为准（目录抓取时 GitHub 星标为 0）。
结尾¶
经过上面的步骤，你可以在 profile 里启用 dsh-hook，在设置页的「钩子」一节对照 hooks.json 的七种事件与每条命令、matcher、超时；需要真正守卫工具调用时，再叠加官方 dsh-hooks-claude-code 与仓库示例脚本。
