前言¶
用 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
