Install guide

How to install dsh-advisor into a dsh profile, verify the install, and uninstall. The quick version lives in the README.

Prerequisites

• A dsh runtime environment ($DSH_HOME, default ~/.dsh) and a writable target profile (e.g. web); restart the dsh session after installing.
• A registry install needs only pnpm on PATH (dsh plugin is a pnpm forwarder). Building from source (git / local / tarball installs below) additionally needs node (≥ 22) and registry auth for the private @deepseek-ai/* peers — prepare runs pnpm build only (no DSH_HOME source-tree prerequisite for dependency resolution; the peers resolve from the npm registry via autoInstallPeers + the ~/.npmrc auth token).

1. One-line registry install

dsh plugin --profile web add dsh-advisor   # <name> = your profile name
# Pin an exact version for reproducibility:
# dsh plugin --profile web add dsh-advisor@0.1.0

A registry install fetches the published tarball, which ships the built artifacts (lib/ + cordis.patch.yml) and has no install / postinstall scripts — no prepare build runs and no build permission is needed. Runtime dependencies (@deepseek-ai/cordis, @deepseek-ai/schemastery, and the @deepseek-ai/dsh-* peers) are declared as peerDependencies and resolved by the dsh installation's flat profile module fallback — no extra install step.

• Version pinning: append @<version> to pin (e.g. dsh-advisor@0.1.0). Registry packages have no commit pinning; use the local directory install to test un-released changes.

2. Local directory install (development / verification)

pnpm install                  # build the bundle (prepare self-build)
dsh plugin --profile web add .   # <name> = your profile name

dsh plugin add appends the bundle to the profile's dsh.profile.bundles (the package declares dsh.bundle); the bundle inserts one plugin row — id: advisor, name: dsh-advisor (see cordis.patch.yml). A local add . goes through pnpm's link: dependency, for which pnpm does not run prepare/postinstall — build the bundle with pnpm install (or pnpm build) before adding. No host patching is involved: the plugin runs entirely from its plugin config row (see Web Settings exposure).

3. Tarball install

pnpm pack
dsh plugin --profile web add dsh-advisor-0.1.0.tgz

A tarball ships the built artifacts (lib/ + cordis.patch.yml), so no prepare script runs and no build permission is needed. Runtime dependencies (@deepseek-ai/cordis, @deepseek-ai/schemastery, and @deepseek-ai/dsh-{session,agent,llm,commands,timeout}) are declared as peerDependencies and resolved by the dsh installation's flat profile module fallback — no extra install step.

4. dsh-tui profile install

The advisor also installs into the terminal TUI profile (dsh --profile dsh-tui) with the same commands as the web profile:

dsh plugin --profile dsh-tui add dsh-advisor   # <name> = your profile name
# Pin an exact version for reproducibility:
# dsh plugin --profile dsh-tui add dsh-advisor@0.1.0
# Local-dir variant (from a built checkout):
dsh plugin --profile dsh-tui add .

The bundle inserts the same - insert: id: advisor row into the dsh-tui profile's patch layer (~/.dsh/profiles/dsh-tui/cordis.patch.yml). The advisor settings namespace is shared across profiles via the global $DSH_HOME/settings.yaml advisor: section (the web Settings card writes there too). On dsh-tui ≥ v0.8.0 the TUI /settings screen also edits the same five keys (enabled / provider / model / immuneTurns / maxDeltaMessages) in its Advisor section — edits are staged and written on save through the revision-fenced settings.mutate into the same namespace user layer, re-applying live without a restart. The section ships with the dsh-tui-settings-sections row in the v0.8.0+ bundle; on older dsh-tui versions it is a clean no-op and the patch layer / settings.yaml remain the edit paths. systemPrompt is not a TUI field (single-line input) — edit it via the web card or $DSH_HOME/settings.yaml. /advisor config is the readback (read-only, with edit hints naming the /settings screen when the seam is mounted), and /advisor / on|off|status|config surface in the TUI / menu with subcommand completion (requires the dsh-tui-command-trees row, shipped in the dsh-tui bundle).

Verify:

dsh --profile dsh-tui --dump-config   # shows a "# == dsh-advisor" layer with the advisor row
dsh --profile dsh-tui

Uninstall:

dsh plugin --profile dsh-tui remove dsh-advisor
dsh --profile dsh-tui --dump-config   # confirm the dsh-advisor layer is gone

5. Web Settings exposure

The dsh web Settings page's "插件配置" (Plugin Configuration) page renders one card per plugin that registers into the settings.plugin.item card slot. The Advisor card (namespace key advisor, rendered after the upstream bash / agent-loop / web-search cards in registration order) reads the provider directory through the dsh host's apiproxy describe (the exposed llm-* namespaces), but reads and writes the advisor config EXCLUSIVELY through the official GatewayService RPC channel — it does not depend on the apiproxy allowlist, which exposes only an allowlist of namespaces to configuration clients: model-provider namespaces plus product namespaces (locale / permission / ui-conversation / ui-theme / ui-onboarding / agent-presets). Upstream dsh has no registration-level opt-in (exposeToWebClients does not exist in upstream SettingsRegisterOptions — verified against the pristine 20da39e snapshot), so the advisor namespace is not on the apiproxy allowlist. The plugin registers AdvisorConfigGateway (a GatewayService with @Remote('get')/@Remote('set') methods), the host's typertGateway claims /api/advisor/get + /api/advisor/set (the same mechanism the dsh goals service uses), and the card calls them via connection.rpc. The in-process write (ctx.settings.update) carries no exposed-namespace check, so saving works on any dsh build that ships the GatewayService channel. No host patching is applied or required.

6. Verify

dsh --profile web --dump-config   # shows a "# == dsh-advisor" layer with the advisor row
dsh --profile web

After booting, the web Settings page's "插件配置" page renders the Advisor card; it reads and writes the advisor namespace live through /api/advisor/get + /api/advisor/set — saving applies to new sessions immediately.

7. Uninstall

dsh plugin --profile web remove dsh-advisor
dsh --profile web --dump-config   # confirm the dsh-advisor layer is gone

Restart the dsh session to complete the uninstall.