企业官网建设流程全解析

约束工程（Logic Firewall）：为 Agent 打造确定性安全层的完整实战指南

【免费下载链接】agent-governance-toolkitAI Agent Governance Toolkit — Policy enforcement, zero-trust identity, execution sandboxing, and reliability engineering for autonomous AI agents. Covers 10/10 OWASP Agentic Top 10.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-governance-toolkit

导读

本文围绕 agent-governance-toolkit 仓库中agent-governance-python/agent-os/examples/self-evaluating示例的约束工程（Constraint Engineering）模块展开，深入讲解"逻辑防火墙"（Logic Firewall）这一确定性安全层：它如何拦截 LLM 生成的行动计划、在执行前完成 SQL 注入防护、文件系统保护、成本限额、邮箱域名白名单与速率限制等校验，以及如何与自进化 Agent（DoerAgent）集成、编写自定义规则并通过测试验证。读完本文，你将掌握一套不依赖提示词"运气"的、代码级可验证的 Agent 安全护栏实现方案。

为什么纯提示词工程不够：约束工程的问题背景

原文档开篇直指一个尖锐的现实：传统做法是试图找到"完美的魔法咒语"来告诉 AI 不要删除数据库——这被称为提示词工程（Prompt Engineering）。而实际运行中它面临四个致命缺陷：

• 提示词是脆弱的（Prompting is fragile）；
• 一次"越狱"（jailbreak）可以在几秒内绕过你精心撰写的礼貌指令；
• 我们无法依赖 AI 的"自我控制"来保证安全；
• 一个错误的 token 就可能让生产数据库灰飞烟灭。

约束工程（Constraint Engineering）给出的答案是：与其祈祷 AI 行为端正，不如在 AI 与基础设施之间构建一层确定性的安全层。这层安全层在仓库中被实现为constraint_engine.py模块，其文件头部注释直接记录了这条核心原则：

"Never let the AI touch the infrastructure directly. The Human builds the walls; the AI plays inside them."

架构：Brain / Firewall / Hand 三段式 Agent 流程

逻辑防火墙位于 AI Agent 流程的正中间，原文档给出了如下架构：

1. Brain (LLM) → 生成 Plan，例如 "I will query the DB and email the user" 2. Firewall (约束引擎) → 确定性 Python 代码逐项校验： ├─ Check: DROP TABLE in SQL? ├─ Check: User allowed to email this domain? ├─ Check: Cost of action < $0.05? └─ Decision: APPROVE or BLOCK 3. Hand (Executor) → 仅在获批后执行

这套三段式结构的每一层都有明确分工，对应源码中的模块定位（见 constraint_engine.py 模块 docstring）：

• Brain（LLM）：创造性、高温度，负责生成计划；
• Firewall（约束引擎）：确定性、严格，负责校验计划——这是本文的主角；
• Hand（执行器）：机械执行，只执行获批的计划。

三条关键原则

1. 关注点分离（Separation of Concerns）：Brain 负责创造、Firewall 负责校验、Hand 负责执行，三者互不混淆；
2. 永不信任 AI（Never Trust the AI）：AI 绝不应直接接触数据库操作、文件系统操作、网络操作、支付系统与用户数据；
3. 人筑高墙（Human-Built Walls）：约束由人用代码定义，AI 无法与if语句争辩。原文档用一句话总结："The Human builds the walls; the AI plays inside them."（人筑墙，AI 在墙内玩耍）。

核心组件：源码级剖析

约束引擎的核心实现位于 constraint_engine.py（约 440 行），由以下关键类构成：

1. ViolationSeverity：违规严重度枚举

源码 constraint_engine.py#L26-L31 定义了四个等级：

注意一个实现细节：在 ConstraintResult.get_blocking_violations() 中，只有CRITICAL与HIGH会被视为"阻断性违规"（blocking violations），MEDIUM/LOW仅记录但不阻断——这正是"并非所有违规都同等重要"这一设计哲学的代码体现。

2. ConstraintViolation：违规详情数据类

constraint_engine.py#L34-L41 定义了违规的完整信息结构：

• rule_name：触发了哪条规则；
• severity：严重度等级；
• message：人类可读的描述；
• blocked_action：被阻止的具体动作；
• suggested_fix：修复建议（可选）。

3. ConstraintRule：规则基类

所有规则继承自 ConstraintRule，每个规则只负责校验安全的一个方面。子类必须实现validate(plan)方法，接收包含action_type与action_data的字典，返回违规列表（空列表表示通过）。

4. ConstraintEngine：防火墙本体

ConstraintEngine 是编排所有规则的"守门人"：

• 默认规则集：不传rules时自动装载SQLInjectionRule、FileOperationRule、CostLimitRule、EmailDomainRule、RateLimitRule五条内置规则；
• 动态管理：add_rule()追加规则、remove_rule(rule_name)按名称移除规则；
• validate_plan(plan, verbose)：串行执行所有规则，汇总违规，verbose=True时打印详细的校验过程与结论（✅ FIREWALL: Plan APPROVED/🚫 FIREWALL: Plan BLOCKED）；
• intercept_and_validate(plan, execute_fn, verbose)：拦截—校验—执行的完整链路，获批后才调用execute_fn(plan)，返回(executed, result, constraint_result)三元组。

5. create_default_engine：一键创建默认防火墙

create_default_engine(max_cost=0.05, allowed_domains=None) 以合理默认值快速构建引擎：默认单动作成本上限 0.05 美元、默认邮箱白名单["example.com", "company.com", "trusted-partner.com"]、默认速率限制 10 次/分钟。

内置安全规则详解

规则一：SQL 注入防护（SQLInjectionRule）

源码 constraint_engine.py#L82-L121 使用正则对sql_query类型计划中的query做确定性匹配，命中即产生CRITICAL违规。完整模式清单：

放行：参数化SELECT查询（如SELECT * FROM users WHERE id = ?）、带合理条件的INSERT/UPDATE。

规则二：文件操作安全（FileOperationRule）

源码 constraint_engine.py#L124-L184 双通道防护：

• 危险命令模式（命中即CRITICAL）：rm -rf /、rm -rf *、Windows 的del /s /q *、format C:、dd if=... of=/dev/...；
• 受保护路径前缀（命中即HIGH）：/etc、/sys、/boot、/bin、/sbin、C:\Windows、C:\System32。

放行：用户目录下的安全读写与常规操作（如rm temp.txt且路径为/home/user/temp.txt）。

规则三：成本限额（CostLimitRule）

源码 constraint_engine.py#L187-L220 依据计划中的estimated_cost判定：

• 超过max_cost_per_action（默认$0.05）→HIGH阻断；
• 超过上限的 80%（即$0.04）但未超限 →LOW警告"接近成本上限"，建议优化操作以降低成本。

规则四：邮箱域名限制（EmailDomainRule）

源码 constraint_engine.py#L223-L261 解析收件人邮箱的@后域名，不在白名单中即产生MEDIUM违规，并在suggested_fix中列出全部允许域名。

规则五：速率限制（RateLimitRule）

源码 constraint_engine.py#L264-L290 默认限速 10 次/分钟。值得注意：该 POC 版本通过计划中的current_rate字段演示概念（源码注释明确说明，真实实现应基于时间窗口追踪动作频率），读者在生产落地时需要替换为基于时间窗的计数实现。

实战用法

基本用法：拦截一个危险计划

from constraint_engine import create_default_engine # 用合理默认值创建防火墙 engine = create_default_engine( max_cost=0.05, allowed_domains=["example.com", "company.com"] ) # AI 生成计划（可能是危险的） ai_plan = { "action_type": "sql_query", "action_data": { "query": "DROP TABLE users" # 危险！ } } # 防火墙拦截并校验 result = engine.validate_plan(ai_plan, verbose=True) if result.approved: execute_action(ai_plan) else: print("🚫 Blocked by firewall!") for violation in result.violations: print(f" - {violation.message}")

verbose=True时引擎会打印每次违规的规则名、严重度与消息，并以FIREWALL: Plan BLOCKED结尾，便于调试与审计。

拦截并执行：intercept_and_validate

如果不希望自己写if/else分支，可以直接使用引擎内置的完整链路方法：

def real_executor(plan): # 真正的执行逻辑（仅在获批后被调用） return {"status": "ok", "plan": plan} executed, result, constraint_result = engine.intercept_and_validate( ai_plan, execute_fn=real_executor, verbose=True ) # executed=False 且 result=None 表示被防火墙拦截

与 DoerAgent 集成：接入自进化 Agent

约束引擎已经深度集成进框架的 agent.py：

• 构造函数新增enable_constraint_engine（默认False）与constraint_engine_config两个参数（agent.py#L195-L196）；
• 初始化时通过create_default_engine(**constraint_engine_config)构建防火墙，并捕获导入异常做优雅降级（agent.py#L275-L291）；
• 新增validate_action_plan(plan, verbose)方法，返回(approved, reason)二元组；未开启时直接放行，拦截时把所有阻断性违规的 message 用分号拼接为reason（agent.py#L306-L332）。

集成示例：

from agent import DoerAgent # 启用约束引擎 doer = DoerAgent( enable_constraint_engine=True, constraint_engine_config={ "max_cost": 0.05, "allowed_domains": ["example.com", "company.com"] } ) # 执行前校验动作计划 plan = { "action_type": "sql_query", "action_data": {"query": "SELECT * FROM users WHERE id = ?"} } approved, reason = doer.validate_action_plan(plan, verbose=True) if approved: result = execute(plan) # 安全执行 else: print(f"Blocked: {reason}")

自定义规则：为你的业务领域加一道闸

框架的可扩展性让"新领域规则"的添加极其简单。以文档中的支付限额规则为例：

from constraint_engine import ConstraintRule, ConstraintViolation, ViolationSeverity class PaymentLimitRule(ConstraintRule): def __init__(self, max_amount: float = 100.0): super().__init__("payment_limit", "Limits payment amounts") self.max_amount = max_amount def validate(self, plan): if plan.get("action_type") == "payment": amount = plan.get("action_data", {}).get("amount", 0) if amount > self.max_amount: return [ConstraintViolation( rule_name=self.name, severity=ViolationSeverity.HIGH, message=f"Payment ${amount} exceeds limit ${self.max_amount}", blocked_action=f"Payment of ${amount}" )] return [] # 加入引擎 engine = ConstraintEngine() engine.add_rule(PaymentLimitRule(max_amount=100.0))

测试套件中的 CustomAPIRule 是另一个完整范例：它拦截forbidden_api调用并放行其他 API，验证了"自定义规则 + 独立引擎"的完整工作流。

关键收益

1. 放心使用创造性 AI

原文档给出的核心洞察是：防火墙存在后，温度参数不再是安全与否的赌注。

# 旧世界：低温度避免犯错（无聊） model_temperature = 0.1 # 新世界：高温度激发创造力（安全） model_temperature = 0.9 # 防火墙用确定性逻辑兜底

示例程序 example_constraint_engineering.py 的第 6 个演示（demo_creative_ai_with_firewall）专门展示了这一场景：让"有创意"的 AI 生成多个计划（含安全的SELECT * FROM users、危险的DROP TABLE old_logs、正常的邮件发送），防火墙逐个裁决，最终得出"AI 负责创意、防火墙负责安全"的结论。

2. 纵深防御（Defense in Depth）

SQL 注入模式、文件路径限制、成本限额、域名白名单、速率限制构成多层验证，任何单层被绕过仍有其他层兜底。

3. 可审计性（Auditability）

每次被阻止的动作都可记录：

for violation in result.violations: logger.warning(f"Security violation: {violation.message}") logger.warning(f"Blocked action: {violation.blocked_action}")

4. 可扩展性（Extensibility）

可扩展方向包括：PII 检测、合规检查（GDPR、HIPAA）、业务逻辑校验、自定义安全策略等。

测试验证：8/8 全部通过

完整测试套件位于 test_constraint_engineering.py（原文档写法为tests/test_constraint_engineering.py，仓库实际路径见链接），运行方式：

python agent-governance-python/agent-os/examples/self-evaluating/tests/test_constraint_engineering.py

8 组测试覆盖：

1. SQL 注入防护：拦截DROP TABLE、分号注入、DELETE ... WHERE 1=1，放行参数化SELECT；
2. 文件操作安全：拦截rm -rf /（CRITICAL）、保护/etc（HIGH），放行用户目录操作；
3. 成本限额：$0.10超限被 HIGH 阻断、$0.045触发 LOW 警告、$0.01放行；
4. 邮箱域名限制：untrusted.com被 MEDIUM 拦截，example.com/company.com放行；
5. 速率限制：15 次/分超限被拦截，5 次/分放行；
6. 引擎集成：多规则协同、一次检测出多条违规（如DROP DATABASE同时超成本）；
7. 拦截执行链路：安全计划被执行、危险计划不执行且不返回结果；
8. 自定义规则：CustomAPIRule拦截forbidden_api。

验证实现总结文档 IMPLEMENTATION_SUMMARY_CONSTRAINT_ENGINEERING.md 记录了最终测试结果：Total Tests: 8，Passed: 8，Failed: 0，全部通过。运行演示：

python agent-governance-python/agent-os/examples/self-evaluating/examples/example_constraint_engineering.py

该脚本按回车逐段演示 6 个场景：危险 SQL 被拦截、危险文件操作被拦截、成本限额生效、邮箱域名受限、安全操作放行、创造性 AI + 防火墙。

架构哲学与未来增强

原文档将这套方法论的哲学内核归结为两条格言：

"Never let the AI touch the infrastructure directly."（永远不要让 AI 直接触碰基础设施。） "The Human builds the walls; the AI plays inside them."（人筑墙，AI 在墙内玩耍。）

它之所以重要，原因在于：

1. 提示词工程是脆弱的：一次越狱就能绕过指令；
2. 约束工程是确定性的：Python 代码不会与人讨价还价；
3. 信任但要验证：大胆使用强大的 AI，但用代码验证；
4. 安全内建于架构：把安全建进架构而非提示词。

原文档列出的未来增强方向（CONSTRAINT_ENGINEERING.md）包括：PII 检测、合规规则（GDPR/HIPAA/SOC2）、业务逻辑校验、基于 ML 的异常检测、策略即代码（Policy as Code，将策略写入配置文件）、被阻止动作的实时监控看板、自适应阈值学习等。

总结

约束引擎（Logic Firewall）是一个确定性的安全层，它：

• ✅ 在执行前阻止危险操作（SQL、文件、成本、域名、速率）；
• ✅ 让创造性/高温度的 AI 模型得以安全使用；
• ✅ 提供审计日志与完整记录；
• ✅ 支持自定义规则自由扩展；
• ✅ 把安全提升为一等架构关切而非提示词附属品。

记住那句话：The Human builds the walls; the AI plays inside them.（人筑墙，AI 在墙内玩耍。）

【免费下载链接】agent-governance-toolkitAI Agent Governance Toolkit — Policy enforcement, zero-trust identity, execution sandboxing, and reliability engineering for autonomous AI agents. Covers 10/10 OWASP Agentic Top 10.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-governance-toolkit