Preface¶

In DSH Desktop, main process capabilities (tray, native notifications, window) are packaged in lib/main.js within resources/app.asar; Host plugins run in child processes with ELECTRON_RUN_AS_NODE=1 and cannot directly call Electron’s Tray, Menu, or Notification due to structural limitations. If every plugin needing these capabilities rewrites asar on its own, issues like overwriting each other’s writes, scattered backups, and traceable post-upgrade states will arise. Furthermore, asar is a read-only archive; any change in file length destroys the directory header and offset. The only tray region that can be safely rewritten with a fixed length is 1,253 bytes.

Below is an introduction to the community plugin dsh-asar-framework (@local/dsh-asar-framework): It centralizes “writing to asar” through the Cordis service asarShell and file channels, allowing Host plugins to use main process-side tray, notification, and window capabilities without changing the shell protocol or repackaging asar.

What is it¶

dsh-asar-framework is released by maintainer DX12xyz, categorized as a DSH Client plugin, under the MIT license. Repository: https://github.com/DX12xyz/dsh-asar-framework; Community directory page: https://www.skillhub.cn/plugins/DX12xyz/dsh-asar-framework.

One-sentence positioning: DSH Desktop’s asar “shell bridge” baseplate — fixed-length asar patching, external tray-bridge.js, asarShell service, and JSONL file channel contract. Current documentation indicates compatibility with DSH Desktop 0.2.2-rc.1 (Electron 44.7.0, Windows x64); the Web version can install the bundle, but lacks the Electron bridge and asar patching, so notification and window capabilities are unavailable.

Core Features¶

Unique Writer and Conflict Observability¶

Other plugins do not directly modify the installation directory; they only place orders via asarShell; paths that can modify asar are limited to this baseplate (offline installer or runtime fixed-length region repair). Who patched it, whether it is from this framework, or whether it is external can all be categorized, rejected, or restored; supports --dry-run to view plans, --apply to write, and --restore to revert to stock, without automatic file modification in the background.

Fixed-Length Patching and External Bridge¶

The main process only handles “one line of JSON”; plugins only recognize asarShell. Intermediate state resides in <DSH_HOME>/dsh-asar-framework/; the bridge polls the main process, with latency for notifications and tray around 250–700 ms.

Verified Capabilities¶

• notification: asarShell.forPlugin(owner).notification.show() → Host writes notify.jsonl → Bridge pops up native notification → Click returns events.jsonl.
• window (since v0.2): list / primary / show / focus; requests and results go through two JSONL streams, 2s timeout, max 16 in-flight; setTitleSuffix currently always returns WINDOW_UNSUPPORTED.
• compat gate (v0.2.2): Quick scan every 60s, heuristic identification of external sources, POST /compat/repair fixed-length repair (requires restart), POST /compat/forget etc.
• tray: asarShell.capabilities currently only contains notification and window; tray is a reserved name, lib/tray/** is a migrated domain library but not yet wired.

Maintainer’s statement: What is provided is “order protection,” not a security sandbox — it can mitigate plugins overwriting each other in collaboration, but cannot prevent malicious rewriting by plugins with the same permissions; threat model see repository docs/SECURITY.md.

Installation and Enablement¶

Prerequisites: Windows x64; DSH Desktop (documentation bound to 0.2.2-rc.1); install/maintenance scripts require Node.js 20+ (documentation states Node.js 24 is verified). Optionally use dsh CLI.

Installation is split into two chains; do not mix them:

Completing only A will not enable notifications/windows: the Host service will start, but there is no bridge in the main process. The B chain must be written after completely exiting DSH Desktop, then restart.

A. Install Bundle¶

Plugin Page (Recommended)

1. Open DSH plugin page → “Install Plugin”;
2. Fill installation source with https://github.com/DX12xyz/dsh-asar-framework or github:DX12xyz/dsh-asar-framework;
3. Restart DSH as prompted (Host side needs restart; client side just refreshes the page).

Command Line

dsh plugin --profile desktop add github:DX12xyz/dsh-asar-framework

You can also use a local directory, file:<path> pointing to the cloned repository, or download local-dsh-asar-framework-<version>.tgz from GitHub Releases:

dsh plugin --profile desktop add "file:<downloaded tgz path>"

B. asar Patch and External Bridge¶

First, set the installation root directory (the directory containing resources\app.asar):

$env:DSH_DESKTOP_INSTALL_ROOT = "<Your DSH installation root directory>"

After the bundle is installed, the first startup will detect the B chain; if not ready, click “One-click Install” in the wizard, or manually execute after completely exiting 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"

# Tray → Quit, write after completely exiting

node scripts/install.mjs --apply   --install-root "$env:DSH_DESKTOP_INSTALL_ROOT"

Rollback stock region and bridge:

node scripts/install.mjs --restore --install-root "$env:DSH_DESKTOP_INSTALL_ROOT"

Exit code: 0 success; 2 validation failure/rejected/external patch; 3 usage error. Details see repository INSTALL.md, docs/UPGRADE.md.

Optionally link with dsh-power: When the restart API is detected, the installation complete page can offer “Restart DSH”; otherwise, it only prompts for manual restart.

Typical Usage¶

Plugins obtain services via Cordis, calling them isolated by owner:

const asarShell = ctx.get('asarShell');
// Notification
await asarShell.forPlugin(owner).notification.show({ /* parameters see TECHDOC / CONTRACT */ });
// Window (v0.2+)
await asarShell.forPlugin(owner).window.show(/* ... */);

Consumers can explicitly asarShell.registerConsumer(...) or automatically register as standard via forPlugin(). For the full API and capability matrix, see repository TECHDOC.md; frozen contracts are based on CONTRACT.md.

Applicable Scenarios and Notes¶

Who is it for: Teams or individuals developing Host plugins on DSH Desktop Windows x64 that require native notifications or window control, and wish to avoid multiple parties patching asar individually.

Must Note:

1. Plugins and this baseplate run with current DSH process permissions; before installation, read the source code and MIT license to self-evaluate whether to accept fixed-length rewriting of the app.asar tray region.
2. Only supports the desktop version baseline listed in the documentation; cross-version baseline is not followed, and mismatched hash will be isolated and self-disabled.
3. Uninstalling is a two-phase process: in Settings page “Uninstall / Rollback” first --restore, then restart before disabling the plugin or deleting <DSH_HOME>\dsh-asar-framework; details see README “Uninstall and Rollback”.
4. If Web authentication failed appears after restart, documentation notes that in rare cases it is related to Electron session cookies and not necessarily asar patches; you can backup and delete %APPDATA%\@deepseek-ai\dsh-desktop\Network\Cookies as per README, then restart.

The DSH ecosystem emphasizes “everything is a plugin”; skillhub.cn is a community directory and has no official affiliation with DeepSeek / Synthflow.

Conclusion¶

Following the steps above, you obtain an auditable shell bridge path: Hosts only talk about asarShell and JSONL, the main process only talks about the external bridge and native UI, and asar writing is centralized in one place. For further reading on architecture and test matrices, open the GitHub repository; for installation via the directory page, go to skillhub plugin page.