跳转至

运行框架工程

概述

运行框架工程（harness engineering）是一门设计和维护辅助系统的实践——这套系统由围绕编码智能体的各类引导机制与传感器组成，旨在提升输出结果的可信度。智能体运行框架（harness）页面介绍了运行框架"是什么"及其核心组件，本页则聚焦于"如何工程化地构建"——包括心智模型、控制结构、调节分类，以及为编码智能体构建有效外层运行框架的实践模式。

一个构建良好的运行框架有两个目标：一是提高智能体首次即可成功的概率；二是建立自我修正的反馈闭环，在问题进入人工审查之前尽可能多地将其拦截。最终效果是：减少审查负担，提升系统质量，减少 Token 浪费。

本文的框架思路来源于 Birgitta Böckeler（Thoughtworks，2026 年 4 月），她将控制论概念应用于运行框架设计。

"运行框架"的有界语境

"harness"（运行框架）一词在不同语境下含义不同：

  • 模型级运行框架：除模型本身以外的所有内容（LangChain 的宽泛定义——参见智能体运行框架）
  • 构建者运行框架：编码智能体产品的创建者内置于产品中的运行框架（系统提示词、代码检索、编排）
  • 用户运行框架：使用编码智能体的团队围绕该智能体构建的外层运行框架，专为其代码库和规范定制

面向编码智能体用户的运行框架工程，聚焦于用户运行框架——即团队为其特定系统构建的各类控制机制。

前馈与反馈

运行框架通过两种互补的控制类型发挥作用：

控制类型 方向 目的 示例
引导机制（前馈） 在智能体执行前 预判不期望的输出；主动引导行为 AGENTS.md、技能、参考文档、编码规范、启动脚本
传感器（反馈） 在智能体执行后 观察输出结果；实现自我修正 代码检查器、类型检查器、测试运行器、AI 代码审查智能体、浏览器自动化

仅使用反馈机制，智能体会不断重复同样的错误。仅使用前馈机制，规则虽然被编码进去，却从不验证是否生效。两者缺一不可。

计算型控制与推理型控制

控制机制在执行类型上也有所不同：

类型 执行方式 速度 可靠性 最适用于
计算型 CPU——确定性执行 毫秒到秒级 可靠、一致 测试、代码检查器、类型检查器、结构分析、依赖扫描
推理型 GPU/NPU——基于 LLM 较慢、成本较高 非确定性 语义分析、AI 代码审查、LLM 充当评审、丰富的引导内容

计算型传感器成本低廉，可随智能体对每次变更同步运行。推理型传感器能提供语义判断，但应有选择性地使用——适合在集成后流水线中运行，或用于确定性工具无法胜任的高价值检查。

一种尤为强大的模式：专为 LLM 消费优化输出的推理型传感器——自定义检查器消息内嵌修复指令，这实际上是一种积极形式的提示词注入，直接进入智能体的自我修正闭环。

引导闭环

人类的职责是通过迭代优化运行框架本身来引导智能体。当问题反复出现时，正确的应对方式是改进前馈或反馈控制机制——而非加强监督。

智能体可以参与这个闭环：编码智能体能够编写结构性测试、从观察到的模式生成规则草案、搭建自定义检查器的脚手架，以及通过代码库考古生成操作指南。这使得构建自定义控制的成本逐步降低。

时机：将质量保障前移

运行框架控制应根据成本、速度和关键程度分布于开发生命周期的各个阶段——与 CI/CD 中测试左移的原则相同。

提交前 / 智能体运行期间： - 快速代码检查器、类型检查器、基础代码审查智能体 - 前馈引导（AGENTS.md、技能、LSP 集成）

集成后流水线： - 重复所有快速控制 - 增加成本较高的传感器：变异测试、广泛的架构审查、详细的推理型审查

持续进行 / 不依附于变更周期： - 漂移检测：死代码、测试覆盖质量、依赖扫描 - 运行时反馈：SLO 监控、响应质量采样、日志异常检测

调节分类

运行框架在三个不同维度上对代码库进行调节，各维度的可运行框架化程度和复杂度差异显著。

可维护性运行框架

调节内部代码质量：重复代码、复杂度、测试覆盖率、风格、架构漂移。这是最成熟的分类——现有工具（代码检查器、覆盖率工具、ArchUnit）可直接对应。

计算型传感器能可靠捕获的内容：重复代码、圈复杂度、测试覆盖缺失、架构漂移、风格违规。

推理型传感器能部分应对的内容：语义重复代码、冗余测试、暴力修复、过度工程化的解决方案——但成本较高且只能概率性覆盖，无法做到每次提交都检查。

两者都难以可靠捕获的内容：问题误判、过度工程化、指令理解偏差。这些需要人工判断。

架构适应性运行框架

通过适应性函数调节架构特性：

  • 前馈性能需求的技能 + 回归性能的反馈测试
  • 描述可观测性规范（日志标准）的技能 + 要求智能体反思日志质量的调试指令
  • 强制模块边界规则的自定义检查器 + 作为预提交钩子运行的结构性测试

OpenAI Codex 团队的做法是一个具体案例：通过自定义检查器和结构性测试强制执行分层领域架构，并定期运行"垃圾回收"智能体扫描漂移、开出有针对性的重构 PR。

行为运行框架

这是最难的分类——调节应用程序是否在功能上按预期运行。

当前的常见方法： - 前馈：功能规格说明（从简短提示词到多文件描述） - 反馈：AI 生成的测试套件 + 覆盖率检查 + 人工测试

这种方法对 AI 生成的测试寄予了相当大的信任，但对于高置信度的自主交付而言尚且不够。经批准的测试夹具模式在特定领域展现出潜力，但并非通用解决方案。行为运行框架仍是一个尚待解决的问题。

可运行框架化程度

并非每个代码库都同等适合被运行框架化。提升可运行框架化程度的属性：

  • 强类型：类型检查器自动成为可用传感器
  • 清晰可定义的模块边界：支持架构约束规则
  • 有明确倾向的框架：将智能体无需推理的细节抽象掉
  • "无聊"的技术选型：稳定的 API、高训练数据覆盖、可组合的抽象

Ned Letcher（Thoughtworks）将这些环境的结构性属性称为环境可供性（ambient affordances）——它们使环境对智能体而言清晰可读、易于导航、便于处理。

绿地项目与遗留系统的权衡：绿地项目团队可以从第一天就将可运行框架化程度设计进去——技术和架构选型决定了代码库的可治理程度。遗留系统团队面临更棘手的问题：运行框架越需要的地方，往往越难构建。

运行框架模板

企业级团队通常只有少量常见的服务拓扑（例如，基于 JVM 的 CRUD 业务服务、Go 编写的事件处理器、Node 构建的数据看板），这些拓扑覆盖约 80% 的需求。它们有望演变为运行框架模板：为特定拓扑的结构、规范和技术栈预配置好引导机制与传感器的捆绑包。

团队可能越来越多地根据现有运行框架的可用性来选择技术栈和架构。这也是Ashby 必要多样性定律的应用：调节器必须拥有至少与被调节系统同等的多样性。锁定某一拓扑可以缩小智能体的输出空间，使得构建一个全面的运行框架更具可行性。

人类的角色

人类开发者为每个代码库都带来了一套隐性运行框架：内化的规范、审美判断、组织记忆和社会责任感。编码智能体完全没有这些——没有"这里我们不这么做"的直觉，不知道哪些技术债务因商业原因而被容忍，也感知不到一个 300 行的函数是个问题。

运行框架是一种尝试，旨在将人类开发者经验所提供的内容外化并显式化。但这样做只能走到一定程度。一个好的运行框架的目标，不是完全消除人工输入，而是将人类的注意力引导到最重要的地方。

最佳实践

挑战 / 领域 描述 解决方案 / 建议
纯前馈运行框架 规则已编码但从不验证 始终将引导机制与传感器配对使用；两者缺一不可
纯反馈运行框架 智能体重复犯同样的错误 增加前馈引导，主动预防已知失效模式
每次提交都运行昂贵的传感器 推理型传感器拖慢循环 每次变更运行计算型传感器；推理型传感器留给集成后或高价值检查
传感器消息未针对 LLM 优化 通用错误消息无助于智能体自我修正 在自定义检查器消息中内嵌修复指令
行为运行框架缺口 AI 生成的测试被无条件信任 在适用场景下辅以经批准的测试夹具模式；对关键路径保留人工测试
运行框架一致性漂移 随着运行框架扩展，引导机制与传感器相互矛盾 将运行框架视为系统整体；定期审查冲突；借助智能体协助维护
遗留代码库的可运行框架化程度 最需要运行框架之处往往最难构建 优先覆盖高风险领域；逐步引入可运行框架化改善

循环不变量

以下内容应在运行框架代码中强制执行，而非在提示词中约定：

  1. 每次工具调用都恰好对应一个结果。
  2. 工具参数在执行前经过解析和验证。
  3. 每个副作用执行前都需完成权限决策。
  4. 工具结果有边界、有结构、可追溯。
  5. 循环具有严格的步数、时间、Token、成本和工具调用预算上限。
  6. 最终答案基于实际观测结果，而非对工具成功执行的假设。
  7. 错误、拒绝、取消和超时都转化为结构化观测结果——绝不悄悄吞掉。

重试策略

只对安全的失败重试。这一区分在操作层面至关重要：

通常可以安全重试： - 短暂的模型 API 错误 - 只读调用的网络超时 - 幂等的检索操作 - 模型修正格式错误参数后的验证失败

不得自动重试： - 支付或金融操作 - 外部发送（电子邮件、Slack、Webhook） - 破坏性操作（删除、覆写） - 权限变更 - 幂等性不明确的操作

对于高风险操作，应使用幂等键和审批记录——而非依赖重试。

并行化规则

只对独立、只读、并发安全的工具调用进行并行化。

可以并行：搜索、读取、检索元数据、对独立记录分类、对独立文档做摘要。

必须串行：写入、发送、删除、金融操作、权限变更、Shell/进程执行、多步骤外部工作流提交。

如有疑问，选择串行。重复写入或发送的代价，高于顺序执行带来的延迟。

熵管理

智能体系统会随时间积累熵：过时的文档、重复的规则、薄弱的示例、废弃的工具，以及被后续运行模仿的低质量模式。应添加定期清理工作流：

清理类型 解决的问题
文档新鲜度扫描 过时的策略、版本号、API 签名
工具库存清理 未使用、重叠或过度授权的工具
质量评分更新 智能体表现已漂移的任务
过期计划归档 已完成或已放弃的计划污染活跃上下文
重复失败分析 持续出现的工具失败或提示词模式
回归评测补充 尚未被评测覆盖的生产环境事故

持续清理的成本，远低于等到漂移演变为系统性问题后再处理。

自动化运行框架优化

人工运行框架工程覆盖特定代码库的用户运行框架，但设计空间过于庞大，难以手工探索——检索逻辑、上下文预算、路由谓词、工具定义和完成条件的组合呈组合爆炸式增长。

Meta-Harness（Lee 等，2026 年）展示了一种互补方案：一个主动搜索运行框架代码的智能体外层循环，借助能访问历史候选方案源代码、评分和原始执行追踪的编码智能体实现。这解决了探索问题，同时仍受益于人工构建的起始运行框架。对运行框架工程师有参考价值的关键发现：

  • 执行追踪比评分更重要：向提案者提供原始追踪（而非压缩摘要），使其能够诊断具体失效模式并作出针对性修改
  • 发现的运行框架具有泛化能力：在某个模型上通过搜索得到的运行框架，可迁移到未见过的模型——运行框架质量部分独立于具体模型
  • 所有运行框架维度均可搜索：外层循环可在单次搜索中联合优化系统提示词、检索逻辑、上下文管理和工具定义

这使运行框架工程师的职责转向：（1）构建一个定义搜索空间的可用脚手架；（2）确保执行追踪的日志记录清晰；（3）设置代表目标分布的评测任务。完整架构和结果详见运行框架优化。

九大技术挑战（调研证据）

两项 2026 年调研（Meng 等，arXiv:2605.29682；Picrew 等，OpenReview TMLR）在运行框架各层识别出九大经实证支撑的挑战，并附有具体的严重程度数据：

# 挑战 运行框架层 关键指标
1 安全性与沙箱隔离 E, G 前沿模型容器逃逸率 15–35%（SandboxEscapeBench）
2 评测与基准测试 V 自动化评测假阴性率 28%（OSWorld）
3 协议标准化 T MCP 延迟：2–15 ms；A2A 延迟：50–200 ms
4 运行时上下文管理 C 基于 Schema 的技能注入：提升 +16.2 pp
5 工具调用与注册表 T 移除 80% 的工具的效果优于单独升级模型
6 记忆架构 S/C Mem0：与全上下文方案相比减少 90% Token
7 规划与推理 E, C 接口设计对性能的影响超过模型能力
8 多智能体协调 T, L 拜占庭容错在对抗性场景下仍未解决
9 计算经济性 E 平均每任务 100 万 Token（AgencyBench）；行业每周 13 万亿 Token 增长

完整的调研背景和运行框架完整性矩阵详见 LLM 运行框架调研。

开放性问题

  • 如何评测运行框架的覆盖率和质量？（类比测试的代码覆盖率和变异测试）
  • 随着运行框架扩展，如何保持引导机制与传感器的同步，防止相互矛盾？
  • 如果传感器从未触发，是代表质量高，还是检测能力不足？
  • 当指令与反馈信号冲突时，智能体能在多大程度上做出合理的权衡？
  • 有什么工具能帮助将前馈与反馈控制作为统一系统进行配置、同步和推理？
  • 自动化运行框架搜索（如 Meta-Harness）能否扩展到优化前馈/反馈控制结构本身，而不仅仅是检索和上下文管理？

参见

参考资料