dsh-hooks 0.2.2 → 0.3.0

package/README.md

@@ -4,7 +4,7 @@ Config-driven lifecycle hooks plugin for [DeepSeek Harness](https://github.com/d
 
 Declare `event -> command` hooks directly in your profile's `cordis.patch.yml` — like Codex CLI / OpenCode hooks, but for dsh. No plugin code required.
 
-[中文文档](README.zh.md) | [Design](#design) | [Feishu example](examples/notify-feishu.mjs)
+[中文文档](README.zh.md) | [Design](#design) | [Feishu example](examples/notify-feishu.mjs) | [Web GUI 面板](packages/dsh-hooks-ui/README.md)
 
 ## Install
 
@@ -31,15 +31,57 @@ Add a config block to your profile's `cordis.patch.yml`:
         timeoutMs: 10000             # optional, default 10000
       - on: 'approval/asked'
         run: 'powershell -Command "Write-Output approval-requested >> hooks.log"'
+      - on: 'tool/call'
+        match:                       # optional: field → regex, all must match
+          tool: '^(rm|git|ssh)'
+        run: 'node examples/notify-webhook.mjs --slack'
+      - on: 'turn/end'
+        when: 'completed'
+        run: 'node examples/notify-feishu.mjs'
+        retries: 2                   # optional: retry non-zero exits (default 0)
+        retryDelayMs: 1000           # optional: base retry delay, doubles (default 500)
+      - on: 'turn/end'
+        input: 'stdin'               # optional: write the full context JSON to stdin
+        run: 'node my-hook.mjs'
+      - on: 'approval/asked'
+        notify:                      # built-in notification: instead of run, no script needed
+          channel: 'desktop'         # platform balloon/toast
+      - on: 'turn/end'
+        when: 'completed'
+        notify:
+          channel: 'webhook'         # POST JSON to any HTTP endpoint
+          url: 'https://hooks.slack.com/services/…'
+          slack: true                # optional: { text } one-line summary (Slack style)
 ```
 
+Every hook field:
+
+| Field | Meaning | Default |
+| --- | --- | --- |
+| `on` | triggering event (see the event table) | required |
+| `when` | filter `turn/end` by end reason | all reasons |
+| `match` | field → regex, all must match; fields are context keys (`tool` / `sessionName` / `sessionId` / `error` / `source` / `cwd` / `content` / `reason`, …), a field absent from the context never matches | no filter |
+| `run` | command spawned through the platform shell (exactly one of `run` / `notify`) | one of the two required |
+| `notify` | built-in notification (exactly one of `run` / `notify`): `channel: webhook` (HTTP JSON; omit `url` to use `DSH_HOOKS_WEBHOOK_URL`, `slack: true` for a one-line summary) or `channel: desktop` (platform balloon/toast) | one of the two required |
+| `input` | `env` passes only the `DSH_HOOK_*` variables; `stdin` additionally writes the full context JSON to the command's stdin | `env` |
+| `timeoutMs` | per-run timeout (ms); the process tree is terminated on expiry | 10000 |
+| `retries` | retry count for non-zero exit codes (spawn failures and timeouts never retry) | 0 |
+| `retryDelayMs` | base delay between retries (ms), doubles per attempt | 500 |
+
 ## Events (v1)
 
 | Event | When it fires | Useful context |
 | --- | --- | --- |
 | `turn/start` | A turn begins | session id, turn |
-| `turn/end` | A turn ends (`completed` / `error` / `aborted` / `blocked` / `max-tokens` / `interrupted`) | reason, turn, duration |
+| `turn/end` | A turn ends (`completed` / `error` / `aborted` / `blocked` / `max-tokens` / `interrupted`) | reason, turn, duration, content, turn token usage |
+| `step/end` | One step of a turn ends (one model call plus its tool executions) | turn, step |
+| `tool/call` | The model requests one tool invocation | tool name, call id, raw arguments JSON |
+| `tool/result` | A tool call completes | tool name (resolved), result text, failure identity |
+| `user/message` | A user-role message appears on the surface | source kind (`user` / `plugin` / …), message text |
 | `approval/asked` | A tool call requests user approval | tool name, call id, reason |
+| `session/title` | The session title updates (explicit rename / LLM title / fallback) | new title, source kind |
+| `session/created` | A session is published | session id, cwd |
+| `session/disposed` | A session leaves the registry | session id, cwd |
 | `agent/created` | An agent is published | session id |
 | `agent/disposed` | An agent leaves the registry | session id |
 | `agent/error` | The agent loop reports an error | error text |
@@ -49,7 +91,7 @@ The `when` filter for `turn/end` matches the `reason.kind` value (`completed`, `
 
 ## Command execution
 
-- Each matching hook spawns `run` through the platform shell, **fire-and-forget**: failures only `console.warn`, never retried, never block the agent loop.
+- Each matching hook spawns `run` through the platform shell, **fire-and-forget**: failures only `console.warn`, never retried by default (`retries` opts into background retries of non-zero exits), never block the agent loop. Command stdout/stderr is captured (64 KiB per stream); on a non-zero exit the stderr tail is appended to the warning log.
 - Context is passed via **environment variables** (no shell injection through data):
 
 | Variable | Meaning |
@@ -57,18 +99,91 @@ The `when` filter for `turn/end` matches the `reason.kind` value (`completed`, `
 | `DSH_HOOK_EVENT` | event type, e.g. `turn/end` |
 | `DSH_HOOK_SESSION_ID` | session id |
 | `DSH_HOOK_SESSION_NAME` | readable session title (latest `session/title` log event, or first human prompt) |
-| `DSH_HOOK_TURN` | turn number (turn events) |
+| `DSH_HOOK_CWD` | session working directory |
+| `DSH_HOOK_TURN` | turn number (turn / step / tool events) |
+| `DSH_HOOK_STEP` | step number (step / tool events) |
 | `DSH_HOOK_REASON` | turn end reason kind |
-| `DSH_HOOK_TOOL` | tool name (approval events) |
-| `DSH_HOOK_CALL_ID` | tool call id (approval events) |
+| `DSH_HOOK_TOOL` | tool name (approval / tool events) |
+| `DSH_HOOK_CALL_ID` | tool call id (approval / tool events) |
+| `DSH_HOOK_TOOL_ARGS` | raw tool arguments JSON (tool/call) |
+| `DSH_HOOK_TOOL_ERROR` | tool failure identity `name: code` (tool/result errors) |
+| `DSH_HOOK_SOURCE` | message / title source kind (`user`, `plugin`, `fallback`, `provider`, …) |
 | `DSH_HOOK_DURATION_MS` | turn duration ms (turn/end) |
 | `DSH_HOOK_STATUS` | agent status (`agent/status`) |
 | `DSH_HOOK_ERROR` | error text (`agent/error`, and the failure message on `turn/end` error) |
-| `DSH_HOOK_CONTENT` | the turn's final assistant text (turn events) |
+| `DSH_HOOK_CONTENT` | event content snapshot: turn assistant text, tool result text, user message text |
+| `DSH_HOOK_USAGE_INPUT_TOKENS` | aggregated input tokens of the turn (turn/end, summed across steps) |
+| `DSH_HOOK_USAGE_OUTPUT_TOKENS` | aggregated output tokens of the turn |
+| `DSH_HOOK_USAGE_CACHE_READ_TOKENS` | aggregated cache-read tokens, when reported |
+| `DSH_HOOK_USAGE_CACHE_WRITE_TOKENS` | aggregated cache-write tokens, when reported |
+| `DSH_HOOK_USAGE_REASONING_TOKENS` | aggregated reasoning tokens, when reported |
 | `DSH_HOOK_TIMESTAMP` | ISO timestamp |
 
 - `{{var}}` placeholders inside `run` are substituted from the same context, e.g. `run: 'echo {{DSH_HOOK_SESSION_ID}} >> log.txt'`.
 
+## Generic webhook example
+
+Besides Feishu, `examples/notify-webhook.mjs` posts the full hook context as one JSON document to any HTTP endpoint — Slack incoming webhooks, Discord, Lark/DingTalk custom bots, ntfy, Bark, n8n:
+
+```yaml
+- id: dsh-hooks
+  name: dsh-hooks
+  config:
+    hooks:
+      - on: 'turn/end'
+        when: 'completed'
+        run: 'node examples/notify-webhook.mjs --url https://hooks.slack.com/services/…'
+      - on: 'tool/result'        # alert on tool failures
+        run: 'node examples/notify-webhook.mjs --slack'
+```
+
+The URL may also live in the dsh process environment as `DSH_HOOKS_WEBHOOK_URL` (never in config files). `--slack` swaps the payload for a one-line `{ text }` summary; `--timeout <ms>` sets the fetch timeout (default 10000, one automatic retry on transport failure).
+
+## Execution history
+
+Every hook trigger is recorded into an in-memory ring buffer (default 500 entries) and best-effort appended to `~/.dsh/dsh-hooks/history.jsonl` (0600) — for future UIs and debugging. Records never contain secrets (env vars never enter records):
+
+```yaml
+- id: dsh-hooks
+  name: dsh-hooks
+  config:
+    history:
+      enabled: true        # optional: persist to disk (default true)
+      max: 500             # optional: in-memory ring buffer size
+      # path: '…'          # optional: custom JSONL path (default ~/.dsh/dsh-hooks/history.jsonl)
+    hooks: […]
+```
+
+Each record: timestamp, kind (run/notify), event, command, session, outcome (spawned / exit-0 / exit-nonzero / timeout / sent / send-failed, …), exit code, duration, stderr tail. Disk failures are swallowed silently — history never blocks a hook.
+
+## dry-run: verify config
+
+Simulate an event to see which hooks would fire and why the others are filtered:
+
+```sh
+dsh-hooks dry-run turn/end --reason completed --profile web
+# ✅ [1] [turn/end when=completed] run: node notify-feishu.mjs
+# ⏭ [2] [turn/end when=error] run: … —— when 不匹配（期望 error，实际 completed）
+# ⏭ [3] [tool/call] run: … —— 事件不匹配（tool/call ≠ turn/end）
+# 共 1 个 hook 会触发。加 --execute 实际执行（真实副作用！）
+
+dsh-hooks dry-run tool/call --tool ssh_exec --execute   # end-to-end: actually run the matching hooks
+```
+
+`dry-run` reads the profile's `cordis.patch.yml` (the `id: dsh-hooks` block) and validates the config (bad regexes fail here).
+
+## Web profile HTTP routes
+
+In the web profile (when the shared webServer service exists) dsh-hooks registers loopback-only `/dsh-hooks/*` routes — CLI/headless environments never see them:
+
+| Route | Method | Purpose |
+| --- | --- | --- |
+| `/dsh-hooks/status` | GET | plugin version, hook count, history count |
+| `/dsh-hooks/history?n=50` | GET | the latest N execution records (JSON envelope) |
+| `/dsh-hooks/test` | POST | simulate an event: `{"event":"tool/call","tool":"ssh_exec","execute":false}` returns a per-hook match report; `execute: true` actually runs the matching hooks |
+
+Security matches dsh-aionui-panel: loopback-only, POSTs require `application/json` (blocks cross-site form CSRF). The web profile also gets a systemPrompt section announcing the plugin to agents.
+
 ## Feishu notification example
 
 The fastest path is the one-shot setup CLI — it creates the Feishu app for you via a QR-code scan and writes all hook config:
@@ -89,6 +204,8 @@ dsh-hooks feishu-test                  # send a test card with the stored creden
 
 Restart `dsh web` afterwards — you will get cards when turns finish, approvals are asked, or the agent errors.
 
+![Feishu card example](assets/screenshot-1.jpg)
+
 ### Manual configuration
 
 Prefer wiring it by hand? See [`examples/notify-feishu.mjs`](examples/notify-feishu.mjs) — a zero-dependency script that posts turn-completion / approval notices through the Feishu **app API** (works without a group custom bot). Configure it like:
@@ -122,6 +239,8 @@ pnpm install
 pnpm run check     # typecheck + test + build
 ```
 
+Releasing and CI operations (Trusted Publishing, security scanning, gotchas): see [docs/RELEASING.md](docs/RELEASING.md).
+
 ## License
 
 MIT

package/README.zh.md

@@ -31,15 +31,57 @@ dsh plugin --profile web add github:PeterBon/dsh-hooks
         timeoutMs: 10000             # 可选，默认 10000
       - on: 'approval/asked'
         run: 'powershell -Command "Add-Content hooks.log approval-requested"'
+      - on: 'tool/call'
+        match:                       # 可选：字段 → 正则，全部匹配才触发
+          tool: '^(rm|git|ssh)'
+        run: 'node examples/notify-webhook.mjs --slack'
+      - on: 'turn/end'
+        when: 'completed'
+        run: 'node examples/notify-feishu.mjs'
+        retries: 2                   # 可选：非零退出码重试（默认 0 不重试）
+        retryDelayMs: 1000           # 可选：重试基础间隔，每次翻倍（默认 500）
+      - on: 'turn/end'
+        input: 'stdin'               # 可选：把完整上下文 JSON 写入命令 stdin
+        run: 'node my-hook.mjs'
+      - on: 'approval/asked'
+        notify:                      # 内置通知：与 run 二选一，无需外部脚本
+          channel: 'desktop'         # 桌面气泡/toast 通知
+      - on: 'turn/end'
+        when: 'completed'
+        notify:
+          channel: 'webhook'         # POST JSON 到任意 HTTP 端点
+          url: 'https://hooks.slack.com/services/…'
+          slack: true                # 可选：改为 { text } 单行摘要（Slack 风格）
 ```
 
+每个 hook 的完整字段：
+
+| 字段 | 含义 | 默认 |
+| --- | --- | --- |
+| `on` | 触发事件（见上方事件表） | 必填 |
+| `when` | 对 `turn/end` 按结束原因过滤 | 全部原因 |
+| `match` | 字段 → 正则，全部匹配才触发；字段为上下文键（`tool`/`sessionName`/`sessionId`/`error`/`source`/`cwd`/`content`/`reason`…），上下文中不存在的字段视为不匹配 | 不过滤 |
+| `run` | 通过系统 shell 执行的命令（与 `notify` 二选一） | 二选一必填 |
+| `notify` | 内置通知（与 `run` 二选一）：`channel: webhook`（HTTP JSON，`url` 可省略用 `DSH_HOOKS_WEBHOOK_URL`，`slack: true` 换单行摘要）或 `channel: desktop`（系统气泡/toast） | 二选一必填 |
+| `input` | `env` 只传 `DSH_HOOK_*` 环境变量；`stdin` 额外把完整上下文 JSON 写入命令标准输入 | `env` |
+| `timeoutMs` | 单次执行超时（毫秒），超时终止进程树 | 10000 |
+| `retries` | 非零退出码的重试次数（spawn 失败与超时不重试） | 0 |
+| `retryDelayMs` | 重试基础间隔（毫秒），每次翻倍 | 500 |
+
 ## 事件（v1）
 
 | 事件 | 触发时机 | 有用上下文 |
 | --- | --- | --- |
 | `turn/start` | 回合开始 | 会话 id、回合号 |
-| `turn/end` | 回合结束（`completed` / `error` / `aborted` / `blocked` / `max-tokens` / `interrupted`） | reason、回合号、耗时 |
+| `turn/end` | 回合结束（`completed` / `error` / `aborted` / `blocked` / `max-tokens` / `interrupted`） | reason、回合号、耗时、内容、本回合 token 用量 |
+| `step/end` | 回合内一步结束（一次模型调用 + 其工具执行） | 回合号、步号 |
+| `tool/call` | 模型请求一次工具调用 | 工具名、调用 id、原始参数 JSON |
+| `tool/result` | 工具调用完成 | 工具名（自动反查）、结果文本、失败标识 |
+| `user/message` | 会话表面出现用户角色消息 | 来源 kind（`user` / `plugin` / …）、消息文本 |
 | `approval/asked` | 工具调用请求用户审批 | 工具名、调用 id、原因 |
+| `session/title` | 会话标题更新（显式改名 / LLM 生成 / 回退） | 新标题、来源 kind |
+| `session/created` | 会话发布 | 会话 id、cwd |
+| `session/disposed` | 会话离开注册表 | 会话 id、cwd |
 | `agent/created` | Agent 发布 | 会话 id |
 | `agent/disposed` | Agent 离开注册表 | 会话 id |
 | `agent/error` | Agent 循环报错 | 错误文本 |
@@ -49,7 +91,7 @@ dsh plugin --profile web add github:PeterBon/dsh-hooks
 
 ## 命令执行
 
-- 每个命中的 hook 通过系统 shell 执行 `run`，**fire-and-forget**：失败只 `console.warn`，绝不重试、绝不阻塞 agent 循环。
+- 每个命中的 hook 通过系统 shell 执行 `run`，**fire-and-forget**：失败只 `console.warn`、默认不重试（`retries` 可 opt-in 后台重试非零退出码）、绝不阻塞 agent 循环。命令的 stdout/stderr 会被捕获（各 64 KiB 上限），非零退出码时把 stderr 尾部写进告警日志。
 - 上下文通过**环境变量**传递（数据不拼接进 shell 字符串，防注入）：
 
 | 变量 | 含义 |
@@ -57,18 +99,91 @@ dsh plugin --profile web add github:PeterBon/dsh-hooks
 | `DSH_HOOK_EVENT` | 事件类型，如 `turn/end` |
 | `DSH_HOOK_SESSION_ID` | 会话 id |
 | `DSH_HOOK_SESSION_NAME` | 会话可读标题（最新 `session/title` 日志事件，或首个用户消息回退） |
-| `DSH_HOOK_TURN` | 回合号（回合事件） |
+| `DSH_HOOK_CWD` | 会话工作目录 |
+| `DSH_HOOK_TURN` | 回合号（回合 / 步骤 / 工具事件） |
+| `DSH_HOOK_STEP` | 步号（步骤 / 工具事件） |
 | `DSH_HOOK_REASON` | 回合结束原因 |
-| `DSH_HOOK_TOOL` | 工具名（审批事件） |
-| `DSH_HOOK_CALL_ID` | 工具调用 id（审批事件） |
+| `DSH_HOOK_TOOL` | 工具名（审批 / 工具事件） |
+| `DSH_HOOK_CALL_ID` | 工具调用 id（审批 / 工具事件） |
+| `DSH_HOOK_TOOL_ARGS` | 工具原始参数 JSON（tool/call） |
+| `DSH_HOOK_TOOL_ERROR` | 工具失败标识 `名称: 代码`（tool/result 出错时） |
+| `DSH_HOOK_SOURCE` | 消息 / 标题来源 kind（`user`、`plugin`、`fallback`、`provider`…） |
 | `DSH_HOOK_DURATION_MS` | 回合耗时毫秒（turn/end） |
 | `DSH_HOOK_STATUS` | Agent 状态（agent/status） |
 | `DSH_HOOK_ERROR` | 错误文本（agent/error，以及 turn/end 出错时的失败详情） |
-| `DSH_HOOK_CONTENT` | 该回合最后一段助手回复文本（回合事件） |
+| `DSH_HOOK_CONTENT` | 事件内容快照：回合最后助手文本、工具结果文本、用户消息文本 |
+| `DSH_HOOK_USAGE_INPUT_TOKENS` | 本回合输入 token 总量（turn/end，逐 step 聚合） |
+| `DSH_HOOK_USAGE_OUTPUT_TOKENS` | 本回合输出 token 总量 |
+| `DSH_HOOK_USAGE_CACHE_READ_TOKENS` | 本回合缓存读 token（有上报时） |
+| `DSH_HOOK_USAGE_CACHE_WRITE_TOKENS` | 本回合缓存写 token（有上报时） |
+| `DSH_HOOK_USAGE_REASONING_TOKENS` | 本回合思考 token（有上报时） |
 | `DSH_HOOK_TIMESTAMP` | ISO 时间戳 |
 
 - `run` 里的 `{{变量}}` 占位符会从同一上下文替换，例如 `run: 'echo {{DSH_HOOK_SESSION_ID}} >> log.txt'`。
 
+## 执行历史
+
+每次 hook 触发都会记入内存环形缓冲（默认 500 条），并 best-effort 追加到 `~/.dsh/dsh-hooks/history.jsonl`（权限 0600）——供未来 UI 与调试使用。记录不含 secret（环境变量从不入记录）：
+
+```yaml
+- id: dsh-hooks
+  name: dsh-hooks
+  config:
+    history:
+      enabled: true        # 可选：持久化到磁盘（默认 true）
+      max: 500             # 可选：内存环形缓冲条数
+      # path: '…'          # 可选：自定义 JSONL 路径（默认 ~/.dsh/dsh-hooks/history.jsonl）
+    hooks: […]
+```
+
+每条记录：时间戳、kind（run/notify）、事件、命令、会话、结果（spawned / exit-0 / exit-nonzero / timeout / sent / send-failed…）、退出码、耗时、stderr 尾部。写盘失败静默吞掉，绝不阻塞 hook。
+
+## dry-run：验证配置
+
+配置完先用 `dry-run` 模拟事件，看哪些 hook 会触发、哪些被过滤：
+
+```sh
+dsh-hooks dry-run turn/end --reason completed --profile web
+# ✅ [1] [turn/end when=completed] run: node notify-feishu.mjs
+# ⏭ [2] [turn/end when=error] run: … —— when 不匹配（期望 error，实际 completed）
+# ⏭ [3] [tool/call] run: … —— 事件不匹配（tool/call ≠ turn/end）
+# 共 1 个 hook 会触发。加 --execute 实际执行（真实副作用！）
+
+dsh-hooks dry-run tool/call --tool ssh_exec --execute   # 端到端真跑匹配的 hook
+```
+
+`dry-run` 直接读 profile 的 `cordis.patch.yml`（`id: dsh-hooks` 配置块），配置校验（非法正则等）会在这一步报错。
+
+## Web profile HTTP 路由
+
+web profile 里（存在共享 webServer 服务时）dsh-hooks 自动注册 loopback-only 的 `/dsh-hooks/*` 路由——CLI/headless 环境完全无感：
+
+| 路由 | 方法 | 用途 |
+| --- | --- | --- |
+| `/dsh-hooks/status` | GET | 插件版本、hook 数、历史条数 |
+| `/dsh-hooks/history?n=50` | GET | 最近 N 条执行历史（JSON envelope） |
+| `/dsh-hooks/test` | POST | 模拟事件评估：`{"event":"tool/call","tool":"ssh_exec","execute":false}` 返回逐 hook 匹配报告；`execute: true` 真跑匹配的 hook |
+
+安全约定与 dsh-aionui-panel 一致：仅回环地址可达、POST 必须 `application/json`（防跨站表单 CSRF）。同时 web profile 下会向 agent 注入一段 systemPrompt 公告，说明插件存在与协作方式。
+
+## 通用 webhook 示例
+
+除了飞书，`examples/notify-webhook.mjs` 把完整 hook 上下文作为一份 JSON POST 到任意 HTTP 端点——Slack 入站 webhook、Discord、企业微信/钉钉自定义机器人、ntfy、Bark、n8n 都能接：
+
+```yaml
+- id: dsh-hooks
+  name: dsh-hooks
+  config:
+    hooks:
+      - on: 'turn/end'
+        when: 'completed'
+        run: 'node examples/notify-webhook.mjs --url https://hooks.slack.com/services/…'
+      - on: 'tool/result'        # 工具连续失败时告警
+        run: 'node examples/notify-webhook.mjs --slack'
+```
+
+URL 也可放在 dsh 进程环境的 `DSH_HOOKS_WEBHOOK_URL`（不要写进配置文件）。`--slack` 把 payload 换成一行摘要的 `{ text }` 格式；`--timeout <ms>` 控制超时（默认 10000，传输失败自动重试一次）。
+
 ## 飞书通知示例
 
 最快的方式是一步到位的 setup CLI——扫码自动创建飞书应用并写好全部 hook 配置：
@@ -89,6 +204,8 @@ dsh-hooks feishu-test                  # 用已存凭据发送测试卡片验证
 
 完成后重启 `dsh web`——回合结束、请求审批、agent 出错时就会收到卡片通知。
 
+![飞书卡片示例](assets/screenshot-1.jpg)
+
 ### 手动配置
 
 想自己接线？见 [`examples/notify-feishu.mjs`](examples/notify-feishu.mjs)——零依赖脚本，通过飞书**应用 API**（不需要群自定义机器人）发送回合完成 / 审批通知。配置示例：
@@ -122,6 +239,8 @@ pnpm install
 pnpm run check     # typecheck + test + build
 ```
 
+发布与 CI 运维（Trusted Publishing、安全扫描、踩坑记录）：见 [docs/RELEASING.md](docs/RELEASING.md)。
+
 ## License
 
 MIT

package/bin/dsh-hooks.mjs

@@ -31,6 +31,7 @@ import { registerApp } from '@larksuiteoapi/node-sdk'
 import QRCode from 'qrcode'
 import YAML from 'yaml'
 import { run as notifyRun } from '../examples/notify-feishu.mjs'
+import { runDryRun } from '../lib/dry-run.js'
 
 const CONFIG_DIR = join(homedir(), '.dsh', 'dsh-hooks')
 export const CONFIG_PATH = join(CONFIG_DIR, 'feishu-config.json')
@@ -277,6 +278,20 @@ function cliArgs(args) {
   return opts
 }
 
+/** Parse the dry-run flags; the first positional arg is the event. */
+function cliDryRunArgs(args) {
+  const opts = { event: '', execute: false }
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--reason') opts.reason = args[++i]
+    else if (args[i] === '--tool') opts.tool = args[++i]
+    else if (args[i] === '--session-name') opts.sessionName = args[++i]
+    else if (args[i] === '--profile') opts.profile = args[++i]
+    else if (args[i] === '--execute') opts.execute = true
+    else if (!args[i].startsWith('-') && opts.event === '') opts.event = args[i]
+  }
+  return opts
+}
+
 function isDirectRun() {
   try {
     return process.argv[1] !== undefined && import.meta.url === new URL(`file:///${process.argv[1].replace(/\\/g, '/')}`).href
@@ -301,10 +316,24 @@ function runCli() {
         console.error(`✗ ${error instanceof Error ? error.message : String(error)}`)
         process.exit(1)
       })
+  } else if (command === 'dry-run') {
+    const opts = cliDryRunArgs(args)
+    if (!opts.event) {
+      console.error('缺少事件参数，用法：dsh-hooks dry-run <event> [--reason <kind>] [--profile <name>] [--execute]')
+      process.exit(1)
+    }
+    runDryRun(opts)
+      .then(() => process.exit(0))
+      .catch((error) => {
+        console.error(`✗ ${error instanceof Error ? error.message : String(error)}`)
+        process.exit(1)
+      })
   } else {
     console.error(`用法:
   dsh-hooks feishu-setup [--profile <name>]   扫码创建飞书通知机器人并自动配置
-  dsh-hooks feishu-test                       验证配置并发送测试卡片`)
+  dsh-hooks feishu-test                       验证配置并发送测试卡片
+  dsh-hooks dry-run <event> [--reason <kind>] [--tool <name>] [--profile <name>] [--execute]
+                                              模拟事件，列出会触发/被过滤的 hook（--execute 实际执行）`)
     process.exit(command === '--help' || command === 'help' || command === undefined ? 0 : 1)
   }
 }

package/examples/notify-feishu.mjs

@@ -347,27 +347,31 @@ export async function run(ctx, args = [], configPath = DEFAULT_CONFIG_PATH) {
   if (!merged.appId || !merged.appSecret) throw new Error('缺少 DSH_HOOKS_FEISHU_APP_ID / DSH_HOOKS_FEISHU_APP_SECRET')
   if (!merged.to) throw new Error('缺少 DSH_HOOKS_FEISHU_TO（接收者 open_id 或 chat_id）')
   if (!merged.event) throw new Error('缺少 DSH_HOOK_EVENT（请通过 dsh-hooks 触发，不要直接运行）')
+  // Credentials leave the pipeline here: card/text builders and the CLI
+  // logger only ever see presentation fields (event, reason, cwd, session,
+  // content, …), never secrets. Keeps the taint-to-log path clean.
+  const { appId, appSecret, to, receiveIdType: mergedReceiveIdType, ...presentationCtx } = merged
   const opts = parseArgs(args)
-  const presentation = eventPresentation(merged)
+  const presentation = eventPresentation(presentationCtx)
   const header = opts.header || presentation.header
   const title = opts.title || presentation.title
   if (!CARD_HEADERS.has(header)) {
     throw new Error(`无效的卡片配色: ${header}，可选: ${[...CARD_HEADERS].join(', ')}`)
   }
-  const token = await getToken(merged.appId, merged.appSecret)
-  const receiveIdType = merged.receiveIdType ?? 'open_id'
+  const token = await getToken(appId, appSecret)
+  const receiveIdType = mergedReceiveIdType ?? 'open_id'
   if (opts.textMode) {
-    const text = opts.body || buildBody(merged)
-    await sendText(token, merged.to, text, receiveIdType)
+    const text = opts.body || buildBody(presentationCtx)
+    await sendText(token, to, text, receiveIdType)
     return { kind: 'text', text }
   }
-  const card = buildCard(merged, {
+  const card = buildCard(presentationCtx, {
     header,
     title,
     note: opts.note || undefined,
-    body: opts.body || buildBody(merged),
+    body: opts.body || buildBody(presentationCtx),
   })
-  await sendCard(token, merged.to, card, receiveIdType)
+  await sendCard(token, to, card, receiveIdType)
   return { kind: 'card', card }
 }