从 Scaffolding 到 Harness：AI Coding Agent 真正难的，不是写代码，而是把系统跑起来

‍♂️ 个人主页小李同学_LSH的主页✍ 作者简介LLM学习者 希望大家多多支持我们一起进步如果文章对你有帮助的话欢迎评论 点赞 收藏 加关注目录Harness定义为什么终端型 Coding Agent 比聊天机器人难得多Scaffolding 和 Harness到底有什么区别OpenDev 的核心不是单模型而是复合系统1Plan Mode 和 Normal Mode 分离2Thinking 和 Action 分离真正决定 Agent 质量的是 Context Engineering1双记忆结构长期目标和短期细节不能混成一团2System Reminders不要指望模型永远记得最初那段 system prompt3Adaptive Context Compaction不要等到快爆了才去总结工具不是越多越好关键是怎么被模型看见安全不是补丁而是架构启发AI Coding Agent 真正难的不是写代码而是把系统跑起来Harness Engineering正在成为 AI Agent 开发圈的高频词。Mitchell Hashimoto 在博客里用了这个说法他原话是“我不知道业界有没有公认的术语我自己管这叫 harness engineering”harness engineering is the idea that anytime you find an agent makes a mistake, you take the time to engineer a solution such that the agent will not make that mistake again in the future.—— Mitchell Hashimoto本文参照此文章核心论文[2603.05344] Building Effective AI Coding Agents for the Terminal: Scaffolding, Harness, Context Engineering, and Lessons Learned论文提出了一个终端原生的开源 coding agent——OpenDev。作者认为CLI 形态的 agent 之所以重要是因为终端本来就是开发者管理源码、执行构建、连接远程环境的主战场。可一旦 agent 进入这个场景它马上会遇到几个硬问题上下文很快膨胀、工具 schema 会吃掉 token、长会话里规则会“失忆”而且 shell 命令带来的安全风险远高于普通聊天场景。工程技术在智能体优先的世界中利用 Codex | OpenAIAgent Model Harness。你不是模型那你就是 Harness。Harness定义“Harness” 这个词字面意思是“马具”就是套在马身上、让人能控制马匹方向和力量的那套装备。 用在 AI 编程的语境里它的比喻再贴切不过AI Agent 就像一匹动力十足但不太守规矩的马而 Harness 就是那套让它既能跑得快、又不会跑偏的缰绳和马鞍。Harness 就是模型之外的一切——系统提示词、工具调用、文件系统、沙箱环境、编排逻辑、钩子中间件、反馈回路、约束机制。模型本身只是能力的来源只有通过 Harness 把状态、工具、反馈和约束串起来它才真正变成一个 Agent。为什么终端型 Coding Agent 比聊天机器人难得多普通聊天机器人可以只关心“一问一答”。但终端型 coding agent 不是这样。它要做的是读文件、查目录、跑命令、启动进程、看报错、修改代码、再回来继续执行。也就是说它不是一次性输出而是在一个持续运行的闭环里工作。论文一开头就给出几个关键挑战上下文窗口有限工具和命令执行带来真实风险能力扩展不能把 prompt 先撑爆。OpenDev 的四层系统架构。 Entry UI、Agent、Tool Context、Persistence 四层。从整体上看OpenDev 并不是“一个模型 一堆工具”的简单组合而是一个分层系统输入层负责 CLI / TUI / Web 入口Agent 层负责推理与执行Tool Context 层同时处理工具调用和上下文工程Persistence 层则负责配置、会话、缓存与结果落盘。这个分层很朴素但特别重要因为它说明作者不是把“LLM 调用”当中心而是把“长期运行的 agent 工作流”当中心。Scaffolding 和 Harness到底有什么区别这篇论文里最值得记住的两个词就是scaffolding和harness。Scaffolding可以理解成“搭脚手架”。在真正开始推理之前系统要先把 prompt 模板、工具 schema、subagent 注册、模型能力信息等东西拼装好。它解决的是“agent 在启动前如何被构造出来”。Harness则是运行时编排层。它把一个原本无状态的 LLM包装成一个持续运行、会调工具、会做纠错、会保存状态的 agent。它处理的是“启动之后发生的一切”推理循环怎么跑、工具怎么调、错误怎么恢复、上下文怎么压缩、安全怎么拦、状态怎么持久化。换句话说Scaffolding 负责把 agent 造出来Harness 负责让 agent 活下去。Agent Harness 架构。中心是扩展后的 ReAct Loop外围是 Prompt Composition、Tool Registry、Safety、Context Engineering、Memory Session、Subagent Orchestration 等运行时子系统。Harness 的中心仍然是 ReAct loop但它已经不是简化版“Thought → Action → Observation”了。论文把它扩展成了六阶段运行循环预检查与压缩、thinking、self-critique、action、tool execution、post-processing。外面还包着安全系统、工具分发、上下文工程、记忆与会话、子代理编排等一整圈基础设施。真正的 Agent 不再只是模型本身而是“模型 运行时系统”的复合体。OpenDev 的核心不是单模型而是复合系统论文没有采用“一个模型包打天下”的思路而是明确做了工作负载分工。OpenDev 把不同阶段路由给不同模型角色比如 action model、thinking model、critique model、vision model、compact model。原因很简单推理、视觉分析、上下文压缩本来就不是同一种任务用同一种模型做所有事情要么太贵要么效果不够稳。以后真正好用的 Agent往往不是“单模型更强”。而是整个系统在不同环节做最合适的能力分配。1Plan Mode 和 Normal Mode 分离OpenDev 还有一个设计很值得借鉴它把“规划”和“执行”拆开了。Plan Mode 只给只读工具用于探索代码库、分析风险、给出结构化计划Normal Mode 才是真正允许写操作和执行动作的阶段。这样做的好处非常直接在需要规划时模型不会因为看见可执行工具而过早行动。2Thinking 和 Action 分离作者还把 thinking phase 单独拆成一个无工具推理阶段。这个思路特别像在强制模型“先想清楚再动手”。因为一旦工具可见很多模型会倾向于立刻执行而不是认真权衡方案。对于复杂任务这种分离很关键。真正决定 Agent 质量的是 Context Engineering如果说 Harness 是运行时骨架那Context Engineering就是这篇论文的灵魂。作者反复强调终端 agent 不是不会推理而是很容易在错误的上下文里推理。文件内容、命令输出、历史消息、工具说明、系统规则这些东西一旦管理不好模型就会越来越“跑偏”。Context Engineering 层。用户查询先进入 QueryProcessor 与 ContextPicker再经过 ContextCompactor 控制 token 预算最后送入 ReAct Core。论文里把这一层拆成好几个子机制动态 system prompt 组装、双记忆结构、系统提醒、错误恢复模板、上下文压缩、经验记忆等。它不是一个单独的小优化而是一套围绕上下文生命周期展开的系统设计。1双记忆结构长期目标和短期细节不能混成一团论文提出了 dual-memory architecture把上下文拆成两部分一部分是压缩过的长期记忆用来保留目标、决策和关键路径另一部分是高保真的短期上下文用来保留最近几轮里最具体的文件内容、报错和行号。这个设计非常合理因为复杂任务中你既不能忘掉全局目标也不能丢掉当前动作所依赖的细节。2System Reminders不要指望模型永远记得最初那段 system prompt‘作者观察到一个很真实的问题会话一长模型虽然还能“看到”最初 system prompt但注意力会逐渐偏向最近消息于是早先的规则开始失效。比如系统一开始明明要求“改完代码后一定跑测试”但二十多个 tool call 之后模型就可能直接宣布 done。System Reminders 的作用。没有提醒时agent 容易在 todo 未完成时提前结束有提醒时运行时系统会在关键决策点插入短消息把模型拉回正确轨道。OpenDev 的做法不是反复重放整段 system prompt而是在关键节点注入很短、单用途的提醒。这个设计非常妙因为它相当于把行为校正从“启动时一次性灌输”改成了“运行时按需纠偏”。3Adaptive Context Compaction不要等到快爆了才去总结有点像dropout普通系统常常是上下文快满了才做一次大规模压缩。这种办法太晚也太粗暴。OpenDev 提出的 ACC 更像一个分阶段减压系统70%、80%、85%、90%、99% 五个阈值逐步采用 warning、masking、pruning、aggressive masking 和最后的 LLM summarization。Adaptive Context Compaction。不是等到 99% 再一次性压缩而是在多个压力阈值上逐步处理尽量延迟真正昂贵的总结。这个机制有两个好处。第一它把很多原本只能靠“紧急总结”解决的问题前置成了持续的小处理第二它尽量保留最近最有价值的细节而不是一刀切地把所有旧内容都糊成摘要。论文报告说这套机制把 observation 的峰值上下文占用降低了约 54%而且在很多情况下直接避免了 emergency compaction。工具不是越多越好关键是怎么被模型看见很多人做 agent会陷入一种天然冲动把能接的工具全接上再把所有 schema 一次性塞给模型。论文对这个问题的态度非常明确工具扩展能力很重要但不能以牺牲上下文效率为代价。工具层架构。Schema 构建、调度分发、生命周期 hooks 被拆成独立组件避免“工具一多系统就乱”。OpenDev 用 ToolSchemaBuilder 统一构造 schema再由 ToolRegistry 进行分类分发。更关键的是外部 MCP 工具不是全量加载而是按需发现。也就是说模型一开始只知道“有哪些服务器、有哪些能力方向”真正具体的工具 schema 只有在需要时才被拉进上下文。Lazy MCP Tool Discovery。先 search_tools 找到最相关工具再把对应 schema 加进后续上下文而不是启动时全量注入。论文给出的数据很直观如果一开始把所有外部 tool schema 都塞进 prompt启动时就可能吃掉接近 40% 的上下文预算改成 lazy discovery 之后启动成本可以压到 5% 以下。这其实是非常典型的 Agent 系统设计原则能力要可扩展但元信息不能先把系统拖死。安全不是补丁而是架构终端 agent 最大的不同之一在于它真的可能执行命令、删除文件、启动进程。论文因此做了五层防御prompt 级规则、schema 级工具约束、运行时审批系统、工具级校验、以及 hooks 机制。作者强调的一个关键观点是相比“让模型先看到危险工具再在执行时阻止它”更好的做法是从 schema 层就不让它看到不该用的东西。这让我特别认同。因为对 Agent 来说最稳的安全策略往往不是更复杂的运行时拦截而是更早的能力裁剪。系统如果一开始就把危险能力从可见面上剔除模型根本不会围绕这些能力进行规划自然也少了很多后续补救成本。启发读完这篇论文我最大的感受不是“OpenDev 很强”而是它把一个经常被说得很玄的东西落到了工程层面AI Coding Agent 不是一个模型问题而是一个运行时系统问题。只靠 prompt不足以支撑长会话。只靠工具接入不足以保证上下文效率。只靠更强模型不足以保证安全与稳定。只有把 scaffolding、harness、context engineering、tool architecture、安全控制放在一起看agent 才真正像一个可运行的软件系统。把 agent 当作一个长期运行、需要编排、需要约束、需要记忆、需要治理的软件系统来设计。如果你之前把 AI Coding Agent 理解成“会写代码的聊天机器人”那这篇论文会把这个认识往前推进一大步。终端型 agent 真正要解决的不只是生成质量而是运行时质量。它要在几十轮交互里保持目标一致、行为可控、上下文不崩、工具不乱、安全不过界。也正因为如此未来谁能把 coding agent 做得更好未必只取决于模型本身更取决于谁能把Harness、上下文工程、工具发现和安全机制这些底层系统搭得更稳。