下载监控悬浮窗 keepermttl/dsh-download-monitor

dsh-download-monitor

DSH Web GUI 下载监控插件：agent 拉起下载后即可离开，插件自动监控并在页面右下角以悬浮窗展示进度；任务完成 / 停滞 / 失败时，插件向注册会话发送结构化报告并把 agent 唤醒；用户可一键停止任务（不唤醒、留痕）；历史任务留痕（合并批次、可删可关）。

特性

- 注册制监控：agent 把下载任务写进 manifest（~/.dsh/dlmon/tasks.json），插件 host 半区自动监听；支持三种任务形态：
- dir：监控目录（对其直接子文件求和算进度），适合 cascette/aria2 这类下载器；
- process：dir + 进程存活检测（进程退出且未完成 → 失败；停止时直接终止进程）；
- job：DSH 后台任务（browser 半区合并 job 状态显示；完成通知走 DSH 原生机制）。
- 状态机：pending → running → completed / failed / stalled / stopped；判定依据：期望字节数、日志完成/错误正则（donePatterns / errorPatterns）、进程存活、停滞阈值（默认 120 秒无字节增长）。
- 悬浮窗：shell.overlay 槽位（官方浮动层），右下角，面板与折叠胶囊都可拖拽、可折叠；「进行中 / 历史」两个分区；每任务显示状态点、进度条、速度、ETA、失败原因；皮肤全适配（--dsw- 令牌）。
- 停止任务：运行/停滞任务行有「停止」（两步确认防误触）：process 任务直接终止进程； dir/job 标记停止。停止 = 终态、不生成唤醒报告（并清掉已排队的报告），manifest 写入 stoppedBy: 'user' 标记，agent 可直接看到是用户主动停止。
- 历史留痕：终态任务（完成/失败/停止）按批次合并记录到 ~/.dsh/dlmon/history.json （同一次 manifest 写入自动成批；batchId 显式成批），每条含简短总结（结果、进度、来源会话 id、时间）；默认保留 20 条（historyCap 可调），可单条删除，可整体关闭（historyEnabled）。
- 唤醒闭环：完成/失败/停滞 → host 入队 → 浏览器经 session.prompt 向注册会话发送【下载监控】 报告 → agent 处理后可 ack（确认后不再重复打扰）；每次状态转换只唤醒一次，会话存储去重、可全局关闭唤醒；prompt 被拒绝（如 sessionId 不存在）会重试并告警，绝不误报已投递。
- 工作流固化：全局技能 download-monitor（~/.dsh/skills/download-monitor/SKILL.md）——所有会话在涉及下载时自动按本协议注册任务、处理唤醒、查询历史。
- 零框架依赖：不 import 任何 @deepseek-ai/ 值（全部结构类型，dsh-archive-viewer 先例），不修改 DSH 源码，纯 cordis.patch.yml + profile 挂载。

安装

前置：Node.js ≥ 22、pnpm、dsh CLI（不在 PATH 时用
node --import tsx/esm /apps/cli/src/bin.ts）。

git clone https://github.com/keepermttl/dsh-download-monitor.git
cd dsh-download-monitor
pnpm install
pnpm build

安装进 web profile（link: 指向本目录）
dsh plugin --profile web add link:$(pwd) # POSIX
dsh plugin --profile web add link:E:\path\to\dsh-download-monitor # Windows

重启 dsh web，浏览器 Ctrl+F5 硬刷新。重启后悬浮窗在右下角出现（有任务时）。

任务注册（manifest 协议）

~/.dsh/dlmon/tasks.json：

{
"version": 1,
"tasks": [
{
"id": "wow-base",
"label": "魔兽基础包续传", "kind": "process", "targetDir": "E:\\WoW_68974\\Data\\data", "expectedBytes": 82900000000, "pid": 12345, "logPath": "C:\\Users\\32701\\AppData\\Local\\Temp\\opencode\\wow_base_watchdog.log",
"errorPatterns": ["All connection attempts failed", "Traceback"],
"donePatterns": ["Installing 0 files"],
"sessionId": "",
"notify": { "onDone": true, "onProblem": true },
"ack": false
}
]
}

字段说明：

| 字段 | 必填 | 说明 |
| id / label | 是 | 唯一 id / 显示名 |
| kind | 是 | dir / process / job |
| targetDir | dir/process | 监控目录（直接子文件求和 = 进度） |
| expectedBytes | 否 | 完成判据之一（字节达标即完成） |
| pid | process | 进程存活检测 |
| logPath + errorPatterns / donePatterns | 否 | 日志尾随（最近 64KB）正则；patterns-without-log 会被拒绝 |
| sessionId | 是 | 唤醒目标会话——必须用完整 id（含 session- 前缀，如 session-65d36e62-…），取自 GUI 会话信息或 session.list；裸 uuid 会被 host 拒绝（插件会警告） |
| notify | 否 | 默认全开 |
| ack | 否 | agent 处理后置 true，插件停止该任务唤醒 |

也可经 RPC 注册（浏览器/agent 侧工具）：POST /dsh-download-monitor/register，见 src/types.ts 的 wire 契约。

agent 行为协议

1. 拉起下载（后台 job 或独立进程）→ 写 manifest（sessionId 填当前会话）→ 结束回合；
2. 收到 【下载监控】 前缀消息 = 插件唤醒：按报告处置（续传/重试/校验/下一阶段）；
3. 处理完后把 manifest 里该任务 ack 置 true（或悬浮窗点「确认」）→ 再次结束回合休息。

悬浮窗操作

- 胶囊 → 点击展开面板；胶囊与面板头部都可拖拽（位置记忆在 localStorage）。
- 「进行中」每行：状态点 / 进度条 / 字节 / 速度 / ETA / 失败原因；运行/停滞任务可「停止」（两步确认：process 直接杀进程，dir/job 仅标记，均不唤醒）；完成/失败任务可点「确认（ack）」。
- 「历史」分区：按批次合并的终态任务（标签/结果徽标/总结/来源会话/完成时间），可单条删除。
- 「设置」：唤醒报告总开关、历史留痕开关、历史保留条数（5-200）、停滞阈值、采样间隔（写回 ~/.dsh/dlmon/state.json）。

agent 使用协议（技能）

全局技能 download-monitor 已注册（~/.dsh/skills/download-monitor/SKILL.md），所有会话在涉及下载时自动加载。核心：启动下载 → 注册 manifest（sessionId 必须带 session- 前缀；批量任务同一次写入或显式 batchId）→ 结束回合休息；收到 【下载监控】 唤醒 → 处理并 ack；用户停止的任务（stoppedBy: 'user'）不重启不补报告；查询历史读 history.json。

开发

pnpm typecheck # tsc --noEmit
pnpm test # vitest（状态机 / manifest 校验 / 报告文本 / job 合并）
pnpm build # tsdown：lib/index.js（host）+ lib/client.js（browser）

已知边界（v1）

- 不自动重启下载器（观察 + 唤醒，决策权留给 agent）；
- job 形态任务：只做状态显示，唤醒走 DSH 原生 job 完成通知；
- 日志尾随只取最后 64KB，错误正则建议用无锚点的行级表达式；
- 悬浮窗只对注册了任务时可见；多标签页各自渲染，唤醒按 manifest 的 sessionId 投递。

排障（本机实战教训）

- dsh plugin add 后启动报 duplicate loader entry id: ui-web-ui-settings：
pnpm 重装会把 profile 的 node_modules 重排，file: 链接可能出现新旧两份导致 loader
重复挂载同一 patch。修复：在 profile 目录重跑 pnpm install（或 pnpm add 触发重解析），再重启。建议在重启前先做预检：
node --import tsx/esm /apps/cli/src/bin.ts web --port 3099（另一个端口），
确认无 loader 报错且端口监听后再动真身。
- GUI 进程就是 agent 进程：重启 dsh web 会杀掉当前回合的 agent。脚本 scripts/restart-gui.ps1 用独立进程完成"杀旧起新"（状态写 %TEMP%\dsh-web-restart.status.json），但保险起见：重启前先告知用户，重启后刷新页面并发消息恢复。
- 验证 host 半区存活（无需重启、无需浏览器）： $body = @{ type='client-request'; rpcId='p'; method='snapshot'; payload=@{} } | ConvertTo-Json -Compress Invoke-WebRequest -Uri 'http://127.0.0.1:3080/dsh-download-monitor/snapshot' -Method POST -ContentType 'application/json' -Body $body -UseBasicParsing

返回 ok:true 即 host 已挂载（配置与任务清单都在响应里）。

许可

MIT © keepermttl。欢迎使用、修改、引用或收录进自己的插件合集，保留 LICENSE 与出处即可。