事件流监视器ichabodcole/dsh-plugin-monitor

dsh-plugin-monitor

一个用于 DeepSeek Harness 的事件监视器：启动一个后台
监视——一个 shell 命令或一个 WebSocket——每行 stdout（或文本帧）都会作为异步事件投递到
所属的 agent 会话。agent 可以继续工作或进入空闲状态；
只有在真正有内容到达时才会进行推理。

仿照 Claude Code 的 Monitor 工具设计。它覆盖了 agent 需要
在事情发生时（而非结束时）做出反应的场景：开发服务器或测试监视器在重新编译时报告，
agent 应在任务中途响应的日志或队列，失败时应中断而非等待的长时间构建，
向它推送消息的套接字。没有它，可选方案要么是
阻塞在命令上直到其退出，要么是按定时器轮询——这会在每次空检查时消耗一个模型回合，
并将每个事件延迟最多一整个轮询间隔。

状态

可用，并已针对真实的 dsh profile 进行了端到端验证。两种生产者均已覆盖：

- command —— 逐行投递、批处理、标签、速率限制与自动终止、job_kill，
以及通过 job_output 恢复被截断的输出
- websocket —— 每个文本帧一个事件，多行帧保持完整，二进制帧
连同其大小一起报告，关闭码和超时作为任务结果呈现

74 个单元测试，在 CI 中于 Linux 上受门控，并在 macOS 上本地运行。验收运行记录在
docs/design.md 中。

dsh 已有的功能，以及本插件新增的内容

dsh 后台任务运行时（ctx.jobs）已经负责任务 id、取消、增量
读取（readOutput() / job_output），以及针对空闲所有者的完成时唤醒。另外，
agent.inject() 会将上下文追加到下一个模型请求——明确地_不是_唤醒。

本插件将其从仅完成时扩展到每次输出事件。投递方式是
agent.send(event, 'next-step', true)——运行时的唤醒式发送，它将事件折叠进
正在进行的工作，并在所有者空闲时开启一个回合。注册表没有逐输出
通知，也不需要：生产者在进程内拥有该流。围绕这一点的是
使其可存活的运维细节：

- 行/帧粒度——每行输出是一个事件
- 短窗口批处理（约 200ms），使多行突发作为一次通知到达
- 速率限制，并在洪流时自动终止
- 每条通知中携带的每监视器标签
- 默认超时，可选加入会话时长持久化，可通过 job_kill 停止

开发

本地开发使用 Bun + Biome（发布的包是 dist/ 中的纯 JS，因此这对
使用者不可见）：

bun install
bun run build     # tsc → dist/
bun run check     # biome

从本地检出安装到 dsh profile——注意 dsh plugin add 在消费者侧会转发给 pnpm，
并且 git 安装需要在消费者的 pnpm-workspace.yaml 中将 prepare 脚本加入允许列表；
这两者都不约束本仓库自身的工具链：

sh
dsh plugin --profile dev add /path/to/dsh-plugin-monitor

将其添加到实际启动所用的 profile —— Web UI 运行的是 web profile，因此安装到 dev 再启动 Web UI，是一条正确但目标错误的命令。启动前请验证：
sh
dsh --dump-config | grep monitor

调整投递预算

可选。默认值对几乎所有人来说就是合适的策略；仅当某个来源确实需要更多余量时才覆盖，作为 profile 条目上的 config: 块：
yaml
- id: monitor
name: dsh-plugin-monitor
config:
maxEventBytes: 32768 # 单个投递事件中的字节数（默认 16 KiB）
throttleBytes: 262144 # 每 10 秒的字节数，超过则限流（默认 128 KiB）
killBytes: 1048576 # 每 10 秒的字节数，超过则停止监控（默认 512 KiB）
spillBytes: 524288 # 事件裁剪输出的容量（默认 256 KiB）

配置在加载时校验，因此写错的预算会导致启动失败，而不是在第一个溢出事件时才失败。从事件中裁剪掉的输出可通过 job_output  恢复；事件会说明投递了多少字节，以及剩余部分存放在哪个溢出块中。

如果安装插件后工具调用开始失败

Cannot read properties of undefined (reading 'prepare')

该 profile 中的每次工具调用都会失败，包括与你刚添加的插件无关的调用。这意味着加载了两份 @deepseek-ai/dsh-tools：其调度器以模块局部的 Symbol() 为键，因此两份副本无法看到彼此的调度器。这是 dsh 的打包问题，而非插件缺陷 —— 参见 deepseek-harness 讨论
#1849。本包将 harness 包声明为 peer 依赖，且不附带任何运行时依赖，因此不应引入第二份副本；要找出确实引入的那一份：
sh
ls $DSH_HOME/profiles//node_modules/@deepseek-ai

目录结构

- src/index.ts —— 插件入口（name、inject、apply）；注册 monitor 工具以及告知模型事件会主动到达的系统提示词部分
- src/events.ts —— 批处理、限流，以及唤醒投递到所属 agent
- src/command.ts —— shell 命令生产者（独立进程组，因此取消会终止整个管道）
- src/websocket.ts —— WebSocket 生产者（每个文本帧一个事件）
- src/lines.ts —— 跨块边界的行拆分
- cordis.patch.yml —— 将 bundle 添加到 profile 时应用的配置层
- docs/design.md —— 设计说明与待决问题

参考资料

- 插件开发指南
- 工具编写
- 工具编写手册（后台工作）
- 后台作业运行时设计说明