dsh-task-overlay · 任务悬浮窗
在 DSH 窗口之外放一个桌面悬浮窗，实时显示当前任务状态；并在 DSH 侧栏提供一个启停开关。
- 目标状态：phase（进行中 / 已暂停 / 受阻 / 已完成）、objective、第 N/M 轮、受阻原因
- Todo 进度：进度条 + 清单（✔ 已完成 / ◐ 进行中 / ○ 待办）
- 提醒：N 个会话等待你确认、N 个会话已完成未查看（跨所有会话）
- 最小化或关闭 DSH 后，桌面浮窗依然存在；DSH 完全退出后它会显示「DSH 未运行」但窗口不消失
桌面浮窗（PowerShell + WPF）仅支持 Windows；DSH 内的开关与状态推送跨平台。
安装
插件市场（推荐）：先安装市场插件 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。
工作原理
DSH GUI（客户端插件，拥有完整会话状态）
│ POST 压缩快照 → 127.0.0.1:45123（2 秒心跳，变化即时推送）
▼
桌面浮窗（独立 WPF 进程 + 内置 TCP 监听）
▲
│ 侧栏开关 → 同源相对路径 /task-overlay/control（start/stop/toggle/status）
DSH 宿主（本包宿主半边）—— start 用 spawn 拉起浮窗，stop 发 {"cmd":"stop"} 优雅关闭
- 数据不来自宿主投影（root 上下文读不到会话作用域的
todos/goal），而由 GUI 客户端推送。
- 浮窗判断 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 | 位置/折叠记忆 |
安全说明
- 宿主控制接口只绑定 webServer 自身监听地址（默认
127.0.0.1），并校验请求 Origin 为同源或 dsh-app://app，防止任意网页 CSRF 启停。
start 只执行包内固定脚本路径，不接受任何外部输入拼接。- 桥接端口（45123）无鉴权，仅绑定回环；本机进程可伪造显示数据或触发关闭，属已知限制。
排查
- 最近一帧快照：
~/.dsh/task-overlay/last-payload.json
- 浮窗没出现：确认 DSH 已刷新（F5）、侧栏开关显示「开」；或手动跑
desktop\launch-overlay.cmd
- 端口被占：改
-Port 并同步 dsh/client.js 的 BRIDGE_URL
开发备注（DSH 0.2.0-rc.2 实测）
- 客户端 bundle 为手写零构建：
window.__ModuleLoader__.load({ id: 包名, factory })，只 require 平台种子模块。
- 宿主行必须指向包根；
apply 必须同步；宿主代码热生效需换新包名（Node ESM 按解析路径缓存）。
- 宿主
spawn 子进程不要用 detached: true（pwsh 会立即退出）。
- 本包不声明 peer，避免版本兼容校验把整包判为不兼容。
License
MIT
