dsh-plugin-dev

DSH Plugin Dev

DSH Plugin Development Guidance Skill (merged and absorbed from dsh-plugin-lint on 2026-09-29: development mainline + mechanical review in one). Sources of accumulation: full-process development实测 in the dsh-plugins repository (real DSH Desktop 2.0.15 / embedded runtime 0.1.7-rc.2, five isolated load experiments, independent review and fixes across 14 PRs) + development实测 during dsh-contract-copilot 0.1.2.

This skill does not replace the implementer: when creating a plugin, do a design pre-check first, then come back after implementation for formal acceptance—the reviewer and the producer do not share the same responsibility.

Companion files

• scripts/lint.mjs → mechanical review layer (version-aware, rule list below)
• scripts/test-lint.mjs → self-test (self-contained fixture, proving each rule catches invalid samples and lets valid controls pass)
• config/harness-path.example.yaml → copy as config/harness-path.local.yaml fill in the local harness repository path (do not commit)
• templates/plugin-quality-report.md → report template for formal review (conclusions carry NOT_VERIFIED semantics)

Dependencies

• Node ≥ 18.6 (lint.mjs uses node:module.isBuiltin), no third-party packages—the script works out of the box.
• harness traceability requires a local copy of the DSH source repository; when all three are missing, version-related checks are marked NOT_VERIFIED (the process does not crash).local Desktop embedded runtime（/Applications/DSH Desktop.app/.../node_modules/@deepseek-ai/) is another source of truth; use the two for comparison.

Development path

1. Determine the form: plugin identity (package.json name + dsh.bundle.patch → cordis.patch.yml, insert row id/name both string), half-body scope (Host-only first, then client), service dependencies (inject—plugins with missing hard dependencies wait and do not activate), zero-dependency principle (@deepseek-ai/* is treated as a host external). Key points are in host-plugin-essentials。Pi plugin DSH-ification starter slice(three-plugin empirical evidence in PR #37): create a new packaging layer trio (package.json/patch/index.mjs, Pi source unchanged and not imported) + bizlink consumer (owner kind namespace) + self-check chain (assert only its own namespace)—mock-level first, batch load verification into the user window.After the starter slice, domain migration follows porting-semantics: source code de-flopi-candidate to find the full set, semantic provenance anchored by line numbers, deviations allowed only in a stricter direction, external IO uniformly injected through seams + fail-closed by default (empirical evidence in PR #42/#45/#46/#49/#51).
2. Write the Host half-body: hand-write an ESM function plugin (name/inject/apply named exports); when there is legacy CJS source in the same directory,do not declare type: module, use entry .mjs(tested combination regression);ctx.provide + ctx.logger.info startup marker + ctx.effect return a disposer. For type lookup, search first dsh-tool-cordis/lib/types/api-catalog.js and the README.zh.md of each package—the embedded tree .d.ts has been stripped; not finding it in the package lib export surface ≠ missing from the whole tree。
3. Connect to business logic: session state uses projection (projection-cookbook: register requires stateVersion, notifications go only through wire, the real turn id is numeric); business object↔session association goes through shared services (dsh-bizlink precedent: owner performs optimistic concurrency at the authority of revision);For model invocation and all common capabilities, first check official sources for reuse（official-capabilities: directory + verification method; verified ctx.llm is the only supported model invocation entry point, do not build your own).
4. Isolated loading verification: follow desktop-load-and-isolation to create an experimental profile (a GUI profile must directly contain @deepseek-ai/dsh-web-app; official bundles are resolved from the installation anchor, local plugins only need to be symlinked for zero-materialization loading),DSH_HOME isolated startup, find activation markers in host logs, stepwise exit via SIGTERM, restore production (profile-selection snapshot/restore).
5. Host-level verification: all-green mocks ≠ host usability — verify in turn the real cordis ctx proxy (reading an undeclared inject property throws → use ctx.getfor optional services), domain schema validation only at the open boundary, and regression cases where the write path must pass real domain validation (to prevent best-effort error swallowing from causing silent failures). For the headless verification entry point and evidence discipline, see pitfalls-logthe "Host Verification and Evidence Discipline" section (each round written to disk under a different name, driver/dump mutually corroborated at the same commit, gate-order assertions confirm the previous gate was not short-circuited, counters must be truly injected, file-level ≠ record-level, offline stub ≠ network failure).
6. Review and write-back: mock ctx integration test (real dual-plugin chaining) → mechanical review (next section) → independent review (role separation) → loading evidence bound to candidate. Write back pitfalls to pitfalls-log, write back version migration differences to harness-facts。

Mechanical review (scripts/lint.mjs）

node skills/dsh-plugin-dev/scripts/lint.mjs <插件目录> --harness-root <DSH 源码仓库>
node skills/dsh-plugin-dev/scripts/test-lint.mjs   # 自测，退出码 0 = 全部规则自证有效

harness root resolution priority:--harness-root parameter → DSH_HARNESS_ROOT environment variable → config/harness-path.local.yaml。--json append machine-readable line; exit code = number of FAILs. Rule sections: §0 harness provenance (version/commit/module table)｜§1 package.json version drift｜§2 dsh.bundle｜§3 exports entry｜§4 dsh.client (inject target declaration, external self-reference/out-of-bounds)｜§5 client artifacts (banner/footer, bare require ↔ module table, build external reconciliation)｜§6 theme variable declaration set reconciliation｜§7 typed locale and CJK hardcoding｜§8 hygiene｜§9 documentation version residue.

Mode	Timing	Required actions
Design pre-check	Before writing code	go through development-standards contract section + this SKILL's pitfalls; trace event/slot names first
Quick review	Third-party/draft	Mechanical + factual + contract; conclusions carry NOT_VERIFIED
Formal acceptance	Before release/claiming completion	All + candidate-bound evidence (commit + clean profile install + boot without errors + real tool invocation + browser rendering screenshot; missing any one → NOT_VERIFIED)

Review work principles (inherited from lint 1.0.0): mechanical first, then semantic; version-aware without frozen assumptions; every API/event/slot reference to the harness must be traced to a source path (real case: documentation described a nonexistent CLI flag and agent/post-step event); do not trust self-reported PASS; objective defects fail-closed, semantic uncertainty yields only WARN/NOT_VERIFIED, never a false PASS.

Boundaries that must be upheld

• Version matching: the source/documentation version relied on for development must match the runtime embedded in the local Desktop (npm latest = embedded version;next is pre-release with no desktop embedding). Misaligned research must be re-verified against the actual artifact.
• Production isolation: experiments use only DSH_HOME Isolated directory + synthetic data; do not read production sessions/credentials/settings; snapshot before touching shared userData and restore afterward; notify the user before and after shutting down production instances.
• Exit sequencing: after SIGTERM,verify step by step that the process has truly disappearedthen run the restore command—the singleton lock will forward a premature open -a to an experimental instance that has not fully died.
• Do not fake verification: mock smoke test ≠ host verification ≠ GUI verification, state the three layers separately; host logs are authoritative evidence for the Host half; mark missing ones as NOT_VERIFIED.
• Combined regression awareness: a single-branch diff cannot see the interactions of shared-directory declarations (such as the type field of package.json in the same directory)—such changes must have all existing tests rerun in full before and after merge.

Deliverables and completion line

One development slice: structural validation → mock integration tests → (when conditions permit) isolated loading of host log evidence → independent review disposition → documentation and pitfalls write-back. Release acceptance follows the formal mode in the previous section. Mark missing loading evidence as NOT_VERIFIED; do not claim "already usable on a real host".

References

• Official capability reuse catalog: before building a custom common layer, first check the official verification methods (source anchoring/package README/consumer examples) + the seven verified items (ctx.llm model invocation,ctx.jobs long tasks within a session,packages/schedule persistent scheduling,ctx.tools model tool registration,ctx.storageDomain persistent KV—the latter two include zero-dependency implementation approaches; the plugin Config/settings form mechanism and domain/changed storage-domain change events—including the three hidden doors of handwritten schema and in-process boundaries) and the to-be-checked list.
• Porting semantic discipline: flopi-candidate source location patterns, line-number anchoring, deviations may only be stricter, do not fabricate unverified branches, external IO injection seams (fail-closed), concurrent branch test counts;six rules for Python→JS cross-language translation(zero-width lookbehind assertions cannot be downgraded to consuming prefixes, URL encoding differential comparison, content hashes cannot serve as revision numbers, the round/date/sort trio, replacement-string capture groups are semantics, declare or eliminate differences).
• Host plugin essentials and version differences: form, loading resolution, zero-dependency and schema strategy, api-catalog type lookup, 0.1.2→0.1.7 migration table.
• Session projection Cookbook: sessionProjections contract, wire notifications, numeric turnId, watermark and fork.
• Desktop loading and isolation experiments: profile workspace, loading proof, DSH_HOME/singleton lock/SIGTERM/wizard state/renderer known issues.
• 0.1.7-rc.2 fact snapshot: version matrix, embedded package quick reference, list of differences from the 0.1.2 specification.
• Pitfall log: measured pitfalls indexed by symptom (including sources), accumulated across versions.
• 0.1.2 development specification (historical authority): full specification of plugin form/distribution/tools/events/slot/client artifact contract/theme/locale + 14 measured pitfalls and harness reference file index.
• Evidence repository:maoscripts/dsh-plugins(evidence and PR review fix records, the original source of this Skill's facts).

Known limitations (inherited lint)

• Regex-level parsing does not build an AST: complex patch structures and nested dictionaries are escalated to manual handling (WARN/NOT_VERIFIED, no false PASS).
• The artifacts bare builtin require and JSX CJK detection are heuristics and require manual confirmation.
• The platform module table/purity regex/theme variable set are all current facts read at runtime from --harness-root , with no version numbers preset.
• Do not automatically execute the target repository's build/test (the report should list the commands to run).