前言¶
DeepSeek Harness（DSH）暴露了工具调用的接口，但没有内置审查、指纹验证或统计面板。开发者需要在配置文件里写 hooks.json，但无法确认每次运行的是哪一段代码。这意味着你无法在执行前确认命令是否被篡改，也无法快速查看哪些 Hook 失败或被阻断。
dsh-codex-hooks 把 Codex 的 Hook 管理层移植到 DSH：从配置、插件和项目中发现 hooks.json，对每个 Hook 进行 sha256 指纹校验，在 Composer 中弹出审查对话框，在 Settings 中统一管理信任状态，提供 /hooks 命令和按轮次的运行统计。
这是什么¶
dsh-codex-hooks 是一个 DSH 插件，由 matata2017 维护，分类为工作流。它不改变 DSH 的配置格式，而是围绕 hooks.json 增加审查、信任、开关和统计能力。
它解决的核心问题是：在 DSH 中如何让 Hook 调用保持可审查、可验证、可统计，而不是让命令在黑盒中执行。
核心功能¶
下面介绍它提供的具体能力。
1. 发现并分组 hooks.json¶
插件会在三个位置查找 hooks.json，并在 UI 中分组显示：
- 从 Config：
$DSH_HOME/hooks.json（默认为~/.dsh/hooks.json） - 从 Plugins：当前激活的 profile 中，每个包含
hooks.json的包 - 从 Projects：工作区
.dsh/hooks.json，最多记住 32 个已访问的工作区
所有这些文件中的钩子会在同一个设置页面中列出，按来源分组。
2. sha256 指纹与信任校验¶
插件会对每个 Hook 的定义进行规范化 JSON，然后对其 UTF-8 字节计算 sha256 指纹。信任决策是绑定在指纹上的，而不是绑定在 Hook 名称或命令字符串上。这意味着如果你修改了命令但指纹不变，信任仍然有效；如果你修改了命令导致指纹改变，之前批准的信任会失效，需要重新审查。
3. 审查与批准¶
新 Hook 默认处于“待审查”状态。在 Composer 工具栏会出现一个 Hook 图标，旁边有一个红色圆点表示仍有 Hook 需要审查。点击该图标会打开“审查 Hook”对话框，每一行对应一个 Hook，带有复选框、名称、一个“新”徽章，以及展开的详细信息（来源、类型、命令、超时）。对话框底部提供三个选项：
- 暂不
- 全部允许
- 允许选中的
批准当前指纹后，信任状态会写入 $DSH_HOME/hooks.state.json。
4. 设置页面统一管理¶
在 Settings → Hooks 中，可以看到所有 Hook，按来源分组。每个 Hook 显示信任状态、开关，并提供“信任”和“撤销”按钮，以及一个“测试”按钮用于 dry-run。
5. /hooks 命令与浏览器¶
输入 /hooks 会打开 Hook 浏览器。第一页列出所有事件，标明是否已安装以及是否需要审查（用 ! 标记）。第二页显示某个事件的处理器，列出每个处理器的信任状态、开关和“信任”/“撤销”按钮。这是一个普通 DSH 斜杠命令，不会到达模型。
6. 按轮次的运行统计¶
每个 Assistant 消息的操作行中会出现一个 Hook 图标。点击该图标会打开“Hook 统计”对话框。对话框针对当前消息所属的轮次读取数据，显示该轮次的 Runs / Blocked / Failed 以及会话总览。对话框会每 1.5 秒刷新一次。由于 Hook 输出不会打印到对话中，模型只能看到 additionalContext，统计信息则保留在内存中。
7. 事件与拦截点¶
插件通过以下事件与 DSH 的工具调用接口对接：
agent/pre-step：提交提示后、执行步骤前触发，可阻塞agent/request：发送给模型前触发，不可阻塞tools/pre-execute：工具调用前触发，可阻塞tools/post-execute：工具调用后触发，可阻塞approval/request：工具调用请求权限前触发，可阻塞agent/created：会话开始时触发，不可阻塞agent/turn-stopping：轮次即将结束时触发，不可阻塞session/disposed：会话销毁时触发，默认超时 1 秒，最大 3 秒
插件通过通配符、精确名称或正则表达式匹配事件名称。
8. 上下文注入与超时¶
每个 Handler 可以提供 additionalContext，插件会在 agent/pre-step、tools/pre-execute、tools/post-execute 和 agent/created 时将其附加到模型输入中，默认长度 2500 字符。
默认超时为 600 秒，session/disposed 事件使用 1 秒默认、3 秒最大超时，避免关闭时挂起。
安装与启用¶
资料未提供官方的 dsh plugin add 安装命令，仅说明插件通过 cordis.patch.yml 修补。安装方式见目录页：https://www.skillhub.cn/plugins/matata2017/dsh-codex-hooks
安装后，插件会自动绑定到 DSH 的客户端包，包括 @deepseek-ai/dsh-client-locale、@deepseek-ai/dsh-client-ui-settings、@deepseek-ai/dsh-client-ui-commands 和 @deepseek-ai/dsh-client-ui-chat。
典型用法¶
以下是一个简单的 Echo Hook 示例（来自仓库的 examples/echo-hook.mjs）：
// echo-hook.mjs
export default {
name: 'echo',
events: ['tools/pre-execute'],
async execute(context) {
const { command } = context.toolCall;
console.log('[Hook] Executing:', command);
return {
additionalContext: `Hook echo: Executing ${command}`,
};
},
};
将其放入 $DSH_HOME/hooks.json 或某个插件的 hooks.json 中，启动 DSH 后，在 Composer 中点击 Hook 图标，审查该 Hook，批准指纹，然后在对话中调用工具。Hook 会在控制台打印执行信息，并将 additionalContext 注入给模型。
另一个示例（examples/approval-allow.mjs）展示如何自动批准某个工具：
// approval-allow.mjs
export default {
name: 'auto-allow',
events: ['approval/request'],
async execute(context) {
const { toolCall } = context;
if (toolCall.name === 'search') {
return { decision: 'allow' };
}
return { decision: 'deny' };
},
};
将其加入 hooks.json 后，当模型尝试调用 search 工具时，Hook 会自动返回 allow，无需人工确认；其他工具调用则默认需要人工批准。
适用场景与注意¶
适合在需要严格控制工具调用、希望对每个 Hook 的执行内容进行审查、并希望快速了解 Hook 运行情况的 DSH 场景中使用。
注意：插件以当前 DSH 进程的权限运行，修改 hooks.json 之前应检查源码与许可证（MIT）。
短结尾¶
dsh-codex-hooks 为 DSH 增加了审查、指纹验证、开关控制和按轮次统计的能力，让 Hook 在 DSH 中的行为变得可见、可控。你可以通过目录页查看详情：https://www.skillhub.cn/plugins/matata2017/dsh-codex-hooks；源码位于 GitHub：https://github.com/matata2017/dsh-codex-hooks。
