前言¶

智能体开发时，我们经常需要盯着进程状态：轮次走到第几步、当前在执行什么工具、todo 完成度、审批是否在等。DSH 的任务进度是持久化在日志里的，要查就得去翻日志或看 UI，不够顺手。

大肥鱼桌面挂件（Fat Fish desktop widget）给桌面加了一只「常驻」的鱼娘：它是一个悬浮在 Windows 桌面上的透明窗口，始终置顶，独立于 DSH 进程，关掉 DSH 窗口甚至程序，鱼还在桌面上继续显示当前会话的进度和审批提醒。

插件定位¶

• 维护者：danheng383-commits
• 分类：客户端
• 插件：danheng383-commits/dsh-widget

这是一款 Windows 桌面挂件插件，通过读取本机 state.json 来展示最近活跃会话的轮次、步骤、工具调用、todo 进度、后台任务与团队任务，并提供审批提醒和窗口拉起功能。

核心功能¶

桌面级置顶¶

挂件是一个独立的 WinForms 分层窗口（per-pixel alpha），浮在所有应用之上，不属于 DSH 窗口。窗口最小化或关闭 DSH，都不会带走这只鱼。

实时进度¶

DSH Host 会把最近活跃会话的进度写入 %LOCALAPPDATA%\dsh-fat-fish\state.json。挂件读取该文件，显示当前阶段（排队 / 思考 / 输出 / 执行工具 / 完成 / 出错）、轮次、步骤、工具次数、耗时。

当前工具与目标¶

展开面板会显示当前工具名（如 grep、pwsh、todo_write 等）以及目标参数，工具名支持中文别名。

任务清单¶

面板显示 todo 的完成度百分比、进度条与逐条清单（✓ / ◐ / ○）。

更多上下文¶

• 后台任务（jobs）：显示正在跑的子任务及其状态。
• 会话目标：当前在第 n/m 轮。
• 团队任务：展示团队任务信息。
• 其它正在跑的会话数：如果有多个会话在跑，会提示总数。

交互¶

• 拖动：按住鱼拖到任意虚拟屏幕位置，位置会自动记住。
• 展开/收起：单击鱼，或在右键菜单中选择「展开详情 / 收起」。
• 大小：右键菜单里提供「大小 → 小 / 中 / 大」。挂件内部有一个全局缩放 $script:UiScale（默认 1.12），几何与字号一起等比放大。
• 归位：右键菜单「回到默认位置」（默认在右下角，避开其它挂件）。
• 退出：右键菜单「退出」，或结束进程 powershell.exe（窗口标题 FatFishDesktop）。
• 状态存储：位置与状态保存在 %LOCALAPPDATA%\dsh-fat-fish\widget.json。

关掉 DSH 后的行为¶

• 超过 7 秒没有新数据，气泡会变成「DSH 未运行 / 大肥鱼在桌面上等你回来」，鱼继续留在桌面。
• DSH 再次启动后，挂件会自动接上数据。

审批提醒¶

DSH 将审批请求作为持久化事件（approval/asked / approval/decided）写入日志，Host 读取这两类事件，不拦截 approval/request 瀑布。

• 有待审批项时：气泡变琥珀色卡片，标题「需要你审批」，下方显示工具名 + 原因。如果收起，卡片本身就是弹窗。
• 鱼右上角挂一个琥珀色的「!」角标。
• 展开面板顶部会插入「等待你审批」的提示区。
• 点卡片会把 DSH 窗口提到最前，直接去处理「允许/拒绝」。
• 新审批出现时会播一次系统提示音；右键菜单「审批提示音」可关闭（持久化在 widget.json 的 alertSound）。
• 审批有结果时会闪 6 秒确认：approval/decided 的 outcome 映射成「已允许 / 已拒绝 / 已取消 / 审批未完成」，面板标题和气泡变色，鱼上角标换成 ✓ / ✗ / —。
• 卡片、角标随后消失；回合结束或 DSH 停止写入时也会自动清理。

安装与启用¶

本插件通过 plugin_manager 安装，安装后 Host 会在加载插件后的 1.5 秒内自动拉起桌面挂件。

{
  "name": "@local/dsh-fat-fish-widget",
  "version": "0.4.0",
  "description": "大肥鱼桌面挂件:一只常驻 Windows 桌面的悬浮鱼娘,始终置顶显示当前会话的轮次、步骤、工具调用、todo、后台任务与团队任务;可自选开机自启与关闭 DSH 后是否保留。",
  "type": "module",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/danheng383-commits/dsh-widget.git"
  },
  "homepage": "https://github.com/danheng383-commits/dsh-widget#readme",
  "dsh": {
    "bundle": {
      "patch": "./cordis.patch.yml"
    }
  }
}

安装命令示例（需要使用当前 profile 的 plugin_manager）：

# 在本目录执行（target 为本目录绝对路径）
dsh plugin_manager install_bundle ./danheng383-commits-dsh-widget

安装后，挂件由 Host 通过 desktop\launch-widget.vbs（wscript → WScript.Shell.Run）静默启动。这种方式与直接 spawn 不同，它将进程交给外壳管理，从而能在 DSH 关闭后依然留在桌面。

典型用法¶

• 随 DSH 启动：打开 DSH，1.5 秒内桌面挂件会自动出现。
• 拖拽位置：按住鱼拖动到合适位置，自动保存。
• 展开/收起：单击鱼或右键选择。
• 调整大小：右键 → 大小 → 小 / 中 / 大。
• 设置开机自启：右键 → 「开机自启」打勾/取消。打勾会在启动文件夹创建指向 desktop\launch-widget.vbs 的快捷方式，取消则删除。
• 控制挂件是否在 DSH 退出后保留：右键 → 「DSH 退出后保留悬浮窗」打开（默认）/ 关闭。关闭后挂件会在检测到 Host 停止写快照约 30 秒后退出。
• 调试：在 %LOCALAPPDATA%\dsh-fat-fish\ 创建空文件 debug-on，会输出每个会话事件和快照写入日志到 debug.log。删除 debug-on 即停止。

适用场景与注意¶

• 平台：只支持 Windows（WinForms + 分层窗口 API），其它平台不启动挂件。
• 挂件是置顶窗口，会覆盖全屏游戏或全屏视频，需要时可右键退出或临时收起。
• 进度展示的是「最近活跃的会话」：多个会话同时跑时，面板会提示其它会话数，但只详细展示最活跃的那个。
• 挂件不联网，不读取会话日志，只读取本机 state.json。
• 插件以当前 DSH 进程权限运行，安装前建议查看源码与许可证。

短结尾¶

大肥鱼桌面挂件通过透明置顶窗口，把 DSH 的任务进度和审批信息直接搬到桌面上，适合需要持续监控智能体执行状态、及时处理审批的开发者。更多信息见目录页与 GitHub 仓库。