前言¶
在 DSH（DeepSeek Harness）里跑 agent 时，任务往往很长：思考、检索、联网、等确认、出错，状态分散在日志和侧边栏里。若你只想余光扫一眼就知道「现在卡在哪」，网页内的 UI 不一定够直观。下面介绍社区插件 dsh-emotion-ball：一颗 44×44 的独立透明置顶小窗，挂在屏幕角落，表情跟着 agent 的真实工作状态变，而不是定时轮播动画。
这是什么¶
dsh-emotion-ball 由维护者 iwanant 发布，归类为 DSH 客户端 插件（当前 package.json 版本 0.3.1）。它给桌面版 DSH 增加一颗「情绪小球」：不是嵌在 DSH 页面里的挂件，而是单独的 Electron 小窗，始终置顶，透明无边框。
小球的状态来自 DSH 的真实事件（如 session/event、agent/status、工具调用），经插件宿主侧状态机折成「现在在干什么」，再推给桌面窗口显示。
核心功能¶
自动跟任务状态换表情¶
空闲时在待机、好奇、发呆、满意等表情间缓慢轮换；有任务时按事件流转，例如：
31 接收任务 → 30 思考中 → 32 处理中 → 40 检索 / 36 联网
→ 33 完成（2s）→ 34 出错 / 35 等待确认 / 41 停止 / 38 拒绝
任务完成或出错时，右上角会亮紫色 !；有问题等你回答时显示 ?。你在 DSH 里点击、滚动或打字后，角标视为已读并自动消失。
交互与手动选表情¶
| 操作 | 结果 |
|---|---|
| 单击小球 | 展开表情选择盘（16 个常用，可切 32 个全量） |
| 悬停格子 | 实时预览；点一下固定该表情（手动模式） |
| 拖动 | 移动位置并记住；贴边时面板自动翻转，避免被屏幕裁切 |
| 双击 | 窗口可见时最小化；被挡住、已最小化或在托盘时拉到最前或还原 |
| 右键 | 眼神跟随开关、主题（跟随系统 / 深色 / 浅色）、低延迟模式 |
主题与 DSH 双向同步¶
在小球菜单里切换主题会写入 DSH 用户设置，重启后仍生效；在 DSH 其它位置改主题，小球也会跟着变。
架构概要（便于排查）¶
插件宿主（index.js）维护状态机、在 127.0.0.1:8766 提供 /state、/manual、/theme 等接口，并 spawn/kill Electron helper。Helper 加载 ball.html，约 400ms 轮询 /state（角标亮着时 120ms）。更细的设计与取舍见仓库内 PLAN-desktop-ball.md。
安装与启用¶
前置条件¶
| 需要 | 说明 |
|---|---|
| Windows 10/11 | 目前仅支持 Windows（双击最小化 / 前台判断走 Win32） |
| DSH 桌面版 | 插件系统可用 |
不需要预装 dsh-pet 或其它 Electron。首次启用时插件会自行下载 Electron 运行时（约 138 MB，国内镜像优先，失败切官方），存放在：
%USERPROFILE%\.dsh\emotion-ball-runtime\
下载进度显示在 DSH 窗口右下角，失败可点重试。若已有 Electron，可设环境变量 DSH_EMOTION_BALL_ELECTRON 指向 electron.exe，插件将不再下载。
步骤¶
- 将本仓库放到任意目录，例如
D:\plugins\dsh-emotion-ball（可从 GitHub 获取源码）。 - 打开 DSH → 侧边栏「插件」→ 安装/添加插件 → 选择上述目录。
- 启用后，约 1 秒内屏幕右下角出现小球。
插件以当前 DSH 进程权限运行；安装前请自行查看源码与许可证，确认可接受后再启用。
典型用法¶
启用后无需额外配置即可跟状态。需要固定表情时：单击小球 → 在选择盘里预览并点击某一格进入手动模式。需要少占内存、追求双击响应时：右键开启「低延迟模式」（会常驻一个 PowerShell，内存约增至 195 MB 量级，默认按需启动约 125 MB）。排查窗口行为时，可为 helper 加 --dev=1 或设 DSH_EMOTION_BALL_DEV=1，日志写在 %APPDATA%\dsh-emotion-ball-helper\input.log。
README 提到插件仍保留 set_emotion 工具定义，每次请求约增加 228 输入 token；若不用可删掉该工具定义。
适用场景与注意¶
适合：在 Windows 上使用 DSH 桌面版、希望用桌面角标快速感知 agent 阶段（思考、检索、联网、出错、待确认）的开发者。
限制（来自官方 README）：
- 仅 Windows；Linux / macOS 上桌面窗口无法按同样方式启动。
- 首次需下载约 138 MB 运行时（解压后约 350 MB），归插件私有目录所有。
- 多显示器 / 高 DPI 下位置记忆可能偏移几像素。
- 球形象来自第三方 Emotion Ball 项目，视觉设计遵循 Emotion Ball Community License：仅限个人学习研究，禁止商用；插件自有代码为 MIT（见仓库
LICENSE与THIRD-PARTY.md）。
DSH 社区插件目录托管在独立站点，与 DeepSeek / 幻方无官方从属关系；本文事实以仓库 README 与 package.json 为准。
结尾¶
dsh-emotion-ball 把 agent 工作状态从日志里抽出来，变成屏幕角落里一颗会换表情的 44×44 置顶球：事件驱动、可手动选表情、主题与 DSH 同步。若你要试用或看更新，可访问 SkillHub 目录页 与 GitHub 仓库。
