前言¶
DeepSeek Harness (DSH) 的核心设计理念是“一切皆插件”，这使得生态扩展非常灵活。但在实际开发中，子代理（Subagent）的路由往往缺乏确定性，且项目级知识（如常用命令、历史教训）容易散落在各处，导致复用困难。
evo-subagent 是一款由 ZekaiShi 维护的 DSH 插件。它解决了上述问题：通过将稳定的代理角色映射到已注册的提供者/模型组合，确保路由可预测；同时维护每个角色的 prefercmd.md（偏好命令）和 memory.md（记忆教训），使知识在项目范围内得到隔离和复用。
安装与前置要求¶
在安装之前，请确保你的环境满足以下条件：
* DeepSeek Harness 版本：0.1.5-rc.3 或更新
* Node.js 版本：>= 24.2.0
安装命令如下：
dsh plugin add evo-subagent
核心功能¶
该插件提供以下核心能力：
* 确定性路由：根据 agent_key 自动路由到同名的 Markdown 绑定文件。
* 参数验证：在创建子代理前，严格校验提供者与模型的组合。
* 知识演进：为每个角色维护 prefercmd.md 和 memory.md 文件。
* 项目隔离：将绑定关系和演进数据隔离在各自的项目工作区中。
* 启动模式：支持全新的 spawn 子代理和上下文感知的 fork 子代理。
* 降级机制：当没有绑定文件时，回退到 DSH 原生的模型继承机制。
* 零凭证存储：插件本身不存储 API 密钥、端点或提供者定义。
典型用法：代理绑定与调用¶
在项目根目录下创建 agents/ 目录，并为每个角色添加一个 Markdown 文件。文件名（不含扩展名）将作为 agent_key。
project/
├─ agents/
│ ├─ code-reviewer.md
│ └─ researcher.md
└─ .evo_subagent/
└─ evolution/
绑定文件必须包含严格的 Front Matter 块，指定提供者和模型（需在 DSH 中已注册，且匹配严格区分大小写）：
---
provider: deepseek-official
model: deepseek-v4-flash
---
# Code reviewer
Optional role notes may follow.
调用插件工具时，传入对应的 key：
{
"agent_key": "code-reviewer",
"description": "Review the implementation",
"prompt": "Report correctness, security, and test coverage issues.",
"run_in_background": false
}
插件内置了三个角色模板：code-reviewer（严重性排序的代码审查）、researcher（基于证据的调查）和 wps-worker（办公文档生产）。如果项目中定义了同名绑定，将覆盖内置模板。
进阶：演进知识与技能¶
每个项目在 .evo_subagent/evolution/<agent_key>/ 目录下存储角色的演进知识。
prefercmd.md：记录经过验证的命令。memory.md：记录可复用的教训和需要避免的错误。
前台子代理会收到一个知识块，若需要返回新条目，可使用以下格式：
[[EVOLUTION]]
prefercmd:
- pnpm test
memory:
- Do not use --force in CI.
[[/EVOLUTION]]
插入条目时，可在行首添加前缀：
* !：保持最高优先级。
* ?：在上下文预算紧张时允许压缩。
插件还随安装注册了三个 DSH 兼容的技能（需确保 DSH 的技能注册表和工具已启用）：
* /evo-route-doctor：诊断意外的路由或无效的提供者/模型对。
* /evo-memory-review：审查角色的 prefercmd.md 和 memory.md，检查过时或冲突的知识。
* /evo-delegation-guide：选择现有角色并准备一个范围化的子代理任务。
路由行为¶
插件的路由逻辑遵循以下步骤：
1. 安全解析 <agent_key>.md。
2. 解析其 fenced 的 provider 和 model 字段。
3. 在实时模型注册表中验证这两个值。
4. 通过选定的 spawn 或 fork 提供者启动子代理。
如果绑定无效，子代理在创建前就会失败。如果缺少绑定，则保留原生 DSH 继承，除非内置模板匹配。
注意事项¶
- 插件以当前 DSH 进程的权限运行，安装前建议检查源码与许可证。
- 提供者和模型必须已经在 DSH 中注册（精确且区分大小写的匹配）。
- 旧版
.smart_subagent/evolution数据作为只读后备方案保留，并在下次保存时复制到新位置。
总结¶
evo-subagent 通过将代理角色、路由逻辑与项目级知识演进解耦，为 DSH 提供了一种结构化管理子代理的方式。无论是通过命令行插件安装，还是集成到现有工作流中，它都能帮助开发者保持子代理行为的可预测性。
