企业官网建设流程全解析

先说个我自己的观察。这两年 AI Coding 火到什么程度？市面上能数得出来的 AI 编程工具已经不止两位数，从能在终端里自动改代码的命令行工具，到挂在编辑器侧边栏的对话面板，再到整个 PR 流程都能自动跑的“数字员工”，形态五花八门。但如果你真的拿它们去跑一个稍复杂的任务——比如“帮我给这个模块加上单元测试，顺便把 CI 里那个偶发失败修掉”——你会发现，模型聪明不聪明只是下限，真正决定体验上限的，是一个大家聊得不多、却无处不在的东西：Agent Harness。

我前后在好几个项目里落地过 AI Coding 工作流，从个人脚本到团队协作仓库都试过。坦白讲，模型选型反而好解决，真正需要花心思去理解、去调优的，就是这套 Harness。这篇文章我就想把它解剖开，聊聊它到底由什么组成、每个部件负责什么、为什么它直接决定了你的 AI 编程助手是“能用”还是“好用”，以及落地时最常踩的坑。适合正在做 AI Coding 工具选型或内部平台搭建的开发者，也适合那些想搞明白“AI 到底是怎么自己改代码的”的好奇派。

1. Agent 与 Harness：很多人在第一步就搞混了

1.1 “模型会写代码”和“Agent 能做项目”是两码事

先做一个思想实验。你给 GPT-4o、Claude 或者任何一个编程大模型输入“帮我写一个 Python 脚本，批量重命名当前目录下的文件”，它大概率几秒钟就能给你一段像模像样的代码。但如果你输入的是“帮我重构这个后端仓库的鉴权模块，把 JWT 校验抽成中间件，所有接口都要兼容旧 token，顺便把单元测试补齐”，模型单独干这件事是很吃力的——不是它不懂怎么改，而是它没有能力自己“走进”你的仓库去看代码结构、定位鉴权逻辑散落在哪些文件、逐个改动后再跑测试验证结果。

差异在哪里？在于前者只是“生成一段代码”，后者需要“在一个真实项目环境里持续行动”。模型本身是一个纯粹的函数：输入 token 序列，输出 token 序列。它没有手，没有眼睛，也记不住上一分钟自己说过什么。它所有的“能力外延”，都必须通过一套工程框架去赋予。这套框架，就是 Agent Harness。

我见过不少团队把这两层混为一谈，模型换了一个又一个，发现“Claude 写代码很强啊，怎么放到我们的任务里就不行了”，最后归咎于模型不够聪明。其实问题往往出在 Harness 太弱：工具接口没封装好、上下文被撑爆、错误恢复逻辑缺失。模型还是那个好模型，但“骨架”撑不起它。

1.2 Harness 与 Agent 的分工：一个管脑子，一个管手脚和骨架

要理解 Harness，先要理解 Agent 这个词在工程语境下的含义。

Agent 是“有自主决策能力的程序实体”，它接收一个目标，自己规划步骤，调用工具，观察结果，反复迭代直到任务完成。而 Harness 是“承载这个 Agent 的固定工程结构”，它解决了 Agent 运行所需的全部基础问题：上下文窗口放不下整个仓库怎么办？Agent 要跑测试、执行命令，安全边界怎么划？工具调用失败、返回了异常输出，重试策略是什么？Agent 跑了一半进程挂了，现场怎么恢复？

我习惯用“人”来类比：模型是大脑，Agent 是完整的“人”——能思考、能行动、能感知；Harness 是这个人所在的“工作环境”——办公桌、电脑、网络、工具架、操作手册，以及一套“遇到问题去找谁”的规则。你说一个人厉不厉害，大脑很重要，但如果他的电脑是坏的、工具是钝的、工作流程是混乱的，再聪明的脑子也发挥不出来。

下面是这三层职责的一个简单对照：

这里补充一个行业内正在发生的变化。早期的开源 Agent 项目，Harness 通常是很薄的一层，无非是“把 prompt 拼好，调模型 API，把结果打印出来”。但到 2026 年，随着 Codex 这类产品喊出“as a platform”的口号，越来越多团队意识到：Harness 本身才是有长期复用价值的平台层。底下的模型可以三天两头换新的，但一套设计良好的 Harness 可以稳定支撑不同模型、不同任务、不同团队的使用场景。这也是为什么我觉得，值得花一整篇文章来解剖它的结构。

2. Agent Harness 的内部骨架：六大核心组件逐个拆解

2.1 编排引擎（Orchestration Loop）：整个 Agent 的“心跳”

任何一个 Agent Harness，最核心的部分都是那个循环。它决定了 Agent 以什么节奏感知、思考、行动，也决定了整个系统在什么条件下继续跑、什么条件下停下来。

最常见的编排循环是 ReAct（Reason + Act）模式：把模型的推理、工具调用、观察结果串成一个循环。简化后的逻辑是这样的：

def agent_loop(task: str, max_iterations: int = 20): messages = [{"role": "user", "content": task}] for step in range(max_iterations): # 1. 推理：让模型基于当前对话历史决定下一步动作 response = llm.chat(messages) # 2. 如果模型判定任务已完成，跳出循环 if response.is_final(): return response.content # 3. 否则解析出要调用的工具和参数 tool_name, tool_args = parse_tool_call(response) # 4. 执行工具，并把结果以 tool 消息形式追加回对话 observation = execute_tool(tool_name, tool_args) messages.append(response.to_message()) messages.append({"role": "tool", "tool_name": tool_name, "content": observation}) raise MaxIterationsExceeded()

这段伪代码看起来简单，但它背后藏了好几个 Harness 设计的决策点，每一个都是坑。

第一个决策点是“什么时候停止”。你不可能让 Agent 无限循环下去，所以必须有最大步数限制。但限制设得太小，大任务跑到一半就被掐断；设得太大，成本超支。我在生产环境里一般把默认值设在 30 到 50 步，同时加上成本上限和 token 上限，三重保险。这里没有银弹，只能根据任务特征调。

第二个决策点是“模型输出如何转成工具调用”。早期方案是让模型输出一段 JSON，然后正则解析，极其脆弱。现在主流做法是使用模型的原生工具调用（function calling / tool use）能力，模型会返回结构化的 tool_call 对象，不需要你自己做脆弱的文本解析。但也有例外：如果你用的模型工具调用能力很弱，你仍然得靠 prompt 约束输出格式。这是 Harness 设计里“适配层”要处理的兼容性难题。

第三个决策点是“工具执行的结果如何反馈给模型”。这个看似简单，实际上非常关键。因为工具输出可能超大——比如git diff的输出可能几千行，pytest的结果可能几百行——你不能全都不加筛选地扔回上下文里，否则很快就把 Token 窗口塞满了。我在后面上下文管理的部分再细讲。

2.2 上下文管理：Token 窗口的“内存管理”

大模型的上下文窗口再大，也有天花板。2026 年很多模型支持 100 万甚至 200 万 token 的上下文，听起来很大，但一个中大型代码仓库的全文可能有几百万行代码。你不可能把整个仓库丢进去。就算能，成本也扛不住。所以 Harness 必须设计一套上下文管理策略。

我在实际项目里把上下文管理分成三个层级，越靠前越是被高频访问的。

第一层是“对话历史”。也就是 Agent 和模型之间一来一回的消息序列。这部分内容最多、增长速度最快，也是最容易失控的地方。需要策略包括：历史消息截断、摘要化、丢弃过时的工具输出等。比如 Agent 已经跑了 20 步，前 10 步的详细操作过程对当前决策可能已经没有帮助了，Harness 可以把它们压缩成一段摘要：“你已经完成依赖安装和环境配置，当前在修改 auth.py 的 token 校验逻辑”。

第二层是“仓库上下文”。也就是 Agent 对代码库结构的理解。常见做法是：启动时构建一个仓库地图，包含目录结构、每个文件的用途摘要、关键符号索引，然后让 Agent 按需“点开”具体文件读取详细内容。这就好比一个人刚进一家公司，先看组织架构图和岗位职责说明，遇到具体问题再找对应的人聊，而不是把全公司每个人的全部聊天记录都背下来。

第三层是“长期记忆”。项目维度的历史经验，比如“上一个任务里我们发现 auth.py 的旧 token 兼容逻辑不能再动了，动一次炸一次”，这种跨任务的教训需要持久化存储。现代 Harness 一般会用向量数据库或结构化文件来管理这类记忆。

伪代码层面，一个粗粒度的上下文管理器大概长这样：

class ContextManager: def __init__(self, tokenizer, max_context_tokens=128000): self.tokenizer = tokenizer self.max_tokens = max_context_tokens self.history: list[Message] = [] self.summary: str = "" def append(self, message: Message): self.history.append(message) self._compact_if_needed() def _compact_if_needed(self): total = self.tokenizer.count([m.content for m in self.history]) if total < self.max_tokens: return # 把最旧的一半压缩成摘要，保留最近的消息 old_messages = self.history[:len(self.history) // 2] self.summary = self.tokenizer.summarize(old_messages) self.history = self.history[len(self.history) // 2:] def to_messages(self) -> list[Message]: if self.summary: return [{"role": "system", "content": f"前期进展摘要：{self.summary}"}] + self.history return self.history

这个版本非常粗糙，但思路是对的。它保证任何时刻发给模型的上下文都不会超过窗口上限，同时保留最近最关键的信息。

2.3 工具调用层：Agent 的“手”

没有工具调用能力的 Agent 只是个聊天机器人。工具调用层就是 Harness 赋予 Agent 的那双手。这层要解决的问题是：Agent 能调用哪些工具？工具的参数如何声明？工具的输出如何返回给模型？

核心的工程点在于工具定义的 Schema。无论是 Anthropic 的 tool use 还是 OpenAI 的 function calling，都要求你为每个工具写一份 JSON Schema，声明工具名称、参数名、参数类型、必填项、描述。这份描述写得清不清楚，直接影响工具被调用的准确率。我见过太多项目，工具描述写的是“Executes command”，模型根本不知道什么时候该调它。我总结的实践是：每个工具描述要写清“这个工具是干什么的”“什么时候用”“什么时候不要用”“参数格式是什么”。

举个我踩过坑的例子。有一个工具是让 Agent 执行终端命令，最初 Schema 写得很简陋，只声明了command这个字符串参数。结果模型经常把cd /repo && npm test这种组合命令直接塞进去，看起来没问题，但一旦涉及到需要交互式输入的命令就会卡住。后来我在描述里明确了“默认使用非交互模式执行命令，不支持交互输入，如果命令可能长时间运行应使用 timeout 参数”，调用准确率立刻上了一个台阶。

工具层的另一个重要设计是“工具的粒度”。工具太粗，比如只有一个“auto_fix()”工具，Agent 没有灵活度；工具太细，比如有 50 个小工具，模型的选择压力就很大，容易选错。我的经验是控制在 10 到 15 个工具以内，按能力域分组：仓库操作、命令执行、测试运行、Git 操作、信息搜索。每个域的底层实现归一个工具，但通过参数来区分动作。

2.4 沙箱与执行环境：Agent 的安全边界

AGI 还没来，现在的 Agent 只是个会犯错的程序。你让它改代码，它可能把生产库删了；你让它跑测试，它可能启动了一个占满内存的进程。所以 Harness 必须有沙箱机制，把 Agent 的执行权限约束在一个可控范围内。

这一点在不同工具里做法不一样。轻量级的可能只是用一个受限的 Docker 容器跑命令；重量级的会做系统调用级别的隔离，比如 gVisor。对于大多数团队，我建议至少做到这几点：

首先，Agent 默认运行在一个独立容器里，容器内没有宿主机 SSH 密钥、云厂商凭证等敏感信息。它需要访问什么，就在环境变量里显式注入，绝不把整个宿主环境透传进去。其次，网络访问要可配置。多数任务并不需要联网，把网络关掉，既能避免 Agent 去“灵感一来”搜个不存在的库，也能降低数据外泄风险。最后，文件系统要只读底镜像加可写工作目录。Agent 只能改工作目录下的文件，对容器内其他地方只有读权限。

这层做得好不好，决定了你敢不敢把 Agent 放权到自己跑 CI、提 PR。我见过一个团队，最开始没有沙箱，Agent 在测试环境里直接执行了DROP DATABASE，还好那只是个临时库，损失不大，但从此他们把沙箱当成了第一优先级。

2.5 记忆与状态持久化：让 Agent 不“失忆”

一次长任务可能跑几十分钟甚至几个小时。如果任务中途断网、进程崩溃、或者你想在另一个时间点继续这个任务，Harness 必须具备状态持久化能力。

这个状态包含几类东西：一是 Agent 当前的对话历史，包括每一步的推理、工具调用和结果；二是任务上下文，比如当前工作目录的位置、已经修改过的文件列表；三是长期记忆，也就是从历史任务中沉淀下来的经验教训。

持久化的存储介质不复杂，最直接的做法就是序列化成文件或存进数据库。但真正难的是“恢复策略”：当你把一次中断的任务重新加载回来，Agent 如何意识到自己之前干到哪了？我见过最简单的实现是把整个历史重新塞给模型，让模型自己“看一下进度在哪”。这种做法在历史不长的时候可行，历史一长就会触发上下文压缩，模型可能丢失关键细节。更稳妥的做法是在持久化时定期写入一份“任务状态快照”，包含当前目标、已完成步骤、待办事项，恢复时优先把快照注入上下文。

这里分享一个我比较推荐的轻量结构：

{ "task_id": "a3f9c2e0", "goal": "重构 auth 模块，抽取出 JWT 中间件", "status": "in_progress", "completed_steps": [ "扫描仓库确认 token 校验逻辑集中在 auth.py 和 utils/jwt.py", "创建 middleware 目录，编写 jwt_auth.py 初版" ], "next_steps": [ "将旧接口迁移到新中间件", "运行 pytest 验证功能", "补充单元测试" ], "working_dir": "/workspace/repo", "modified_files": ["middleware/jwt_auth.py"], "updated_at": "2026-08-14T08:30:00Z" }

这份快照的恢复成本很低，但价值极高。它让 Agent 具备了“跨会话工作”的能力，这也是现在很多平台级 harness 和其他“一次会话搞定一个任务”的轻量工具之间的重要分水岭。

3. 为什么 Harness 直接决定 AI Coding 的成败

3.1 先看一个 10 万行仓库的实际场景

聊完了组件，我们来把视角拉到真实场景。假设你的团队打算用 AI Coding 工具重构一个 10 万行代码的微服务仓库，任务是把鉴权逻辑从散落的 20 个文件里统一抽到中间件。

模型很强，但它在没有 Harness 的情况下根本无从下手——它看不到你的仓库结构，不知道哪些函数在哪些文件里，不知道测试抽出来之后怎么能跑通。而一个合格的 Harness 是这样协同工作的：

第一步，Harness 通过仓库映射工具快速扫描整个仓库，生成一份结构化的索引。第二步，Agent 根据索引定位到可疑文件，调用文件读取工具查看具体代码。第三步，Agent 制定重构计划，调用代码编辑工具逐个文件修改。第四步，每次修改后，Agent 调用测试工具运行相关测试用例，根据失败反馈继续调整。第五步，全部测试通过后，Agent 调用 Git 工具创建分支、提交代码、推送远程。

你看，这整条链路上的每一步，单靠模型都做不到，必须由 Harness 把“模型想法”翻译成“仓库里的真实动作”。如果没有一套好用的 Harness，模型纵有屠龙之技，也无龙可屠。

3.2 上下文危机：系统提示词、工具描述和仓库内容抢地盘

一个常见的误区是：只要模型上下文窗口够大，就可以把仓库全塞进去。这样做的问题远不只是成本。我实测过一个 20 万 token 仓库全文塞进去的场景，模型确实能“看到”所有代码，但任务的推理质量反而显著下降。原因在于注意力被稀释了：真正关键的三行代码淹没在一大片无关代码中，模型抓不住重点。

这就是 Harness 上下文管理策略价值最直观的体现。它要做的是“选择性暴露”：不是让模型看到一切，而是确保模型在任何时刻都能看到“它当下最需要的一切”。上下文里的每一分空间都很珍贵，系统提示词、工具描述、仓库索引、任务历史、工具输出，五类内容在争抢有限的窗口。好的 Harness 会动态调节它们之间的比例。

我常用的参数是：

context_budget: system_prompt_max_tokens: 4000 tool_definitions_max_tokens: 6000 repository_index_max_tokens: 12000 task_history_max_tokens: 64000 tool_output_max_tokens: 20000 reserved_for_reasoning: 20000

这个配置不是我拍脑袋定的，而是根据多次实测调整出来的。系统提示词和工具定义不能砍，它们决定了 Agent 的基本行为方针；仓库索引控制在 1.2 万 token 左右，既能覆盖中等仓库的常规结构，又不至于喧宾夺主；任务历史给了最大的空间，因为它是 Agent 当前决策的直接依据；工具输出每次控制在 2 万 token 内，超出部分自动截断或摘要。

3.3 工具调用的可靠性：一个 JSON 解析失败，Agent 就废了

工具调用环节，有一个细节特别容易忽视，却又特别致命：模型返回的工具调用参数需要在 Harness 里被正确解析和执行。早期的做法是让模型输出 JSON 字符串，然后程序去 JSON.parse。模型偶尔会在 JSON 里多一个注释、少一个引号，或者把布尔值写成字符串，导致解析失败。这个问题的出现频率，远比你想象的高。

现代 Harness 的应对策略有两层：第一层，优先使用模型厂商提供的原生工具调用能力，参数以结构化对象返回，不做文本解析；第二层，当原生能力不可用时，设计一套容错机制。比如解析失败后不直接报错，而是把解析错误作为反馈送还给模型，让模型自己修正输出，最多重试两三次。

我在一个自研 Harness 里就实现过类似的重试机制，核心逻辑大致是：

def safe_parse_tool_call(raw_response, max_retries=2): for attempt in range(max_retries): try: return extract_tool_call(raw_response) except ParseError as e: # 将错误信息反馈给模型，让它修正 feedback = f"你的工具调用参数解析失败：{e}。请检查 JSON 格式，确保所有 key 都使用双引号。" raw_response = llm.chat([...] + [{"role": "assistant", "content": raw_response}, {"role": "user", "content": feedback}]) raise ToolCallParseFailed()

这个方案的原理很简单：与其让程序死磕模型输出的“脏数据”，不如利用模型的自我纠错能力。模型看到自己的输出被解析器拒绝，并且收到了具体的错误信息，绝大多数情况下都能在下一次生成时修正。这个技巧在我的落地经验里，几乎把工具调用成功率从 95% 提升到了 99% 以上。

3.4 成本与延迟：Harness 是天然的“节流阀”

说一个经常被忽略的视角：Harness 其实是控制 AI Coding 成本的核心环节。同一个任务，用一个设计不良的 Harness，可能要让模型反复读取大文件、尝试多次失败的工具调用，最终消耗 3 到 5 倍的 token；而一个设计良好的 Harness，能通过上下文压缩、工具结果筛选、失败快速止损，把成本压到前者的五分之一。

这里有两个常见的排查方法。一是打开详细的 token 日志，看每次循环的输入 token 是怎么分布的。如果发现工具输出占据了大量 token 但实际没被用上，那就应该在工具输出层做裁剪。二是关注“无效迭代”的次数，即模型反复调用相同的工具、得到相同结果的轮数。这类无效迭代是延迟和成本的双重杀手，Harness 可以通过“结果缓存”来避免：同一工具、相同参数、相同输入文件内容，直接返回上一次的结果。

4. 工程落地：一个轻量 Harness 的搭建参考

4.1 从零搭一个最小可用循环

聊了不少理论，我们实际动手理一个最小可用的 Harness 骨架。以下是一个不依赖特定云厂商 SDK 的简化实现示意，目标是跑通“Agent 能读取文件、执行命令、修改代码、运行测试”这条主链路。

# harness_core.py import os import subprocess from dataclasses import dataclass, field from typing import Callable, Any TOOLS: dict[str, Callable] = {} def register_tool(name: str, schema: dict, handler: Callable): TOOLS[name] = {"schema": schema, "handler": handler} @register_tool("read_file", { "type": "object", "properties": {"path": {"type": "string", "description": "文件路径"}}, "required": ["path"] }, lambda **kw: open(kw["path"]).read()) @register_tool("write_file", { "type": "object", "properties": {"path": {"type": "string"}, "content": {"type": "string"}}, "required": ["path", "content"] }, lambda **kw: open(kw["path"], "w").write(kw["content"]) or "ok") @register_tool("run_command", { "type": "object", "properties": {"command": {"type": "string"}, "timeout": {"type": "integer", "default": 30}}, "required": ["command"] }, lambda **kw: subprocess.run(kw["command"], shell=True, capture_output=True, text=True, timeout=kw.get("timeout", 30)).stdout[-4000:]) def execute_tool(name: str, args: dict) -> str: if name not in TOOLS: return f"Error: 未知工具 {name}" try: return str(TOOLS[name]["handler"](**args)) except Exception as e: return f"Error: {e}"

配合前面提到的编排循环，再加一个模型客户端，就能组成一个很简版的 Harness。当然这个版本离生产可用还差得远——没有沙箱、没有上下文压缩、没有状态持久化——但它足够让你理解 Harness 的骨架结构：工具注册表是“手”，编排循环是“大脑的节拍器”，上下文管理是“短期记忆”。

4.2 关键配置项与参数选择参考

如果你打算在团队内搭建或选型 Harness，我整理了一份我认为比较关键的参数清单，可以当作对照表来用：

这些值不是固定的，不同任务类型差异很大。比如处理大型重构任务时，我会把最大迭代步数放大到 80，但提高每步的“收敛检查”频率；而处理简单脚本生成时，步数压在 10 到 15 步就够了，多一步都是在浪费钱。

4.3 团队协作：一个 Harness，多个开发者的正确姿势

团队使用 AI Coding 工具，和单人体验完全是两码事。单人场景下，你不太在意 Agent 是不是动了别人的代码，冲突了手动处理就行；团队场景下，你必须考虑共享 Harness 的并发、隔离、权限问题。

我建议团队实践里的一个基本配置：Agent 每次任务启动时，从主干拉一个独立的工作分支，所有修改都提交到这个分支上，任务完成后生成 PR，由人类成员审核合并。这个流程听起来没什么技术含量，但它从根本上避免了“Agent 直接在主干上乱改”的灾难。

另一个容易踩的坑是“环境漂移”。同一个任务，两个开发者分别在自己电脑上跑同一个 Harness，结果可能因为本地环境不同而产生不同结果。团队落地时，最好把 Harness 的运行时做一个标准化镜像，所有人用同一个容器运行 Agent。这样至少能保证“Agent 看到的文件系统”是一致的，排查问题会容易得多。

我们还试过更进一步的协作模式：给不同 Agent 分配不同的能力域，比如一个 Agent 专门负责前端 UI 修改，另一个负责后端 API，通过共享的 Harness 状态库协调进度。这个模式还没有完全跑顺，中间有不少同步问题，但方向我判断是对的——AI Coding 的终局不会是一个全能 Agent 单打独斗，而是多个专业 Agent 在统一 Harness 下协作。

5. 常见问题与排查技巧实录

这一节我把实际使用 Harness 过程中最常遇到的问题整理出来，每个都附上排查思路和解决策略，可以直接当速查表用。

5.1 Agent 在同一个问题上反复绕圈

表现：日志里能看到 Agent 反复调用同一个工具，或者反复进行同一个推理步骤，输出高度相似，就是没有实质进展。

原因分析：最常见的是上下文里缺少“否定性信息”。Agent 尝试了方案 A 失败，但它的上下文里没有被明确告知“方案 A 已被验证不可行，不要重复尝试”。尤其是上下文被截断或摘要之后，早期的失败尝试可能被压缩掉了，Agent 就“忘了”自己已经试过这条路，于是又走回去。

解决办法：在上下文管理里增加一个“已尝试方案清单”。每次工具调用失败或者代码改动导致测试失败时，把失败结果和失败原因结构化记录下来，并注入到每轮推理的上下文中。这样即使早期历史被压缩，Agent 也知道哪些路已经被堵死。另外把“如果某方案连续失败两次，切换思路”写进系统提示词，也能有效减少绕圈。

5.2 工具调用参数频繁解析失败

表现：模型返回工具调用后，参数解析总报错，Agent 无法真正执行工具。

原因分析：要么是模型对工具 Schema 的遵循度不够，要么是工具 Schema 本身定义得不好。比如参数名和自然语言描述不一致，或必填参数定义漏了，导致模型生成了不完整的参数。

解决办法：优先启用模型的原生 tool call 能力，而不是让模型输出文本再解析。如果仍要解析文本，务必在解析失败时把错误反馈给模型，让它自己修正，而不是直接抛异常终止任务。同时审查工具描述，检查是否足够具体、是否有歧义。实测下来，把工具描述从 30 个字扩充到 100 个字，精确描述“什么时候用、什么时候不用、参数怎么填”，能把选错工具和写错参数的概率降低一半以上。

5.3 上下文爆炸导致回答质量断崖式下降

表现：任务跑到后期，模型开始“忘记”最初的指令，或者频繁生成不相关的代码。查看日志，发现输入 token 已经逼近上下文窗口上限。

原因分析：上下文管理失效。通常是没有及时清理过时的工具输出，或者没有把早期对话历史压缩成摘要。有些 Harness 开发者会简单地把上下文窗口设小一点来“避免超限”，结果窗口内的有用信息更少了，质量下降得更厉害。

解决办法：这是我推荐的排查顺序。先看 token 分布：打开请求日志，看哪些类型的消息占用了最多 token。如果工具输出占比很高，就在工具层做输出裁剪；如果历史消息占比很高，就加大摘要压缩力度；如果是系统提示词本身太长，试着精简它。目的不是“别超限”，而是“把有限的窗口留给最有价值的内容”。这一步是最需要持续调试的，因为它直接关系到模型的输出质量。

5.4 沙箱内跑不通，沙箱外全正常

表现：Agent 在沙箱里执行命令老失败，比如找不到某些依赖、npm install 装不上、权限不足，但你在自己电脑上跑同样的命令一切正常。

原因分析：沙箱镜像和宿主机环境不一致。最常见的坑就是网络限制。我把网络默认设为关闭，结果 Agent 执行 npm install 时直接失败，报错信息不能说明问题，我花了半小时才排查出来。另一个常见问题是依赖缓存：沙箱里没有本地的缓存目录，安装时间暴涨，超时后被 kill。

解决办法：在沙箱内引入可复用的缓存卷，比如 npm、pip、gradle 的缓存目录都挂载到持久化卷上。这样第一次安装慢，后续任务直接命中缓存。网络方面采用白名单机制：少数明确需要的域名开放访问，其余一律关闭。这样既不影响构建速度，也把风险控制住了。如果某个命令在沙箱内怎么都跑不通，我的排查习惯是先在沙箱内手动执行一遍，逐条对比环境变量和依赖版本，很多时候问题出在默认 shell 配置不同。

5.5 Agent 修改了不该碰的文件

表现：回看 diff，发现 Agent 改了一些与任务完全无关的文件，比如把 README 的格式顺手改了，或者动了某个配置文件里与任务无关的字段。

原因分析：模型对“最小变更原则”的理解不够。它在看到一个文件时，容易顺手“优化”那些看起来奇怪但不影响任务的内容。这种问题在文件较大、任务定义不够清晰时尤其明显。

解决办法：在系统提示词里明确写清楚“只修改完成该任务必需的内容，禁止无关改动”，同时把任务描述得更精确，标注“可以改哪些文件、不要动哪些文件”。代码审查环节也要保留：Agent 提交的 PR 仍然要人工 review，这是底线。我的习惯是让 Harness 生成一份“修改摘要”，列出每个改动文件的变更原因，这样人工审查时可以快速聚焦到关键 diff。

结尾：我的几点实操体会

文章写到这里，最后分享几个我自己的判断。第一，AI Coding 项目里，模型选型当然重要，但 Harness 才是真正拉开体验差距的地方。同一个模型，放在一个精心设计的 Harness 里和放在一个粗糙的壳子里，表现能差出一大截。第二，Harness 的设计没有标准答案，完全取决于你的使用场景。跑个人脚本的轻量工具和组织级 AI 开发平台的 Harness，复杂度不在一个量级，硬套别人的方案很可能水土不服。第三，不要等所有组件都完美了再落地。哪怕是只有“读取文件、改代码、跑测试”三件套的最小 Harness，都能帮你跑通流程、发现问题，再迭代完善。

如果问我有什么最值得先做的小改进，我会说：先看一眼你的 AI Coding 工具，它每次调用模型时，发给模型的上下文里有多少是“废话”。把工具输出裁剪一下、历史摘要做一下，往往是最低成本、最高回报的优化。这个动作做完，你会明显感受到 Agent 的“智商”提升了一截。