dsh-plugin-guide 0.1.1 → 0.2.0

package/templates/ts/README.pt.md

@@ -0,0 +1,44 @@
+# {{pkgName}}
+
+Um plugin do DeepSeek Harness (DSH) gerado com [`dsh-plugin-dev new`](https://github.com/PerryLink/dsh-plugin-guide).
+
+## Compatibility
+
+| Superfície | Estado |
+|---|---|
+| Harness | DeepSeek Harness `0.1.1-rc.2` |
+| Node | `^22.19.0 || >=24.0.0` |
+| Plataformas | Todas (ESM puro; sem código nativo, sem rede) |
+
+## What it does
+
+Registra a ferramenta `{{name}}_echo`. Ao chamá-la, responde `<greeting>: <text>`, em que `<greeting>` vem da configuração do plugin e `<text>` é o argumento.
+
+## Install
+
+```sh
+pnpm pack
+dsh plugin --profile <name> add ./{{pkgName}}-{{version}}.tgz
+dsh --profile <name> --dump-config | grep '{{pkgName}}'
+```
+
+## Configuration
+
+| Chave | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `greeting` | string | `Hello` | Prefixo da resposta echo |
+
+A configuração é validada pelo schema Schemastery `Config` em `src/config.ts`; nenhum ajuste fica fixo no código.
+
+## Development
+
+```sh
+pnpm install
+pnpm run typecheck
+pnpm test
+pnpm run build
+```
+
+## License
+
+[Apache License 2.0](LICENSE) © {{year}} {{pkgName}} contributors.

package/templates/ts/README.zh.md

@@ -0,0 +1,44 @@
+# {{pkgName}}
+
+由 [`dsh-plugin-dev new`](https://github.com/PerryLink/dsh-plugin-guide) 脚手架生成的 DeepSeek Harness（DSH）插件。
+
+## Compatibility
+
+| 项目 | 状态 |
+|---|---|
+| Harness | DeepSeek Harness `0.1.1-rc.2` |
+| Node | `^22.19.0 || >=24.0.0` |
+| 平台 | 全部（纯 ESM；无原生代码、无网络） |
+
+## What it does
+
+注册 `{{name}}_echo` 工具。调用它时返回 `<greeting>: <text>`，其中 `<greeting>` 来自插件配置，`<text>` 是入参。
+
+## Install
+
+```sh
+pnpm pack
+dsh plugin --profile <name> add ./{{pkgName}}-{{version}}.tgz
+dsh --profile <name> --dump-config | grep '{{pkgName}}'
+```
+
+## Configuration
+
+| 键 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `greeting` | string | `Hello` | echo 回复的前缀 |
+
+配置由 `src/config.ts` 中的 Schemastery `Config` 模式校验；没有任何硬编码可调参数。
+
+## Development
+
+```sh
+pnpm install
+pnpm run typecheck
+pnpm test
+pnpm run build
+```
+
+## License
+
+[Apache License 2.0](LICENSE) © {{year}} {{pkgName}} contributors.

package/templates/ts/cordis.patch.yml

@@ -0,0 +1,10 @@
+# {{pkgName}} bundle layer: register the scaffolded plugin as a bundle row.
+# This file is the `dsh.bundle.patch` layer (see package.json#dsh.bundle.patch).
+# Layer semantics: a YAML array of row verbs; `insert` adds plugin rows to the
+# composed config. A row's `id` must be unique within the layer stack; `name`
+# resolves the plugin module through the installed package (package.json#main).
+- insert:
+    # `id`: stable row identifier used by later layers to override this row.
+    - id: {{pkgName}}
+      # `name`: the module the loader imports; resolves to this package entry.
+      name: {{pkgName}}

package/templates/ts/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "{{pkgName}}",
+  "version": "{{version}}",
+  "description": "A DeepSeek Harness (DSH) plugin scaffolded by dsh-plugin-dev.",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib",
+    "cordis.patch.yml"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepare": "tsdown"
+  },
+  "dependencies": {
+    "tsdown": "^0.22.14",
+    "typescript": "^5.9.3"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-tools": ">=0.1.0-rc.8 <0.2.0",
+    "@deepseek-ai/schemastery": "^3.18.0",
+    "@types/node": "^22.20.1",
+    "vitest": "^3.2.7"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-tools": ">=0.1.0-rc.8 <0.2.0",
+    "@deepseek-ai/schemastery": "^3.18.0"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "packageManager": "pnpm@11.7.0",
+  "license": "Apache-2.0"
+}

package/templates/ts/src/config.ts

@@ -0,0 +1,12 @@
+import Schema from '@deepseek-ai/schemastery'
+
+// Tunable configuration must be a Schemastery Schema, never a plain object:
+// the harness validates it at load time and fails loud on invalid values, and
+// every key can be changed from cordis.yml without editing code (guide §3.6).
+export interface Config {
+  greeting: string
+}
+
+export const Config: Schema<Config> = Schema.object({
+  greeting: Schema.string().default('Hello').description('Greeting prefix for the echo tool.'),
+})

package/templates/ts/src/index.ts

@@ -0,0 +1,36 @@
+import type { Context } from '@deepseek-ai/cordis'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { Config } from './config'
+import type { Config as ConfigShape } from './config'
+
+export const name = '{{pkgName}}'
+export const inject = ['tools']
+
+// Re-export the schema so the loader can validate this plugin's config.
+export { Config }
+
+/** Pure greeting builder kept separate from the tool so tests stay keyless. */
+export function buildGreeting(greeting: string, text: string): string {
+  return `${greeting}: ${text}`
+}
+
+// Every registration is an effect: `ctx.tools.register` returns the disposer that
+// removes the tool on unload, so the plugin stays hot-reloadable (guide §3.3).
+export function apply(ctx: Context, config: ConfigShape): void {
+  ctx.tools.register(
+    defineTool({
+      name: '{{name}}_echo',
+      description: 'Echo a greeting back to the caller.',
+      parameters: {
+        text: { type: 'string', required: true, description: 'Text to echo.' },
+      },
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => [{ type: 'text', text: value }],
+      },
+      async execute(args) {
+        return buildGreeting(config.greeting, args.text)
+      },
+    }),
+  )
+}

package/templates/ts/tests/index.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest'
+import { buildGreeting } from '../src/index'
+
+describe('{{pkgName}}', () => {
+  it('builds a greeting from the configured prefix', () => {
+    expect(buildGreeting('Hello', 'world')).toBe('Hello: world')
+  })
+
+  it('keeps the text verbatim after the prefix', () => {
+    expect(buildGreeting('Hi', 'a b:c')).toBe('Hi: a b:c')
+  })
+})

package/templates/ts/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "strict": true,
+    "noImplicitAny": true,
+    "skipLibCheck": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true
+  },
+  "include": ["src", "tests"]
+}

package/templates/ts/tsdown.config.mjs

@@ -0,0 +1,15 @@
+import { defineConfig } from 'tsdown'
+
+// tsdown bundles src/index.ts into lib/index.js (ESM) and emits lib/index.d.ts.
+// It is also the self-contained `prepare` script for git installs: no project
+// references, no type checking (see guide §7.1 "build-script catch").
+export default defineConfig({
+  entry: { index: 'src/index.ts' },
+  format: ['esm'],
+  platform: 'node',
+  target: 'node22',
+  dts: true,
+  clean: true,
+  sourcemap: false,
+  outDir: 'lib',
+})

package/templates/ts/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    include: ['tests/**/*.test.ts'],
+    environment: 'node',
+  },
+})