企业官网建设流程全解析

1. 为什么我要用纯 Java 去啃 Agent Harness 这块硬骨头

第一次听到“Agent Harness”这个词，很多人脑子里冒出来的第一反应是 Python。原因很简单，过去两年几乎所有关于智能体编排、工具调用、多轮推理的示例代码，默认语言都是 Python，生态里现成的库一抓一大把。我在项目立项的时候也犹豫过：是不是顺着大流走，用 Python 快速搭一个原型出来，先跑通再说？但真正把需求摊开来看之后，我放弃了这条路。

BizBuddy 这个平台的定位不是“跑个 Demo 看看效果”，而是要塞进企业已有的业务系统里，和现有的权限体系、审计日志、消息队列、定时任务、监控告警这些东西长在一起。企业里跑着的核心服务，绝大多数是 Java 写的，运维团队熟悉 JVM 的调优和排障，安全团队对 Java 生态的依赖扫描和漏洞治理有成熟流程。如果我硬塞一个 Python 运行时进去，等于凭空多出一套需要单独维护、单独监控、单独做安全合规的技术栈。这个隐性成本，远比“Python 写起来快”那点收益要大。

所以 BizBuddy 的核心约束从一开始就定死了：纯 Java 实现，不引入任何非 JVM 的运行时依赖。这里的“纯 Java”不是指不能用第三方库，而是指整个 Agent Harness 的调度、推理循环、工具注册、状态管理、并发控制，全部跑在 JVM 上，用 Java 语言和 JVM 生态的组件来完成。这个决定带来的取舍贯穿了整个项目，后面每一节我都会具体讲。

先说说 Agent Harness 到底是个什么东西，免得后面聊得太抽象。你可以把它理解成智能体的“操作系统内核”。一个智能体要干活，需要几件事：接收任务、规划步骤、调用工具、观察结果、决定下一步、直到任务完成或者放弃。Harness 就是把这套循环管起来的那层框架。它不负责“智能”本身——智能来自背后的大模型——它负责的是把模型的输出变成可执行的动作，把动作的结果喂回给模型，并且在中间加上超时、重试、限流、审计、权限校验这些企业级必须有的东西。

BizBuddy 要解决的核心问题，是让业务团队能够用自然语言描述一个任务，平台自动拆解成若干步骤，调用企业内部已有的 API、数据库查询、文件处理等能力，最终把结果交付出来。听起来和市面上很多“智能体平台”差不多，但企业级这三个字意味着完全不同的要求：一次工具调用失败不能把整个任务搞崩，敏感操作必须走审批，每一步都要留痕可追溯，并发上来之后不能把下游系统打挂。这些才是真正花时间的地方。

这篇文章我会把 BizBuddy 从设计到落地的关键取舍讲清楚，包括为什么选 Java、Harness 的循环怎么设计、工具注册怎么做、状态和并发怎么管、企业级的安全和审计怎么嵌进去。如果你也在做类似的事情，或者正在纠结技术选型，希望这些踩过的坑能帮你少走点弯路。

2. 把 Agent 循环拆开看：Harness 到底管哪几件事

2.1 一次任务执行的完整生命周期

在动手写代码之前，我花了大概两周时间，把“一个任务从进入到结束”的全过程画在了白板上。这个动作看起来笨，但极其重要。因为 Agent Harness 最容易出问题的地方，不是某个单点功能没实现，而是状态在多个环节之间传递时丢了或者串了。

一个任务在 BizBuddy 里的生命周期大致是这样的：用户提交任务描述，Harness 创建一个 TaskContext，里面装着任务 ID、用户身份、权限范围、超时预算、已用步数、对话历史、中间产物。然后进入主循环，每一轮做四件事：把当前上下文和可用工具列表发给模型，模型返回一个动作（调用某个工具，或者给出最终答案），Harness 校验这个动作是否合法、是否有权限、是否超出预算，合法就执行，把结果写回上下文，进入下一轮。直到模型给出最终答案，或者触发终止条件（步数耗尽、超时、连续失败）。

这里有个关键设计点：Harness 不信任模型的任何输出。模型说“我要调用删除用户接口”，Harness 不会直接执行，而是先过一遍策略引擎。策略引擎检查这个用户有没有删除权限、这个操作是不是在高危名单里、当前任务是不是已经超过了允许的步数。只有全部通过，才真正执行。这个“不信任”原则是企业级和玩具级的分水岭。

2.2 为什么循环控制不能交给模型自己

很多人做 Agent 的第一版，喜欢让模型自己决定“我还要不要继续”。模型说“我完成了”，循环就结束。这个做法在 Demo 里没问题，在生产里是灾难。原因有三个。

第一，模型会“幻觉完成”。它可能只做了一半就自信地说任务搞定了，尤其是任务步骤比较多的时候。第二，模型没有成本概念。它不知道每次调用工具都要花钱、花时间、占用下游资源，可能会无休止地重试。第三，模型无法感知外部约束。比如下游系统已经限流了，模型还在那儿一个劲地调。

所以 BizBuddy 把循环的终止权牢牢握在 Harness 手里。模型可以“建议”结束，但最终是否结束由 Harness 根据预算、步数、错误率来判断。具体来说，每个任务创建时会带一个maxSteps和deadline，每轮循环开始前检查，超了就强制终止并返回当前已有的中间结果。这个设计让任务执行变得可预测，运维团队能算出最坏情况下一个任务会占用多少资源。

2.3 上下文窗口的取舍：全量塞进去还是做摘要

Agent 循环里最容易被低估的问题是上下文管理。每一轮都要把历史发给模型，历史越长，token 消耗越大，而且模型在超长上下文里的表现会下降。BizBuddy 一开始的做法是“全量保留”，结果跑复杂任务时 token 成本高得吓人，而且模型开始忽略早期的关键指令。

后来改成了分层策略。最近 N 轮对话完整保留，更早的历史做摘要压缩，只保留关键决策和中间产物的引用。中间产物本身不塞进上下文，而是存在外部存储里，上下文里只放一个句柄，模型需要时再通过工具去取。这个改动让单任务的 token 消耗降了大概六成，而且模型的表现反而更稳定了。

这里有个实操心得：摘要压缩不要用另一个模型调用去做，成本高且不稳定。我们用的是规则化的摘要——保留每轮的工具名、关键参数、结果状态码，丢掉冗长的原始返回。对模型来说，知道“查了订单表，返回成功，有 3 条记录”比看到完整的 JSON 更有用。

3. 纯 Java 技术栈的选型：每一层为什么这么定

3.1 运行时与并发模型的选择

既然定了纯 Java，接下来就是具体选型。运行时用标准 JDK，版本跟着企业现有基线走，不追最新。并发模型这块我纠结了一阵，最终选了虚拟线程加结构化并发的思路，但做了降级兼容——如果运行环境不支持，就退回线程池。

为什么是虚拟线程？因为 Agent 任务的本质是大量 IO 等待：等模型返回、等工具执行、等数据库查询。传统线程池在这种场景下要么开太大导致内存爆，要么开太小导致吞吐上不去。虚拟线程让每个任务可以独占一个“轻量线程”，写代码时是同步阻塞的风格，心智负担小，底层却能支撑很高的并发。这对 Harness 这种“每个任务一个执行流”的模型特别合适。

但这里有个坑：虚拟线程不是银弹。如果工具执行里有 synchronized 块或者用了 ThreadLocal 做重活，虚拟线程的优势会被抵消，甚至出现“钉住”问题。所以 BizBuddy 在工具执行层强制要求：不允许在工具实现里用 synchronized，共享状态一律走无锁结构或者显式的锁对象。这条规矩写进了工具开发规范里。

3.2 工具注册与发现机制

工具是 Agent 的手脚。BizBuddy 里一个“工具”就是一个可以被模型调用的能力单元，比如“查询订单”“发送通知”“生成报表”。工具注册机制我设计成了注解加注册中心的模式。

开发者写一个工具类，加上@BizTool注解，声明工具名、描述、参数 schema。平台启动时扫描这些注解，把工具元信息注册到中心的 ToolRegistry 里。模型看到的工具列表，就是从 ToolRegistry 里按当前用户权限过滤出来的。这个过滤很关键——不同角色的用户能用的工具不一样，财务能用的工具和客服能用的工具必须隔离。

工具的描述文本（description）是给模型看的，直接决定模型会不会正确调用。我在这上面踩过坑：一开始描述写得太简略，模型经常选错工具。后来定了个规矩，每个工具的描述必须包含三要素——这个工具做什么、什么场景下用、参数怎么填。写清楚之后，工具选择的准确率明显上来了。

3.3 模型接入层的抽象

模型接入这块，BizBuddy 没有绑定任何一家。抽象出了一个ModelClient接口，核心方法就是“给一段消息历史，返回一个动作”。不同模型厂商的差异——请求格式、流式返回、function calling 的字段名——全部在各自的实现类里消化掉。

这样做的好处是，企业可以根据成本、合规、效果在不同任务上选不同的模型。比如简单的意图识别用小模型，复杂的规划用大模型。Harness 层完全不关心背后是谁，只认ModelClient接口。这个抽象也让测试变得容易，写个假的 ModelClient 返回预设动作，就能把整个循环跑起来做单元测试，不用真的去调模型。

4. 企业级能力怎么嵌进 Harness 的骨架里

4.1 权限校验为什么必须放在工具执行前

企业环境里，权限是红线。BizBuddy 的权限模型分两层：一层是“用户能不能用这个工具”，另一层是“这次调用的参数是否越界”。第一层在工具注册中心过滤时解决，第二层必须在执行前实时校验。

举个例子，一个“查询客户信息”的工具，客服角色可以用，但只能查自己负责的客户。这个“只能查自己的”约束，光靠工具列表过滤是做不到的，必须在执行时拿到当前用户身份和请求参数，做一次数据级的校验。BizBuddy 把这层校验做成了可插拔的ToolGuard接口，每个工具可以挂自己的守卫逻辑。守卫不通过，直接返回拒绝，模型收到拒绝后可以选择换个方式或者放弃。

注意：权限校验一定要在工具真正执行之前完成，不能先执行再检查。有些团队图省事，先调了接口再判断结果该不该给模型看，这是很危险的，因为副作用已经产生了。

4.2 审计日志要记到什么粒度

审计这块，我的原则是“宁可多记，不可漏记”。BizBuddy 对每一次工具调用都记一条审计记录，包含任务 ID、用户、工具名、参数摘要、执行结果状态、耗时、模型给出的调用理由。参数摘要不是完整参数，敏感字段要脱敏，但结构要保留，方便事后追溯。

为什么连“模型给出的调用理由”都要记？因为在排查问题时，经常需要回答“模型当时为什么这么决策”。有了理由字段，复盘时能看出是模型理解错了，还是工具描述有歧义，还是上下文丢了关键信息。这个字段在早期排障阶段帮了大忙。

审计日志的存储用的是追加写的关系表，不做更新和删除。查询走独立的只读副本，避免影响主流程。日志量大的时候按任务 ID 分片，保证单任务的所有记录能快速捞出来。

4.3 限流、熔断与降级在 Harness 层的统一处理

下游系统是有限的，Agent 的调用欲望是无限的。BizBuddy 在 Harness 层统一做了限流和熔断，而不是让每个工具自己实现。每个工具可以配置自己的 QPS 上限和并发上限，Harness 在执行前检查令牌桶，超了就排队或者直接拒绝。

熔断的逻辑是：某个工具连续失败达到阈值，短时间内直接拒绝所有调用，给下游喘息时间。模型收到“该工具暂时不可用”的反馈后，可以选择走备用路径或者告知用户稍后再试。这套机制让整个平台在下游抖动时不会雪崩，这是企业级和 Demo 级的又一个分水岭。

降级策略也做在了 Harness 层。比如某个任务配置了“主模型不可用时切备用模型”，这个切换逻辑不需要工具或业务代码关心，Harness 在调用模型失败时自动走备用。这种横切关注点集中在 Harness 里，业务开发者就不用重复造轮子。

5. 状态管理与并发控制：最容易翻车的地方

5.1 TaskContext 的设计与不可变性

TaskContext 是整个 Harness 里最核心的数据结构，也是最容易出并发问题的地方。我的做法是：TaskContext 本身尽量不可变，每次状态变更产生一个新的快照。这样多个线程读同一个上下文时不会互相干扰，也不需要加锁。

具体实现上，TaskContext 里放的是不可变集合和值对象。每轮循环结束时，基于旧上下文生成新上下文，写回任务的状态存储。这个“写回”是带版本号的乐观锁，版本对不上就重试。这样即使同一个任务被意外并发处理，也能保证状态不会错乱。

这个设计有个代价：内存里会短暂存在多个上下文快照。但实测下来，单个上下文的大小是可控的（因为中间产物存在外部），这点内存开销换来的是并发安全，非常值。

5.2 长任务的断点续跑怎么做

企业里的任务经常是长任务，跑几分钟甚至几十分钟。如果中途服务重启，任务不能就这么丢了。BizBuddy 的做法是每轮循环结束都把上下文持久化，任务状态标记为“进行中”。服务重启后，扫描所有“进行中”的任务，从最后一次持久化的上下文恢复，继续跑。

这里有个细节：恢复时不能盲目重跑上一轮的工具调用，因为那个调用可能已经产生了副作用。所以上下文里会记录“上一轮动作是否已提交”。如果已提交，恢复时直接进入下一轮；如果未提交，才重新执行。这个“提交标记”是断点续跑正确性的关键，少了它就会出现重复下单、重复发通知这类事故。

5.3 并发任务之间的资源隔离

多个任务同时跑的时候，资源隔离很重要。BizBuddy 给每个任务分配了独立的预算——步数预算、时间预算、token 预算。一个任务把预算耗光，不会影响别的任务。工具层面的限流是全局的，但任务层面的预算是独立的。

另外，任务之间共享的只有只读的工具元信息和模型客户端，其他都是隔离的。这样设计的好处是，一个任务出问题（比如陷入死循环），最多耗光自己的预算然后被终止，不会拖垮整个平台。运维团队可以放心地让平台跑大量并发任务，不用担心某个坏任务把系统搞挂。

6. 实测中暴露的问题与我的应对

6.1 模型工具选择准确率不够的排查过程

上线初期遇到的最头疼的问题是：模型经常选错工具。明明该调“查询订单”，它去调了“查询物流”。排查过程分了三步。

第一步，看审计日志里的调用理由。发现模型对两个工具的区别理解模糊，因为它们的描述写得太像了。第二步，把工具描述拿出来对比，果然，“查询订单”写的是“查询订单信息”，“查询物流”写的是“查询物流信息”，对模型来说几乎没区别。第三步，重写描述，明确各自的适用场景和参数差异，比如“查询订单”强调“根据订单号查订单状态和金额”，“查询物流”强调“根据订单号查配送进度和承运方”。

改完之后准确率上来了，但还没到理想状态。后来又加了一招：在系统提示里明确告诉模型“如果不确定用哪个工具，先调用一个通用的查询工具确认”。这个兜底策略进一步降低了误调用。

6.2 上下文膨胀导致成本失控的修复

前面提过上下文全量保留的问题。具体表现是：一个跑了二十多轮的任务，token 消耗是预期的好几倍，而且模型开始“忘事”——早期的关键约束被淹没了。

修复方案是分层上下文加外部存储。实现时有个坑：摘要压缩的规则一开始写得太激进，把一些模型后续需要的细节也压掉了，导致任务质量下降。后来调整了规则，保留“决策类”信息（做了什么选择、为什么），压缩“数据类”信息（具体的返回内容），只留句柄。这个平衡点找了挺久，最后是靠对比不同压缩策略下的任务成功率定下来的。

6.3 工具执行超时引发的连锁反应

有个工具是调外部接口的，平时响应很快，但偶尔会卡住几十秒。一开始 Harness 没有对工具执行设超时，结果一个卡住的任务占着线程不放，并发一上来线程池就满了，整个平台响应变慢。

修复是给每个工具调用加超时，超时后中断执行并返回失败。但这里有个细节：中断不等于副作用没发生。外部接口可能已经收到了请求，只是响应慢。所以超时后的处理要谨慎，对于非幂等的操作，超时后不能简单重试，要标记为“状态未知”，让模型决定是查询确认还是放弃。这个“状态未知”的处理逻辑，是踩了坑之后才补上的。

实操建议：所有对外部系统有副作用的工具，都要考虑超时和重试的语义。幂等操作可以安全重试，非幂等操作必须走“查询确认”路径。这个判断应该在工具元信息里声明，让 Harness 自动处理。

7. 我对这套架构后续演进的一些想法

BizBuddy 跑到现在，核心循环和治理能力已经比较稳了。回头看，纯 Java 这个决定虽然让初期开发慢了一些，但在企业落地阶段省了太多事。运维不用学新东西，安全扫描能覆盖，性能调优有现成经验，这些都是实打实的收益。

如果让我给正在做类似事情的人一句建议，那就是：先把 Harness 的治理能力想清楚，再动手写循环。很多人一上来就急着让 Agent 跑起来，结果跑通之后发现权限、审计、限流、断点续跑这些全得推倒重来。这些能力不是加在旁边的插件，而是长在循环骨架里的，后补的代价很大。

工具描述的质量，怎么强调都不过分。它看起来是文档工作，实际上直接决定 Agent 的智商上限。我现在的做法是，每加一个工具，都要找人实际测几轮，看模型能不能正确选、正确填参数，不达标就改描述，改到达标为止。

至于后续，我在考虑把工具的组合能力再往上提一层，让常用的工具序列能沉淀成“技能”，模型可以直接调技能而不是一步步拼工具。这样能进一步降低 token 消耗和出错概率。不过这是下一步的事了，当前这套骨架已经能撑住企业里的实际使用。