Introduction

The core design philosophy of DeepSeek Harness (DSH) is “everything is a plugin,” which makes ecosystem extension very flexible. However, in actual development, subagent routing often lacks determinism, and project-level knowledge (such as common commands and past lessons) tends to be scattered, making reuse difficult.

evo-subagent is a DSH plugin maintained by ZekaiShi. It solves the above issues: by mapping stable agent roles to registered provider/model combinations, it ensures predictable routing; it also maintains each role’s prefercmd.md (preferred commands) and memory.md (memorized lessons), so knowledge remains isolated and reusable within the project scope.

Installation and Prerequisites

Before installing, ensure your environment meets the following requirements:
* DeepSeek Harness version: 0.1.5-rc.3 or later
* Node.js version: >= 24.2.0

The installation command is:

dsh plugin add evo-subagent

Core Features

The plugin provides the following core capabilities:
* Deterministic routing: Automatically routes to the same-named Markdown binding file based on agent_key.
* Parameter validation: Strictly validates the provider and model combination before creating a subagent.
* Knowledge evolution: Maintains prefercmd.md and memory.md files for each role.
* Project isolation: Isolates bindings and evolution data within their respective project workspaces.
* Launch modes: Supports fresh spawn subagents and context-aware fork subagents.
* Fallback mechanism: Falls back to DSH’s native model inheritance mechanism when no binding file exists.
* Zero credential storage: The plugin itself does not store API keys, endpoints, or provider definitions.

Typical Usage: Agent Binding and Invocation

Create an agents/ directory at the project root and add a Markdown file for each role. The file name (without extension) is used as the agent_key.

project/
├─ agents/
│  ├─ code-reviewer.md
│  └─ researcher.md
└─ .evo_subagent/
   └─ evolution/

Binding files must include a strict Front Matter block specifying the provider and model (they must be registered in DSH, and matching is strictly case-sensitive):

---
provider: deepseek-official
model: deepseek-v4-flash
---

# Code reviewer
Optional role notes may follow.

When invoking the plugin tool, pass the corresponding key:

{
  "agent_key": "code-reviewer",
  "description": "Review the implementation",
  "prompt": "Report correctness, security, and test coverage issues.",
  "run_in_background": false
}

The plugin includes three built-in role templates: code-reviewer (severity-ranked code review), researcher (evidence-based investigation), and wps-worker (office document production). If a project defines a binding with the same name, it overrides the built-in template.

Advanced: Evolution Knowledge and Skills

Each project stores role evolution knowledge under the .evo_subagent/evolution/<agent_key>/ directory.

  • prefercmd.md: Records verified commands.
  • memory.md: Records reusable lessons and mistakes to avoid.

Foreground subagents receive a knowledge block. To return new entries, you can use the following format:

[[EVOLUTION]]
prefercmd:
- pnpm test
memory:
- Do not use --force in CI.
[[/EVOLUTION]]

When inserting entries, you can add a prefix at the beginning of the line:
* !: Keep the highest priority.
* ?: Allow compression when the context budget is tight.

The plugin also registers three DSH-compatible skills upon installation (ensure DSH’s skill registry and tools are enabled):
* /evo-route-doctor: Diagnose unexpected routing or invalid provider/model pairs.
* /evo-memory-review: Review a role’s prefercmd.md and memory.md, checking for stale or conflicting knowledge.
* /evo-delegation-guide: Select an existing role and prepare a scoped subagent task.

Routing Behavior

The plugin’s routing logic follows these steps:
1. Safely parse <agent_key>.md.
2. Parse its fenced provider and model fields.
3. Validate these two values against the live model registry.
4. Launch the subagent through the selected spawn or fork provider.

If the binding is invalid, the subagent fails before creation. If a binding is missing, native DSH inheritance is preserved, unless a built-in template matches.

Notes

  • The plugin runs with the permissions of the current DSH process. It is recommended to review the source code and license before installing.
  • The provider and model must already be registered in DSH (exact, case-sensitive matching).
  • Legacy .smart_subagent/evolution data is preserved as a read-only fallback and copied to the new location on the next save.

Summary

By decoupling agent roles, routing logic, and project-level knowledge evolution, evo-subagent provides a structured way to manage subagents in DSH. Whether installed via the command-line plugin or integrated into existing workflows, it helps developers keep subagent behavior predictable.