前言¶
在 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 插件页。
