前言¶
在 DSH 桌面版裏，主進程能力（托盤、原生通知、窗口）打包在 resources/app.asar 的 lib/main.js 中；Host 插件運行在 ELECTRON_RUN_AS_NODE=1 的子進程裏，結構上無法直接調用 Electron 的 Tray、Menu、Notification。若每個需要這些能力的插件都自行改寫 asar，會出現寫入互相覆蓋、備份分散、升級後狀態不可追溯等問題。asar 又是隻讀歸檔，任意文件長度變化都會破壞目錄頭與 offset，能安全等長改寫的托盤區域僅 1,253 字節。
下面介紹社區插件 dsh-asar-framework（@local/dsh-asar-framework）：把「寫 asar」收歸一處，通過 Cordis 服務 asarShell 與文件通道，讓 Host 插件在不改外殼協議、不重打包 asar 的前提下使用主進程側的托盤、通知與窗口能力。
這是什麼¶
dsh-asar-framework 由維護者 DX12xyz 發佈，歸類爲 DSH 客戶端插件，許可證 MIT。倉庫：https://github.com/DX12xyz/dsh-asar-framework；社區目錄頁：https://www.skillhub.cn/plugins/DX12xyz/dsh-asar-framework。
一句話定位：DSH 桌面版的 asar「殼橋」基座——等長 asar 補丁、外置 tray-bridge.js、asarShell 服務與 JSONL 文件通道契約。當前資料標明適配 DSH Desktop 0.2.2-rc.1（Electron 44.7.0，Windows x64）；Web 端可裝 bundle，但無 Electron 橋與 asar 補丁，通知與窗口能力不可用。
核心功能¶
唯一寫入者與衝突可觀測¶
其他插件不直接改安裝目錄，只通過 asarShell 下單；能改 asar 的路徑限於本基座（離線安裝器或運行期等長 region 修復）。誰打的補丁、是否本框架、是否外來，都可分類、可拒絕、可還原；支持 --dry-run 看計劃、--apply 寫入、--restore 回到 stock，無後臺自動改檔。
等長補丁與外置橋¶
| 會做 | 不做 |
|---|---|
| 將 1,253 B 托盤 region 替換爲「委託外置橋」實現，長度與 offset 不變 | 不重打包 asar、不新增注入點或 require 路徑 |
在 resources/app.asar.unpacked/dsh/tray-bridge.js 原子換裝橋文件 |
不自動更新 asar；升級需人工確認並重啓 |
提供 asarShell 與文件通道（通知、窗口請求/結果、診斷） |
不 provide tray、不寫 menu.json（托盤貢獻仍歸既有插件） |
主進程只處理「一行 JSON」；插件只認識 asarShell。中間狀態落在 <DSH_HOME>/dsh-asar-framework/，橋輪詢主進程，對通知與托盤而言延遲約在 250–700 ms。
已覈實的能力面¶
- notification：
asarShell.forPlugin(owner).notification.show()→ Host 寫notify.jsonl→ 橋彈出原生通知 → 點擊回傳events.jsonl。 - window（v0.2 起）：
list/primary/show/focus；請求與結果走兩條 JSONL，2 s 超時、最多 16 個在途；setTitleSuffix目前固定返回WINDOW_UNSUPPORTED。 - compat gate（v0.2.2）：每 60 s 快速巡檢、外來來源啓發式識別、
POST /compat/repair等長修復（需重啓）、POST /compat/forget等。 - tray：
asarShell.capabilities當前僅含notification與window；tray爲保留名，lib/tray/**爲已遷移領域庫、尚未接線。
維護者聲明：提供的是「秩序保護」，不是安全沙箱——能減輕協作型插件互相覆蓋，不能防同權限惡意改寫；威脅模型見倉庫 docs/SECURITY.md。
安裝與啓用¶
前置條件：Windows x64；DSH Desktop（資料綁定 0.2.2-rc.1）；安裝/維護腳本需 Node.js 20+（資料寫明已驗證 Node.js 24）。可選使用 dsh CLI。
安裝分兩條鏈，勿混用：
| 鏈 | 作用 | 是否改安裝目錄 |
|---|---|---|
| A. Cordis bundle | profile 依賴與 bundle | 否 |
| B. asar 補丁 + 橋 | app.asar 與外置橋、狀態目錄 |
是（--apply / --restore） |
只完成 A 不會讓通知/窗口生效：Host 服務會起，但主進程無橋。B 鏈須在 完全退出 DSH 桌面版後寫入，寫完再重啓。
A. 安裝 bundle¶
插件頁（推薦）
- 打開 DSH 插件頁 →「安裝插件」；
- 安裝源填
https://github.com/DX12xyz/dsh-asar-framework，或github:DX12xyz/dsh-asar-framework； - 按提示重啓 DSH（Host 半身需重啓；client 半身刷新頁面即可）。
命令行
dsh plugin --profile desktop add github:DX12xyz/dsh-asar-framework
亦可用本地目錄、file:<路徑> 指向 clone 後的倉庫，或從 GitHub Releases 下載 local-dsh-asar-framework-<版本>.tgz 後：
dsh plugin --profile desktop add "file:<下載的 tgz 路徑>"
B. asar 補丁與外置橋¶
先設置安裝根目錄（含 resources\app.asar 的目錄）：
$env:DSH_DESKTOP_INSTALL_ROOT = "<你的 DSH 安裝根目錄>"
bundle 裝好後首次啓動會檢測 B 鏈；未就緒可向導內「一鍵安裝」，或完全退出 DSH 後手動執行：
node scripts/install.mjs --status --install-root "$env:DSH_DESKTOP_INSTALL_ROOT"
node scripts/install.mjs --dry-run --install-root "$env:DSH_DESKTOP_INSTALL_ROOT"
# 托盤 → Quit 完全退出後再寫
node scripts/install.mjs --apply --install-root "$env:DSH_DESKTOP_INSTALL_ROOT"
回滾 stock region 與橋：
node scripts/install.mjs --restore --install-root "$env:DSH_DESKTOP_INSTALL_ROOT"
退出碼：0 成功；2 校驗失敗/拒絕/外來補丁；3 用法錯誤。細項見倉庫 INSTALL.md、docs/UPGRADE.md。
可選聯動 dsh-power：檢測到重啓 API 時安裝完成頁可提供「重啓 DSH」；否則僅提示手動重啓。
典型用法¶
插件側通過 Cordis 獲取服務，按 owner 隔離調用：
const asarShell = ctx.get('asarShell');
// 通知
await asarShell.forPlugin(owner).notification.show({ /* 參數見 TECHDOC / CONTRACT */ });
// 窗口（v0.2+）
await asarShell.forPlugin(owner).window.show(/* ... */);
消費者可顯式 asarShell.registerConsumer(...)，或通過 forPlugin() 自動登記爲 standard。完整 API、能力矩陣見倉庫 TECHDOC.md；凍結契約以 CONTRACT.md 爲準。
適用場景與注意¶
適合誰：在 DSH Desktop Windows x64 上開發需要原生通知或窗口控制的 Host 插件，且希望避免多方各自打 asar 補丁的團隊或個人。
務必注意：
- 插件與本基座以當前 DSH 進程權限運行；安裝前應閱讀源碼與 MIT 許可證，自行評估是否接受對
app.asar托盤區域的等長改寫。 - 僅支持資料列明的桌面版本 baseline；跨版本不沿用 baseline，哈希不符會隔離並自禁用。
- 卸載分兩階段：設置頁「卸載 / 回滾」先
--restore，重啓後再關插件或刪<DSH_HOME>\dsh-asar-framework；細節見 README「卸載與回滾」。 - 若重啓後出現
Web authentication failed，資料說明少數情況與 Electron 會話 cookie 有關，與 asar 補丁無必然關係；可按 README 備份並刪除%APPDATA%\@deepseek-ai\dsh-desktop\Network\Cookies後重啓。
DSH 生態強調「一切皆插件」；skillhub.cn 爲社區目錄，與 DeepSeek / 幻方無官方從屬關係。本介紹事實均來自上述倉庫 README 與 package.json 抓取內容。
結尾¶
經過上面的步驟，你得到的是一條可審計的殼橋路徑：Host 只談 asarShell 與 JSONL，主進程只談外置橋與原生 UI，asar 寫入集中在一處。進一步閱讀架構與測試矩陣可打開 GitHub 倉庫；從目錄頁安裝可走 skillhub 插件頁。
