前言¶
在 DSH 裏做插件兼容性排查時，若依賴上游的 dsh-compat-check 工具，每次檢查都要把完整工具 schema 隨請求發給模型，一次檢查往往要 4–8 輪往返，每輪輸入 token 在 40–100K 量級，而實際計算都在本機完成。對日常開發或 CI 門禁來說，這既慢又貴。下面介紹社區插件 dsh-compat-optimize（維護者 dongchiluo，分類：客戶端）：在保持與原有判定邏輯一致的前提下，用磁盤緩存預熱、單次返回報告，並提供不經過模型的離線 CLI。
這是什麼¶
dsh-compat-optimize 是 DSH 插件，同時附帶可獨立運行的 Node CLI。倉庫說明爲：Fast path for DSH plugin compatibility checks: cache warm-up, one-shot reports, zero-token CLI。無需構建步驟，也無額外 npm 依賴。載入 DSH 後註冊工具 compat_optimize（插件 id：tool-compat-optimize）。可選依賴同目錄下的 dsh-compat-check 加載上游檢查邏輯；未安裝時使用內置 fallback。
與 dsh-compat-check 的差異¶
| 階段 | 使用 dsh-compat-check（LLM 工具） | 使用本插件 |
|---|---|---|
| 工具 schema | 每次請求重傳（約 1,198 字符描述） | compat_optimize 描述壓縮至約 104 字符 |
| 單次檢查 | 4–8 輪往返 | action=run 一次返回摘要、報告路徑與報告正文 |
| 本地計算 | 反覆解析約 4.76 MB 的 app.asar 頭（冷路徑約 183 ms） |
頭信息解析一次並落盤，跨進程複用（暖緩存約 85 ms） |
| 離線 / CI | 只能經模型調用 | bin/compat-check-cli.mjs，0 token |
資料中說明：deferLoading 不能省 token，宿主仍會在每次請求中投影工具定義；縮短 description 纔是省 token 的手段。
核心功能¶
DSH 工具動作¶
通過 compat_optimize 的 action 參數調用（action 必填）：
action |
作用 | 是否聯網 |
|---|---|---|
status |
緩存狀態、上次運行摘要 | 否 |
warm |
解析 app.asar 頭並持久化 |
否（除非 withNetwork: true） |
run |
執行檢查，返回緊湊摘要與報告 | 否 |
bench |
重複 N 次並報告中位數/最小/最大耗時 | 否 |
notes |
與上游 GitHub release、npm 對照 | 緩存未命中時需聯網 |
還可傳 installDir、pluginsDir、outDir、cacheDir、iterations、refresh、withNetwork、source 等參數。
離線 CLI¶
node bin/compat-check-cli.mjs [command] [options]
命令：check（默認）、status、warm、notes、bench。
退出碼：0 無損壞插件；1 發現不兼容插件；2 運行時錯誤。
默認不訪問網絡，除非指定 --notes、--refresh 或 --network。
磁盤緩存¶
默認目錄 <baseDir>/.cache/compat-check/，與 dsh-compat-check 字節級兼容，包含 asar-header、asar-entry、upstream、last-run.json 等。條目用內容指紋（首 64 KB 的 sha1）校驗，避免 Electron 下 app.asar 合成 stat 導致緩存失效。
安裝與啓用¶
將倉庫放入 DSH 插件目錄（默認 <baseDir>/plugins），無需 npm install：
git clone https://github.com/dongchiluo/dsh-compat-optimize.git <baseDir>/plugins/dsh-compat-optimize
<baseDir> 解析順序：$DSH_COMPAT_BASE_DIR → $DSH_HOME → 用戶主目錄。CLI 可單獨指定根目錄，例如：
DSH_COMPAT_BASE_DIR=/opt/dsh node bin/compat-check-cli.mjs check
配置默認值在 cordis.patch.yml，可在個人 profile 中按插件 id 覆蓋（整段替換，不合並；省略字段則回退 schema 默認）。常用字段包括：
| 字段 | 默認 | 含義 |
|---|---|---|
baseDir |
空則見上 | 插件、報告、緩存根目錄 |
pluginsDir |
空則 baseDir/plugins |
待檢查插件目錄 |
installDir |
空則自動檢測 | DSH 安裝目錄（可指向 resources/app.asar） |
outDir |
空則 baseDir/out/compat |
報告輸出目錄 |
cacheDir |
空則 baseDir/.cache/compat-check |
緩存目錄 |
warmOnStart |
false |
插件啓動時是否預熱緩存 |
mainPluginDir |
空則同級 dsh-compat-check |
上游檢查邏輯路徑 |
典型用法¶
在插件目錄下，零 token 做一次檢查（退出碼即結論）：
node bin/compat-check-cli.mjs check
CI 門禁與 JSON 輸出：
node bin/compat-check-cli.mjs check --json
先預熱再檢查：
node bin/compat-check-cli.mjs warm && node bin/compat-check-cli.mjs check
性能採樣：
node bin/compat-check-cli.mjs bench --bench 10
自測（約 60 條斷言，無 DSH 安裝也可跑大部分用例）：
node _selftest.mjs
適用場景與注意¶
- 適合：需要在對話外批量或自動化做 DSH 插件兼容性檢查、希望減少
compat_check多輪 token 消耗、或在 cron/CI 裏用退出碼做門禁的開發者。 - 環境：Node.js ≥ 20；作爲 DSH 插件時需 DSH
>=0.2.1-rc.5 <0.3.0（package.json 版本 0.1.0，MIT 許可證）。 - 安全與權限：插件在當前 DSH 進程權限下運行，會讀取安裝目錄、插件目錄並寫入緩存與報告。安裝前請自行審閱倉庫源碼與許可證，社區目錄 skillhub.cn 爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
dsh-compat-optimize 把兼容性檢查從「多輪 LLM 工具調用」收成「本地緩存 + 一次 run 或一條 CLI」，判定與上游邏輯對齊，並給 CI 提供了明確的退出碼。進一步瞭解可訪問目錄頁與倉庫：
- 目錄頁：https://www.skillhub.cn/plugins/dongchiluo/dsh-compat-optimize
- GitHub：https://github.com/dongchiluo/dsh-compat-optimize
