前言¶
用 DeepSeek Harness（DSH）跑长任务时，目标 phase、Todo 清单和「待确认 / 已完成未查看」往往都在主窗口里。最小化或切到别的应用后，要再点开 DSH 才能扫一眼状态。若你希望在桌面上常驻一块小区域显示同一套信息，并在 DSH 里用开关控制启停，社区插件 dsh-task-overlay 就是面向这个场景的客户端扩展。
下面介绍它做什么、怎么装、怎么用，以及 Windows 桌面浮窗与跨平台侧栏各自负责什么。
这是什么¶
dsh-task-overlay 由维护者 gg947919490-byte 发布，分类为客户端插件。它在 DSH 窗口之外放一个桌面悬浮窗，实时展示当前任务状态；同时在 DSH 侧栏提供「桌面浮窗」启停开关。
桌面浮窗部分基于 PowerShell + WPF，仅支持 Windows。DSH 内的开关与 GUI 向浮窗推送状态，这部分逻辑随 DSH 客户端跨平台可用（非 Windows 上仍可使用侧栏开关与状态推送，但无桌面 WPF 窗口）。
核心功能¶
目标与 Todo¶
浮窗与 DSH 侧同步的内容包括：
- 目标状态：phase（进行中 / 已暂停 / 受阻 / 已完成）、objective、第 N/M 轮、受阻原因
- Todo 进度：进度条与清单（已完成 / 进行中 / 待办）
- 提醒：跨所有会话统计——N 个会话等待确认、N 个会话已完成未查看
生命周期行为¶
- 最小化或关闭 DSH 窗口后，桌面浮窗仍可存在
- DSH 完全退出后，浮窗不会自动消失，但会显示「DSH 未运行」
DSH 侧控制¶
安装并刷新页面后，侧栏底部会出现「桌面浮窗」开关（绿点表示运行中），用于启停桌面浮窗进程。
安装与启用¶
插件要求 Node >= 20、DSH >= 0.2.0-0（见仓库 package.json）。许可证为 MIT。
插件市场（推荐）¶
先安装市场插件 dshmarket，在 DSH 中打开 设置 → Plugin Market，搜索 dsh-task-overlay 一键安装。
DSH 官方插件页¶
在安装框填写：
github:gg947919490-byte/dsh-task-overlay
或粘贴 Release 中 dsh-task-overlay.tgz 的直链。
CLI¶
dsh plugin add gg947919490-byte/dsh-task-overlay
安装完成后刷新一次 DSH 页面（F5），侧栏底部应出现「桌面浮窗」开关。
典型用法¶
| 入口 | 操作 |
|---|---|
| DSH 侧栏底部「桌面浮窗」开关 | 点击启停桌面浮窗（绿点=运行中） |
浮窗标题栏 ▾ / ▸ |
展开详情 / 收成 190×32 迷你胶囊 |
| 拖动浮窗标题栏 | 移动位置（位置与折叠状态会记住） |
浮窗 ✕ |
关闭浮窗进程（可在 DSH 侧栏开关重新打开） |
不经过 DSH 开关首次启动：双击 desktop\launch-overlay.cmd 或 desktop\launch-overlay.vbs。
开机自启：将 launch-overlay.vbs 的快捷方式放入 shell:startup。
工作原理（简要）¶
数据不由宿主从 root 上下文投影（读不到会话作用域的 todos / goal），而由 DSH GUI 客户端推送：
DSH GUI（客户端插件，拥有完整会话状态）
│ POST 压缩快照 → 127.0.0.1:45123（2 秒心跳，变化即时推送）
▼
桌面浮窗（独立 WPF 进程 + 内置 TCP 监听）
▲
│ 侧栏开关 → 同源相对路径 /task-overlay/control（start/stop/toggle/status）
DSH 宿主（本包宿主半边）—— start 用 spawn 拉起浮窗，stop 发 {"cmd":"stop"} 优雅关闭
浮窗判断 DSH 是否存活采用三段式：≤20 秒视为实时；>20 秒保留最后一帧并标注数据年龄；>150 秒且宿主端口拒连才显示「DSH 未运行」。
配置与排查¶
常用配置¶
| 位置 | 参数 | 默认 | 说明 |
|---|---|---|---|
dsh/client.js |
BRIDGE_URL |
http://127.0.0.1:45123/task-overlay |
客户端推送地址，需与浮窗 -Port 一致 |
desktop/task-overlay.ps1 |
-Port |
45123 |
桥接监听端口 |
| 同上 | -DshPort |
19387 |
宿主端口，用于存活探测 |
| 同上 | -Width |
300 |
展开态宽度（200–520） |
| 同上 | -StateFile |
~/.dsh/task-overlay/desktop-window.json |
位置/折叠记忆 |
端口被占用时：修改 -Port，并同步 dsh/client.js 的 BRIDGE_URL。
排查¶
- 最近一帧快照：
~/.dsh/task-overlay/last-payload.json - 浮窗未出现：确认已 F5 刷新、侧栏开关为「开」；或手动运行
desktop\launch-overlay.cmd
安全说明（使用前应了解）¶
- 宿主控制接口绑定 webServer 自身监听地址（默认
127.0.0.1），并校验请求Origin为同源或dsh-app://app - 桥接端口（45123）无鉴权，仅绑定回环；本机其他进程理论上可伪造显示数据或触发关闭，属 README 中说明的已知限制
适用场景与注意¶
适合：在 Windows 上长时间跑 DSH 任务、希望桌面一角常驻目标 / Todo / 会话提醒，又不想反复切回主窗口的开发者。
注意：
- 桌面 WPF 浮窗仅 Windows；其他系统只能依赖 DSH 内开关与客户端推送逻辑
- 插件以当前 DSH 进程权限运行；安装前建议阅读 GitHub 仓库 源码与 MIT 许可证
- 社区目录 SkillHub 插件页 为独立生态站点，与 DeepSeek / 幻方无官方从属关系
结尾¶
dsh-task-overlay 把 DSH 会话里的 goal、Todo 进度和跨会话确认提醒，推到独立桌面浮窗，并用侧栏开关统一管理启停。Windows 用户按上述 CLI 或插件市场安装、刷新后即可试用。
