dsh-awesome-hud

为 DeepSeek Harness Web 聊天页打造的悬浮 HUD 面板：会话状态、上下文占用与一键压缩、git 变更、子代理、任务与 MCP 启停，一目了然。

HUD在dsh中的效果（浅色主题）

HUD在dsh中的效果（深色主题）

[!NOTE] 一个 DSH Web 插件（dsh.bundle.patch 通道安装）。浏览页面右上角新增「HUD面板」按钮，点击开合悬浮面板；面板与 dsh-better-sidebar 右侧栏互斥协作，互不遮挡。

📑 目录

• ✨ 功能列表
• 🚀 快速开始
• 🧭 使用说明
• 🖼️ 界面截图
• ⚙️ 兼容性
• 🔧 技术栈
• ⬆️ 升级说明（v0.11.x → v0.14.1）
• 📄 许可证

✨ 功能列表

互斥协作：打开 better-sidebar 右侧边栏会自动关闭 HUD；手动关闭右侧边栏后 HUD 自动恢复。点击「HUD面板」按钮时若右侧边栏已打开，则先自动关闭侧边栏再打开 HUD（若版本兼容性导致自动关闭失败，HUD 会延迟到右侧边栏关闭后自动打开）。

🚀 快速开始

方式一：从 GitHub 远程安装（推荐）

# 1. 安装（要求本机 git 可访问 GitHub）
dsh plugin --profile web add github:Ycet/dsh-awesome-hud

# 2. 重启 DSH Web 服务并刷新页面

方式二：从本地源码安装（开发）

# 1. 安装（将 <absolute-path-to-plugin> 替换为本地源码目录绝对路径）
dsh plugin --profile web add dsh-awesome-hud@link:<absolute-path-to-plugin>

# 2. 重启 DSH Web 服务并刷新页面

安装完成后，聊天页右上角（「打开工作区」按钮左侧）出现「HUD面板」按钮，点击即可开合。

[!NOTE] HUD 面板默认展开；每个会话各自记住自己的开合状态（按会话 id 存于 localStorage），在 A 会话收起不会影响 B 会话。新建会话页（尚未开始的空白会话）例外：该页每次进入都从收起状态开始（只改内存态、不写 localStorage，因此不影响任何会话的记忆），并在右上角提供独立的悬浮「HUD面板」按钮用于在该页展开。模块可见性保存于 DSH profile 设置中，跨浏览器/设备随 profile 同步。

🧭 使用说明

• HUD 面板：悬浮于聊天页右上角，宽度 300px，高度上限为输入框底部（留 8px 底距），内容超出时面板内部滚动（滚动条仅在滚动时显示，停止 2s 后渐隐）；聊天内容与输入框随面板展开自动向左让位，不会重叠。
• 设置菜单：「会话」模块右上角齿轮打开菜单，可勾选展示「上下文窗口 / 用量 / git / 子代理任务 / 任务 / 计划清单 / MCP」模块（用量仅在其可用时列出），底部「取消 / 确认」按钮丢弃或保存勾选；「会话」模块恒展示。用量可用时，菜单内额外提供「用量模块内容」分组，可分别开关 DeepSeek 余额、OpenCode Go 用量和 Codex 额度。
• 会话模块：会话名称右侧铅笔按钮可重命名会话——点击进入编辑态（输入框 + 取消/确认图标按钮），Enter 提交、Esc 取消，输入为空时确认按钮置灰；确认后保存新名称，会话列表标题自动更新。
• 上下文窗口：进度条颜色随占用率自动切换；底部按「已用 n · 上限 n · 缓存命中 n%」展示，缓存命中率固定保留一位小数（无可用统计时显示 —）；「压缩」在会话空闲时可用，运行中按钮禁用并提示原因。
• 用量模块：位于「上下文窗口」模块下方。DeepSeek/OpenCode Go 复用 dsh-account-usage 插件路由，Codex 复用 dsh-codex-subscription 的浏览器 RPC；面板打开时立即加载、之后每 60 秒轮询；数据均缩进展示并带对应图标；模块支持折叠，默认展开（折叠状态经 localStorage 持久化）。
  • DeepSeek 余额：展示余额合计（充值 + 赠送），「跳转」按钮弹出选择菜单，可跳转 deepseek 开放平台或 opencode go 用量页；点击具体余额数值可直接打开设置面板「账户」分区的 deepseek 标签页；仅当已配置 DEEPSEEK_PLATFORM_TOKEN 时展示该行。
  • OpenCode Go 用量：三行分别展示 oc-go 5h / 1w / 1m 窗口用量百分比，点击具体百分比数值可直接打开设置面板「账户」分区的 opencode go 标签页；仅当已配置 OpenCode Go Key 且订阅有效（/api/account-usage/opencode 返回 ok + keySource）时展示。
  • Codex 额度：展示 codex 5h额度 与 codex 周额度 两条剩余额度整数百分比，使用 ChatGPT 图标；点击百分比数值打开「设置：Codex 订阅」页面。仅当安装并登录 dsh-codex-subscription 时展示；已登录但额度请求暂时失败时保留行并显示 —，无法确认安装/登录状态时隐藏。
  • gpt-reserve 额度：dsh-codex-subscription 返回 gpt-reserve 额度（/wham/usage 的 additional_rate_limits → rateLimits 中 id 为 base_model_inference、limit_name/name 为 gpt-reserve；插件按 id 或 name 归一化匹配，忽略大小写、下划线、连字符与空格）时，在周额度下方追加 codex gpt-reserve额度 行，样式、图标与交互与 5h/周额度完全一致（取其主窗口剩余百分比；额度带名称时显示为「codex gpt-reserve额度（名称）」）。该额度不存在时不展示该行；存在但窗口数据异常时保留行并显示 —。
  • 模块可见性与可配置内容：DeepSeek、OpenCode Go 与 Codex 各自独立；仅已安装/配置/登录的数据源显示对应行，全部不可用时模块与设置项整体隐藏；展示内容可在「用量模块内容」分组中单独开关（host settings 持久化，随 profile 同步）。
• git 模块：每 5 秒随面板打开自动刷新（写操作后立即刷新）；标题栏右侧分支按钮点击弹出下拉列表——可切换已有分支（当前分支高亮带勾标记），或在输入框中输入新分支名点击「添加」创建并自动切换；「git graph」弹窗按每页最多 80 条分页展示当前仓库（全部引用）提交图（滑到列表底部出现「加载更多」按钮点击追加下一页，全部加载完后底部显示「已显示全部提交」提示）；分支标签中，当前分支为蓝底白字，其他分支为灰底黑字；HEAD 指向版本以放大的白色填充圆点 + 蓝色描边标记。提交行右键菜单可复制短哈希（前 7 位）/全哈希（40 位）/提交标题，并提供以下受保护操作：
  • 从此处创建分支：点击后原菜单项位置展开为输入框 + 「取消」/「确认」图标按钮（输入框为空时确认按钮置灰）。输入合法分支名并点击确认后，以该提交为起点执行 git checkout -b <名称> <提交> 并切换到新分支：成功提示后菜单关闭、git 快照与提交图刷新，新分支标签随即显示为蓝底当前分支。分支名重复、或本地修改会阻止切换时给出提示（后者列出受影响文件）并保留输入内容，便于改名重试；不自动 stash、不强制切换。输入框内按 Enter 不触发创建，按 Escape 取消输入并恢复为原菜单项（再按一次关闭菜单）；Git 操作（merge / rebase / cherry-pick / revert）进行中时该项置灰。
  • 合并至当前分支：先在原菜单项位置显示行内「确认？/取消」，确认后执行 git merge --no-edit；已包含提示「无需合并」、本地修改阻塞提示受影响文件、合并冲突自动 git merge --abort 回滚并列出冲突文件清单。
  • reset(soft)-保留暂存：仅可选择当前本地分支历史中、早于 HEAD 的提交；二次确认后以 git reset --soft 回退，所选提交之后的提交内容保留在暂存区。
  • reset(mix)-取消暂存：同样仅可回退至当前本地分支历史中的较早提交；二次确认后以 git reset --mixed 回退，所选提交之后的提交内容保留在工作区且不在暂存区。
  • reset(hard)-撤回更改：二次确认后以 git reset --hard 回退并丢弃所选提交之后的提交内容，以及已跟踪文件的未提交修改；未跟踪文件不会被删除。
  • reset 在未检出本地分支、Git 操作进行中、所选提交不在当前分支历史中或所选提交即为 HEAD 时不可用。变更文件按分组展示（状态字母按类型着色——修改 M 黄色、新增 A 蓝色、删除 D 红色、未跟踪 ? 灰色，重命名 R / 复制 C 蓝色）：
  • 分组：staged（暂存区）与 changes（未暂存区，含未跟踪）两组，组名右侧灰色数字为组内文件数，并提供一键按钮：changes 组「+」暂存全部未暂存文件、staged 组「-」取消暂存全部暂存文件；某组无文件时该组不展示
  • 文件行操作：点击任一文件行弹出选项菜单——staged 组文件提供「remove from stage」（移出暂存区）；changes 组文件提供「add to stage」（暂存该文件）与「revert」（撤销该文件变更；未跟踪新建文件撤销 = 删除该文件，均带二次确认与受影响文件清单）
  • commit：按钮在暂存区无文件时置灰；点击弹出提交弹窗（展示待提交暂存文件数量 + 多行输入框 + AI generate + commit），输入为空时 commit 置灰；Enter 仅换行，需点击 commit 才会提交；提交范围仅为暂存区
  • AI generate：使用当前会话所选模型，结合暂存区全部 diff（超 16KB 截断）与当前会话最近对话上下文（用户直接消息与助手消息，供理解改动意图；若对话中用户明确指定了提交备注则直接采用），按内置本地 git 提交规范生成提交信息并填入输入框——格式 [YYMMDD] 开发项目名称 vX.Y.Z：修改内容（日期取系统当前时间；版本号依规范自动判断：破坏性变更→主版本、向后兼容新功能→次版本、修复/文档→修订号；项目名与当前版本取自工作区向上最近的 package.json）；生成后自动校验版本号是否已按规范递增，不达标时自动重试一次（附上一次输出与原因反馈），仍不达标则照常填入并提示核对
  • revert：按钮在无任何未暂存变更（含未跟踪）时置灰；点击后二次确认弹窗列出全部受影响文件（未跟踪文件带 ? 前缀标识），确认后还原已跟踪文件的未暂存变更并删除未跟踪新建文件（暂存区不受影响）
• 子代理任务模块：按层级缩进展示全部后代子代理；执行中状态徽章为黄色，已完成为绿色；点击条目跳转对应子代理会话页。
• 任务模块：列表展示当前会话待办任务；进行中（in progress）任务行首为旋转动画图标（DeepSeek 官方同款，1s/圈，品牌蓝），已完成/待处理保持勾选与待办图标；模块底部展示「x 已完成 · x 进行中 · x 待处理」三态计数（含 0 恒显），标题栏保留「已完成/总数」计数。
• 计划清单模块：位于「任务」模块下方，展示当前会话通过 plan 模式产出的全部计划清单（新→旧），仅在存在计划记录时展示；每 5 秒随面板打开自动刷新，状态由会话日志自动推导：
  • 待审批（黄色标签）：计划刚产出、用户尚未审批；
  • 已执行（绿色标签）：用户在计划审查中审批通过（exit_plan_mode 成功返回）；
  • 已废弃（灰色标签、文字划线变淡）：用户拒审/要求修改/打断审查，或计划无审批结论但 plan 模式随后退出（如 /plan off）；
  • 行主文字取计划首个 Markdown 标题，无标题时截取正文；点击任一行弹出计划全文弹窗（标题、状态、产出时间与正文，正文按轻量 Markdown 渲染，支持标题/列表/代码块/链接/引用与 GFM 表格）；模块底部展示「x 已执行 · x 待审批 · x 已废弃」三态计数（含 0 恒显）；模块可折叠，默认展开。
• MCP 模块：开关控制 dsh 全局的 MCP 服务启停；切换后页面自动刷新生效；模块默认展开，无任何 MCP 服务时仍展示空状态。
• 便笺模块：按工作区共享的便笺——以会话所在工作区目录为键保存（同一工作区目录下的所有会话共用一份内容，含输入框高度），本地持久化；删除或归档其中任一/全部会话都不影响该工作区其它会话的内容，下次在同一工作区新建会话时内容依旧存在；输入框底部拖拽手柄可拖拽调整高度（实时持久化），5000 字上限与字符计数显示；右侧圆点指示便笺内容存在；可一键添加便笺全文至对话输入框（新建会话页会发送到该工作区最近的会话）；输入框为空时「清空」按钮置灰，有内容时首次点击进入红色确认态，二次点击后清空（点击其他区域、Escape 或 2 秒超时会取消）；模块可折叠/展开（状态持久化）。未归属工作区（无 cwd）的会话降级为会话级隔离，不与其它会话共享。
• 待办模块：按工作区共享的待办清单——以会话所在工作区目录为键保存（同一工作区目录下的所有会话共用同一份清单与顺序，本地持久化）；勾选完成/恢复、添加/删除项、整行拖拽排序（拖动手柄位于行最左侧勾选框之前）、一键清空已完成（二次确认弹窗，无已完成项时按钮置灰）；底部展示完成计数；可一键添加全部待办至对话输入框；模块可折叠/展开（状态持久化）。同一工作区多会话/多标签页同时编辑时按条目 id 归并，不会互相清空。
• 折叠状态：各模块折叠/展开状态刷新页面后保持（localStorage）；「会话」模块图标使用 DSH favicon。
• 新建会话页：新建/空白会话（无会话记录）页面在视口右上角显示悬浮「HUD面板」按钮（该页没有标题栏，故由本按钮提供入口；位置与真实会话标题栏按钮一致）；该页每次进入都从收起状态开始，点击按钮后展开，面板位置与真实会话完全一致（固定贴页面右侧、宽 300px），输入框与页面内容整体左移约 300px 让位；展开时按钮会同步向左让位到面板左侧（不遮挡、不重叠），收起后回到右上角；该页只展示有数据源的模块（会话 / 用量 / 便笺 / 待办 / MCP，以及目标工作区确为 git 仓库时的 git）。进入真实会话后加载该会话自己的开合记忆，标题栏原按钮接管入口。

🖼️ 界面截图

各模块预览

「会话」模块

「上下文窗口」模块

「用量」模块

「git变更」模块

「子代理任务」模块

「任务」模块

「计划清单」模块

「MCP」模块

「便笺」模块

「待办」模块

其他界面

HUD 设置菜单

「git graph」界面

「git commit」界面

「计划清单」界面

⚙️ 兼容性

🔧 技术栈

⬆️ 升级说明（v0.11.x → v0.14.1）

v0.14.1：修复 git graph 右键菜单无法打开：菜单初始状态缺少「从此处创建分支」输入行字段时会被误判为「已展开」并读取输入内容，抛出 Cannot read properties of undefined (reading 'text') 使整个右键菜单渲染失败。现已显式初始化该字段，并对读取统一做 null / undefined 归一化保护。

v0.14.0：git graph 支持「从此处创建分支」：提交行右键菜单在「合并至当前分支」下方新增该项。点击后原位展开输入框与「取消」/「确认」图标按钮，确认即基于该提交执行 git checkout -b 并跳转到新分支；输入为空时确认按钮置灰，重复分支名与本地修改阻塞均给出提示且保留输入内容，Enter 不触发创建、Escape 取消输入，Git 操作进行中时该项置灰。

v0.13.4：便笺新增安全清空：便笺操作区在「添加至对话」左侧增加「清空」按钮。输入框为空时按钮置灰；有内容时首次点击进入红色二次确认态，确认按钮以红色描边和文字显示，二次点击后清空并同步到同工作区会话。点击确认按钮外区域、按 Escape 或等待 2 秒会取消确认，不改变内容；localStorage 写入失败时保留原内容并提示。

面板开合状态改为按会话独立：旧版本把单一开关状态存在 dsh-awesome-hud:open，升级后该值会迁移为「首个进入的会话」的状态，其余会话各自默认展开并各自记忆。

新建会话页新增悬浮入口：面板位置与真实会话一致（固定贴页面右侧）；该页每次进入均为收起状态。

「便笺」「待办」由会话级改为工作区级。升级后首次在某工作区打开面板时，插件会做一次性的自动归并迁移：

• 便笺：取该工作区内候选会话中 updatedAt 最新的一份；
• 待办：按条目 id 去重合并（同 id 以先出现的为准），顺序保持稳定；
• 迁移结果写入工作区键，并记录迁移标记（dsh-awesome-hud:workspace-migrated），同一工作区只迁移一次；
• 旧的会话级键保留不删除，回滚到旧版本后仍可读到迁移前数据。

如介意旧键占用的空间，可在确认迁移完成后于浏览器控制台执行 localStorage.removeItem("dsh-awesome-hud:workspace-migrated")，再删除 dsh-awesome-hud:notes / dsh-awesome-hud:todos 中「非工作区路径」的旧键（删除后无法再回滚迁移）。

📄 许可证

MIT