dsh-plugin-starter

English | 中文

A distributable Skill project for DSH (DeepSeek Harness) dual-face plugin development: a DSH-loadable skill file (SKILL.md) plus copy-paste templates (templates/), covering the full workflow from research, scaffolding, implementation, build, verification to GitHub release.

Layout

dsh-plugin-starter/
├── SKILL.md                    # DSH skill: full workflow + tool/route/UI development + presets + pitfalls + cheatsheet
├── templates/                  # copy-paste templates (build after replacing the package name)
│   ├── host.ts                 #   Host template — route-type (webServer.register)
│   ├── host-tool.ts            #   Host template — tool-type (ctx.tools.register(defineTool))
│   ├── client.ts               #   Client template (settings.section settings page)
│   ├── tsdown.config.ts        #   dual-target build config (__ModuleLoader__ wrapper)
│   ├── package.json            #   dsh.client + dsh.bundle declarations
│   ├── tsconfig.json
│   └── cordis.patch.yml        #   DSH install config
└── README.md

Chinese documentation lives in README.zh.md (published). SKILL.zh.md and templates-zh/ exist only in the local working copy (Chinese reference; gitignored, never published).

1. Install this repo as a DSH skill

Put this repo (or just SKILL.md) under any skill root — DSH discovers it automatically:

Skill root	Path	Scope
User	<DSH_HOME>/skills/dsh-plugin-starter/	all workspaces
Project	<projectRoot>/.dsh/skills/dsh-plugin-starter/	current project
Custom	point customSkillDirs at this repo in settings	as configured

# user-level example ($DSH_HOME defaults to ~/.dsh when unset)
git clone https://github.com/lnyanhongyan/dsh-plugin-starter "$DSH_HOME/skills/dsh-plugin-starter"

After installation, DSH loads SKILL.md automatically when the task matches its whenToUse (or you can invoke it directly with the /dsh-plugin-starter gesture in a message).

2. Scaffold a new plugin from the templates

# 1. new plugin dir, copy the templates
mkdir my-plugin && cd my-plugin
cp -r ../dsh-plugin-starter/templates/* .
mkdir -p src/client

# 2. place the Host file in src/, the Client file in src/client/
mv host.ts   src/index.ts
mv client.ts src/client/index.ts

# tool-only plugin: just the Host half, no Client half
# mv host-tool.ts src/index.ts   # (choose either host.ts or host-tool.ts; tool-type picks this one)

# 3. rename checklist: replace every @lnyanhongyan/dsh-plugin-name below with your package name

Rename checklist (3 config files + 3 source files)

Location	Replace
package.json	name → your package name (e.g. @your-namespace/dsh-my-plugin)
tsdown.config.ts	PLUGIN_ID → same as the package name
cordis.patch.yml	name → same as the package name
tsconfig.json	the key in paths → same as the package name
src/index.ts (host.ts)	route prefix /plugin-path → your route path; plugin-name → your plugin id
src/index.ts (host-tool.ts)	tool name my_tool → your tool name; rewrite description from the model's perspective
src/client/index.ts	plugin-name → your plugin id (slot id / locale namespace / log labels)

Naming: use your own npm/GitHub namespace (e.g. @lnyanhongyan/dsh-xxx); don't squat on the official @deepseek-ai namespace.

Build & install

pnpm install          # install dependencies
pnpm typecheck        # type check
pnpm build            # tsdown dual build → lib/index.mjs + lib/client.js
pnpm pack             # produce .tgz

dsh plugin --profile web add ./my-plugin   # install into DSH
dsh web --port 3081                        # restart, then verify in the settings page

3. Reference implementations

dsh-rule-manager is a complete dual-face reference:

• Host registers /rules/* routes (overview / read / write / delete / projects), manages rule files via ctx.get('fs'), requests full access through sandboxPolicy, and deletes files with fs.unlink (Windows-safe).
• Client is the "Rule Manager" settings page: ctx.slots.inject('settings.section', ...) registration, fetch() to the routes, --dsw-alias-* tokens for theming.

For tool-type plugins, see dsh-fetch-url (local plugins/ dir): ctx.tools.register(defineTool({name:'fetch_url', ...})), with output.schema enforcement, presentCall UI rendering, and cooperative cancellation (exec.signal).

4. Publish to GitHub

git init && git add . && git commit -m "feat: initial release"
# create the repository on GitHub (your account) first, then push
git remote add origin git@github.com:your-account/repo-name.git
git push -u origin master

GitHub permission note: a fine-grained token needs Contents: Read and write on the repository, or use a classic token (ghp_ prefix, repo scope).

Maintenance: this repository is maintained plan-first — structural changes ship a change proposal for review before implementation; small changes land directly, always with verification.

License

MIT