前言¶
DeepSeek Harness（DSH）在本地跑起来之后，一个工作区里往往开着多条会话。你切到编辑器或别的窗口时，很难立刻判断：哪条会话停在「等你回答」，哪条还在跑，哪条已经闲下来。去网页里逐个翻状态，既打断思路，又容易漏掉待批准的权限请求。
下面介绍社区插件 doncc/dsh-beacon：在 Linux 系统托盘放一个常驻小圆点，把本机全部 DSH 会话聚合成一种颜色；需要处理时，用中键或菜单跳回最早那条在等你的对话。它只读 DSH 本地状态文件，不向 DSH 进程注入代码。维护者为 doncc，归类为客户端插件，许可证 MIT（见 GitHub 仓库）。
这是什么¶
dsh-beacon 由两部分可选组成：
- 托盘程序：
tray.py在顶栏/托盘显示三色状态灯，并提供跳转、刷新、停止 DSH 等操作。 - DSH 插件（可选）：在 DSH 设置里提供「状态灯」开关，并让前端通过焦点文件完成会话切换。
定位可以概括成一句话：顶栏一个点，告诉你 DSH 有没有在等你。
三种颜色分别表示什么¶
状态优先级为 黄 > 灰 > 绿。
| 颜色 | 状态 | 含义 |
|---|---|---|
| 绿 | 全部完成 | 没有会话在跑，也没有等你确认的事 |
| 黄 | 等你确认 | 至少有一条待回答的提问，或待批准的权限请求；图标会闪烁 |
| 灰 | 正在执行 | 有会话在跑，但没有卡在等你 |
核心功能与交互¶
聚合状态：约每 1.5 秒轮询一次本机 DSH 数据，单次聚合约 26 ms。读取 ~/.dsh/storages/session_projcache/sessions/*.json 判断是否在跑、是否有 userQuestions；对需要细查的会话再解压 session.v4.jsonl.zstd，用审批与提问的配对差集补齐「待批准 / 待回答」。
交互（GNOME 等遵循 AppIndicator 的桌面）：
| 操作 | 效果 |
|---|---|
| 中键单击 | 跳到「最早待确认」的那条会话 |
| 左键 / 右键 | 菜单：状态摘要、待确认列表（可点跳转）、打开 DSH 网页、刷新状态、停止 DSH、仅关闭状态灯 |
左键在 GNOME 上会打开菜单而非直达，这是托盘协议限制；中键走 SecondaryActivate，是一键直达的手势。
装好 DSH 插件后，还会在设置页出现「状态灯」分区，可勾选隐藏托盘图标；托盘写入 beacon-focus.json，前端轮询后切换到对应会话。
安装与启用¶
安装分两条路径，按是否需要托盘图标选择。
只装 DSH 侧（无托盘图标）¶
插件市场收录后，仅需 DSH 设置与跳转逻辑、不要系统托盘时，使用：
dsh plugin --profile web add github:doncc/dsh-beacon
装完后设置页会有「状态灯」相关分区，但系统托盘里不会出现圆点。
要托盘状态灯¶
先做依赖，再跑仓库里的 install.sh。第 4 节的 --with-plugin 会在装托盘时顺带注册 DSH 插件；若已用上面的 dsh plugin add 装过插件，后续 --with-plugin 可跳过。
1. 依赖（Debian / Ubuntu）¶
sudo apt install python3-gi gir1.2-ayatanaappindicator3-0.1 zstd x11-utils
python3-gi与ayatana AppIndicator：GTK3 托盘图标。zstd：解压会话日志以配对审批与提问。x11-utils（xwininfo）：查找已打开的 DSH 浏览器窗口并置前。
GNOME 通常需要 AppIndicator 扩展；KDE、XFCE 等支持 StatusNotifierItem 的桌面也可显示。
2. 安装托盘本体¶
仓库 README 给出的步骤为克隆仓库并执行安装脚本（示例将 DSH 装在 ~/opt/DSH）：
git clone https://github.com/doncc/dsh-beacon.git
cd dsh-beacon
./install.sh --dsh-root ~/opt/DSH
- 默认安装到
~/.local/share/dsh-beacon，可用--prefix修改。 --dsh-root指向 DSH 本体安装目录：状态灯从这里读dsh.log（带 token 的地址）并调用stop-dsh.sh，不修改该目录内容。
先启动 DSH，再手动试跑托盘：
DSH_ROOT=~/opt/DSH ~/.local/share/dsh-beacon/tray.py
3. 随 DSH 一起启动（可选）¶
在 DSH 启动脚本中，端口起来且存在图形会话时拉起托盘；在停止脚本中按 tray.pid 结束进程。也可使用用户级 systemd 单元 dsh-beacon.service（见仓库 README）。托盘发现 DSH 端口（默认 3080）未监听时会自行退出，启动顺序不必严丝合缝。
4. 安装 DSH 插件（可选）¶
若未用 dsh plugin add 装过，可在仓库目录执行：
./install.sh --with-plugin # 默认 web profile
./install.sh --with-plugin --profile tui
脚本会把插件放到 ~/.dsh/plugins/dsh-beacon 并注册到对应 profile。完成后重启 DSH。
典型用法¶
- 日常开着 DSH 与托盘，切到其他应用时看顶栏颜色：绿表示可以放心忽略，黄表示至少有一条需要你确认或回答。
- 出现黄灯且闪烁时，中键单击托盘图标，跳回最早待处理会话；或打开菜单从列表里选具体会话。
- 不需要托盘但仍要设置页开关时，只执行
dsh plugin --profile web add github:doncc/dsh-beacon即可。
环境变量（可按本机路径覆盖）：
| 环境变量 | 默认值 | 作用 |
|---|---|---|
DSH_ROOT |
~/opt/DSH |
读 dsh.log、调用 stop-dsh.sh |
DSH_BEACON_HOME |
脚本所在目录 | 图标与 tray.pid |
DSH_HOME |
~/.dsh |
DSH 配置与状态目录 |
DSH_PORT |
3080 |
DSH Web 端口 |
相关文件：~/.dsh/beacon-settings.json（启用开关）、~/.dsh/beacon-focus.json（跳转目标，前端消费后删除）。
适用场景与注意¶
适合谁：在 Linux 桌面上长期跑 DSH、多会话并行、又经常切走主窗口的开发者。需要「不用回网页扫一圈就知道有没有卡点」时使用托盘；仅需设置里开关与前端跳转时，可以只装 DSH 插件。
权限与安全：托盘与插件在本机用户权限下读取 ~/.dsh 与 DSH 安装目录中的日志/脚本，安装前建议阅读 源码与 LICENSE。
已知限制（摘自上游文档）：
- 窗口置前依赖 X11；Wayland 下置前可能失败，焦点文件仍可用，切回浏览器后页面会跳转。
- 顶栏图标须用 PNG，且换状态须换文件名（GNOME 缓存限制）。
- 不能靠带 token 的 URL 深链跳会话，故采用焦点文件 + 前端轮询。
- 轮询间隔与闪烁节奏目前写死（1.5 s 轮询、350 ms 半周期）。
卸载可在克隆目录执行 ./uninstall.sh。
结尾¶
dsh-beacon 把「全机会话是否在等你」收成托盘上的一个点：黄灯闪就表示该回去了。DSH 生态主张「一切皆插件」；插件目录由社区站点维护，与 DeepSeek / 幻方无官方从属关系。
