前言¶
用 DeepSeek Harness（DSH）跑智能体会话时，进度往往只在主窗口里：阶段切换、工具调用、todo 完成情况要切回 DSH 才能看清。窗口最小化或暂时关掉界面后，更难判断「现在是在排队、思考还是在跑工具」。下面介绍社区插件 dsh-widget（大肥鱼桌面挂件）：在 Windows 桌面上单独开一条置顶、透明背景的可拖拽鱼娘，实时读 Host 写出的进度快照；可选在 DSH 退出后仍留在桌面，并在需要审批时用气泡和角标提醒你。
这是什么¶
dsh-widget 由维护者 oioiphainon 发布，在 SkillHub 等社区目录中归类为客户端插件。它不做 DSH 内的网页浮层（旧版 legacy/ 已停用），而是 Host（index.js）配合 PowerShell + WinForms 桌面进程（desktop/FatFishDesktop.ps1），通过 %LOCALAPPDATA%\dsh-fat-fish\state.json 与 DSH 解耦：关掉 DSH 窗口甚至退出 DSH 程序后，鱼仍可留在桌面上（超过约 7 秒无新数据时气泡会显示「DSH 未运行」类文案，DSH 再启动会自动接上）。
核心功能¶
进度与上下文¶
Host 监听会话与 agent 状态，折叠出 progress / approvals，并以约 800 ms 心跳（及事件后 120 ms 补写）原子写入 state.json；挂件约每 180 ms 读取该文件并绘制。气泡与详情面板可展示：
- 阶段：排队、思考、输出、执行工具、完成、出错等，以及轮次、步骤、工具次数、用时；
- 当前工具名与目标（如
grep、pwsh等，部分工具有中文别名）； - todo 完成度、进度条与逐条清单状态；
- 后台任务、会话目标（第 n/m 轮）、团队任务，以及其它正在跑的会话数量。
调试时 Host 还提供 GET /api/fat-fish/progress（需浏览器认证），结构与落盘数据一致。
桌面交互¶
- 透明 PNG 素材（
desktop/fish.png），无白底圆盘；整鱼可拖，位置与 UI 状态写入%LOCALAPPDATA%\dsh-fat-fish\widget.json。 - 单击在气泡与详情面板间切换；右键可展开/收起、大小（小/中/大）、归位（默认右下角，并避开
dsh-whale-widget鲸鱼位置）、退出。 - 隐藏悬浮窗：右键一键隐藏（不持久化，避免下次登录误以为故障）；恢复可点系统托盘小鱼图标，或再次运行
desktop\launch-widget.vbs（单实例锁会通过show-request唤醒隐藏实例）。 - 开机自启（可选，默认关）：在启动文件夹创建指向
launch-widget.vbs的快捷方式；DSH 退出后保留悬浮窗（可选，默认开）：写入widget.json的keepAfterExit；关闭后 Host 停止写快照约 30 秒宽限后挂件自行退出。
审批提醒¶
Host 从会话日志读取 approval/asked / approval/decided，不拦截 approval/request 瀑布。有待审批时气泡变琥珀色「需要你审批」，鱼挂 ! 角标并可选提示音（widget.json 的 alertSound）；点击卡片将 DSH 窗口提到最前。处理结果会约 6 秒显示「已允许 / 已拒绝」等映射文案。右键可关审批提示音。
随 DSH 启动¶
插件加载后 Host 在约 1.5 秒内通过 desktop\launch-widget.vbs（VBS 静默启动，避免子进程随 Host 作业对象一起被带走）拉起桌面挂件，单实例互斥，重复拉起不会叠出第二条鱼。
安装与启用¶
环境：Windows 10/11 + DeepSeek Harness；系统自带 PowerShell 5.1，无需管理员；挂件不联网、不上传数据。
推荐用官方文档中的命令安装（--profile desktop 请换成你实际 profile，可先 dsh profile list）：
dsh plugin --profile desktop add github:oioiphainon/dsh-widget
需要固定版本时可钉 tag，例如 README 中的：
dsh plugin --profile desktop add github:oioiphainon/dsh-widget#v0.4.2
装好后 DSH 加载插件时会自动拉起挂件；也可手动双击插件目录下 desktop\launch-widget.vbs。验证：桌面右下角出现鱼与气泡，任务栏托盘（可能在溢出面板）有小鱼图标。
卸载示例：
dsh plugin --profile desktop remove @local/dsh-fat-fish-widget
再右键鱼 → 退出；配置目录 %LOCALAPPDATA%\dsh-fat-fish 可手动删除以清空本地状态。
典型用法¶
- 安装并打开 DSH，等待桌面右下角出现大肥鱼；会话运行时观察气泡中的阶段与当前工具。
- 需要看 todo、后台任务或团队任务时，单击鱼展开详情面板；拖鱼到习惯位置，位置会自动记住。
- DSH 弹出工具审批时，看琥珀色气泡与
!角标，点卡片切回 DSH 处理；若不想被打扰，右键关闭「审批提示音」。 - 只想用 DSH 时出现挂件：右键关闭「DSH 退出后保留悬浮窗」；希望登录就有鱼、DSH 未开也显示「DSH 未运行」：右键开启「开机自启」。
- 临时不想看到鱼：右键「隐藏悬浮窗」，再从托盘小鱼左键恢复。
全局 UI 缩放可在 desktop/FatFishDesktop.ps1 中调整 $script:UiScale（默认 1.12），改完需右键退出挂件后重新启动生效。
适用场景与注意¶
适合在 Windows 上长期开 DSH、希望任务进度始终贴在桌面上、且关心审批是否 pending 的开发者。与「只在 DSH 窗口内看日志」相比，挂件独立进程、置顶透明窗，最小化 DSH 不影响看进度。
使用前请注意：
- 插件以当前 DSH 进程及其拉起的 Host 逻辑运行；桌面脚本来源为 GitHub 仓库，安装前建议浏览源码与仓库声明的许可与版本（
package.json当前版本为 0.4.2，包名@local/dsh-fat-fish-widget）。 - 仅支持 Windows；Linux/macOS 不适用。
- 社区目录（如 SkillHub 插件页）由社区维护，与 DeepSeek / 幻方无官方从属关系；DSH 生态是「一切皆插件」，本插件是其中一条客户端向扩展。
结尾¶
dsh-widget 把 DSH 最近活跃会话的进度、todo 与审批状态，通过本地 state.json 喂给桌面置顶鱼娘，并可选开机自启、DSH 退出后保留与一键隐藏。若你在 Windows 上跑 Harness，又希望「打开 DSH 就有一条鱼在桌上报进度」，可按上文命令安装并在托盘与右键菜单里按需调节行为。
- 目录页：https://www.skillhub.cn/plugins/oioiphainon/dsh-widget
- 源码与完整说明：https://github.com/oioiphainon/dsh-widget
