任务胶囊 zoe1nan/dsh-hud

DSH Task HUD · 小蓝鲸任务胶囊

给 DeepSeek Harness 加一颗「液体能量」任务胶囊：一颗浮在桌面最上层的悬浮窗，用官方小蓝鲸和一条会流动的蓝色液体，实时汇报当前会话的 todo 进度。

工作台最小化，或被全屏窗口完全盖住时，它出现在桌面上；切回工作台就自动收起。悬停看百分比，点一下展开任务卡，按住可以拖到任何位置。

截图里的任务与步骤都是示例数据，不包含任何真实会话内容。

功能

- 纯桌面悬浮：没有页面内 HUD，不会插进工作台界面；只在桌面置顶窗里出现一颗胶囊。
- 液体即进度：蓝色液体的液面位置 = 已完成步骤 / 总步骤；液面有波动、气泡和辉光，不是一根生硬的进度条。
- 只在需要时出现：工作台被最小化（IsIconic），或前台是一块铺满整屏、且不属于 DSH 的窗口（全屏视频 / 游戏 / 远程桌面）时才显示；Alt+Tab 切普通窗口、打开截图工具都不会把它叫出来。
- 悬停看百分比：鼠标停在胶囊上 150ms，3/5 原地淡换成 60%，移开 400ms 换回；不展开、不位移。
- 点击展开任务卡：单击胶囊展开/收起任务卡——标题、状态、进度、步骤清单（✓ / ● / ○）、当前动作、耗时；点卡片外部也能收起。
- 拖动跟手：按住胶囊可以拖到任意位置；拖拽位移用屏幕坐标差计算并按设备像素对齐，不会来回抖。位置记在 ~/.dsh/dsh-hud/overlay-pos.json，下次启动原地恢复。
- 跟着系统明暗走：读 Windows 个性化设置里的 AppsUseLightTheme，深色磨砂玻璃 / 浅色纸面白玻璃两套皮肤实时切换。
- 完成态：液体满格 → 读数变对勾，停留 6.5 秒后淡回「待命」。
- 不被截图：置顶窗声明了 WDA_EXCLUDEFROMCAPTURE，截图 / 录屏工具拍不到它，不会在截图里叠出一颗 HUD（Windows 10 2004+；更老的系统会退化成「黑块」式遮挡）。
- 字体：HUD 用 Noto Sans SC，不再是系统默认的微软雅黑；没装 Noto 的机器会回退到系统 CJK 字体。
- 只读：HUD 只读取 DSH 已经产生的 todo / turn 状态，不写入、不改动会话，也不联网。

安装

前置：DeepSeek Harness 桌面版（自带 dsh CLI，安装目录下 resources/runtime/cli/bin/dsh.cmd）、Windows 10/11（桌面置顶窗使用系统自带 PowerShell 5.1 + WPF，无第三方依赖）。插件只有 Windows 端实现：其他系统上宿主半仍会运行，但没有可显示的窗口。

方式一：目录安装（推荐）

git clone https://github.com/zoe1nan/dsh-hud.git
dsh plugin --profile desktop add /path/to/dsh-hud

方式二：打包安装

pnpm pack # 或 npm pack，得到 dsh-hud-1.1.0.tgz
dsh plugin --profile desktop add /path/to/dsh-hud-1.1.0.tgz

安装后重启 DeepSeek Harness（桌面版重启才会加载新插件）。重启后把工作台最小化，胶囊就会出现在桌面上；第一次启动时置顶窗脚本需要一两秒准备。

使用

- 悬停胶囊：3/5 ↔ 60% 切换。
- 单击胶囊：展开 / 收起任务卡。
- 按住拖动：拖到任意位置，松手即记住（overlay-pos.json）。
- 任务完成后：满格 → 对勾 → 6.5 秒后回到「待命」。
- 进行中但还没写 todo 时：胶囊显示「进行中」，液体呼吸但不虚构百分比。
- 工作台恢复前台后：桌面胶囊自动隐藏，直到下次最小化或被全屏窗口盖住。

数据与隐私

- 所有数据都在本机：宿主把当前状态写到 ~/.dsh/dsh-hud/state.json，置顶窗只读这个文件。
- 不联网、不上传、不写会话；插件目录里没有账号、密钥或本机路径。
- 可随时删除 ~/.dsh/dsh-hud/ 重置（不影响会话数据）。

工作原理

DSH sessions ──todos 投影 / turn 事件──▶ Host 半 (index.js) │ 折叠成一份只读状态 └──▶ ~/.dsh/dsh-hud/state.json ──▶ 桌面置顶窗 (overlay.ps1, WPF)

- Host 半（index.js）：注入 sessions / sessionProjections，用 sessionProjections.snapshot() 读 todos 与 title，用 session/event 折叠 turn 运行状态；输出 status（charging / waiting / done / noplan）、步骤数组、百分比与当前动作；按需拉起置顶窗进程，并用 15 秒心跳看门狗维持单实例。
- 桌面置顶窗（overlay.ps1）：无边框、透明、Topmost 的 WPF 窗口；与宿主通过文件 IPC（状态、心跳、位置）协作；单实例 Mutex；-ParentPid 守护，宿主退出即退出；进程意外退出会被看门狗自动拉起。
- 形态交接：置顶窗每 400ms 检查两个条件——工作台窗口是否 IsIconic（最小化），以及前台窗口是否是一块铺满整块屏幕且不属于 DSH 的窗口（全屏视频 / 游戏等）；满足任一才显示。
- 主题：每 350ms 先按系统明暗切换调色板，再读状态，不依赖宿主下发。
- 不进截图：显示时调用 SetWindowDisplayAffinity(hwnd, WDA_EXCLUDEFROMCAPTURE)；调试期可用环境变量 DSH_HUD_ALLOW_CAPTURE=1 或文件开关关闭（便于截图验收）。
- 拖拽：按下时记录鼠标的屏幕物理像素坐标与窗口 Left/Top，移动时用屏幕坐标差 / DPI 得到 DIP 位移，并按整设备像素对齐，避免「窗口内坐标 → 窗口移动 → 相对坐标反向变化」形成的抖动反馈环。

目录结构

dsh-hud/
├── index.js # Host 半：状态折叠 + 置顶窗拉起/看门狗 ├── overlay.ps1 # Windows 桌面置顶窗（PowerShell 5.1 + WPF） ├── whale.png # 官方小蓝鲸图标（透明 PNG） ├── whale.svg # 官方鲸鱼矢量路径（来源：DSH 界面图标） ├── cordis.patch.yml # 插件装配 ├── package.json └── docs/ # README 截图

开发与调试

- node --check index.js 做语法检查；overlay.ps1 用 PowerShell 解析器校验（脚本必须带 UTF-8 BOM，否则中文注释会让 Windows PowerShell 5.1 按 ANSI 解析而报错）： $s = Get-Content -Raw overlay.ps1
$e = $null; [System.Management.Automation.Language.Parser]::ParseInput($s, [ref]$null, [ref]$e) | Out-Null
if ($e.Count) { $e | Select-Object -First 5 }

- 首次安装后如果桌面窗没出现，查看 ~/.dsh/dsh-hud/overlay-spawn.log 与 overlay.log。
- 置顶窗被看门狗拉起时无法传环境变量，调试也可以在 %USERPROFILE%\.dsh\dsh-hud\ 下新建空文件：force-show（强制显示）、allow-capture（允许被截图）、snapshot（标志存在期间每 1.2 秒把窗口自身渲染成 overlay-snapshot.png，用于检查真实排版；删掉文件即停止）；删掉文件即恢复。
- 置顶窗把窗口起点、尺寸直接按 DIP 写回 overlay-pos.json，拖动位置就存在这里。
- 同步到本地安装目录时注意：本地副本的 package.json 包名与 cordis.patch.yml 必须与安装方式一致（本文档仓库副本用 dsh-hud，本地 link 安装通常用 @local/dsh-hud）。

已知限制

- 桌面置顶窗目前只支持 Windows（PowerShell 5.1 + WPF 自绘，无第三方依赖）。
- 进度数据来自 DSH 的 todo_write；还没有写 todo 的轮次会显示「进行中」而不是虚构百分比。
- 超过 45 分钟没有新事件的会话不再参与显示（避免旧任务常驻）。
- 目前没有独立的设置页（尺寸/位置/开关后续可加；置顶窗位置可拖动保存）。
- 更新插件代码后需要重启 DeepSeek Harness 才会加载新版本。

License

MIT

DeepSeek Harness 的「液态能量」任务 HUD 插件。桌面端专用的置顶胶囊，带官方鲸鱼图标：工作台最小化，或被另一个全屏窗口完全盖住时，胶囊浮在桌面上；工作台回来，它再隐藏。液面高度 = 已完成步骤 / 总步骤。悬停把 3/5 换成 60%；点击展开任务卡，里面有步骤清单、当前动作和已用时间；拖到任意位置，位置会记住。它跟随 Windows 浅色/深色设置，不会被截图拍到（WDA_EXCLUDEFROMCAPTURE），所有状态都放在 ~/.dsh/dsh-hud/ 下。没有页内 HUD。

用 dsh plugin --profile desktop add <path-or-tgz> 安装，然后重启 DeepSeek Harness。仅支持 Windows（PowerShell 5.1 + WPF，无第三方依赖）；严格只读，不联网。

MIT 许可。