04-debugging.md

4. Debugging and verification workflow

The sequence below is the exact, spike-proven path (works without a DEEPSEEK_API_KEY).

4.1 Scaffold

npx create-dsh-plugin my-plugin -t tool          # tool | events | webui
npx create-dsh-plugin my-events -t events --yes --verify

--verify runs pnpm install then pnpm run build then dsh plugin add (temp profile) then dump-config grep. The scaffold's core value is pinning @deepseek-ai/dsh-tools to the next-tag version (see §5.3 Distribution).

Screenshot: (four green steps).

4.2 Build

cd my-plugin
pnpm install
pnpm run build          # tsc -> dist/index.js (pure ESM)

4.3 Install into a profile

# From the PARENT directory (relative paths anchor to the invoking dir):
dsh plugin --profile my-profile add ./my-plugin

Screenshot: (dsh plugin add + --dump-config).

4.4 Verify config composition

dsh --profile my-profile --dump-config | grep my-plugin
# expected:
#   - id: my-plugin
#     name: my-plugin

--dump-config prints the assembled tree without booting; --dump-default-config prints only the bundle layer.

4.5 Boot and observe

dsh --profile my-profile
# watch for the plugin's own logs, e.g.:
#   [my-plugin] registered "my_tool" — listed=true
# Ctrl-C → the disposer runs: [my-plugin] DISPOSED — ...

4.6 Prove events fire without a key

dsh plugin --profile headless add ./my-plugin
dsh --profile headless "run a probe"
# session/event fires for real; the model call then fails with MISSING_CREDENTIAL
# (the honest blocker — you've proven compile + load + event wiring).

Useful environment variables: DSH_HOME, DEEPSEEK_API_KEY, DEEPSEEK_BASE_URL, DSH_TOOLS_MODE (native/code/both), DSH_PERMISSION_MODE, DSH_CWD.

---

← Prev: The 15 design principles · Contents · Next: Distribution and publishing →