Coding Agent Harness 是 Agent Harness 在软件开发任务中的具体实现。它把模型连接到代码仓库、文件编辑器、终端、测试系统和版本控制，并通过权限、隔离、验证与恢复机制约束 Agent 的行动。
通用 Agent Harness 解决“怎样让模型作为 Agent 运行”的问题；Coding Agent Harness 进一步解决“怎样让 Agent 在真实软件项目中可靠地理解、修改和验证代码”的问题。本词条重点介绍编码场景特有的组成部分和代表性实现。
为什么编码需要专门的 Harness
软件任务同时具有两个特点：
- 行动能力强：Agent 可以修改大量文件、执行任意程序、安装依赖、访问网络，甚至触及凭据和生产系统；
- 自动反馈丰富：测试、类型检查、Linter、构建系统和 Git 能够快速提供结构化结果。
因此，Coding Agent 的效果不只取决于模型会不会写代码。仓库上下文是否准确、工具是否容易使用、命令是否安全、失败能否恢复、完成条件是否经过验证，都会直接影响最终结果。
核心组成
项目上下文
Harness 需要向 Agent 提供项目说明、目录结构、依赖、构建命令、代码规范、当前 Git 状态和任务进度。常见的项目指令载体包括仓库说明文件、目录级规则和按需加载的技能文档。
项目规则应说明真实的开发约束，例如使用哪个包管理器、怎样运行测试、哪些目录不能修改、数据库结构以哪里为准。只提供通用的“请编写高质量代码”通常不足以约束真实工程行为。
仓库探索与搜索
Coding Agent 不可能始终把整个仓库放入模型上下文。Harness 通常提供目录浏览、文件名搜索、全文搜索、文件读取，有时还会提供符号定义、引用关系、版本历史或语义检索。
搜索结果的格式也很重要：路径、行号、匹配上下文和结果数量会影响模型能否继续定位问题。
文件编辑
文件编辑工具可以采用精确文本替换、补丁、局部编辑或完整文件写入。Harness 需要检查目标文件是否存在、原始内容是否匹配、文件是否在允许范围内，以及修改后产生了什么差异。
可靠的编辑机制应尽量避免静默覆盖用户修改，并使变更能够通过 Diff 审查和版本控制回退。
命令与进程执行
Agent 通过终端运行测试、构建、开发服务器、格式化工具和调试命令。Harness 需要处理工作目录、环境变量、交互式输入、长时间进程、输出截断、超时和退出码。
命令执行能力接近开发者本人的系统权限，因此通常需要沙盒、网络限制和审批策略共同保护。
验证循环
代码生成只是候选方案，运行验证才会产生环境证据。Harness 可以根据任务选择单元测试、集成测试、类型检查、Linter、构建、性能测试或浏览器检查，并把失败结果返回模型继续修复。
“命令退出码为零”也不一定代表需求已经完成。Harness 还需要核对验收条件、变更范围和测试是否覆盖了真正的目标。
Git 与恢复
Git 为 Coding Agent 提供 Diff、提交历史、分支和回退能力。长任务或并行任务还可以使用独立分支、临时工作副本或 Worktree 隔离修改，在合并点集中处理冲突。
Harness 不应擅自丢弃用户原有的未提交修改。执行清理、覆盖历史或删除大量文件之前，需要先确定精确范围并获得明确授权。
权限、沙盒与审批
常见控制包括：
- 限制能够读取和写入的文件目录；
- 隔离命令执行产生的进程和资源；
- 默认阻止或限制网络访问；
- 对安装依赖、访问外部服务和破坏性命令请求批准；
- 将仓库文件、Issue、网页和工具输出视为不可信数据；
- 防止密钥通过日志、网络请求或最终回答泄露。
权限提示属于决策层，沙盒属于操作系统执行层。两者需要配合：用户拒绝危险动作是一层保护，即使 Agent 判断错误，执行环境仍应限制其影响范围。
长任务状态
复杂开发可能超过一次模型上下文或一次运行时间。Harness 可以保存任务计划、已完成项目、验证结果、未解决问题和交接记录，让新的会话从真实进度继续，而不是重新猜测之前发生了什么。
本地 Harness 与云端 Harness
| 方式 | 代码执行位置 | 主要特点 |
|---|---|---|
| 本地运行 | 开发者电脑或本地容器 | 可以使用现有环境和未提交修改，但必须谨慎控制本机权限 |
| 云端运行 | 临时虚拟机、容器或托管工作区 | 便于后台和并行执行，通常围绕分支与 Pull Request 交付 |
| 混合运行 | 本地与云端任务相互交接 | 可以按任务选择环境，但需要处理状态、凭据和修改同步 |
运行界面并不能决定 Harness 类型。同一个 Coding Agent 可以同时提供终端、IDE、桌面应用和云端任务等入口。
常见产品与实现
下面列举的是代表性 Coding Agent 产品或开源实现。它们都包含某种 Coding Agent Harness，但产品功能和实现方式会持续变化，应以各自官方文档为准。
Pi Coding Agent
Pi 是一个开源、面向终端的轻量 Coding Agent Harness。其核心提供模型调用、Agent 循环、会话状态以及读取、写入、编辑和 Bash 等基础工具，并通过 TypeScript Extensions、Skills、提示模板、主题和 Pi Packages 扩展能力。
Pi 的设计重点是保持核心较小，把工作流和额外能力交给用户自行组合。它支持不同模型提供商，也提供 TUI、非交互输出、JSON 事件流、RPC 和 SDK 等接入方式。需要特别注意的是，Pi 官方说明其核心不内置完整的文件、进程、网络和凭据权限系统；需要高隔离时，应在容器等受控环境中运行，或通过扩展构建所需的确认与限制机制。
DeepSeek Harness
DeepSeek Harness 是 DeepSeek AI 开源的通用 Agent Harness，而不是只面向编码的成品 Coding Agent。它采用插件化架构，把 Session、系统提示、工具、Agent 循环、模型适配、持久化、权限和界面等能力组合为可替换组件。
在选择代码工作区并配置相应插件后，DeepSeek Harness 可以读取和编辑文件、运行命令、维护计划并委派任务，因此也可以组成 Coding Agent Harness。它更适合需要自行组合或嵌入 Agent 控制面的开发者。创建本词条时，官方仍将其标记为 Developer Preview，并提示可能出现不兼容变化。
OpenAI Codex
Codex 是 OpenAI 的 Coding Agent，提供终端、编辑器、桌面应用和云端等使用形态。其开源 CLI 展示了本地代码探索、命令执行、沙盒、权限审批和任务运行等机制。
从 Harness 角度观察 Codex，可以重点关注工作区权限、网络访问、命令审批、工具事件、任务状态和本地与云端执行方式。
Claude Code
Claude Code 是 Anthropic 的 Agentic Coding 工具，可读取代码库、编辑文件、运行命令，并运行于终端、IDE、桌面和云端等环境。
它通过项目说明文件提供长期上下文，通过工具与 MCP 扩展能力，通过 Skills 表达可复用工作方式，并使用权限规则、沙盒和 Hooks 控制或检查工具执行。其公开文档适合用来理解 Harness 的扩展点如何分布在 Agent 循环周围。
Cursor Agent
Cursor Agent 是以代码编辑器为主要交互界面的 Coding Agent。其公开能力包括代码库搜索、文件读取与编辑、终端和浏览器操作，并提供本地检查点帮助用户预览或恢复 Agent 修改。
它体现了 IDE 型 Harness 的特点：代码导航、编辑 Diff、终端和交互反馈集中在同一个开发界面中。
GitHub Copilot cloud agent
GitHub Copilot cloud agent 面向 GitHub 上的异步开发任务。它在临时开发环境中研究仓库、制定计划、修改分支并运行测试，最终由开发者查看差异并决定是否创建、审查和合并 Pull Request。
它体现了云端 Harness 的典型边界：任务围绕仓库、分支、日志、检查和人工合并组织，执行环境与开发者本机隔离。
OpenHands
OpenHands 是开源的软件开发 Agent 平台，并提供可组合的 Software Agent SDK。它适合研究如何把 Agent 循环、运行环境、工具和服务端会话组合成可自行部署或扩展的 Coding Agent 系统。
OpenHands 更接近开源平台与开发组件，不应与面向最终用户的商业编辑器简单放在同一个维度排名。
SWE-agent
SWE-agent 是面向自动化软件工程研究的开源系统。其工作强调 Agent-Computer Interface：专门为模型设计的代码导航、编辑和程序执行接口会显著影响 Agent 表现。
它更适合作为 Harness 和评测研究案例，而不是日常编码产品清单中的直接替代品。
怎样比较不同 Harness
选择或评估 Coding Agent 时，可以观察以下方面，而不是只比较模型名称：
- 能否准确搜索并理解大型仓库；
- 编辑工具是否稳定，Diff 是否容易审查和回退；
- 是否能运行项目真实使用的测试与构建流程；
- 文件、网络、命令和凭据权限怎样控制；
- 本地、云端、IDE 和自动化任务是否符合工作方式；
- 长任务能否保存状态、恢复和接受中途调整；
- 是否提供清晰的工具日志、验证证据和未完成边界；
- 能否通过项目指令、Skills、Hooks、MCP 或 SDK 进行扩展；
- 数据和代码会被发送到哪里，组织策略能否限制其使用；
- 在自己的真实仓库和固定任务集上，成功率、成本和延迟如何。
不同产品可能使用相同模型，却因为上下文选择、工具接口、权限与验证设计不同而表现不同。因此，模型评测不能替代对完整 Coding Agent Harness 的评测。
常见失败
- 只读取一个文件就修改跨模块逻辑；
- 修改代码后没有运行相关检查；
- 为了让测试通过而删除或弱化测试；
- 在错误的工作目录运行命令；
- 安装依赖或访问网络时没有说明外部影响；
- 覆盖用户未提交的修改；
- 长任务丢失部分需求后过早结束；
- 把仓库中的恶意文本当作用户指令；
- 报告“已经部署”或“已经修复”，但没有环境证据。
这些失败有些来自模型判断，有些来自 Harness 缺少上下文、约束或验证。可靠系统需要同时改进模型与 Harness，而不能把所有问题都归因于提示词。