Across2005/harness-self-evolution-plugin

Harness 自进化插件

一个 MoonBit 原生插件，用于扫描、监控、提议并回滚跨多个 AI harness 平台的插件生态系统的进化。版本 2.6.0。MIT。

此插件对每个宿主都是同一个编译后的二进制文件。每个宿主不同的是宿主如何启动该二进制文件、数据读写的位置，以及哪些宿主特定文件（补丁、清单、面板）与二进制文件放在一起。

你使用的是哪个宿主？

选择运行你会话的那个。如果你不知道，请运行：

Windows PowerShell
Test-Path '~/.dsh'
Test-Path '~/.minimax'
Test-Path '~/.zcode'

打开对应的指南：

| 宿主 | 状态（2026-09-17） | 指南 |
|---|---|---|
| DeepSeek Harness（DSH）≥ 0.1.6 | 已端到端验证 | docs/deploy/deepseek-harness.md |
| Minimax Code（Mavis） | 已端到端验证 | docs/deploy/mavis.md |
| ZCode ≥ 0.5.0 | 已声明，等待验证 | docs/deploy/zcode.md |
| 其他任何宿主 | 不支持 | — |

“已验证”的含义：全新安装能在此机器上完成完整的 提议 → 批准 → 执行 循环，并且运行时之后保持健康。“已声明”意味着代码路径存在，但尚未在真实的 ZCode 安装上运行过端到端测试。“不支持”意味着运行时将回退到 DSH 路径，并在每次启动时发出 Unknown HARNESS_EVOLUTION_HOST ... 警告——不要依赖它。

活动宿主的状态由二进制文件本身在启动时打印（参见 src/store/paths.mbt 中的 host_verification_notice）。操作员无需阅读此 README 就能知道他们是在已验证还是已声明的宿主上；启动日志会直接说明。同一矩阵也由一个回归测试固定（host verification notice reflects the current verification matrix），因此若其中一个被无意更改而另一个没有，构建就会失败。

如果你的宿主不在表中，请参阅 docs/code-architecture.md § Adding a new host——需要改动三个文件，外加验证测试。

如果你是在编写或调试 DSH 插件，而不是部署此插件，请阅读 docs/dsh-plugin-integration.md：宿主半部 / 客户端半部契约、Lazy-CJS 客户端打包规则（一个多余的顶层 export 会破坏组合中的每个插件）、DSH_HOME 路由，以及“Failed to load plugins”的诊断顺序。

它做什么

- 扫描活动宿主配置的扫描根目录下已安装的插件
- 监控调用延迟、成功率、token 使用量、重试次数和用户反馈
- 识别强信号（用户覆盖、连续三次失败、延迟回退 > 20%）和中等信号（重复的参数误用、循环检测、重复偏好）
- 提议由基准驱动、绑定到 Matt Pocock 工程原则的进化
- Approve 始终是人工步骤。auto_approve 默认为 false，并且始终保持 false——这是防止“代码把自己改成一堵墙”的唯一关卡
- Execute 使用状态机 pending → approved → executing → completed，并在验证器失败时从经过验证的快照进行确定性回滚
- Sub-agent factory 持久化 Markdown + YAML frontmatter 定义；作用域 plugin 位于插件的数据根目录下，作用域 user 位于宿主机的用户级目录中（路径因宿主机而异，参见部署指南）

一段话概括架构

编译后的二进制文件（bin/harness-evolution.exe）是一个 stdio MCP 服务器。MCP 协议接口和这十四个工具与宿主机无关。每个宿主机有两处不同：(a) 路径布局，在 src/store/paths.mbt::host_agents_dir 和 src/scanner/scanner.mbt::default_scan_roots 中声明；(b) 启动器和补充文件。运行时从 HARNESS_EVOLUTION_HOST 中选择宿主机（默认为 deepseek-harness，可选 minimax-code、zcode，或使用 HARNESS_EVOLUTION_USER_DIR 显式覆盖用户目录）。docs/deploy/ 中的每份部署指南都明确说明了该宿主机使用哪种启动器机制以及哪些补充文件。

有关拆分路径加载原则的详细信息，请参见 docs/code-architecture.md。

构建

.\build.ps1 -Task all    # check + test + build; one command rebuilds the binary

构建前提条件：MoonBit >=0.1.20260904，Linux/macOS 上使用 MSVC 或 Clang。bin/harness-evolution.exe 中的当前二进制文件是 Windows 原生的；在目标平台上重新构建会生成该平台的原生二进制文件。

数据和配置

插件将提案、指标、信号、缓存和执行日志存储在 $HARNESS_EVOLUTION_HOME 下（默认为 ~/.harness-evolution/v2/）。使用该环境变量进行覆盖，以将开发/测试数据分开。

配置按以下顺序读取，第一个存在的文件生效：

1. $HARNESS_EVOLUTION_CONFIG（显式覆盖）
2. /.dsh-plugin/plugin.json（DSH 自清单）
3. /.zcode-plugin/plugin.json（旧版兼容）
4. .dsh-plugin/plugin.json（相对于插件根目录）

如果都不存在，插件将以内置默认值启动——缺少配置不是启动失败。

安装到正确的树中（DSH_HOME）

安装是按 DSH 树进行的：dsh plugin add 写入 $DSH_HOME/profiles/，而 $DSH_HOME
决定启动哪棵树（默认为 ~/.dsh——托管启动器可能将其指向其他位置）。树之间
不共享任何内容：bundles、node_modules、会话和技能都是按树隔离的，因此在一棵树中验证过的安装
对启动另一棵树的宿主机仍然不可见。dsh.profile.bundles 在启动时读取，因此必须
重启宿主机，十四个 mcp__harness-evolution__* 工具才会在会话中出现。

$env:DSH_HOME                                                            # which tree is dsh touching?
dsh --profile web --dump-config | Select-String 'mcp-harness-evolution'  # 已经挂载在这棵树里了？

完整安装、验证和回滚：docs/deploy/deepseek-harness.md；
实时安装实践（多 home 现实、.dsh-module-fallback 陷阱）：
docs/dsh-compatibility.md。

许可证

MIT。参见 LICENSE。