前言¶

在 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