你尝试过自己搭建编码代理吗？把模型连上文件工具和Shell，扔给一个真实代码库，通常十几步工具调用后就崩了：读错文件、忘记初始目标、上下文被无用输出塞满。

而同样的任务交给 Claude Code，却能干净利落地完成。

很多人第一反应是“Anthropic的模型更强”。这个结论错过了真正的工作发生在哪里。

差距不在模型，而在Harness（代理线束）。Harness 是包裹在模型外层的普通代码，负责规划、工具执行、记忆管理、安全控制和编排，而模型只负责“下一步该做什么”。

Anthropic 把这个分工描述为“大脑与双手”：模型是大脑，Harness 是执行并保持任务在轨的双手。

下面我们把 Harness 完整拆解成可落地的层级，并用 CrewAI 这个开源框架一步步复现，标明哪些是框架免费提供的，哪些 still 需要你自己工程化。

Harness 的核心构成

一个完整的生产级编码代理 Harness 可以拆成四个主要部分：

• Memory：为模型提供当前工作上下文 + 跨会话学到的知识
• Skills：编码代理应遵循的流程、约束和启发式规则
• Protocols：连接用户、工具和其他代理的接口
• Harness Core：把一切串起来的核心，包括子代理编排、沙箱、评估器、审批循环、可观测性和上下文压缩

Claude Code 正是用这套相对完整的 Harness 实现了可靠的编码能力。下面我们从最底层的执行循环开始，一层一层往上叠加。

第一层：核心执行循环（CrewAI 免费提供）

最底层的循环极其简单：

1. 把任务发给模型
2. 模型要么直接回复，要么请求一个或多个工具
3. 执行工具，把结果塞回对话
4. 重复，直到模型不再请求工具并给出最终答案

这个循环本身就能让模型读文件、改代码、跑 Shell、执行测试。但纯循环很容易目标漂移、上下文爆炸。

CrewAI 实现：
创建一个 Agent + Task + Crew，调用kickoff()就自动跑起这个循环。你不需要自己写 while 循环。

fromcrewaiimportAgent,Crew,Task bug_fixer=Agent(role="Bug Fixer",goal="修复代码库中的失败测试",llm=LLM(model="anthropic/claude-sonnet-4.6"),tools=[file_read,file_write,shell_exec])task=Task(description="在 ./workspace 中修复 account.py 的失败测试",expected_output="修改摘要 + 最终测试结果")crew=Crew(agents=[bug_fixer],tasks=[task])result=crew.kickoff()

框架把“决定-执行-反馈”循环完全封装了。

第二层：工具系统（CrewAI 提供基础，特定需求需自定义）

模型本身只会生成文本，工具让它真正“动手”。

CrewAI 内置文件系统工具：

• FileReadTool、DirectoryReadTool、FileWriterTool

这些工具还能充当外部记忆：把大段搜索结果写进文件，只在上下文中保留文件名，需要时再读回来（这就是 Anthropic 说的context engineering）。

自定义工具用@tool装饰器，docstring 就是给模型的说明书。

第三层：规划（Planning）——对抗上下文腐烂

长任务执行十几二十步后，原始目标很容易被中间结果淹没（context rot）。

解决方案是让代理先输出一个 step-by-step 计划，并在整个执行过程中把计划留在上下文中。

CrewAI 实现：

crew=Crew(...,planning=True)# 任务级规划agent=Agent(...,reasoning=True)# 单个代理的深度推理

规划负责全局路线图，reasoning 负责代理内部的思考-评估-精炼循环。两者结合能显著减少目标漂移。

第四层：子代理与层级编排（Subagents）

大型代码库修复可能需要读几十个文件，主代理不需要把所有中间结果都塞进自己的上下文。

做法是委托：主代理把具体任务分给专业子代理，子代理在自己的上下文中完成工作，只返回简短结论。

CrewAI 实现：开启allow_delegation=True+Process.hierarchical，并指定manager_agent。

示例拆分：

• Codebase Explorer（探索仓库）
• Software Engineer（实现修改）
• Test Runner（在沙箱跑测试）
• Engineering Lead（经理代理，负责委托与汇总）

第五层：安全（Sandbox + 人工审批）

再强的提示词也挡不住模型执行危险命令。真正的安全来自两层机制：

1. 权限系统：敏感操作必须人工审批
2. 沙箱隔离：即使批准，命令也只能在隔离环境执行

CrewAI 实现：

• 使用 E2B 等沙箱工具，把 Shell 和 Python 执行完全隔离在临时 VM 中
• Task 上设置human_input=True，任务生成答案后暂停，等待人工 review

第六层：记忆与检查点（Memory + Checkpoint）

默认情况下，代理跑完一次就忘得一干二净。

• Memory：跨会话持久化事实（如“项目偏好：最终代码必须格式化”）
• Checkpoint：保存运行时状态，支持中断后恢复

CrewAI 实现：

crew=Crew(agents=[...],tasks=[...],memory=True,# 跨运行记忆checkpoint=True# 运行时检查点)

记忆由 LLM 自动提炼重要信息并检索；检查点可存 JSON 或 SQLite。

完整 Harness 在一个 Bug Fix 任务上的效果

把上面六层全部打开，对一个包含真实 Bug 的 BankAccount 类（5 个测试，初始 3 失败 2 通过）进行测试。规则是只能修改实现，不能改测试本身。

结果：Harness 成功把所有测试修复通过。

这与 Anthropic 内部评估编码代理的方式高度一致——用真实失败测试套件作为客观衡量标准。

框架能给你什么、不能给你什么

框架免费提供：

• 执行循环
• 工具调用机制
• 规划与推理
• 子代理委托
• 沙箱集成
• 记忆与检查点

仍需你自己工程化：

• 每个 Agent 的 role/goal/backstory 提示词（需要反复迭代）
• 执行环境搭建（沙箱配置）
• 工具选择与权限分配
• 成本控制（规划 + 子代理会增加 API 调用）

此外要记住：随着模型能力提升，部分今天必须的 Harness scaffolding 未来可能会变得多余。Anthropic 自己就曾因为模型升级而移除了某些上下文重置机制。

系统级判断

起初很多人（包括我）以为“只要模型够强，简单接工具就能做出可靠编码代理”。在用 CrewAI 完整复现 Harness 各层后才发现，模型只是大脑，真正决定成败的是“双手”——规划、记忆、安全、编排这些工程层。

Harness 不是临时补丁，而是目前让编码代理从“玩具”变成“生产工具”的核心工程工作。

在你的代码库上真正落地前，建议从一个极小的 Bug Fix 任务开始：只开 planning + memory + sandbox + human_input，观察上下文长度、成功率和成本变化，再逐步叠加子代理。

当模型继续变强时，Harness 的设计会越来越像“最小必要 scaffolding”，而不是越来越复杂。

你目前在构建或评估编码代理时，遇到的最大瓶颈是上下文管理、目标漂移，还是安全审批？

我是紫微AI，在做一个「人格操作系统（ZPF）」。后面会持续分享AI Agent和系统实验。感兴趣可以关注，我们下期见。