🐋 Deepseek Harness Launcher（鲸鱼悬浮窗）

一个 Windows 桌面悬浮窗，实时反映 DeepSeek Harness 的工作状态，同时作为进入 Harness 的快捷入口。

✨ 功能特性

• 实时状态动画：Harness 内有任务在跑时显示 working 动图，空闲时显示 idle 动图（默认每 1.5 秒检测一次，可调）
• 实时活动状态：气泡框实时显示当前工作状态——正在思考… / 正在调用 pwsh / 正在编辑文件 / 正在联网搜索 / 等待审批：xx 等
• 一键进入：双击悬浮窗直接用默认浏览器打开 Harness
• 状态气泡：单击查看 Harness 运行状态（在线/离线、任务执行中/空闲、当前活动）
• 自由拖动：按住拖动到桌面任意位置
• 更换动图：气泡框内一键更换 working / idle 动图（仅支持 GIF 格式，自动校验文件有效性）
• 残留自动清理：自动清除工作动图右下角抠图残留（绿幕 / 灰黑块），且只作用于原始动图，不影响用户替换后的动图
• 开机自启：登录时自动在后台启动 Harness（npx -y @deepseek-ai/dsh web）并拉起悬浮窗，无需手动开 cmd

📋 系统要求

• Windows 10 / 11（桌面交互会话）
• PowerShell 5.1（Windows 自带）或更高
• 可选的 npx（Node.js）——用于开机自启时自动拉起 Harness；若你手动运行 Harness 也可

📁 目录结构

Whaleplugin/
├── README.md              # 本文档
├── LICENSE                # MIT 开源许可
├── install.ps1            # 一键注册开机自启（管理员运行可注册"登录时"任务，顺位最早）
├── uninstall.ps1          # 一键移除开机自启
└── src/                   # 运行时源码（整目录复制到任意位置即可运行）
    ├── launcher.vbs       # 隐藏启动器（无控制台窗口）
    ├── start-whale.ps1    # 启动器：静默启动 Harness → 等待端口就绪 → 拉起悬浮窗
    ├── whale-window.ps1   # 悬浮窗本体（WPF，含全部交互与状态监控）
    ├── working.gif        # "有任务运行"动图（可通过气泡框更换）
    └── idle.gif           # "空闲"动图（可通过气泡框更换）

src/ 目录是可移动的：所有脚本通过自身路径定位资源，复制到任意文件夹即可运行。

🚀 安装

方式一：立即使用（不需要管理员）

1. 双击 src\launcher.vbs（无窗口，静默后台启动 Harness + 悬浮窗）

方式二：注册开机自启

# 在 Whaleplugin 目录下
powershell -ExecutionPolicy Bypass -File .\install.ps1

• 普通权限：注册 HKCU 开机自启（登录后自动启动）
• 管理员权限（推荐）：额外注册任务计划「登录时」任务，启动顺位排在绝大多数自启软件之前

方式三：手动命令行

powershell -NoProfile -ExecutionPolicy Bypass -File .\src\start-whale.ps1

🖱️ 使用说明

🧩 工作原理

• 状态检测：每 1.5s 轮询 Harness API POST /api/session.list，任一会话 running=true → 显示 working 动图，否则 idle 动图
• 活动状态：后台线程每 2s 轮询 session.history，从最近事件推断当前活动（tool/call → 工具名；assistant/chunk 的 reasoning-delta → 思考；approval/asked → 等待审批）
• 动图播放：System.Drawing 逐帧解码 GIF（保留原始帧延迟），DispatcherTimer 轮播
• 残留清理：对原始 working.gif 按帧做连通性分析 + 非蓝像素清除（右下角区域），误伤主体概率极低
• 进程生命周期：悬浮窗由启动器托管；停止 Harness 通过记录的主进程 PID + 端口反查执行 taskkill /T 结束整棵进程树

⚙️ 配置

所有可调参数都在 src\whale-window.ps1 顶部附近：

🗑️ 卸载

# 1. 移除开机自启
powershell -ExecutionPolicy Bypass -File .\uninstall.ps1

# 2. 右键悬浮窗 →「退出」关闭悬浮窗

# 3. 删除整个 Whaleplugin 文件夹

❓ 常见问题

Q：悬浮窗没出现？ A：确认 Harness 已在运行（http://127.0.0.1:3080 可访问）。start-whale.ps1 会等待端口最多 120s。也可查看 src\launcher.log 排查。 大部分情况下都是系统开机自启任务过多导致需要排队。

Q：更换动图后重启又变回原图？ A：更换的动图会复制到 src\ 覆盖原文件并持久生效；若直接改动了 src\working.gif，重启后仍会使用新文件。

Q：为什么 working 动图被自动"清理"过？ A：原始工作动图右下角有抠图残留（绿幕/灰黑块），脚本按原图哈希识别并在加载时自动清除；你替换的新动图不会被清理。

Q：双击灵敏度/拖动手感怎么调？ A：见上表「配置」，修改 src\whale-window.ps1 后重启悬浮窗即可。

📄 开源许可

MIT License

🙏 致谢

• 基于 DeepSeek Harness 的公开 Web API 构建