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 <deepseek-harness>/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": "<注册该任务的会话 id>",
      "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 <checkout>/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 半区存活（无需重启、无需浏览器）：

```powershell

$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 已挂载（配置与任务清单都在响应里）。

dsh-download-monitor

Install

Check the source files

dsh-download-monitor

特性

安装

任务注册（manifest 协议）

agent 行为协议

悬浮窗操作

agent 使用协议（技能）

开发

已知边界（v1）

排障（本机实战教训）

许可

Source facts

Install

Check the source files

dsh-download-monitor

特性

安装

任务注册（manifest 协议）

agent 行为协议

悬浮窗操作

agent 使用协议（技能）

开发

已知边界（v1）

排障（本机实战教训）

许可

More related plugins

dsh-archive-viewer

OpenViking#examples/dsh-memory-plugin

hindsight#coding-agents