Harness Self-Evolution Plugin
让多种 Harness 平台的插件生态持续自我进化 —— 扫描 → 监控 → 识别 → 提案 → 人工审批 → 真实升级。
支持:DeepSeek Harness(首打)/ Minimax Code / ZCode / Claude Code / OpenClaw
中文
一句话定位
挂在多种 Harness 平台上的自进化插件(首打 DeepSeek Harness)。用户全程只介入一处:看提案,点同意或不同意。
最新进展(v2.4.0,2026-09-09)
| 轮次 | 提交 | 关键变化 |
|---|---|---|
| 2.4.0 | 02e1d51 |
DSH subagent 真实集成:1.0 端 dsh-runner.ts 适配 DSH 宿主编排协议,server.ts 新增 3 个 MCP 工具(get_execution_plan / report_task_result / finalize_execution),配套 371 行 DSH_INTEGRATION.md;MoonBit 端真实进程执行器由占位升级为 HARNESS_EVOLUTION_AGENT_CMD 环境变量驱动,scanner 加 list_skill_and_source_files 双收集;legacy-ts 增 41 个 test(store 状态机、server 注册、engine 映射),引入 eslint;版本元数据升 2.4.0 |
| 2.3.0 | a2381fd |
v2.3.0 收尾:monitor.mbt 缩 367 行(抽到 monitor/deep_check.mbt / monitor/flush.mbt),config.mbt 缩 197 行(抽到 types/config_helpers.mbt);ServerState::with_harness_config 统一三段配置;五处版本元数据升 2.3.0 |
| 2.2.0 | 8b9970e |
接通 scan_targets 配置孤岛:plugin.json 的 scan_targets 段真正驱动扫描根,支持 ~/... 展开,缺失/类型不符/为空都回退默认根并点名告警;新增 ScanConfig::from_plugin_json 纯解析函数和 8 个白盒用例 |
| 2.2.0 | 8b9970e |
五处版本元数据一并升 2.2.0(moon.mod / plugin.json / jsonrpc server_version / DESIGN.md 镜像 / SKILL.md frontmatter) |
| 第六轮 | b9392eb |
信号缓冲有界化(max_buffered_signals=500,溢出丢最旧);num_field 拒绝 NaN / Infinity;删除全仓零调用点的 ::at 生产构造器 |
| 第四轮 | cd2c525 |
4 真 bug 修复(tdiv floor 误用 / generate_signature 剥掉 plugin_id / factory 前后空 trim 不一致 / cooldown_hours 走裸 to_int) |
| 第五轮 | b309000 |
AgentDefStore::list 把「读不动」改告警;版本元数据补齐 2.1.0 |
| v2.1 | 0d3b0ce |
子 Agent 工厂落地:3 个 MCP 工具管理两个作用域(plugin / user)的定义文件 |
完整门禁(build.ps1 -Task all):Total tests: 347, passed: 347, failed: 0.,退出码 0,产物 bin/harness-evolution.exe 1,293,824 B,独立两跑一致。1.0 参考实现(legacy-ts/,TypeScript + Node)6 suites / 75 tests 全过,跨实现合计 422/422。
特性
- 插件扫描:解析
plugin.json/SKILL.md,评复杂度、接口清晰度、文档质量。 - 指标采集:按调用记录延迟、成功率、Token 开销;热路径不读盘,深度检查按节流间隔。
- 信号识别:强信号(用户纠正 / 连续失败 ≥ 3 / 指标下滑 > 20%)立即触发;中信号累积;弱信号只记录。
- 提案生成:八类进化提案绑定 Matt Pocock 工程原则;24 小时冷却、每会话上限 3 条、重复丢弃。
- 执行验证:状态机
pending → approved → executing → completed,非approved拒绝执行。 - 子 Agent 工厂(v2.1):3 个 MCP 工具(
create_sub_agent/list_sub_agents/delete_sub_agent)管理两个作用域的 Markdown + YAML frontmatter 定义文件;路径 A 出厂模板、路径 B 动态管理均已上线,路径 C(OCR 触发真实派发)待平台回调。
兼容性
本插件兼容多种 Harness 平台:
- DeepSeek Harness:支持 DeepSeek Harness 的插件扫描、监控、进化全流程
- Minimax Code:支持 Minimax Code 的插件扫描、监控、进化全流程
- ZCode:支持 ZCode CLI 的插件管理(
zcode plugin link/zcode plugin list等) - Claude Code:作为 MCP 服务器,可被 OpenClaw 等开源 AI 平台调用
- OpenClaw:作为 MCP 服务器,可被 OpenClaw 等开源 AI 平台调用
多宿主支持
| 平台 | 宿主标识 | 配置路径 |
|---|---|---|
| DeepSeek Harness | ~/.deepseek/harness/plugins/, ~/.deepseek/harness/extensions/ |
|
| Minimax Code | ~/.minimax/plugins/, ~/.minimax/extensions/ |
|
| ZCode | ~/.zcode/cli/plugins/, ~/.zcode/skills/ |
|
| Claude Code | OpenClaw 等开源 AI 平台 | |
| OpenClaw | ~/.openclaw/ |
架构
flowchart TB
subgraph 宿主
Client["DeepSeek Harness / Minimax Code / ZCode / Claude Code"]
end
subgraph "harness-self-evolution(MCP server, stdio JSON-RPC)"
direction TB
HE["harness_evolution/<br/>装配与启动"]
MCP["mcp/<br/>10 工具 · stdio JSON-RPC"]
ENG["engine/<br/>决策树 + 风险评估"]
EXE["executor/<br/>DAG 分层 + Sub-Agent 编排"]
FAC["factory/<br/>子 Agent 定义管理"]
SCN["scanner/<br/>插件发现 + 信息提取"]
MON["monitor/<br/>性能采集 + 信号检测"]
ST["store/<br/>唯一持久化层<br/>(JSONL / 缓存 / 提案 / 子 Agent)"]
TY["types/<br/>19 张 wire 表 · 词汇表单一事实来源"]
UT["util/<br/>路径 / 时间 / 日志 / 4 个零依赖 Deep Module"]
end
Client -- "scan_plugins / propose_evolution /<br/>approve_proposal / execute_evolution /<br/>create_sub_agent ..." --> MCP
HE --> MCP
MCP --> ENG
MCP --> EXE
MCP --> SCN
MCP --> MON
MCP --> FAC
ENG --> ST
EXE --> ST
FAC --> ST
SCN --> ST
MON --> ST
SCN --> TY
ENG --> TY
EXE --> TY
FAC --> TY
MON --> TY
ENG --> MON
EXE --> MON
ST --> UT
TY --> UT
ENG --> UT
EXE --> UT
FAC --> UT
SCN --> UT
MON --> UT
依赖图是严格分层的(util → types → store → scanner/monitor → engine/executor/factory → mcp → harness_evolution),由 src/mcp/architecture_test.mbt 的 11 条守卫(G1–G6)机器化验证;任何新增反向边、往 stdout 写日志、绕过 store/ 持久化,都会在 moon test 里立刻变红。
安装
前置要求:
- MoonBit 工具链(
moon)。 - Windows:Visual Studio 的 C++ 生成工具(
cl.exe)+ Windows SDK。native 后端把 MoonBit 编译成 C 再用 MSVC 链接,build.ps1会自动探测并注入INCLUDE/LIB/PATH,不需要手工跑vcvars64.bat。 - 宿主环境(任选其一):
- DeepSeek Harness
- Minimax Code CLI(
mcode) - ZCode CLI
- Claude Code / OpenClaw(作为 MCP 服务器)
运行时不需要 Node.js —— 产物是独立的 native 可执行文件。
# 克隆(任选一)
git clone https://github.com/Across2005/harness-self-evolution-plugin.git
# 或
git clone https://www.gitlink.org.cn/Across2005/harness-self-evolution-plugin.git
cd harness-self-evolution-plugin
# 构建:check + test + build,产物复制到 bin\harness-evolution.exe
# 依赖由 moon 根据 moon.mod 里写死的精确版本自动拉取,无需单独的 install 步骤
.\build.ps1 all
# 链接到 ZCode(可选)
zcode plugin link .
为什么锁死
async@0.20.1:0.21.x 开始使用noraise + nocancel效果注解语法,而当前工具链(moon 0.1.20260819)解析它会报[3002] Parse error, unexpected token '+'。升级到能解析该语法的 moon 版本后方可放开约束。关于
moon.lock:本机工具链不产生模块根的moon.lock(moon mod tidy是独立插件moon-mod,未安装时直接报错;.mooncakes/.moon-lock实测为空)。可复现构建靠的是moon.mod里写死的精确版本而不是范围,并由架构守卫 G6 机器化钉住。用moon tree可随时核对实际解析结果(应为moonbitlang/async@0.20.1)。
快速开始
1. 环境准备
确保已安装以下工具:
- MoonBit 工具链(
moon):从 MoonBit 官网 下载安装 - Windows 用户:Visual Studio 的 C++ 生成工具(
cl.exe)+ Windows SDK(build.ps1会自动探测) - 宿主环境(任选其一):
- DeepSeek Harness
- Minimax Code CLI:
npm install -g mmx-cli - ZCode CLI
- Claude Code / OpenClaw(作为 MCP 服务器)
2. 获取与构建
# 克隆仓库(任选一)
git clone https://github.com/Across2005/harness-self-evolution-plugin.git
cd harness-self-evolution-plugin
# 完整构建(检查 + 测试 + 构建)
.uild.ps1 all
构建成功后,产物位于 bin/harness-evolution.exe。
3. 链接到宿主(ZCode)
# 将插件链接到 ZCode(使宿主能发现并加载插件)
zcode plugin link .
4. 启动插件
插件作为 MCP 服务器运行,由宿主自动启动。启动流程:
- 宿主(ZCode)读取
.zcode-plugin/plugin.json配置 - 宿主启动
bin/harness-evolution.exe进程 - 插件通过 stdio JSON-RPC 与宿主通信
- 插件自动扫描 配置的插件目录(
scan_targets) - 监控开始,记录性能事件和进化信号
5. 验证运行
# 检查插件是否正常运行
zcode plugin list
应该能看到 harness-self-evolution (v2.4.0) - Active。
6. 使用插件功能
通过宿主调用 MCP 工具:
// 扫描所有插件
const result = await callMcpTool('scan_plugins', {});
// 获取插件性能指标
const metrics = await callMcpTool('get_plugin_metrics', { plugin_id: 'browser-use-0.4.1' });
// 生成进化提案
const proposal = await callMcpTool('propose_evolution', { plugin_id: 'browser-use-0.4.1' });
手动测试(可选)
如需手动测试 MCP 服务器,可使用 MCP 客户端工具:
# 启动插件(手动模式)
echo '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}' | .in\harness-evolution.exe
# 应该收到 JSON-RPC 响应
build.ps1 子命令
| 命令 | 作用 |
|---|---|
.\build.ps1 check |
moon check --deny-warn --target native(零错零警才算过) |
.\build.ps1 test |
moon test --target native |
.\build.ps1 build |
release 构建 + 复制到 bin\harness-evolution.exe |
.\build.ps1 fmt |
moon fmt |
.\build.ps1 all |
依次执行 check → test → build |
配置
配置只来自 .zcode-plugin/plugin.json 的 evolution_config 段(查找顺序:$HARNESS_EVOLUTION_CONFIG → <cwd>/.zcode-plugin/plugin.json → 内置默认值)。AGENTS.md 不参与任何配置解析。
2.2.0 起,plugin.json 的 scan_targets 段 真正驱动扫描根:数组里的每个路径(支持 ~/...)替换内置的 3 个默认根;未配置/为空/类型不符时回退默认根并启动时点名告警。不存在的路径在扫描时跳过并打一行 stderr 提示。完整语义见 CONTEXT.md 的「配置来源」一节。
{
"scan_targets": ["~/plugins", "~/work/zcode-plugins"],
"evolution_config": {
"intensity": "50%",
"auto_approve": false,
"cooldown_hours": 24,
"max_log_bytes": 33554432,
"signal_thresholds": {
"consecutive_failures": 3,
"loop_detection": 5,
"latency_regression": 0.2
}
}
}
字段含义(完整列表与边界见 CONTEXT.md 与 DESIGN.md):
intensity:"100%"强信号或两个中信号均可触发;"50%"仅强信号触发;"0%"关闭所有进化检查。出厂默认 50%。auto_approve:故意不接通。1.0 里它是配置孤岛(写了但无消费方),2.0 起遇true显式告警并回落false—— 人工审批是「自动改代码失控」的唯一闸门。cooldown_hours:同一插件两次提案的最短间隔,默认 24,下界 1。max_log_bytes:metrics.jsonl/signals.jsonl的保留上限(字节,默认 32 MiB,下界 1 MiB),超限后自动裁到只保留最新的完整行。proposals.jsonl(审计事实来源)与execution.log不裁剪。signal_thresholds.*:连续失败次数 / 循环检测次数 / 性能回归比例。
调用模式
本插件是 MCP 服务器,一切行为都由工具调用驱动:
- 扫描:客户端调用
scan_plugins(2.2.0 起按plugin.json的scan_targets段指定根)建立档案。 - 监控:宿主在工具调用链上经
record_tool_call/record_user_feedback注入事件。 - 提案:
propose_evolution基于信号生成提案。 - 执行:
approve_proposal→execute_evolution(必经人工审批)。
MCP 工具(16 个)
| 工具 | 作用 |
|---|---|
scan_plugins |
扫描所有插件(2.2.0 起按 scan_targets 段) |
get_plugin_metrics |
获取插件性能指标 |
propose_evolution |
生成进化提案(可带手动 signals) |
approve_proposal |
批准提案(必经环节) |
reject_proposal |
拒绝提案 |
list_proposals |
列出所有提案 |
execute_evolution |
执行已批准提案 |
create_sub_agent |
创建子 Agent 定义文件(v2.1) |
list_sub_agents |
列出子 Agent 定义(v2.1,可按 scope 过滤) |
delete_sub_agent |
删除子 Agent 定义(v2.1) |
analyze_plugins |
合并工具:扫描并/或获取指标(v2.3,mode=scan/metrics/both) |
evolve_plugin |
合并工具:生成或执行提案(v2.3,action=propose/execute) |
manage_sub_agent |
合并工具:管理子 Agent 定义(v2.3,action=create/list/delete) |
get_execution_plan |
NEW 获取任务 DAG(供 DSH Agent 编排 subagent) |
report_task_result |
NEW 回写 Sub-Agent 执行结果 |
finalize_execution |
NEW 完成执行并更新提案状态 |
DSH Sub-Agent 集成
⚠️ 给接手 Agent 的提示
本插件的执行器已与 DSH 的
subagent工具对接。 如果你是一个运行在 DSH 中的 Agent,请阅读DSH_INTEGRATION.md了解完整的集成模式。
快速开始:
// 1. 获取执行计划
const plan = await callMcpTool('execute_evolution', { proposal_id: 'evo-xxx', dry_run: false });
// 2. 按层级执行(同层并行,层间串行)
for (const layer of plan.task_dag) {
await Promise.all(layer.tasks.map(task =>
subagent({ prompt: task.prompt, description: task.agent })
));
}
// 3. 完成
await callMcpTool('finalize_execution', { proposal_id: 'evo-xxx', success: true });
执行流程:
宿主 Agent MCP Server DSH subagent
│ │ │
├── execute_evolution ────────►│ │
│◄── task_dag ────────────────┤ │
│ │ │
├── subagent(prompt) ─────────┼────────────────────────────►│
│ (layer 0, 并行) │ │
│◄────────────────────────────┼──── result ─────────────────┤
│ │ │
├── report_task_result ──────►│ │
│ │ │
├── subagent(prompt) ─────────┼────────────────────────────►│
│ (layer 1) │ │
│◄────────────────────────────┼──── result ─────────────────┤
│ │ │
├── finalize_execution ──────►│ │
│◄── status: completed ───────┤ │
详细文档见 DSH_INTEGRATION.md。
数据存储
所有数据以 JSONL / JSON 格式存储在同一个数据根目录下(默认 ~/.harness-evolution/v2/,可用 $HARNESS_EVOLUTION_HOME 覆盖):
plugin-cache.json # 扫描缓存(每条带目录指纹:mtime + 子项数 + 子项 mtime)
metrics.jsonl # 性能事件(monitor 写,受 max_log_bytes 约束)
signals.jsonl # 进化信号(monitor 写 / engine 读,受 max_log_bytes 约束)
proposals.jsonl # 进化提案(ProposalStore 唯一读写口,**不裁剪**)
execution.log # 执行日志(executor,**不裁剪**)
agents/ # 子 Agent 定义(factory 写,scope=plugin;scope=user 写到宿主用户目录)
子 Agent 用户目录(scope=user)按宿主类型区分:
- DeepSeek Harness:
~/.deepseek/harness/agents/ - Minimax Code:
~/.minimax/agents/ - ZCode:
~/.zcode/agents/
可通过环境变量 HARNESS_EVOLUTION_HOST 切换宿主类型。
数据根目录的默认值只在 `store/paths.mbt` 一处定义,并由 `mcp/architecture_test.mbt` 的 G4 守卫机器化地防止它再次扩散(1.0 版把它散落在 4 个文件里)。
> **关于 v1 目录**:2.0 使用 `v2/` 子目录,**不做自动迁移**。若检测到 1.0 的 `~/.harness-evolution/` 存在,启动时会在 stderr 提示一行,然后原样保留。原因是 1.0 的 `plugin-cache.json` 命中条件过于宽松(只要缓存非空就直接返回,从不校验目录是否还存在),实测会被一条指向已删除临时目录的幽灵记录永久毒化 —— 丢弃重扫比迁移更安全。
### 子 Agent 协同
```mermaid
flowchart LR
P[提案审批] --> E[Executor 启动]
E --> D[任务分解]
D --> CG[code-generator]
D --> TW[test-writer]
D --> DW[doc-writer]
D --> IT[integration]
D --> VA[validator]
CG --> T0[T0 语法]
TW --> T1[T1 功能]
VA --> T2[T2 回归]
T0 --> R[更新 Registry]
T1 --> R
T2 --> R
出厂模板随插件的 agents/ 目录分发(frontmatter + 系统提示词,ZCode 的 agent 载体格式),宿主会自动发现加载;create_sub_agent / list_sub_agents / delete_sub_agent 三个工具可以增删管理这些定义。设计与研究结论见 docs/subagent-factory.md。
架构守卫(G1–G6)
| 守卫 | 约束 |
|---|---|
| G1 / G1b | 包依赖图与声明完全一致,且每条边严格向下(构造性无环) |
| G2 / G2b | @stdio.stdout 只在 mcp/server.mbt,@stdio.stderr 只在 util/log.mbt |
| G3 / G3b | @fs 的写操作只在 store/ |
| G4 / G4b | 数据目录字面量只在 store/paths.mbt |
| G5 / G5b | legacy-ts/tests/ 的 37 个 jest 用例逐条有 MoonBit 对应物 |
| G6 | moon.mod 只有一个外部依赖,且 native 是首选目标 |
每条守卫都做过负向探针验证(人为引入违规确认会变红),否则「永远通过的测试」只是装饰。
与 1.0(TypeScript)版对拍
1.0 的完整工程保留在 legacy-ts/,仍可运行:
cd legacy-ts
npm install
npx jest # 37 个用例
它是 2.0 移植正确性的客观参照:G5 守卫会解析这 37 个用例名,逐条核对 MoonBit 侧的对应测试是否仍然存在。
风险缓解
- 只读扫描:Scanner 不修改任何插件代码。
- 审批强制:所有进化必须经
approve_proposal。 - 状态机约束:提案只能从
pending → approved → executing → completed(或被reject_proposal回到rejected),非法跃迁一律拒。 - 信号缓冲有界:
signal_buffer上限 500 条(max_buffered_signals),溢出丢最旧。 - 数值防御:
num_field拒绝NaN/Infinity,回落默认值并点名告警。 - 观测日志有界:
metrics.jsonl/signals.jsonl受max_log_bytes约束,超限保留最新完整行。 - 手动信号需注意:
propose_evolution的signals参数按设计是 medium 强度,默认 50% 只放行 strong —— 手动信号在出厂默认配置下不会触发提案;要把手动信号生效得把intensity设为"100%"(已知缺陷第 1 条 F5)。 - 生产数据源尚未接入:
record_tool_call/record_user_feedback在本仓库里没有生产调用方(1.0 也一样)。可走手动路径,但自动信号需 Harness 侧注入事件(注入点已就绪,待平台回调)。
文档
CONTEXT.md—— 设计上下文、缺陷清单、配置来源、架构守卫、Matt Pocock 原则 ↔ 进化类型映射DESIGN.md—— 详细设计、模块边界、调用链DSH_INTEGRATION.md—— DSH Sub-Agent 集成指南docs/subagent-factory.md—— 子 Agent 工厂的设计与研究结论specs/minimax-code-support.md—— Minimax Code 扫描支持规格legacy-ts/—— 1.0(TypeScript)版的完整工程,作为移植正确性的客观参照
贡献
欢迎提交 Issue 和 Pull Request。请先读 CONTEXT.md 的「架构不变量」与「Matt Pocock 原则」两节 —— 任何反向边、往 stdout 写日志、绕过 store/ 持久化、引入裸配置孤岛,都会被架构守卫在 moon test 阶段直接拒。
许可证
English
What is this
A self-evolution plugin for multiple Harness platforms (primary: DeepSeek Harness). It scans plugins, monitors performance, detects signals, drafts upgrade proposals, and (only after explicit human approval) executes the upgrade. The user touches it in exactly one place: reviewing proposals.
Supported platforms: DeepSeek Harness / Minimax Code / ZCode / Claude Code / OpenClaw
Latest (v2.4.0, 2026-09-09)
- DSH subagent integration: the 1.0 side now ships a
dsh-runner.tsadapter that hands a topology-sorted task DAG to the host DeepSeek Harness Agent; the host executes each layer in parallel viasubagentcalls, then writes results back viareport_task_resultand finalizes withfinalize_execution. SeeDSH_INTEGRATION.md(371 lines) for the full host-side contract. - Real process runner: MoonBit's
runner.mbtreadsHARNESS_EVOLUTION_AGENT_CMD(template with{prompt}/{input}placeholders) and dispatches to@process; falls back to a mock when unset, with sandbox and streaming-IO extension points preserved. - Scanner one-pass dual collection:
list_skill_and_source_filescollects skill and source manifests in a single walk, halving I/O for large plugin trees. - JsonlStore backward read: tolerates v1/v2 records and normalises to v3 schema on load.
- 1.0 hygiene:
legacy-ts/.eslintrc.jslands;tests/server.test.tsandtests/store.test.tsclose the 1.0 coverage gap (75/75, +41 tests in this round). - Combined test count: 422/422 (MoonBit 347 + legacy-ts 75).
Quickstart
1. Prerequisites
- MoonBit toolchain (
moon): download from MoonBit website - Windows: Visual Studio C++ Build Tools (
cl.exe) + Windows SDK (auto-detected bybuild.ps1) - Host environment (choose one):
- DeepSeek Harness
- Minimax Code CLI:
npm install -g mmx-cli - ZCode CLI
- Claude Code / OpenClaw (as MCP server)
2. Clone and Build
git clone https://github.com/Across2005/harness-self-evolution-plugin.git
cd harness-self-evolution-plugin
# Full build: check + test + build
.\build.ps1 all
The output binary is at bin/harness-evolution.exe.
3. Link to Host (ZCode)
zcode plugin link .
4. Run
The plugin runs as an MCP server, automatically started by the host:
- Host reads
.zcode-plugin/plugin.jsonconfiguration - Host launches
bin/harness-evolution.exe - Plugin communicates via stdio JSON-RPC
- Plugin auto-scans configured plugin directories (
scan_targets) - Monitoring begins, recording performance events and evolution signals
5. Verify
zcode plugin list
# Should show: harness-self-evolution (v2.4.0) - Active
6. Use Plugin Features
// Scan all plugins
const result = await callMcpTool('scan_plugins', {});
// Get plugin metrics
const metrics = await callMcpTool('get_plugin_metrics', { plugin_id: 'browser-use-0.4.1' });
// Generate evolution proposal
const proposal = await callMcpTool('propose_evolution', { plugin_id: 'browser-use-0.4.1' });
Documentation
CONTEXT.md— design context, defect ledger, config source, architecture guardsDESIGN.md— detailed designdocs/subagent-factory.md— sub-agent factory
No comments yet. Be the first to write one.