企业官网建设流程全解析

搞LLM应用这一年多，我最大的感受就是：让模型写一段漂亮回复根本不算本事，真正磨人的是把一个智能体Agent放到真实场景里反复跑，让它不崩、不乱、不烧钱。这个过程中我折腾最多的，就是标题里的Agent Harness这个东西——中文语境下可以叫智能体控制器——尤其是上下文管理和编排这两块，几乎每一个上线项目都踩过一遍。

先说清楚这篇文章是什么。它不是理论综述，也不是某个框架的广告，而是我自己实践笔记的完整整理：从最朴素的“一个while循环套prompt”开始，逐步讲清楚Harness到底解决了什么问题、上下文怎么管才不会爆、编排怎么做才不会乱、容错怎么写才不会崩，最后给出一套可以直接抄的笔记类Agent Harness代码骨架。适合正在做Agent落地、被上下文炸掉、或者Agent跑着跑着就自行其是的工程师和产品团队参考。

1. Agent Harness 到底是什么：先搞懂它管哪些事

1.1 从裸写循环说起：没有 Harness 的日子

最早我做的所谓Agent，其实就是一个while循环加一个精心设计的prompt。模型输出解析失败就重试，上下文一股脑全塞进去，工具调用的结果也不校验，跑demo的时候一切正常，一上真实数据就原形毕露：生成长文时上下文直接爆掉、模型不懂得收敛、同一个工具反复调用、偶尔还会编造根本不存在的函数名。

这些问题的根源不是模型能力，而是外层缺少一套“让Agent安全运行”的控制装置。你想想，一辆车跑得快不快看发动机，但方向盘、刹车、仪表盘这些都不在发动机里。对LLM来说，Agent Harness就是那套方向盘和仪表盘。

Harness这个英文词，原意是把马套上车的那套挽具。放在智能体工程里，它就是介于LLM和具体业务之间的一层控制框架，负责驱动Agent循环、管理上下文、调度工具、处理错误和持久化状态。简单说：模型是发动机，Harness是驾驶室。

1.2 Harness 和 Agent 的区别：别再混为一谈

这是我被问得最多的问题，也是很多项目设计混乱的根源。Agent指的是业务流程中能做决策、能执行动作的那个执行体，它关心的是目标、策略和工具选择；而Harness是承载Agent的运行环境，它关心的是循环怎么转、状态放哪、出错怎么办。

我常用的一个类比：Agent是演员，Harness是剧组。演员负责演戏，剧组负责剧本分发、场记、灯光、救场。你直接调LLM接口拿到的那段JSON只是演员台词，而你自己写的那个循环、状态管理、工具注册表、召回逻辑、限流熔断，全是剧组的工作。

在代码层面，很多开源框架把这两层揉在同一个类里，比如LangChain的AgentExecutor，既管决策也管执行。但概念上必须分开，否则你很难回答一个问题：如果Agent决策错了，是模型的问题还是Harness的问题？分清楚之后，排查效率会高非常多。

1.3 Harness 的核心职责清单

根据我自己的项目经验，一个合格的Harness至少要覆盖以下八件事：

• 驱动“思考-行动-观察”循环，并控制循环何时终止
• 维护Agent状态，包括当前任务、历史轨迹、中间变量
• 将长期记忆和检索结果按需注入上下文，而不是无脑拼接
• 维护工具注册表，负责参数校验和调用规范
• 解析模型输出，并对不合规输出做修复和重试
• 处理异常，包括超时、限流、工具报错、上下文溢出
• 记录完整运行轨迹，方便离线回放和问题定位
• 统计token消耗和成本，防止预算失控

这八条看着简单，每一条展开都是一堆细节。接下来我挑最折磨人的两块——上下文管理和编排——重点讲。

2. 上下文管理：Agent 的工作台与记忆系统

2.1 先算清上下文这本账：你的窗口真的够用吗

很多团队一上来就选128K窗口的模型，觉得上下文肯定够用，其实根本不是这么回事。我以笔记Agent为例给你算一笔账：

• 系统提示词：写清楚角色、规则、输出格式，大约2000 token
• 用户任务描述：比如“整理五月份第三周的会议纪要”，约300 token
• 工具定义：每个工具的描述和参数Schema大约300 token，注册8个工具就是2400 token
• 对话历史：每轮Agent思考加工具调用，输入输出合计大约1500 token，10轮就是15000 token
• 检索出来的笔记内容：按Top 3召回，每篇500 token，又是1500 token

算下来固定开销就5000 token左右，这还没开始干活。真正跑起来，每多一轮工具调用，输入输出都会增长。128K的窗口看着很大，但模型对长上下文的注意力会衰减，中间位置的信息最容易被忽略，学术界管这个叫lost in the middle。所以上下文管理的核心不是“塞得下”，而是“要塞得准”。

我的实操经验是：把窗口的70%作为上下文预算，剩下的30%是给模型回复和意外情况留的缓冲。具体公式是：

可用历史长度 = 上下文窗口 × 0.7 - 固定开销（系统提示词 + 工具定义 + 任务描述）

这个预算再分给“工作记忆”和“检索注入”两部分，谁重要谁先拿。

2.2 三层上下文架构：核心记忆、工作记忆、外部存储

我把Agent的上下文设计成三层，这是目前最稳定、改造成本最低的方案。

第一层叫核心记忆，就是系统提示词加用户当前任务。系统提示词里只放不会变的东西：角色定位、输出格式、安全边界、工具使用总原则。用户任务描述单独放，因为每次任务不同。这两块是上下文中优先级最高的部分，永远保留。

第二层叫工作记忆，就是当前任务最相关的对话轨迹和中间结果。我会保留最近5轮完整的思考过程，更早的轮次通过摘要压缩。为什么只留5轮？因为Agent的中间推理有很多是重复的，比如反复比较同一批候选笔记，保留全量纯属浪费token。

第三层叫外部存储，就是不在上下文里、但随时可以检索回来的东西。对我们笔记场景来说，就是全部Markdown笔记的向量索引加摘要库。需要用的时候，通过检索把最相关的几篇注入到工作记忆，用完就丢。

这三层各司其职之后，我几乎没有再遇到过上下文爆掉的问题。

2.3 上下文压缩与裁剪：三种手段的配合打法

压缩不是简单截断，而是分场景用不同手段。

第一是近因滑动窗口。只保留最近N轮完整消息，之前的全部移出上下文。这个方案简单粗暴，适合处理那些历史中确实没有重要信息的场景。缺点也很明显：如果第2轮出现过关键决策，第10轮要引用时已经没了。

第二是摘要压缩。我让LLM每两轮就把前面的对话总结成一段结构化的要点摘要，替换到系统提示词里。注意摘要不是自由发挥，我固定了格式，必须包含：已完成事项、待办事项、关键结论、当前不确定项。这样一个1000 token的长对话可以被压到150 token左右，信息损失可控。代价是每次压缩会额外消耗一次模型调用，所以要设好压缩触发条件，比如窗口占用超过预算60%时才压缩。

第三是结构化检索。笔记内容永远不直接全量进上下文，而是先进向量库，查询时用语义召回TopK，动态拼装成临时上下文块。这块如果要展开，其实就是RAG那一套：分块、embedding、向量检索、重排序。我用的分块策略是按标题切分，Markdown的二级标题和三级标题作为天然边界，每个块控制在400到600 token之间，既保证语义完整，又方便精准召回。

三种手段配合的节奏是：平时靠滑动窗口控制长度，窗口快满时触发摘要压缩，涉及具体笔记内容时走结构化检索。

2.4 上下文一致性的坑：旧数据害死人

上下文管理里最隐蔽的问题不是长度，是一致性。我踩过一次大坑：笔记Agent在第二轮引用了某篇笔记的旧版本，原因是第一轮检索的结果被缓存了，而那篇笔记在第二轮开始前已经被用户修改过。结果Agent基于过期内容做了一堆错误判断。

现在我的所有上下文块都带版本标记和时效信息。工具返回的数据会标注“获取时间”，检索结果会标注“笔记最后修改时间”，系统提示词里明确写了一条规则：如果发现上下文中存在互相矛盾的信息，以标注时间更新的为准，并且要把数据冲突作为一个新事实记录到工作记忆，而不是闷头往下走。

另外，同一篇笔记在同一轮里只允许出现一次。如果滑动窗口和检索结果都包含同一篇笔记的不同版本，Harness会做去重合并，选版本号最高的那个。这个小功能看着不起眼，避免了大量认知混乱。

3. 编排实践：让 Agent 按节奏干活，而不是即兴发挥

3.1 工作流编排与自主编排：两条路线的取舍

编排这个词被用烂了，但实际只有两条路线。

工作流编排，就是预先画好流程图，Agent只能沿着固定节点走。比如笔记整理流程定为“检索→理解→更新→校验”四步，每步之间是硬衔接，模型不能跳步。优点是行为可预测、好调试，缺点是灵活性差，遇到计划外场景容易卡死。

自主编排，就是经典的Agentic Loop，模型每轮自己决定下一步干什么。优点是能处理开放任务，缺点是失控风险高，你不知道它下一步会调哪个工具，也不知道什么时候能停下来。

我的选择是混合编排，固定骨架加局部自主。以笔记类任务为例，整体流程固定为“定位笔记→提取信息→执行修改→自检确认”，但每一步内部，模型可以自己决定用哪个工具、查几个来源、先看摘要还是先看全文。这样既保住了关键路径的确定性，又没牺牲局部灵活性。

3.2 ReAct 模式：思考与行动的循环拆解

ReAct是目前Agent实现的主流范式，核心是Reasoning加Acting交替进行。每一轮循环包括三段内容：

• Thought（思考）：模型分析当前状态，说明为什么这么做
• Action（行动）：调用某个工具，带着参数
• Observation（观察）：工具返回的结果

这三段周而复始，直到模型输出Final Answer。我举个实际轨迹，你就明白这个模式长什么样：

Thought: 用户想整理本周的会议纪要，我需要先找到本周相关的笔记文件。 Action: search_notes(query="本周 会议纪要 周会", top_k=3) Observation: 找到三篇笔记，分别是周一产品评审、周三技术方案会、周五项目同步会。 Thought: 三篇笔记都存在，我需要逐篇提取待办事项，先从第一篇开始。 Action: read_note(note_id="note_1001", section="待办行动项") Observation: 提取到5个待办事项，其中两个已完成，三个进行中。 ...

这个模式的好处是每一步都可解释、可回放，Harness可以清楚地知道Agent在哪一步出错。坏处是轮次多了token消耗大，所以一定要和第二节的压缩策略配合。

3.3 我的 Harness 编排层实现：一个状态机骨架

我代码里的编排层不是一个while循环，而是一个简单的状态机。状态包括：

• IDLE：等待任务
• THINKING：调用LLM生成Thought和Action
• ACTING：执行工具调用
• OBSERVING：处理工具返回结果
• FINISHED：输出最终答案

状态转移规则是：IDLE收到任务后进入THINKING；THINKING产出Action后进入ACTING；ACTING执行完进入OBSERVING；OBSERVING把结果拼回上下文，再回到THINKING；THINKING产出Final Answer时进入FINISHED。任何状态超时或异常都进入ERROR状态，由容错模块接管。

这个状态机的价值在于：你知道Agent当前在哪一步，而不是只有一个笼统的“运行中”。出问题时，能精确说是执行工具崩了，还是模型输出格式坏了，还是上下文超限了。

3.4 任务拆分与优先级：避免 Agent 抓不住重点

开放式任务经常一上来就是个大目标，比如“整理这个月的所有笔记”。如果让Agent直接干，它很容易迷失，一会儿改这篇一会儿翻那篇，最后什么都没完成。我现在的做法是在Harness层先做任务分解。

任务分解的策略是：先让LLM把大目标拆成可独立验证的子任务，每个子任务带依赖关系和预估成本。比如“整理这个月的所有笔记”会被拆成：

• 子任务A：列出本月全部笔记清单，预估20篇
• 子任务B：按主题聚类，识别出会议记录、技术笔记、灵感碎片三类
• 子任务C：逐类提取关键待办和执行状态
• 子任务D：合并去重，生成月度总结笔记

执行顺序由依赖关系决定，B依赖A，C依赖B，D依赖C。优先级则参考三个因素：用户是否在任务描述里强调了某个方向、子任务的依赖深度、token成本。Harness会维护一个任务队列，每完成一个子任务就更新全局状态，让Agent时刻清楚“我已经做到哪一步、还剩什么”。

4. 容错控制与自愈设计：构建不崩的Agent系统

4.1 Agent 的失败模式清单：先知道会怎么死

容错设计的第一步是枚举失败模式。我整理过一张清单，几乎涵盖了所有踩过的坑：

• 输出格式错乱：模型没有按约定的JSON格式输出，多写了注释、少了括号
• 工具幻觉：调用了不存在的工具，或者工具存在但参数编造
• 无限循环：Agent反复执行同一个动作，比如反复搜索同一个关键词
• 上下文污染：工具返回了大量无用信息，把关键信息冲淡
• 幻觉知识：Agent在没有依据的情况下编造笔记内容
• 外部依赖故障：向量库超时、embedding接口限流、文件系统权限错误

这些失败模式里，只有少数能靠换更强的模型解决，大多数必须在Harness层用工程手段拦截。

4.2 三类容错策略：前置校验、运行时控制、后置纠偏

我把容错手段分成三层，按从上游到下游的顺序排列。

前置校验是在工具调用执行之前做的。每个工具都定义了参数Schema，模型输出Action后，Harness用轻量校验器检查参数类型和枚举值范围，不合格的直接拦截，不给工具执行机会。同时维护一个工具白名单，模型只能调用白名单内部署好的工具，从根上消灭工具幻觉。

运行时控制是执行过程中做的。核心参数有三个：最大迭代次数，我通常设10到15，超过就强制终止；单次工具超时，我设30秒到60秒；连续相同动作检测，如果模型连续3轮输出同样的Action和参数，视为死循环，直接打断并提示模型换个策略。

后置纠偏是结果出来之后做的。如果模型输出的JSON解析失败但内容语义完整，我会用一次“结构化修复”调用，把原始输出交给模型重写为合法JSON，最多重试2次。如果最终答案出现事实性矛盾，则触发“无依据自动纠偏”，让Agent回退到最近一个可信状态，提示用户补充信息。

4.3 让 Agent 学会说“我不知道”：验证器与护栏

这是很多Agent系统缺失的一环。大多数内置Agent倾向于编造答案，因为模型的训练目标就是补全文本，它没有“不知道”这个选项。Harness必须强行加一道护栏：所有Action必须挂载验证函数，验证失败时自动切换到“需要更多信息”分支，触发追问或切换检索策略。

比如在笔记场景里，Agent要输出一条行动项，但这条行动项无法溯源到任何一篇笔记内容，验证器就会拒绝，并要求Agent返回指定搜索的观察结果作为证据。这种“无证据不输出”的机制让系统在面对模糊查询时，从“硬编答案”变成了“承认信息不足并主动补全”。

4.4 可观测性：Agents 也需要事后回放

没有轨迹记录的Agent系统就是黑盒，出了问题只能靠猜。我现在的做法是给每一次Agent运行生成一份结构化trace，存到SQLite里。trace包含：

• 全局运行ID和父级ID
• 每轮的Thought、Action、Observation摘要
• 调用的工具名、输入参数摘要、输出摘要
• 每一步的耗时和token消耗
• 错误信息和重试次数

这份trace我称之为Agent的“飞行记录仪”。线上问题出现后，我第一件事不是看代码，而是回放trace，看模型在哪一轮开始跑偏。有几次排查效率从几小时缩短到十几分钟，靠的就是这个。

除了单体Agent的trace，多Agent协作场景下还要给编排层加分布式追踪的思路，用trace_id串联所有子任务，形成一棵完整的执行树。

5. 完整实操案例：从零搭一个笔记 Agent Harness

5.1 场景与需求定义

我从零搭一个“漫游笔记Agent”，它的工作是在一堆Markdown笔记之间检索、提炼、整理、归档。用户输入一句自然语言指令，Agent负责找到相关笔记、提取关键信息、按规则生成新笔记或修改旧笔记，最后输出一份操作摘要。

这个场景非常适合验证Harness设计，因为它涉及检索、读取、写入、总结、校验五类工具，而且每个操作之间都有依赖，上下文天然会膨胀。

硬件和依赖方面，我用的是Python 3.11加一个轻量级异步框架，没有依赖LangChain那种重框架，因为我想把Harness的每一行逻辑都握在自己手里。LLM用支持工具调用的通用模型即可，向量检索我用本地的轻量库，整个系统可以不依赖外部服务运行。

5.2 核心代码骨架：一个可运行的 Harness

下面是我实际项目里简化后的核心骨架，保留了Harness的关键逻辑，你可以直接抄走改改。

import json import time from dataclasses import dataclass, field from typing import Callable, Dict, Optional @dataclass class Tool: name: str description: str parameters_schema: dict handler: Callable validate: Callable = lambda **kwargs: None @dataclass class AgentContext: system_prompt: str messages: list = field(default_factory=list) memory_budget_tokens: int = 8000 tool_call_versions: dict = field(default_factory=dict) class AgentHarness: def __init__(self, llm, tools: Dict[str, Tool], config: Optional[dict] = None): self.llm = llm self.tools = tools self.config = config or { "max_iterations": 12, "max_retries": 2, "timeout_seconds": 45, "token_ratio": 0.7, } self.trace = [] async def run(self, task: str, notes_index) -> dict: ctx = AgentContext(system_prompt=self._build_system_prompt(notes_index)) ctx.messages = [ {"role": "user", "content": task} ] for i in range(self.config["max_iterations"]): # 1. 控制上下文长度，超出预算则压缩 self._enforce_budget(ctx) # 2. 调用模型，生成下一轮动作 response = self.llm.invoke(ctx.messages) action = self._parse_action(response) # 3. 如果模型输出最终答案，直接返回 if action["type"] == "final": return self._finalize(ctx, action["answer"]) # 4. 校验工具参数，失败则重试 ok, validated_args = self._validate_action(action, ctx) if not ok: ctx.messages.append(self._retry_prompt(action, "参数校验失败")) continue # 5. 执行工具调用并记录观察结果 observation = await self._execute_tool(validated_args, ctx) ctx.messages.append({ "role": "tool", "tool_call_id": action["call_id"], "content": observation, }) self._record_trace(i, action, observation) return {"status": "max_iterations_exceeded", "partial_result": self._extract_partial(ctx)} def _build_system_prompt(self, notes_index) -> str: # 核心记忆区：角色、规则、工具使用约束、索引说明 prompt = f"""你是一个知识库笔记助手。当前知识库索引如下： {notes_index.describe()} 规则： 1. 所有事实必须来自工具观察结果，不得编造。 2. 使用工具的步骤中，每次只调用一个工具。 3. 引用笔记时必须标注笔记ID。 4. 最终答案需包含：操作了哪些笔记、提取了哪些关键信息、遗留哪些疑点。 """ return prompt def _parse_action(self, response): # 尝试解析JSON，失败就返回特殊错误让上层修复 text = response.content.strip() try: return json.loads(text) except json.JSONDecodeError: return {"type": "parse_error", "raw": text} def _validate_action(self, action, ctx): tool_obj = self.tools.get(action.get("tool_name")) if not tool_obj: return False, None # 这里可以用jsonschema做严格校验，省略细节 try: validated = tool_obj.validate(**action.get("arguments", {})) return True, validated except Exception: return False, None async def _execute_tool(self, validated_args, ctx): tool_obj = self.tools[validated_args["tool_name"]] try: result = await tool_obj.handler(**validated_args["arguments"]) return json.dumps(result, ensure_ascii=False, default=str) except Exception as e: return f"TOOL_ERROR: {str(e)}" def _record_trace(self, i, action, observation): self.trace.append({ "step": i, "time": time.time(), "action": action, "observation_summary": observation[:200], })

这段代码最关键的设计是_enforce_budget和_validate_action。前者做上下文压缩，后者做工具前置拦截。整个运行循环的终点有两个：模型主动输出Final Answer，或者迭代次数耗尽强制退出。第二种情况下返回“partial result”，后续容错模块可以接管。

5.3 实测效果与参数调优：别信默认参数

我拿一份20篇混乱的Markdown笔记做了压测，原始笔记总字数大概3万，如果全部塞进上下文，一次调用就会超过8K预算。使用上面的Harness后，每轮平均上下文稳定在3000 token左右，原因是滑动窗口和摘要压缩把历史控制住了，检索只注入Top 3。

实测下来几个关键参数的经验值：

调参过程里最意外的是temperature。我早期用0.7，Agent经常在工具参数上发挥创意；降到0.2之后，工具幻觉直接下降了大约七成。如果你的Agent频繁编造参数或工具名，先降温度，再考虑换模型。

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

6.1 上下文越管越乱，Agent 前后矛盾

这是最常见的翻车现场。一般来说，问题不在滑动窗口的轮数，而在压缩时机。太早压缩会把关键决策丢掉，太晚压缩等于没压。

我调试时的第一件事是看trace里的摘要块。如果摘要丢失了某个关键待办事项，就调整压缩触发逻辑，把“待办事项完整性检查”加到压缩提示词里，让模型在生成摘要前先对照原历史做一次查漏。

另一个隐藏问题：有的实现会把压缩后的摘要和原始历史都留在上下文里，导致一个信息两个版本，Agent引用时随机选一个。我的经验是，压缩动作一旦完成，原始历史必须从上下文清出去，只留摘要引用。

6.2 无限循环：Agent 反复做同一个动作

出现这个现象，多半是Observation没有给模型提供有效的新信息。比如模型搜索“周会纪要”，返回为空，它不甘心，又搜了一遍完全一样的关键词。这类死循环靠max_iterations兜底能防住，但更聪明的做法是修改Action去重逻辑。

我在Action执行前会检查一个动作指纹（工具名加参数哈希）。如果最近三跳内出现过完全一致的指纹，就不执行，直接返回给模型一条提示：“该动作与前序动作重复且未产生新结果，请更换关键词或切换检索范围”。

6.3 频繁触发重试但依然解析失败

一次两次解析失败是运气，连续失败就是系统问题了。常见的责任人是输出格式约束写得不够清楚。我发现对模型最有效的格式约束是给一个完整的JSON示例，而不是只给字段定义。

如果你已经给了示例模型还是乱输出，检查一下系统提示词里是否同时出现了多套格式要求。我曾经把“要求输出JSON”和“要求输出Markdown列表”两句话都留在提示词里，模型一会儿输出JSON一会儿输出Markdown，换了更复杂的模板才稳定下来。

6.4 检索结果不相关，Agent 拿着噪声硬干活

检索质量会影响Agent的决策，但很多rank问题不是embedding模型的问题，而是分块策略的问题。我踩过最蠢的一个坑：把整篇5000字的笔记当成一个块去embedding，结果语义向量被严重稀释，查询“待办事项”时根本召不到藏在笔记中段的行动项。

现在我的分块标准是：按二级标题切分，每块400到600 token，块之间允许20%重叠，保证跨标题的上下文不断裂。改为这个策略后，检索命中率提升非常明显。

6.5 成本失控：Agent 不贵，贵在反复试错

最后提醒一下成本问题。一次Agent运行动辄5到10轮调用，每轮输入里都带着浓缩后的历史，累计token远超你写一个prompt的成本。我监控成本的核心指标不是单次调用价格，而是“完成一个标准任务的平均成本”。

压测数据给我一个参考：整理一份周报笔记，当Agent稳定运行时大概需要6轮调用，总输入输出合计约4.2万token；如果Agent出现频繁重试，这个数字会翻到8万以上。所以成本优化的重点不是换更便宜的模型，而是减少无效重试和无效检索。

我现在给Harness加了一条成本告警规则：单任务token数超过同类任务历史均值的2倍时，自动挂起任务并通知人工审查。这条规则已经拦下了好几次因上下文污染导致的成本失控。

我个人在实际操作中最大的体会是：Agent Harness的设计没有银弹，它是一门用工程手段给模型“画跑道”的手艺。模型每多一分自由，Harness就要多一分约束；模型每多一分能力，Harness就要多一分校验。上下文管理解决的是“让模型看得清”，编排解决的是“让模型走得稳”，容错解决的是“让模型摔不坏”，三者缺一不可。

最后再分享一个和开头呼应的小技巧：如果你还在用裸while循环套prompt的方式做Agent，别急着上重框架，先把这篇文章里的五件事补上——迭代上限、预算压缩、参数校验、轨迹记录、成本告警。这五个点花不了多少代码量，但能把一个“能跑”的demo变成一个“敢上线”的系统。