1. 从每次都要重新教说起Harness 的可靠性困局如果你正在做 Agent 相关的开发大概率经历过这样的场景昨天调得好好的一个 Agent今天换了个任务跑行为就完全不一样了。你翻日志、改 prompt、调参数折腾半天终于跑通结果明天再跑又崩了。这种薛定谔的 Agent状态几乎是每个做 Agent 工程的人都会踩的坑。Harness 这个词在 Agent 圈子里最近被提得很多但很多人对它的理解还停留在包一层壳的层面。实际上Harness 在 Agent 工程里扮演的角色更像是约束层和编排层——它决定了 Agent 能调用哪些工具、以什么顺序调用、在什么条件下终止、出错后怎么恢复。换句话说Agent 是大脑Harness 是神经系统和骨骼。大脑再聪明如果神经系统不稳定整个系统就是不可靠的。而棘轮原理Ratchet Principle恰好是解决这个可靠性问题的核心思路。棘轮这个东西你可以在扳手、扎带、登山绳扣上见到——它的特点是只能往一个方向走不能倒退。每转一格就锁住一格不会因为外力而滑回去。把这个原理搬到 Harness 设计上意思就是每一次成功的执行路径都应该被固化下来成为后续执行的约束条件让系统只能越用越稳而不是每次都在随机游走。这篇文章要聊的就是怎么把棘轮原理落地到 Harness 的实际工程里。我会从核心机制拆解开始讲到具体的实现方案、踩过的坑、以及怎么验证你的 Harness 是不是真的在棘轮式地变可靠。不管你是刚接触 Agent 开发还是已经在做多智能体编排应该都能从中拿到一些可以直接用的东西。2. 棘轮原理在 Harness 里到底锁住了什么2.1 棘轮的核心机制单向累积不可回退先把这个概念讲透。棘轮原理的本质是状态的单向累积。在机械棘轮里齿爪卡住齿轮齿轮只能正转不能反转。在 Harness 工程里这个齿爪就是执行约束这个齿轮就是Agent 的行为空间。具体来说Harness 里的棘轮机制锁住的是三样东西工具调用的合法序列哪些工具可以在什么阶段被调用调用完之后必须接什么。比如一个数据查询工具调用完之后必须接一个校验步骤不能直接跳到写操作。状态转移的合法路径Agent 从规划状态到执行状态到验证状态每一步的转移条件是什么什么情况下不允许跳转。失败恢复的收敛方向出错之后恢复策略必须是收敛的不能出现重试导致状态更混乱的情况。这三样东西一旦被棘轮锁住Agent 的行为空间就会随着执行次数的增加而单调收窄——不是变窄到不能用而是把那些已经被证明会出问题的路径逐步排除掉。2.2 为什么不回退比能回退更重要很多人第一反应是能回退不是更灵活吗Agent 出错了让它退回去重来不就行了这个想法在简单场景下没问题但在复杂 Agent 编排里是灾难性的。原因很简单回退会引入状态不确定性。你退回到某个检查点但外部环境已经变了工具返回的数据已经变了这时候重来的结果和第一次完全不一样。更糟糕的是如果回退逻辑本身有 bugAgent 可能在两个状态之间反复横跳陷入死循环。棘轮原理的不回退不是说不让 Agent 纠错而是说纠错的方式不是回退而是前进到下一个更受约束的状态。打个比方你走迷宫走错了一条路棘轮机制不是让你退回起点而是把这条错路标记为死路然后从当前位置选择一条新的、之前没走过的路。这样你的搜索空间是单调递减的不会重复踩同一个坑。2.3 Harness 中棘轮的三个层级在实际工程里棘轮可以作用在三个不同的层级上每个层级的粒度和影响范围不一样层级锁住的对象粒度典型实现方式工具层单个工具的调用前置条件和后置效应细工具包装器 前置校验流程层多步骤之间的转移规则中状态机 转移守卫会话层跨会话的经验累积粗持久化约束库 加载机制工具层的棘轮最容易实现也最容易被忽略。很多人写工具包装器的时候只做了参数校验没做调用上下文校验。比如一个发送消息的工具你只校验了消息内容非空但没校验当前是否已经过了审批状态。这就是棘轮没锁住。流程层的棘轮是大多数 Agent 框架真正缺失的部分。大部分框架给你的是一个自由跳转的状态图Agent 可以在任意两个状态之间跳。棘轮要求你给每条边加上单向守卫——走过去可以走回来不行除非满足特定的升级条件。会话层的棘轮是最有价值的也是最难做的。它要求你把每次会话中被证明有效的约束持久化下来下次会话加载时自动生效。这就是为什么你的 Harness 能越用越可靠——它不是靠模型变聪明而是靠约束库变厚。3. 把棘轮装进 Harness从状态机到约束累积的落地路径3.1 用带守卫的状态机替代自由跳转最直接的落地方式是把 Agent 的执行流程建模成一个带守卫的有向无环图DAG而不是一个自由的状态图。每个节点是一个执行阶段每条边是一个转移边上挂一个守卫函数。守卫函数的签名大概长这样def guard_transition(context: ExecutionContext, from_state: str, to_state: str) - bool: 返回 True 表示允许转移False 表示拒绝。 拒绝时Harness 应该记录一次棘轮事件并选择备选路径。 # 检查前置条件 if not context.has_completed_required_steps(from_state): return False # 检查是否违反单向约束 if context.has_visited(to_state) and not context.allow_revisit(to_state): return False # 检查资源约束 if context.remaining_budget() estimate_cost(to_state): return False return True关键点在于has_visited和allow_revisit这两个检查。默认情况下allow_revisit返回 False意味着已经走过的状态不能再走。这就实现了棘轮的单向性。只有当你显式地把某个状态标记为可重入比如一个幂等的查询步骤才允许回访。这个设计带来的直接好处是Agent 不会在规划-执行-规划-执行之间无限循环。它要么前进到验证阶段要么在规划阶段就失败退出。执行路径的长度是有上界的。3.2 约束累积让每次失败都变成下一次的护栏光有状态机还不够因为状态机的守卫条件是静态的。棘轮原理的精髓在于动态累积——每次执行产生的失败信息应该被转化成新的约束加到守卫条件里。具体做法是维护一个约束库Constraint Store结构大概是这样class ConstraintStore: def __init__(self, persist_path: str): self.path persist_path self.constraints self._load() def add_from_failure(self, failure: FailureRecord): 从一次失败中提取约束 constraint { type: failure.category, # 比如 tool_sequence_violation condition: failure.trigger, # 触发条件 action: block, # 阻止还是警告 scope: failure.scope, # 作用范围工具级/流程级/会话级 created_at: now(), hit_count: 0 } # 去重如果已有相同约束只增加计数 existing self._find_similar(constraint) if existing: existing[hit_count] 1 # 命中次数超过阈值升级为硬约束 if existing[hit_count] 3: existing[action] block else: self.constraints.append(constraint) self._save() def check(self, context) - list: 检查当前上下文是否违反任何约束 violations [] for c in self.constraints: if c[action] block and self._matches(c, context): violations.append(c) return violations这个约束库有几个设计要点值得展开说。第一约束的来源必须是结构化的失败记录而不是原始日志。你不能直接把报错信息塞进约束库那样约束会爆炸式增长且互相矛盾。你需要一个失败分类器把失败归到有限的几个类别里工具序列违规、状态转移违规、资源超限、输出格式不符、外部依赖失败。每个类别对应一种约束模板。第二约束要有软化和硬化的机制。新提取的约束默认是软约束只警告不阻止当同一个约束被命中超过阈值次数后自动升级为硬约束直接阻止。这个阈值我一般设 3实测下来比较平衡——既能快速收敛又不会因为偶发问题误伤。第三约束库必须持久化而且要能跨会话加载。这是越用越可靠的关键。每次 Harness 启动时先从磁盘加载约束库把硬约束注入到守卫函数里。这样昨天踩过的坑今天不会再踩。3.3 失败恢复的收敛设计不允许越恢复越乱棘轮原理对失败恢复有一个硬性要求恢复后的状态必须比失败前的状态更受约束。换句话说恢复不能是回到原点重来而必须是带着新约束前进。实现这个要求需要在恢复策略里加一个约束增量检查def recover(failure, context): # 提取约束 new_constraints extract_constraints(failure) # 检查恢复后是否至少新增了一条约束 if not new_constraints: # 没有新约束说明这次失败没有被学习 # 这种情况下不允许简单重试必须升级处理 return escalate_to_human(failure) # 把新约束加入上下文 context.constraints.extend(new_constraints) # 从失败点继续而不是从头开始 return resume_from(failure.last_valid_state, context)这个逻辑看起来简单但它堵住了一个非常常见的坑无脑重试。很多 Agent 框架的默认恢复策略就是重试三次但重试的时候上下文没变约束没变结果大概率还是失败。棘轮式恢复要求每次重试都必须带着新的约束否则就不叫恢复叫碰运气。4. 实战中那些让 Harness 变脆的坑4.1 坑一约束库膨胀导致启动变慢我最早做约束累积的时候没做去重和过期机制结果跑了两个月约束库涨到几万条每次 Harness 启动要加载十几秒守卫函数检查一遍要几百毫秒。Agent 的响应速度直接崩了。后来加了三层治理相似约束合并用条件表达式的结构哈希做去重相同结构的约束只保留一条用hit_count记录命中次数。冷约束淘汰超过 30 天没有被命中的软约束自动归档到冷存储不参与实时检查。约束索引按scope和type建索引守卫函数只检查当前上下文相关的约束而不是全量遍历。治理之后约束库稳定在几百条的活跃规模启动时间回到毫秒级。4.2 坑二硬约束误伤正常路径有一次我把一个工具 A 之后不能直接调工具 B的约束硬化了结果发现某些合法场景下就是需要 A 之后调 B。原因是这个约束是从一次特定上下文的失败里提取的但作用范围被错误地设成了全局。这个坑的教训是约束的作用范围必须尽可能窄。提取约束的时候要把失败时的上下文特征比如任务类型、输入数据特征、当前状态一起记录下来约束只在匹配这些特征时才生效。全局硬约束是最后手段能不用就不用。我现在的做法是给每个约束加一个context_signature字段守卫函数检查约束时先匹配签名签名不匹配就跳过。这样同一个工具序列在不同任务类型下可以有不同的约束。4.3 坑三棘轮锁死了探索能力棘轮原理有个天然的副作用约束越多Agent 能走的路越少。如果约束累积太快太猛Agent 会变得畏手畏脚什么都不敢做最后连正常任务都完不成。我遇到过一次极端情况一个 Agent 跑了几天之后几乎所有工具调用都被硬约束挡住了因为历史上每次调用都出过某种错。这就是过度棘轮化。解决办法是引入探索配额每次会话允许一定比例的绕过约束操作这些操作会被标记为探索性执行如果成功对应的约束会被降级或删除如果失败约束会被加强。这样系统在收敛和探索之间保持平衡。class ExplorationQuota: def __init__(self, ratio0.1): self.ratio ratio self.used 0 def can_explore(self, total_steps): return self.used total_steps * self.ratio def record_exploration(self, constraint_id, success): self.used 1 if success: # 探索成功降级约束 downgrade_constraint(constraint_id) else: # 探索失败加强约束 strengthen_constraint(constraint_id)这个配额比例我一般设 10%实测下来既能保持收敛趋势又不会把路走死。4.4 坑四跨会话约束加载的顺序问题约束库持久化之后加载顺序会影响守卫函数的判断结果。如果两条约束互相矛盾一条说允许一条说阻止先加载哪条决定了最终行为。我踩过的坑是新约束加载后覆盖了旧约束但旧约束其实更宽松、更合理。结果系统行为突然变严一堆正常任务失败。现在的做法是给约束加优先级和时间戳加载时按优先级排序同优先级按时间戳倒序新的优先。同时加一个冲突检测步骤加载时如果发现两条约束在相同上下文下结论相反就标记为冲突人工介入或者自动降级较新的那条。5. 怎么验证你的 Harness 真的在棘轮式变可靠5.1 三个可量化的指标光说变可靠了没用得有指标。我一般看三个数约束命中率守卫函数检查时有多少比例的检查触发了约束。这个数应该随着运行次数增加而先升后稳。升说明在学到东西稳说明约束库收敛了。首次通过率Agent 第一次尝试就完成任务的比率。棘轮机制生效的话这个数应该单调上升。恢复收敛步数从失败到恢复成功的平均步数。棘轮式恢复应该让这个数逐步下降因为每次恢复都带着更多约束不需要反复试错。这三个指标我建议做成仪表盘每次 Harness 版本更新后对比看。如果首次通过率不升反降说明约束累积出了问题大概率是误伤了正常路径。5.2 用回放测试验证约束有效性除了线上指标还需要离线验证。做法是把历史执行记录存下来每次约束库更新后用历史记录做回放看新约束会不会阻止那些曾经成功的执行路径。如果一条新约束阻止了历史成功路径那它大概率是误伤的需要重新审视作用范围。这个回放测试我一般跑最近 1000 条成功记录误伤率超过 1% 就要人工检查。def replay_test(constraint_store, success_records): false_positives [] for record in success_records: violations constraint_store.check(record.context) if violations: false_positives.append((record.id, violations)) fp_rate len(false_positives) / len(success_records) if fp_rate 0.01: alert(f约束误伤率过高: {fp_rate:.2%}) return false_positives5.3 棘轮健康度检查清单最后给一个我日常用的检查清单每次 Harness 大版本更新前过一遍检查项合格标准不合格的处理活跃约束数量100-500 条过多则归档冷约束过少则检查提取逻辑硬约束占比不超过 30%过高说明软化机制失效约束平均命中次数大于 2过低说明约束太细碎回放误伤率小于 1%过高则收窄约束作用范围探索配额使用率5%-15%过低说明约束太松过高说明太紧跨会话加载耗时小于 100ms过高则加索引或分片这套清单跑下来基本能保证你的 Harness 是在棘轮式地变可靠而不是在随机漂移。6. 一个最小可用的棘轮 Harness 实现骨架把上面的东西串起来给一个可以直接抄的骨架。这个骨架不依赖任何特定 Agent 框架你可以把它套在现有的执行循环外面。class RatchetHarness: def __init__(self, constraint_store_path: str, exploration_ratio: float 0.1): self.store ConstraintStore(constraint_store_path) self.quota ExplorationQuota(exploration_ratio) self.visited_states set() self.execution_log [] def execute(self, agent, task, max_steps50): context ExecutionContext(tasktask) state planning for step in range(max_steps): # 1. 检查约束 violations self.store.check(context) if violations and not self.quota.can_explore(step): # 硬约束阻止尝试备选路径 alternative self._find_alternative(state, context, violations) if alternative is None: return self._fail_with_learning(context, violations) state alternative continue # 2. 执行当前状态 try: result agent.step(state, context) self.execution_log.append((state, result)) except Exception as e: # 3. 失败恢复提取约束带着约束前进 failure FailureRecord.from_exception(e, state, context) self.store.add_from_failure(failure) recovery_state self._recover_state(failure, context) if recovery_state is None: return self._fail_with_learning(context, [failure]) state recovery_state continue # 4. 状态转移带守卫 next_state self._next_state(state, result, context) if next_state is None: return self._success(context) if not self._guard(state, next_state, context): # 转移被守卫拒绝记录棘轮事件 self._record_ratchet_event(state, next_state, context) continue self.visited_states.add(state) state next_state return self._fail_with_learning(context, [max_steps_exceeded]) def _guard(self, from_state, to_state, context): # 单向性检查 if to_state in self.visited_states and not context.allow_revisit(to_state): return False # 约束检查 if self.store.check(context): return False return True这个骨架的核心就是四个动作检查约束、执行、失败学习、带守卫转移。你可以根据自己用的 Agent 框架把agent.step和_next_state替换成框架对应的接口。实际用的时候我建议先从一个很小的约束集开始比如只锁工具调用序列这一层跑一段时间看指标再逐步扩展到流程层和会话层。一上来就全量棘轮化大概率会因为约束误伤导致 Agent 不可用。另外提醒一点约束库的持久化格式建议用 JSON Lines 而不是单个 JSON 文件因为追加写比全量重写快得多而且不容易因为写入中断导致整个库损坏。每条约束一行加载时逐行解析坏行跳过并告警。这套东西我在几个 Agent 项目里跑了半年多最直观的感受是Agent 的可靠性不再依赖模型本身有多强而是依赖约束库有多厚。模型换代的时候约束库可以直接迁移新模型在老约束下跑起步就比裸跑稳得多。这大概就是棘轮原理在 Harness 工程里最大的价值——它把经验变成了可累积、可迁移、可验证的工程资产而不是散落在 prompt 和日志里的玄学。
