dsh-hooks 0.11.0 → 0.13.0

package/README.md

@@ -107,12 +107,17 @@ Every hook field:
 | `agent/error` | The agent loop reports an error | error text |
 | `agent/status` | Agent status transition | status |
 | `hook/failed` | A hook fails consecutively past `failedAlertThreshold` (default 3; synthetic, emitted from the outcome stream) | failing hook summary, consecutive failure count |
+| `usage/daily` | The first event after the local calendar day rolls over (synthetic, no timers): reports the token usage of the day that just ended | covered day, turns that day, contributing sessions, day's token totals |
 
 The `when` filter for `turn/end` matches the `reason.kind` value (`completed`, `error`, …). Hooks for other events run unconditionally.
 
 ## 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 |
@@ -134,11 +139,11 @@ The `when` filter for `turn/end` matches the `reason.kind` value (`completed`, `
 | `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` | event content snapshot: turn assistant text, tool result text, user message text, turn-initiating message text (turn/start) |
-| `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_USAGE_INPUT_TOKENS` | input token total (turn/end: this turn, summed across steps; usage/daily: the whole day) |
+| `DSH_HOOK_USAGE_OUTPUT_TOKENS` | output token total (same scoping) |
+| `DSH_HOOK_USAGE_CACHE_READ_TOKENS` | cache-read tokens when reported (same scoping) |
+| `DSH_HOOK_USAGE_CACHE_WRITE_TOKENS` | cache-write tokens when reported (same scoping) |
+| `DSH_HOOK_USAGE_REASONING_TOKENS` | reasoning tokens when reported (same scoping) |
 | `DSH_HOOK_RUNNING_SUBAGENTS` | live subagents still running under this session (turn/end; `0` = none — lets a hook tell "work handed off to background subagents" apart from "the turn finished for real") |
 | `DSH_HOOK_PARENT_SESSION_ID` | parent session id (subagent lineage; absent for top-level sessions) |
 | `DSH_HOOK_SUBAGENT` | `1` when the session is a subagent child, `0` otherwise |
@@ -151,6 +156,9 @@ The `when` filter for `turn/end` matches the `reason.kind` value (`completed`, `
 | `DSH_HOOK_TREE_DURATION_MS` | parent turn/end → tree settle duration, ms (`tree/settled`) |
 | `DSH_HOOK_FAILED_HOOK` | identity summary of the hook that failed consecutively (`hook/failed`) |
 | `DSH_HOOK_FAILURES` | consecutive failure count when the alert fired (`hook/failed`) |
+| `DSH_HOOK_USAGE_DAY` | local calendar day the token totals cover, `YYYY-MM-DD` (`usage/daily`) |
+| `DSH_HOOK_USAGE_TURNS` | turns with reported accounting that day (`usage/daily`) |
+| `DSH_HOOK_USAGE_SESSIONS` | distinct sessions that contributed usage that day (`usage/daily`) |
 | `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'`.
@@ -184,6 +192,26 @@ For the simpler "notify only once the whole tree settles" pattern, the synthetic
 
 Settled-but-idle continuable children do not count as running, so they don't keep suppressing the notification. The settle watch is event-driven and best-effort: it survives until the plugin restarts, and a failed re-check drops the watch silently (no late notification).
 
+### usage/daily: the cross-day token report
+
+`turn/end` answers "what did this turn cost". For a per-day view, use the synthetic `usage/daily` event: the plugin accumulates every reported `turn/end` usage in memory per **local calendar day** (subagent sessions included — same account), and when the day rolls over it emits one report for the day that just ended, on the next event that arrives. Detection is purely event-driven: no timers, no scheduled tasks.
+
+```yaml
+- on: 'usage/daily'
+  match: { usageInputTokens: '>0' }     # optional: skip days without usage
+  run: 'node examples/log-usage.mjs'    # or notify: { channel: 'webhook', url: '…' }
+```
+
+`DSH_HOOK_USAGE_DAY` is the day the report covers (`YYYY-MM-DD`); `DSH_HOOK_USAGE_TURNS` / `DSH_HOOK_USAGE_SESSIONS` are that day's counted turns and contributing sessions; the token details reuse the `turn/end` variable names (`usageInputTokens` / `usageOutputTokens` / `usageCacheReadTokens` / `usageCacheWriteTokens` / `usageReasoningTokens`) with day scope instead of turn scope.
+
+Three boundaries by design, not bugs:
+
+- **In-memory**: a plugin-process restart drops the day in progress (the new process starts a fresh day at zero); reports already emitted are unaffected.
+- **Event-driven, not timed**: a day is reported when the next event arrives, so after a quiet midnight the report waits for the next event; a day with no reported turn usage is never reported (an empty report is noise).
+- **Zero cost when unused**: with no `usage/daily` hook declared, no accumulation and no day check happen at all.
+
+`dsh-hooks dry-run usage/daily` simulates a report for "yesterday" with non-zero tokens, so match filters and the command can be verified first.
+
 ### Numeric match comparisons
 
 Numeric context fields (`turn`, `step`, `durationMs`, `toolDurationMs`, `usage*`, `runningSubagents`, …) support real comparisons instead of regex hacks:
@@ -275,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:
@@ -289,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
@@ -296,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.
 
@@ -312,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

@@ -107,12 +107,17 @@ dsh plugin --profile web add github:PeterBon/dsh-hooks
 | `agent/error` | Agent 循环报错 | 错误文本 |
 | `agent/status` | Agent 状态切换 | 状态 |
 | `hook/failed` | 同一 hook 连续失败达到 `failedAlertThreshold`（默认 3；合成事件，从结果流发射） | 失败 hook 摘要、连续失败次数 |
+| `usage/daily` | 本地日历日翻篇后的下一个事件（合成事件，无定时器）：报告刚结束那一天的 token 用量 | 覆盖日期、当日回合数、贡献会话数、当日 token 明细 |
 
 `turn/end` 的 `when` 匹配结束原因（`completed`、`error`…）；其他事件的 hook 无条件执行。
 
 ## 命令执行
 
-- 每个命中的 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 字符串，防注入）：
 
 | 变量 | 含义 |
@@ -134,11 +139,11 @@ dsh plugin --profile web add github:PeterBon/dsh-hooks
 | `DSH_HOOK_STATUS` | Agent 状态（agent/status） |
 | `DSH_HOOK_ERROR` | 错误文本（agent/error，以及 turn/end 出错时的失败详情） |
 | `DSH_HOOK_CONTENT` | 事件内容快照：回合最后助手文本、工具结果文本、用户消息文本、回合触发消息文本（turn/start） |
-| `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_USAGE_INPUT_TOKENS` | 输入 token 总量（turn/end 为本回合、逐 step 聚合；usage/daily 为当日聚合） |
+| `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_RUNNING_SUBAGENTS` | 本会话下仍在运行的存活子代理数（turn/end；`0` = 无——让 hook 能区分「工作已交给后台子代理」与「回合真正结束」） |
 | `DSH_HOOK_PARENT_SESSION_ID` | 父会话 id（子代理谱系；顶层会话无此变量） |
 | `DSH_HOOK_SUBAGENT` | 会话为子代理时为 `1`，否则 `0` |
@@ -151,6 +156,9 @@ dsh plugin --profile web add github:PeterBon/dsh-hooks
 | `DSH_HOOK_TREE_DURATION_MS` | 父回合结束 → 树落定的耗时（毫秒，`tree/settled`） |
 | `DSH_HOOK_FAILED_HOOK` | 连续失败的 hook 身份摘要（`hook/failed`） |
 | `DSH_HOOK_FAILURES` | 告警触发时的连续失败次数（`hook/failed`） |
+| `DSH_HOOK_USAGE_DAY` | 报告覆盖的本地日历日 `YYYY-MM-DD`（`usage/daily`） |
+| `DSH_HOOK_USAGE_TURNS` | 当日计入的回合数（`usage/daily`） |
+| `DSH_HOOK_USAGE_SESSIONS` | 当日贡献用量的会话数（`usage/daily`） |
 | `DSH_HOOK_TIMESTAMP` | ISO 时间戳 |
 
 - `run` 里的 `{{变量}}` 占位符会从同一上下文替换，例如 `run: 'echo {{DSH_HOOK_SESSION_ID}} >> log.txt'`。
@@ -185,6 +193,26 @@ config:
 
 已落定但闲置（idle）的 continuable 子代理不计入运行中，不会一直压住通知。落定监视是事件驱动且 best-effort 的：插件重启后监视集合丢失；重查失败会静默放弃该监视（不会补发迟到的通知）。
 
+### usage/daily：跨日 token 日报
+
+`turn/end` 只回答「这个回合花了多少」。要按天看成本，用合成事件 `usage/daily`：插件在内存里按**本地日历日**累计每个 `turn/end` 上报的 token（子代理会话的回合一并计入——同一个账号），日期翻篇后对下一个到达的事件发射一次日报，报告刚结束的那一天。检测纯事件驱动、无定时器、无定时任务。
+
+```yaml
+- on: 'usage/daily'
+  match: { usageInputTokens: '>0' }     # 可选：跳过没有用量的日子
+  run: 'node examples/log-usage.mjs'    # 或 notify: { channel: 'webhook', url: '…' }
+```
+
+`DSH_HOOK_USAGE_DAY` 是报告覆盖的日期（`YYYY-MM-DD`）；`DSH_HOOK_USAGE_TURNS` / `DSH_HOOK_USAGE_SESSIONS` 是当日计入的回合数与贡献会话数；token 明细沿用 `turn/end` 的 `DSH_HOOK_USAGE_*` 变量名（`usageInputTokens` / `usageOutputTokens` / `usageCacheReadTokens` / `usageCacheWriteTokens` / `usageReasoningTokens`），语义变为「该日聚合」。
+
+三条边界（按设计，不是 bug）：
+
+- **内存累计**：插件进程重启会丢掉进行中那一天的累计（重启后从新的一天、从零开始）；已发出的日报不受影响。
+- **事件驱动而非定时**：一天的用量要等下一个事件到达才报告，所以跨夜后若一直没动静，日报会推迟到下一次有事件时补发；那一天从未有回合上报用量则不发射（空日报是噪声）。
+- **零开销**：没有声明任何 `usage/daily` hook 时，插件完全不做累计与跨日检测。
+
+`dsh-hooks dry-run usage/daily` 用「昨天」和非零 token 模拟一次日报，可先验证 match 与命令。
+
 ### match 数值比较
 
 对数字字段（`turn`、`step`、`durationMs`、`toolDurationMs`、`usage*`、`runningSubagents`…）可以直接写数值比较，不用绕正则：
@@ -258,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 会触发、哪些被过滤：
@@ -272,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
@@ -279,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 运行时依赖。
 
@@ -295,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)
   }
 }