evo-subagent

English | 简体中文

evo-subagent is a DeepSeek Harness plugin for predictable subagent routing and project-scoped evolution.

It maps stable agent roles to registered provider/model pairs, remembers verified commands and lessons for each role, and keeps every project's agent knowledge isolated.

Features

• Route each agent_key through a same-named Markdown binding.
• Validate the exact provider/model pair before creating a child agent.
• Maintain per-agent prefercmd.md and memory.md knowledge files.
• Isolate bindings and evolution data by project workspace.
• Support fresh spawn children and context-aware fork children.
• Fall back to DSH's native model inheritance when no binding exists.
• Store no API keys, endpoints, credentials, or provider definitions.

Installation

dsh plugin add evo-subagent

Quick start

1. Open Settings → Plugins and expand evo-subagent.
2. Select a workspace and add a built-in role, or place a custom binding in its agents/ directory.
3. Choose a registered provider/model pair for each custom binding.
4. Expand an agent to review its prefercmd.md and memory.md evolution files.

Download the MP4 tutorial

Agent bindings

Create an agents/ directory in the project and add one Markdown file per role. The filename stem becomes the agent_key.

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

Each binding begins with a strict front matter block:

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

# Code reviewer
Optional role notes may follow.

The provider and model must already be registered. Matching is exact and case-sensitive.

Call the plugin tool with the corresponding key:

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

Built-in roles

Three templates are included:

A project binding with the same agent_key overrides its built-in template.

Evolution

Each project stores role-specific knowledge under:

.evo_subagent/evolution/<agent_key>/prefercmd.md
.evo_subagent/evolution/<agent_key>/memory.md

• prefercmd.md records commands that have been verified to work.
• memory.md records reusable lessons and failures to avoid.

Foreground subagents receive a bounded knowledge block. They can return new entries with:

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

Entries are deduplicated and bounded. Prefix an entry with ! to keep it at highest priority, or ? to make it compressible when the context budget is tight.

Legacy .smart_subagent/evolution data remains a read-only fallback and is copied to the new location on the next save.

Workspace management

The plugin settings card groups agents by project and lets users:

• view or collapse workspace agent lists;
• edit a custom binding's registered provider/model route;
• add a built-in role to a workspace by copying its template;
• bind one workspace-root AGENTS.md as the Main agent;
• inspect and edit each agent's evolution files.

Main-agent evolution is stored under .evo_subagent/evolution/main/. Binding and unbinding only changes the plugin-managed instruction block in AGENTS.md.

Tool fields

Routing behavior

1. Resolve <agent_key>.md safely.
2. Parse its fenced provider and model fields.
3. Verify both values against the live model registry.
4. Start the child through the selected spawn or fork provider.

Invalid bindings fail before a child is created. Missing bindings preserve native DSH inheritance unless a built-in template matches.

Development

Requires Node.js 22 or newer.

npm test
npm run check
npm pack --dry-run

License

MIT