#Harness Self-Evolution Plugin

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

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

#中文

#一句话定位

#最新进展（v2.4.0，2026-09-09）

#特性

• 插件扫描：解析 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 触发真实派发）待平台回调。

#兼容性

• 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 平台调用

#多宿主支持

#架构

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

#安装

• 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 服务器）

# 克隆（任选一）
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

#3. 链接到宿主（ZCode）

# 将插件链接到 ZCode（使宿主能发现并加载插件）
zcode plugin link .

#4. 启动插件

1. 宿主（ZCode）读取 .zcode-plugin/plugin.json 配置
2. 宿主启动 bin/harness-evolution.exe 进程
3. 插件通过 stdio JSON-RPC 与宿主通信
4. 插件自动扫描 配置的插件目录（scan_targets）
5. 监控开始，记录性能事件和进化信号

#5. 验证运行

# 检查插件是否正常运行
zcode plugin list

#6. 使用插件功能

// 扫描所有插件
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' });

#手动测试（可选）

# 启动插件（手动模式）
echo '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}' | .in\harness-evolution.exe

# 应该收到 JSON-RPC 响应

#build.ps1 子命令

#配置

{
  "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
    }
  }
}

• 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.*：连续失败次数 / 循环检测次数 / 性能回归比例。

#调用模式

1. 扫描：客户端调用 scan_plugins（2.2.0 起按 plugin.json 的 scan_targets 段指定根）建立档案。
2. 监控：宿主在工具调用链上经 record_tool_call / record_user_feedback 注入事件。
3. 提案：propose_evolution 基于信号生成提案。
4. 执行：approve_proposal → execute_evolution（必经人工审批）。

#MCP 工具（16 个）

#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 ───────┤                             │

#数据存储

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 写到宿主用户目录）

• DeepSeek Harness：~/.deepseek/harness/agents/
• Minimax Code：~/.minimax/agents/
• ZCode：~/.zcode/agents/

数据根目录的默认值只在 `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

#架构守卫（G1–G6）

#与 1.0（TypeScript）版对拍

cd legacy-ts
npm install
npx jest          # 37 个用例

#风险缓解

• 只读扫描：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）版的完整工程，作为移植正确性的客观参照

#贡献

#许可证

#English

#What is this

#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

#3. Link to Host (ZCode)

zcode plugin link .

#4. Run

1. Host reads .zcode-plugin/plugin.json configuration
2. Host launches bin/harness-evolution.exe
3. Plugin communicates via stdio JSON-RPC
4. Plugin auto-scans configured plugin directories (scan_targets)
5. 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