agent-">AI 编程 Agent 的工程化脚手架解析

一、从一个根本矛盾说起

大语言模型的能力在过去两年里飞速提升，代码生成、逻辑推理、多语言理解等基准测试上的表现不断刷新。但当你真正把一个大模型放进真实的软件工程任务里，会发现一个尴尬的事实：它只能接收 token，输出 token。

它不知道刚才建议修改的那个文件到底改对了没有，不知道测试套件是否通过，不知道上一轮报错的具体堆栈信息被丢到了哪里。它甚至不知道自己已经连续尝试了五次相同的修复方案，而每次都以同样的方式失败。

这意味着，无论模型本身多强，要让它成为一个能实际“干活”的编程 Agent，光靠模型是不够的。必须在模型之外搭建一套工程脚手架，把模型的输出与真实世界的执行结果连接起来，形成闭环。这套脚手架，业界通常称之为 Harness 层。

用一个简洁的公式来表达：

Model + Harness = Agent

模型提供推理与生成能力，Harness 提供执行、反馈、记忆与控制能力。二者结合，才构成一个完整的编程 Agent。

二、Harness 层到底包含什么

如果把模型比作一台高性能发动机，那么 Harness 就是传动系统、仪表盘、冷却系统和方向盘的总和。没有它，发动机再强也无法驱动车辆前行。

从工程实现的维度看，Harness 层至少需要覆盖以下几个核心模块。

2.1 Prompt 编排与上下文工程

模型不会自动理解一个代码仓库的结构。它需要有人把代码库的目录树、关键模块的职责说明、项目的编码规范、当前任务的描述、历史对话的摘要等信息，整理成模型能够消化的输入格式。

这项工作远比“拼一个字符串”复杂。它涉及：

• 信息筛选：一个大型仓库可能有数十万行代码，不可能全部塞进上下文窗口。需要根据当前任务动态选择相关文件片段。
• 格式组织：用结构化的方式呈现代码上下文，比如按文件路径分层、标注函数签名与依赖关系，让模型更容易定位关键信息。
• 规范注入：把项目的代码风格、命名约定、测试要求等以系统指令的形式注入，确保模型输出符合工程标准。

# 示意：上下文组装的基本逻辑
def build_context(task, repo_index, conversation_history):
    relevant_files = repo_index.search(task.keywords, top_k=20)
    repo_structure = repo_index.get_tree(max_depth=3)
    project_rules = load_project_conventions()
    context = {
        "system": project_rules,
        "repo_tree": repo_structure,
        "relevant_code": [f.read_snippet() for f in relevant_files],
        "history_summary": summarize(conversation_history),
        "current_task": task.description
    }
    return format_for_model(context)

2.2 工具调用：让模型的手伸到真实世界

模型本身不能执行 shell 命令、不能读写文件、不能运行测试。Harness 层需要提供一套工具接口，把模型输出的“意图”翻译成真实的系统操作。

典型的工具集合包括：

• 文件操作：读取指定路径的文件内容、写入修改后的代码、创建新文件、删除废弃文件。
• 命令执行：在受控环境中运行 shell 命令，比如编译、安装依赖、启动服务。
• 测试运行：调用测试框架执行单元测试或集成测试，并捕获结果。
• 代码搜索：在仓库中按符号、关键词或正则表达式检索代码位置。
• 版本控制：查看 diff、暂存变更、提交修改。

关键在于，这些工具的执行结果必须被结构化地回传给模型，而不是简单的“成功/失败”。比如测试失败时，需要把失败的测试用例名、断言信息、堆栈跟踪都整理好，作为下一轮对话的输入。

2.3 迭代控制与容错

一个真实的编程任务往往需要多轮修改才能完成。Harness 层需要设定合理的迭代策略：

• 最大轮次限制：防止模型陷入无限循环，通常设置一个上限（比如 20 轮），超过后终止并报告。
• 失败重试：当模型输出格式异常或工具执行出错时，自动进行有限次数的重试，并在重试时调整输入。
• 进度检测：判断模型是否在原地打转，比如连续多轮修改同一文件但没有进展，此时应主动干预。
• 回滚机制：当一轮修改导致更严重的错误时，能够回退到上一个稳定状态。

2.4 上下文摘要与压缩

多轮对话和大型代码库很容易撑爆模型的上下文窗口。Harness 需要具备摘要能力：

• 对话摘要：把之前的交互历史压缩成简洁的要点，保留关键决策和当前状态。
• 代码摘要：对暂时不相关但可能需要参考的模块，生成函数级别的摘要描述，而不是保留完整代码。
• 分层记忆：把信息分为“当前任务上下文”“近期历史”“长期知识”三层，按需加载。

2.5 测试失败回传与反馈闭环

这是 Harness 最核心的价值之一。当测试失败时，Harness 需要：

1. 捕获失败的详细信息（测试名称、断言差异、错误日志）。
2. 如果涉及前端或 UI，截取浏览器截图或 DOM 快照。
3. 将这些信息重新组织成模型可理解的输入，驱动下一轮修复。

# 示意：测试失败后的反馈组装
def on_test_failure(test_result, model_context):
    feedback = {
        "failed_tests": test_result.failed_cases,
        "error_logs": test_result.stderr,
        "screenshot": test_result.screenshot_path,
        "previous_attempts": model_context.recent_diffs
    }
    model_context.append_feedback(feedback)
    return model_context

2.6 记忆系统与子 Agent 协调

对于复杂的工程任务，单个 Agent 可能不够用。Harness 层可以支持：

• 跨任务记忆：记录之前解决过的问题、踩过的坑、项目特有的约定，避免重复犯错。
• 子 Agent 分工：把一个大任务拆解成多个子任务，分配给不同的子 Agent 并行处理。比如一个子 Agent 负责修改后端接口，另一个负责更新前端调用，还有一个负责补充测试。
• 协调与合并：子 Agent 完成各自任务后，Harness 需要检查冲突、合并变更、运行整体测试。

三、为什么 Harness 必须独立于模型

一个自然的问题是：为什么不把这些逻辑直接写进模型里，让模型自己学会调用工具、管理上下文？

原因在于迭代速度的不匹配。

模型训练一次需要大量的计算资源和时间，周期通常以月为单位。而 Harness 层的工程实践迭代非常快——今天发现一种更好的上下文组织方式，明天就可以上线验证；这周发现某个工具接口设计不合理，下周就能重构。

如果把 Agent 逻辑写死在模型里，每次调整都需要重新训练，这在工程上不可接受。分离 Harness 层，意味着工程团队可以独立于模型团队快速试错、持续优化。

此外，Harness 层还承担了安全性、可控性和可观测性的职责。比如限制模型可以执行的命令范围、记录每一步操作的审计日志、在出现异常时及时熔断。这些都不是模型本身擅长的事情。

四、构建 Harness 层的实践建议

如果你正在设计自己的 AI 编程 Agent，以下几点值得参考：

第一，把工具接口设计成幂等且可组合的。 每个工具应该职责单一，输入输出明确，便于模型理解和组合调用。

第二，反馈信息要丰富但不过载。 回传给模型的错误信息需要包含足够的定位线索，但也要做适当的摘要和过滤，避免把无关的噪音塞进去。

第三，迭代控制要有硬性边界。 设定最大轮次、最大 token 消耗、最大执行时间等硬限制，防止失控。

第四，记忆系统要分层设计。 不是所有信息都值得记住，也不是所有记忆都需要每次都加载。按任务相关性动态管理记忆的存取。

第五，可观测性从一开始就要考虑。 记录每一轮的输入输出、工具调用结果、模型决策路径，便于调试和优化。

五、总结

AI 编程 Agent 的能力上限，不仅取决于底层模型有多强，更取决于 Harness 层设计得有多好。Prompt 编排、工具调用、迭代控制、上下文摘要、测试反馈、记忆系统、子 Agent 协调——这些模块共同构成了“模型之外的一切”，也正是它们让一个只会输出 token 的模型，变成一个能真正完成工程任务的 Agent。

理解 Harness 层的职责与设计原则，对于任何想要构建或使用 AI 编程 Agent 的开发者来说，都是不可或缺的基础认知。