6. FAQ

August 24, 2026 · View on GitHub

  1. @deepseek-ai/dsh-tools latest is stale. Pin to the next-tag version (^0.1.0-rc.6).
  2. Node too old. ^22.19 || >=24; otherwise you get an EBADENGINE warning (harmless).
  3. Mixed dsh-* version lines. Keep all of them on the same 0.1.0-rc.x.
  4. Importing @deepseek-ai/cordis at runtime. It's a peerDependency — import type only.
  5. Not "type": "module". Plugins must be pure ESM.
  6. Dropping the disposer. ctx.tools.register/ctx.on auto-dispose; for your own timers/connections, wrap them in ctx.effect(() => { ...; return cleanup }).
  7. dsh plugin add <dir> relative-path anchoring. Run it from the plugin's parent directory.
  8. name in cordis.patch.yml is a package name, not a relative path. (dsh-spike, not ./dist/tool-time.js.)
  9. Assuming file order = load order. Load order is inject service dependencies.
  10. tools/change is an unfiltered registry-subject notification. Host-level listeners see every tool register/unregister — booting emits dozens, that's normal.
  11. npm/pnpm ≥10 block native build scripts (koffi, node-pty). A fresh npx @deepseek-ai/dsh (or a plugin install) can stall because the package manager withholds the install scripts of native dependencies DSH needs. Approve them — npm: npm approve-scripts koffi node-pty (or npm approve-scripts --all; on npm 10 the command is npm approve-builds); pnpm: pnpm approve-builds. npm/pnpm ≥10 now ask before running install scripts (supply-chain hardening) — expected, not a bug.
  12. External links dead in desktop shells (Electron / bare WKWebView). A shell without an openExternal proxy silently swallows every target=_blank / window.open click. Plugin-side we already fall back to copy-link + toast (plugin-manager 0.8.1+); the real fix is host-side — two lines of Swift: implement WKUIDelegate.createWebViewWith → NSWorkspace.shared.open(url), or cancel external hosts in decidePolicyFor and open them in the system browser.
  13. Cordis patch config written but ignored. A config override must be a top-level { id, config } row — wrapping it in a - set: list is silently skipped, so your config "just doesn't take effect". Real-world pitfall: notify v0.2 shipped exactly this.

← Prev: Distribution and publishing · Contents · Next: Skins and Personalization →