本文详细介绍了如何通过构建模型外围的 Harness工作框架来打造高效的编码 Agent。文章指出真正的差异不在模型本身而在于模型外围的 Harness它负责规划、工具调度、记忆管理、安全控制与上下文维护。通过分析 Claude Code Harness 的结构和功能文章阐述了记忆模块、技能模块、协议模块和 Harness 核心的作用并强调了模型决策与执行分离的重要性。此外文章还介绍了 CrewAI 框架如何帮助开发者从零构建自己的编码 Agent并详细解释了规划能力、文件系统工具、子 Agent 协作机制、记忆管理和权限控制与沙盒系统的应用。最后文章总结了编码 Agent 的能力主要存在于 Harness 中并鼓励读者利用开源框架 CrewAI 来实现自己的编码 Agent。你是否曾尝试打造自己的编码 Agent接入文件读写工具、Shell 执行能力后让它处理真实代码库——结果往往在十几步工具调用内就崩溃了读错关键文件中途遗忘原始目标上下文被大量过期输出塞满有效信息被淹没。而同样的任务交给 Claude Code却能干净利落地完成。人们容易归因于“Anthropic 的模型更强”但这种判断忽略了真正决定成败的关键部分。真正的差异不在模型本身而在模型外围的 Harness工作框架。Harness 是围绕大语言模型编写的普通代码层负责规划、工具调度、记忆管理、安全控制与上下文维护模型自身只做一件事根据当前状态决定下一步该执行哪个动作。以下是 Claude Code Harness 的整体结构示意图图中模块看似复杂实则可清晰划分为四个核心部分记忆模块为模型提供当前任务上下文并持久化跨会话积累的事实性知识技能模块定义 Agent 的行为逻辑包括执行流程、硬性约束与启发式规则协议模块统一处理 Agent 与用户、工具、其他 Agent 之间的交互契约Harness 核心通过子 Agent 编排、沙盒隔离、评估器反馈、审批循环、可观测性追踪及上下文压缩等能力将前三者有机整合。Anthropic 将这一分工形象地比作“大脑”与“双手”模型是大脑专注决策Harness 是双手负责执行、校验与兜底确保整个过程始终可控、可追溯、可恢复。因此你的 Agent 与 Claude Code 的差距并非源于模型能力的高下而在于模型周围这套工程化框架的完备程度。Claude Code 是目前生产环境中功能最强大的 Harness 之一其全部能力仅依赖上图所示架构中非常有限的几层实现。为了厘清你需要从零构建多少内容我基于开源 Agent 编排框架 CrewAI 重建了该系统。结果令人惊讶大部分基础能力已直接映射到 CrewAI 的内置特性中那些尚未覆盖的部分恰恰正是真正需要投入工程精力攻克的难点。接下来我们将从最底层的核心循环出发逐层叠加关键能力→ 规划 → 子 Agent → 沙盒 → 记忆每一步都会明确标注哪些由 CrewAI 原生支持哪些需你自行实现。Claude Code Harness 的工作原理Claude Code 的核心是一个标准 Agent 循环你发送一条消息模型据此决定下一步动作——要么直接返回文本响应要么请求调用一个或多个工具若发起工具调用则执行工具并将结果返回对话历史模型再基于更新后的上下文做出下一轮决策。该循环持续运行直到模型输出纯文本且不再请求任何工具调用为止。在此循环中模型可执行的操作如读取文件、编辑代码、运行 Shell 命令、执行测试并非独立模式而是同一循环下的不同工具调用类型。但仅靠这个基础循环尚不足以支撑可靠的编码 Agent。Claude Code 在其外围叠加了五大增强层规划能力Plan before act文件系统工具File I/O with context-awareness子 Agent 协作机制Delegation to specialized sub-Agents记忆管理Short- and long-term memory权限控制与沙盒系统Sandboxed execution approval gates这些增强层并未替换核心循环而是对其进行加固与延展使其足够稳健、安全得以胜任真实开发场景。这正是我们要重建的架构路径先实现最小可行的核心循环再逐层添加各增强模块核心 Agent 循环该循环按以下五步持续运行直至任务完成1. 向模型提交当前对话历史与可用工具列表2. 模型返回纯文本响应或包含一个/多个工具调用请求3. 若存在工具调用则并行执行全部请求并将结果追加至对话历史4. 使用更新后的完整对话历史重新进入步骤 15. 当模型返回纯文本且未发起任何工具调用时循环终止任务完成。对应的伪代码如下while True: reply model(messages, tools) calls [b for b in reply if b.type tool_use] if not calls: # 纯文本响应无工具调用任务完成 return reply.text messages [reply, run_all(calls)]每次工具调用完成一个原子操作为模型注入新信息并驱动其后续决策。简单问题可能一次迭代即解决而修复复杂 Bug 或重构大型代码库则可能需数十次迭代直至模型获得足够信息生成最终答案。构建第一个 Agent我们来创建一个简单的 Bug Fixer Agentfrom crewai import LLM, Agent, Crew, Task bug_fixer Agent( roleBug Fixer, goal在代码库中定位并描述所报告 Bug 的修复方案。, backstory你通过读取目录与文件构建对代码结构的准确理解。, llmclaude-sonnet-4-6, ) task Task( description寻找 {objective} 的修复方案。, expected_output一段简短的修复说明以及该修复应应用的具体文件。, ) result Crew(agents[bug_fixer], tasks[task]).kickoff( inputs{objective: account.py 中的透支 Bug} )这里需理解三个核心概念Agent 定义“谁来干活”通过角色role、目标goal、语言模型LLM及可用工具共同刻画其能力边界Task 描述“干什么活”明确任务输入、预期输出与执行要求Crew 将 Agent 与 Task 组织起来调用kickoff()即启动前述 Agent 循环且该循环与底层模型厂商无关无论 Anthropic、OpenAI、Google 或其他模型均可运行。为 Agent 添加工具工具是让一个仅能生成文本的模型真正具备代码库操作能力的关键。它们支持读取文件、写入文件、执行 Shell 命令以及调用外部 API。CrewAI 开箱即用地提供了以下文件系统工具FileReadTool用于读取指定路径的文件内容DirectoryReadTool用于列出目录结构与文件名FileWriterTool用于将内容写入指定路径的文件。from crewai_tools import DirectoryReadTool, FileReadTool, FileWriterTool read_file FileReadTool() write_file FileWriterTool() list_dir DirectoryReadTool() filesystem_tools [read_file, write_file, list_dir]这些工具还可充当外部记忆。与其将大量搜索结果保留在模型的上下文窗口中Agent 可将其写入临时文件仅保留文件名作为索引并在需要时再读取。要点 与其将大量搜索结果保留在模型的上下文窗口中Agent 可将其写入临时文件仅保留文件名作为索引并在需要时再读取。这有助于缩小上下文窗口、提升模型专注度也正是 Anthropic 所称的“上下文工程”。内置工具仅覆盖常见工作流。对于更具体的需求可通过tool装饰器将任意 Python 函数暴露为工具。函数的文档字符串即为使用说明明确告知模型该工具的功能、适用时机及输入要求。from crewai.tools import tool import subprocess tool(run_tests) def run_tests(path: str tests/) - str: 在指定路径运行 pytest 测试套件并返回结果。 result subprocess.run( [pytest, path, -q], capture_outputTrue, textTrue, timeout120 ) output result.stdout result.stderr return output[-4000:] if len(output) 4000 else output长期任务的规划随着任务复杂度上升简单的执行循环会逐渐偏离原始目标。经过多次工具调用、文件读取和中间结果处理后上下文被后续信息填满原始目标反而被淹没。这种缓慢退化现象被称为“上下文腐烂”context rot。要点 这种缓慢退化现象被称为“上下文腐烂”context rot。规划直接应对这一问题Agent 在执行任何操作前先构建分步计划并在整个执行过程中持续将该计划保留在上下文中。计划本身不执行任务而是一张路线图确保模型始终锚定原始目标——其作用与 Claude Code 的待办清单一致。CrewAI 在 Crew 层级通过planningTrue启用该能力它会在执行前生成计划并在任务推进过程中始终提供该计划。from crewai import Crew, LLM crew Crew( agentsself.agents, tasksself.tasks, planningTrue, planning_llmLLM(modelgpt-4o-mini), )注意CrewAI 默认使用 gpt-4o-mini 执行规划您可按需替换为任意其他 LLM。单个 Agent 也可通过启用reasoningTrue对自身工作进行自主思考from crewai import Agent bug_fixer Agent( roleBug Fixer, goalFind and describe the fix for the reported bug in the codebase., backstoryYou read directories and files to build an accurate picture of the code., tools[FileReadTool()], reasoningTrue, max_reasoning_attempts3 # 可选设置最大推理尝试次数 )规划与推理解决的是不同层面的问题规划为整体任务构建高层级路线图推理则赋予单个 Agent 在行动前充分梳理自身策略的时间。启用推理后Agent 将依次执行以下步骤1. 反思当前任务草拟执行计划2. 判断该计划是否已完备3. 如未满足要求则反复优化直至满意或达到max_reasoning_attempts上限4. 将最终确定的推理计划注入任务上下文再启动执行。二者协同使 Agent 在长期任务中始终保持目标导向显著降低目标偏移风险。通过子 Agent 进行任务委派规划有助于保持 Agent 专注但无法减少模型需承载的信息量。在大型代码库中即使经过周密规划的任务也可能超出单次上下文窗口容量。定位一个 Bug 可能需读取数十个文件而主 Agent 并不需要将全部内容保留在内存中。子 Agent 通过任务委派解决此问题主 Agent 将特定子任务交由辅助 Agent 处理后者在独立上下文中完成工作并返回简明摘要主 Agent 仅接收结论无需了解中间过程。CrewAI 通过分层工作流hierarchical workflows支持该机制管理型 Agent 向专业型 Agent 分配任务并整合其输出结果。此前示例中所有工作均由单一Bug FixerAgent 完成。现将职责拆分为一位管理者与三位专业 AgentCodebase Explorer探索代码库并绘制仓库结构图Software Engineer实施所请求的代码变更Test Runner在沙盒环境中运行测试并报告通过或失败Engineering Lead统筹三位专业 Agent 的协作。from crewai import Crew, Agent, Task, Process explorer Agent( roleCodebase Explorer, goalMap the repository and surface the files relevant to the task., backstoryYou read directories and files to build a picture of the code., tools[read_file, list_dir], llmllm, ) # 其余两位专业 Agent 同理配置 manager Agent( roleEngineering Lead, goalBreak the request into steps and delegate each to the right specialist., backstoryYou decide who does what, review tests, finish once change is done., llmllm, allow_delegationTrue, ) crew Crew( agents[explorer, coder, tester], tasks[task], manager_agentmanager, processProcess.hierarchical, )需特别注意allow_delegation默认为禁用状态必须显式设为True才能在管理型 Agent 上启用委派能力。沙盒化保障 Agent 执行安全具备 Shell 访问权限的 Agent 可能执行破坏性命令仅靠提示词禁止某类行为并不能构成有效防护。真正的保护来自两层机制1. 一种权限系统对敏感操作要求人工审批2. 一个沙盒环境用于隔离代码执行——即使已获批准的命令也无法访问宿主机。Anthropic 也采用相同的设计思路。将代码执行移入沙盒既能显著降低用户需手动审批操作的频率又能持续保障宿主机的安全。CrewAI 中的沙盒机制在沙盒中而非宿主机上执行代码即实现了上述第二层保护。在此配置下所有代码均运行于 E2B 环境中E2B 为每次会话启动一个全新的虚拟机并在会话结束后立即销毁该虚拟机。Shell 命令与 Python 代码完全在该隔离环境中执行。from crewai_tools import E2BExecTool, E2BPythonTool sandbox_tools [E2BExecTool(), E2BPythonTool()] # 运行测试 / 执行代码人机协同审批Human-in-the-loop approval在 Task 中设置human_inputTrue会使 Crew 在生成答案后暂停执行。您可审查输出内容再选择批准或退回重做。当执行流程到达该任务时CrewAI 将通过标准输入stdin等待您的反馈。from crewai import Task task Task( description( 在工作目录 ./workspace 中{objective}。 先探索代码结构再实施修改然后运行测试并汇报结果。 ), expected_output一份变更文件摘要及最终测试输出。, human_inputTrue, )若您的 Crew 运行于 Web 应用或聊天界面而非终端CrewAI 的基于 Webhook 的人机协同审批机制同样支持该审核步骤。记忆与检查点机制默认情况下Agent 在一次运行结束后会清空全部上下文。次日若需在同一项目中修复另一个 Bug它将从零开始重新理解整个代码库。有两种机制可让 Agent 在多次运行间延续信息且二者用途不同检查点Checkpointing保存 Agent 在单次运行过程中的完整状态使其可在中断后恢复执行或沿不同路径继续推进至同一进度点持久化记忆Persistent memory跨独立对话长期存储事实性信息例如项目级偏好设置“完成前始终格式化最终代码”。CrewAI 中的记忆机制CrewAI 提供统一的 Memory 接口不区分短期、长期、实体或外部记忆等类型。在保存信息时它调用 LLM 自动识别关键细节、组织语义结构并确保后续可高效检索。在 Crew 初始化时设置memoryTrue即可启用跨轮次记忆能力。每项任务完成后CrewAI 会从其输出中提取有用事实并存入记忆后续运行中系统将自动检索相关记忆并将其注入当前任务的 Prompt 中。from crewai import Crew crew Crew( agents[explorer, coder, tester], tasks[task], memoryTrue, )除非为某个 Agent 显式配置独立记忆否则 Crew 内所有 Agent 共享同一份记忆。CrewAI 中的检查点机制检查点是 Agent 进度的一个完整快照包含其配置、当前任务状态、内存内容、中间结果、输入数据以及完整执行历史。默认情况下CrewAI 在每项任务成功完成后自动生成检查点以便工作流在意外中断后能从中断点恢复。检查点可存储于以下两种内置存储后端之一JsonProvider将每个检查点保存为独立 JSON 文件便于人工阅读与调试。SqliteProvider将全部检查点集中存入单个 SQLite 数据库更适合高频写入场景与大规模工作负载。from crewai import Crew crew Crew( agents[explorer, coder, tester], tasks[task], checkpointTrue, )Crew、Flow与Agent均接受checkpoint参数子组件默认继承父组件的设置除非显式覆盖。综合示例完整执行链路下面是一个完整任务的端到端实现整合了执行循环、工具调用、规划能力、子 Agent 协作、沙盒执行与记忆机制from crewai import Agent, Crew, LLM, Process, Task from crewai.tools import tool from crewai_tools import (DirectoryReadTool, FileReadTool, FileWriterTool, E2BExecTool, E2BPythonTool) llm LLM(modelanthropic/claude-sonnet-4.6) list_dir DirectoryReadTool(directory./workspace) filesystem_tools [FileReadTool(), FileWriterTool(), list_dir] sandbox_tools [E2BExecTool(), E2BPythonTool()] tool(run_tests) def run_tests(path: str tests/) - str: 同步 ./workspace 到沙盒环境然后在其中运行 pytest。 return E2BExecTool().run(commandsync_and_test_command(path)) explorer Agent(roleCodebase Explorer, goalMap repo, surface relevant files., tools[FileReadTool(), list_dir], llmllm) coder Agent(roleSoftware Engineer, goalImplement requested change., toolsfilesystem_tools, reasoningTrue, llmllm) tester Agent(roleTest Runner, goalRun tests in sandbox, report pass/fail., toolssandbox_tools [FileReadTool()] [run_tests], llmllm) manager Agent(roleEngineering Lead, goalDelegate steps, finish once tests pass., allow_delegationTrue, llmllm) task Task( descriptionIn ./workspace, {objective}. Explore, edit, test, report., expected_outputSummary of changes and test output., human_inputTrue, ) crew Crew( agents[explorer, coder, tester], tasks[task], manager_agentmanager, processProcess.hierarchical, planningTrue, memoryTrue, checkpointTrue, ) result crew.kickoff(inputs{objective: fix failing tests in account.py})Agent 执行效果最易评估的场景是存在可自动验证的成功标准时。一套完备的测试套件能为 Agent 提供明确目标使其可自主规划、编辑、测试并迭代直至全部测试通过。因此该方案在一个小型代码库上进行了测试一个BankAccount类包含两个真实 Bug 和五个测试其中三个测试失败。规则是仅修复实现部分不得修改测试。这与 Anthropic 内部评估编码 Agent 的方式一致。一个已公开的案例中Claude 针对一大套失败的测试用例重建了 claude.ai 界面的克隆版本。在此场景中Harness 将项目状态从“3 个测试失败、2 个通过”提升至“全部 5 个测试均通过”而“仅修改实现”的约束也彻底封堵了通过编辑或删除失败测试来走捷径的可能性。仍需你亲自负责的部分系统中以下部分并非框架自动构建而是由你主导Prompt。每个 Agent 的行为由其角色role、目标goal和背景设定backstory共同决定。调优这些要素需要反复测试与迭代没有任何配置开关可替代这一过程。执行环境。无论是 E2B 沙盒还是自托管虚拟机都需你自行搭建并完成集成。工具选择。每个 Agent 应配备哪些工具、哪些工具应开放给哪个 Agent——这类设计决策完全由你作出框架不代为判断。此外Harness 本身也会带来额外开销规划planning、子 Agentsubagents和循环looping均会增加 API 调用次数因此复杂 Agent 架构的实际成本可能高于单次模型调用即可解决的任务。还有一个长期需留意的限制随着模型能力持续提升部分当前 Harness 中的“脚手架”将逐渐失去必要性。因为今日嵌入 Harness 的许多机制本质是对当前模型能力局限的临时规避而非永久性需求。例如Anthropic 最初使用上下文重置context resets防止 Claude Sonnet 4.5 过早终止任务但在更强大的 Claude Opus 4.5 上线后该机制已不再需要。总结这就是核心发现编码 Agent 的能力主要存在于其 Harness 中而编排框架orchestration framework所提供的 Harness 支持远超多数人的直观预期。以下功能均可通过配置直接启用循环looping规划planning委托delegation沙盒化sandboxing记忆memory但与此同时Prompt 设计、执行环境选择与工具链配置仍完全由你掌控。如果你想在自己的代码库上运行这套方案CrewAI 文档完整覆盖本文所用全部功能且整个框架完全开源。最后2026 年一晃已经过半AI 大模型的热潮不仅没有降温反而持续升温金融行业用大模型做风控、医疗依靠 AI 解析影像电商、制造、教育各行各业都在把 AI 融入日常业务。曾经热闹的 “百模大战”早就告别单纯比拼模型参数正式进入落地应用时代。现在企业疯狂紧缺一类人才懂业务、懂 AI、能做出可上线项目的大模型开发工程师岗位缺口大薪资待遇十分可观。风口再好不如手握高薪 offer 实在。行情火热普通人、程序员该怎样从零入门大模型抓住这波机会今天整理好【2026 最新版】AI 大模型全套免费学习资源覆盖零基础入门、项目实战、理论知识、大厂面试从基础一路进阶。所有资料分类归档没有多余杂料无套路免费分享给想要入局 AI 赛道的程序员与零基础小白扫码免费领取全部内容1、大模型系统化完整学习路线2、大模型经典书籍文档3、AI 大模型最新行业研究报告4、企业级实战项目 完整配套源码5、大厂大模型面试真题汇总6、这些资料真的有用吗这份资料由我和鲁为民博士(北京清华大学学士和美国加州理工学院博士)共同整理现任上海殷泊信息科技CEO其创立的MoPaaS云平台获Forrester全球’强劲表现者’认证服务航天科工、国家电网等1000企业以第一作者在IEEE Transactions发表论文50篇获NASA JPL火星探测系统强化学习专利等35项中美专利。本套AI大模型课程由清华大学-加州理工双料博士、吴文俊人工智能奖得主鲁为民教授领衔研发。资料内容涵盖了从入门到进阶的各类视频教程和实战项目无论你是小白还是有些技术基础的技术人员这份资料都绝对能帮助你提升薪资待遇转行大模型岗位。这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】