前言¶

DeepSeek Harness（DSH）桌面端基於 Electron / Chromium。實測表明：只要窗口沒有最小化，渲染進程裏常駐的 requestAnimationFrame（rAF）循環仍會按約 60 fps 出幀，即便窗口已經被別的程序完全蓋住。Chromium 自帶的遮擋檢測對「普通窗口疊在上面」往往有效，但對獨佔全屏遊戲這類繞過 DWM 的遮擋識別不到，GPU 與渲染進程仍會維持高佔用。

最小化可以立刻把佔用壓到接近零，但會改變窗口狀態。維護者 codelearnerlu 的客戶端插件 dsh-occlusion-throttle 換了一條路：在宿主側用 Win32 判斷窗口是否被完全遮擋，在前端把 rAF 與 CSS 動畫掛起；重新可見時立即恢復。插件歸類爲「客戶端」，僅支持 Windows；當前版本 0.1.0，許可證 MIT，依賴 DSH engines.dsh: ^0.2.1-rc.2。倉庫尚未發佈到 npm，也未提交 DSH 市場，需按 README 手動鏈入 desktop profile。

這是什麼¶

dsh-occlusion-throttle 是 DSH 桌面端插件：當應用窗口被其他窗口完全遮擋（典型場景是獨佔全屏遊戲蓋住 DSH），暫停動畫渲染（rAF + CSS 動畫）；窗口重新露出時立刻恢復。觀察器自身開銷約 0.12% 單核（默認 occlusion-watcher.exe），工作集約 15.7 MB。

• 維護者：codelearnerlu
• 目錄頁：https://www.skillhub.cn/plugins/codelearnerlu/dsh-occlusion-throttle
• 源碼：https://github.com/codelearnerlu/dsh-occlusion-throttle

爲什麼需要它¶

README 中記錄了本機 2026-11-05/06 的對比（頁面含常駐 rAF 時）：

結論：未最小化時 Chromium 會持續出幀；獨佔全屏遮擋需自行判斷。本插件在遮擋且文檔無焦點時掛起前端動畫，目標效果接近「不停渲染卻不改最小化狀態」。

核心功能與工作方式¶

檢測與通信¶

1. 宿主側（index.js）拉起常駐觀察器：默認每 400 ms 用 WindowFromPoint 在窗口內採樣 16 個點（中心點快路徑）；狀態變化或每 2.5 s 心跳時輸出 JSON。
2. 暴露本機 HTTP 接口：GET /dsh-occlusion-throttle/state。
3. 前端（client.js）約每秒輪詢一次；當 occluded: true 且 document.hasFocus() === false 時掛起 rAF，併爲 <html> 加上 .dsh-occlusion-sleep 以暫停 CSS 動畫。
4. 恢復可見、獲得焦點、pointerdown、visibilitychange 或出錯路徑會立即喚醒並補跑掛起的回調。

安全策略（失敗即不降頻）¶

• 接口 404、超時 800 ms、JSON 解析失敗、宿主未就緒：一律按「不遮擋」，正常渲染。
• 宿主觀察器崩潰約 5 秒後自動重啓；狀態超過 8 秒無心跳按「未知 = 不降頻」。
• 對點穿/透明覆蓋層與 DWM cloaked 窗口有過濾，降低誤判（例如 NVIDIA Overlay 類 layered 窗口）。

設置界面¶

設置 →「遮擋降頻」：可查看實時狀態、啓用開關、輪詢間隔與最近事件（暫停/恢復時間與累計統計）。

安裝與啓用¶

安裝需編輯 desktop profile 並重啓 DSH（三步）。將 $src 換成你本地的插件目錄路徑（README 以目錄聯接爲例，不是 dsh plugin add 一鍵命令）：

$profile = "$env:USERPROFILE\.dsh\profiles\desktop"
$src     = "<你的路徑>\dsh-occlusion-throttle"
cmd /c mklink /J "$profile\node_modules\dsh-occlusion-throttle" $src

編輯 $profile\package.json：

1. 在 dependencies 增加一行，例如："dsh-occlusion-throttle": "link:D:/Study/DeepSeek Harness Workspace/dsh-occlusion-throttle",（路徑改爲你本機實際路徑）。
2. 在 dsh.profile.bundles 數組增加 "dsh-occlusion-throttle"。

托盤退出 DSH 後重新打開以使 bundle 生效。

驗證與典型用法¶

遮擋時主界面被蓋住，無法直接看面板，可用以下任一方式驗證。

看日誌（推薦）——在另一窗口或第二塊屏執行：

Get-Content "$env:USERPROFILE\.dsh\occlusion-throttle.log" -Wait -Tail 5

將 DSH 窗口完全蓋住約 3 秒再放開，日誌中應出現 client sleep (occluded) / client wake。任務管理器中 DeepSeek Harness (renderer) 在遮擋期間應接近 0 佔用。

設置頁回放——設置 → 遮擋降頻 →「最近事件」與「累計暫停 X 秒 · N 次暫停」。

命令行查狀態——端口隨啓動變化，使用 GUI 中顯示的地址：

curl.exe -s http://127.0.0.1:<端口>/dsh-occlusion-throttle/state

前端調試對象：window.__DSH_OCCLUSION_THROTTLE__（含 stats、poll、wakeNow）。

不安裝 DSH 也可跑倉庫自檢（使用 DSH 自帶 node）：

$node = "$env:USERPROFILE\.dsh\dsh-runtimes\dsh-primary-runtime\dependencies\node\bin\node.exe"
& $node .\selftest.mjs
& $node .\client-selftest.mjs

卸載¶

1. 從 package.json 的 dependencies 與 dsh.profile.bundles 刪除對應項；
2. 刪除 node_modules\dsh-occlusion-throttle 目錄聯接；
3. 重啓 DSH。

適用場景與注意¶

適合誰

• 常在 Windows 上開着 DSH，同時玩獨佔全屏遊戲或其它全屏程序，希望後臺不把渲染/GPU 頂滿的用戶。
• 需要在本機 localhost 讀狀態、並接受插件以當前 DSH 進程權限運行（觀察器只讀窗口幾何，與 127.0.0.1 通信，README 聲明不上傳數據、不聯網）。

邊界

• 僅 Windows（os: ["win32"]）；其它平臺宿主 no-op。
• 整窗被遮擋才降頻；任一樣本點仍露出則視爲可見。
• 暫停的是 rAF 與 CSS 動畫，不等價於 Chromium 進程級休眠；與最小化、普通窗口遮擋（Chromium 已能識別）相比，價值主要集中在獨佔全屏遮擋場景。
• 安裝前請閱讀源碼與 MIT 許可證；倉庫說明當前未上架 npm / 市場，自行鏈入即表示接受本地構建與觀察器（可選本地用 csc 編譯 occlusion-watcher.exe，否則回退 PowerShell 版，開銷更高）。

DSH 生態強調「一切皆插件」；社區目錄站點（如 skillhub.cn）與 DeepSeek / 幻方無官方從屬關係，本文檔以 GitHub README 與 package.json 爲準。

結尾¶

dsh-occlusion-throttle 用 Win32 點位採樣補足 Chromium 對獨佔全屏遮擋的盲區，以約 0.12% 單核成本在前端閘斷動畫循環，重新可見即恢復。需要鏈接安裝、重啓與日誌/設置頁驗證時，可按上文步驟操作。

• 插件目錄：https://www.skillhub.cn/plugins/codelearnerlu/dsh-occlusion-throttle
• GitHub：https://github.com/codelearnerlu/dsh-occlusion-throttle