前言¶
DeepSeek Harness（DSH）的對話流裏，當調用 wait_agent、job_output、bash 這類會阻塞等待的工具時，對話框會長時間保持空白，用戶無法知道當前在做什麼。這種「黑盒等待」容易讓使用者產生焦慮，也缺少對超時風險的直觀感知。
dsh-deepsleep-progress 是 DSH Web 插件，在阻塞工具卡正下方掛一條 elapsed / budget 進度條，隨時間推進更新進度，並在預算用盡或返回結果時自動收起。進度條僅反映本地等待時長與超時預算的比值，不是真實完成度，但能讓等待過程變得可見、可控。
這是什麼¶
dsh-deepsleep-progress 是一個客戶端插件，由維護者 xyzYaeMiko 開發，分類爲「客戶端」。它爲 DSH Web 中會阻塞的工具調用提供可視化的進度條，並附帶一個圖形化的設置頁面，允許用戶自定義樣式、預算、末端圖片與時鐘格式。
核心價值是：在 DSH 對話流中爲長時間等待的操作提供「可見的等待」，讓開發者與使用者都能更清晰地掌握當前任務進度與超時風險。
核心功能¶
進度條顯示¶
插件在對話流中，爲符合條件的工具調用（wait_agent、job_output、bash、ask_user_question）在工具卡正下方插入一行進度條。該行在 tool/result 事件到達前一直顯示，返回後自動隱藏。
進度條內容爲 {elapsed} / {budget}，其中 elapsed 來自會話日誌中 tool/call 事件的 time（epoch ms），時間基準是工具調用開始時刻，不是插件加載時刻。
預算來源¶
預算（budget）有四個優先級，按順序判斷：
- 命令字面量：命令中包含
sleep N（bash）或Start-Sleep …（pwsh）的時長，多個累加。echo "sleep 5"這種不作爲命中。 - 調用參數：參數中的
timeout_ms、timeoutMs或timeout（毫秒）。如果參數值小於預算，則作爲封頂。 - 配置項：
config.tools[工具名]裏配置的預算（毫秒）。 - 都不存在 → 預算未知，不畫進度條，只保留左側圖片與文字
elapsed / —。
默認預算（白名單）：
| 工具 | 默認預算 | 說明 |
|---|---|---|
wait_agent |
30000 | 工具默認 timeout_ms: 30000 |
job_output |
60000 | 估算值；顯式傳 timeout_ms 時以參數爲準 |
bash |
null |
命令字面 sleep N 時按 N 走滿；否則只有顯式傳 timeoutMs 才顯示確定進度 |
ask_user_question |
null |
隱式無限等待 |
不在白名單裏的工具永遠不顯示進度條。
三態顯示¶
進度條根據預算與 elapsed 的關係呈現三種狀態：
- 進行中：藍色填充，隨 elapsed/預算前進。
- 超額：填充到 100% 轉爲橙色。
- 預算未知：不畫進度條，只保留左側圖片與文字（如
8.0s / —）。
末端圖片¶
進度條填充的最前沿會掛一個圖片，隨進度一起移動（類似浮標/小人騎在進度頭上）。
- 默認：內置一張透明背景的「睡覺鯨魚 + zzz」圖（96px），data URI 嵌入
client.js，無需聯網。 - 自定義：通過配置
headImage指定 http(s) URL 或 data URI。GIF / APNG / WebP 會自動播放動畫。 - 位置：圖片中心對準填充前沿，並在軌道內 clamp，半張圖不會溢出軌道兩端。
- 未知預算：不畫進度條，圖片和文字停在左側，只走時鐘。
- 關閉：
headImage: ''，行高回落到 14px。
建議圖片大小 ≤ 200KB、邊長 ≤ 128px，避免影響存儲與解碼性能。
圖形化設置頁¶
DSH 設置 → 等待進度條（英文界面：Settings → Wait progress）是本插件貢獻的獨立設置頁。頁面改動立即生效，當前顯示的進度條會同步更新。
設置頁能力包括：
- 通用：總開關、前置文案（默認
deepsleeping）、時鐘格式（{elapsed} {budget} {remaining} {ratio}）、工具白名單與預算。 - 末端圖片：開關、內置圖、恢復默認圖、從本機選擇圖片（PNG/GIF/WebP）、URL 或 data URI、大小、未知預算時的顯示。
- 尺寸與間距：軌道高度、圓角、左縮進、上下間距、文字大小。
- 顏色與背景：填充色、超額填充色、軌道底色、文案顏色、時鐘顏色。每個顏色有系統取色器 + RGB / 十六進制輸入框。
- 時序：出現延遲（默認 350ms）、走字間隔（默認 100ms）。
- 清空本機覆蓋：一鍵回到插件 Config 的默認值。
持久化約定：頁面改動存在當前瀏覽器的 localStorage（鍵 wait-progress:settings:v1），作爲插件 Config 的本機覆蓋。cordis.patch.yml 裏的 Config 仍是默認值，兩者疊加時本機覆蓋優先。因此設置不會跨瀏覽器/跨設備同步；換機器或清瀏覽器數據後會回到 Config 默認值。
安裝與啓用¶
npm 安裝（市場收錄後可用）¶
plugin_manager({ action: 'install_bundle', target: 'dsh-deepsleep-progress@0.1.0' })
本地開發安裝¶
plugin_manager({
action: 'install_bundle',
target: '/absolute/path/to/this/repo',
})
安裝後查看返回的 application：applied 即已生效（HMR），restart-required 才需要重啓。
首次安裝後插件立即生效（HMR）；之後修改 Config 需要刷新頁面才能讀到新值。
典型用法¶
在 profile 的 cordis.patch.yml 中配置插件，覆蓋默認預算與樣式：
- id: deepsleep-progress
config:
# 白名單 + 預算（毫秒；null = 預算未知）
tools:
wait_agent: 120000
job_output: 90000
bash: 600000
pwsh: 600000
ask_user_question: null
# 外觀
accent: 'rgb(77, 107, 254)'
overrunAccent: 'rgb(240, 169, 58)'
track: 'rgba(148, 158, 190, 0.22)'
height: 4
radius: 2
inset: 22
gapTop: 2
gapBottom: 6
fontSize: 11
label: deepsleeping
# 末端圖片
headSize: 18
clockFormat: '{elapsed} / {budget}'
unknownBudgetText: '—'
# 行爲
enabled: true
inferSleepBudget: true
showDelayMs: 350
tickMs: 100
在 DSH 設置 → 等待進度條裏，通過圖形化界面調整上述配置，或從本機選擇圖片作爲末端浮標。
適用場景與注意¶
適合需要調用長時間運行工具（如等待外部服務響應、執行耗時 bash 命令、輪詢 job_output）的場景。進度條能幫助用戶感知等待時長與超時風險，減少對「卡死」的誤判。
注意事項：
- 進度條表示的是「本地等待時長 ÷ 超時預算」，不是真實任務完成度。預算未知時不會畫進度條。
job_output的默認 60s 上限是估算值，前端不可見；顯式傳timeout_ms時以參數爲準。- 首次安裝後，如果頁面已打開，Config 的 global 要等刷新才注入；插件本身仍會以內置默認值立即渲染。
- 設置頁的改動僅保存在當前瀏覽器的 localStorage，不跨設備同步；圖片用 data URI 存在本地，單張限制 2MB。
- 容器與文字默認使用主題 token（
--dsw-alias-*），顏色字面值屬於插件 artwork 範疇。
插件以當前 DSH 進程權限運行，安裝前應檢查源碼與許可證（MIT）。
短結尾¶
dsh-deepsleep-progress 爲 DSH 對話流中的等待操作提供可視化的 elapsed / budget 進度條與圖形化設置頁，適合需要處理長時間工具調用的場景。更多細節與源碼可訪問插件目錄頁與 GitHub 倉庫。
