dsh-hooks 0.12.0 → 0.13.1

package/README.md

@@ -113,7 +113,11 @@ 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 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.
+- Each matching hook spawns `run` through the platform shell, **fire-and-forget**: failures only `console.warn`, never retried by default, 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.
+- **Retries** (`retries` / `retryDelayMs`) apply to both execution channels with the same shape: up to `retries` extra attempts after the first one, with the delay doubling per attempt (`retryDelayMs`, default 500 ms):
+  - `run`: retries **non-zero exit codes** only (spawn failures and timeouts are never retried).
+  - `notify` webhook channel: retries **transport failures** (connection reset, timeout) and HTTP **408 / 429 / 5xx**; other 4xx mean the request itself is wrong and are not retried. The default `retries: 0` now means exactly one attempt — before 0.13 the webhook channel hard-coded a single transport retry, which is now folded into `retries`: existing configs that relied on it should set `retries: 1`.
+  - `notify` desktop channel is a local popup and never retries.
 - Context is passed via **environment variables** (no shell injection through data):
 
 | Variable | Meaning |
@@ -299,6 +303,16 @@ Every hook trigger is recorded into an in-memory ring buffer (default 500 entrie
 
 Each record: timestamp, kind (run/notify), event, command, session, outcome (spawned / exit-0 / exit-nonzero / timeout / skipped / sent / send-failed, …), exit code, duration, stderr tail. Disk failures are swallowed silently — history never blocks a hook.
 
+To follow the log while you work, use `tail` (Ctrl+C to quit):
+
+```sh
+dsh-hooks tail                                            # replay the last 10, then follow
+dsh-hooks tail --event turn/end --outcome exit-nonzero    # only failed turn ends
+dsh-hooks tail --hook notify-feishu --n 50 --json         # 50 backfill lines, raw JSONL for jq
+```
+
+`tail` resolves the JSONL path from the profile's `history.path`, falling back to the default without failing when the config file is missing or mid-edit. It reads only appended bytes, waits for complete lines (a record observed mid-write stays pending), and restarts from byte 0 when the file is truncated or rotated.
+
 ## dry-run: verify config
 
 Simulate an event to see which hooks would fire and why the others are filtered:
@@ -313,6 +327,17 @@ dsh-hooks dry-run turn/end --reason completed --profile web
 dsh-hooks dry-run tool/call --tool ssh_exec --execute   # end-to-end: actually run the matching hooks
 ```
 
+**Simulating numeric fields**: give count/timing/token fields a value to exercise numeric `match` filters:
+
+```sh
+dsh-hooks dry-run turn/end --running-subagents 3
+dsh-hooks dry-run turn/end --duration-ms 1250 --usage-input 120000 --usage-output 45000
+dsh-hooks dry-run tool/result --tool-duration-ms 15000
+dsh-hooks dry-run usage/daily --field usageCacheReadTokens=90000   # generic: --field <name>=<value>
+```
+
+Simulatable fields: `turn`, `step`, `durationMs`, `toolDurationMs`, `runningSubagents`, `totalSubagents`, `treeDurationMs`, `usageTurns`, `usageSessions`, `usageInputTokens`, `usageOutputTokens`, `usageCacheReadTokens`, `usageCacheWriteTokens`, `usageReasoningTokens`. Anything outside the list (or a non-finite number) is reported as "ignored" rather than dropped silently. The mock mirrors the runtime: `turn/end` always carries `runningSubagents` (0 by default), so the documented `match: { runningSubagents: '^0$' }` pattern is reachable in dry-run too; `usage/daily` carries "yesterday" plus non-zero token details.
+
 `dry-run` reads the profile's `cordis.patch.yml` (the `id: dsh-hooks` block) and validates the config (bad regexes fail here).
 
 ## Web GUI
@@ -320,11 +345,11 @@ dsh-hooks dry-run tool/call --tool ssh_exec --execute   # end-to-end: actually r
 After install, the dsh web settings panel gains a "Hooks" section (beside General and Plugins):
 
 - **Status badges**: plugin version, hook count, history count, plus live diagnostics (in-flight runs, recent failures)
-- **Manual tester**: pick an event (14 kinds) + reason/tool; "Simulate" shows the per-hook match report, "Execute" really triggers the matching hooks; the report clears when the inputs change
+- **Manual tester**: pick an event (18 kinds) + reason/tool, and fill the "simulated fields" row with numeric context (`runningSubagents`, `durationMs`, usage in/out); "Simulate" shows the per-hook match report, "Execute" really triggers the matching hooks; the report clears when the inputs change
 - **Notify-channel tests**: fire a test notification at the webhook (optional Slack summary) / desktop channel and show the payload preview
 - **Feishu connect**: scan-to-connect inside the panel — the QR code renders inline (with expiry countdown and a cancel button); after the scan the app is created, credentials + hook config are written, and the connected summary offers a one-click test card, an inline truncation-length editor (50–5000 chars, default 300, with a content preview), a re-connect flow, and a disconnect (optionally removing the Feishu hooks)
 - **Hook list / editor**: a read-only list of the current hooks (event/when/match/run/notify + timeout/retry fields) with one-click "copy YAML"; the "edit" mode turns it into a form editor whose changes are validated (regexes, run-notify exclusivity) and written back to `cordis.patch.yml` with an automatic backup
-- **Execution-history timeline**: at the bottom of the card, **collapsed by default** (the toggle state persists in localStorage; "expand" opens the latest 30 triggers: time / event / command / outcome / stderr tail), refreshed every 5s
+- **Execution-history timeline**: at the bottom of the card, **collapsed by default** (the toggle state persists in localStorage), refreshed every 5s. Expanded, it filters by **event / outcome / session** (filters persist in localStorage, with a "showing N of M" count and a clear button) and **exports the current view as JSONL** (same shape as the on-disk `history.jsonl`, file name stamped with local time); the panel fetches the latest 200 records and filters in the browser
 
 CLI/headless environments are unaffected: the browser half loads only in the web GUI and the core has no UI runtime dependencies.
 
@@ -336,7 +361,7 @@ In the web profile (when the shared webServer service exists) dsh-hooks register
 | --- | --- | --- |
 | `/dsh-hooks/status` | GET | plugin version, hook count, history count, the **current hook list**, and live runner stats |
 | `/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 |
+| `/dsh-hooks/test` | POST | simulate an event: `{"event":"tool/call","tool":"ssh_exec","execute":false}` returns a per-hook match report; `fields` overrides numeric context (`{"event":"turn/end","fields":{"runningSubagents":2}}`, unknown fields → 400); `execute: true` actually runs the matching hooks |
 | `/dsh-hooks/notify/test` | POST | fire a test notification at a channel: `{"channel":"webhook","url":…,"slack":true}` or `{"channel":"desktop"}`; returns the payload preview |
 | `/dsh-hooks/hooks/save` | POST | save the hook list: `{"profile":"web","hooks":[…]}` — validates (events, reasons, regexes, run-notify exclusivity), writes back to cordis.patch.yml with an automatic backup |
 | `/dsh-hooks/feishu/status` | GET | Feishu connection summary (app id / target masked, secret never leaves the server) + the scan-session snapshot + the truncation length + a content preview |

package/README.zh.md

@@ -113,7 +113,11 @@ dsh plugin --profile web add github:PeterBon/dsh-hooks
 
 ## 命令执行
 
-- 每个命中的 hook 通过系统 shell 执行 `run`，**fire-and-forget**：失败只 `console.warn`、默认不重试（`retries` 可 opt-in 后台重试非零退出码）、绝不阻塞 agent 循环。命令的 stdout/stderr 会被捕获（各 64 KiB 上限），非零退出码时把 stderr 尾部写进告警日志。
+- 每个命中的 hook 通过系统 shell 执行 `run`，**fire-and-forget**：失败只 `console.warn`、默认不重试、绝不阻塞 agent 循环。命令的 stdout/stderr 会被捕获（各 64 KiB 上限），非零退出码时把 stderr 尾部写进告警日志。
+- **重试**（`retries` / `retryDelayMs`）对两个执行通道都生效，都是「首次尝试之后再重试 N 次」、间隔按 `retryDelayMs` 逐次翻倍（默认 500ms）：
+  - `run`：只重试**非零退出码**（spawn 失败与超时不重试）。
+  - `notify` 的 webhook 渠道：重试**传输失败**（连接被重置、超时）与 HTTP **408 / 429 / 5xx**；其余 4xx 表示请求本身有问题，不重试。**默认 `retries: 0` 表示只尝试一次**——0.13 之前 webhook 曾硬编码「传输失败自动再试一次」，现在这层兜底已并入 `retries`，需要它的老配置请显式写 `retries: 1`。
+  - `notify` 的 desktop 渠道是本地弹窗，不重试。
 - 上下文通过**环境变量**传递（数据不拼接进 shell 字符串，防注入）：
 
 | 变量 | 含义 |
@@ -282,6 +286,16 @@ config:
 
 每条记录：时间戳、kind（run/notify）、事件、命令、会话、结果（spawned / exit-0 / exit-nonzero / timeout / skipped / sent / send-failed…）、退出码、耗时、stderr 尾部。写盘失败静默吞掉，绝不阻塞 hook。
 
+终端里想边跑边看，用 `tail`（Ctrl+C 退出）：
+
+```sh
+dsh-hooks tail                                  # 回放最近 10 条，然后实时跟进
+dsh-hooks tail --event turn/end --outcome exit-nonzero   # 只看失败的回合结束
+dsh-hooks tail --hook notify-feishu --n 50 --json         # 50 条起，输出原始 JSONL 供 jq
+```
+
+`tail` 的 JSONL 路径取自 profile 配置的 `history.path`（未配置或配置读不出来时回落到默认路径，不会因为配置文件半途改动而报错）。它只读新增字节、容忍半行（等换行再输出）、文件被截断/轮转时自动从 0 重新跟进。
+
 ## dry-run：验证配置
 
 配置完先用 `dry-run` 模拟事件，看哪些 hook 会触发、哪些被过滤：
@@ -296,6 +310,19 @@ dsh-hooks dry-run turn/end --reason completed --profile web
 dsh-hooks dry-run tool/call --tool ssh_exec --execute   # 端到端真跑匹配的 hook
 ```
 
+**模拟数值字段**：数字类上下文（`runningSubagents`、`durationMs`、`toolDurationMs`、`usage*`…）可以直接给定值，用来验证基于数值的 `match`：
+
+```sh
+dsh-hooks dry-run turn/end --running-subagents 3
+dsh-hooks dry-run turn/end --duration-ms 1250 --usage-input 120000 --usage-output 45000
+dsh-hooks dry-run tool/result --tool-duration-ms 15000
+dsh-hooks dry-run usage/daily --field usageCacheReadTokens=90000   # 通用写法：--field <名>=<值>
+```
+
+可模拟字段白名单：`turn`、`step`、`durationMs`、`toolDurationMs`、`runningSubagents`、`totalSubagents`、`treeDurationMs`、`usageTurns`、`usageSessions`、`usageInputTokens`、`usageOutputTokens`、`usageCacheReadTokens`、`usageCacheWriteTokens`、`usageReasoningTokens`。非白名单字段或非法数字不会被静默丢弃——报告里会列出「已忽略无法模拟的字段」。
+
+模拟上下文与运行时保持一致：`turn/end` 一定带 `runningSubagents`（默认 0），所以 README 推荐的 `match: { runningSubagents: '^0$' }` 在 dry-run 里也能命中；`usage/daily` 带「昨天」与非零 token 明细。
+
 `dry-run` 直接读 profile 的 `cordis.patch.yml`（`id: dsh-hooks` 配置块），配置校验（非法正则等）会在这一步报错。
 
 ## Web GUI
@@ -303,11 +330,11 @@ dsh-hooks dry-run tool/call --tool ssh_exec --execute   # 端到端真跑匹配
 安装后，dsh web 的设置面板里会出现「Hooks」分区（与「通用」「插件」平级）：
 
 - **状态徽章**：插件版本、hook 数、历史条数，以及运行诊断（正在执行的 hook 数、最近失败数）
-- **手动测试**：选事件（14 类）+ reason/tool，「模拟」看逐 hook 匹配报告，「执行」真实触发；切换输入自动清空旧结果
+- **手动测试**：选事件（18 类）+ reason/tool，并可用「模拟字段」一行填入 `runningSubagents` / `durationMs` / usage 输入输出等数值上下文；「模拟」看逐 hook 匹配报告，「执行」真实触发；切换输入自动清空旧结果
 - **通知渠道测试**：向 webhook（可选 Slack 摘要）/ desktop 渠道发一条测试通知，显示发送内容预览
 - **飞书通知**：网页内扫码连接飞书——显示二维码（含有效期倒计时、可取消），扫码后自动创建应用、写入凭据与 hook 配置；已连接后显示应用摘要，可一键发送测试卡片、调整卡片截断长度（50–5000 字符，默认 300，带正文预览）、重新扫码换绑或断开连接（可选一并移除飞书 hooks）
 - **当前 hooks**：只读清单（事件/when/match/run/notify + 超时重试参数），一键「复制 YAML」；点「编辑」进入表单编辑器，增删改 hook 后写回 `cordis.patch.yml`（自动备份原文件、写前校验正则与 run/notify 二选一，保存即热加载）
-- **执行历史时间线**：位于分区底部、**默认折叠**（展开状态记忆于 localStorage；标题旁「展开」查看最近 30 条触发：时间 / 事件 / 命令 / 结果 / stderr 尾部），5 秒自动刷新
+- **执行历史时间线**：位于分区底部、**默认折叠**（展开状态记忆于 localStorage），5 秒自动刷新。展开后可按**事件 / 结果 / 会话**过滤（条件同样记忆在 localStorage，附「显示 N / 共 M 条」计数与「清空过滤」），并把当前视图**导出为 JSONL**（与磁盘上的 `history.jsonl` 同格式，文件名带本地时间戳）——面板一次拉取最近 200 条，过滤在浏览器侧完成
 
 CLI/headless 环境完全不受影响：浏览器半只在 web 加载，核心零 UI 运行时依赖。
 
@@ -319,7 +346,7 @@ web profile 里（存在共享 webServer 服务时）dsh-hooks 自动注册 `/ds
 | --- | --- | --- |
 | `/dsh-hooks/status` | GET | 插件版本、hook 数、历史条数、**当前 hooks 清单**与运行统计 |
 | `/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-hooks/test` | POST | 模拟事件评估：`{"event":"tool/call","tool":"ssh_exec","execute":false}` 返回逐 hook 匹配报告；可用 `fields` 覆盖数值上下文（`{"event":"turn/end","fields":{"runningSubagents":2}}`，非法字段返回 400）；`execute: true` 真跑匹配的 hook |
 | `/dsh-hooks/notify/test` | POST | 向指定渠道发测试通知：`{"channel":"webhook","url":…,"slack":true}` 或 `{"channel":"desktop"}`，返回发送内容预览 |
 | `/dsh-hooks/hooks/save` | POST | 保存 hook 列表：`{"profile":"web","hooks":[…]}`——校验（事件/when/正则/run-notify 二选一）后写回 cordis.patch.yml，自动备份原文件 |
 | `/dsh-hooks/feishu/status` | GET | 飞书连接摘要（app id / 目标均已打码，绝不返回 secret）+ 扫码会话快照 + 截断长度 + 正文预览 |

package/bin/dsh-hooks.mjs

@@ -25,7 +25,8 @@
  */
 import { spawn } from 'node:child_process'
 import QRCode from 'qrcode'
-import { runDryRun } from '../lib/dry-run.js'
+import { loadHistoryPath, runDryRun } from '../lib/dry-run.js'
+import { formatTailRecord, HistoryTailer, matchesTailFilter } from '../lib/tail.js'
 import {
   FEISHU_CONFIG_PATH,
   mergePatchYaml,
@@ -120,18 +121,99 @@ function cliArgs(args) {
 
 /** Parse the dry-run flags; the first positional arg is the event. */
 function cliDryRunArgs(args) {
-  const opts = { event: '', execute: false }
+  const opts = { event: '', execute: false, fields: {} }
+  /** Numeric context fields the CLI exposes by name (plus the generic --field). */
+  const fieldFlags = {
+    '--running-subagents': 'runningSubagents',
+    '--duration-ms': 'durationMs',
+    '--tool-duration-ms': 'toolDurationMs',
+    '--usage-input': 'usageInputTokens',
+    '--usage-output': 'usageOutputTokens',
+  }
+  for (let i = 0; i < args.length; i++) {
+    const flag = args[i]
+    if (flag === '--reason') opts.reason = args[++i]
+    else if (flag === '--tool') opts.tool = args[++i]
+    else if (flag === '--session-name') opts.sessionName = args[++i]
+    else if (flag === '--profile') opts.profile = args[++i]
+    else if (flag === '--execute') opts.execute = true
+    else if (fieldFlags[flag] !== undefined) opts.fields[fieldFlags[flag]] = cliNumber(args[++i])
+    else if (flag === '--field') {
+      // Generic escape hatch: --field usageCacheReadTokens=90000
+      const [name, raw] = String(args[++i] ?? '').split('=')
+      if (name) opts.fields[name] = cliNumber(raw)
+    } else if (!flag.startsWith('-') && opts.event === '') opts.event = flag
+  }
+  return opts
+}
+
+/**
+ * CLI numbers stay numbers when they parse (the mock only accepts finite
+ * numbers); anything else is passed through so the dry-run report can name
+ * the field as ignored instead of silently dropping it.
+ */
+function cliNumber(raw) {
+  const value = Number(raw)
+  return raw !== undefined && raw !== '' && Number.isFinite(value) ? value : raw
+}
+
+/** Parse the tail flags. */
+function cliTailArgs(args) {
+  const opts = { json: 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]
+    const flag = args[i]
+    if (flag === '--profile') opts.profile = args[++i]
+    else if (flag === '--n') opts.n = cliNumber(args[++i])
+    else if (flag === '--event') opts.event = args[++i]
+    else if (flag === '--outcome') opts.outcome = args[++i]
+    else if (flag === '--hook') opts.hook = args[++i]
+    else if (flag === '--interval') opts.intervalMs = cliNumber(args[++i])
+    else if (flag === '--file') opts.file = args[++i]
+    else if (flag === '--json') opts.json = true
   }
   return opts
 }
 
+/**
+ * Follow the history JSONL: print the last `n` records, then everything
+ * appended afterwards. Returns a stop function (the CLI wires it to SIGINT,
+ * tests call it directly).
+ */
+export async function tailHistory(options = {}) {
+  const print = options.print ?? console.log
+  const intervalMs = typeof options.intervalMs === 'number' && options.intervalMs > 0 ? options.intervalMs : 500
+  const file = options.file ?? loadHistoryPath(options.profile ?? 'web')
+  const filter = { event: options.event, outcome: options.outcome, hook: options.hook }
+  const active = Object.entries(filter).filter(([, value]) => value !== undefined)
+  const tailer = new HistoryTailer(file)
+
+  const emit = (records) => {
+    for (const record of records) {
+      if (!matchesTailFilter(record, filter)) continue
+      print(options.json ? JSON.stringify(record) : formatTailRecord(record))
+    }
+  }
+
+  print(`dsh-hooks tail · ${file}`)
+  if (active.length > 0) print(`过滤：${active.map(([key, value]) => `${key}=${value}`).join(' ')}`)
+  const backfill = tailer.backfill(typeof options.n === 'number' ? options.n : 10)
+  if (backfill.length === 0) print('（暂无历史记录）')
+  emit(backfill)
+  print('—— 实时跟进中（Ctrl+C 退出）——')
+
+  const timer = setInterval(() => {
+    try {
+      const batch = tailer.readNew()
+      if (batch.reset) print(`⚠ 文件被截断或轮转，已从头跟进：${file}`)
+      emit(batch.records)
+    } catch (error) {
+      print(`⚠ 读取失败：${error instanceof Error ? error.message : String(error)}`)
+    }
+  }, intervalMs)
+
+  return () => clearInterval(timer)
+}
+
 function isDirectRun() {
   try {
     return process.argv[1] !== undefined && import.meta.url === new URL(`file:///${process.argv[1].replace(/\\/g, '/')}`).href
@@ -159,7 +241,7 @@ function runCli() {
   } else if (command === 'dry-run') {
     const opts = cliDryRunArgs(args)
     if (!opts.event) {
-      console.error('缺少事件参数，用法：dsh-hooks dry-run <event> [--reason <kind>] [--profile <name>] [--execute]')
+      console.error('缺少事件参数，用法：dsh-hooks dry-run <event> [--reason <kind>] [--profile <name>] [--execute] [--running-subagents N]')
       process.exit(1)
     }
     runDryRun(opts)
@@ -168,12 +250,30 @@ function runCli() {
         console.error(`✗ ${error instanceof Error ? error.message : String(error)}`)
         process.exit(1)
       })
+  } else if (command === 'tail') {
+    const opts = cliTailArgs(args)
+    tailHistory(opts)
+      .then((stop) => {
+        process.on('SIGINT', () => {
+          stop()
+          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 dry-run <event> [--reason <kind>] [--tool <name>] [--profile <name>] [--execute]
-                                              模拟事件，列出会触发/被过滤的 hook（--execute 实际执行）`)
+                                               [--running-subagents N] [--duration-ms N] [--tool-duration-ms N]
+                                               [--usage-input N] [--usage-output N] [--field <名>=<值>]
+                                              模拟事件，列出会触发/被过滤的 hook（--execute 实际执行）
+  dsh-hooks tail [--profile <name>] [--n <count>] [--event <name>] [--outcome <name>] [--hook <text>]
+                                               [--json] [--interval <ms>] [--file <path>]
+                                               实时跟踪执行历史（history.jsonl），Ctrl+C 退出`)
     process.exit(command === '--help' || command === 'help' || command === undefined ? 0 : 1)
   }
 }