前言¶
在 DeepSeek Harness（DSH）里跑智能体时，常见需求是「等日志写完、等构建跑完、等远端推送一条消息」，再让模型继续下一步。若只靠模型反复轮询读文件或读命令输出，会占用回合、打断思路，也不利于在 Web 界面里一眼看到「现在有哪些东西在听」。
下面介绍社区插件 dsh-tool-monitor（npm 包名 @caizhiyuan/dsh-tool-monitor，仓库 substitute525/dsh-tool-monitor）。它在宿主侧后台监听文件、命令输出或 WebSocket，有新输出时按规则唤醒所属会话，并在 Web 会话头部提供监听器列表与输出查看面板。维护者为 substitute525，分类为工作流，开源协议 MIT。
这是什么¶
dsh-tool-monitor 是一个声明了 dsh.bundle.patch 的 dsh-plugin 组合包（bundle）：装进 profile 后会自动插入一层 profile layer，无需再手工改 profile 的 cordis.patch.yml。宿主模块负责监听与唤醒；Web 客户端半部在会话头部注册「N 个监听器」控件。
监听器状态保存在插件自有的 Map 里（id 形如 monitor-N），不写入框架的 ctx.jobs，因此不会出现在 DSH 自带的「后台任务」列表中——这是有意的设计，与框架任务列表分离。
核心功能¶
三种监听源¶
通过工具 monitor_start 在后台发起监听，立即返回 monitor_id，主流程可继续执行：
| source | 含义 |
|---|---|
file |
轮询文件变化 |
command |
监听命令 stdout/stderr（停止时会杀后台进程） |
ws |
出站 WebSocket 客户端，事件驱动（不依赖 interval_ms） |
默认在监听到任意新输出时触发唤醒；可用 pattern（JavaScript 正则）限定仅匹配到的输出才触发。
WebSocket（ws）模式要点（来自 README）：
- text frame → 一个事件，多行 frame 保持为一个整体，不会拆散。
- binary frame → 仅报告
[binary frame, N bytes]，内容不透传。 - socket 关闭 → 结束监控并展示 close code（
1000/1001记为completed；如1006/1011记为failed）。 - 错误/异常在关闭前会先浮出，且不受
pattern过滤。 - 可选
protocols数组，按 RFC 6455 协商子协议。
模型可见的四个工具¶
宿主层注册，所有 preset 的所有会话可用：
monitor_start— 启动监听。主要参数：source（file|command|ws）、path/command/url、protocols（ws 可选）、duration_seconds（0 表示持续到会话或插件停止）、interval_ms（默认 3000，对 ws 忽略）、pattern、initial_snapshot（file 现有内容作为首批）、one_shot（首次触发后自动停止）、max_chars（缓冲尾保留，默认 4000）。monitor_read(id)— 增量读取（消费游标，语义同job_output）。monitor_stop(id)— 停止监听。monitor_list()— 列出本会话可见的监听器。
Web 会话头部¶
提供「N 个监听器」控件：点开可看到每个监听的状态点、时长、详情与停止按钮；点某行可按需展示保留的输出。客户端约每 2s 轮询宿主 /tool-monitor/list（优先 connection.rpc，否则同源 fetch）；监听器列表变化时，宿主还会通过专属 WebSocket 端点 /tool-monitor/ws 推送 { type:'snapshot', monitors:[...] }。输出不随推送下传——Web 端查看行内输出走 /tool-monitor RPC 的 read（保留窗口、非消费）；模型端走 monitor_read。
唤醒机制¶
构造 UserMessage（source 为 plugin:tool-monitor 的 notice）。所属 agent 空闲时立即 followup 唤醒；忙时通知进入插件自有队列，待该 owner 变为 idle 后按 monitor 分组合并成一条 followup 发出，避免忙时被反复打断，且没有唤醒次数上限。agent/disposed 或插件卸载会停止其全部监听。
安装与启用¶
本包为完整 bundle，安装命令以 README 为准：
# 从 npm 安装
dsh plugin --profile web add @caizhiyuan/dsh-tool-monitor
开发时可从源码 link（示例路径以 README 为准，改宿主后需重启 dsh）：
dsh plugin --profile web add link:W:/图南/dsh-tool-monitor
安装后重启 dsh（宿主模块与新 client bundle 生效；client 部分刷新页面即可）。dsh plugin add 会把包名写入 profiles\web\package.json 的 dsh.profile.bundles，并校验 dsh.bundle.patch 指向的 patch 可解析。
前提：profile 需已组合 webServer（Web 版默认具备）。headless 无 webServer 时，模型侧四个工具仍可用，但没有 Web 头部控件与 WS 推送。
当前资料中的版本为 0.5.1（见仓库 package.json）。
典型用法（思路）¶
README 未给出完整对话示例，但工具参数已足够复现常见流程：
- 模型调用
monitor_start，例如监听构建日志文件并带pattern匹配BUILD SUCCESS，或source: 'command'跑长时间命令，或source: 'ws'连本地/内网 WS 服务。 - 会话在空闲或从忙转闲后收到 notice 类 followup，摘要说明哪个 monitor 有新输出。
- 模型用
monitor_read(monitor_id)拉增量内容继续推理；需要结束时调用monitor_stop(monitor_id)。 - 人在 Web 头部打开监听器列表，点行查看保留输出或手动停止。
file 源若设置 initial_snapshot: true，可把文件现有内容作为首批事件，适合「先启动监听再 tail 增量」的场景。one_shot: true 适合「等到第一次匹配就停」的一次性等待。
适用场景与注意¶
适合：本地/CI 日志 tail、长命令 stdout 等待、WebSocket 推送驱动的自动化步骤、需要在 Web UI 里并列查看多个监听状态的工作流。
注意：
- 插件以当前 dsh 进程权限运行；
command与file路径、wsURL 均受该权限约束。安装前应阅读源码与 MIT 许可证，确认监听目标可信。 command监听会在monitor_stop或会话清理时终止子进程，避免孤儿进程。- 专属 WS 端点做 loopback 校验，拒绝非本地来源。
- 社区目录 SkillHub 插件页 与 GitHub 仓库由社区维护，与 DeepSeek / 幻方无官方从属关系；DSH 生态理念是「一切皆插件」，本文事实以仓库 README 与
package.json为准。
结尾¶
dsh-tool-monitor 把「等输出」从轮询回合里拆出来：后台监听 file / command / WebSocket，按规则唤醒会话，并在 Web 头部集中展示监听器与按需输出。若你在 DSH Web profile 里做构建、日志或 WS 驱动的工作流，可按上文命令安装 @caizhiyuan/dsh-tool-monitor（0.5.1，MIT），重启后结合四个 monitor 工具与头部面板使用。
- 目录页：https://www.skillhub.cn/plugins/substitute525/dsh-tool-monitor
- GitHub：https://github.com/substitute525/dsh-tool-monitor
