企业官网建设流程全解析

1. 拆开 AI Agent 的“驾驶舱”：Harness 到底管什么

很多人第一次听到 Harness 这个词，脑子里浮现的是线束、安全带或者测试框架。放在 AI Agent 的语境里，它其实更接近“驾驶舱”或者“总装线”的概念。你手里有一个大模型，它能聊天、能写代码、能推理，但它本身只是一个“大脑”，不会自己去看文件、不会自己发请求、不会自己记住上一轮干了什么。Harness 就是把这些能力串起来的那套骨架，让模型从“会说”变成“会做”。

我最早接触 Agent 开发的时候，也走过弯路。那时候觉得只要把 prompt 写好，把工具描述塞进去，模型就能自己规划、自己调用、自己收尾。实测下来完全不是那么回事。模型会忘记自己刚才调用过什么工具，会在多轮对话里丢失上下文，会在工具报错之后反复重试同一个错误参数，甚至会在任务完成之后继续“幻觉”出新的步骤。这些问题不是模型能力不够，而是缺少一个稳定的 Harness 来约束和调度。

所以这篇文章想聊的，就是标题里说的那 7 个子系统。它们不是某个框架的官方定义，而是我在实际搭建和拆解多个 Agent 项目之后，总结出来的一套“最小可用骨架”。你可以把它理解成 Agent 的操作系统：负责启动、负责循环、负责记忆、负责工具、负责安全、负责观测、负责收尾。缺了哪一个，Agent 都会在某类任务上表现得像个“半成品”。

这篇文章适合谁看？如果你正在从 0 到 1 搭建 AI Agent，或者已经在用 DeepSeek Harness、Spring AI、LangChain 这类工具做开发，但总觉得“能跑但不够稳”，那这 7 个子系统的拆解会帮你找到短板。如果你只是好奇 Agent 内部到底怎么运转，也可以把它当成一张结构图来看。下面我会逐个拆开讲，每个子系统都配上我实际踩过的坑和可复现的配置思路。

2. 子系统一：Agent Loop，Agent 的心跳从哪来

2.1 为什么 Loop 是第一个要讲清楚的

Agent Loop 是整个 Harness 的心脏。没有它，模型就只是一次性的问答机器。Loop 的本质是一个“感知-决策-执行-反馈”的循环：读取当前状态，让模型决定下一步动作，执行动作，把结果写回状态，然后进入下一轮。听起来简单，但真正写起来，90% 的稳定性问题都出在这个循环的边界控制上。

我见过最常见的错误写法是while True加一个if task_done: break。这种写法在简单任务上能跑，但一旦模型判断失误，或者工具返回了非预期结果，循环就会失控。要么无限重试，要么提前退出。更麻烦的是，你很难知道它到底循环了多少轮、每轮花了多少 token。

一个可用的 Loop 至少要有四个约束：最大轮次、单轮超时、状态变更检测、终止条件。最大轮次是硬止损，我一般设 15 到 25 轮，具体看任务复杂度。单轮超时是防止某个工具调用卡死，比如网络请求挂起。状态变更检测是判断这一轮和上一轮相比，任务状态有没有实质推进，如果没有推进还继续循环，那就是在烧钱。终止条件则要区分“正常完成”和“异常终止”，前者触发结果汇总，后者触发错误上报。

2.2 一个可落地的 Loop 伪代码结构

下面这段是我常用的 Loop 骨架，用 Python 伪代码表示，重点看注释里的约束逻辑：

max_turns = 20 state = init_state(task) for turn in range(max_turns): # 1. 构造当前上下文，包含历史动作和观察结果 context = build_context(state, history) # 2. 让模型决策下一步 action = llm_decide(context, tools_schema) # 3. 检查是否终止 if action.type == "finish": return summarize(state, action) # 4. 执行动作，带超时和异常捕获 try: observation = execute_tool(action, timeout=30) except ToolError as e: observation = f"工具执行失败: {e}" # 5. 写回状态，检测是否有实质推进 new_state = update_state(state, action, observation) if not has_progress(state, new_state): state.stall_count += 1 if state.stall_count >= 3: return abort("连续三轮无进展，终止任务") state = new_state return abort("达到最大轮次，任务未完成")

这段代码里，has_progress是最容易被忽略但最值钱的部分。我的做法是给状态里的关键字段做快照对比，比如“已收集的信息条目数”“已修改的文件列表”“已确认的子任务完成数”。如果这些字段连续几轮都没变，那基本可以判定模型在原地打转，这时候主动终止比继续烧 token 更划算。

2.3 Loop 设计里的两个反直觉经验

第一个经验是：不要追求“一轮做更多事”。很多教程鼓励让模型在一轮里规划多个步骤，减少循环次数。但实测下来，单轮动作越多，错误传播越快。一个动作失败，后面依赖它的动作全废，而且模型很难从这种复合失败里恢复。我现在的做法是“单轮单动作”，宁可多循环几轮，也要保证每轮的状态变更清晰可追溯。

第二个经验是：终止条件要让模型参与，但不能完全交给模型。模型说“我完成了”的时候，Harness 必须做一次独立校验。比如任务要求“生成一份包含三个章节的报告”，那校验逻辑就是检查输出里有没有三个章节标题，而不是听模型自己说完成了。这个校验层放在 Loop 的终止分支里，能挡掉大量“自信但错误”的完成声明。

3. 子系统二：LLM Integration，模型接入不是换个 API Key 那么简单

3.1 模型接入层要解决的三个问题

LLM Integration 这个子系统，表面上看就是“把请求发给模型，把回复拿回来”。但真正做 Agent 的时候，这一层要处理的问题远不止这些。我把它归纳为三个：格式适配、能力路由、失败降级。

格式适配是指不同模型对工具调用的支持方式不一样。有的模型原生支持 function calling，返回结构化的工具调用请求；有的模型只能靠 prompt 约束输出 JSON，然后你自己解析。Harness 的接入层要屏蔽这些差异，对上层的 Loop 暴露统一的llm_decide接口。这样你换模型的时候，Loop 逻辑不用动。

能力路由是指根据任务类型选择不同的模型。简单分类任务用小模型，复杂推理用大模型，代码生成用专门调优过的模型。我见过一些项目把所有请求都发给同一个大模型，成本高不说，延迟也大。接入层应该支持按任务标签路由，比如task_type="code"走代码模型，task_type="summary"走轻量模型。

失败降级是指模型调用失败时的处理策略。超时、限流、返回格式错误，这些都要有对应的重试或降级逻辑。我的做法是：格式错误重试一次，附带更严格的格式约束；超时或限流则切换到备用模型，同时记录事件供后续分析。

3.2 工具描述的质量决定模型决策的质量

接入层里还有一个容易被低估的环节：工具描述（tool schema）的编写。模型能不能正确选择工具、正确填参数，很大程度上取决于你给它的工具描述。我见过太多项目把工具描述写成一句话，比如“查询天气”，然后抱怨模型总是传错参数。

好的工具描述要包含四要素：功能说明、参数含义、参数格式、使用场景。举个例子：

{ "name": "search_flights", "description": "查询指定日期和城市之间的航班信息。适用于用户询问航班、机票、出行方案时。不适用于查询火车或酒店。", "parameters": { "from_city": {"type": "string", "description": "出发城市中文名，如'北京'"}, "to_city": {"type": "string", "description": "到达城市中文名，如'上海'"}, "date": {"type": "string", "description": "出发日期，格式 YYYY-MM-DD"} } }

注意 description 里明确写了“不适用于查询火车或酒店”，这种负向约束能显著减少误调用。参数描述里给了示例格式，模型填参的准确率也会提升。这些细节看起来琐碎，但它们是接入层真正产生价值的地方。

3.3 上下文窗口管理：别等到爆了才想起来

Agent 跑多轮之后，上下文会越来越长。历史动作、工具返回、中间结果全堆在一起，很快就会撞上模型的上下文窗口上限。接入层必须有一套上下文管理策略，不能简单地把所有历史都塞进去。

我常用的策略是“滑动窗口加摘要”。最近 N 轮保留完整内容，更早的历史压缩成摘要。摘要由模型生成，只保留关键决策和结果，丢弃中间过程。这样既能控制长度，又不会丢失重要信息。另一个技巧是把工具返回的大块数据存到外部存储，上下文里只放引用 ID 和简短描述，需要时再按 ID 取回。这个做法在文件处理、日志分析类任务里特别有效。

4. 子系统三：Memory，Agent 的记性靠什么撑住

4.1 短期记忆和长期记忆要分开设计

Memory 子系统经常被简化成“把对话历史存起来”。但 Agent 的记忆需求比聊天机器人复杂得多。我把它分成短期记忆和长期记忆两层。短期记忆是当前任务内的状态，包括已完成的子任务、已收集的信息、当前的决策上下文。长期记忆是跨任务的知识，比如用户偏好、历史成功方案、常见错误模式。

短期记忆我一般放在内存里，用结构化的状态对象维护，随任务结束而销毁。长期记忆则要持久化，可以用向量库做语义检索，也可以用关系型数据库做精确查询。关键是要有明确的写入和读取规则，不能什么都往长期记忆里塞。我的规则是：只有被验证过的、可复用的信息才写入长期记忆，比如“用户偏好用表格形式输出”“某类 API 的认证方式”。

4.2 记忆检索的时机比存储更重要

存得多不如取得准。Agent 在每一轮决策前，应该检索一次相关记忆，但检索范围要控制。我的做法是：短期记忆全量注入，长期记忆按当前任务描述做语义检索，只取 top 3 到 top 5 条。注入的时候要标注来源，让模型知道哪些是当前任务状态，哪些是历史经验。

这里有个坑：长期记忆检索出来的内容如果和当前任务冲突，模型可能会被误导。比如历史经验说“用方案 A”，但当前任务明确要求“用方案 B”。所以检索结果注入时，要加上优先级说明，当前任务指令的优先级高于历史经验。这个细节在 prompt 里加一句话就能解决，但不加就会出问题。

4.3 记忆的清理和过期策略

长期记忆如果不清理，会越来越臃肿，检索质量也会下降。我一般给每条记忆加两个字段：最后使用时间、使用次数。超过 90 天没被检索到的记忆，标记为冷数据，不再参与检索但保留存档。使用次数高的记忆提升权重，检索时优先返回。

另外，任务结束后要做一次记忆复盘。把这次任务里产生的可复用信息提取出来，写入长期记忆；把临时状态清理掉。这个复盘步骤可以做成自动化的，也可以让模型生成一份复盘摘要，人工确认后再写入。我倾向于后者，因为自动写入容易把噪声也存进去。

5. 子系统四：Tool Execution，工具调用的安全边界

5.1 工具注册和权限控制

Tool Execution 子系统管的是“Agent 能做什么”。工具注册要集中管理，每个工具要有明确的名称、描述、参数 schema、执行函数、权限标签。权限标签是关键，比如read_only、write、network、system。Agent 在调用工具前，Harness 要检查当前任务是否允许这类权限。

我见过一些项目为了图方便，把所有工具都开放给 Agent，结果模型在调试阶段误删了文件、误发了请求。权限控制不是限制 Agent 的能力，而是给它划一个安全的活动范围。我的做法是：默认只开放只读工具，写操作和网络操作需要显式授权，系统级操作一律禁止，除非是专门的运维类 Agent。

5.2 参数校验和沙箱执行

模型生成的工具参数不能直接信任。Harness 在执行前要做参数校验：类型对不对、必填项有没有、取值范围是否合法。比如日期格式、文件路径、URL 域名，这些都要校验。校验失败不要直接报错给模型，而是返回一个友好的提示，让模型有机会修正。

沙箱执行是另一层保护。对于代码执行、文件操作这类高风险工具，要在隔离环境里跑。我一般用容器或者受限的进程空间，限制文件系统访问范围、网络访问、执行时间。这样即使模型生成了危险操作，也不会影响宿主环境。这个投入在开发阶段看起来麻烦，但一旦 Agent 上线，它能帮你挡掉很多意外。

5.3 工具返回的标准化处理

工具返回的结果格式五花八门，有的是 JSON，有的是纯文本，有的是二进制。Harness 要把它们标准化成模型能理解的格式。我的做法是统一包装成{status, data, error, meta}结构。status 表示成功或失败，data 是结果内容，error 是错误信息，meta 放执行时间、数据量等辅助信息。

标准化之后，模型看到的工具返回是一致的，它更容易学会如何处理。另外，大块数据要做截断或摘要，不能直接把几 MB 的日志塞进上下文。截断时保留头部和尾部，中间用省略标记，这样模型既能看到开头和结尾的关键信息，又不会撑爆上下文。

6. 子系统五：Orchestration，多 Agent 协作的调度逻辑

6.1 单 Agent 什么时候该升级成多 Agent

不是所有任务都需要多 Agent。我的判断标准是：如果任务可以拆成几个相对独立、且各自需要不同工具集或不同模型能力的子任务，那就值得上多 Agent。比如一个“市场调研”任务，可以拆成“数据收集 Agent”“数据分析 Agent”“报告撰写 Agent”，各自用不同的工具和模型。

但如果任务本身是线性的、工具集也统一，那单 Agent 加 Loop 就够了。强行拆多 Agent 只会增加通信开销和协调复杂度。我见过一些项目为了“看起来高级”，把简单任务拆成五个 Agent，结果调试起来痛苦不堪，效果还不如单 Agent。

6.2 调度模式：中心化和去中心化怎么选

多 Agent 的调度有两种主流模式：中心化调度和去中心化协作。中心化调度有一个 Orchestrator Agent 负责分配任务、收集结果、决定下一步。去中心化则是 Agent 之间直接通信，各自决定何时把控制权交给谁。

我的经验是：任务流程明确、需要严格控制的场景用中心化；任务探索性强、需要灵活协作的场景用去中心化。中心化的优点是可控、可观测、容易调试；缺点是 Orchestrator 容易成为瓶颈。去中心化的优点是灵活；缺点是容易出现“踢皮球”或者死循环。

实际项目里我更多用中心化，因为 Agent 任务大多需要明确的阶段划分和结果汇总。Orchestrator 不一定要用大模型，简单的规则引擎也能胜任，这样更稳定、更省成本。

6.3 Agent 之间的通信协议

多 Agent 通信要有统一的消息格式。我一般定义{from, to, type, payload, timestamp}结构。type 区分任务分配、结果返回、状态查询、错误上报。payload 里放具体内容。所有消息要落盘，方便回溯。

通信的另一个关键是超时和重试。一个 Agent 发给另一个 Agent 的任务，如果超时没响应，要有重试或转交机制。不能让整个流程卡在一个 Agent 上。我的做法是给每个跨 Agent 调用设超时，超时后由 Orchestrator 决定是重试、跳过还是终止整个任务。

7. 子系统六：Observability，Agent 跑起来之后你怎么知道它在干嘛

7.1 日志、指标、追踪三件套

Observability 是 Harness 里最容易被省略、但上线后最离不开的子系统。Agent 的行为是概率性的，同样的输入可能走出不同的路径。没有观测能力，你根本不知道它为什么成功、为什么失败。

我一般做三层观测：日志记录每一轮的输入输出和决策；指标统计轮次、token 消耗、工具调用次数、成功率；追踪把一次任务的完整调用链串起来，包括跨 Agent 的调用。这三层里，追踪最有价值，因为它能让你看到“模型在第三步选错了工具，导致第五步失败”这种因果链。

7.2 关键指标的定义和告警

指标不能随便定，要围绕稳定性来选。我关注的核心指标有：任务完成率、平均轮次、单任务 token 消耗、工具调用失败率、无进展轮次占比。这些指标能反映 Harness 的健康度。

告警阈值要根据历史数据来定。比如工具调用失败率突然从 2% 涨到 15%，那可能是某个外部服务挂了，或者模型换了版本导致参数格式变了。无进展轮次占比升高，说明 Loop 的终止策略可能需要调整。这些告警能让你在用户投诉之前发现问题。

7.3 回放和调试

Agent 出问题的时候，光看日志不够，要能回放。我的做法是把每一轮的完整上下文、模型输入输出、工具调用参数和结果都存下来，支持按任务 ID 回放。回放的时候可以逐步执行，也可以跳到某一轮查看状态。

这个能力在调试 prompt 和工具描述时特别有用。你可以看到模型在某个上下文下为什么选了错误的工具，然后针对性地修改工具描述或加约束。没有回放，调优基本靠猜。

8. 子系统七：Guardrails，让 Agent 不越界的那道墙

8.1 输入输出过滤

Guardrails 是最后一道防线，管的是“Agent 不能做什么”。输入侧要过滤恶意指令、越权请求、敏感内容。输出侧要检查结果是否符合格式要求、是否包含不该出现的内容、是否触发了禁止操作。

我一般用规则加模型双重过滤。规则处理明确的禁止项，比如特定关键词、特定操作类型。模型处理模糊的边界情况，比如判断某个请求是否属于越权。两层过滤都通过，才允许继续。

8.2 操作审计和人工确认

高风险操作要有人工确认环节。比如删除文件、发送邮件、修改数据库，这些操作在执行前应该暂停，等待人工批准。Harness 要支持这种“中断-确认-继续”的流程。

审计日志要记录所有操作，包括谁批准的、什么时候批准的、操作内容是什么。这在团队协作场景里尤其重要，能追溯责任，也能积累经验。

8.3 熔断和降级

当 Agent 出现异常行为时，要有熔断机制。比如连续多次工具调用失败、token 消耗异常飙升、循环轮次超过阈值，Harness 应该自动暂停任务，通知人工介入。降级策略则是在模型服务不可用时，切换到备用模型或返回缓存结果，保证基本可用性。

这些机制在开发阶段可能用不上，但一旦 Agent 面向真实用户，它们就是保命的。我宁愿在开发时多花两天做 Guardrails，也不愿意上线后半夜被叫起来处理 Agent 失控。

9. 把这 7 个子系统串起来：一个最小 Harness 的落地顺序

9.1 从哪开始搭

如果你现在要从零搭一个 Harness，我的建议顺序是：先做 Agent Loop 和 LLM Integration，让 Agent 能跑起来；然后加 Tool Execution 和 Memory，让它能干活、能记住；接着加 Observability，让你能看见它在干嘛；最后加 Orchestration 和 Guardrails，处理复杂场景和安全边界。

这个顺序的逻辑是：先保证“能跑”，再保证“能干活”，然后保证“能看见”，最后保证“不闯祸”。反过来先做 Guardrails 也不是不行，但你会花很多时间在还没有稳定行为的东西上设限制，效率不高。

9.2 每个阶段的最小可用标准

Loop 阶段：能完成一个单工具调用的任务，比如“查询天气并返回结果”。LLM Integration 阶段：能切换两个不同模型，工具调用格式统一。Tool Execution 阶段：能注册至少三个工具，参数校验和错误处理到位。Memory 阶段：短期记忆能支撑 10 轮以上的任务，长期记忆能跨任务检索。Observability 阶段：能按任务 ID 回放完整调用链。Orchestration 阶段：能跑通一个双 Agent 协作任务。Guardrails 阶段：高风险操作有人工确认，异常行为能熔断。

每个阶段不用做到完美，但要有可验证的标准。这样你才知道自己走到哪了，下一步该补什么。

9.3 常见误区：别把框架当 Harness

最后说一个我踩过的坑。很多人把 LangChain、Spring AI 这类框架当成 Harness，觉得用了框架就万事大吉。框架确实提供了很多组件，但 Harness 的核心是“针对你的任务场景做约束和调度”。框架给你的是积木，怎么搭、搭成什么样，还是取决于你对任务的理解。

我见过用同一套框架搭出来的 Agent，有的很稳，有的很飘。差别不在框架，在于 Harness 的设计：Loop 的终止条件、工具描述的质量、记忆的检索策略、观测的粒度。这些才是决定 Agent 能不能真正干活的关键。框架帮你省了底层代码，但省不了思考。

所以回到标题的问题：AI Agent 真正干活的 Harness 到底是啥？我的答案是，它是一套围绕任务场景设计的约束和调度系统，由这 7 个子系统组成。每个子系统都不复杂，但组合起来，决定了 Agent 是“玩具”还是“工具”。你不需要一次把 7 个都做到位，但你需要知道缺了哪个，以及缺了之后会在哪里出问题。这个认知，比任何框架文档都值钱。