dsh-topbar

dsh plugin --profile web add dsh-topbar

dsh-topbar

<div align="center">

<b style="font-size: 1.15em;">把 DSH 每个会话的运行状态，搬到 GNOME 顶栏上</b><br /><br />

<a href="https://www.npmjs.com/package/dsh-topbar"><img alt="npm version" src="https://img.shields.io/npm/v/dsh-topbar" /></a>

<a href="https://gitee.com/We1YI/dsh-topbar"><img alt="gitee" src="https://img.shields.io/badge/gitee-We1YI%2Fdsh--topbar-4d6bfe" /></a>

<a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg" /></a>

<img alt="GNOME 3.36-48" src="https://img.shields.io/badge/GNOME-3.36%20%7C%2044%20%7C%2048-4d6bfe" /><br /><br />

<a href="https://www.npmjs.com/package/@deepseek-ai/dsh?activeTab=versions"><img alt="支持的 DSH 版本：0.1.1-rc.1+，含 0.2.0-rc.2" src="https://img.shields.io/badge/DSH-0.2.0--rc.2-4d6bfe" /></a>

<a href="https://gitee.com/We1YI/dsh-topbar/tags"><img alt="最新版本" src="https://img.shields.io/badge/%E6%9C%80%E6%96%B0%E7%89%88%E6%9C%AC-v0.5.3-4d6bfe" /></a><br /><br />

<img alt="灰=运行中" src="https://img.shields.io/badge/---8a8a8a" /> <img alt="绿=已完成未确认" src="https://img.shields.io/badge/---3fa34d" /> <img alt="黄=等待回复或审批" src="https://img.shields.io/badge/---e0a819" /><br /><br />

<img alt="顶栏截图：灰/绿/黄三态色块" src="https://gitee.com/We1YI/dsh-topbar/raw/main/docs/topbar@2x.png" width="520" /><br /><br />

<i>↑ 真实顶栏截图：每个会话一个色块，紧挨时钟区域——灰=运行中，绿=已完成未确认，黄=等待回复/审批</i>

</div>

<div align="center">

✅ <b>GNOME 3.36 \~ 48</b>：安装扩展时自动探测 <code>gnome-shell --version</code> 并选对应变体 · 详见 <a href="#️-平台支持">平台支持</a>

</div>

📑 目录

• [✨ 功能一览](#-功能一览)
• [🚀 安装](#-安装)
• [🎨 状态与颜色](#-状态与颜色)
• [⚙️ 配置](#️-配置)
• [🧩 子智能体与分叉对话](#-子智能体与分叉对话)
• [🆕 最近更新](#-最近更新)
• [🛠️ 工作原理](#️-工作原理)
• [🐛 排障](#-排障)
• [🖥️ 平台支持](#️-平台支持) · [⚠️ 已知限制](#️-已知限制) · [🔐 安全](#-安全)
• [🧑‍💻 开发](#-开发) · [📄 许可证](#-许可证)

✨ 功能一览

• 🟦 三态色块：灰=运行中、绿=已完成未确认、黄=等待回复/审批，一眼看清哪些在跑、哪些跑完了、哪些卡在等你
• 🟨 审批与提问即变黄：审批、ask_user_question、计划评审三种「需要你」的情况统一标黄，且提醒活到你看见为止——回答后仍按可配置的 dwell 保持，不会几秒就消失
• 🟩 分叉对话照常显示：DSH 的「分叉对话」与「子智能体」在 header 里都写 parentSession，本插件按 origin 正确区分（见 [子智能体与分叉对话](#-子智能体与分叉对话)）
• 👥 子智能体活动上卷：子智能体自己不出块（不刷屏），但它运行时会让所属会话保持灰色——父 turn 结束后依然看得见
• 🪟 多页面并集：同时开多个 DSH 标签页/浏览器时按「等待 > 运行 > 完成」取并集，不再互相覆盖导致闪烁或黄标丢失
• ⚙️ 配置界面在插件自己的页面：侧边栏 插件 → 已安装 → dsh-topbar → 查看，在插件详情页上直接调字号、宽度、色块上限、极简模式、显示哪些状态、点击行为、提醒时长；改完 1 秒内生效
• 🖱️ 点击色块直达：可配置为打开 DSH 网页、跳转到对应会话（?open=<id> 深链），浏览器可选
• 🔧 自装自愈：DSH 启动时把 GNOME 扩展幂等同步到 ~/.local/share/gnome-shell/extensions/（无需 sudo），X11 下文件变化自动重载 Shell
• 🩺 自带诊断：会话内 topbar_status 工具可查上报状态、推送计数、当前配置与扩展自装结果

🚀 安装

前置：已装好 DSH（dsh web 能跑）、Node.js ≥ 20、Ubuntu 20.04 / GNOME 3.36、系统中存在 /usr/bin/gdbus。

支持的 DSH 版本：

<a href="https://www.npmjs.com/package/@deepseek-ai/dsh?activeTab=versions"><img alt="支持的 DSH 版本：0.1.1-rc.1+，含 0.2.0-rc.2" src="https://img.shields.io/badge/DSH-0.2.0--rc.2-4d6bfe" /></a>

engines.dsh 声明 >= 0.1.1-rc.1。逐版核对过、所依赖契约一致的版本：

DSH 版本 · 状态

0.1.1-rc.1 / 0.1.1-rc.2 · compatible

0.1.2-alpha.2 / 0.1.2-alpha.5 · compatible

0.1.5-rc.1 / 0.1.5-rc.2 · compatible

0.2.0-rc.2 · compatible（本机实测版本）

📌 本插件只用到三处 DSH 契约：会话列表投影（running / origin / parentId）、客户端 UI 状态服务 uiSession.sessionStatus（完成提醒走它的 completionUnread）、以及 host 侧两条 waterfall（approval/request、user-questions/request，只用于黄色）。

⚠️ 从 0.2.0-rc.2 起有两个破坏性变更，v0.4.8 已相应迁移：SessionSummary.completed 被删除（绿灯改读 sessionStatus.completionUnread）；插件配置页的 slot 与设置命名空间被重构（见 [配置](#️-配置)）。其余真正挑版本的是 GNOME 侧（见 [平台支持](#️-平台支持)），不是 DSH。

方式一：npm（推荐）

dsh plugin --profile web add dsh-topbar

装完硬刷新浏览器（Ctrl+F5）。GNOME 扩展半部由插件自动安装并在运行中的 Shell 里直接启用——不需要重载 Shell，也不需要注销；只有 Shell 连续拒绝两条启用 API 时才会退回重载兜底（仅 X11，桌面短暂闪烁，窗口保持）。

方式二：离线 tar.gz（无 npm 网络时）

mkdir dsh-topbar && tar xzf dsh-topbar-<版本>-bundle.tar.gz -C dsh-topbar && cd dsh-topbar
PROFILE_DIR=~/.dsh/profiles/<名字> ./install.sh register
# 重启 DSH，硬刷新浏览器

register 幂等：把包复制到 <profile>/dsh-topbar/、改 package.json（依赖 + dsh.profile.bundles）与 cordis.patch.yml、安装 GNOME 扩展。升级重复执行即可。

方式三：让 DSH 自己装

把下面这段发给任意一个 DSH 会话：

帮我安装 dsh-topbar 插件（DSH 顶栏会话指示器）：
1. 执行 dsh plugin --profile web add dsh-topbar
2. 装完提醒我硬刷新浏览器（Ctrl+F5）
3. 如果顶栏没出现色块，帮我查 topbar_status 工具的输出
本插件支持 GNOME 3.36\~48，扩展会按 gnome-shell --version 自动选变体；装完如果顶栏没动静，帮我看看 topbar_status 里的 extInstall。

🎨 状态与颜色

颜色 · 含义 · 判定依据

灰 #8a8a8a · 运行中 · sessionStatus.running ?? SessionSummary.running

绿 #3fa34d · 已完成、未点开确认 · sessionStatus.completionUnread === true

黄 #e0a819 · 等待你回复 / 审批 · host 侧 approval/request + user-questions/request

红 · 出错 · 未实现（见 [已知限制](#️-已知限制)）

<p align="center">

<img alt="三态色块真实截图" src="https://gitee.com/We1YI/dsh-topbar/raw/main/docs/topbar@2x.png" width="520" /><br />

<i>左起：灰=运行中 ×2 · 绿=已完成未确认 · 黄=等待回复（示例快照，用 <a href="#手动排查命令">排障命令</a> 推入后截取）</i>

</p>

绿 ≠ 空闲。 绿块是侧栏那个「跑完但你没点开看」的绿点：点开会话、或它再次开始运行，绿块自动消失——插件不自己维护「已读」。

黄块活到你看见为止。 审批 / 提问的 waterfall 在你回答的瞬间就 resolve 了（通常几秒）。如果那时就清黄，任何起身离开过的人回来都看不到，提醒就失去意义。所以黄色不在 settle 时清除，而是按 dwell 计时（见 [配置](#️-配置)）。

时机 · 行为

审批 / 提问 / 计划评审弹出 · 变黄 ✅

你点允许/拒绝或回答 · 仍保持黄色，dwell 从点击时刻重新计时

dwell = 0 · 回答后立即跟随真实状态

dwell = -1（常驻） · 一直黄到该会话真正结束或从列表消失

一直不回答 · 一直黄（agent 被你阻塞着，就该黄着）

会话从列表消失 · 立即清除

⚙️ 配置

侧边栏 → 插件 → 已安装 → dsh-topbar → 查看，配置表单就渲染在这个插件详情页上（描述下方、「包含的组件」上方）。

📌 不在「设置」里。 DSH 0.2.0-rc.2 把「设置 → 插件」改成了只读清单，插件配置迁到了侧边栏的 Plugins 页。本插件 v0.4.8 起注册到 plugins.bundle.config，表单由宿主渲染（configForms 服务），只有点「保存」才写入。

⚠️ 升级注意：设置命名空间已从 dsh-topbar 改为 profile 条目 id topbar，旧版写在 settings.yaml 里的 dsh-topbar: 一节不会自动迁移，需在新表单里按需重设一次（各字段默认值与原先一致）。

配置随每次推送一同发往 GNOME 扩展，改动 1 秒内生效，不需要重启 DSH 或重载 Shell。保存后的值落在这个 profile 的 cordis.patch.yml 中本插件条目（- id: topbar）的 config: 下。

配置 · 范围 · 默认 · 说明

字体大小 · 9\~14 px · 11 · 标题文字字号（截断测量同步使用）

标题最大宽度 · 60\~400 px · 140 · 超出显示 …

最大色块数 · 1\~12 · 8 · 超出时优先保留

…(truncated)