如何从零开始构建编码代理测试框架

You paste a model call into a script, it answers a question, and you have a chatbot. Then you ask it to read your files, run the tests, and fix what breaks, and suddenly one call is not enough. The layer that closes that gap is the harness, and it is smaller than most people expect. Build it once and you understand every coding agent you will ever use.

你将模型调用粘贴到脚本中，它回答一个问题，你就有了一个聊天机器人。然后你让它读取你的文件、运行测试并修复出错的地方，突然间一次调用就不够了。填补这一空白的层就是 Agent Harness，而且它比大多数人预期的要小。构建一次，你就能理解你将使用的所有 coding agent。

This guide builds a coding agent harness in Python, one layer at a time, with a working snippet for each. By the end you will have the provider call, the agent loop, a tool registry, context management, a sandbox, and a permission check, which together are what turn a model into an agent that acts on real code.

本指南在 Python 中逐层构建一个 coding agent harness，每一层都配有可运行的代码片段。到最后，你将拥有 provider 调用、agent 循环、工具注册表、上下文管理、沙盒和权限检查，这些组合在一起，就能将模型转变为能够操作真实代码的 agent。

What Is a Coding Agent Harness and Why Build One?

什么是编码智能体 harness，为什么要构建一个？

A coding agent harness is the scaffolding around a language model that runs the loop. It calls the model, executes the tools the model asks for, appends the results to the conversation, and repeats until a stop condition fires. The model does the reasoning. The harness supplies the environment.

编码 agent harness 是围绕运行循环的语言模型的脚手架。它调用模型，执行模型请求的工具，将结果追加到对话中，并重复此过程直到触发停止条件。模型负责推理。harness 提供环境。

You can get an agent from a framework in a few lines, so why build an agent harness yourself? Because doing it by hand is the fastest way to see what every framework hides, and because production teams end up needing control over the loop, the tool boundary, and the safety layer that a default cannot give them. The pieces are small enough that hand-rolling them is a weekend, not a quarter.

你可以通过框架用几行代码获得一个 agent，那为什么还要自己构建 Agent Harness 呢？因为手动构建是了解每个框架隐藏了什么的最快方法，而且因为生产团队最终需要控制循环、工具边界和安全层，而这些是默认配置无法提供的。这些组件足够小，手动实现只需要一个周末，而不是一个季度。

The table below lists the six layers this guide builds. Each maps to one real implementation ch...