# 9大系统全景 OpenClawHarness 由 9 个相互协作的核心系统组成，从底层知识到顶层自治，形成完整的 AI 开发闭环。 ![系统架构全景图](../images/harness_flow_overview.png) ## 总览 | # | 系统 | 核心职责 | 关键模块 | 状态 | |---|------|----------|----------|------| | 1 | **任务流水线** | 从需求到交付，8步全自动 | `harness_run.py`, orchestrator | ✅ 稳定 | | 2 | **记忆系统** | 永不失忆的 3 层记忆 | MemClaw, Qdrant, Cortex | ✅ 稳定 | | 3 | **多Agent编排** | 8 角色 DAG 并行调度 | `agency_manifest.yml`, DAG engine | ✅ 稳定 | | 4 | **有机协调** | T1-T5 五终端协同 | Contract Manager, Quality Gradient | ✅ 稳定 | | 5 | **质量门控** | 5 维 AND 门控自动拦截 | Gate Keeper, Git rollback | ✅ 稳定 | | 6 | **监控面板** | 15 个 DAO 实时可视化 | FastAPI, SSE, Feishu notify | ✅ 可用 | | 7 | ⚡ **自进化引擎** | 从失败中学习、自动进化 | Diagnostician, Skill Evolver, Interceptor | ✅ 稳定 | | 8 | 🧠 **知识引擎** | 知识采集→分类→链接→进化 | Analyzer, Compiler, Classifier, QualityGate | ✅ 可用 | | 9 | 🩺 **自愈引擎** | 自动检测→诊断→修复→验证 | 22 种故障, L1→L2→L3 升级 | ✅ 稳定 | --- ## 1️⃣ 任务流水线系统 8 步全自动流水线是整个 Harness 的中枢神经： ``` 需求输入 → 上下文预载 → 知识图谱查询 → Skill 分发 → Prompt 生成 → 执行器调用 → 结果验证 → 知识回写 ``` | 步骤 | 做什么 | 关键保障 | |------|--------|----------| | S1 需求解析 | 理解任务意图、拆分子任务 | LLM 语义理解 + 结构化输出 | | S2 上下文预载 | 加载 `harness-context.md` | 强制预载，文件不存在=拒绝执行 | | S3 图谱查询 | 查询项目依赖、模块关系 | Qdrant 向量检索 + 知识图谱 | | S4 Skill 分发 | 匹配 11 个 Skill 模块 | 置信度排序，<0.5 跳过 | | S5 Prompt 生成 | 组装完整 prompt（含上下文+Skill+约束） | 三层注入结构 | | S6 执行器调用 | Claude Code → Codex → OpenCode Fallback | 3 层自动降级 | | S7 结果验证 | Gate Keeper 5 维验证 | 全通过才合并 | | S8 知识回写 | 双向同步 harness-context + corrections | 经验入库 | --- ## 2️⃣ 记忆系统 (MemClaw) > 核心使命：**永不失忆。** AI 做多步任务时忘记规则和决策，是最大的单点故障。 ### 三层记忆架构 | 层次 | 存储 | 用途 | 容量 | |------|------|------|------| | **工作记忆** | `harness-context.md` | 项目当前状态快照 | 单文件 | | **知识库** | `knowledge_wiki/` | 结构化知识条目 + 经验记录 | 500+ 文件 | | **长期记忆** | MemClaw (Qdrant 向量库 + Cortex 服务) | 语义检索 + 会话历史 | 无上限 | ``` 每次任务前: harness-context.md 强制预载 (L1) → Qdrant 语义检索相关经验 (L2) → Cortex 查询历史决策 (L3) 每次任务后: 新发现的规则 → 写回 harness-context.md 失败教训 → corrections/failure/*.md 成功经验 → corrections/success/*.md 知识更新 → knowledge_wiki/* ``` ![6层架构图](../images/arch.svg) --- ## 3️⃣ 多Agent编排系统 ![Agency Workflow](../images/openclawharness-agency-workflow.png) 8 种角色 Agent 按 DAG（有向无环图）并行或串行执行： ``` PM（产品经理） / \ Architect UI Designer (架构师) (UI 设计师) \ / Expert Review（评审） / \ Frontend Backend (前端开发) (后端开发) \ / Tester（QA测试） | Automation（DevOps） ``` | 特性 | 说明 | |------|------| | 并行执行 | Architect + UI 同时开工，Frontend + Backend 同时开发 | | 最大迭代 | 3 次反馈循环，每次迭代质量梯度提升 0.1 | | 能力分配 | 按任务类型（前端/后端/文档/测试）自动分配最合适的 AI 工具 | | 成本优化 | 简单任务用低成本模型，复杂架构用强模型 | --- ## 4️⃣ 有机协调系统 (Organic) T1-T5 五终端人格并行工作，合约驱动协作： ![任务协作流程图](../images/flow.svg) | 终端 | 人格 | 职责 | 触发条件 | |------|------|------|----------| | T1 工匠 | UI/UX 专注者 | 前端实现、视觉还原 | 有前端任务 | | T2 架构师 | 系统设计者 | 后端逻辑、API、数据库 | 有后端任务 | | T3 叙述者 | 文档写手 | 技术文档、用户指引 | 开发完成 | | T4 策略师 | 产品思考器 | 质量评分、需求验证 | 全流程 | | T5 怀疑者 | QA 测试员 | 边界检查、安全扫描 | 代码产出 | **5 种园丁干预**：AMPLIFY（增强资源）/ REDIRECT（重定向）/ MEDIATE（仲裁）/ INJECT（注入规则）/ PRUNE（裁剪冗余） 详见 [有机协调系统](organic.md)。 --- ## 5️⃣ 质量门控系统 (Gate Keeper) 5 维 AND 门控——一项不通过即回滚，零容忍妥协： | Gate | 检查内容 | 工具/方法 | 失败后果 | |------|----------|-----------|----------| | **Format** | 代码格式规范 | Ruff / Black / ESLint | 自动格式化后重新验证 | | **Content** | 语义完整性 | AST 分析 + 符号检查 | 回滚 + 标记为内容缺陷 | | **Behavior** | 功能行为验证 | pytest / Jest 全量测试 | 回滚 + 触发自愈引擎 | | **Performance** | 性能退化检测 | 基准对比 ±20% | 警告 + 人工审查 | | **Security** | 安全风险扫描 | SQL 注入 / XSS / 密钥泄露 | 回滚 + 安全告警 | ``` 全部 PASS → 自动合并代码 → 更新 harness-context → 经验入库 任一 FAIL → Git 自动回滚 → 升级修复层级 (L1→L2→L3) ``` --- ## 6️⃣ 监控面板系统 (Dashboard) 15 个 DAO 模块 + FastAPI + SSE 实时推送 + 飞书通知： | DAO | 监控内容 | |-----|----------| | 系统 | CPU / 内存 / 磁盘 / 进程状态 | | 执行 | 当前任务队列、执行中任务、等待中任务 | | 失败 | 失败分类统计、趋势图、Top 5 失败类型 | | 进化 | Skill 进化状态、进化历史 | | 技能 | 11 个 Skill 的健康状态 | | 契约 | 接口合约状态、匹配率 | | 健康 | 系统整体健康评分 | | 测试 | 测试覆盖率、失败测试列表 | | 报告 | 日报/周报自动生成 | | Git | 提交统计、分支状态 | | 知识 | 知识库规模、最近更新 | | 审查 | 代码审查待处理列表 | | 回溯 | 历史故障回溯分析 | | 工作流 | 工作流状态监控 | | 强制 | 门控拦截记录 | --- ## 7️⃣ Skill 系统 11 个可插拔 Skill 模块，按置信度自动匹配任务： | Skill | 功能 | |-------|------| | organic-quality | 质量梯度追踪 | | self-heal | 自动诊断修复 | | coding-principles | SOLID/DRY 编码原则 | | frontend-test | 前端测试运行 | | anti-rationalization | 防止AI自我合理化 | | expert-review | 代码评审 | | knowledge-classify | 知识自动分类 | | multi-pattern | 多模式探索 | | batch-task | 批量任务处理 | | health-check | 系统健康检查 | | context-inject | 上下文精准注入 | --- --- # ⚡ 深度一：自进化引擎 > *不做只会重试的傻瓜，每次失败都是进化机会。* — 老赵 ## 什么是自进化引擎？ 自进化引擎是 OpenClawHarness 最独特的能力。传统工具失败后只会"重试一次"，而自进化引擎把每次失败当成**养分**，让系统自动诊断→修复→验证→部署，形成完整的进化闭环。 **代号 L5**（Layer 5），是整个 Harness 的最顶层。 ![L5 自进化架构](../images/L5_Self_Evolution_Architecture.png) ## 核心哲学 | 传统 AI 工具 | 自进化引擎 | |-------------|-----------| | 失败 → 重试（相同参数） | 失败 → 诊断 → 学习 → 修复 → 永不复发 | | 错误是 bug | 错误是资源 | | 靠人工沉淀经验 | 自动沉淀 618 条成功 + 35 条失败记录 | | 每次从零开始 | 越用越强，知识持续积累 | ## 进化闭环：6 阶段详解 ``` ┌──────────────────────────────────────────────────────────────┐ │ L5 自进化闭环 │ │ │ │ ① 任务失败 / 质量不达标 │ │ ↓ │ │ ② Diagnostician 诊断（22 种故障类型，96% 匹配率） │ │ ↓ │ │ ③ Skill Evolver 生成修复方案（8 阶段状态机） │ │ ↓ │ │ ④ Gate Keeper 5 维 AND 门控 │ │ ↓ ↓ │ │ PASS → ⑤ 自动部署 FAIL → Git 回滚 + 升级修复层级 │ │ ↓ L1→L2→L3 │ │ ⑥ 效果追踪（Interceptor） │ │ ↓ │ │ 更新 harness-context → 经验入库 → 下次更聪明 │ └──────────────────────────────────────────────────────────────┘ ``` ### 阶段 ①：失败捕获 所有任务执行结果被记录——成功的进 `corrections/success/`，失败的进 `corrections/failure/`。每个记录包含：时间戳、错误类型、堆栈信息、项目上下文、失败前的操作序列。 ### 阶段 ②：Diagnostician 精准诊断 22 种故障类型，覆盖 96% 以上运行期问题： | 类别 | 故障类型 | 示例 | |------|----------|------| | 代码层 | import 错误 | `ModuleNotFoundError: No module named 'xxx'` | | 代码层 | 类型不匹配 | `TypeError: expected str, got int` | | 代码层 | API 变更 | 函数签名不兼容 | | 代码层 | 编码问题 | Windows GBK vs UTF-8 乱码 | | 进程层 | 进程泄漏 | 子进程未正确回收 | | 进程层 | 超时崩溃 | AI 执行超时无响应 | | 进程层 | 内存溢出 | 大文件一次性加载爆内存 | | 环境层 | 路径问题 | 相对路径/绝对路径混用 | | 环境层 | 权限问题 | Windows UAC / Linux sudo | | 环境层 | 依赖缺失 | requirements.txt 未安装 | | 运行层 | 网络超时 | API 调用无重试 | | 运行层 | 执行器不可用 | Claude Code 进程僵死 | | 运行层 | 参数混淆 | `--mode` vs `--model` 误传 | | 测试层 | 测试与实现不一致 | 改了代码没改测试 | | 测试层 | 测试环境隔离 | test 间相互污染 | | 协作层 | Git 冲突 | 多 Agent 同时修改同一文件 | | 协作层 | 接口不匹配 | 前端期望的字段后端未返回 | | 协作层 | 多代码库依赖不确定 | cross-repo 引用断裂 | | 配置层 | Config 不同步 | config.json vs config.yaml | | 配置层 | Daemon 状态误判 | .pid 文件存在但进程已死 | | 知识层 | Context 过时 | harness-context 未及时更新 | | 知识层 | 经验未归档 | 重复踩坑 | ### 阶段 ③：Skill Evolver 8 阶段状态机 ``` P0 加载上下文 → P1 识别知识缺口（哪些失败模式未被 Skill 覆盖） → P2 分析同一缺口的多轮表现（避免过度修复） → P3 制定修复策略（打补丁 vs 重写 vs 新增 Skill） → P4 生成/修改 Skill 代码 → P5 5 维门控验证 → P6 测试覆盖验证（新增行为必须有对应测试） → P7 生成 evolve_plan.md 进化计划文档 → P8 汇总报告 ``` ### 阶段 ④-⑥：验证 → 部署 → 追踪 - **Gate Keeper 5 维验证**：全 PASS 才部署，单维 FAIL 即回滚 - **自动部署**：通过的修复自动合并到 `main` 分支 - **Interceptor 效果追踪**：部署后持续监控，验证修复是否真的解决问题 ## 关键数据 | 指标 | 数据 | |------|------| | 故障诊断覆盖 | 22 种，96%+ 运行期问题 | | 自愈成功率 | ~75% | | 修复平均耗时 | 2 分钟 | | 知识沉淀 | 618 条成功 + 35 条失败 | | 部署方式 | 全自动（PASS → merge → deploy） | | 失败升级 | L1 确定性 → L2 上下文感知 → L3 人工 | --- # 🧠 深度二：知识引擎 > *知识不是静态文档，而是活的、会进化的有机体。* ## 什么是知识引擎？ 知识引擎是 OpenClawHarness 的"大脑皮层"——负责从代码、文档、执行反馈、人工输入等多源采集知识，经分析→分类→链接→编译→质量把关→进化，最终为 AI 执行提供精准的上下文支持。 **它不是简单的搜索工具，而是会主动发现矛盾、补全缺失、淘汰过时知识的知识生命体。** ## 架构：7 大组件协作 ``` ┌──────────────────────────────────────────────────────────────┐ │ 知识引擎 7 组件协作图 │ │ │ │ KnowledgeInputer (采集) │ │ ├── 代码注释 → API 文档 │ │ ├── 执行反馈 → 经验条目 │ │ ├── 人工笔记 → 结构化知识 │ │ └── 外部文档 → 摘要提取 │ │ ↓ │ │ KnowledgeAnalyzer (分析) │ │ ├── 解析 Markdown 笔记 → 提取标题/标签/关键词/链接 │ │ ├── 生成向量嵌入 → Qdrant 存储 │ │ └── 识别知识的类型（类/函数/概念/决策/教训） │ │ ↓ │ │ KnowledgeClassifier (分类) │ │ ├── 按类型：class / function / concept / decision / lesson │ │ ├── 按领域：前端/后端/测试/运维/架构 │ │ ├── 按质量：verified / draft / deprecated │ │ └── 按时效：current / historical / archive │ │ ↓ │ │ KnowledgeCompiler (编译) │ │ ├── 为具体任务编译相关知识块 │ │ ├── 语义检索 + 关键词匹配 + 图谱遍历 │ │ └── 输出：<4000 chars 的高密度上下文 │ │ ↓ │ │ KnowledgeQualityGate (质量把关) │ │ ├── 矛盾检测：同类型错误在多个地方有不同说法？ │ │ ├── 时效检查：3 个月未更新的知识标记为 stale │ │ ├── 完整性：必需字段是否齐全？ │ │ └── 重复检测：同一知识是否有多个版本？ │ │ ↓ │ │ KnowledgeWriter (写入) │ │ ├── 自动生成 Markdown 笔记 │ │ ├── Frontmatter 标准化（title/date/tags/type） │ │ └── 双向链接维护（[[wiki_link]]） │ │ ↓ │ │ KnowledgeEvolver (进化) │ │ ├── 发现知识缺口 → 标记 missing │ │ ├── 合并重复 → 保留最新/最完整版本 │ │ ├── 更新过时 → 生成修订建议 │ │ └── 淘汰无效 → archive + reason │ │ │ │ KnowledgeEngineOrchestrator (编排) │ │ └── 统筹全流程：COLLECT → GENERATE → LINK → DETECT → EVOLVE│ └──────────────────────────────────────────────────────────────┘ ``` ## 6 种任务类型 | 类型 | 触发条件 | 执行流程 | |------|----------|----------| | **COLLECT** | 用户输入"采集" / 定时任务 | Inputer → Analyzer → Classifier → Writer | | **GENERATE** | 用户输入"生成"/"wiki" | Analyzer → Compiler → Writer (生成新笔记) | | **LINK** | 用户输入"链接" / 知识变更后 | Analyzer → Writer (更新 [[双链]]) | | **DETECT** | 用户输入"矛盾"/"检测" / 定时 | QualityGate 全量扫描 | | **EVOLVE** | 用户输入"进化" / 积累 10+ 条新知识 | Evolver 补全/合并/升级/淘汰 | | **FULL** | 默认 / 用户输入"完整" | 全部 5 步顺序执行 | ## 关键数据流 ``` 用户说"帮我采集最近一周的编码教训" → KnowledgeEngineOrchestrator.parse_task("collect") → 扫描 corrections/failure/ 目录（最近 7 天） → KnowledgeAnalyzer 解析每条失败记录 → KnowledgeClassifier 分类（代码层/进程层/环境层） → KnowledgeQualityGate 检测矛盾 → KnowledgeWriter 生成知识笔记 → Qdrant 更新向量索引 → harness-context.md 同步更新 ``` ## 与自进化引擎的协作 ``` 自进化引擎生成修复方案 → KnowledgeQualityGate 检测与现有知识是否矛盾 → 无矛盾 → KnowledgeWriter 收录 → 有矛盾 → KnowledgeEvolver 产生 merge/replace 建议 → 人工确认或自动采纳 → 经验库更新 → 下次 Diagnostician 参考更多经验 ``` --- # 🩺 深度三：自愈引擎 > *系统应该像一个生物体：受伤了能自动愈合，不需要人拿着手术刀。* ## 什么是自愈引擎？ 自愈引擎是 OpenClawHarness 的"免疫系统"——它持续扫描项目健康状况，发现异常后自动诊断并执行修复，从最简单的文件丢失到复杂的依赖断裂，分三层逐步升级处理。 ## 自愈层次：L1 → L2 → L3 ``` ┌──────────────────────────────────────────────────────────────┐ │ 自愈引擎 3 层架构 │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ L1 确定性修复（自动，无需思考） │ │ │ │ ├── .last_sync 缺失 → 自动创建 │ │ │ │ ├── corrections/ 目录缺失 → 自动创建 │ │ │ │ ├── harness-context.md 空白 → 从知识库重建 │ │ │ │ ├── 编码异常 → 自动 utf-8 规范化 │ │ │ │ └── 已知错误模式 → 正则匹配 + 确定性替换 │ │ │ │ 成功率：~90% | 耗时：<10s │ │ │ └─────────────────────────────────────────────────────┘ │ │ ↓ L1 修复失败 │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ L2 上下文感知修复（需要理解项目） │ │ │ │ ├── import 错误 → 检查路径+安装依赖 │ │ │ │ ├── 类型不匹配 → 对比 API 文档+调整签名 │ │ │ │ ├── 配置冲突 → 对比 config.json vs config.yaml │ │ │ │ ├── 测试失败 → 对比代码变更+定位回归点 │ │ │ │ └── Daemon 假死 → 检查进程+重启 │ │ │ │ 成功率：~65% | 耗时：30s-2min │ │ │ └─────────────────────────────────────────────────────┘ │ │ ↓ L2 修复失败 │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ L3 人机协作（生成修复方案队列，等待确认或自动实施） │ │ │ │ ├── 未知故障类型 → 自动聚类 → 推荐新类型 │ │ │ │ ├── 复杂重构 → 生成多方案 + 影响分析 │ │ │ │ ├── 跨系统冲突 → 综合分析报告 │ │ │ │ └── 安全敏感操作 → 明确要求人工审批 │ │ │ │ 成功率：~40% 自动，60% 人工确认后实施 │ │ │ └─────────────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────────┘ ``` ## 扫描与执行流程 ```python class SelfHealingEngine: def scan_and_heal(self, dry_run=False) -> HealReport: # 1. L1 检查：.last_sync 标记 self._heal_sync_marker(report) # 2. 扫描 corrections/success/*.md for correction in success_dir: self._heal_success_correction(correction) # 3. 扫描 corrections/failure/*.md for failure in failure_dir: self._heal_failure_correction(failure) # 4. 检查 harness-context.md self._heal_harness_context(context_file) # 5. 生成 HealReport（含所有 HealAction） return report ``` ## 常见自愈案例 ### 案例 1：编码问题自动修复 ``` 检测：corrections/failure/*.md 出现 3 次 "UnicodeDecodeError" 诊断：Windows GBK 环境导致中文注释乱码 L1 修复： ├── 所有 .py 文件头部插入 # -*- coding: utf-8 -*- ├── 环境变量追加 PYTHONIOENCODING=utf-8 └── config.py 启动时 sys.stdout.reconfigure(encoding='utf-8') 结果：该问题自愈后从未复发 ``` ### 案例 2：Daemon 假死自动恢复 ``` 检测：.pid 文件存在，但进程列表中无对应 PID 诊断：进程被 System Tray 清理，.pid 未删除 L2 修复： ├── 检查 .cron_daemon.state 确认上次运行时间 ├── 超过阈值 → 发送飞书通知 "Daemon 疑似离线" ├── 自动重启 daemon 进程 └── 写入自愈报告 结果：不影响 7×24 持续运行 ``` ### 案例 3：Config 漂移自动纠错 ``` 检测：config.json 和 config.yaml 的 timeout 值不一致 诊断：两个配置入口未同步 L1 修复： ├── 以 config.yaml 为准（主配置） ├── config.json 自动同步 └── 差异写入 corrections/ 供人工复查 ``` ## 与自进化引擎的协作 ``` 自愈引擎发现未知故障（L2 修复失败） → 升级到 L3 → 自动生成 EvolutionInsight → 提交给自进化引擎 → Skill Evolver 分析并生成新 Skill → Gate Keeper 验证 → 部署新 Skill → 自愈引擎下次遇到→直接 L1 解决 ✅ ``` --- ## 三大引擎协同全景 ``` ┌──────────────────────┐ │ 用户任务 │ └──────────┬───────────┘ ↓ ┌─────────────────────────────────────────┐ │ 任务流水线 (8 步执行) │ └─────────────────────────────────────────┘ ↓ ↓ ↓ ┌─────┴──┐ ┌─┴────┐ ┌┴──────────┐ │ 成功？ │ │ 失败？│ │质量不达标？ │ └─────┬──┘ └─┬────┘ └┬──────────┘ ↓ ↓ ↓ ┌──────────────┐ ┌──────────────────────┐ │ 🧠 知识引擎 │ │ 🩺 自愈引擎 │ │ 采集经验入库 │ │ L1 确定修复 │ │ 分类归档 │ │ ↓ 失败 │ │ 链接知识图谱 │ │ L2 上下文修复 │ └──────────────┘ │ ↓ 失败 │ │ L3 人工+自进化 │ └──────────┬───────────┘ ↓ ┌──────────────────────┐ │ ⚡ 自进化引擎 │ │ Diagnostician 诊断 │ │ Skill Evolver 修复 │ │ Gate Keeper 验证 │ │ 自动部署 → 永不复发 │ └──────────────────────┘ ``` --- ## 相关页面 - [任务流水线详解](pipeline.md) - [记忆层设计](memory.md) - [有机协调系统](organic.md) - [L5 自进化系统](evolution.md) - [架构概览](overview.md)