前言¶
DeepSeek Harness（DSH）的主窗口适合长时间编排任务；若你经常只是「问一句、看回复、继续写代码」，每次都要找窗口、还原、再最小化，成本不低。社区插件 dsh-desktop-ball（展示名：桌面悬浮球 / Desktop Floating Ball）在 Windows 桌面上放一颗可自定义的小球，单击即在独立窗口里打开完整 DSH 对话，主窗口可以留在后台。下面介绍它做什么、怎么装、日常怎么用，以及和主界面、浏览器窗口的差异。
这是什么¶
dsh-desktop-ball 是 DSH 的客户端类插件，维护者为 han8421，许可证 MIT，当前包版本 0.18.0（以仓库 package.json 为准）。它在 Windows 10/11 上提供系统级置顶悬浮球；聊天层用 WebView2 内嵌 DSH Web 客户端，没有地址栏和浏览器 chrome。
和常见做法相比，有三点取舍（资料原文表述）：
- 小球是独立原生窗口，不是主窗口最小化后的替身；DSH 最小化后小球仍在。
- 聊天窗不是普通浏览器标签，而是无 Edge 图标、无翻译条的
--app式体验（优先 WebView2）。 - 不修改 DSH 的
app.asar、不注入 Electron 主进程，升级 DSH 后插件可单独保留。
核心功能¶
以下能力均来自项目 README 与 package.json 描述，可按需选用。
交互
- 单击悬浮球：打开或置顶桌面聊天窗口。
- 双击：仅隐藏窗口，WebView 与当前对话保留，再点一次恢复，不会重新初始化。
- 拖动小球：位置会记忆；距屏幕边缘 26px 内松手会吸附，留 4px 缝隙。
- 拖动窗口边或角：缩放聊天窗（最小 360×480），尺寸自动记忆。
对话能力
- 输入区与主界面一致：模型、权限、推理等级、关闭思考，图片/附件上传与拖拽，流式回复与停止（细节见仓库
docs/composer.md）。 ask_user_question与approval/request可在小窗内处理；主窗口与快捷窗口谁先响应谁生效。- 快捷窗口使用独立 DSH 会话，侧边栏可见，可在完整界面继续；新建会话归入名为
ChatWindow的工作区。
外观
- 图标支持图片、GIF、视频或纯色；可裁剪形状与大小。
- 聊天背景区域、消息颜色、助手名称可在 右键悬浮球 或 DSH 设置 →「悬浮球与外观」 中调整。
其他
- 鼠标移到球上会预热加载，点击时通常已就绪。
- 界面语言可跟随 DSH、中文或 English。
- 缺少 WebView2 Runtime 时自动退回 Edge / Chrome
--app窗口；macOS / Linux / 浏览器无原生小球，用应用内面板与Alt + Q（Harness 窗口内快捷键，非系统全局热键）。
安装与启用¶
环境要求：Windows 10/11 + DSH Desktop，dsh >= 0.2.1-rc.2 < 0.3.0；原生小球依赖 PowerShell 5.1 与 WPF。
方式 A：插件页本地路径（README 推荐）¶
- 打开 DSH Desktop，侧边栏进入 Plugins / 插件。
- 选择从本地路径安装，填入插件目录的绝对路径。
- 启用
dsh-desktop-ball组合包，按提示重启。 - 重启后桌面右下角出现悬浮球；DSH 侧边栏不再添加旧的「快捷对话」入口。
方式 B：CLI（在插件包目录下执行）¶
命令会把当前目录以 link: 写入 desktop profile，并把 dsh-desktop-ball 追加到 dsh.profile.bundles：
dsh plugin --profile desktop add .
只检查配置、不启动应用：
dsh --profile desktop --dump-config
输出中应出现 id: quick-chat 与 name: dsh-desktop-ball（内部标识仍沿用 dsh-quick-chat，用于数据目录与认证 fragment，见仓库架构文档）。
方式 C：手动改 profile（进阶）¶
插件页不可用时，需完全退出 DSH Desktop，用 DSH 自带 pnpm 链接目录并在 %USERPROFILE%\.dsh\profiles\desktop\package.json 的 dsh.profile.bundles 末尾加入 "dsh-desktop-ball"。改前请备份 package.json；完整 PowerShell 示例见 GitHub README 安装节。
典型用法¶
| 操作 | 效果 |
|---|---|
| 点悬浮球 | 打开 / 置顶桌面聊天窗口 |
| 双击悬浮球 | 隐藏聊天窗口（保留 WebView 与对话） |
窗口顶栏 — / 图钉 / 新建 / ⋯ / ✕ |
最小化到球 / 切换置顶 / 新对话 / 更多 / 关闭 |
Alt + Q |
在主界面展开或收起应用内面板（非 Windows 原生球场景同样适用） |
Enter / Shift + Enter |
发送 / 换行 |
Esc |
先关菜单，再收起应用内面板 |
桌面入口只有悬浮球；应用内快捷入口为 Alt + Q。快捷窗口本地 localStorage 最多保留 12 条历史，完整长会话请在 DSH 完整界面查看。
原理简述¶
DSH 渲染层插件不能直接创建 Electron BrowserWindow，因此插件分两块：index.js 生成带短期认证 token 的 URL 并启动 native/ball.ps1（WPF 透明置顶球，监听 Host PID）；同一 PowerShell 进程内用 WebView2 打开认证 URL，交换 token 后进入聊天面板。状态与 token 写在 %LOCALAPPDATA%\dsh-quick-chat\，卸载插件时会删除；聊天窗使用独立 profile。
适用场景与注意¶
适合：在 Windows 上长期开着 DSH，又希望用最少窗口切换完成短问答、审批或小范围改动的开发者。
注意：
- 插件随当前 DSH 进程权限运行；安装前请阅读 源码 与 MIT 许可证，自行判断是否满足安全与合规要求。
- 预热与隐藏窗口会保留 WebView2 进程（资料称通常约 100–200 MB），10 分钟无操作后自动回收。
- 原生悬浮球仅
win32（见package.json的os字段）；其他平台走应用内面板。 - 社区目录 SkillHub 插件页 与 GitHub 由社区维护，与 DeepSeek / 幻方无官方从属关系；星标等元数据以各站点当时展示为准（目录线索为 2 stars）。
自定义 GIF/图片后若拖不动小球，README 排查表指出需保证 WPF Ball 网格 Background="Transparent"；更多现象见仓库 docs/troubleshooting.md。
