YeqingTang/dsh-task-watcher

DSH 任务监视器（DshTaskWatcher）

它是 DSH 的一个纯只读旁路监视器：像贴在 DSH 旁边的探针，只“看”不“动”，不对 DSH 做任何修改、不依赖任何外部组件，随时可独立安装/卸载。

DSH（DeepSeek Harness）的对话任务在浏览器里跑的时候，你可以放心切到别的程序——任务完成 / 失败 / 中断 / 子任务进展 / 需要你批准或回答，都会以 Windows 通知的形式提醒你；托盘图标与监控窗口随时显示所有任务的实时进度。

监控窗口

目录

1. 它能做什么
2. 系统要求
3. 安装
4. 使用
5. 配置 config.json
6. 数据与日志
7. 更新
8. 卸载
9. 常见问题（FAQ）
10. 版本历史

1. 它能做什么

| 功能 | 说明 |
|---|---|
| 托盘图标四态 | 🔴 红 = 需要你处理 ／ 🟠 橙 = 任务运行中 ／ 🟢 绿 = 空闲 ／ ⚪ 灰 = DSH 未连接 |
| 原生悬浮摘要 | 系统原生 tooltip 精简显示：运行中 N · 待处理 M（或 DSH 空闲） |
| 监控窗 | 单击托盘图标弹出完整任务信息（可拖动、可📌固定、点击外部隐藏） |
| 任务完成通知 | 弹出通知：标题 + 本次任务统计（用时 / 回合数 / 步骤数 / 输出 tokens）+ 提示音；多任务并发时附「剩余 N 个任务运行中」 |
| 子任务通知 | 子任务（subagent）完成同样通知，带「子任务」标记 |
| 待处理通知 | 会话需要你批准/回答时立即弹通知 + 提示音（任务开始不推送，避免打扰） |
| 状态窗口 | 始终置顶小窗：运行中任务列表（实时多列细化）+ 最近完成列表 |
| 单任务详情窗 | 双击运行中任务，查看该任务的完整细粒度统计 |
| 快捷操作 | 点击通知气泡 → 打开 DSH 控制台 |
| 断线自愈 | DSH 重启后自动恢复监控，无需任何操作 |

浏览器关闭也不影响监控——它只依赖 DSH 本机服务（127.0.0.1:3080），与浏览器无关。

2. 系统要求

- Windows 11（Windows 10 亦可）
- DSH 已安装并正在运行（默认地址 http://127.0.0.1:3080）
- 无需安装任何运行时——使用系统自带的 Windows PowerShell 5.1 与 WinForms

3. 安装

方式〇：DSH 插件市场（DSH 用户推荐）

在 DSH Web GUI 设置 → 插件 → 插件市场 搜索 dsh-task-watcher 一键安装；或命令行：

dsh plugin --profile web add @yeqingtang/dsh-task-watcher-plugin

插件会把监视器部署到 %LOCALAPPDATA%\DshTaskWatcher 并自动拉起托盘，设置 → 插件 → 任务监视器 提供启停开关。监视器本体保持独立进程生命周期：桌面快捷方式启动、托盘右键退出照常可用，DSH 重启不影响正在运行的托盘。
方式一：安装包（推荐，适用于其他机器）

从 Releases 页面下载 DshTaskWatcher-setup-0.5.4.exe，双击运行即可：

- 安装位置：%LOCALAPPDATA%\DshTaskWatcher（无需管理员权限）
- 可选：桌面快捷方式、开机自启（默认不勾选）
- 安装完成自动启动监视器
- 卸载：开始菜单或控制面板「DSH 任务监视器」卸载程序（保留运行数据在 %LOCALAPPDATA%\DshTaskWatcher\）

方式二：便携版 zip

从 Releases 页面下载 DshTaskWatcher-portable-0.5.4.zip，解压后运行其中的 install.ps1：

powershell -NoProfile -ExecutionPolicy Bypass -File install.ps1

安装脚本做三件事：

1. 复制程序到 %LOCALAPPDATA%\DshTaskWatcher\（保留你已有的 config.json）
2. 创建桌面快捷方式「DSH任务监视器」
3. 立即启动监视器

卸载：解压目录里的 uninstall.ps1。

方式三：源码直接运行（开发调试）

powershell -NoProfile -ExecutionPolicy Bypass -File .\app\DshTaskWatcher.ps1

可选参数（便携版 install.ps1）

额外创建开机自启快捷方式（默认不创建）
powershell ... -File install.ps1 -AutoStart

只安装不启动
powershell ... -File install.ps1 -NoStart

不创建桌面快捷方式
powershell ... -File install.ps1 -NoDesktopShortcut

开机自启默认关闭：避免未经同意常驻。需要时用 -AutoStart 重跑一次安装即可（会同时补创建启动快捷方式，不影响已有配置）。

此时配置/日志仍在 %LOCALAPPDATA%\DshTaskWatcher\（配置优先读取脚本同目录的 config.json）。

4. 使用

4.1 托盘图标

图标在任务栏右下角，四态颜色（优先级从高到低）：

| 颜色 | 含义 |
|---|---|
| 🔴 红 | 有任务需要你处理（等待批准工具调用 / 等待回答提问） |
| 🟠 橙 | 有任务正在运行（1 个或多个） |
| 🟢 绿 | 已连接，无任务运行 |
| ⚪ 灰 | DSH 未连接（host 未启动，自动重试） |
托盘四态状态图标

需要用户介入（选择 / 审批 / 提问）时：

- 图标变红，悬浮提示显示 ⚠ 待处理 N · 运行中 M
- 立即弹出系统通知（标题「需要你的批准」或「有提问待回答」，附会话标题与内容），并播放提示音
- 点击通知 → 打开 DSH 控制台响应
- 处理完毕后（批准/拒绝/回答）自动恢复原状态，无需任何操作
- 该功能基于 DSH 事件流（WebSocket），断线自动重连，重连后自动补回未处理项

4.2 监控窗（单击托盘图标打开）

鼠标左键单击托盘图标弹出监控窗，表格展示所有运行中会话的完整信息：

- 打开方式：左键单击托盘图标（每次单击都展示，已显示则保持）
- 关闭方式：点击窗口外任意位置（未固定时）/ 点 ✕ 按钮
- 始终置顶：展开后在最上层显示，不会被其他窗口遮挡
- 📌 固定（图钉图标，灰=未固定 / 蓝=已固定）：固定后点击其他位置不隐藏，且内容每 3 秒自动刷新
- 拖动：按住标题栏或表格区域任意位置拖动
- 表格：8 列（状态 / 任务 / 用户消息 / 步骤 / 回合 / tps / 时长 / 输出），双行文字（自动换行、超长省略号）、数值列右对齐；时长为冒号钟表格式（9:12 / 1:05:30）；回合数与官方 Web GUI 一致（含进行中的当前回合）
- 状态列：🟢 运行中 / 🟠 重试中（LLM 失败重试）/ 🔴 待批准·待回答（等待你）/ 🟡 子任务 / 完成行按结局着色——⚪ 已完成（灰）/ 🔴 已失败·已中断（红，失败行显示错误消息）/ 🟠 已中止·达上限·被阻断（橙）
- 标题跟随重命名：在 Web GUI 里给会话重命名后，监控窗（含已完成行）最多 2 秒内跟随新标题
- 空闲时（无运行中任务）表格显示最近完成记录列表（统计为会话累计总量）

托盘图标的系统原生悬浮显示精简摘要：运行中 N · 待处理 M（或 DSH 空闲）。

4.3 右键菜单

| 菜单项 | 作用 |
|---|---|
| 打开 DSH 控制台 | 浏览器打开 http://127.0.0.1:3080 |
| 监控窗 | 打开/关闭监控窗（开关） |
| 状态窗口 | 打开/关闭多任务状态窗口（见 4.4） |
| 暂停监控 | 暂停轮询与通知（再点一次恢复） |
| 重新加载配置 | 读取最新 config.json 并立即生效 |
| 编辑配置 | 用记事本打开 config.json |
| 打开日志目录 | 打开 %LOCALAPPDATA%\DshTaskWatcher\logs\ |
| 退出 | 退出监视器 |

托盘右键菜单

点击通知气泡 → 打开 DSH 控制台。

4.4 状态窗口（多任务细粒度监控）

右键托盘 →「状态窗口」。窗口分上下两块，每 3 秒自动刷新（随轮询节奏）：

上方「运行中 (N)」列表——每个运行中任务一行（主任务在前，先开始的在上）：

| 列 | 含义 |
|---|---|
| 任务 | 会话标题（待处理任务前带 ⚠） |
| 类型 | 主任务 / 子任务 / ⚠ 审批中 / ⚠ 提问中 |
| 回合 | LLM 回合数（含进行中的当前回合，与 Web GUI 一致） |
| 步骤 | 已执行的步骤数 |
| 输出 | 累计输出 tokens（如 143k） |
| 速度 | 实时生成速度（t/s） |
| 上下文 | 上下文占用百分比（压力/窗口） |
| 时长 | 本次任务已运行时长 |
| 目录 | 会话工作目录 |

下方「最近完成」列表：最近 10 条完成任务（标题、增量统计、完成时间）。

状态窗口

双击运行中任意一行 → 弹出该任务详情窗：

- 基本信息：标题、会话 ID、类型、状态、工作目录、开始时间、已运行、最后活动
- 进度统计：回合、步骤、输出 tokens、生成速度、LLM 耗时、工具耗时
- 上下文明细：压力 tokens、窗口大小、占用率、未缓存输入、缓存读取
- 其他：规划模式、目标（goal）、待办（todos）数量

4.5 通知示例

任务完成通知

5. 配置 config.json

配置文件位置：安装目录 %LOCALAPPDATA%\DshTaskWatcher\config.json（便携运行时在脚本同目录）。
改完用右键菜单「重新加载配置」立即生效，无需重启。

| 配置项 | 默认值 | 说明 |
|---|---|---|
| baseUrl | http://127.0.0.1:3080 | DSH 服务地址（一般不用改） |
| openUrl | http://127.0.0.1:3080 | 点击托盘/通知时打开的地址 |
| pollSeconds | 3 | 轮询间隔（秒），最小 1。越短响应越快，本机开销可忽略 |
| toastOnStart | false | 任务开始时是否推送系统通知（默认不推送，只在完成/待处理时推送；需要可改 true） |
| toastOnFinish | true | 任务完成时是否通知 |
| playSoundOnFinish | true | 完成通知是否播放提示音 |
| toastForSubagents | true | 子任务开始/完成是否也通知（子任务多时可关掉减少打扰） |
| statusWindowOnTop | true | 状态窗口是否始终置顶 |
| notifyOnUserAction | true | 会话需要用户介入（审批/提问）时弹系统通知 |
| attentionSound | true | 介入通知播放提示音 |

6. 数据与日志

程序数据目录：%LOCALAPPDATA%\DshTaskWatcher\

| 文件 | 说明 |
|---|---|
| status.json | 每次轮询更新的状态快照：连接状态、运行中任务（含回合/步骤/tokens/速度/上下文/LLM 与工具耗时/plan/goal/todos 等细粒度字段）、最近完成记录。可用于调试或二次开发 |
| logs\watcher.log | 运行日志：启动、连接/断开、任务开始/完成（含统计），超过 200KB 自动裁剪 |
| icons\ | 自动生成的托盘图标（灰/绿/橙/红） |
| config.json | 你的配置 |

7. 更新

用新版文件重新运行 install.ps1 即可（覆盖安装，保留既有 config.json），随后按提示重启监视器（或右键托盘 → 退出后重新启动）。

8. 卸载

安装包方式：开始菜单或「设置 → 应用」中找到「DSH 任务监视器」→ 卸载（或运行安装目录 unins000.exe）。

便携版方式：运行解压目录里的 uninstall.ps1：

powershell -NoProfile -ExecutionPolicy Bypass -File uninstall.ps1

卸载脚本：停止监视器进程 → 删除桌面/启动快捷方式 → 删除 %LOCALAPPDATA%\DshTaskWatcher\。

保留配置与日志
powershell ... -File uninstall.ps1 -KeepData

安装包卸载默认保留运行数据（日志/status.json），如需彻底清除可手动删除 %LOCALAPPDATA%\DshTaskWatcher\。

9. 常见问题（FAQ）

Q1：安全软件（如火绒）把快捷方式删了 / 拦截了？
这是误报——本工具只读取本机 DSH 状态、发通知，无任何网络外联。处理：
1. 火绒 →「病毒查杀」→「隔离区」→ 恢复被删文件（如有）
2. 火绒 →「菜单(≡)」→「安全设置」→「信任区」→ 添加安装目录：%LOCALAPPDATA%\DshTaskWatcher
3. 重新运行 install.ps1

Q2：托盘图标看不到？
点击任务栏右下角「^」展开隐藏图标；或右键任务栏 →「任务栏设置」→「选择要在任务栏上显示的图标」，把「DSH任务监视器」打开。

Q3：图标是灰色？
DSH 服务没启动或地址不对。确认 dsh web 正在运行、浏览器能打开 http://127.0.0.1:3080；检查 config.json 的 baseUrl。

Q4：没有收到完成通知？
- 检查是否点过「暂停监控」（图标会变灰并显示"已暂停"）
- 检查 toastOnFinish / playSoundOnFinish 配置
- Windows 通知中心设置里确认允许此应用通知
- 任务完成早于轮询间隔（默认 3 秒）的瞬时任务可能检测不到，可调小 pollSeconds

Q5：中文会乱码吗？
不会。程序显式按 UTF-8 编解码（旧版 PowerShell 命令的常见乱码问题已规避）。

Q6：怎么开机自启？
安装时加 -AutoStart 重跑 install.ps1，或手动把「DSH任务监视器」快捷方式复制到启动目录（Win+R 输入 shell:startup）。

Q7：能同时开两个监视器吗？
不能也不需要——程序有单实例锁，重复启动会自动退出。（演示模式 -Demo 除外，它用于截图/展示，与正式实例互不干扰。）

Q8：为什么完成通知提示"剩余 N 个任务运行中"？
多任务并发时，某个任务先完成而其他任务还在跑，通知会附上剩余数量，方便你判断整体是否全部跑完。

10. 版本历史

| 版本 | 内容 |
|---|---|
| v0.5.1 | 会话结局监控：失败 / 中断 / 中止 / 达上限 / 被阻断分级通知与着色（附错误消息）、LLM 失败重试「重试中」状态、断连自动识别为「会话中断」；用户消息列（回合粒度解析 + 深窗口兜底，超长回合不再误显「本回合持续中」）；标题跟随会话重命名（含已完成行）；回合数口径与官方 Web GUI 对齐（含进行中回合；已完成行改会话累计总量）；监控窗排版修复（列错位 / 纵向居中 / 刷新闪烁）；时长列钟表格式（1:05:30）；面板横向收紧（716px） |
| v0.5.2 | 性能与稳定：网络轮询全部移入后台线程（UI 零阻塞，常驻内存约 -40%，空闲自动降频）；右键退出强退兜底；全局鼠标钩子按需装卸。数据正确性：监视器启动时继承运行中任务的真实时长与累计输出；tps 改用官方口径修复恒 0；监控窗每秒实时刷新 + 二次打开数据冻结修复。无终端启动：conhost --headless 启动链，双击图标不再出现终端窗口 |
| v0.5.3 | 插件市场 + 多实例安全：可从 DSH 插件市场一键安装（dsh-task-watcher 插件，Web GUI 内启停开关）；单实例互斥（与插件版并存不双开）；停止意图记忆（插件管理下 DSH 重启不擅自拉回已停托盘） |
| v0.5.4 | DSH 0.1.2 兼容：适配新版 API 签名 Cookie 认证与端点迁移（session/list、session/page）；事件流端点移除后自动退避纯轮询 |
| v0.5.0 | 首个公开发布版本：托盘四态图标（灰/绿/橙/红，状态色大圆+白色脉冲折线）；单击托盘图标弹出监控窗（始终置顶、可拖动、📌固定、点击外部隐藏、3 秒自动刷新）；系统原生悬浮摘要；任务完成/子任务/待处理通知（含统计与提示音、「剩余 N 个任务运行中」）；状态窗口（运行中 9 列明细 + 最近完成）+ 双击详情窗；基于 DSH 事件流（WebSocket）的审批/提问实时提醒；断线自动重连；零第三方依赖（PowerShell 5.1 + WinForms）；Inno 安装包与便携 zip 两种分发形态 |

开源许可

本项目采用 Apache License 2.0，详见 LICENSE。

图标致谢

- 固定按钮图钉图标来自 Bootstrap Icons（icons.getbootstrap.com），MIT License，可商用；生成脚本见 tools/make-pin.ps1

打包发布

- 安装包 / 便携版打包流程见 packaging/PACKAGING.md
- 构建产物（安装包 / 便携 zip）发布在 Releases