Skip to content
dsh marketplace

dsh-hooks

Verified

@moon16u/dsh-hooks · v2.1.1 · MIT · Web UI

File-defined DSH command hooks with approval-only UI, read-only details, lifecycle and tool gates

Install

dsh plugin add @moon16u/dsh-hooks

Confirm the layer applied with dsh --profile default --dump-config — see the install guide.

Source

Published to npm without a public repository. Inspect the package contents before installing.

Tags

Readme

dsh-hooks

English | 中文

@moon16u/dsh-hooks 执行由配置文件声明的命令钩子。每条定义在显式批准前都不生效， 审批页除完成授权所需的状态操作外全为只读。

只读详情与审批

入口：插件 → 已安装 → 内置插件配置 → 钩子。

页面按“来自项目/用户/Profile 配置文件”分组。点击项目卡片查看事件列表，展开钩子后 显示命令、匹配器、超时和执行方式；“更多配置”包含来源、执行目录、输出预算、固定内容 文件、环境变量名及定义指纹。

事件内使用紧凑编号行，右侧放配置文件入口、展开按钮和启停开关。展开后优先展示 Hook 类型、命令、匹配器、超时四项；执行方式等其余字段在“更多配置”中， 撤销批准保留在展开区域，不占用折叠列表。

配置文件入口调用宿主的默认应用，不是浏览器所在设备的文件系统；Profile 内联声明 没有文件入口。打开文件不会批准或执行钩子。

状态操作只有批准、启停和撤销批准。点击未批准钩子的药丸开关，会展开四项基本信息和 折叠的“更多配置”，此时尚未启用；点击下方“批准”即批准并启用，不重复展示配置， 不需要勾选，也没有第二次确认。批准前后台校验定义指纹与一次性审批凭据， 来源文件禁用和总开关限制始终有效。批准只对后续匹配事件生效，不会立即执行命令。 页面没有新增、编辑、删除、JSON 编辑或保存入口。

隔离样例截图：桌面 · 窄屏。

声明与权限

钩子定义只在文件中维护：

  • 项目：最近 Git 根目录的 .dsh/hooks.json；没有 Git 上级时使用会话目录。
  • 用户：$DSH_HOME/hooks.json，默认 ~/.dsh/hooks.json。
  • Profile：profile patch 中的 commandHooks JSON 字符串。

三类来源累加，任何定义文件都不能授予信任。批准绑定精确定义、实际执行目录和指定的 固定内容文件；定义或文件内容变化后需重新批准。界面只更新宿主的审批与启停账本， 不改写声明文件。账本位于 $DSH_HOME/workspace-hooks/<profile-hash>.json， POSIX 使用 0600，Windows 继承目录 ACL；Windows 用户须限制该目录的访问权限。 同一 profile 只应由一个 DSH 进程写入。

引擎默认可用，未经批准的命令不执行。文件中设置 commandHooksEnabled: false 会禁用所有命令，包括已批准的命令；界面只显示该状态，不提供修改入口。

受信任命令以 DSH 系统用户身份运行，没有独立钩子沙箱，也不经过逐次工具审批。 批准前请阅读 SECURITY.md。除非接受明文存储，不要把密钥写进命令或 env。 完整的事件映射、字段、输入输出与错误语义见 command-hooks.md。

安装

包名为 @moon16u/dsh-hooks，profile 配置 ID 为 dsh-hooks。

dsh plugin --profile web add @moon16u/dsh-hooks

若从本地检出使用，改为挂载包目录，改动源码无需重新发布：

dsh plugin --profile web add "link:/path/to/dsh-pouch/packages/dsh-hooks"

宿主代码更新后重启 DSH，再刷新页面。集成目标为 DSH 0.2.1-rc.2， 支持 Linux/WSL、macOS 和 Windows。默认 shell: "auto" 在 Linux/macOS 使用 Bash， Windows 依次查找 PowerShell 7 标准安装路径、PATH、Windows PowerShell 5.1。 shell: "bash" 或 "pwsh" 可显式指定；相应 shell 必须安装在 subprocess 执行环境中。 Windows 上保留 Bash 脚本时需设置 shell: "bash" 并保证 Bash 在 PATH 中； 命令语法不会自动转换。不保证未经验证的后续宿主版本兼容。无需修改 DSH 宿主本身。

升级后归一化定义新增 shell 字段，原有批准指纹失效，钩子需重新审阅批准，不自动迁移授权。 PowerShell 调用原生程序时需用 exit $LASTEXITCODE 传递退出码，包括阻断用的退出码 2。

测试

node --test test/*.test.mjs
# 复用已安装官方 runtime，仅运行临时无害命令
DSH_RUNTIME_ROOT=/path/to/dsh/node_modules node test/official-runtime.mjs

默认测试包含官方 subprocess 的隔离原生命令，Hooks Native Platforms CI 覆盖 Ubuntu、Windows、macOS，包括 JSON/Unicode、退出码、超时与取消、后代进程清理、 环境清理、信任和账本持久化；Windows 额外测试 PowerShell 5.1 回退。 测试不使用正式 DSH profile、凭据或模型端点。

集成脚本使用已安装的官方 subprocess 服务与临时无害命令，旧脚本显式选择 Bash， 需已安装 Bash。其中适配器映射一组仅在 DSH_HOOK_TEST_FIXTURE 指向含一个 .mjs 适配器与一个 .sh 同级的目录时运行， 不假定任何项目路径。默认测试不发起网络请求，也不调用模型。 官方源码依据和平台限制见 platforms.md， 历史设计说明见 design.md。