前言¶
在 DeepSeek Harness（DSH）里跑多会话任务时，常见做法是切回主窗口看进度，或在任务栏里猜哪个窗口还在跑。DSH 生态里插件可以扩展宿主能力；若你希望不占用 DSH 主界面就能一眼看到「有没有在跑、要不要点授权、要不要回复」，就需要一个独立于应用窗口的状态指示。下面介绍社区插件 dsh-float-lamp：由维护者 shZhang1614 发布，分类为客户端，在 Windows 桌面上提供置顶、无边框的小灯窗，与 DSH 进程通过本地状态文件联动。
这是什么¶
dsh-float-lamp 是 DSH 的悬浮任务状态灯插件。宿主侧（lib/index.js）汇总各会话事件并写入 ~/.dsh/float-lamp/state.json；灯窗（widget/lamp.ps1，PowerShell WinForms）在 DSH 窗口之外置顶显示，按颜色与动画反映聚合状态。鼠标悬停可列出正在运行的任务摘要；轻点灯可跳回 DSH 宿主窗口。当前 package 版本为 0.4.2，许可证 MIT，仅支持 Windows。
灯色与判定¶
状态来自对会话日志的折叠（turn/start|end、approval/asked|decided、tool/call|result 等），多会话时优先级为：橙 > 蓝 > 绿 > 灰。
| 灯色 | 含义 | 判定要点 |
|---|---|---|
| 绿 | 运行中 | 存在未闭合的 turn/start |
| 橙 | 待授权 | 存在 approval/asked 且尚未 approval/decided |
| 蓝 | 待交互 | ask_user_question / exit_plan_mode 调用挂起 |
| 灰 | 空闲 | 无活动轮次 |
| 暗灰（宿主离线） | DSH 未运行 | state.json 超过 15 秒未更新，或标记 hostDown |
绿灯时灯上会显示当前状态与计数，并附带本回合已运行时长（分/秒）。绿/橙/蓝状态下可有 20fps 动画（光晕呼吸、抖动、漂浮）；灰与离线时静止。离线超过 60 秒灯进程会自动退出；宿主重启后插件会重新拉起灯。
核心功能¶
宿主插件¶
- 每 800ms 轮询
ctx.sessions.list()，并对session/created、session/event、internal/dispatch做事件订阅，增量折叠日志、按seq去重。 - 聚合结果写入
~/.dsh/float-lamp/state.json（5 秒心跳 + 事件即时更新）。 - 通过
lamp.pid与lamp-alive心跳保证灯窗单实例；进程存活但心跳停止时会回收僵尸灯再拉起。 - 读取
~/.dsh/profiles/<profile>/cordis.patch.yml：若本插件被标记disabled: true，约 5 秒内写hostDown并熄灭灯；重新启用后再拉起。
灯窗交互¶
- 悬停：约 0.3 秒后左侧弹出深色卡片，逐行列出各会话：
[状态] 最近一条用户消息（正在: 工具名）。 - 左键：拖动记忆位置（
pos.json）；轻点未拖动则激活 DSH 宿主（最小化会自动还原）。 - 右键菜单：置顶开关、动画开关、透明度（100/75/50/25%）、大小（小/标准/大）、退出；偏好保存在
settings.json。高 DPI 使用 PerMonitorV2 适配。
渲染上使用 UpdateLayeredWindow 做逐像素 alpha，无卡片背景，仅发光圆灯与描边文字，便于在不同桌面背景下阅读。
安装与启用¶
官方安装命令（profile 为 desktop）：
dsh plugin --profile desktop add github:shZhang1614/dsh-float-lamp
安装后重启 DeepSeek Harness 应用；插件加载后会自动拉起灯窗，无需手动运行脚本。
若需禁止插件自动拉起灯窗，可设置环境变量：
DSH_FLOAT_LAMP_NO_WIDGET=1
手动仅启动灯窗（调试或特殊场景）：
powershell -NoProfile -ExecutionPolicy Bypass -File widget\lamp.ps1
（路径相对于插件源码目录；正常使用由宿主 spawn。）
离线分发：可将发布 zip 解压后在该目录运行 install-offline.ps1（PowerShell 5.1+，且本机已安装并能启动过 DSH）；卸载运行 uninstall-offline.ps1。插件零 npm 依赖，适合内网拷贝安装。
在 dshmarket 中关闭插件会改写 bundles 与 cordis.patch.yml（disabled: true），加载状态下约 5 秒内灯会熄灭；重新开启后需再次重启应用才会加载并亮灯。
典型用法与运行时文件¶
日常使用流程可以概括为：
- 用上述命令安装并重启 DSH。
- 将灯拖到屏幕边缘不挡操作；需要详情时悬停看卡片，需要回到 DSH 时轻点灯。
- 通过右键调整透明度与大小，避免遮挡其他窗口。
运行时数据目录为 ~/.dsh/float-lamp/，常见文件包括：
| 文件 | 作用 |
|---|---|
state.json |
聚合状态（state、counts、runningSince、tasks、updatedAt、hostDown 等） |
pos.json |
灯窗位置 |
settings.json |
透明度、缩放、动画等偏好 |
lamp.pid / lamp-alive |
单实例与探活 |
debug.log / lamp-error.log |
插件与灯窗诊断 |
单独运行灯且无宿主时，灯显示「宿主离线」，60 秒后退出，属预期行为。
适用场景与注意¶
适合：在 Windows 上长期使用 DSH 桌面 profile、多会话并行、且希望任务状态始终可见的开发者；尤其在意授权（橙）与问答（蓝）提醒、又不想频繁 Alt-Tab 回主窗口的场景。
务必知晓：
- 插件在 DSH 宿主进程权限下运行，并会启动本地 PowerShell 灯窗进程；安装前应自行查看 GitHub 仓库 源码与 MIT 许可证。
- 仅 Windows（PowerShell WinForms）；
widget/lamp.ps1须保存为 UTF-8 带 BOM，否则 PowerShell 5.1 解析中文可能报错。 - 社区目录 SkillHub 插件页 与 GitHub 为独立信息源，与 DeepSeek / 幻方无官方从属关系；星标等元数据以各站点当时展示为准。
仓库提供 node test/fold-test.mjs 做状态机断言，GitHub Actions 在 push 时运行测试 workflow。
结尾¶
dsh-float-lamp 把 DSH 的多会话状态收敛成桌面上一盏小灯：绿橙蓝灰与离线一目了然，悬停看任务、轻点回宿主，设置与位置本地持久化。若你在 Windows 上使用 DSH 并想减少「不知道任务卡在哪一步」的切换成本，可按官方命令安装后重启应用即可试用。
