Hi带娃的我热爱AI 大模型应用落地、意识解码与 AI 开发工具链。 创业路上用技术换时间一起把 AI 变成生产力 WeClaw_69_总结与展望Harness工程的迭代哲学与被否决的方案第四季系列文章第 8 篇总第 69 篇- 迭代哲学 · 三轮评审 · 被否决方案 · Reasoning Sandwich · 双路径对称 · 未来路线 专栏信息《从零到一构建跨平台 AI 助手WeClaw 实战指南》专栏 ·第四季专栏定位面向开发者和技术决策者的实战专栏用真实案例和完整代码带你理解如何构建生产级 AI 应用本文是第四季的收官之作回顾整个 Harness Engineering 对齐迭代的历程——从初始评估到 V3 最终方案总结三轮评审的淬炼过程深入分析被否决的方案特别是 Reasoning Sandwich 的降级提炼工程思考并展望未来路线。 作者与项目作者简介翁勇刚 WENG YONGGANG新概念龙虾-WeClaw 开发团队负责人一群专注于跨平台 AI 应用的实践者理念“再复杂的技术也能用代码讲清楚” 项目地址https://github.com/wyg5208/weclaw.git 官网地址https://weclaw.link 作者 CSDNhttps://blog.csdn.net/yweng18⭐ 欢迎 Star⭐、Fork、贡献代码 摘要本文结构概览回顾 WeClaw Harness Engineering 对齐迭代的完整历程——从 4.3/5.0 的初始评估到 V1 方案的 6 个 Critical Issues到 V2 的 3 个阻塞项再到 V3 的可编码实施。重点分析三轮评审中暴露的深层问题双路径不对称、流式不可逆性、API 契约假设错误。以 Reasoning Sandwich 的降级为案例讲解何时放弃一个设计的工程判断。最后展望未来路线——从增强型单 Agent到多 Agent 编排 确定性约束的范式演进。核心问题一个方案从看起来完美到可以编码实施中间需要经历什么为什么有些设计在文档层面成立在代码层面却崩溃关键成果提炼了三轮评审中的核心工程教训完整的 7 差距对齐路线图和状态总览Reasoning Sandwich 降级的深度反思未来 3-6 个月的技术演进方向适合读者关注 AI Agent 工程化的开发者、架构师、技术决策者阅读时长约 20 分钟关键词迭代哲学、三轮评审、被否决方案、Reasoning Sandwich、双路径对称、未来路线一、回顾从 4.3 分到 V3 方案1.1 评估结论在系列开篇#62我们对 WeClaw 进行了六层 Harness 成熟度评估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 分——一个不错的起点但远非终点。7 个差距领域G1-G7构成了迭代方向。1.2 V1 → V2 → V3 的淬炼历程V1 方案初始规划 ↓ 三视角评审 → 6 Critical 6 Warning 4 Suggestion V2 方案修订版 ↓ 代码级深度评审 → 3 阻塞项 5 风险项 V3 方案最终版→ 可编码实施每一轮评审都发现了上一轮无法发现的问题。这不是因为前面的评审不够认真而是因为修复了表层问题后更深层的问题才会浮出水面。就像一个洋葱你剥掉外面那层皮才能看到里面那层。二、三轮评审的核心发现2.1 V1 → V2架构级修正V1 方案最大的问题是只考虑了非流式路径。6 个 Critical Issues 中有 3 个与此相关编号问题根因C1chat_stream全面遗漏方案只描述了_chat_impl的注入点C2Checklistcontinue时序错误没有考虑add_assistant_message的执行顺序C5Reasoning Sandwich 不可行没有考虑 reasoning 模型不支持 function callingV2 修复确立了双路径对称覆盖原则——所有 Hook 注入必须同时覆盖_chat_impl非流式和chat_stream流式两条 ReAct 路径。2.2 V2 → V3代码级验证V2 方案在文档层面看起来完美但代码级评审发现了文档说有、代码说没有的问题编号问题发现方式B1ExecutionTracker.get_recent_calls()不存在读 agent.py L77-178发现只有字段无方法B2chat_stream缺少_validate_tool_relevance读 L2488-2530发现流式路径遗漏此校验B3Reasoning Sandwichhas_tool_callsFalse逻辑矛盾分析模型调用时序发现无法在调用前预知结果B1 的教训方案中写self._execution_tracker.get_recent_calls(3)看起来合理。但如果去读代码这个方法根本不存在——recent_success_calls是一个字段没有公开的访问方法。文档层面的合理性 ≠ 代码层面的可行性。B2 的教训这是一个潜伏的现有系统 Bug——非流式路径有_validate_tool_relevance校验流式路径没有。这意味着流式模式下模型可以调用任何工具而不被拦截。新功能注入前先修复现有路径的不对称。B3 的教训Reasoning Sandwich 希望在最终回复阶段切换到 reasoning 模型。但最终回复的标志是has_tool_calls False——这个值在模型调用返回后才知道。你无法在调用前就知道返回不会有工具调用。时序矛盾是最难发现的设计缺陷——它在逻辑上自洽但在时序上不可能。2.3 5 个实施风险项编号风险V3 修复R1流式 Checklist 用continue导致 UX 混乱改为后置告知模式R2依赖注入入口是gui_app.py而非assistant.py修正引用R3EventBus 不支持子实例为角色 Agent 创建独立EventBus()实例R4AgentPool 向后兼容风险GENERAL角色不传额外参数R5default.toml有编码乱码区域配置添加在[agent.trace]之后三、流式不可逆性 —— 最重要的工程发现3.1 问题的本质WeClaw 的流式路径通过yield delta_content实时将文本发送给用户。这意味着模型生成 好的我已经完成了修改。 → yield 好的 → 用户看到了 ✅ → yield 我已经完成了 → 用户看到了 ✅ → yield 修改。 → 用户看到了 ✅ → 此时检查 Checklist → 发现问题 → 但文本已经全部发给用户了无法回收 ❌这就像脱口而出了一句话——说出去的话泼出去的水你只能补充不能撤回。3.2 影响范围这个发现影响了两个关键设计决策CompletionChecklist 的流式策略#67非流式路径文本未发送可以continue重入循环 → 静默修正流式路径文本已发送只能yield追加告知提示 → 后置告知Reasoning Sandwich 的降级见第四节原计划在最终回复阶段切换到 reasoning 模型但流式路径下最终回复的文本已经在逐步 yield无法在 yield 开始前切换模型3.3 通用工程教训流式架构的不可逆性是一个通用约束——不仅影响 WeClaw也影响所有使用流式 LLM API 的应用操作流式下可行性替代方案拦截并重入❌ 文本已 yield后置告知撤回已发送文本❌ 单向流不可能切换模型中途❌ 已开始生成在下一步切换追加提示✅ 新的 yield后置告知模式四、被否决的方案 —— Reasoning Sandwich 降级全记录4.1 原始设想在 ReAct 循环中不同阶段使用不同推理强度的模型Step 1-5规划阶段 → DeepSeek-Reasoner高推理深度思考 Step 6-20执行阶段 → DeepSeek-V3中推理快速执行 Step 21-25验证阶段→ DeepSeek-Reasoner高推理严格审查三明治模型强-弱-强规划和验证用强推理执行用普通推理。4.2 第一轮评审V1→V2发现的问题问题1reasoning 模型不支持 function callingDeepSeek-Reasoner 是一个推理专用模型——它可以生成深思熟虑的文本但不能调用工具。这意味着它无法在规划阶段调用工具因为规划也需要调用搜索工具等。V2 的修复将 Reasoning Sandwich 限制在最终回复阶段——此时 Agent 已经完成了所有工具调用只需要生成最终文本回复。4.3 第二轮评审V2→V3发现的矛盾问题2时序矛盾即使限制在最终回复阶段仍然有时序问题# ReAct 循环中的关键代码简化responseawaitself.model_registry.call_model(messages,toolstools)# 调用完成后才知道 response 是否有 tool_callshas_tool_callslen(response.tool_calls)0# 如果 has_tool_calls False → 这是最终回复# 但模型切换需要在 call_model 之前决定# → 你不知道这次调用会不会有 tool_calls这是一个因果倒置你无法在调用前预知调用结果。4.4 降级决策V3 将 Reasoning Sandwich降级为实验性骨架classReasoningScheduler:阶段感知模型选择器实验性。 设计约束 - Reasoning 模型不支持 function calling仅用于纯文本生成 - 仅在 CompletionChecklist 触发的额外步骤中生效 此时明确无工具调用是 checklist 重入步骤 defshould_switch(self,is_checklist_retry:bool,step_idx:int)-str|None:仅当明确为 Checklist 重入步骤时才返回 reasoning model_key。ifnotis_checklist_retry:returnNoneifself._verification_model:returnself._verification_modelreturnNone关键设计is_checklist_retry True是一个已知的确定性信号——当 Checklist 拦截并重入循环时这一步明确是自检修正步骤不需要工具调用。此时可以安全切换到 reasoning 模型。4.5 联合启用条件V3 为 Reasoning Sandwich 设定了严格的启用条件非本方案范围CompletionChecklist 已稳定运行 2 周无误报在_chat_impl的 Checklistcontinue分支内添加模型切换逻辑调用时不传 tools 参数确保 reasoning 模型不需要 function calling4.6 教训总结教训说明文档 ≠ 实现方案文档上完美的设计可能在代码层面有根本性矛盾时序矛盾最隐蔽逻辑自洽不代表时序可行——先有鸡还是先有蛋在工程中也存在降级 ≠ 失败将设计降级为骨架不是失败而是更诚实的工程判断确定性信号最可靠不确定的信号如has_tool_calls不如确定性信号如is_checklist_retry五、其他被否决的方案5.1 否决清单方案为什么否决我们选择了什么重构_chat_impl为 Pipeline侵入性太高agent.py 3296行运行稳定Hook 注入侵入性最小LangGraph/AutoGen 替换编排外部依赖与 EventBus/AgentPool 架构不兼容自建 RoleOrchestratorToolRegistry 层面做角色限制影响所有 Agent 实例无法会话级隔离AgentPool 层面过滤独立进程实现熵管理过度设计asyncio.Task 已足够后台 TaskChecklist 用 LLM 判断token 成本高延迟不可控纯规则检查流式 Checklist 用 continue 重入文本已 yield 给用户continue 导致重复后置告知模式5.2 否决方案的共同特征被否决的方案都有一个共同特征它们看起来更优雅或更强大但实际风险不可控。Pipeline 重构更优雅——但回归风险大LangGraph 更强大——但与现有架构不兼容LLM Checklist 更智能——但成本和延迟不可控我们的选择标准是风险可控 架构优雅 功能强大。六、7 差距对齐状态总览6.1 路线图M0Day 1-2: 前置基础设施修复 → Task 0.1: ExecutionTracker.get_recent_calls()3行 ✅ 可立即实施 → Task 0.2: chat_stream 补全 _validate_tool_relevance10行✅ 可立即实施 M1Week 1-2: 确定性约束 Pre-completion Checklist → Task 1: ConstraintEngine~200行 ✅ 依赖 M0 → Task 2: CompletionChecklist~200行 ✅ 无依赖可与 Task 1 并行 M2Week 3-4: Loop Detection 熵管理 → Task 3: LoopDetector~180行 ✅ 无依赖 → Task 4: EntropyManager~250行 ✅ 无依赖 M3Week 5-7: 角色化多 Agent 自适应 Harness → Task 5: RoleOrchestrator~300行 AgentRoles~150行 TokenBudget~150行 → Task 6: AdaptiveHarness~250行 ⏳ 需 TaskTrace 数据积累 1-2 周 M4Week 8: Reasoning Sandwich 骨架 → Task 7: ReasoningScheduler~150行 ⏳ 实验性仅骨架不注入6.2 代码量汇总里程碑新模块新增行数agent.py 改动M0--13行M12~400~28行M22~430~10行M34~850~10行M41~150不注入合计9~1830~61行6.3 配置汇总# config/default.toml — 新增 7 个配置节 [agent.constraint_engine] # G1 enabled false [agent.completion_checklist] # G5 enabled false [agent.loop_detection] # G6 enabled false [agent.entropy_manager] # G3 enabled false [agent.roles] # G2 enabled false [agent.adaptive_harness] # G4 enabled false [agent.reasoning_sandwich] # G7实验性 enabled false所有功能默认关闭——逐项开启灰度上线。七、提炼六个工程原则从整个迭代过程中我们提炼出六个可复用的工程原则原则1双路径对称覆盖如果系统有两条执行路径如流式/非流式所有新功能必须同时覆盖两条路径。验证方法每次新增 Hook 注入点时在两条路径的代码中搜索同一方法名。原则2代码级验证优先方案文档的合理性不等于代码层面的可行性。每个设计决策都必须对照源码验证。验证方法对每个方案中的代码引用实际读取对应源文件确认方法/字段/签名存在。原则3Hook 注入优于架构重构在稳定系统中新增功能时侵入性最小的方案优先于最优雅的方案。验证方法评估方案时将改动范围和回归风险作为一级评估维度。原则4流式不可逆性流式输出的内容不可回收。所有在最终回复前的拦截逻辑在流式路径上需要替代方案。验证方法每个在_chat_impl中使用continue的逻辑检查chat_stream中是否可行。原则5降级优于崩溃当设计存在根本性矛盾时降级为骨架或实验性功能比强行实施更好。验证方法每个新功能都有明确的启用条件和降级策略。原则6配置驱动灰度所有新功能默认关闭逐项开启。每个功能有独立的配置节。验证方法检查每个新功能的配置项是否有enabled false默认值。八、未来路线8.1 短期1-3 个月M0-M2 实施完成前置修复、确定性约束、Checklist、Loop Detection、熵管理。预期收益Agent 执行可靠性提升 30-50%验证指标循环检测命中率、Checklist 触发率、约束引擎拦截率8.2 中期3-6 个月M3 实施角色化多 Agent 自适应 Harness。预期收益复杂任务成功率提升 40-60%验证指标角色化任务的 token 消耗 vs 单 Agent、任务完成率Reasoning Sandwich 联合启用在 Checklist 稳定后尝试在自检步骤中使用 reasoning 模型。前提Checklist 误报率 10%8.3 长期6-12 个月Harness-Bench 对标在 Harness-Bench 的五大失败模式上将 WeClaw 的防护覆盖率从平均 3.8 星提升到 4.5 星以上。社区反馈循环收集使用 WeClaw 的开发者反馈持续优化自适应 Harness 的模式挖掘算法。学术发表将 WeClaw 的 Harness 工程实践整理为案例研究论文——“From Prompt Engineering to Harness Engineering: An Iterative Approach to Agent System Alignment”。8.4 成熟度目标当前状态4.3/5.0 目标状态4.8/5.0 Prompt Layer 4.0 → 4.5自适应 Prompt Context Layer 5.0 → 5.0维持领先 Tools Layer 4.0 → 4.5ConstraintEngine Orchestration Layer 4.5 → 5.0Checklist LoopDetection Multi-Agent Layer 4.0 → 5.0RoleOrchestrator Safety Observability 4.5 → 5.0EntropyManager 综合成熟度 4.3 → 4.8九、给同行的建议如果你也在构建 Agent 系统并考虑 Harness Engineering 对齐以下是我们的建议9.1 先评估再规划后实施不要跳过评估直接做方案。WeClaw 的评估发现了 7 个差距——如果你不做评估可能只关注了 2-3 个遗漏了关键的差距。9.2 多轮评审逐层深入第一轮评审关注架构“方向对不对”第二轮评审关注代码“实现可不可行”第三轮评审关注细节“边界情况有没有处理”。9.3 尊重流式架构的约束如果你的系统有流式输出记住流式是不可逆的。所有在最终回复前的拦截逻辑都需要流式路径的替代方案。9.4 降级不是失败将功能降级为实验性骨架是一种成熟的工程判断。它意味着你承认了当前设计的局限性同时保留了未来改进的空间。9.5 配置驱动灰度永远不要一次开启所有新功能。每个功能有独立的enabled false配置逐项开启观察效果再决定下一个。十、系列总结第四季共 8 篇文章覆盖了 WeClaw Harness Engineering 对齐的完整旅程编号主题核心贡献#62总体技术分析六层模型评估框架 7 差距识别#63确定性约束引擎ConstraintEngine 设计 三层校验链#64角色化多 Agent 协作RoleOrchestrator EventBus 隔离 Token 预算#65熵管理EntropyManager 四类清理任务 空闲调度#66自适应 HarnessAdaptiveHarness 模式挖掘 安全边界#67Pre-completion Checklist双路径差异策略 流式不可逆性#68Loop Detection三级检测 渐进响应 锚定消息注入#69本文总结与展望迭代哲学 被否决方案 未来路线核心信息Agent Model Harness。当所有人都在追逐更强的模型时真正决定 Agent 表现的是它运行的线束架构。Harness Engineering 不是一次性工程而是一个持续迭代的过程——从评估到规划从实施到评审从 V1 到 V3每一步都在收敛到更好的方案。感谢阅读第四季系列。如果你在实践中也遇到了 Harness 工程相关的挑战欢迎在 GitHub 上讨论。 相关文章第四季全系列WeClaw_62_Harness工程全景六层模型评估与WeClaw 4.3分成熟度诊断WeClaw_63_确定性约束引擎从Prompt引导到代码级强制的范式转变WeClaw_64_角色化多Agent协作从并行隔离到Explorer_Planner_Coder_Reviewer分工编排WeClaw_65_熵管理AI系统的垃圾回收机制WeClaw_66_自适应Harness让系统从历史成功模式中学习WeClaw_67_Pre-completion_ChecklistAI的交付前自检清单WeClaw_68_Loop_Detection检测和中断Agent的死亡循环前三季精选WeClaw_60_能力越强护栏越硬AI自主进化的安全边界工程与核能类比WeClaw_61_当AI把内部协议泄漏给用户DeepSeek_DSML标记污染content字段的全链路排查与修复本文是 WeClaw 专栏第四季的收官之作总第 69 篇。如果这个系列对你有帮助欢迎给项目点个 Star ⭐