@your-scope/dsh-plugin-template
用于 DeepSeek Harness 的独立 Cordis 插件模板
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:omdsh-dev/plugin-template#2803a03858e914101be93a2f51558717af37303dPlugin Template 以 @your-scope/dsh-plugin-template 发布，当前版本为 0.0.1。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
English | 中文
A self-contained standalone repository template for an ESM Cordis plugin. Every source file, compiler setting, test fixture, contributor instruction, skill, and build helper used by the repository is inside this directory; every development input resolves below this repository root.
Normal npm dependencies are resolved from the package registry. A DSH host is a runtime consumer of the finished package, not a source or build input.
.
├── .agents/skills/ # Repository-local plugin development workflow
│ ├── dsh-plugin-development/ # End-to-end coordinator
│ └── dsh-plugin-*/ # Plan, scaffold, implement, compose, test, release
├── docs/
│ └── dsh-plugin-contracts.md # Shared local contract for all plugin skills
├── patches/
│ └── README.md # Dependency and DSH-host patch contract
├── scripts/
│ ├── extract-patch.mjs # Config-driven host patch regeneration (see patches/README.md)
│ ├── patch.sh # Idempotent host patch application
│ └── verify-self-contained.mjs # Repository-boundary and skill metadata check
├── src/
│ ├── README.md # Growth rules for services and feature modules
│ ├── config.ts # Serializable schema and resolved defaults
│ ├── index.ts # Loader-facing function-plugin namespace
│ ├── invariant.ts # Package-owned invariant companion
│ └── runtime.ts # Fakeable host boundary and Cordis activation
├── tests/
│ ├── README.md # Harness, feature-test, and snapshot conventions
│ ├── harness.ts # Shared real-Cordis test mount
│ ├── plugin.spec.ts # Loader export and activation tests
│ └── snapshots/
│ └── README.md # Optional product-visible fixture contract
├── .gitignore # Generated artifact exclusions
├── AGENTS.md # Repository-local contributor rules
├── LICENSE # Template license
├── README.md # Repository and usage contract
├── cordis.patch.yml # Profile bundle contribution
├── package.json # Exports, peers, dsh.bundle.patch
├── pnpm-lock.yaml # Reproducible registry dependency graph
├── pnpm-workspace.yaml # Package-manager and optional patch policy
├── tsconfig.json # Strict no-emit typecheck project
├── tsconfig.vitest.json # Source-plane test typecheck project
├── tsdown.config.ts # Direct source-to-runtime/declaration build
└── vitest.config.ts # Test runner configuration
The baseline mirrors the scalable first-level split used by larger DSH plugins while keeping product behavior minimal:
src/index.ts owns the Loader namespace;src/config.ts owns the serializable schema and direct-call defaults;src/runtime.ts owns fakeable host boundaries and Cordis activation;tests/harness.ts owns the shared real-Cordis test mount;src/<feature>/ directories;tests/snapshots/;patches/: pnpm patchedDependencies for exact registry versions, self-contained diffs against the DSH host when the plugin needs host source changes.Directories such as Turtle UI's chat, components, and extension areas describe that product, not the DSH plugin contract. Create equivalent feature directories only when the new plugin owns those capabilities. See src/README.md, tests/README.md, tests/snapshots/README.md, and patches/README.md for the local rules.
package.json, src/index.ts, src/config.ts, src/runtime.ts, src/invariant.ts, tests/plugin.spec.ts, cordis.patch.yml, the TypeScript package metadata, README.md, and AGENTS.md.@your-scope/dsh-plugin-template and plugin ids only in those identity owners. Do not perform a global replacement inside .agents/skills/; its generic examples and marker checks must remain reusable.description, LICENSE, and cordis.patch.yml.node_modules.src/runtime.ts, moving cohesive capabilities into project-specific src/<feature>/ directories as needed. Keep src/index.ts limited to Loader metadata and public re-exports, and scope registrations through ctx.effect(), ctx.on(), or registry disposers.docs/dsh-plugin-contracts.md. Do not add local-path link: or file: dependencies.private to false only when the package's public dependencies and distribution artifacts are ready.Do not add a default export to a function plugin. Cordis Loader unwraps exports.default ?? exports; a stray default export discards namespace exports such as inject, Config, and apply.
DSH discovers the repository-local workflow under .agents/skills/. Start with dsh-plugin-development for the complete sequence, or invoke one stage directly:
| Skill | Purpose |
|---|---|
dsh-plugin-plan | Decide plugin form, dependencies, configuration, invariant, composition, and evidence. |
dsh-plugin-scaffold | Instantiate and baseline-verify a new repository from this template. |
dsh-plugin-implement | Implement lifecycle-safe Cordis behavior, metadata, docs, and invariants. |
dsh-plugin-compose | Install the bundle into an isolated profile and prove effective activation. |
dsh-plugin-test | Verify Loader exports, behavior, disposal, composition, snapshots, and artifacts. |
dsh-plugin-release | Check local, Git, or npm distribution readiness without publishing implicitly. |
Keep these directories when copying the template so future sessions rooted in the plugin repository retain the same workflow.
Run every command from this directory:
pnpm install
pnpm run verify:self-contained
pnpm run typecheck
pnpm test
pnpm run build
pnpm install resolves only the dependencies declared by this package. verify:self-contained rejects filesystem dependency specs, compiler paths that leave the repository, external or broken Markdown links, absolute workstation paths, and malformed bundled skill metadata. typecheck checks both the source project in tsconfig.json and the source-plane tests in tsconfig.vitest.json against the local strict compiler baseline. build compiles the host entries directly from src/ and emits ready-to-pack runtime JavaScript plus declarations into lib/; it does not run an install-time lifecycle build.
The release artifact is built from src/ before packing. Profile or consumer installation uses the ready-made lib/ output and does not run prepare; pnpm pack --dry-run --json verifies the final archive contents.
Two GitHub Actions workflows ship with the template:
.github/workflows/ci.yml — every push to main and every pull request: install with the frozen lockfile, verify:self-contained, typecheck, tests, and build..github/workflows/release.yml — every push to main: verifies, typechecks, tests, builds, packs the ready-made tarball (pnpm pack), and publishes it to a GitHub Release tagged v<version> from package.json. Bump version to cut a new release; re-pushing the same version refreshes that release's artifact.The package manifest declares the bundle patch:
{
"dsh": {
"bundle": {
"patch": "./cordis.patch.yml"
}
}
}
A DSH host may install this package into a profile and apply cordis.patch.yml over its own runtime composition. That host integration is intentionally outside this repository's build and test inputs. The patch composes plugins; it does not alter host source, compiler settings, build scripts, or catalogs.
The invariant companion uses a narrow local interface for the host's invariants service. This keeps the package build independent of the host's private source package while preserving the runtime registration used by a DSH profile.
This template demonstrates a function plugin and therefore named exports:
// src/index.ts
export const name = 'plugin-template'
export const inject: string[] = []
export { Config } from './config.ts'
export { apply } from './runtime.ts'
// src/config.ts
export interface Config { /* serializable fields */ }
export const Config: z<Config> = z.object({ /* validation and defaults */ })
// src/runtime.ts
export function apply(ctx: Context, config: Config): void { /* effects */ }
A service provider instead normally default-exports its Service subclass. Do not mix the two forms.
Before considering packed or GitHub Release distribution, build and inspect the final archive:
pnpm run verify:self-contained
pnpm run typecheck
pnpm test
pnpm run build
pnpm pack --dry-run --json
The final package must contain every runtime and declaration file named by main, types, exports, and files. Keep private: true until the package's DSH host peers are available through the selected distribution channel.
The included test proves Loader-safe ESM exports and schema-resolved activation. Replace the activation assertions with observable behavior and disposal assertions for every registry contribution. Product-visible plugins should add a real Loader/profile composition test in the consuming DSH application rather than relying only on hand-mounted unit tests.