前言¶
用 DeepSeek Harness（dsh）跑一轮稍长的任务时，网页界面里最常见的不确定感是：模型还在生成吗、todos 做到哪一步、子代理是不是卡在审批、刚才那次中断有没有留下痕迹。核心界面会显示工具调用和结算后的统计，但输入框附近往往缺少一条一直能看见的会话状态。
DeepSeek Harness 是 DeepSeek AI 开源的智能体运行时，架构口号是「一切皆插件」，底层用 Cordis 做组合。官方仓库目前仍标为 developer preview，兼容性破坏会持续出现。界面增强这类能力通常不改 agent-loop，而是挂到 Web GUI 的槽位上。dsh-ui-progress 做的就是这件事：在输入框停靠区放一条常驻进度条，读取会话快照来展示真实执行状态。
下面按插件目录页、GitHub README / INSTALL.md 和官方 Harness 仓库核对后整理：它是什么、能显示什么、怎么安装，以及用的时候要注意哪些边界。
这是什么¶
dsh-ui-progress 是一款面向 DeepSeek Harness Web UI 的界面增强插件，npm 包名是 @dsh-external/dsh-ui-progress，由 lhh010 维护，许可证为 BSD-3-Clause，主要语言是 TypeScript。截至 2026-08-18，目录页与 GitHub 仓库均显示 8 颗星。当前默认版本是 v0.9.1（package.json 中的 version 字段）。
它解决的问题很具体：在 conversation.input.dock（输入框停靠区）提供一条常驻会话进度条，覆盖 todos 真实进度、实时 token 生成速率、中断橘红态和待办提醒。实现方式是纯浏览器端（client）插件，不触碰 agent-loop；v0.8.0 起宿主 half 为空，也不再向模型注入任何可见输入。
package.json 里把客户端声明写成嵌套的 dsh.client，platform 为 web，并 inject @deepseek-ai/dsh-client-locale、@deepseek-ai/dsh-client-runtime、@deepseek-ai/dsh-client-ui-conversation。也就是说，它只服务于 dsh web，不是终端 TUI 插件。
收录它的 DeepSeek Harness 插件库 是独立的社区目录，与 DeepSeek / 幻方没有从属或背书关系。目录页会链到维护者仓库，安装前应自己看源码和许可证。
核心功能¶
常驻进度条读的是会话快照¶
进度条挂在输入框停靠区，读取框架的 useSession 快照，而不是自己估算一条「会话完成了百分之几」。README 写明它会渲染这些信息：
- 运行中 / 空闲
- 当前在飞的工具名
- 当前窗口已结算的工具结果数
- 当前轮次
运行中时，左侧加载圈旋转，进度条带 shimmer 扫光和品牌色光环脉冲，填充宽度缓动。
填充宽度按 todos 投影计算：有 todos 时，比例是 (已完成 + 进行中) / 总数，进行中的任务会计入进度；没有 todos 时固定填 100%。仓库明确说：会话整体进度没有专门投影，因此不展示伪百分比。v0.8.0 已去掉旧的「每个已结算工具结果进一格、窗口上限 10」分段填充。
运行中还会显示：
- 已耗时：从当前回合开始，按 0.1 秒步进；满一分钟后折叠成
XmYs，再按秒递增。 - ETA：只在模型最近一次
report_progress上报里带了eta时显示。插件自己不做线性外推，模型没报就不显示。
空闲时显示上一回合耗时。会话跑过至少一轮后进入空闲，进度条切成浅绿色；从未运行过的会话保持中性蓝灰。
中断橘红态¶
v0.8.0 增加中断态：本会话最近一个已结束回合被中断或停止——手动打断、API 故障或其他意外原因——进度条变成橘红色（浅橘背景 + 橘红填充 / 图标 / 百分比 + 慢速脉冲），标签为「已中断」。它优先于普通的运行中 / 完成配色。
判定只看最近一个回合。中断后继续发送并正常完成的新回合，会让进度条恢复常规配色；窗口里的中断遗留标记仍在，但不再触发配色。注意态（下面的琥珀色）仍优先于中断态。
仓库也写了检不出的情况：中断回合既没有 partial 内容、也没有在飞工具调用时不留痕迹；分页或压缩截断旧标记后，中断态会消退；处于 model-retry 路径的回合不显示中断态。
实时 token 生成速率¶
v0.9.0 起，运行中且模型正在生成时（有流式 partial 内容、且没有待处理的人机交互），进度条在已耗时旁显示实时速率，例如 12.3 tok/s。工具执行、等待人机交互、回合结束时不显示；回合结束后的精确速率由核心 StatsLine 呈现，避免重复。
流式 chunk 本身不带 token 计数，核心端只有回合结束后的 provider usage，所以这个数字是自校准估算值：
- 初始按 CJK 感知字符密度折算当前 partial：中日韩宽字符约 1 字符 ≈ 1 token，其余按核心 token-meter 同款 4 字符 ≈ 1 token。
- 窗口内一旦有已结算 step 上报真实 output tokens，就用「真实 tokens ÷ 加权字符数」缩放后续估算，让数字贴近所用模型 tokenizer 的密度。
- 速率按约 1 秒滑动窗口平均，只统计窗口内新增 token；空窗口保持上次读数，不归零。
- 口径与核心端结算 tokens/s（
outputTokens / decodeMs）一致，排除 TTFT；每个新 step 重新起算。
README 强调：显示值不是 provider 当场报告的 token 数，首个校准 step 之前仍是字符启发式。
待办提醒（attention）¶
本会话或其后代 subagent 存在等待人处理的交互时，进度条切成琥珀色警告态，并提示来源与类型：
| 文案 | 含义 |
|---|---|
| 等待审批 / 需要选择 | 本会话的沙箱命令审批或选项选择 |
| 子代理等待审批 / 子代理需要选择 | 来自 subagent |
| 等待审批 · 子代理 2 项待处理 | 本会话与子代理待办并存时的示例写法 |
计划审阅也属于这类等待人处理的交互。subagent 会话会被官方侧边栏隐藏，pending 状态从全局会话列表里 origin: 'subagent' 行的 pendingInteraction 读取。这是主 agent 感知子代理在等你的主要出口。
状态优先级按 README 原文是：
pending（琥珀） > running（蓝） > interrupted（橘红） > done（绿） > idle（中性）
不再向模型注入内容¶
v0.8.0 起，插件不再注入任何模型可见输入：自带的 report_progress 工具和上报引导段落已移除，宿主 half 为空，只做浏览器端呈现。不修改用户消息，也不改会话上下文。
ETA 仍然可以工作，前提是其他宿主插件注册了 report_progress，并且模型在上报里给了 eta 字段。本插件本身不再提供这个工具。
配置方面：无配置键。装好后只需在配置树插入一行插件 id。
安装与启用¶
目录页给出的安装命令是：
dsh plugin add github:lhh010/dsh-ui-progress
需要可复现安装时，目录页建议固定 commit 哈希：
dsh plugin add github:lhh010/dsh-ui-progress#commit
把 commit 换成实际哈希即可。目录页同时提醒：插件以当前 dsh 进程的权限运行，安装时可能执行代码，安装前应检查源代码仓库和许可证。
仓库 INSTALL.md 把当前默认路径写得更具体。v0.9.1 面向 DSH 快照 snapshot0810（snapshots/20260810T155924Z），并声明兼容 snapshot0811 与最终快照 snapshot0812（snapshots/20260812T172954Z-final），也兼容 npm 发版 @deepseek-ai/dsh@0.0.1-rc.5（dist-tag next）和 @deepseek-ai/dsh@0.0.1-rc.2。前置条件是：本机已有构建好的 DSH 快照（~/.dsh/source/current 指向含 lib/ 产物的快照），并且 dsh web 在运行。
按 tag 固定版本、装进 web profile 的写法如下：
git clone https://github.com/lhh010/dsh-ui-progress.git
cd dsh-ui-progress && pnpm install
dsh plugin --profile web add '@dsh-external/dsh-ui-progress@github:lhh010/dsh-ui-progress#v0.9.1'
本地开发也可以用 link：
dsh plugin --profile web add link:/path/to/dsh-ui-progress
然后在 $DSH_HOME/profiles/web/cordis.patch.yml 插入：
- insert:
- id: dsh-ui-progress
name: '@dsh-external/dsh-ui-progress'
INSTALL.md 写明：这条配置热重载，不必为了加配置行而重启。v0.8.0 起宿主 half 为空，浏览器 half 刷新页面即可生效。如果改过源码或换过快照，0809 及之后的宿主在激活时会校验客户端构建产物，缺失会抛 ClientPackageCompositionError 并拒绝启动 dsh web，这时需要重新 pnpm run build 再启动。
旧快照不要混用默认 tag。README 的对应关系可以缩成下面这张表：
| 插件版本 | DSH 快照 | 说明 |
|---|---|---|
v0.9.1（默认） |
snapshot0810，兼容 0811 / 最终 0812 | 客户端元数据改为嵌套 dsh.client |
v0.9.0 |
snapshot0809 | 原生 0809 构建，含实时 token 速率 |
v0.8.0 |
snapshot0808（兼容 0809） | 去掉自带 report_progress，改为 todos 真实比例 + 中断橘红态 |
v0.6.0 |
snapshot0807 | 旧 slot 契约，不适用于 0808 及之后 |
v0.1.0 |
snapshot0805 | 旧安装方式：~/.dsh/config.yaml + pnpm add -w link: |
0809 用户固定 #v0.9.0，0808 用户固定 #v0.8.0，0807 用户固定 #v0.6.0，0805 用户固定 #v0.1.0。DSH 仍在快速迭代，装之前先对一下自己的快照或 npm 版本。
典型用法¶
插件没有额外配置项，启用后直接看输入框上方的进度条即可。INSTALL.md 给出的验证步骤可以按原样做：
- 开一个会跑工具、最好带 todos 的会话。运行中应看到加载圈旋转、实时已耗时；模型正在生成时出现 token 速率；若有其他插件提供
report_progress且模型上报了eta，还会出现预计剩余时间。 - 有 todos 列表时，填充宽度应按真实完成比例变化；没有 todos 时填充固定 100%，不要把它读成「已经全部完成」。
- 手动停止会话，或等到 API 出错中断后，进度条应切成橘红色「已中断」。
- 中断后再发一条并让回合正常结束，进度条应回到绿色完成态。
- 若本会话或子代理在等审批 / 选择，进度条应先进入琥珀色注意态，文案会区分本会话和子代理。
README 还提到一种排障方式：dsh web 启动后，浏览器里 window.__DSH_BOOT__ 清单应包含 @dsh-external/dsh-ui-progress，并且 /plugins/@dsh-external/dsh-ui-progress/client.js 返回 200。0810 起如果 package.json 仍只写顶层 dshClient、没有嵌套 dsh.client，宿主会静默把它排除出 boot 图——「启动顺利但插件全没」。当前 v0.9.1 已经迁到嵌套字段。
适用场景与注意事项¶
适合这些情况：
- 日常用
dsh web，希望在输入框附近一直看到当前回合是否在跑、todos 做到哪、耗时多少 - 任务里经常出现沙箱审批、选项选择或子代理，需要一条不会被侧边栏藏起来的待办提醒
- 关心流式生成速度，想把运行中的估算 tok/s 和回合结束后的 StatsLine 对照
- 接受「纯 UI、零核心改动」，不想让进度插件改 agent-loop 或往上下文里塞提示词
使用前注意下面几条，都来自目录页和仓库文档：
- 只覆盖 Web UI。
dsh.client.platform是web。终端里的 TUI 或纯 CLI 会话看不到这条进度条。 - 填充比例不是全程进度。 无 todos 时固定 100%；有 todos 时只反映当前 todos 列表。不要用它判断「这个会话还要多久彻底结束」，除非模型另外通过
report_progress给了eta。 - token 速率是估算值。 流式阶段没有官方 token 计数；校准前是字符启发式，校准后仍是滑动窗口平均。最终以核心 StatsLine 的结算值为准。
- ETA 依赖别人。 本插件不再自带
report_progress。没有其他插件注册该工具、或模型没报eta（非字符串 / 非正数也视为无效），ETA 行就不会出现。进度条只取窗口内最近一次上报。 - 中断检测有盲区。 无 partial、无在飞工具的中断可能检不出；压缩窗口后旧标记会丢；重试路径不显示中断态。
- 版本必须对齐快照。 默认
v0.9.1面向 0810 及之后；更早的 snapshot 要用对应 tag。官方 Harness 仍是 developer preview，换快照后应核对 README 的兼容说明。 - 权限与来源。 插件以当前 dsh 进程权限运行。社区目录不是官方应用商店，安装前检查 GitHub 源码 和 BSD-3-Clause 许可证；需要可复现环境时固定 tag 或 commit。
小结¶
dsh-ui-progress 把会话执行状态钉在 Web UI 的输入框停靠区：todos 按真实列表填进度，运行中给出已耗时和自校准的 token 速率，中断切橘红，等人处理时切琥珀，完成切浅绿。它是 lhh010 维护的开源 client 插件，不改 agent-loop，也从 v0.8.0 起不再向模型注入内容。
对已经在用 dsh web、又希望少盯侧边栏和工具卡片的人来说，装上之后主要变化就是输入框上方多了一条一直在的状态条。版本要和当前 DSH 快照对齐，装之前看一眼源码和许可证。
目录页：https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-ui-progress/
GitHub：https://github.com/lhh010/dsh-ui-progress
