前言¶

DeepSeek Harness（DSH）裏的 agent 跑長任務時，通常用 todo_write 維護一份任務清單。這份清單躺在會話面板裏，沒有提示、不顯示進度，你得自己點開才知道它做到哪一步了。dsh-todo-progress-hud 把同一份清單提到輸入框正上方，變成一條常駐的進度條，進度、當前步驟、每一項的狀態全程可見。它由 heisedexiaoniukou-max 維護，MIT 協議，屬於客戶端類插件。

下面介紹這個插件的定位、安裝與用法。

定位與數據來源¶

插件不產生任何數據，只讀取會話投影 todos。所以它顯示的內容始終和 agent 的 todo_write 一致，不需要額外配置或同步邏輯，也沒有網絡請求和持久化。沒有 todo 的會話不會渲染任何內容。

它按訪問輸入框正上方的位置工作，掛載點是 conversation.input.dock，佔用的正是 DSH 內置任務面板的同一個槽位，因此不會多出一條重複的任務信息。

核心功能¶

1、一條常駐任務條。頭部始終可見，展開後是完整清單，點一下整條可以摺疊，再點展開。摺疊狀態記在 localStorage。

2、實時進度。細進度條平滑過渡，計數（如 2/5）跟隨變化，當前步驟自動輪換。

3、狀態有色。完成轉綠、進行中爲靛藍並帶柔光環、失敗轉紅、待辦空心。

4、失敗可見。節點內容以 ⚠ / ✗ / ❌ 開頭即標記爲失敗，整條邊框告警，進度不會假裝正常。

5、外觀跟隨主題。只用 --dsw-alias-* 主題變量，無陰影、無浮層，寬度對齊輸入框；暗色模式自動換成更亮的強調色，並尊重系統 prefers-reduced-motion。

環境要求¶

• DeepSeek Harness >= 0.2.0（使用 conversation.input.dock 插槽）
• 只適用於 Web / Desktop 頁面，純 headless 環境不渲染

安裝¶

通過 GitHub 安裝，跟隨默認分支，永遠拿到最新版：

dsh plugin --profile web add github:heisedexiaoniukou-max/dsh-todo-progress-hud

需要鎖定版本時，在倉庫地址後加 #v2.1.0：

dsh plugin --profile web add github:heisedexiaoniukou-max/dsh-todo-progress-hud#v2.1.0

本地目錄安裝（開發調試時使用）：

dsh plugin --profile web add /absolute/path/to/dsh-todo-progress-hud

也可以在 DSH 界面裏通過 Settings → Plugins，或讓 agent 調用 plugin_manager 的 install_bundle 完成安裝。裝好後刷新頁面即可看到任務條。

典型用法¶

agent 正常調用 todo_write，任務條就會出現並按節點實時點亮。下面是節點失敗時的約定寫法，失敗節點需要在內容裏以 ⚠️ 開頭：

todo_write([
  { content: "K1 定位問題", status: "completed" },
  { content: "⚠️ K3 聯調（接口 500）", status: "in_progress" },
  { content: "K4 迴歸", status: "pending" }
])

行爲對應關係：

權限與副作用¶

插件不需要任何工具權限、網絡權限或 Host 服務。唯一的持久化數據是 localStorage 裏的摺疊偏好，另外可以用 todo-progress-hud:motion 強制在系統減少動畫時開啓動效。

插件以當前 dsh 進程的權限運行，安裝前應檢查源碼與許可證，確認是否滿足自身環境要求。

實現要點¶

插件由兩半組成：Host 半邊的 index.js 和瀏覽器半邊的 client.js。client.js 是唯一真正的實現，無依賴、不打包、無構建步驟，通過 window.__ModuleLoader__.load({ id, factory }) 註冊，改完刷新頁面即可生效。

有個細節值得說明：主機在每次 turn/start 會清空投影。插件按會話緩存上一份非空清單，避免換行時任務條閃爍。樣式只用主題變量，尺寸用 em 與 --dsh-content-font-size 自適應。

在控制台執行 window.__TP_HUD 可以確認瀏覽器實際加載的版本。

卸載¶

dsh plugin --profile web remove dsh-todo-progress-hud

小結¶

它解決的是同一個問題：agent 的 todo 清單藏在會話面板裏，長任務做到哪一步要靠人去點開看。現在這份清單直接顯示在輸入框上方，進度和失敗節點一眼可見。適合用 DSH Web / Desktop 客戶端跑多步任務、又不想被任務面板打斷的人。

目錄頁：https://www.skillhub.cn/plugins/heisedexiaoniukou-max/dsh-todo-progress-hud

GitHub：https://github.com/heisedexiaoniukou-max/dsh-todo-progress-hud