状态浮窗 a903067276-rgb/dsh-hud

dsh-hud 📊

Awesome DSH Plugin

DeepSeek Harness（dsh）web 的 HUD 状态面板插件：输入框工具行一键按钮，可拖动浮层面板展示 Git 状态、MCP 服务器、技能列表、官方用量信息与余额。

非官方项目：社区成员独立开发维护，非 DeepSeek 官方产品。

截图

dsh-hud 输入框仪表盘按钮

dsh-hud 收进官方右侧栏（标签页形态）

dsh-hud 浮窗形态

默认形态：收进官方右侧栏作为标签页（DSH 0.1.5+，用输入框左侧的 HUD 按钮开合，再点一次收起右栏）；也可切回浮窗（旧宿主自动回落），浮窗可拖拽位置与宽度。
面板内容：Git 状态、提交历史、关注仓库、MCP 服务器、技能列表，以及官方用量信息（token 输入/输出、缓存命中率、分模型统计、上下文占用）。

功能

- Git —— 分支、ahead/behind、未暂存 / 已暂存 / 未跟踪文件（分组可折叠）、每文件 +N/-N 摘要、点击文件展开 diff 全文、最近 10 条提交（条数由 commitCount 配，1~50； 提交记录默认收起，点开才展开）
- 设置页可改（v1.8.0） —— 上面这些都能在「设置 → 插件 → dsh-hud」卡片里改：提交记录条数、余额三档（关 / 官方 / 自定义）、余额预设与自定义字段（地址 / 请求头 / 凭据变量 / 字段路径 / 换算 / 相减 / 额外头）。保存走 profile 条目 config（volatile → 即时生效、不用重启）。
- 按改动自动折叠（2026-09-26 用户定） —— 干净的仓库/子仓库收成一行（带 ✓ 与 ↑↓ 未推送数），有改动的自动展开到文件层；手动点过之后以你的选择为准，并记住（localStorage，重开面板/刷新都算数）
- 整组折叠（2026-10-01 用户定） —— 同一"工作区 / 关注仓库"下的子仓库算一组：全干净就只留父仓库一行（右侧 ✓ N 仓），子文件夹名字一个都不列；有改动时只列有改动的子仓库，其余收成一行「▸ 另外 N 个干净仓库」。点父行 = 整组开关（展开 / 收回一行）
- 刷新按需升级（2026-10-01） —— 文件变化走"轻量指纹"（一次 shell 拿回各仓库的改动数 / 分支 / 领先落后 / HEAD）：指纹没变就不拉全量；有脏仓库时最多每 5 秒补一次全量（保证 +/- 明细新鲜）。效果：干净工作区下每次变化只花 1 次 shell（此前是每仓库 1 次）
- MCP —— 已挂载的 MCP 服务器（从 mcp__<服务器>__<工具> 工具名推导）
- Skills —— 当前 agent 可用的技能列表
- 官方信息聚合 —— 当前模型 + reasoning effort、plan 状态、token 用量（输入 / 输出 / 缓存命中率）、会话统计（轮数、步数、LLM 与工具耗时、解码 tok/s、上下文占用 %）
- 余额预设（2026-09-26 调研后加） —— balancePreset 填服务名就自动带好地址/请求头/字段路径/凭据变量：kimi（data.available_balance）、siliconflow（data.totalBalance）、openrouter（total_credits − total_usage）、zai、one-api（自建/中转系，data.quota 需 balanceScale 换算，默认 50 万/元；地址每家不同要自己填）、deepseek（=官方）。自己填的字段优先于预设。
- 余额安全闸 —— 自定义地址必须是 https（本机/内网除外），否则拒绝请求并提示；不跟随 302 重定向（防 Authorization 被带到别的域）；key 只放请求头、绝不拼进 URL；接口回 200 但解析不到余额时会提示一次（one-api 系出错就是 200 + success:false）。
- 余额（三档可选，2026-09-26 新增） —— balanceMode 选：off 不请求也不显示 / official（默认）走 DeepSeek 官方 GET /user/balance / custom 走你自己的接口（配 balanceUrl，可选 balanceHeader（默认 authorization: Bearer <key>）、balanceTokenEnv（默认 DEEPSEEK_API_KEY）、balancePath（如 data.balance、balance_infos[0].total_balance；留空则宽松找常见字段）、balanceCurrency）。key 只会发给你自己配置的那个地址；取不到/失败一律显示 --，不会瞎猜一个数
- 分模型用量 —— 本会话按模型的 token 明细（请求数/输入/缓存/输出），切换 flash/pro 后两个模型的用量都保留显示

按钮还带未提交文件数角标，不打开面板也能一眼看出项目有没有待提交改动。

安装

本仓库是官方 bundle 插件格式（根 package.json 的 dsh.bundle + dsh.client），经官方 profile 管理一行安装：

DSH 0.1.7 及以后：
dsh plugin --profile web add "github:a903067276-rgb/dsh-hud#main"
DSH 0.1.5 及更早（本版需要 0.1.7+）：
dsh plugin --profile web add "github:a903067276-rgb/dsh-hud#v1.4.1"

装完重启 dsh web（bundle 层在启动时合成，热更新无效）。需要 pnpm （dsh plugin 是 pnpm 转发器）。

手动挂载兜底：见 docs/install.md。

用法

点输入框工具行的仪表盘图标按钮（官方 dsw 风格，跟随深浅色主题）。面板默认在左侧展开（默认 240px，避开官方右侧回合导航条），拖标题栏可任意移动位置（localStorage 记忆，重开面板按记忆位置显示）；拖左边缘把手调整宽度（200–480px，localStorage 记忆）。带计数徽标的小节标题可点击折叠/展开。数据每 30 秒自动刷新（面板关闭时只轮询轻量的 git 角标数据）。

平台支持

| 平台 | 状态 |
| macOS | ✅ 开发环境，全功能实测 |
| Linux | ⚠️ 未实测；架构上预期可用，见 docs/install.md |
| Windows | ⚠️ 未实测；架构上预期可用，见 docs/install.md |

环境要求

- DSH web（≥ 0.1.1-rc.1）（npx @deepseek-ai/dsh web 启动）
- 版本对照（分模型用量投影使用 0.1.1+ 契约；0.1.0-rc.7/rc.8 仍是旧契约）：
- ✅ DSH 0.1.7 及以后——装本版（v1.8.1）：它声明了 peerDependencies: {"@deepseek-ai/dsh": "^0.1.7-rc.1 || ^0.2.0-rc.1"}，宿主不匹配会明确拒绝加载并说明原因，不再静默出错。配置迁到 0.1.7 的插件 Config（.volatile() 字段可即时生效），改完不用重启。
- ✅ DSH 0.2.0-rc.1——已验证兼容：peer 范围同时覆盖两条线（^0.1.7-rc.1 || ^0.2.0-rc.1），dsh.compatibility.dshReleases 矩阵新增 "0.2.0-rc.1": "compatible"——已在 0.2.0-rc.1 真机 + 影子实例验证。0.2 起宿主对 profile bundle 做 peer 门禁，范围不覆盖当前运行时会整个跳过加载，靠这个范围插件才会被加载。
- ⚠️ DSH 0.1.5 及更早——请装上一版 tag v1.4.1：那条线保持原行为，不含任何 0.1.7 专用 API。
- ⛔ 旧版本插件（≤ v1.4.1）在 0.1.7 上不受支持——所有 git 命令失败（shell.run 已删除）→ Git 段全空，右栏标签页形态也用不上。插件要跟宿主一起升。
- 维护策略：本插件将持续跟随 DSH 最新版本演进；对旧版 DSH 的兼容仅是尽力而为、不保证长期有效。

| 你的 DSH 版本 | 装这个 | 说明 |
| 0.1.1-rc.1 及以上 | main（v1.2.15+） | 全功能 |
| 0.1.0-rc.7 – 0.1.0-rc.8 | v1.2.11 — dsh plugin add github:a903067276-rgb/dsh-hud#v1.2.11 | 0.1.1 旧投影契约的最后一个版本 |
| 0.1.0-rc.6 及更早 | rc6-compat — dsh plugin add github:a903067276-rgb/dsh-hud#rc6-compat | 冻结，不再维护——建议升级 |

- PATH 里有 git 命令行
- 不需要额外装 shell：DSH 的 shell 服务在所有平台上都以 bash -c 执行（Windows 为 Git Bash），DSH 能跑，本插件就跟着能跑

工作原理

┌─ Host（Node，cordis 插件）────────┐ ┌─ 浏览器（client bundle）───┐ │ lib/index.js │ │ lib/client.js │ │ │ │ │ │ webServer.register(/api/dsh-hud) │──fetch──▶ input.left seat：按钮 │ │ ├ /api/dsh-hud git/mcp/… │ │ shell.overlay seat：面板 │ │ └ /api/dsh-hud/diff 单文件 diff│ │ │ └───────────────────────────────────┘ └────────────────────────────┘

Host 半经 webServer prefix 路由输出 JSON，全部 git 命令合并成一次 bash -c
调用（__HUD_[BHSLN]__ 分隔符分段，切项目刷新快）。Client 半是手写的
window.__ModuleLoader__.load(...) bundle，零构建步骤；按钮与面板通过模块级 store
（useSyncExternalStore）共享状态。维护者请看 docs/architecture.md （含实现细节与踩坑记录）。

注意事项

- bundle 安装与手动挂载二选一，不要同时用。
- 所有数据都在本地从运行中的 dsh 实例读取；唯一的外呼是官方余额接口（用 DEEPSEEK_API_KEY 凭据，key 不出机器）。
- DSH_HUD_NO_WATCH=1 可完全关闭文件监听——HUD 改为纯 30s 轮询 + 手动/聚焦刷新。
适合目录树极其庞大的机器（例如一个父目录下放几十个仓库的布局）——macOS 文件监听在这种规模下不稳定；监听器默认也设了 128 个上限，超出的深层目录变化会在 ~30s 内通过轮询发现。
- DSH_HUD_BALANCE=off 可完全关闭余额请求——不外呼、不打日志，面板余额恒显示 --。
- 余额只支持 DeepSeek 官方 key。接口是官方的 /user/balance、凭据取 DEEPSEEK_API_KEY；若该环境变量里放的是中转/网关 key，请求必然 401，面板显示 --。这类失败现在只提示一次 并退避 30 分钟（旧版本每 60 秒重试一次且每次都打日志）。非官方 API 的余额显示已在计划中（#10）。

开发

lib/index.js host 半 —— 数据路由（git / mcp / skills / model） lib/client.js client 半 —— UI（按钮 + 面板），最终产物，无构建步骤 cordis.patch.yml bundle patch —— 单 entry 包名挂载（官方 bundle 流程） docs/ 安装指南与实现说明 examples/ 手动双 entry 挂载示例（兜底安装路径）

本地测试：软链（或 dsh plugin --profile web link）进 web profile 的 node_modules，加两条挂载 entry，重启 dsh web。

设计路线（简洁优先）

dsh-hud 刻意保持最小：

- 零依赖 —— 无运行时依赖、无构建步骤，client bundle 就是仓库里的最终产物
- 纯只读 —— 只读 git 状态、MCP/Skills 列表和官方投影，不做任何 git 写操作、不改文件
- 一个按钮一个面板 —— 没有设置页、没有配置文件

独立社区项目：非 DeepSeek 官方出品，与任何其他 DSH 插件项目无关联、非衍生、无代码共享。需要重操作（提交/推送 UI、文件树、git 图谱）的话，社区有其他插件覆盖；dsh-hud 刻意只做"扫一眼就懂"的状态面板，可与它们共存。

社区

本插件是 DeepSeek Harness 生态的一部分。更多插件见 dsh-plugin 话题。

许可证

MIT