企业官网建设流程全解析

上周我把 AgentScope Harness 正式接进了我们基于 RuoYi-Vue-Plus 改出来的内部管理系统，跑完第一轮真实任务之后，心情很复杂：集成本身并不难，难的是怎么让一个以 Java 生态为主的团队，愿意接受“平台里跑着另一个服务”这件事。这篇不是我的一次性总结，而是把选型理由、封装过程、失败经历一起写出来，给同样想在不更换后端框架的前提下引入智能体能力的同学做个参考。

如果你正在用 RuoYi-Vue-Plus 做业务后台，又希望在里面跑 AgentScope 智能体任务，这篇文章可以直接当成一份踩坑手册用。核心思路就一句：把 AgentScope Harness 部署成独立服务，Java 侧只负责任务编排、状态流转和数据落库，两者通过 HTTP API 异步协作。

1. 选型背景：AgentScope Harness 与 RuoYi-Vue-Plus 为什么能组合

1.1 RuoYi 平台在 AI 集成上的先天优势与短板

RuoYi-Vue-Plus 本身就是给“快速搭管理后台”准备的，用户体系、权限模型、菜单配置、定时任务、代码生成这些能力非常齐全。我们内部系统已经跑了两年，几千个用户、几十个角色的权限关系都在里面。现在要加 AI 智能体能力，第一反应当然是在这个框架上加一个模块，直接调用模型 API，完成信息抽取、内容生成、流程问答这些工作。

但真做起来后你会发现，单独调模型 API 只是智能体应用里最表层的一环。业务场景一旦复杂，就需要管理多轮对话状态、动态挑选工具、控制智能体执行的节奏、把中间结果反馈给用户。这些逻辑如果全部写在 Java 的 Service 层里，代码很快会变成一大团纠结的 if/else。RuoYi 的强项是标准 CRUD 和权限流，不是状态机和高频异步编排，硬塞进去等于给框架上刑。

所以我把视线转向了 AgentScope Harness。AgentScope 生态本身围绕智能体的编排、运行、评估做了大量工作，Harness 相当于一个独立的执行和调度组件，能把智能体从“写死的一段逻辑”变成“可以接收外部业务指令并返回执行结果的运行单元”。它和我们已有的权限中心、代码生成器并不冲突，反而能互补：RuoYi 负责“人怎么进来、数据怎么管”，Harness 负责“任务怎么跑、结果怎么给”。

1.2 AgentScope Harness 具体承担的角色

在最终方案里，AgentScope Harness 承担四个角色：

• 智能体运行时：接收业务系统发来的任务请求，按预设的 Agent 配置运行大模型、调用工具、收集中间结果。
• 工具注册中心：把已有的内部接口稍作包装后注册成智能体可调用的工具，实现任务自动化。
• 评测与回归环境：每次修改 Agent 提示词或工具流程后，自动跑一遍基准用例，避免“修复一个问题又引出三个新问题”。
• 异步任务服务：通过任务 ID 对外暴露状态查询接口，让 RuoYi 侧可以随时拉起执行记录。

听起来功能挺多，但在实际集成的第一周里，Harness 并没有被当作一个需要深度集成的 SDK，而是被当作一个独立的“黑盒服务”来对待。这样做的好处是，双方之间只交换最小契约，技术栈差异不会互相污染。

1.3 集成方式选型：为什么走 HTTP API 而不是直接扣 Python 进程

我们组内当时有几个候选方案。第一种是直接用 Java 重新实现一套 Agent 编排引擎，保证“纯 Java 全家桶”；第二种是在 Java 进程里通过进程调用方式启动 AgentScope Python 脚本；第三种是部署独立的 AgentScope Harness 服务，Java 侧通过 HTTP 接口接入。

第一种方案听起来很完美，但等于把智能体框架重新发明一遍，评估下来至少要多花一个月工时。第二种方案看着简单，但进程间的生命周期管理非常脆弱：服务重启后脚本进程变孤儿、Python 依赖更新导致启动失败、任务数量一多系统资源立刻失控，这些坑我都见过。

最终选择了 HTTP API 隔离方案。AgentScope Harness 独立运行在 Docker 容器里，对外暴露少量 REST 接口；RuoYi-Vue-Plus 侧只负责管理调用记录、状态更新、结果展示。两边通过 JSON 通信，Java 端不需要关心 Python 包怎么装、依赖版本对不对，运维上也可以各自扩容。

2. 集成前的基础设施准备：服务部署与接口约定

2.1 AgentScope Harness 以独立服务方式部署

我建议把 AgentScope Harness 放在和 RuoYi 应用同一套内网环境里，但不要直接部署在同一个 Tomcat 或同一台宿主机上。原因有两个：一是 Python 侧的依赖隔离需要独立环境，二是智能体任务往往比普通 HTTP 请求更耗时，混布会出现资源争抢。

我们的部署结构是这样的：一台 8 核 16G 的 Linux 机器，用 Docker Compose 启动 AgentScope Harness。容器内开了两个端口：一个用于 API 访问（对外映射为 18081），一个用于内部运行监控（不对外映射）。日志挂载到宿主机的固定目录，方便和 RuoYi 的应用日志放到一起采集。

启动命令不用写得太复杂，因为核心配置都在一个 config.yaml 里：

server: port: 8081 task: queue_size: 100 max_concurrency: 8 default_timeout: 120 callback: enabled: true retry_times: 3

这里的关键参数是max_concurrency。它决定了 Harness 同时跑多少个 Agent 任务。我们内部系统平时的并发请求量不算大，所以设定为 8，避免一次性占用过多内存。如果你的场景是客服问答一类的在线请求，需要把并发调高，并且给 Java 侧也做好限流。

2.2 RuoYi-Vue-Plus 侧需要新增的模块与配置

RuoYi-Vue-Plus 的模块划分很清楚，ruoyi-admin、ruoyi-system、ruoyi-framework各司其职。我新建了一个agent-task模块，专门放智能体任务相关的 Controller、Service、Mapper 和 DTO。

新增的配置集中在application.yml里：

agent-scope: harness: base-url: http://192.168.1.20:18081 query-timeout: 5000 callback-secret: ruoyi-agent-2024 max-retry: 3

base-url是 Harness 的地址，query-timeout用来控制查询任务状态时的超时时间，callback-secret是我们和 Harness 之间约定的回调签名密钥。这个签名不能只放在 yml 里，后续我会在配置中心集中管理，避免机器换掉后一堆系统连不上。

2.3 API 契约设计与数据格式约定

集成之前，最该做的一件事是把接口契约定清楚，用一张表把请求、回调、查询三类接口固定住。我们最终确定的接口如下：

请求体的设计遵循一个原则：业务字段不要塞太满。Harness 只需要知道“用什么 Agent、传入什么参数、希望以什么方式返回”，其他数据都应该放到商定的biz_params里原样透传：

{ "agentId": "document-qa-agent", "sessionId": "task-001-xyz", "bizParams": { "docId": 1024, "userId": "u_9527", "question": "请总结这份处理报告" }, "callbackRoute": "/open-api/agent/callback" }

Java 侧只要能正确解析这套 JSON，就可以和 Harness 完全解耦。我们后来扩展了多种 Agent，也几乎没有改过这套契约。

3. Java 侧封装实现：从 HttpClient 到任务管理器的落地代码

3.1 用 Spring Boot 的 RestTemplate 还是自研接口客户端

刚开始我图省事，直接用RestTemplate封装了 Harness 的调用。代码写起来非常顺手，几行就能发一个请求。但上线一跑就发现问题：默认的SimpleClientHttpRequestFactory没有连接池概念，每个任务都要重新建 connection，遇到瞬时并发时连接建立的开销非常明显。

后来我把底层换成了HttpClient配合连接池，更新了一下配置：

@Bean public RestTemplate agentHarnessRestTemplate() { HttpClient httpClient = HttpClientBuilder.create() .setMaxConnTotal(200) .setMaxConnPerRoute(50) .setConnectionTimeToLive(60, TimeUnit.SECONDS) .build(); HttpComponentsClientHttpRequestFactory factory = new HttpComponentsClientHttpRequestFactory(httpClient); factory.setConnectTimeout(3000); factory.setReadTimeout(65000); return new RestTemplate(factory); }

注意readTimeout我没有设成固定 5 秒。智能体任务里一旦涉及多轮工具调用，单次回调的响应时间很容易超过 30 秒，所以读取超时要放宽。查询接口的 5 秒超时是在 Service 层单独控制的，两个超时不能混为一谈。

3.2 异步任务状态机与回调接口实现

RuoYi-Vue-Plus 本身有定时任务模块，但我不建议用固定频率轮询 Harness。轮询的最大问题是延迟不可控：任务刚好在轮询间隔之外结束，用户就要多等几秒。我们的做法是“回调优先 + 兜底查询”双通道。

核心逻辑是一张agent_task表，记录每个任务从提交到结束的所有状态：

提交任务的 Service 方法很简单，核心是把业务参数转成 DTO，然后调用 Harness 接口，拿到taskId后立刻落库返回。

回调接口则是一个普通 Spring MVC POST 接口，接收 Harness 推送的结果，做两件事：验证签名、更新状态。签名用callback-secret和 payload 内容拼接后做 HMAC-SHA256，长度校验失败直接返回 401。这里有个细节：回调处理必须做幂等，因为网络抖动会导致 Harness 重试回调，我们不能因为两次回调就更新两次结果。

3.3 前端页面如何接入任务列表与状态刷新

RuoYi-Vue-Plus 前端用的是 Vue 3，和 Harness 没有直接关系。我们要做的只是在现有“任务管理”页面增加一个列表页和详情抽屉。

列表页数据完全来自agent_task表，不需要实时调用 Harness。这样页面加载非常快。任务详情页展示开始时间、结束时间、执行日志摘要和最终结果。为了实现“任务完成后自动刷新”，我用的是 WebSocket 推送，而不是前端轮询。

WebSocket 连接由 RuoYi 侧统一维护，任务状态发生变化时，后端把taskId和状态推到当前会话绑定的连接上，前端收到后只刷新当前选中的任务卡片。这里要注意一点：回调结果落库和 WebSocket 推送必须放在同一个事务边界里，否则可能出现“数据库已更新但页面没刷新”的情况。

4. 实际集成中踩到的坑与排查链路

4.1 回调时偶现“消息体已被消费”的诡异报错

这个问题折磨了我们大半天。现象是 Harness 回调 RuoYi 接口时，偶尔会收到类似“Body already consumed”的异常，但不是每次都出现。后来抓线程栈发现原因是：我们在进入 Controller 之前做了一次统一的日志切面，用@RequestBody读取 JSON 后，没有意识到HttpServletRequest的输入流只能读一次。日志切面先消费了 body，真正处理业务的 Controller 再读就拿到空串。

解决方式有两种，一是把日志切面里的 body 缓存到请求属性里，二是统一封装一个RepeatableReadRequestWrapper。我选择了后者，因为它能一并解决后续可能出现的参数签名验证问题。

4.2 AgentScope Harness 返回时间过长导致的网关超时

上线第一版时，前端点击一个按钮，后端会先调用 Harness，等它执行完再返回结果。遇到简单的资料问答还好，一旦 Agent 要搜索内部知识库、再做好几次工具调用，整体耗时就到了 30 秒以上。Nginx 网关默认的 60 秒超时虽然没在线上一开始就触发，但用户已经明显感觉到卡顿。

排查后确认问题不在 Harness，而在整体调用模式。我改成“先快速返回 pending 状态，随后通过回调/推送更新结果”，前端不再等待最终结果。这个改动也让 Harness 端可以放心使用较大的default_timeout，不用为了响应前端而牺牲任务质量。

4.3 并发任务增多后 Python 端内存持续上涨

Harness 单独部署并不能完全避免资源问题。我们把并发从 4 调到 16 后，容器内存一直涨，直到触发 OOM。日志显示执行引擎的任务上下文没有被及时释放。后来在 Harness 配置中明确打开了任务结束后的清理开关，并把 Daemon 线程的堆栈保留时间调短，内存曲线才稳定下来。

这类问题的排查思路是：先看是不是 Java 侧重复提交任务导致 Harness 积压，再用监控接口看活跃任务数。如果活跃任务数正常但内存还涨，大概率是执行引擎内部缓存，需要检查清理参数，而不是盲目加内存。

4.4 JSON 参数在字典排序后签名不匹配

回调签名在联调阶段一直报验签失败，两边拿同一个 JSON 转字符串，肉眼看着一模一样，但 HMAC 结果就是不同。后来发现 Harness 侧在签名前对 JSON 的 key 做了字典排序，而 Java 侧直接把原始字符串拿去计算。JSON key 顺序不同，签名自然不匹配。

规范做法是：双方约定一个规范化字符串，也就是对 JSON 的 key 做字典排序后去掉多余空格再拼上 secret。以后只要新增字段，校验逻辑也能保持一致。

5. 从能跑到跑稳：稳定性加固与细节优化

5.1 任务执行结果的幂等落库

刚开始落库逻辑比较简单：回调来了就 update，更新影响行数直接判断成功。后来连续出现“任务显示成功但结果文件没生成”的现象。排查发现是 Harness 重试回调时，我们把第一次回调的完成状态覆盖成了第二次的“中间状态”。确定方案是加一层幂等控制，任务表增加finish_time字段，当存在 finish_time 时，后续回调只做日志记录，不更新结果内容。

这个改动看似简单，但避免了绝大多数数据一致性问题。如果你有多个回调版本，建议再给回调消息加一个event_id，用唯一键去重。

5.2 用户权限与多租户隔离在 Harness 调用层的实现

RuoYi-Vue-Plus 自带权限体系，我们可以限制“谁能调用某个 Agent”。但真正要注意的是，调用层不能绕过权限直接传内部账号。我们做法是：Agent 请求体里只能携带系统内部生成的sessionId，用户实际的 userId 通过 RuoYi 的 Security 上下文拿到，作为bizParams里的一个字段传给 Harness。

这样即使 Harness 不小心把 sessionId 泄露出去，他人也无法直接用这个 ID 冒充用户。多租户隔离也做了两层：数据库层面按租户过滤agent_task记录，调用层按租户过滤 Agent 可见性。Harness 本身不感知租户，它只执行抽象任务，这样扩租户时不需要动 Python 环境。

5.3 监控告警与异常处理的最小化配置

我没有一开始就上完整监控链路，只加了最小化配置：任务失败率超过 5% 时发企业微信通知，任务长时间处于 PENDING 时每 5 分钟扫描一次并告警。这两条救过我们两次大问题。

第一次是 Harness 容器重启后没有自动注册回调路由，所有新任务都卡在 PENDING；第二次是底层模型服务的 Key 频率超限，导致任务整体失败率飙升。如果只盯着业务日志看，发现这些问题至少要滞后一两个小时。

5.4 后续扩展：模型网关接入和流式输出

现在这套集成已经稳定运行了两周，RuoYi-Vue-Plus 侧完全看不到 AgentScope 的 Python 细节。接下来我想把模型网关接入逻辑迁移到 Harness 的配置中心统一管理，再做流式输出的支持。流式输出的核心变化在回调协议：不再等任务全部完成，而是分段回调 token 序列，这对 Java 侧的状态机又是一个挑战。

不过这是下一个阶段的事了。眼前的经验是，集成一个复杂框架时，不要总想着把对方吞进来，分清边界、定好契约，反而跑得更稳。如果你也正在做类似的事，我建议从最简单的异步任务提交开始，先把链路跑通，再逐步补上权限、监控和流式能力。