尧图网页设计 
Hi带娃的我热爱AI 大模型应用落地、意识解码与 AI 开发工具链。 创业路上用技术换时间一起把 AI 变成生产力 WeClaw_63_确定性约束引擎从Prompt引导到代码级强制的范式转变第四季系列文章第 2 篇总第 63 篇- Constraint Engine · 确定性校验 · 语义级约束 · Hook 注入 · 零 token 成本 专栏信息《从零到一构建跨平台 AI 助手WeClaw 实战指南》专栏 ·第四季专栏定位面向开发者和技术决策者的实战专栏用真实案例和完整代码带你理解如何构建生产级 AI 应用本文深入探讨 Harness Engineering 七大差距中的 G1——架构约束自动执行。我们将从为什么 Prompt 引导不够用出发设计一个确定性约束引擎ConstraintEngine在工具执行前进行语义级校验并将这一过程以零 token 成本嵌入 ReAct 循环。 作者与项目作者简介翁勇刚 WENG YONGGANG新概念龙虾-WeClaw 开发团队负责人一群专注于跨平台 AI 应用的实践者理念“再复杂的技术也能用代码讲清楚” 项目地址https://github.com/wyg5208/weclaw.git 官网地址https://weclaw.link 作者 CSDNhttps://blog.csdn.net/yweng18⭐ 欢迎 Star⭐、Fork、贡献代码 摘要本文结构概览从 Agent 执行中的约束失灵现象出发——模型明明在 System Prompt 中被告知不要直接调用底层 shell 执行危险命令却仍然反复违反——分析 Prompt 引导的局限性然后设计 ConstraintEngine一个在工具执行前进行语义级确定性校验的规则引擎。重点讲解如何通过 Hook 注入嵌入 ReAct 循环、如何与现有的 ToolCallValidator 和 _validate_tool_relevance 协同工作以及如何在前置基础设施修复M0的基础上实现零 token 成本的约束执行。核心问题当你告诉 LLM “请在file工具中指定合法路径”它有时候听有时候不听。Prompt 是建议不是约束。如何将关键约束从建议升级为强制关键成果设计了 ConstraintEngine 的核心数据结构和规则集明确了 ToolCallValidator → _validate_tool_relevance → ConstraintEngine 的三层校验链通过 Hook 注入实现双路径对称覆盖零 token 成本适合读者AI Agent 开发者、对 LLM 约束控制感兴趣的工程师阅读时长约 15 分钟关键词ConstraintEngine、确定性约束、Hook 注入、ReAct 循环、语义校验、零 token 成本一、问题现场 —— Prompt 引导的失灵时刻1.1 一个典型的约束失灵场景用户要求 Agent 修改一个配置文件。Agent 的执行序列如下Step 1: file.read(config/default.toml) ✅ 合理 Step 2: file.write(config/default.toml, ...) ✅ 合理 Step 3: file.write(config/default.toml, ...) ⚠️ 重复编辑同一文件 Step 4: file.write(config/default.toml, ...) ⚠️ 又一次 Step 5: file.write(config/default.toml, ...) ❌ 第5次了 Step 6: shell.execute(rm temp/*) ❌ 危险命令在 System Prompt 中我们明确告诉了模型“不要重复编辑同一文件超过 3 次”、“shell 工具禁止执行 rm 命令”。但模型还是做了。1.2 为什么 Prompt 引导不够Prompt 引导有三个根本性局限局限说明类比概率性遵守LLM 会理解约束但不保证100%执行告诉孩子不要碰热 stove但孩子有时还是会碰上下文稀释长对话中早期约束被后续上下文淹没第50条消息时第1条的约束已经模糊不可审计约束被违反时没有拦截记录出了事才知道没有提前预警核心洞察Prompt 是给模型看的说明书不是给系统执行的交通规则。说明书可以被忽略交通规则不行。1.3 现有校验器的不足WeClaw 已有两层校验但它们都不够工具调用请求 │ ▼ ToolCallValidator ← 只检查数量max_per_call3 │ PASS ▼ _validate_tool_relevance ← 只检查工具与意图的相关性 │ PASS ▼ 执行工具 ← ⚠️ 这里有语义级空白ToolCallValidator只管调了多少个_validate_tool_relevance只管这个工具跟意图有没有关系。但参数是否安全、依赖层级是否正确、是否重复编辑同一文件——这些语义级约束无人检查。二、设计 ConstraintEngine —— 确定性约束规则引擎2.1 核心数据结构dataclassclassConstraintRule:一条确定性约束规则。name:str# 规则名称severity:str# REJECT | WARNcheck_fn:Callable[[ToolCallContext],bool]# 校验函数message_template:str# 告警/拒绝消息模板dataclassclassToolCallContext:工具调用的完整上下文供规则函数使用。tool_name:straction_name:strarguments:dictcurrent_intent:strrecent_calls:list[tuple[str,str,str]]# 最近N次调用记录session_step:int# 当前步骤序号dataclassclassConstraintResult:约束校验结果。status:str# PASS | REJECT | WARNmessage:str# 告警/拒绝原因rule_name:str# 触发的规则名2.2 规则引擎核心classConstraintEngine:确定性约束规则引擎。在工具执行前由 ReAct 循环直接调用。def__init__(self):self._rules:list[ConstraintRule][]defvalidate(self,ctx:ToolCallContext)-ConstraintResult:逐条规则校验返回第一个 REJECT 或最后一个 WARN。last_warnNoneforruleinself._rules:ifrule.check_fn(ctx):ifrule.severityREJECT:returnConstraintResult(statusREJECT,messagerule.message_template.format(**ctx.__dict__),rule_namerule.name,)elifrule.severityWARNandnotlast_warn:last_warnConstraintResult(statusWARN,messagerule.message_template.format(**ctx.__dict__),rule_namerule.name,)iflast_warn:returnlast_warnreturnConstraintResult(statusPASS,message,rule_name)设计要点REJECT 优先遇到第一个 REJECT 立即返回不继续检查WARN 不阻断WARN 只记录告警不阻止执行零 token 成本全部是 Python 规则函数不调用 LLM2.3 初始规则集四条规则覆盖最常见的约束失灵场景def_build_default_rules()-list[ConstraintRule]:return[# 规则1依赖层级检查# 禁止低层工具直接调用高层 API如 shell 直接调用模型 APIConstraintRule(namedependency_layer_check,severityREJECT,check_fnlambdactx:(ctx.tool_nameshellandany(kwinstr(ctx.arguments.get(command,))forkwin[model_registry,agent_pool])),message_template禁止 shell 工具直接操作内部组件: {tool_name},),# 规则2输出格式检查# 文件生成类工具必须包含合法路径参数ConstraintRule(nameoutput_format_check,severityREJECT,check_fnlambdactx:(ctx.action_namein(write,create,save)andnotctx.arguments.get(path,)),message_template文件操作缺少合法 path 参数: {action_name},),# 规则3参数安全检查# shell 工具禁止危险命令模式ConstraintRule(nameparameter_safety_check,severityREJECT,check_fnlambdactx:(ctx.tool_nameshelland_has_dangerous_pattern(ctx.arguments.get(command,))),message_templateshell 命令包含危险模式: {tool_name},),# 规则4单任务文件编辑次数上限ConstraintRule(namemax_file_edits_per_task,severityWARN,check_fnlambdactx:(ctx.action_namein(write,edit)andsum(1forcinctx.recent_callsifc[0]fileandc[1]in(write,edit))20),message_template单任务文件编辑已达上限({session_step}步)请考虑合并操作,),]为什么 max_file_edits 是 WARN 而不是 REJECT因为重复编辑可能是合理的比如增量修改一个大文件我们只想提醒模型注意而不是强制阻断。三、三层校验链 —— 与现有系统的协同3.1 校验链全景工具调用请求 │ ▼ ① ToolCallValidator ← 数量限制max_per_call3 │ PASS ▼ ② _validate_tool_relevance ← 意图相关性file工具 vs casual_chat意图 │ PASS ▼ ③ ConstraintEngine ← 语义级约束本篇新增 │ PASS ▼ 执行工具三层校验各有职责互不重叠层级校验对象例子阻断方式ToolCallValidator数量“一次调了5个工具”REJECT_validate_tool_relevance意图相关性“casual_chat 意图调了 shell”REJECTConstraintEngine语义正确性“shell 执行了 rm”REJECT 或 WARN3.2 职责边界一个常见的设计陷阱是让 ConstraintEngine “什么都管”——这样会导致它变成一个上帝类。我们严格限定其边界✅管参数安全、依赖层级、输出格式、重复模式❌不管工具数量ToolCallValidator 的职责、意图匹配_validate_tool_relevance 的职责四、前置修复 —— M0 阻塞项解除4.1 为什么需要先修 ExecutionTrackerConstraintEngine 的max_file_edits_per_task规则需要查询最近 N 次调用记录。这些记录存储在ExecutionTracker.recent_success_calls字段中——但代码级评审发现这个字段没有公开的访问方法。# ExecutionTracker 现有代码agent.py L77-178classExecutionTracker:def__init__(self):self.recent_success_calls:list[tuple[str,str,str]][]# ...defrecord_success(self,tool_name,action_name,args_hash):self.recent_success_calls.append((tool_name,action_name,args_hash))# ...# ❌ 没有 get_recent_calls() 方法4.2 修复3 行代码defget_recent_calls(self,n:int3)-list[tuple[str,str,str]]:获取最近 N 次成功调用记录 (tool_name, action_name, args_hash)。returnself.recent_success_calls[-n:]看起来微不足道——3 行代码但它是一个阻塞项ConstraintEngine 依赖此方法没有它就无法获取上下文。4.3 另一个阻塞项chat_stream 路径遗漏代码级评审还发现chat_stream流式路径完全没有调用_validate_tool_relevance。这意味着流式模式下模型可以调用任何工具——即使与当前意图完全无关。# _chat_impl 路径非流式— 有校验 ✅is_relevant,reject_reasonself._validate_tool_relevance(tool_name,action_name)ifnotis_relevant:# ... 拒绝并 continue# chat_stream 路径流式— 无校验 ❌# 直接执行工具没有任何前置校验修复在chat_stream的工具执行循环中补全_validate_tool_relevance调用约10行使两条路径对称。关键洞察这种双路径不对称是大型代码库中最隐蔽的 Bug 类型。非流式路径有完整校验流式路径却遗漏了——而流式是桌面端和 PWA 的主要执行路径。五、Hook 注入 —— 嵌入 ReAct 循环5.1 抽取私有方法所有 Hook 注入点都抽取为私有方法供_chat_impl和chat_stream双路径复用def_check_constraint(self,tool_name,action_name,arguments,tc_id,_batch,step_idx,intent_result):ConstraintEngine 前置检查G1返回 True 表示被拦截应 continue。ifnotself._constraint_engine:returnFalse# 未启用零开销resultself._constraint_engine.validate(ToolCallContext(tool_nametool_name,action_nameaction_name,argumentsarguments,current_intentintent_result.primary_intent,recent_callsself._execution_tracker.get_recent_calls(3),session_stepstep_idx,))ifresult.statusREJECT:_batch.append((tool,result.message,{tool_call_id:tc_id}))returnTrue# 被拦截调用方应 continueifresult.statusWARN:logger.warning(ConstraintEngine WARN: %s (rule%s),result.message,result.rule_name)returnFalse# 放行5.2 注入位置在 ReAct 循环中ConstraintEngine 检查位于_validate_tool_relevance之后、工具执行之前# ReAct 循环中的工具处理两条路径共用模式# ① 数量校验validationself.tool_validator.validate(tool_calls)ifvalidation.statusREJECT:continue# ② 意图相关性校验is_relevant,reject_reasonself._validate_tool_relevance(tool_name,action_name)ifnotis_relevant:continue# ③ 语义约束校验新增 G1ifself._check_constraint(tool_name,action_name,arguments,tc_entry[id],_batch,step_idx,intent_result):continue# 被约束引擎拦截# ④ 执行工具resultawaitself.tool_registry.call_function(...)5.3 零开销保证当 ConstraintEngine 未启用时_check_constraint的第一行就返回False——没有任何额外计算。这保证了对现有系统的性能零影响。六、配置驱动灰度6.1 配置结构# config/default.toml — 添加在 [agent.trace] 之后 [agent.constraint_engine] enabled false # 默认关闭 max_file_edits_per_task 20 # 文件编辑上限 enable_dependency_check true # 依赖层级检查 enable_safety_check true # 参数安全检查6.2 灰度策略# gui_app.py _initialize_core_components() 中constraint_configagent_config.get(constraint_engine,{})ifconstraint_config.get(enabled,False):engineConstraintEngine()engine.load_rules_from_config(constraint_config)self._agent._constraint_engineengine logger.info(ConstraintEngine 已启用加载 %d 条规则,len(engine._rules))灰度路径第一周仅启用parameter_safety_check最安全拦截危险命令第二周追加output_format_check防止文件操作缺少路径第三周追加dependency_layer_check防止跨层调用第四周追加max_file_edits_per_taskWARN 模式观察误报率七、与现有安全体系的协同WeClaw 已有完善的安全体系ConstraintEngine 不是替代而是补充┌─────────────────┐ │ Prompt Security │ ← 输入侧检测恶意提示注入 └────────┬────────┘ │ ┌────────▼────────┐ │ Permission Manager│ ← 权限侧三级风险分类 └────────┬────────┘ │ ┌────────▼────────┐ │ Audit Logger │ ← 审计侧全量记录 └────────┬────────┘ │ ┌───────────────────────┼───────────────────────┐ │ │ │ ┌────▼─────┐ ┌──────▼──────┐ ┌──────▼──────┐ │ToolCall │ │_validate_ │ │Constraint │ │Validator │ │tool_relevance│ │Engine(新增) │ │(数量) │ │(意图匹配) │ │(语义约束) │ └──────────┘ └─────────────┘ └─────────────┘ConstraintEngine 的独特价值它是唯一能访问recent_calls上下文的校验器。其他校验器只看当前这一次调用而 ConstraintEngine 能看到最近 N 次调用——这使得重复模式检测成为可能。八、核心教训8.1 约束分两种建议性和强制性Prompt 是建议性约束——模型理解但不保证遵守。代码是强制性约束——绕不过去。关键约束必须两层都有Prompt 告诉模型为什么不应该做ConstraintEngine 确保它做不到。8.2 前置修复的价值M0 阶段只改了 13 行代码310但它们是整个方案的基石。如果没有先修get_recent_calls()ConstraintEngine 的核心规则就无法工作。最小阻塞项往往是最容易被忽视的。8.3 WARN 比 REJECT 更难设计REJECT 是非黑即白的——违反了就拒绝。WARN 是微妙的——什么时候该提醒提醒太频繁是噪音太稀疏是失职。我们选择max_file_edits_per_task作为唯一 WARN 规则正是因为它是建议但不强制的典型场景。 相关文章WeClaw_62_Harness工程全景六层模型评估与WeClaw 4.3分成熟度诊断WeClaw_60_能力越强护栏越硬AI自主进化的安全边界工程与核能类比本文是 WeClaw 专栏第四季的第 2 篇总第 63 篇。如果这篇文章对你有帮助欢迎给项目点个 Star ⭐ WeClaw_63_确定性约束引擎：从Prompt引导到代码级强制的范式转变
Hi带娃的我热爱AI 大模型应用落地、意识解码与 AI 开发工具链。 创业路上用技术换时间一起把 AI 变成生产力 WeClaw_63_确定性约束引擎从Prompt引导到代码级强制的范式转变第四季系列文章第 2 篇总第 63 篇- Constraint Engine · 确定性校验 · 语义级约束 · Hook 注入 · 零 token 成本 专栏信息《从零到一构建跨平台 AI 助手WeClaw 实战指南》专栏 ·第四季专栏定位面向开发者和技术决策者的实战专栏用真实案例和完整代码带你理解如何构建生产级 AI 应用本文深入探讨 Harness Engineering 七大差距中的 G1——架构约束自动执行。我们将从为什么 Prompt 引导不够用出发设计一个确定性约束引擎ConstraintEngine在工具执行前进行语义级校验并将这一过程以零 token 成本嵌入 ReAct 循环。 作者与项目作者简介翁勇刚 WENG YONGGANG新概念龙虾-WeClaw 开发团队负责人一群专注于跨平台 AI 应用的实践者理念“再复杂的技术也能用代码讲清楚” 项目地址https://github.com/wyg5208/weclaw.git 官网地址https://weclaw.link 作者 CSDNhttps://blog.csdn.net/yweng18⭐ 欢迎 Star⭐、Fork、贡献代码 摘要本文结构概览从 Agent 执行中的约束失灵现象出发——模型明明在 System Prompt 中被告知不要直接调用底层 shell 执行危险命令却仍然反复违反——分析 Prompt 引导的局限性然后设计 ConstraintEngine一个在工具执行前进行语义级确定性校验的规则引擎。重点讲解如何通过 Hook 注入嵌入 ReAct 循环、如何与现有的 ToolCallValidator 和 _validate_tool_relevance 协同工作以及如何在前置基础设施修复M0的基础上实现零 token 成本的约束执行。核心问题当你告诉 LLM “请在file工具中指定合法路径”它有时候听有时候不听。Prompt 是建议不是约束。如何将关键约束从建议升级为强制关键成果设计了 ConstraintEngine 的核心数据结构和规则集明确了 ToolCallValidator → _validate_tool_relevance → ConstraintEngine 的三层校验链通过 Hook 注入实现双路径对称覆盖零 token 成本适合读者AI Agent 开发者、对 LLM 约束控制感兴趣的工程师阅读时长约 15 分钟关键词ConstraintEngine、确定性约束、Hook 注入、ReAct 循环、语义校验、零 token 成本一、问题现场 —— Prompt 引导的失灵时刻1.1 一个典型的约束失灵场景用户要求 Agent 修改一个配置文件。Agent 的执行序列如下Step 1: file.read(config/default.toml) ✅ 合理 Step 2: file.write(config/default.toml, ...) ✅ 合理 Step 3: file.write(config/default.toml, ...) ⚠️ 重复编辑同一文件 Step 4: file.write(config/default.toml, ...) ⚠️ 又一次 Step 5: file.write(config/default.toml, ...) ❌ 第5次了 Step 6: shell.execute(rm temp/*) ❌ 危险命令在 System Prompt 中我们明确告诉了模型“不要重复编辑同一文件超过 3 次”、“shell 工具禁止执行 rm 命令”。但模型还是做了。1.2 为什么 Prompt 引导不够Prompt 引导有三个根本性局限局限说明类比概率性遵守LLM 会理解约束但不保证100%执行告诉孩子不要碰热 stove但孩子有时还是会碰上下文稀释长对话中早期约束被后续上下文淹没第50条消息时第1条的约束已经模糊不可审计约束被违反时没有拦截记录出了事才知道没有提前预警核心洞察Prompt 是给模型看的说明书不是给系统执行的交通规则。说明书可以被忽略交通规则不行。1.3 现有校验器的不足WeClaw 已有两层校验但它们都不够工具调用请求 │ ▼ ToolCallValidator ← 只检查数量max_per_call3 │ PASS ▼ _validate_tool_relevance ← 只检查工具与意图的相关性 │ PASS ▼ 执行工具 ← ⚠️ 这里有语义级空白ToolCallValidator只管调了多少个_validate_tool_relevance只管这个工具跟意图有没有关系。但参数是否安全、依赖层级是否正确、是否重复编辑同一文件——这些语义级约束无人检查。二、设计 ConstraintEngine —— 确定性约束规则引擎2.1 核心数据结构dataclassclassConstraintRule:一条确定性约束规则。name:str# 规则名称severity:str# REJECT | WARNcheck_fn:Callable[[ToolCallContext],bool]# 校验函数message_template:str# 告警/拒绝消息模板dataclassclassToolCallContext:工具调用的完整上下文供规则函数使用。tool_name:straction_name:strarguments:dictcurrent_intent:strrecent_calls:list[tuple[str,str,str]]# 最近N次调用记录session_step:int# 当前步骤序号dataclassclassConstraintResult:约束校验结果。status:str# PASS | REJECT | WARNmessage:str# 告警/拒绝原因rule_name:str# 触发的规则名2.2 规则引擎核心classConstraintEngine:确定性约束规则引擎。在工具执行前由 ReAct 循环直接调用。def__init__(self):self._rules:list[ConstraintRule][]defvalidate(self,ctx:ToolCallContext)-ConstraintResult:逐条规则校验返回第一个 REJECT 或最后一个 WARN。last_warnNoneforruleinself._rules:ifrule.check_fn(ctx):ifrule.severityREJECT:returnConstraintResult(statusREJECT,messagerule.message_template.format(**ctx.__dict__),rule_namerule.name,)elifrule.severityWARNandnotlast_warn:last_warnConstraintResult(statusWARN,messagerule.message_template.format(**ctx.__dict__),rule_namerule.name,)iflast_warn:returnlast_warnreturnConstraintResult(statusPASS,message,rule_name)设计要点REJECT 优先遇到第一个 REJECT 立即返回不继续检查WARN 不阻断WARN 只记录告警不阻止执行零 token 成本全部是 Python 规则函数不调用 LLM2.3 初始规则集四条规则覆盖最常见的约束失灵场景def_build_default_rules()-list[ConstraintRule]:return[# 规则1依赖层级检查# 禁止低层工具直接调用高层 API如 shell 直接调用模型 APIConstraintRule(namedependency_layer_check,severityREJECT,check_fnlambdactx:(ctx.tool_nameshellandany(kwinstr(ctx.arguments.get(command,))forkwin[model_registry,agent_pool])),message_template禁止 shell 工具直接操作内部组件: {tool_name},),# 规则2输出格式检查# 文件生成类工具必须包含合法路径参数ConstraintRule(nameoutput_format_check,severityREJECT,check_fnlambdactx:(ctx.action_namein(write,create,save)andnotctx.arguments.get(path,)),message_template文件操作缺少合法 path 参数: {action_name},),# 规则3参数安全检查# shell 工具禁止危险命令模式ConstraintRule(nameparameter_safety_check,severityREJECT,check_fnlambdactx:(ctx.tool_nameshelland_has_dangerous_pattern(ctx.arguments.get(command,))),message_templateshell 命令包含危险模式: {tool_name},),# 规则4单任务文件编辑次数上限ConstraintRule(namemax_file_edits_per_task,severityWARN,check_fnlambdactx:(ctx.action_namein(write,edit)andsum(1forcinctx.recent_callsifc[0]fileandc[1]in(write,edit))20),message_template单任务文件编辑已达上限({session_step}步)请考虑合并操作,),]为什么 max_file_edits 是 WARN 而不是 REJECT因为重复编辑可能是合理的比如增量修改一个大文件我们只想提醒模型注意而不是强制阻断。三、三层校验链 —— 与现有系统的协同3.1 校验链全景工具调用请求 │ ▼ ① ToolCallValidator ← 数量限制max_per_call3 │ PASS ▼ ② _validate_tool_relevance ← 意图相关性file工具 vs casual_chat意图 │ PASS ▼ ③ ConstraintEngine ← 语义级约束本篇新增 │ PASS ▼ 执行工具三层校验各有职责互不重叠层级校验对象例子阻断方式ToolCallValidator数量“一次调了5个工具”REJECT_validate_tool_relevance意图相关性“casual_chat 意图调了 shell”REJECTConstraintEngine语义正确性“shell 执行了 rm”REJECT 或 WARN3.2 职责边界一个常见的设计陷阱是让 ConstraintEngine “什么都管”——这样会导致它变成一个上帝类。我们严格限定其边界✅管参数安全、依赖层级、输出格式、重复模式❌不管工具数量ToolCallValidator 的职责、意图匹配_validate_tool_relevance 的职责四、前置修复 —— M0 阻塞项解除4.1 为什么需要先修 ExecutionTrackerConstraintEngine 的max_file_edits_per_task规则需要查询最近 N 次调用记录。这些记录存储在ExecutionTracker.recent_success_calls字段中——但代码级评审发现这个字段没有公开的访问方法。# ExecutionTracker 现有代码agent.py L77-178classExecutionTracker:def__init__(self):self.recent_success_calls:list[tuple[str,str,str]][]# ...defrecord_success(self,tool_name,action_name,args_hash):self.recent_success_calls.append((tool_name,action_name,args_hash))# ...# ❌ 没有 get_recent_calls() 方法4.2 修复3 行代码defget_recent_calls(self,n:int3)-list[tuple[str,str,str]]:获取最近 N 次成功调用记录 (tool_name, action_name, args_hash)。returnself.recent_success_calls[-n:]看起来微不足道——3 行代码但它是一个阻塞项ConstraintEngine 依赖此方法没有它就无法获取上下文。4.3 另一个阻塞项chat_stream 路径遗漏代码级评审还发现chat_stream流式路径完全没有调用_validate_tool_relevance。这意味着流式模式下模型可以调用任何工具——即使与当前意图完全无关。# _chat_impl 路径非流式— 有校验 ✅is_relevant,reject_reasonself._validate_tool_relevance(tool_name,action_name)ifnotis_relevant:# ... 拒绝并 continue# chat_stream 路径流式— 无校验 ❌# 直接执行工具没有任何前置校验修复在chat_stream的工具执行循环中补全_validate_tool_relevance调用约10行使两条路径对称。关键洞察这种双路径不对称是大型代码库中最隐蔽的 Bug 类型。非流式路径有完整校验流式路径却遗漏了——而流式是桌面端和 PWA 的主要执行路径。五、Hook 注入 —— 嵌入 ReAct 循环5.1 抽取私有方法所有 Hook 注入点都抽取为私有方法供_chat_impl和chat_stream双路径复用def_check_constraint(self,tool_name,action_name,arguments,tc_id,_batch,step_idx,intent_result):ConstraintEngine 前置检查G1返回 True 表示被拦截应 continue。ifnotself._constraint_engine:returnFalse# 未启用零开销resultself._constraint_engine.validate(ToolCallContext(tool_nametool_name,action_nameaction_name,argumentsarguments,current_intentintent_result.primary_intent,recent_callsself._execution_tracker.get_recent_calls(3),session_stepstep_idx,))ifresult.statusREJECT:_batch.append((tool,result.message,{tool_call_id:tc_id}))returnTrue# 被拦截调用方应 continueifresult.statusWARN:logger.warning(ConstraintEngine WARN: %s (rule%s),result.message,result.rule_name)returnFalse# 放行5.2 注入位置在 ReAct 循环中ConstraintEngine 检查位于_validate_tool_relevance之后、工具执行之前# ReAct 循环中的工具处理两条路径共用模式# ① 数量校验validationself.tool_validator.validate(tool_calls)ifvalidation.statusREJECT:continue# ② 意图相关性校验is_relevant,reject_reasonself._validate_tool_relevance(tool_name,action_name)ifnotis_relevant:continue# ③ 语义约束校验新增 G1ifself._check_constraint(tool_name,action_name,arguments,tc_entry[id],_batch,step_idx,intent_result):continue# 被约束引擎拦截# ④ 执行工具resultawaitself.tool_registry.call_function(...)5.3 零开销保证当 ConstraintEngine 未启用时_check_constraint的第一行就返回False——没有任何额外计算。这保证了对现有系统的性能零影响。六、配置驱动灰度6.1 配置结构# config/default.toml — 添加在 [agent.trace] 之后 [agent.constraint_engine] enabled false # 默认关闭 max_file_edits_per_task 20 # 文件编辑上限 enable_dependency_check true # 依赖层级检查 enable_safety_check true # 参数安全检查6.2 灰度策略# gui_app.py _initialize_core_components() 中constraint_configagent_config.get(constraint_engine,{})ifconstraint_config.get(enabled,False):engineConstraintEngine()engine.load_rules_from_config(constraint_config)self._agent._constraint_engineengine logger.info(ConstraintEngine 已启用加载 %d 条规则,len(engine._rules))灰度路径第一周仅启用parameter_safety_check最安全拦截危险命令第二周追加output_format_check防止文件操作缺少路径第三周追加dependency_layer_check防止跨层调用第四周追加max_file_edits_per_taskWARN 模式观察误报率七、与现有安全体系的协同WeClaw 已有完善的安全体系ConstraintEngine 不是替代而是补充┌─────────────────┐ │ Prompt Security │ ← 输入侧检测恶意提示注入 └────────┬────────┘ │ ┌────────▼────────┐ │ Permission Manager│ ← 权限侧三级风险分类 └────────┬────────┘ │ ┌────────▼────────┐ │ Audit Logger │ ← 审计侧全量记录 └────────┬────────┘ │ ┌───────────────────────┼───────────────────────┐ │ │ │ ┌────▼─────┐ ┌──────▼──────┐ ┌──────▼──────┐ │ToolCall │ │_validate_ │ │Constraint │ │Validator │ │tool_relevance│ │Engine(新增) │ │(数量) │ │(意图匹配) │ │(语义约束) │ └──────────┘ └─────────────┘ └─────────────┘ConstraintEngine 的独特价值它是唯一能访问recent_calls上下文的校验器。其他校验器只看当前这一次调用而 ConstraintEngine 能看到最近 N 次调用——这使得重复模式检测成为可能。八、核心教训8.1 约束分两种建议性和强制性Prompt 是建议性约束——模型理解但不保证遵守。代码是强制性约束——绕不过去。关键约束必须两层都有Prompt 告诉模型为什么不应该做ConstraintEngine 确保它做不到。8.2 前置修复的价值M0 阶段只改了 13 行代码310但它们是整个方案的基石。如果没有先修get_recent_calls()ConstraintEngine 的核心规则就无法工作。最小阻塞项往往是最容易被忽视的。8.3 WARN 比 REJECT 更难设计REJECT 是非黑即白的——违反了就拒绝。WARN 是微妙的——什么时候该提醒提醒太频繁是噪音太稀疏是失职。我们选择max_file_edits_per_task作为唯一 WARN 规则正是因为它是建议但不强制的典型场景。 相关文章WeClaw_62_Harness工程全景六层模型评估与WeClaw 4.3分成熟度诊断WeClaw_60_能力越强护栏越硬AI自主进化的安全边界工程与核能类比本文是 WeClaw 专栏第四季的第 2 篇总第 63 篇。如果这篇文章对你有帮助欢迎给项目点个 Star ⭐