Introduction¶

In the DeepSeek Harness (DSH) ecosystem, managing subagents typically requires writing additional configuration or scripts. This plugin solves that problem: it allows you to define agents directly using local Markdown files and register them as official DSH subagents. This provides a lightweight way to extend DSH’s capabilities, supporting background task dispatch and bidirectional follow-up.

Core Features¶

1. Markdown File as Agent Definition
   Create a .md file in the ~/.dsh/agents/ directory, where the filename is the Agent name. Frontmatter defines metadata (such as model and thinking intensity), while the body serves as the system prompt. Changes take effect immediately.

2. Breakpoint Resumption
   If a long-running task is interrupted during execution (for example, due to errors, cancellation, rate limits, or crashes), subsequent calls automatically resume from the saved progress instead of starting over from the beginning.

3. Background Dispatch and Bidirectional Follow-up
   Supports placing agents in the background while the main conversation continues. The ask_agent interface can send follow-up messages to a background agent and wait for a reply.

4. Ready-to-use Preset Agents
   The plugin includes three preset Agents: workhorse, oldfox, and rubber-duck. They are seeded only on first startup when the directory is empty, and subsequent changes will not overwrite them.

5. Based on the Official Spawn Provider
   All custom Agents are started through DSH’s official spawn provider, making them genuine dsh subagents that inherit official native capabilities for sessions, persistence, and bidirectional communication.

6. Concurrency and Depth Control
   Supports limiting concurrent behavior through configuration options such as maxActiveSubagents (maximum number of simultaneously active sub-agents, default 8) and maxDepth (maximum delegation nesting depth, default 1).

Installation and Enablement¶

This plugin requires DSH version >= 0.1.7-rc.1 (RC/stable line; the Alpha line is no longer supported).

1. Local Installation
   Clone the repository locally and mount it in the Profile:

    dsh plugin --profile tui add ~/github/dsh-subagent-registry

Restart DSH to activate the plugin.

2. NPM Installation

    npm i @aiwayds/dsh-subagent-registry

Load it in the Profile configuration using the stable ID `dsh-subagent-registry`, or mount it using a bundle patch.

Typical Usage¶

1. Direct Invocation from the Main Conversation
   Use the Agent name directly in the conversation:

    用 workhorse 把今天的发布清单整理成表格

The underlying call is `use_agent(agent: "workhorse", prompt: "…")`.

2. Asking a Background Agent
   Use ask_agent to send a message to a background agent and wait for a reply:

    ask_agent(agent: "worker", message: "…")

3. Defining a Custom Agent
   Create a file in ~/.dsh/agents/ and configure the frontmatter:

    ---
    name: my-agent
    description: "一行简介"
    model: opencode-go/deepseek-flash
    thinking: high
    ---
    You are my-agent. 这段正文作为 system prompt。

4. Configuring the Concurrency Limit
   Write the configuration in the profile patch:

    subagent: {
      maxActiveSubagents: N,
      maxDepth: M
    }

Applicable Scenarios and Notes¶

• Target Users: Developers who need to manage multiple role-based divisions of work (such as development, review, and testing), or users who want to manage AI behavior logic using plain text.
• Uninstall Method: dsh plugin --profile <name> remove @aiwayds/dsh-subagent-registry. After uninstallation, the Agent files are retained, but the use_agent / ask_agent tools are removed.
• Fallback Handling: Without this plugin, dsh-tui-pi degrades gracefully, only losing the ability to dispatch custom Agents.
• Dependency Check: Before use, ensure that the current DSH version satisfies >= 0.1.7-rc.1.

Conclusion¶

By introducing a local Markdown file mechanism, this plugin lowers the barrier to using DSH subagents while maintaining compatibility with official mechanisms. For more configuration details, refer to the documentation.