Hi带娃的我热爱AI 大模型应用落地、意识解码与 AI 开发工具链。 创业路上用技术换时间一起把 AI 变成生产力 WeClaw_62_Harness工程全景六层模型评估与WeClaw 4.3分成熟度诊断第四季系列文章第 1 篇总第 62 篇- Harness Engineering · 六层架构模型 · 成熟度评估 · 差距分析 · 迭代规划 专栏信息《从零到一构建跨平台 AI 助手WeClaw 实战指南》专栏 ·第四季专栏定位面向开发者和技术决策者的实战专栏用真实案例和完整代码带你理解如何构建生产级 AI 应用第四季主题Harness EngineeringAgent 运行线束工程—— 当 Agent 的能力上限不再取决于模型本身而取决于它运行的线束架构时我们如何系统性地评估、对齐和迭代改进本文是第四季的开篇从 Harness Engineering 的六层架构模型出发对 WeClaw 进行全景式成熟度诊断识别出 7 个关键差距领域并由此展开后续 6 篇维度深入分析 1 篇总结展望的系列文章。 作者与项目作者简介翁勇刚 WENG YONGGANG新概念龙虾-WeClaw 开发团队负责人一群专注于跨平台 AI 应用的实践者理念“再复杂的技术也能用代码讲清楚” 项目地址https://github.com/wyg5208/weclaw.git 官网地址https://weclaw.link 作者 CSDNhttps://blog.csdn.net/yweng18⭐ 欢迎 Star⭐、Fork、贡献代码 摘要本文结构概览从 2026 年 AI 工程领域最核心的范式演进——Agent Model Harness出发系统介绍 Harness Engineering 的六层架构模型Prompt → Context → Tools → Orchestration → Multi-Agent → Safety Observability然后以此框架对 WeClaw 进行逐层诊断给出 4.3/5.0 的综合成熟度评分并识别出 7 个关键差距领域。最后概述我们的 V3 迭代方案如何通过 4 个里程碑、8 个 Task 系统性对齐这些差距。核心问题当所有人都在追逐更强的模型时真正决定 Agent 表现的线束架构却被忽视。一个运行在粗糙 Harness 上的 GPT-4 级模型实际表现可能不如一个运行在精心设计 Harness 上的 GPT-3.5 级模型。我们如何评估自己的 Harness 成熟度差距在哪里如何系统性改进关键成果建立了 WeClaw 六层 Harness 成熟度雷达图识别出 7 个差距领域G1-G7按优先级排列规划了 M0→M4 的迭代路径1830 行新增代码 61 行 Hook 注入适合读者AI Agent 开发者、架构师、对 Agent 工程化感兴趣的技术决策者阅读时长约 20 分钟关键词Harness Engineering、六层架构、成熟度评估、ReAct 循环、Agent 工程、Hook 注入一、什么是 Harness Engineering1.1 从模型即一切到线束决定上限2026 年AI 工程领域发生了一个根本性的认知转变Agent Model Harness这个公式来自 OpenAI Codex 团队的三支柱框架和 Harness-Bench (arXiv:2605.27922) 的学术定义。它的核心命题是Agent 的能力上限不取决于模型本身而取决于它运行的线束架构。什么是线束Harness借用汽车工程的类比发动机Model再强大如果没有传动系统Context Pipeline、方向盘Orchestration、刹车Safety Guardrails和仪表盘Observability这辆车也开不起来。线束工程就是围绕模型构建的所有非模型组件的总和。1.2 六层架构模型Harness Engineering 将 Agent 的非模型组件划分为六个层次层次核心职责类比Prompt Layer参数化、动态提示词构建给发动机的点火指令Context Layer动态上下文管道、窗口管理、RAG燃油供给系统Tools Layer工具集 权限控制 渐进暴露变速箱和驱动轮Orchestration Layer路由、安全护栏、状态管理方向盘和刹车Multi-Agent Layer多 Agent 专业化协作多车协同编队Safety Observability沙箱、审计、遥测仪表盘和行车记录仪这六层从下到上每一层都建立在前一层的基础上。一个成熟的 Agent 系统需要在这六个维度上同时达到较高水平。1.3 为什么现在重要在 2024-2025 年大多数 AI 应用还停留在调 API 拼 Prompt的阶段。但随着 Agent 的自主性越来越强——它们开始调用工具、修改文件、执行 shell 命令——线束的质量就成了决定成败的关键。Harness-Bench 的研究发现Agent 的五大失败模式中只有 36.4% 是模型能力不足导致的其余 63.6% 都可以通过 Harness 层面的工程改进来预防。二、WeClaw 六层 Harness 技术栈落实矩阵2.1 逐层诊断我们对 WeClaw 的代码库进行了系统性审计逐层评估 Harness 落实度第 1 层Prompt Layer — 参数化提示词体系维度WeClaw 实现成熟度参数化 System Promptprompts.py2732行包含意图分类提示词、工具选择提示词等★★★★动态 Prompt 渲染根据意图识别结果动态注入工具优先级标注[推荐]/[备选]/[禁用]★★★★安全提示注入prompt_security.py— 6 大类威胁模式检测★★★★压缩感知注解压缩后自动追加系统提示★★★评价已超越静态指令阶段实现了参数化和安全扫描但尚未达到完全自适应。第 2 层Context Layer — 上下文架构维度WeClaw 实现成熟度智能上下文压缩context_compressor.py1280行— 辅助LLM摘要替换 工具结果裁剪★★★★★Token 预算管理token_utils.py 压缩器内tail_token_budget尾部保护★★★★缓存感知压缩cache_aware_compression— DeepSeek 缓存命中成本 压缩成本时延迟压缩★★★★★RAG 检索增强完整向量检索管线Embedder VectorStore TextSplitter Parser★★★★经验记忆检索experience_store.py— SQLite ChromaDB 双引擎三层过滤★★★★评价这是 WeClaw Harness 中最成熟的一层。1280 行的 ContextCompressor 配合辅助 LLM 经济学低成本 qwen-turbo 做摘要加上缓存感知压缩的创新设计已达到业界领先水平。第 3 层Tools Layer — 工具集与权限控制维度WeClaw 实现成熟度工具注册系统统一 BaseTool 接口60 内置工具★★★★渐进式工具暴露tool_exposure.py412行— 推荐集→扩展集→全量集按意图置信度分层★★★★★工具调用前置校验tool_validator.py— 数量限制硬约束★★★MCP 协议桥接mcp_client.py— 将外部 MCP Server 工具转为 BaseTool★★★★评价渐进式工具暴露引擎是亮点创新——引导而非限制渐进而非决断的设计哲学与 Harness Engineering 的约束理念高度契合。不足在于前置校验器当前仅做数量限制参数格式校验和语义级约束尚未实现。第 4 层Orchestration Layer — 编排与恢复维度WeClaw 实现成熟度错误分类器error_classifier.py— 7种错误类型 5种恢复策略★★★★★降级链FallbackChain— 模型降级链管理防循环检测★★★★★重试策略RetryStrategy— 指数退避 随机抖动★★★★辅助模型经济学auxiliary_client.py— 独立预算管理$0.5/天★★★★★评价编排层是另一强项。错误分类→恢复策略→降级链的三级容错体系非常完整。第 5 层Multi-Agent Layer — 多 Agent 协作维度WeClaw 实现成熟度Agent 实例池agent_pool.py— 会话级隔离LRU淘汰全局速率限制★★★★Curator 自改进curator.py813行— 对话→技能自动沉淀 周期性维护★★★★★PWA 远程协同WebSocket 跨端消息路由★★★★评价Curator 自改进闭环是差异化亮点——对话经验自动沉淀为可复用技能。但当前多 Agent 协作更多是并行隔离模式尚未实现角色分工协作。第 6 层Safety Observability Layer — 安全与可观测维度WeClaw 实现成熟度提示注入防护prompt_security.py423行— 6大类威胁模式双扫描模式★★★★★权限管理三级风险LOW/MEDIUM/HIGH 三级策略★★★★审计日志audit.py832行— SQLite持久化 EventBus自动订阅★★★★★全链路追踪task_trace.py367行— 意图→工具暴露→调用序列→结果★★★★★评价安全与可观测层非常完整。832 行审计系统 367 行全链路追踪构成了纵深防御体系。2.2 综合评分WeClaw Harness 成熟度雷达图5分制 Prompt Layer ████████░░ 4.0 Context Layer ██████████ 5.0 ← 最强层 Tools Layer ████████░░ 4.0 Orchestration Layer █████████░ 4.5 Multi-Agent Layer ████████░░ 4.0 Safety Observability█████████░ 4.5 综合 Harness 成熟度 ████████░░ 4.3 / 5.04.3/5.0— 这是一个相当不错的分数。在六个维度中有三个达到了 4.5 以上Context、Orchestration、Safety没有一个低于 4.0。但 Harness Engineering 的核心理念是木桶效应。一个 5.0 分的 Context 层无法弥补一个 3.0 分的 Multi-Agent 协作层。Agent 的整体表现取决于最短的那块木板。三、对标 Harness-Bench五大失败模式Harness-Bench 定义了 Agent 执行对齐的五大失败模式。我们以此对照 WeClaw失败模式行业发生率WeClaw 防护覆盖度Contract/Format— 输出格式违约36.4%ToolCallValidator Schema 约束★★★Tool/Recovery— 工具失败后无法恢复24.6%ErrorClassifier FallbackChain★★★★★Evidence/Grounding— 证据不完整14.6%RAG ExperienceStore★★★★Artifact Commitment— 推理未落盘11.1%GeneratedFiles 管理 审计日志★★★State/Continuation— 状态丢失9.3%ContextCompressor Session 持久化★★★★关键发现Tool/Recovery 和 State/Continuation 覆盖最好但 Contract/Format 和 Artifact Commitment 是薄弱环节——这恰好指向我们的改进方向。四、七个关键差距领域基于上述诊断我们识别出 7 个需要改进的差距领域编号差距当前状态Harness 理想态优先级G1架构约束自动执行依赖 Prompt 引导CI/Linter 级确定性约束P1G2角色化多 Agent 协作会话级并行无角色分工Explorer/Planner/Coder/ReviewerP1G3熵管理Curator 做技能维护定期清理 文档一致性 死代码扫描P2G4自适应 Harness配置驱动根据历史成功模式自动调整P2G5Pre-completion Checklist无任务完成前强制自检清单P2G6Loop Detection无显式实现检测重复工具调用防止死亡循环P3G7Reasoning Sandwich统一推理强度规划/验证阶段高推理实现阶段中推理P3这 7 个差距不是平行的——它们之间有依赖关系G1约束引擎──→ G2角色协作Reviewer 需要 ConstraintEngine ↗ G5Checklist──→ G7Reasoning Sandwich需要 Checklist 触发标记 ↑ G6Loop Detection── 独立可与 G5 并行 G3熵管理── 独立后台运行 G4自适应── 需要数据积累最后启用五、迭代方案从 V1 到 V3 的演进5.1 三轮评审的淬炼我们的迭代方案经历了三轮严格评审V1 → V2三视角评审发现 6 个 Critical IssuesC1: 流式路径全面遗漏 → 双路径对称覆盖C2: Checklist continue 时序错误 → 移至正确位置C3: 架构原则矛盾 → Hook 注入 EventBus 辅助C4: RoleOrchestrator 集成缺陷 → SharedMemory 隔离 EventBusC5: Reasoning Sandwich 不可行 → 仅最终回复切换C6: LoopDetector 变量错误 → 修正方法名V2 → V3代码级深度评审发现 3 个阻塞项 5 个风险项B1:ExecutionTracker.get_recent_calls()方法不存在 → 新增B2:chat_stream缺少_validate_tool_relevance→ 补全B3: Reasoning Sandwichhas_tool_callsFalse逻辑矛盾 → 降级为实验性骨架R1-R5: 流式 UX、入口文件、EventBus 隔离、向后兼容、配置位置5.2 核心架构原则经过三轮评审淬炼我们确立了 6 条不可动摇的设计原则Hook 注入 EventBus 辅助核心控制流用直接 Hook信息通报用 EventBus配置驱动灰度所有功能默认关闭逐项开启独立模块 Hook 注入新功能独立.py模块Agent 仅做 hook 挂载15行Token 预算硬上限多 Agent 总 token ≤ 单 Agent 的 1.5 倍双路径对称覆盖_chat_impl和chat_stream必须同时覆盖依赖注入一致性由gui_app.py统一创建和注入引擎实例5.3 里程碑路线图M0Day 1-2: 前置基础设施修复 → ExecutionTracker.get_recent_calls()3行 → chat_stream 补全 _validate_tool_relevance10行 M1Week 1-2: 确定性约束 Pre-completion Checklist → ConstraintEngine~200行 CompletionChecklist~200行 → 零 token 成本纯规则改进 M2Week 3-4: Loop Detection 熵管理 → LoopDetector~180行 EntropyManager~250行 M3Week 5-7: 角色化多 Agent 自适应 Harness → RoleOrchestrator~300行 AgentRoles~150行 → TokenBudgetController~150行 AdaptiveHarness~250行 M4Week 8: Reasoning Sandwich 骨架 → ReasoningScheduler~150行仅骨架不注入总新增代码~1830 行新模块 ~61 行 agent.py Hook 注入六、为什么选择 Hook 注入而非重构这是整个方案中最关键的架构决策。我们考虑过三种方案方案优势风险结论重构为 Pipeline架构最优雅侵入性太高回归风险大❌ 否决LangGraph/AutoGen社区成熟外部依赖与 EventBus/AgentPool 不兼容❌ 否决Hook 注入 独立模块侵入性最小可灰度Agent 类持续膨胀✅ 采纳选择 Hook 注入的核心逻辑是WeClaw 的 agent.py 已经有 3296 行双 ReAct 路径运行稳定。与其推倒重来不如在关键位置插入 Hook让新功能以插件方式挂载。每个 Hook 注入点都遵循同一模式抽取私有方法供双路径复用在 ReAct 循环的特定位置调用方法内部判断功能是否启用未启用时直接返回原值零开销# 典型的 Hook 注入模式def_check_constraint(self,...):ifnotself._constraint_engine:returnFalse# 未启用零开销resultself._constraint_engine.validate(...)ifresult.statusREJECT:_batch.append(...)returnTrue# 被拦截returnFalse# 在 ReAct 循环中ifself._check_constraint(...):continue6.1 双路径对称覆盖的挑战WeClaw 有两条 ReAct 路径_chat_impl非流式和chat_stream流式。流式是桌面端和 PWA 的主要执行路径。代码级评审发现chat_stream路径遗漏了_validate_tool_relevance调用——这是一个现有系统的 Bug非流式路径有此校验但流式路径没有。这意味着流式模式下模型可能调用与当前意图无关的工具而不被拦截。这类双路径不对称问题在大型代码库中非常常见也是我们确立双路径对称覆盖原则的原因。七、系列文章导读本系列共 8 篇文章本文是开篇。后续 7 篇将分别深入每个差距维度编号主题对应差距核心看点#62本文总体技术分析全景六层模型评估 7 差距识别 迭代规划#63确定性约束引擎G1从 Prompt 引导到代码级强制的范式转变#64角色化多 Agent 协作G2Explorer/Planner/Coder/Reviewer 分工编排#65熵管理G3AI 系统的垃圾回收机制#66自适应 HarnessG4让系统从历史成功模式中学习#67Pre-completion ChecklistG5AI 的交付前自检清单#68Loop DetectionG6检测和中断 Agent 的死亡循环#69总结与展望全景迭代哲学 工程思考 未来路线其中 G7Reasoning Sandwich因为在代码级评审中发现根本性逻辑矛盾reasoning 模型不支持 function calling已被降级为实验性骨架将在 #69 总结篇中作为被否决的方案案例讨论。八、核心教训在结束本文之前分享我们在评估过程中获得的三个关键认知8.1 成熟度评估必须代码级仅看文档和配置文件你会得出过于乐观的结论。我们的 V2 方案在文档层面看起来完美无缺但代码级评审发现了 3 个阻塞项一个方法根本不存在一条路径遗漏了关键校验一个功能设计存在逻辑矛盾教训文档说有代码说没有——永远以代码为准。8.2 双路径是隐形陷阱WeClaw 的_chat_impl和chat_stream是两条独立的 ReAct 循环它们共享大部分逻辑但有微妙差异。任何新功能如果只覆盖一条路径就会在另一条路径上产生不对称行为。教训大型代码库中对称覆盖比单路径完美更重要。8.3 迭代评审的价值从 V1 到 V3我们经历了三轮评审V16 个 Critical架构级问题V23 个阻塞 5 个风险代码级问题V3可编码实施每一轮评审都发现了上一轮无法发现的问题——因为前一轮的问题修复后更深层次的问题才暴露出来。教训方案评审不是一次性活动而是渐进式收敛过程。 相关文章WeClaw_60_能力越强护栏越硬AI自主进化的安全边界工程与核能类比WeClaw_61_当AI把内部协议泄漏给用户DeepSeek_DSML标记污染content字段的全链路排查与修复本文是 WeClaw 专栏第四季的第 1 篇总第 62 篇。如果这篇文章对你有帮助欢迎给项目点个 Star ⭐
Hi带娃的我热爱AI 大模型应用落地、意识解码与 AI 开发工具链。 创业路上用技术换时间一起把 AI 变成生产力 WeClaw_62_Harness工程全景六层模型评估与WeClaw 4.3分成熟度诊断第四季系列文章第 1 篇总第 62 篇- Harness Engineering · 六层架构模型 · 成熟度评估 · 差距分析 · 迭代规划 专栏信息《从零到一构建跨平台 AI 助手WeClaw 实战指南》专栏 ·第四季专栏定位面向开发者和技术决策者的实战专栏用真实案例和完整代码带你理解如何构建生产级 AI 应用第四季主题Harness EngineeringAgent 运行线束工程—— 当 Agent 的能力上限不再取决于模型本身而取决于它运行的线束架构时我们如何系统性地评估、对齐和迭代改进本文是第四季的开篇从 Harness Engineering 的六层架构模型出发对 WeClaw 进行全景式成熟度诊断识别出 7 个关键差距领域并由此展开后续 6 篇维度深入分析 1 篇总结展望的系列文章。 作者与项目作者简介翁勇刚 WENG YONGGANG新概念龙虾-WeClaw 开发团队负责人一群专注于跨平台 AI 应用的实践者理念“再复杂的技术也能用代码讲清楚” 项目地址https://github.com/wyg5208/weclaw.git 官网地址https://weclaw.link 作者 CSDNhttps://blog.csdn.net/yweng18⭐ 欢迎 Star⭐、Fork、贡献代码 摘要本文结构概览从 2026 年 AI 工程领域最核心的范式演进——Agent Model Harness出发系统介绍 Harness Engineering 的六层架构模型Prompt → Context → Tools → Orchestration → Multi-Agent → Safety Observability然后以此框架对 WeClaw 进行逐层诊断给出 4.3/5.0 的综合成熟度评分并识别出 7 个关键差距领域。最后概述我们的 V3 迭代方案如何通过 4 个里程碑、8 个 Task 系统性对齐这些差距。核心问题当所有人都在追逐更强的模型时真正决定 Agent 表现的线束架构却被忽视。一个运行在粗糙 Harness 上的 GPT-4 级模型实际表现可能不如一个运行在精心设计 Harness 上的 GPT-3.5 级模型。我们如何评估自己的 Harness 成熟度差距在哪里如何系统性改进关键成果建立了 WeClaw 六层 Harness 成熟度雷达图识别出 7 个差距领域G1-G7按优先级排列规划了 M0→M4 的迭代路径1830 行新增代码 61 行 Hook 注入适合读者AI Agent 开发者、架构师、对 Agent 工程化感兴趣的技术决策者阅读时长约 20 分钟关键词Harness Engineering、六层架构、成熟度评估、ReAct 循环、Agent 工程、Hook 注入一、什么是 Harness Engineering1.1 从模型即一切到线束决定上限2026 年AI 工程领域发生了一个根本性的认知转变Agent Model Harness这个公式来自 OpenAI Codex 团队的三支柱框架和 Harness-Bench (arXiv:2605.27922) 的学术定义。它的核心命题是Agent 的能力上限不取决于模型本身而取决于它运行的线束架构。什么是线束Harness借用汽车工程的类比发动机Model再强大如果没有传动系统Context Pipeline、方向盘Orchestration、刹车Safety Guardrails和仪表盘Observability这辆车也开不起来。线束工程就是围绕模型构建的所有非模型组件的总和。1.2 六层架构模型Harness Engineering 将 Agent 的非模型组件划分为六个层次层次核心职责类比Prompt Layer参数化、动态提示词构建给发动机的点火指令Context Layer动态上下文管道、窗口管理、RAG燃油供给系统Tools Layer工具集 权限控制 渐进暴露变速箱和驱动轮Orchestration Layer路由、安全护栏、状态管理方向盘和刹车Multi-Agent Layer多 Agent 专业化协作多车协同编队Safety Observability沙箱、审计、遥测仪表盘和行车记录仪这六层从下到上每一层都建立在前一层的基础上。一个成熟的 Agent 系统需要在这六个维度上同时达到较高水平。1.3 为什么现在重要在 2024-2025 年大多数 AI 应用还停留在调 API 拼 Prompt的阶段。但随着 Agent 的自主性越来越强——它们开始调用工具、修改文件、执行 shell 命令——线束的质量就成了决定成败的关键。Harness-Bench 的研究发现Agent 的五大失败模式中只有 36.4% 是模型能力不足导致的其余 63.6% 都可以通过 Harness 层面的工程改进来预防。二、WeClaw 六层 Harness 技术栈落实矩阵2.1 逐层诊断我们对 WeClaw 的代码库进行了系统性审计逐层评估 Harness 落实度第 1 层Prompt Layer — 参数化提示词体系维度WeClaw 实现成熟度参数化 System Promptprompts.py2732行包含意图分类提示词、工具选择提示词等★★★★动态 Prompt 渲染根据意图识别结果动态注入工具优先级标注[推荐]/[备选]/[禁用]★★★★安全提示注入prompt_security.py— 6 大类威胁模式检测★★★★压缩感知注解压缩后自动追加系统提示★★★评价已超越静态指令阶段实现了参数化和安全扫描但尚未达到完全自适应。第 2 层Context Layer — 上下文架构维度WeClaw 实现成熟度智能上下文压缩context_compressor.py1280行— 辅助LLM摘要替换 工具结果裁剪★★★★★Token 预算管理token_utils.py 压缩器内tail_token_budget尾部保护★★★★缓存感知压缩cache_aware_compression— DeepSeek 缓存命中成本 压缩成本时延迟压缩★★★★★RAG 检索增强完整向量检索管线Embedder VectorStore TextSplitter Parser★★★★经验记忆检索experience_store.py— SQLite ChromaDB 双引擎三层过滤★★★★评价这是 WeClaw Harness 中最成熟的一层。1280 行的 ContextCompressor 配合辅助 LLM 经济学低成本 qwen-turbo 做摘要加上缓存感知压缩的创新设计已达到业界领先水平。第 3 层Tools Layer — 工具集与权限控制维度WeClaw 实现成熟度工具注册系统统一 BaseTool 接口60 内置工具★★★★渐进式工具暴露tool_exposure.py412行— 推荐集→扩展集→全量集按意图置信度分层★★★★★工具调用前置校验tool_validator.py— 数量限制硬约束★★★MCP 协议桥接mcp_client.py— 将外部 MCP Server 工具转为 BaseTool★★★★评价渐进式工具暴露引擎是亮点创新——引导而非限制渐进而非决断的设计哲学与 Harness Engineering 的约束理念高度契合。不足在于前置校验器当前仅做数量限制参数格式校验和语义级约束尚未实现。第 4 层Orchestration Layer — 编排与恢复维度WeClaw 实现成熟度错误分类器error_classifier.py— 7种错误类型 5种恢复策略★★★★★降级链FallbackChain— 模型降级链管理防循环检测★★★★★重试策略RetryStrategy— 指数退避 随机抖动★★★★辅助模型经济学auxiliary_client.py— 独立预算管理$0.5/天★★★★★评价编排层是另一强项。错误分类→恢复策略→降级链的三级容错体系非常完整。第 5 层Multi-Agent Layer — 多 Agent 协作维度WeClaw 实现成熟度Agent 实例池agent_pool.py— 会话级隔离LRU淘汰全局速率限制★★★★Curator 自改进curator.py813行— 对话→技能自动沉淀 周期性维护★★★★★PWA 远程协同WebSocket 跨端消息路由★★★★评价Curator 自改进闭环是差异化亮点——对话经验自动沉淀为可复用技能。但当前多 Agent 协作更多是并行隔离模式尚未实现角色分工协作。第 6 层Safety Observability Layer — 安全与可观测维度WeClaw 实现成熟度提示注入防护prompt_security.py423行— 6大类威胁模式双扫描模式★★★★★权限管理三级风险LOW/MEDIUM/HIGH 三级策略★★★★审计日志audit.py832行— SQLite持久化 EventBus自动订阅★★★★★全链路追踪task_trace.py367行— 意图→工具暴露→调用序列→结果★★★★★评价安全与可观测层非常完整。832 行审计系统 367 行全链路追踪构成了纵深防御体系。2.2 综合评分WeClaw Harness 成熟度雷达图5分制 Prompt Layer ████████░░ 4.0 Context Layer ██████████ 5.0 ← 最强层 Tools Layer ████████░░ 4.0 Orchestration Layer █████████░ 4.5 Multi-Agent Layer ████████░░ 4.0 Safety Observability█████████░ 4.5 综合 Harness 成熟度 ████████░░ 4.3 / 5.04.3/5.0— 这是一个相当不错的分数。在六个维度中有三个达到了 4.5 以上Context、Orchestration、Safety没有一个低于 4.0。但 Harness Engineering 的核心理念是木桶效应。一个 5.0 分的 Context 层无法弥补一个 3.0 分的 Multi-Agent 协作层。Agent 的整体表现取决于最短的那块木板。三、对标 Harness-Bench五大失败模式Harness-Bench 定义了 Agent 执行对齐的五大失败模式。我们以此对照 WeClaw失败模式行业发生率WeClaw 防护覆盖度Contract/Format— 输出格式违约36.4%ToolCallValidator Schema 约束★★★Tool/Recovery— 工具失败后无法恢复24.6%ErrorClassifier FallbackChain★★★★★Evidence/Grounding— 证据不完整14.6%RAG ExperienceStore★★★★Artifact Commitment— 推理未落盘11.1%GeneratedFiles 管理 审计日志★★★State/Continuation— 状态丢失9.3%ContextCompressor Session 持久化★★★★关键发现Tool/Recovery 和 State/Continuation 覆盖最好但 Contract/Format 和 Artifact Commitment 是薄弱环节——这恰好指向我们的改进方向。四、七个关键差距领域基于上述诊断我们识别出 7 个需要改进的差距领域编号差距当前状态Harness 理想态优先级G1架构约束自动执行依赖 Prompt 引导CI/Linter 级确定性约束P1G2角色化多 Agent 协作会话级并行无角色分工Explorer/Planner/Coder/ReviewerP1G3熵管理Curator 做技能维护定期清理 文档一致性 死代码扫描P2G4自适应 Harness配置驱动根据历史成功模式自动调整P2G5Pre-completion Checklist无任务完成前强制自检清单P2G6Loop Detection无显式实现检测重复工具调用防止死亡循环P3G7Reasoning Sandwich统一推理强度规划/验证阶段高推理实现阶段中推理P3这 7 个差距不是平行的——它们之间有依赖关系G1约束引擎──→ G2角色协作Reviewer 需要 ConstraintEngine ↗ G5Checklist──→ G7Reasoning Sandwich需要 Checklist 触发标记 ↑ G6Loop Detection── 独立可与 G5 并行 G3熵管理── 独立后台运行 G4自适应── 需要数据积累最后启用五、迭代方案从 V1 到 V3 的演进5.1 三轮评审的淬炼我们的迭代方案经历了三轮严格评审V1 → V2三视角评审发现 6 个 Critical IssuesC1: 流式路径全面遗漏 → 双路径对称覆盖C2: Checklist continue 时序错误 → 移至正确位置C3: 架构原则矛盾 → Hook 注入 EventBus 辅助C4: RoleOrchestrator 集成缺陷 → SharedMemory 隔离 EventBusC5: Reasoning Sandwich 不可行 → 仅最终回复切换C6: LoopDetector 变量错误 → 修正方法名V2 → V3代码级深度评审发现 3 个阻塞项 5 个风险项B1:ExecutionTracker.get_recent_calls()方法不存在 → 新增B2:chat_stream缺少_validate_tool_relevance→ 补全B3: Reasoning Sandwichhas_tool_callsFalse逻辑矛盾 → 降级为实验性骨架R1-R5: 流式 UX、入口文件、EventBus 隔离、向后兼容、配置位置5.2 核心架构原则经过三轮评审淬炼我们确立了 6 条不可动摇的设计原则Hook 注入 EventBus 辅助核心控制流用直接 Hook信息通报用 EventBus配置驱动灰度所有功能默认关闭逐项开启独立模块 Hook 注入新功能独立.py模块Agent 仅做 hook 挂载15行Token 预算硬上限多 Agent 总 token ≤ 单 Agent 的 1.5 倍双路径对称覆盖_chat_impl和chat_stream必须同时覆盖依赖注入一致性由gui_app.py统一创建和注入引擎实例5.3 里程碑路线图M0Day 1-2: 前置基础设施修复 → ExecutionTracker.get_recent_calls()3行 → chat_stream 补全 _validate_tool_relevance10行 M1Week 1-2: 确定性约束 Pre-completion Checklist → ConstraintEngine~200行 CompletionChecklist~200行 → 零 token 成本纯规则改进 M2Week 3-4: Loop Detection 熵管理 → LoopDetector~180行 EntropyManager~250行 M3Week 5-7: 角色化多 Agent 自适应 Harness → RoleOrchestrator~300行 AgentRoles~150行 → TokenBudgetController~150行 AdaptiveHarness~250行 M4Week 8: Reasoning Sandwich 骨架 → ReasoningScheduler~150行仅骨架不注入总新增代码~1830 行新模块 ~61 行 agent.py Hook 注入六、为什么选择 Hook 注入而非重构这是整个方案中最关键的架构决策。我们考虑过三种方案方案优势风险结论重构为 Pipeline架构最优雅侵入性太高回归风险大❌ 否决LangGraph/AutoGen社区成熟外部依赖与 EventBus/AgentPool 不兼容❌ 否决Hook 注入 独立模块侵入性最小可灰度Agent 类持续膨胀✅ 采纳选择 Hook 注入的核心逻辑是WeClaw 的 agent.py 已经有 3296 行双 ReAct 路径运行稳定。与其推倒重来不如在关键位置插入 Hook让新功能以插件方式挂载。每个 Hook 注入点都遵循同一模式抽取私有方法供双路径复用在 ReAct 循环的特定位置调用方法内部判断功能是否启用未启用时直接返回原值零开销# 典型的 Hook 注入模式def_check_constraint(self,...):ifnotself._constraint_engine:returnFalse# 未启用零开销resultself._constraint_engine.validate(...)ifresult.statusREJECT:_batch.append(...)returnTrue# 被拦截returnFalse# 在 ReAct 循环中ifself._check_constraint(...):continue6.1 双路径对称覆盖的挑战WeClaw 有两条 ReAct 路径_chat_impl非流式和chat_stream流式。流式是桌面端和 PWA 的主要执行路径。代码级评审发现chat_stream路径遗漏了_validate_tool_relevance调用——这是一个现有系统的 Bug非流式路径有此校验但流式路径没有。这意味着流式模式下模型可能调用与当前意图无关的工具而不被拦截。这类双路径不对称问题在大型代码库中非常常见也是我们确立双路径对称覆盖原则的原因。七、系列文章导读本系列共 8 篇文章本文是开篇。后续 7 篇将分别深入每个差距维度编号主题对应差距核心看点#62本文总体技术分析全景六层模型评估 7 差距识别 迭代规划#63确定性约束引擎G1从 Prompt 引导到代码级强制的范式转变#64角色化多 Agent 协作G2Explorer/Planner/Coder/Reviewer 分工编排#65熵管理G3AI 系统的垃圾回收机制#66自适应 HarnessG4让系统从历史成功模式中学习#67Pre-completion ChecklistG5AI 的交付前自检清单#68Loop DetectionG6检测和中断 Agent 的死亡循环#69总结与展望全景迭代哲学 工程思考 未来路线其中 G7Reasoning Sandwich因为在代码级评审中发现根本性逻辑矛盾reasoning 模型不支持 function calling已被降级为实验性骨架将在 #69 总结篇中作为被否决的方案案例讨论。八、核心教训在结束本文之前分享我们在评估过程中获得的三个关键认知8.1 成熟度评估必须代码级仅看文档和配置文件你会得出过于乐观的结论。我们的 V2 方案在文档层面看起来完美无缺但代码级评审发现了 3 个阻塞项一个方法根本不存在一条路径遗漏了关键校验一个功能设计存在逻辑矛盾教训文档说有代码说没有——永远以代码为准。8.2 双路径是隐形陷阱WeClaw 的_chat_impl和chat_stream是两条独立的 ReAct 循环它们共享大部分逻辑但有微妙差异。任何新功能如果只覆盖一条路径就会在另一条路径上产生不对称行为。教训大型代码库中对称覆盖比单路径完美更重要。8.3 迭代评审的价值从 V1 到 V3我们经历了三轮评审V16 个 Critical架构级问题V23 个阻塞 5 个风险代码级问题V3可编码实施每一轮评审都发现了上一轮无法发现的问题——因为前一轮的问题修复后更深层次的问题才暴露出来。教训方案评审不是一次性活动而是渐进式收敛过程。 相关文章WeClaw_60_能力越强护栏越硬AI自主进化的安全边界工程与核能类比WeClaw_61_当AI把内部协议泄漏给用户DeepSeek_DSML标记污染content字段的全链路排查与修复本文是 WeClaw 专栏第四季的第 1 篇总第 62 篇。如果这篇文章对你有帮助欢迎给项目点个 Star ⭐
