@muzi3/dsh-plugin-herdr-watch

DSH 插件：Herdr 里有 agent 状态变化时，主动唤醒管理 agent，而不是让管理 agent 轮询。

管理 agent（herdrmgr preset）只在有 turn 时运行，空闲时不在任何循环里；而 herdr_* 工具是 请求-响应式，skill 是知识、persona 是约束 —— 三者都不产生事件。「herdr 变了」与「管家知道」 之间本来没有通路，这个 watcher 就是那条通路。

信号五类：appeared（新增）/ blocked（停在审批）/ resolved（blocked→idle）/ settled （长任务落定）/ disappeared（消失）。五类一视同仁：只唤醒，不替 agent 发任何通知 —— 要不要打扰人，由被唤醒的那个 agent 自己判断。

三道内建约束（别放松）

1. 确定不是目标就停轮询：本进程的顶层 agent 都读得出明确 preset、且都不是目标时，清定时器、 不再轮询（但保留监听 —— 原地切 preset 是 rebind，不触发 agent/created）。
2. 惰性启动：靠 agent/created 触发；判断不了时最多留一个低频兜底（DSH_HERDR_WATCH_IDLE_PROBE_MS， 设 0 即零定时器）。没有目标绝不拉快照。
3. 投递过滤：只投给 preset 匹配的顶层 agent，读不出就一律不投（fail closed）。

目标 preset 是代码里的常量 TARGET_PRESET（默认 herdrmgr）。

降噪

判据是纯函数 + 一个落盘账本，三种手段正交：

| 手段 | 作用 | 开关（环境变量） | |---|---|---| | 冷却 | 同一 pane 的同类信号，冷却期内不再报 | DSH_HERDR_WATCH_COOLDOWN_MS（全局）\newline DSH_HERDR_WATCH_{SETTLED,BLOCKED,RESOLVED}_COOLDOWN_MS（按类） | | 去重 | 内容签名相同且在窗口内，不再报 | DSH_HERDR_WATCH_DEDUP_MS（一旦设置对所有种类统一生效，0 = 全关） | | 落盘账本 | 去重依据写进 $DSH_HOME/run/herdr-watch/state.json，重启 / 压缩不会忘 | DSH_HERDR_WATCH_STATE=off（或设成别的路径） |

为什么去重窗口要按信号种类分：blocked 反复冒出来没有新信息（窗口长），settled 同一 agent 干完第 2、3 件长任务是有信息量的（去重关掉，只靠冷却）。全局一个窗口必有一类错。

运行参数

| 变量 | 含义 | |---|---| | DSH_HERDR_WATCH_POLICY | 设 off 完全退回旧行为（每条变化立刻唤醒），用于消融 | | DSH_HERDR_WATCH_INTERVAL_MS | 轮询间隔 | | DSH_HERDR_WATCH_IDLE_PROBE_MS | 判断不了时的低频兜底间隔；0 = 零定时器 | | DSH_HERDR_WATCH_MIN_WORK_MS | 连续 working 超过它才算长任务（settled 只报长任务） | | DSH_HERDR_WATCH_MAX_WAKES | 连续唤醒上限（防失控）；收到用户消息时重置 | | DSH_HERDR_WATCH_MAX_PENDING | 攒着的待补送变化上限 | | DSH_HERDR_WATCH_FAIL_ALERT | 快照连续失败到该次数报一次「watcher 降级」；0 = 不报 |

依赖

• herdr-manager skill 的 scripts/herdr：herdr 语义的唯一真源（preflight 门禁、完整限定 pane id、「超时 ≠ 失败」的判据）。按 DSH_HERDR_SCRIPT → $DSH_HOME/skills/herdr-manager/scripts/herdr → ~/.dsh/skills/herdr-manager/scripts/herdr 顺序定位。
• @deepseek-ai/dsh-llm：按 DSH_HOME 定位（$DSH_HOME/profiles/node_modules/...）， 所以插件本体可以住在任意目录，不必和 $DSH_HOME 同树。
• python3：scripts/herdr 的运行环境。

用法

# profile 补丁层的 preset 里
- id: herdr-watch
  name: '@muzi3/dsh-plugin-herdr-watch'

测试

npm test        # node --test test/

降噪策略是纯函数，最大的一块测试面就在这里（冷却 / 去重窗口 / 账本跨重启）。