Harness Self-Evolution Plugin

让多种 Harness 平台的插件生态持续自我进化 —— 扫描 → 监控 → 识别 → 提案 → 人工审批 → 真实升级。

支持：DeepSeek Harness（首打）/ Minimax Code / ZCode / Claude Code / OpenClaw

English · 中文

中文

一句话定位

挂在多种 Harness 平台上的自进化插件（首打 DeepSeek Harness）。用户全程只介入一处：看提案，点同意或不同意。

轮次	提交	关键变化
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）的定义文件

特性

插件扫描：解析 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/
装配与启动"]
        MCP["mcp/
10 工具 · stdio JSON-RPC"]
        ENG["engine/
决策树 + 风险评估"]
        EXE["executor/
DAG 分层 + Sub-Agent 编排"]
        FAC["factory/
子 Agent 定义管理"]
        SCN["scanner/
插件发现 + 信息提取"]
        MON["monitor/
性能采集 + 信号检测"]
        ST["store/
唯一持久化层
（JSONL / 缓存 / 提案 / 子 Agent）"]
        TY["types/
19 张 wire 表 · 词汇表单一事实来源"]
        UT["util/
路径 / 时间 / 日志 / 4 个零依赖 Deep Module"]
    end
    
    Client -- "scan_plugins / propose_evolution /
approve_proposal / execute_evolution /
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 阶段直接拒。

许可证

MIT

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.ts adapter that hands a topology-sorted task DAG to the host DeepSeek Harness Agent; the host executes each layer in parallel via subagent calls, then writes results back via report_task_result and finalizes with finalize_execution. See DSH_INTEGRATION.md (371 lines) for the full host-side contract.
Real process runner: MoonBit’s runner.mbt reads HARNESS_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_files collects 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.js lands; tests/server.test.ts and tests/store.test.ts close 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 by build.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.json configuration
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 guards
DESIGN.md — detailed design
docs/subagent-factory.md — sub-agent factory

License

MIT