dsh-plugin-greet

dsh-plugin-greet

English | 简体中文

A beginner-friendly, installable DeepSeek Harness plugin that demonstrates bundle distribution, profile composition, plugin configuration, the typed defineTool() API, structured output, validation, testing, and a real model-driven tool call.

This is a community example, not an official DeepSeek AI plugin. DeepSeek Harness is currently in Developer Preview, so future releases may require compatibility updates.

What you will learn

This repository keeps the implementation in one small entry file so that a new plugin author can follow the complete path:

User prompt
  → model chooses the greet tool
  → argument schema checks the shape
  → execute validates and normalizes values
  → the tool returns structured data
  → output.render creates model-facing text
  → the model writes its final response

The example covers:

• exporting a validated plugin Config
• injecting and using the Harness tools service
• registering a tool with the current defineTool() schema DSL
• required and optional tool arguments
• English and Chinese greetings
• friendly and formal styles
• structured canonical output with a text renderer
• actionable validation errors
• unit tests and CI packaging checks

Tool contract

The plugin registers one model-callable tool named greet.

Input

Leading and trailing whitespace is removed from name. Unknown arguments, empty names, unsupported languages, and unsupported styles are rejected with clear errors.

Output

The canonical result is structured data:

{
  "message": "Hello, Ada!",
  "name": "Ada",
  "language": "en",
  "style": "friendly"
}

output.render converts that value into the model-facing text:

Hello, Ada!

This separation lets other plugins or policies use the structured fields without making the model read raw JSON.

Greeting examples

Supported dsh versions

For dsh-plugin-greet@0.3.2, use @deepseek-ai/dsh@0.2.0-rc.2. The preview 0.2.1-alpha.1 is also verified. Compatibility is stated for these exact releases, not all 0.2.x versions.

Last checked: October 7, 2026.

Current verification covers Node.js 22.19 and 24 in CI: unit tests, installation of the packed plugin through the profile CLI, four greeting modes, invalid arguments, Web startup, launch-token login, and HTML responses. It does not include a real model request. See the passing 0.3.2 CI run.

The old Harness releases use broad upstream dependency ranges that can now resolve incompatible services. Their fresh-install failures do not prove the greeting implementation is incompatible with an already-installed old environment; those existing environments were not revalidated. For new installations, use one of the two supported releases above.

The @deepseek-ai/dsh-tools peer declaration retains historical ranges for existing installations. A version satisfying that declaration is not by itself a tested dsh compatibility guarantee. New Harness releases need another compatibility check before being added to the supported list.

To use the verified preview, replace @deepseek-ai/dsh@0.2.0-rc.2 with @deepseek-ai/dsh@0.2.1-alpha.1 consistently in the installation and launch commands below.

Install from npm

Use Node.js ^22.19.0 or >=24.0.0 and install pnpm (npm install -g pnpm@10.32.1) for profile plugin management. Development dependencies target Harness 0.2.0-rc.2; CI also verifies 0.2.1-alpha.1. The commands below pin the default release tested by this repository.

Stop any running DeepSeek Harness instance, then install the package into the web profile:

npx @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web add dsh-plugin-greet@0.3.2

Version 0.3.2 refreshes development dependencies and compatibility checks for Harness 0.2. Its greeting behavior is unchanged from 0.3.0.

This command does more than a regular npm install: it installs the package into the selected Harness profile and adds its declared bundle to the profile composition.

Before starting, confirm that the bundle is present in the final configuration:

npx @deepseek-ai/dsh@0.2.0-rc.2 --profile web --dump-config

Then start the Web UI:

npx @deepseek-ai/dsh@0.2.0-rc.2 web

Try the tool

Use the page opened by the launcher, or open the complete URL printed in the terminal, including its ?token=... query. The default port is 3080. The first visit establishes a browser session and redirects to the clean URL; opening the bare address without a valid session returns 401. Then send:

You must use the greet tool to greet Ada in a friendly English style.

The expected tool call is:

IN  { "name": "Ada", "language": "en", "style": "friendly" }
OUT Hello, Ada!

Try Chinese formal output:

You must use the greet tool to greet 小明 in formal Chinese.

Expected result:

IN  { "name": "小明", "language": "zh", "style": "formal" }
OUT 您好，小明。

The plugin does not listen for keywords such as Hello. It makes the tool available to the model, and the model decides whether to call it. Explicitly naming the greet tool makes the behavior easier to verify.

Configure the plugin

The exported configuration schema supplies these defaults:

greeting: Hello
punctuation: "!"
defaultLanguage: en
defaultStyle: friendly

To override them, restate the plugin row in a later patch layer, such as the profile's cordis.patch.yml:

- insert:
    - id: greet-tool
      name: dsh-plugin-greet
      config:
        greeting: Hi
        punctuation: "!"
        defaultLanguage: en
        defaultStyle: friendly

With that configuration, a call containing only { "name": "Grace" } returns Hi, Grace!.

greeting and punctuation customize friendly English output. Chinese and formal wording use the built-in examples shown above. defaultLanguage and defaultStyle are used only when the model omits those arguments.

Later patch layers replace the entire row configuration rather than deep-merging individual keys, so keep id, name, and the complete desired config together.

Install from GitHub

To install the current development branch:

npx @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web add \
  github:0lidaxiang/dsh-plugin-greet#master

For stable usage, prefer a published npm version, release tag, or specific commit SHA.

Install from a local checkout

Run this command from the parent directory of the repository:

npx @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web add ./dsh-plugin-greet

After changing the code, restart DeepSeek Harness and verify the tool through the chat interface.

Develop and test

Install dependencies and run the unit tests:

npm ci
npm test

Run the complete local check, including the npm package preview:

npm run check

The test suite imports the real Harness tool API and verifies configuration defaults, registration metadata, all four greeting modes, structured output rendering, whitespace normalization, invalid values, unknown arguments, and length limits. GitHub Actions runs these checks on Node.js 22.19 and 24.

Run the same compatibility checks as CI (requires pnpm and registry access):

npm run test:compat -- 0.2.0-rc.2
npm run test:compat -- 0.2.1-alpha.1

Each check installs the selected Harness into a temporary directory, runs the unit tests against it, packs this checkout, installs that tarball through the real profile CLI, and starts Web on an available loopback port. It verifies all four greetings, invalid arguments, the launch-token login flow, and the HTML response, then stops the server and removes the temporary profile. It does not call a model or use your existing profile. CI runs both Harness versions on both Node versions.

Update Cordis alongside the Harness development packages: 0.2.0-rc.2 requires Cordis ~4.0.4, while 0.2.1-alpha.1 requires ~4.0.5-alpha.1. The compatibility script reads the selected release's Cordis peer requirement from the official npm registry instead of reusing the development version. Pin matching versions of dsh-tools and dsh-system-prompt; the dsh-tools npm latest tag does not track the CLI's latest tag.

Troubleshooting

The model replies but does not call greet

Say explicitly: You must use the greet tool.... A normal greeting such as Hello does not force a tool call.

The tool is not listed

Stop the running Harness process, reinstall the plugin into the same profile, inspect --dump-config, and then restart the Web UI.

npm install dsh-plugin-greet worked, but the tool is missing

A regular npm install only adds a dependency to the current Node.js project. Use dsh plugin --profile <name> add ... to install and compose the bundle into a Harness profile.

The Web page returns 401

Open the complete launch URL printed by the current Harness process, including ?token=..., to establish a browser session. An old process's token or a bare URL in a browser without a valid session will not log you in.

Installation reports a missing Harness peer

The official profile disables automatic peer installation and resolves Harness services from the host at startup, so pnpm can report a missing peer during installation. Check the supported version below, inspect --dump-config, and restart Harness. Avoid adding a separate copy of dsh-tools to the profile to silence this warning; the plugin should use the host's service.

My configuration did not take effect

Make sure your later patch restates the row with the same id (greet-tool), the package name, and the complete config object.

A Harness source checkout stopped working after git pull

Use a supported Node.js version, refresh dependencies, and remove stale generated output before rebuilding:

nvm use 22.22.3
pnpm install --frozen-lockfile
pnpm run clean
pnpm run build
pnpm dsh --profile web --no-open

Project structure

dsh-plugin-greet/
├── .github/
│   ├── assets/social-preview.png # GitHub social preview image
│   └── workflows/ci.yml          # Tests and package checks
├── docs/
│   ├── README.zh-CN.md       # Chinese documentation
│   ├── greet-tool-result.png # README screenshot
│   └── readme-hero.webp      # Lightweight README hero
├── scripts/check-compat.mjs # Packed installation and Web compatibility check
├── scripts/fixtures/        # Tool runtime probe for the temporary Web profile
├── tests/greet.test.js       # Node.js unit tests
├── cordis.patch.yml          # Inserts the plugin into a profile
├── index.js                  # Config and greet tool implementation
├── package-lock.json         # Reproducible dependency versions
├── package.json              # Package and dsh.bundle metadata
└── LICENSE

Security and compatibility

DeepSeek Harness plugins run inside the host process. Review third-party plugin source code before installation, and prefer a pinned release tag or commit SHA.

The plugin has no network, filesystem, shell, or credential access. It uses the official @deepseek-ai/dsh-tools package for typed tool registration and @deepseek-ai/schemastery for configuration validation.

See Supported dsh versions for current support, historical verification, and known installation limitations.

License

MIT