企业官网建设流程全解析

1. 从两个被混用的词说起

这两年做 AI Agent 的人越来越多，但有个现象挺有意思：大家在群里聊技术，十句话里能蹦出七八个"Engineering"——Prompt Engineering、Context Engineering、Harness Engineering、Loop Engineering。前两个还算有人能说清楚，后两个基本就是各说各的，有人拿它当架构名词，有人拿它当岗位 title，还有人干脆把它当成某个开源项目的模块名。

我最早接触 Harness Engineering 这个词，是在翻一些 Agent 框架源码的时候。当时看到harness这个目录名，第一反应是"这不是测试夹具吗"，结果点进去一看，里面装的是工具注册、权限校验、执行沙箱、结果回传这一整套东西。后来跟几个做 Agent 落地的朋友聊，才发现这个词在工程圈已经悄悄变成了一个约定俗成的说法，专门指围绕模型能力搭建的那层"驾驭装置"。而 Loop Engineering 更微妙，它描述的是 Agent 运行时那个"想—做—看—再想"的循环该怎么设计、怎么收敛、怎么防止跑飞。

这两个概念之所以容易被混淆，是因为它们都处在"模型之外、应用之内"这个夹层里。Prompt Engineering 管的是怎么把话说清楚，Context Engineering 管的是往窗口里塞什么，而 Harness 和 Loop 管的是模型被调用之后，整个系统怎么转起来、怎么转得住。打个比方：如果模型是一台发动机，Prompt 是点火钥匙，Context 是油箱，那 Harness 就是变速箱和底盘，Loop 就是油门与刹车的配合节奏。发动机再猛，底盘散了、油门刹车打架，车照样开不出去。

这篇文章我想把这两个概念彻底拆开讲清楚。不是掉书袋式的定义罗列，而是从"你真正要写代码时该往哪放什么"这个角度切入。适合已经动手搭过 Agent、但总觉得架构别扭的人看，也适合正准备从零做一个 Agent 项目、想少走弯路的人参考。我会尽量把每个设计选择背后的"为什么"讲透，因为这两个词的价值恰恰在于——它们回答的不是"怎么做"，而是"为什么非得这么分"。

2. Harness Engineering：给模型套上可用的缰绳

2.1 它到底解决什么问题

先说结论：Harness Engineering 处理的是模型能力与真实世界之间的接口问题。模型本身只会输出 token，它不知道什么是文件、什么是数据库、什么是"这个操作不能做"。你要让它干活，就必须在它和真实世界之间架一层东西，这层东西就是 Harness。

我见过太多项目在这块栽跟头。最常见的场景是：开发者兴冲冲接了个模型，写了个 while 循环让它调工具，跑起来发现模型开始疯狂删文件、无限调用同一个 API、把敏感信息打印到日志里。这时候才意识到，模型不是不聪明，是没有边界感。Harness 的核心职责就是给它建立边界感。

具体来说，Harness 要解决四类问题：

• 能力暴露：模型能调用哪些工具，每个工具的参数 schema 长什么样，怎么让模型准确理解工具的用途
• 执行隔离：工具在什么环境里跑，能不能访问网络，能不能写文件，超时了怎么办
• 权限控制：哪些操作需要人工确认，哪些可以自动执行，危险操作怎么拦截
• 结果规整：工具返回的原始数据怎么裁剪、怎么格式化，才能塞回上下文而不撑爆窗口

这四件事听起来简单，但每一件都有大量细节。比如"能力暴露"这一项，工具描述写得好不好，直接决定模型会不会用错工具。我做过一个对比测试，同一个文件读取工具，描述写成"读取文件"和写成"读取指定路径的文本文件内容，返回前 N 行，路径必须是绝对路径"，模型调用成功率差了将近 40%。这就是 Harness 层面的工程价值——它不改变模型，但改变模型的表现。

2.2 一个 Harness 的最小骨架

如果你现在要动手写一个 Harness，我建议按下面这个结构组织。这不是唯一解，但经过多个项目验证，扩展性和可维护性都比较平衡。

class ToolHarness: def __init__(self, registry, sandbox, policy): self.registry = registry # 工具注册表 self.sandbox = sandbox # 执行沙箱 self.policy = policy # 权限策略 def expose(self): # 生成给模型看的工具描述列表 return [t.to_schema() for t in self.registry.enabled_tools()] def invoke(self, name, args, context): tool = self.registry.get(name) if not self.policy.allow(tool, args, context): return {"error": "permission_denied", "hint": "需要人工确认"} try: raw = self.sandbox.run(tool, args, timeout=tool.timeout) except TimeoutError: return {"error": "timeout", "retryable": True} return self.registry.postprocess(tool, raw)

这段代码里，expose和invoke是两个关键入口。expose负责把工具"翻译"成模型能理解的形式，invoke负责把模型的意图"翻译"成真实操作。中间夹着的policy和sandbox就是边界。

我特别想强调postprocess这一步。很多项目忽略了它，直接把工具原始返回丢回上下文，结果一个ls命令返回几千行，直接把窗口占满。好的 Harness 会在这一步做裁剪、摘要、截断，甚至根据当前任务动态决定返回多少。这个设计意图是：模型看到的信息量应该由任务决定，而不是由工具决定。

2.3 工具描述：最容易被低估的工程点

工具描述（tool schema）是 Harness 里最不起眼、但影响最大的部分。我把它单独拎出来讲，因为踩过的坑实在太多。

一个合格的工具描述应该包含四要素：用途、参数、约束、示例。用途说明这个工具干什么，参数说明每个字段的类型和含义，约束说明什么情况下不该用，示例给一两个典型调用。缺了约束和示例，模型就容易在边界情况下乱调。

举个真实例子。我做过一个数据库查询工具，最初描述只写了"执行 SQL 查询，参数是 sql 字符串"。结果模型经常生成DROP TABLE或者不带LIMIT的全表扫描。后来改成：

执行只读 SQL 查询。参数 sql 必须是 SELECT 语句，禁止包含 INSERT/UPDATE/DELETE/DROP。查询结果最多返回 100 行，超出会被截断。示例：SELECT id, name FROM users WHERE age > 18 LIMIT 10。

改完之后，危险查询基本消失了。这不是模型变聪明了，是 Harness 把约束显式化了。模型在生成时能看到这些约束，自然就会规避。

这里有个经验：约束要写在描述里，不要只写在代码里。你在invoke里做校验当然也对，但那是事后拦截，模型已经浪费了一次调用。写在描述里是事前预防，效率高得多。两者结合最好——描述里写清楚，代码里再兜底。

2.4 沙箱与权限：别等出事才补

沙箱和权限控制是 Harness 里最"重"的部分，也是最容易被跳过的地方。小项目跑 demo 时觉得没必要，一旦上真实环境就出问题。

我的建议是，从第一天就把沙箱做起来，哪怕是最简陋的版本。最简单的做法是用子进程加资源限制，复杂一点可以用容器。关键是要有超时、内存上限、文件系统隔离这三样。超时防止死循环，内存上限防止 OOM，文件系统隔离防止误删。

权限控制我习惯分三档：

这个分档不是拍脑袋定的，而是根据操作的可逆性来的。只读操作可逆（大不了重查），写操作部分可逆（有备份能恢复），删除和对外发布基本不可逆。可逆性越低，管控越严。

有个细节值得注意：确认操作要给出足够的信息让人判断。不能只弹一句"是否允许执行 write_file"，而要显示"即将写入 /path/to/file，内容前 200 字符如下……"。人工确认的价值在于人能做出正确判断，信息不足的确认等于没确认。

3. Loop Engineering：让 Agent 转得起来又停得下来

3.1 循环的本质是一个状态机

如果说 Harness 是静态的"装置"，那 Loop 就是动态的"节奏"。Loop Engineering 处理的是 Agent 运行时那个反复迭代的过程：模型思考、调用工具、观察结果、再思考，直到任务完成或触发终止条件。

很多人把 Loop 简单理解成while not done: think(); act(); observe()，这没错，但太粗糙了。真实的 Loop 是一个状态机，至少包含这几个状态：规划、执行、观察、反思、终止。每个状态之间的转移条件，才是 Loop Engineering 的核心。

我画不出图（这里也不适合放图），但可以用文字描述一个典型的转移逻辑：

• 从规划进入执行：当模型产出了明确的工具调用意图
• 从执行进入观察：工具返回了结果
• 从观察进入反思：结果与预期不符，或结果信息量过大需要消化
• 从反思回到规划：需要调整策略
• 从任意状态进入终止：任务完成、达到步数上限、或触发错误阈值

这个状态机的设计质量，直接决定 Agent 是"聪明地干活"还是"原地打转"。我见过最典型的失败模式是：模型反复调用同一个工具，每次拿到相似结果，然后继续调用。这不是模型笨，是 Loop 没有设计"重复检测"和"强制反思"机制。

3.2 终止条件：比你想的复杂

终止条件是 Loop Engineering 里最需要精心设计的部分。新手通常只设一个"任务完成"，结果 Agent 要么永远不认为完成，要么过早认为完成。

我的经验是至少设四类终止条件，按优先级排列：

1. 显式完成：模型明确输出"任务已完成"或类似信号
2. 步数上限：硬性限制最大迭代次数，防止无限循环
3. 无进展检测：连续 N 步没有产生新的有效信息
4. 错误阈值：连续 M 次工具调用失败

这四类里，第二和第三类最实用。步数上限是保底，无进展检测是提质。无进展检测怎么实现？我的做法是给每一步的结果算一个"信息增量"，如果连续几步增量都低于阈值，就强制终止或强制切换策略。

信息增量怎么算？简单点可以用结果哈希去重，复杂点可以用嵌入向量算相似度。我用过的一个土办法是：把每步的工具调用名加参数拼成字符串，如果最近三步的字符串高度相似，就判定为原地打转。这个方法粗糙但有效，实现成本极低。

提示：终止条件一定要有"兜底"的那一层。我见过太多项目因为没设步数上限，一个 bug 导致 Agent 跑了一晚上，烧掉大量调用额度。硬上限是必须的，哪怕设得很宽松。

3.3 上下文管理：Loop 里的隐形战场

Loop 每转一圈，上下文就长一截。转个十几圈，窗口就满了。所以 Loop Engineering 里有一大半精力其实花在上下文管理上，这也是它和 Context Engineering 的交汇点。

常见的上下文管理策略有三种：

• 滑动窗口：只保留最近 N 轮，简单但会丢历史
• 摘要压缩：把旧轮次压缩成摘要，保留信息但损失细节
• 分层记忆：近期完整保留，中期摘要，远期只留关键结论

我实际项目里用得最多的是第三种。具体做法是：最近 3 轮完整保留，第 4 到第 10 轮压缩成一段摘要，10 轮以前只保留"已确认的事实"和"未解决的问题"两个列表。这样既控制了长度，又保住了关键信息。

这里有个反直觉的经验：不是所有历史都值得保留。很多中间步骤的细节对最终任务毫无价值，保留它们反而干扰模型判断。我做过对比，同样一个多步任务，保留全部历史和只保留关键结论，后者的完成质量反而更高。原因是模型在长上下文里容易"分心"，被无关细节带偏。

所以 Loop Engineering 的一个核心原则是：主动遗忘比被动截断更重要。你要在循环里主动判断哪些信息该丢，而不是等窗口满了再被动裁剪。

3.4 重试与退避：别让 Agent 撞墙

工具调用失败是常态，网络抖动、服务限流、参数错误都会导致失败。Loop 里必须有重试机制，但重试不能是无脑重试。

我的做法是区分错误类型：

关键区别在于：瞬时错误由系统重试，逻辑错误由模型处理。系统重试是机械的，模型处理是智能的。把该模型处理的错误交给系统重试，只会浪费调用；把该系统重试的错误交给模型，只会让模型困惑。

指数退避的参数我一般设成：首次等待 1 秒，每次翻倍，上限 30 秒。这个参数不是随便定的，1 秒起步是因为大部分瞬时故障在 1 秒内恢复，30 秒上限是因为再长就不如直接失败了。当然具体数值要看你的下游服务特性，做压测调优更靠谱。

4. 两者如何配合：一个完整的运行时视角

4.1 分层关系：Harness 是静态的，Loop 是动态的

把 Harness 和 Loop 放在一起看，它们的关系其实很清晰：Harness 定义了"能做什么"，Loop 定义了"怎么去做"。

Harness 是静态的，它在 Agent 启动前就配置好了——有哪些工具、什么权限、什么沙箱。Loop 是动态的，它在运行时不断变化——这一步调什么、下一步怎么调整、什么时候停。

用一个类比：Harness 像是给工人准备的工具箱和工作台，Loop 像是工人的工作流程。工具箱决定了工人能用什么工具，工作流程决定了工人怎么用这些工具完成任务。工具箱再好，流程乱了也白搭；流程再顺，工具箱里没家伙也干不了活。

这个分层关系有个重要的实践含义：两者的调试方法完全不同。Harness 的问题通常是配置问题，可以通过单元测试覆盖——工具描述对不对、权限策略对不对、沙箱隔离对不对。Loop 的问题通常是涌现问题，只能通过端到端测试和日志分析来定位——为什么这一步做了这个选择、为什么循环没收敛。

所以我在项目里会把两者的测试分开：Harness 用单元测试，每个工具、每条策略都有测试用例；Loop 用场景测试，构造典型任务看整体表现。混在一起测，出了问题很难定位是配置错了还是流程错了。

4.2 数据流：一次调用的完整旅程

我们跟着一次工具调用走一遍，看看 Harness 和 Loop 各自在哪个环节发力。

假设模型决定调用read_file读取一个配置文件。这个意图首先进入 Loop 的执行状态。Loop 会做几件事：检查当前步数是否超限、检查这个调用是否和上一步重复、把调用意图记录到轨迹里。然后它把调用交给 Harness。

Harness 接到调用后，先查工具注册表确认工具存在，再查权限策略确认允许执行，然后把调用丢进沙箱。沙箱执行完返回原始内容，Harness 做后处理——裁剪、格式化、脱敏。最后把处理好的结果返回给 Loop。

Loop 拿到结果后进入观察状态，判断这个结果是否有效、是否需要反思。如果有效，进入下一轮规划；如果无效，可能触发重试或调整策略。

这个流程里，Loop 管的是"要不要做、做完怎么办"，Harness 管的是"能不能做、怎么做安全"。职责边界很清楚。我见过一些项目把两者混在一起，权限校验写在 Loop 里，重试逻辑写在 Harness 里，结果代码一团乱，改一处崩三处。分开之后，各自演化互不干扰。

4.3 一个容易踩的坑：把 Loop 逻辑写进 Harness

这是我最想提醒的一点。很多开发者会把"重试""循环调用"这类逻辑写进 Harness 的工具封装里，觉得这样调用方就省事了。短期看确实方便，长期看是灾难。

原因很简单：Harness 不知道全局状态。它不知道这是第几次调用、不知道之前失败过几次、不知道任务的整体目标。它只能看到单次调用的参数。把重试逻辑放这里，它只能做机械重试，无法做智能决策。

正确的做法是：Harness 只负责单次调用的执行和结果处理，所有涉及"多次""状态""策略"的逻辑都放 Loop。这样 Harness 保持无状态、可测试，Loop 承担有状态的决策职责。这个边界一旦划清，整个系统的可维护性会提升一个档次。

5. 实操中的常见问题与排查

5.1 工具调用成功率低怎么办

这是最高频的问题。排查顺序我一般是这样：

先看工具描述。把描述打印出来，假装自己是模型，看能不能准确理解这个工具干什么、参数怎么填。如果描述含糊，先改描述。这一步能解决大部分问题。

再看参数 schema。类型对不对、必填项标了没、枚举值列全了没。schema 不严谨，模型就容易生成非法参数。

最后看上下文。模型在决定调用工具时，上下文里有没有足够的信息支撑这个决策。如果上下文里没有相关线索，模型只能瞎猜。

这三步走下来，八成的问题能定位。剩下两成通常是模型能力问题，换个更强的模型或者拆细任务往往能解决。

5.2 Agent 陷入死循环怎么破

死循环的表现是：反复调用相似工具、反复得到相似结果、步数一直涨但任务没进展。

应急处理是加步数上限，先止血。根治要从 Loop 设计入手。我常用的两个手段：

一是重复检测。记录最近几步的调用签名，发现重复就强制插入一个"反思"步骤，让模型明确说明"为什么重复调用、下一步打算怎么变"。

二是进展度量。给每步结果算个分数，连续低分就触发策略切换。策略切换可以是换工具、换思路、或者直接求助人工。

这两个手段配合使用效果最好。重复检测抓"形似"，进展度量抓"神似"，两者都触发才强制干预，避免误伤正常的迭代。

5.3 上下文爆炸怎么控制

上下文爆炸的根源是 Loop 每转一圈就加内容，但没人负责减内容。

我的做法是在 Loop 里设一个"上下文预算"，比如总 token 数的 70%。每轮结束后检查用量，超过预算就触发压缩。压缩策略按前面说的分层记忆来：近期保留、中期摘要、远期只留结论。

有个细节：压缩要在轮次边界做，不要在轮次中间做。中间压缩会破坏当前轮的上下文完整性，导致模型判断失误。轮次边界压缩则不影响当前决策。

5.4 权限确认太频繁影响体验

权限确认是安全需要，但太频繁确实烦人。我的优化思路是分级 + 记忆。

分级就是前面说的三档，只读自动、写操作确认、危险禁止。记忆是指：同一个操作在同一会话里确认过一次后，短时间内不再重复确认。比如用户确认了"允许写入 /tmp 目录"，那接下来几分钟内对 /tmp 的写入就不再弹窗。

这个记忆要有超时，不能永久生效。我一般设 5 分钟，够完成一个连续任务，又不至于让权限长期敞开。

5.5 排查速查表

这张表我贴在工位上很久了，出问题先对一遍，能省不少时间。

6. 我个人的一些体会

做 Agent 这两年，最大的感受是：模型能力在快速提升，但工程能力才是决定项目成败的关键。同一个模型，Harness 和 Loop 设计得好，能做出惊艳的效果；设计得差，就是个昂贵的玩具。

Harness Engineering 和 Loop Engineering 这两个词，本质上是在提醒我们：Agent 不是"模型加个循环"这么简单。模型之外的那层工程，才是真正体现功力的地方。工具怎么暴露、权限怎么控制、循环怎么收敛、上下文怎么管理，每一个都是实打实的工程问题，都需要认真设计、反复调试。

如果你正在做 Agent 项目，我的建议是：先把 Harness 做扎实，工具描述写清楚、沙箱权限做到位，这是地基。然后再打磨 Loop，把终止条件、上下文管理、重试策略设计好，这是骨架。地基和骨架稳了，上面盖什么楼都行。

最后分享一个小技巧：给 Agent 的每一步都打日志，而且要结构化。记录步数、状态、工具调用、参数、结果摘要、耗时。这些日志平时看着冗余，出问题时就是救命稻草。我排查过的最诡异的 bug，都是靠翻日志找到的。日志的粒度要细到"能还原当时的决策上下文"，否则等于没记。