Introduction to the DeepSeek Harness Plugin: dsh-kokoro

Introduction¶

The plugin ecosystem of DeepSeek Harness (DSH) is designed to extend capabilities through modularization. dsh-kokoro is an HTTP client plugin for a local Kokoro TTS service. It does not contain any model weights (ONNX, .pt, or voice bins) and exists only as a connector and parameter validation layer. Developers use it to send text to a local server and receive the path to a generated WAV file, thereby enabling text-to-speech functionality within the DSH environment.

Core Positioning¶

• Plugin name: jwilson411/dsh-kokoro
• Maintainer: jwilson411
• Functional role: HTTP TTS client plugin; registers the kokoro_tts tool.
• Core logic: POST text to a local Kokoro server and return the path to a WAV file.
• Characteristics: No weight data, no playback/mixing/caching, and no API key authentication.

Installation and Enablement¶

Installing this plugin requires a DeepSeek Harness environment that already has the web profile configured.

dsh plugin --profile web add github:jwilson411/dsh-kokoro

After installation, the plugin depends on @deepseek-ai/dsh-tools (recommended version ^0.1.1-rc.2) and @deepseek-ai/cordis. The system requires Node.js version 22.14.0 or higher.

Configuration and Usage¶

The plugin itself contains no model data and must connect to a running kokoro-tts-api server.

Connecting to a Local Server¶

The plugin’s default base URL is http://127.0.0.1:8000, although the server listens on port 8765 by default. Therefore, you need to explicitly configure the connection address.

There are two configuration methods, listed from highest to lowest priority:
1. Profile configuration: Set baseURL in the configuration line in cordis.patch.yml.
2. Environment variable: Set DSH_KOKORO_BASE_URL.

Example:

# dsh.profile.bundles 配置示例
- id: kokoro
  config:
    baseURL: http://127.0.0.1:8765

Starting the server:
Before using the plugin, start the corresponding Kokoro TTS API server.

KOKORO_PORT=8765 make run

After startup, you can perform a health check:

curl -s http://127.0.0.1:8765/health

Stub Mode (Testing Without a Server)¶

If no server is running or if you are debugging, you can enable Stub mode. In this mode, no network requests are made; instead, a silent WAV file is generated to validate the call flow.

KOKORO_STUB=1

Tool Registration and Parameters¶

The Cordis tool ID registered by the plugin is kokoro. It injects the tools dependency.

Tool: kokoro_tts¶

This tool accepts the following parameters:

Supported voice list (19 total):
- am_ series (American male voice): michael, adam, liam, eric, james, william, caleb, david, ethan
- bm_ series (British male voice): daniel, george, lewis, oliver
- af_ series (American female voice): heart, nova, sarah, bella
- bf_ series (British female voice): emma, isabella

Return Value¶

On successful invocation, the tool returns a JSON object containing the file path and related metadata:

{
  "path": "/tmp/dsh-kokoro/kokoro-am_michael-uuid.wav",
  "voice": "am_michael",
  "speed": 1.0,
  "bytes": 122444,
  "text_chars": 41,
  "plugin": "dsh-kokoro"
}

Notes¶

1. File paths and permissions:

   • The default output directory is os.tmpdir()/dsh-kokoro.
   • The directory permissions are 0700, and the file write permissions are 0600.
   • The plugin does not automatically clean up generated temporary files; they are managed by the operating system or the user.
   • The plugin does not support custom output paths or file names, to prevent abuse of file write permissions.

2. Request limitations:

   • Requests do not follow redirects.
   • The response Content-Type must be audio/*, and the first 12 bytes must be a RIFF/WAVE header; otherwise, an error KOKORO_BAD_AUDIO is raised.

3. Timeouts and size limits:

   • The default timeout is 30 seconds (configurable).
   • The default maximum response size is 10 MiB (configurable).

4. Headless mode:

   • You can also import createKokoroTtsTool directly in a Node.js script for headless invocation.

This plugin is suitable for scenarios where you need to quickly integrate a local lightweight TTS capability into a DeepSeek Harness environment, without maintaining large model files in the DSH repository.