dsh-awesome-hud
为 DeepSeek Harness Web 聊天页打造的悬浮 HUD 面板：会话状态、上下文占用与一键压缩、git 变更、子代理、任务与 MCP 启停，一目了然。
HUD在dsh中的效果（浅色主题）
alt text
HUD在dsh中的效果（深色主题）
alt text
[!NOTE]
一个 DSH Web 插件（dsh.bundle.patch 通道安装）。浏览页面右上角新增「HUD面板」按钮，点击开合悬浮面板；面板与 dsh-better-sidebar 右侧栏互斥协作，互不遮挡。
📑 目录
✨ 功能列表
| 模块 | 说明 |
|---|
| 会话 | 当前工作区名称、会话名称、会话状态（任务中/待审批/空闲中/待回答/等待子任务）、模型提供商/模型名/推理等级；会话名称右侧铅笔按钮可重命名（点击进入编辑态，输入框+取消/确认，确认后保存并自动更新会话列表标题）；右上角「HUD 设置」勾选展示模块 |
| 上下文窗口 | 上下文占用进度条（0–40% 绿 / 40–90% 黄 / >90% 红）、底部展示「已用 n · 上限 n · 缓存命中 n%」（缓存命中率保留一位小数；数据不可用时显示 —）、一键「压缩」当前会话上下文 |
| 用量 | DeepSeek 余额、OpenCode Go 三个窗口用量百分比（oc-go 5h/1w/1m）与 Codex 5 小时/周剩余额度百分比（dsh-codex-subscription 返回 gpt-reserve 额度时，追加展示同等样式的 codex gpt-reserve额度 行）；行首带对应图标并缩进，点击具体数值直达对应设置页；DeepSeek、OpenCode Go 与 Codex 按各自安装/登录状态独立展示 |
| git | 当前分支（标题栏右侧分支按钮：下拉列表可切换已有分支、创建新分支并自动切换）、变更文件数量；变更文件按暂存区（staged）与未暂存区（changes）分组展示（组名带灰色计数，无文件的分组自动隐藏）；文件行点击可暂存/移除暂存/撤销；「commit」提交暂存区（手动输入或 AI 生成提交信息——按内置本地 git 提交规范 [YYMMDD] 项目名 vX.Y.Z：内容），「revert」撤销全部未暂存变更（已跟踪文件还原内容、未跟踪新建文件一并删除；破坏性操作均有二次确认与受影响文件清单）；「git graph」弹窗（全部引用提交分页展示：每页最多 80 条，滑到底部出现「加载更多」按钮逐页追加，直至全部历史；当前分支标签为蓝底白字，其他分支为灰底黑字；提交行右键菜单可复制短哈希/全哈希/提交标题、从此处创建分支、合并至当前分支，或执行 soft / mixed / hard reset；创建分支为原位输入 + 图标按钮，合并与 reset 为行内二次确认）；仅在有 git 仓库时展示 |
| 子代理任务 | 当前会话全部后代子代理（按层级缩进）、执行中（黄）/已完成（绿）状态，点击跳转子代理会话页；仅在有子代理时展示 |
| 任务 | 当前会话待办任务列表、已完成/待完成状态与计数（如1/3），随任务列表实时刷新；进行中任务显示旋转动画图标，底部展示「已完成/进行中/待处理」三态计数（含 0 恒显）；仅在有任务时展示 |
| 计划清单 | 当前会话通过 plan 模式（exit_plan_mode）产出的全部计划：待审批（黄）/已执行（绿）/已废弃（灰、划线淡色）三态标签，标题栏展示计划总数，点击行弹出计划全文弹窗，模块底部展示「已执行/待审批/已废弃」三态计数（含 0 恒显）；仅在有计划记录时展示 |
| MCP | 接入的全部 MCP 服务及 dsh 全局启用状态；开关直接启停 dsh 全局的 MCP 服务（写入 profilecordis.patch.yml），切换后页面刷新 |
| 便笺 | 按工作区共享的便笺（同一工作区目录下所有会话共用一份内容，本地持久化）；输入框底部拖拽手柄可调整高度（实时持久化），5000 字上限与字符计数，右侧圆点指示内容存在；可一键添加便笺全文至对话输入框；输入框为空时「清空」按钮置灰，有内容时需二次确认后清空；折叠/展开状态持久化 |
| 待办 | 按工作区共享的待办清单（同一工作区目录下所有会话共用一份清单与顺序，本地持久化）；勾选完成/恢复、添加/删除、整行拖拽排序（拖动手柄位于行最左侧）、一键清空已完成（二次确认，空列表置灰）；底部展示完成计数；可一键添加全部待办至对话输入框；折叠/展开状态持久化 |
互斥协作：打开 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 位）/提交标题，并提供以下受保护操作：
🖼️ 界面截图
各模块预览
「会话」模块
alt text
「上下文窗口」模块
alt text
「用量」模块
alt text
「git变更」模块
alt text
「子代理任务」模块
alt text
「任务」模块
alt text
「计划清单」模块
alt text
「MCP」模块
alt text
「便笺」模块
alt text
「待办」模块
alt text
其他界面
HUD 设置菜单
alt text
「git graph」界面
alt text
「git commit」界面
alt text
「计划清单」界面
alt text
⚙️ 兼容性
| 项目 | 版本/说明 |
|---|
| DeepSeek Harness | 0.1.1-rc.2（其余 rc 线未逐个验证；插件以可选服务 + 特征检测方式降级） |
| dsh-plan-mode | 计划清单数据源：会话日志exit_plan_mode 工具调用（tool/call/tool/result/plan/mode 事件）；上游审批语义变更时需复查状态推导 |
| dsh-better-sidebar | 0.16.1（通过公开服务 ctx.betterSidebar 监听面板状态；自动关闭依赖其折叠按钮 DOM 特征，失败时按「延迟打开」降级，不影响 HUD 独立使用） |
| 平台 | macOS 已验证；Windows/Linux 仅理论兼容（git 命令行为一致） |
| 主题 | 跟随深浅主题（使用--dsw-alias-* 主题 token） |
| 语言 | 简体中文 / English，跟随 DSH locale |
| 数据作用域 | 「便笺」「待办」按工作区目录共享（localStorage）；无 cwd 的会话降级为会话级隔离 |
| 面板开合状态 | 按会话 id 独立持久化（dsh-awesome-hud:open，值为 `{ "会话 id": "1" |
| 面板开合状态 | 按会话 id 独立持久化（dsh-awesome-hud:open，值为 `{ "会话 id": "1" |
🔧 技术栈
| 类别 | 内容 |
|---|
| Host 侧 | Node.js ESM、ctx.webServer 前缀路由、ctx.settings、ctx.tools.guard、ctx.subagents、ctx.compaction、ctx.subprocess、ctx.llm（AI 生成提交信息） |
| Client 侧 | 原生 JavaScript ModuleLoader bundle、React（react.createElement）、Cordis Slots（conversation.session.header.utilities / shell.overlay）、CSS 主题变量；不新增 slot，新建会话页入口复用 shell.overlay |
| 数据来源 | 客户端会话投影（ctx.sessions.list / workspaces / modelDirectories）+ 自有 host API（git / MCP / 子代理 / 计划清单 / 压缩）+ dsh-account-usage 余额/用量路由（复用） |
| 测试 | node --test（git 解析、MCP 解析、状态推导、计划清单推导、设置收敛、信任围栏；位于 test/） |
⬆️ 升级说明（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
