🌐 Language / 语言：English（this page）· 中文

DSH Plugin Installer (dsh-plugin-installer)

Add a plugin-install capability to any DSH (DeepSeek Harness) deployment: a new
Install Plugin page under Settings → Plugins that installs dynamic
Cordis plugins from an uploaded package file or a Git repository URL —
installed and hot-loaded instantly. Both the installer itself and the
plugins it installs persist across restarts. Best of all, you never touch
a CLI: hand this package to a DSH conversation and say "install this
plugin" — the AI follows AGENTS.md to patch the deployment, restart, and
verify everything for you.

✨ Highlights

🚀 Quick start (conversational install, recommended)

1. Hand this directory (or an archive of it) to a DSH conversation and say:
   "install this plugin";
2. The AI follows AGENTS.md: locates DSH_HOME and the profile → runs
   install.sh (idempotent, safe to re-run) → asks about restarting the
   service (and does it for you, with verification, once you agree; the
   automatic restart force-stops the current process, so the page briefly
   disconnects and then reconnects on its own);
3. After the restart, open Settings → Plugins — the Install Plugin tab
   is there, and the installer now loads on every boot.

Equivalent manual commands (optional — same effect as step 2):

bash install.sh                    # auto-detect the only profile
bash install.sh --profile web      # pick a profile explicitly
bash install.sh --dsh-home /path   # point at a specific DSH_HOME

The script copies the plugin package → creates the
@local/dsh-plugin-installer symlink → appends the composition row (skipped
when already present) → verifies Node resolution (plus a --dump-config check
when the dsh command is available). Verify after restarting:

curl -s http://127.0.0.1:3080/ | grep -c "@local/dsh-plugin-installer"   # expect 1
curl -s -o /dev/null -w "%{http_code}" \
  "http://127.0.0.1:3080/plugins/@local/dsh-plugin-installer/client.js"   # expect 200

Just want a restart-free trial? Hand dsh-plugin-installer.json to the DSH
agent and install it with cordis_define + cordis_run (session-scoped,
temporary, writes nothing to disk; no persistence, in-page approval, or other
static-version features).

📦 Package layout

dsh-plugin-installer-pkg/
├── AGENTS.md                     # Agent-facing install guide (the playbook for conversational installs)
├── README.md                     # English documentation (this page)
├── README.zh.md                  # Chinese documentation
├── LICENSE                       # MIT license
├── install.sh                    # Persistent install script (idempotent)
├── uninstall.sh                  # One-shot uninstall script (idempotent)
├── scripts/restart-dsh.sh        # Detached restart helper (lets the agent restart the service for you)
├── dsh-plugin-installer.json     # Temporary-mode manifest (for cordis_define)
├── examples/demo-plugin.json     # Example plugin package (upload to try it out)
└── plugin/                       # Static plugin package @local/dsh-plugin-installer
    ├── package.json
    └── lib/
        ├── index.js              # Host half: install logic + persistence + session restore
        └── client.js             # Browser half: the Settings → Plugins install page UI (zh/en)

🛠️ Usage

Installing plugins (two ways)

• Upload a package file: pick a dsh-plugin.json manifest file (≤2MB);
• Git repository URL: enter a repo URL (http(s)/ssh/git protocols and
  git@ form, optional branch/tag). The default manifest location is
  dsh-plugin.json at the repo root; for monorepos, put a subdirectory-relative
  path in Manifest path (e.g. plugins/demo/dsh-plugin.json).

Manifest format:

{
  "name": "My Plugin",
  "purpose": "One-line description",
  "version": "1.0.0",
  "idPrefix": "demo",
  "host": "return { apply(ctx) { ... } }",
  "client": "return { inject: ['slots'], apply(ctx) { ... } }"
}

• name / purpose are required; provide at least one of host / client
  (function-body source in the same format as cordis_define); id
  (optional) identifies updates and defaults to name; version (optional,
  ≤64 chars) is shown in the list; idPrefix (optional, 3–6 lowercase letters).
• Reinstalling a package with the same name/id hot-updates it
  (update mode).
• Installed plugins hot-load immediately — no restart needed.

Managing installed plugins

The installed list on the install page covers the full lifecycle:

• Approve & load: after a restart restore, browser-UI plugins show this
  button — one click grants authorization and loads them (no other panel
  needed);
• Stop: stops the run but keeps persistence (it restores again after the
  next restart);
• Remove: stops the run + deletes the on-disk manifest + cancels
  persistence, so the plugin stays gone after restarts;
• Version / time / source: every row shows its version, update time, and
  source (file / Git URL);
• Failure visibility: run failures show their error message; restore
  failures show as "restore failed" with the reason;
• Cross-session reuse: plugins installed in other sessions are listed at
  the bottom with a one-click Install into this session action.

Persistence semantics

• Every install writes its manifest to $DSH_HOME/plugin-installer/store.json
  (atomic, safe under concurrent multi-session writes);
• After a DSH restart, plugins are re-registered and run automatically when
  their owning session is opened:
  • host-only plugins start immediately;
  • plugins with a browser UI show Approve & load on the install page —
    one confirmation loads them (DSH's security gate for browser code, which
    must be confirmed again after each restart);
• A corrupted store file is reported clearly on the page (the original file is
  kept — nothing is silently reset).

🗑️ Uninstall

bash uninstall.sh                    # auto-detect the only profile
bash uninstall.sh --profile web      # pick a profile explicitly
bash uninstall.sh --keep-data        # keep persisted manifests of installed plugins

The script removes the composition patch block, the node_modules/@local
symlink, the plugin package directory, and (by default) the
$DSH_HOME/plugin-installer data directory; restart the service afterwards.

❓ FAQ

Requirements

• A DSH deployment with the dynamic-Cordis plugin tools (i.e. a
  dynamicCordisRunner service is present);
• git on the machine for Git-based installs;
• Write access to $DSH_HOME (default ~/.dsh) for the install script.