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