1. 为什么要在 RuoYi-Vue-Plus 里塞进一个 AI 编排引擎

RuoYi-Vue-Plus 这套脚手架在国内中小型管理系统开发里出镜率极高，权限、数据权限、多租户、代码生成、工作流这些企业级能力基本开箱即用，很多团队拿它当"后台底座"来搭业务系统。但这两年有个明显变化：业务方开始不满足于"表单+列表+审批"这套老三样，越来越多的需求变成"能不能让系统自己判断一下""能不能根据这段描述自动生成工单""能不能把这几份文档自动归类"。说白了，就是要在传统 CRUD 系统里长出一点"智能"。

问题在于，绝大多数 RuoYi 系项目是纯 Java 技术栈，团队里没人愿意为了一个 AI 功能再单独维护一套 Python 服务，跨语言调用、部署、监控、鉴权全是额外成本。这时候把 AI 编排能力直接以 Java 库的形式嵌进现有工程，就成了最省事的路子。AgentScope 的 Harness 模块正好提供了这样一套 Java 侧的 Agent 编排能力，它把"模型调用、工具注册、多轮对话、执行循环"这些原本散落在各处的逻辑收敛成一个可编程的运行时。

这篇内容面向的是已经熟悉 RuoYi-Vue-Plus 基本结构、想在不引入第二套语言栈的前提下接入 AI 能力的后端开发者。我会把整个集成过程拆开讲：从依赖怎么引、模块怎么放，到 Agent 怎么注册、工具怎么暴露、会话怎么和系统用户绑定，再到实际跑起来之后那些文档里不会写的坑。核心关键词就三个：AgentScope Harness 集成、纯 Java AI 平台、RuoYi-Vue-Plus 扩展。读完你应该能自己动手把一套可用的 AI 编排能力挂到现有后台里，而不是停留在"知道有这么个东西"。

2. 集成前的架构判断：Harness 到底该放在哪一层

2.1 RuoYi-Vue-Plus 的模块划分与 AI 能力的归属

RuoYi-Vue-Plus 默认是多模块 Maven 结构，常见的是ruoyi-admin（启动入口）、ruoyi-system（系统业务）、ruoyi-common（通用工具）、ruoyi-framework（框架配置）这几块。AI 编排能力放哪里，直接决定了后面依赖会不会打架、循环依赖会不会出现。

我的建议是单独开一个ruoyi-ai模块，而不是塞进ruoyi-system或者ruoyi-common。理由很实际：Harness 会引入自己的 HTTP 客户端、JSON 处理、可能的日志门面，这些和ruoyi-common里已有的工具类存在版本冲突风险。单独成模块，依赖隔离干净，ruoyi-admin只依赖ruoyi-ai的接口层，业务模块通过接口调用，不会把 AI 的传递依赖污染到整个工程。

具体依赖方向是这样的：ruoyi-ai依赖ruoyi-common（复用它的统一返回、异常、工具类），ruoyi-system按需依赖ruoyi-ai，ruoyi-admin负责把ruoyi-ai的 Bean 扫描进来。这样 AI 模块既能用上框架的通用能力，又不会反向被业务模块依赖，保持单向。

2.2 为什么不做成独立微服务

有人会问，既然 AI 调用可能耗时、可能不稳定，为什么不干脆拆成独立服务？我的实测结论是：在中小规模场景下，独立服务的运维成本远大于它带来的隔离收益。拆出去意味着你要多维护一套注册发现、多一套鉴权透传、多一套链路追踪，而 AI 调用本身在 RuoYi 这种后台系统里往往是低频、非核心路径的操作（比如生成一段摘要、做一次分类），完全可以用线程池 + 异步任务的方式在单体里消化掉。

真正需要拆服务的临界点，是当 AI 调用变成高频核心链路，或者需要独立扩缩容的时候。在那之前，单体里嵌一个模块，部署简单、调试方便、事务和权限都能复用现成的，这才是"纯 Java AI 平台"这个思路的价值所在。

2.3 Harness 在运行时的角色定位

把 Harness 理解成一个"Agent 运行时容器"比较准确。它本身不负责具体业务，而是提供：Agent 的生命周期管理、消息在 Agent 之间的流转、工具的注册与调用分发、以及一轮对话的执行循环。你在 RuoYi 里要做的事情，本质上是把系统的业务能力包装成 Harness 能识别的工具，再把 Harness 的执行结果接回系统的业务流。

这个定位决定了集成的两个关键接口：一个是"工具注册"，把 RuoYi 的 Service 方法暴露给 Agent；另一个是"会话管理"，把 Harness 的会话和 RuoYi 的登录用户、租户绑定起来。这两块做扎实了，剩下的就是配置和调优。

3. 依赖引入与模块骨架搭建的实操细节

3.1 Maven 依赖的引入方式与版本对齐

Harness 作为 Java 库，通常以 Maven 坐标形式提供。在ruoyi-ai模块的pom.xml里引入时，第一件要确认的事是它依赖的 JSON 库和 HTTP 客户端版本。RuoYi-Vue-Plus 较新版本用的是 Jackson 或者 Hutool 的 JSON 工具，如果 Harness 内部用的是别的 JSON 实现，就可能在序列化时出现字段丢失、日期格式不一致这类隐蔽问题。

我的做法是在ruoyi-ai的pom.xml里显式声明 Harness 依赖，然后用mvn dependency:tree把整棵依赖树打出来，重点看三类包：JSON 处理、HTTP 客户端、日志门面。如果发现和父工程已有版本冲突，用<exclusions>把 Harness 传递进来的旧版本排掉，统一走父工程的版本管理。这一步看着琐碎，但不做的话后面会出现"本地跑得好好的，打包上线就报 NoSuchMethodError"这种经典问题。

<dependency> <groupId>com.example.agentscope</groupId> <artifactId>harness-core</artifactId> <version>${harness.version}</version> <exclusions> <exclusion> <groupId>com.fasterxml.jackson.core</groupId> <artifactId>jackson-databind</artifactId> </exclusion> </exclusions> </dependency>

提示：版本号统一放到父工程的<properties>里管理，别在子模块里写死，否则多模块升级时会漏改。

3.2 模块目录结构与包命名约定

ruoyi-ai模块内部我习惯按职责分四个包：config（自动配置和 Bean 声明）、agent（Agent 定义与注册）、tool（业务工具封装）、service（对外暴露的服务接口）。这样分的好处是，当你要排查"某个工具为什么没被 Agent 调用到"时，直接去tool包看注册逻辑，不用在几百个类里翻。

包名沿用 RuoYi 的约定，比如com.ruoyi.ai.config、com.ruoyi.ai.agent，这样和框架其他模块风格一致，团队新人接手时不会有认知负担。配置类上用@Configuration加@ConditionalOnProperty，让 AI 能力可以通过配置开关控制是否启用——这点很重要，因为不是每个部署环境都需要 AI 功能，能关掉就意味着出问题时可以快速降级。

3.3 自动配置类的编写要点

自动配置类是整个模块的入口，它要做三件事：初始化 Harness 运行时、注册工具、暴露服务 Bean。初始化运行时的时候，模型相关的配置（比如接口地址、密钥、超时时间）应该从 RuoYi 的配置体系里读，而不是硬编码。

@Configuration @ConditionalOnProperty(prefix = "ruoyi.ai", name = "enabled", havingValue = "true") public class AiAutoConfiguration { @Bean @ConditionalOnMissingBean public HarnessRuntime harnessRuntime(AiProperties properties) { HarnessConfig config = HarnessConfig.builder() .endpoint(properties.getEndpoint()) .apiKey(properties.getApiKey()) .connectTimeout(properties.getConnectTimeout()) .readTimeout(properties.getReadTimeout()) .build(); return HarnessRuntime.create(config); } }

这里有个细节：@ConditionalOnMissingBean要加上，方便测试时用 Mock 替换真实运行时。超时时间一定要显式配置，Harness 默认的超时往往偏长，在 Web 请求线程里同步调用会拖垮整个接口响应，后面第 6 节会专门讲这个。

4. 把 RuoYi 的业务能力包装成 Agent 可调用的工具

4.1 工具注册的核心机制

Harness 调用业务能力的方式是"工具调用"——Agent 在推理过程中决定要调用哪个工具、传什么参数，Harness 负责把调用分发到对应的实现上。所以集成的核心工作，就是把 RuoYi 的 Service 方法包装成工具。

工具注册一般有两种模式：注解扫描和手动注册。注解扫描写起来简洁，在方法上加个@AgentTool之类的注解，启动时自动收集；手动注册则是在配置类里一个个register。我倾向于混合使用：通用的、稳定的工具用注解扫描，需要动态参数或者依赖运行时上下文的用手动注册。原因是注解扫描在遇到重载方法、泛型参数时容易出歧义，而手动注册虽然啰嗦，但每个工具的入参出参都清清楚楚。

4.2 工具描述的质量决定 Agent 的可用性

这是最容易被低估的一点。很多人把工具注册完就完事了，结果 Agent 要么不调用工具，要么乱调用。问题几乎都出在工具描述上。Harness 是靠描述来判断"这个工具是干什么的、什么时候该用"的，描述写得含糊，Agent 的决策就一塌糊涂。

举个例子，你有一个查询订单的工具，描述写成"查询订单信息"，Agent 根本不知道它和"查询物流"有什么区别。正确的写法是把适用场景、参数含义、返回内容都写清楚：

@AgentTool( name = "queryOrderDetail", description = "根据订单编号查询订单的详细信息，包括下单时间、金额、状态。" + "适用于用户明确提供了订单编号、需要了解订单具体内容的场景。" + "如果用户只提供了手机号而没有订单号，请先调用 queryOrderByPhone。" ) public OrderDetail queryOrderDetail(@ToolParam("订单编号，纯数字字符串") String orderNo) { return orderService.getByOrderNo(orderNo); }

描述里明确写了"什么时候用""什么时候不用""前置工具是什么"，Agent 的调用准确率会有肉眼可见的提升。这是我在实际项目里反复验证过的经验，比调模型参数管用得多。

4.3 参数校验与异常兜底

工具被 Agent 调用时，传进来的参数是模型生成的，不能假设它一定合法。订单号可能传成中文，日期可能格式不对，枚举值可能超出范围。所以每个工具方法的第一件事应该是参数校验，校验失败要返回一个结构化的错误信息，而不是直接抛异常。

为什么强调结构化错误？因为 Agent 拿到错误信息后可能会自我修正、重新调用。如果你直接抛IllegalArgumentException，Harness 可能把它当成系统故障终止整个流程；如果你返回{"error": "订单号格式不正确，应为纯数字"},Agent 就有机会换个参数再试一次。这个差别在复杂任务里非常关键。

public ToolResult queryOrderDetail(String orderNo) { if (orderNo == null || !orderNo.matches("\\d+")) { return ToolResult.error("订单号格式不正确，应为纯数字字符串"); } OrderDetail detail = orderService.getByOrderNo(orderNo); if (detail == null) { return ToolResult.error("未找到该订单，请确认订单号是否正确"); } return ToolResult.success(detail); }

4.4 工具与数据权限的绑定

RuoYi-Vue-Plus 有完善的数据权限体系，工具调用不能绕过它。也就是说，Agent 通过工具查数据时，必须带上当前登录用户的身份，走和普通接口一样的数据权限过滤。实现方式是在工具方法里通过SecurityUtils拿到当前用户，把用户上下文传给 Service 层。

这里有个坑：如果 AI 调用是异步执行的（比如放到线程池里跑），SecurityUtils依赖的ThreadLocal在新线程里是空的，会直接报"获取用户失败"。解决办法是在提交异步任务前把用户上下文取出来，作为参数传进去，在异步线程里手动设置。这个细节不处理，异步 AI 功能一上线就会大面积报错。

5. 会话管理：让 Agent 记住"谁在问、问到哪了"

5.1 会话与系统用户的映射关系

Harness 的会话（Session）是它内部维护的对话上下文，而 RuoYi 的用户是系统级的身份。两者需要建立映射：一个系统用户可能有多个会话（比如开了多个对话窗口），一个会话必须归属于某个用户和某个租户。

我的做法是在数据库里建一张ai_session表，字段包括会话 ID、用户 ID、租户 ID、创建时间、最后活跃时间、会话状态。Harness 侧生成会话 ID 后，往这张表里插一条记录。这样做的价值在于：会话可以持久化、可以审计、可以按用户清理。纯内存的会话在服务重启后就丢了，用户体验很差。

5.2 多轮对话上下文的存储策略

多轮对话的上下文如果全放内存，服务一重启就断片；如果每轮都全量存数据库，数据量会爆炸。折中方案是内存 + 持久化双层：活跃会话的上下文放内存（用带过期时间的缓存），同时定期把关键节点快照到数据库。用户下次进来时，先从内存找，找不到再从数据库恢复最近 N 轮。

N 取多少合适？我的经验是保留最近 10 到 20 轮足够覆盖绝大多数场景。再往前的上下文对当前对话的贡献很小，反而会占用大量 token、拖慢响应、增加成本。超过这个轮数的历史，可以只保留摘要而不是原文。

5.3 会话并发与线程安全

同一个会话如果被并发访问（比如用户快速点了两次发送），Harness 的内部状态可能被破坏。解决办法是对会话加锁，同一会话的请求串行执行。可以用ConcurrentHashMap存会话锁对象，或者用 Redis 的分布式锁（多实例部署时必须用后者）。

public String chat(String sessionId, String userInput) { Lock lock = sessionLocks.computeIfAbsent(sessionId, k -> new ReentrantLock()); lock.lock(); try { return harnessRuntime.chat(sessionId, userInput); } finally { lock.unlock(); } }

单机用ReentrantLock够了，多实例部署就得换成 Redis 锁，否则两个实例同时操作一个会话照样出问题。这个点在做集群部署时特别容易漏。

6. 实测踩坑：那些文档里不会写的集成问题

6.1 同步调用拖垮 Web 线程池

最开始我把 AI 调用直接放在 Controller 里同步执行，测试环境没问题，一上生产就发现接口响应时间从几百毫秒飙到十几秒，并发一高整个线程池被打满，连不相关的接口都开始超时。原因很简单：AI 调用是秒级甚至十秒级的操作，而 Tomcat 的请求线程是宝贵资源，被这种长耗时操作占住，其他请求就排队了。

解决方案是异步化。接口收到请求后立即返回一个任务 ID，AI 调用丢到独立线程池里执行，前端通过轮询或者长连接拿结果。线程池要单独配置，核心线程数、队列长度、拒绝策略都要根据实际并发量调，别用默认的。

@Bean("aiExecutor") public ThreadPoolTaskExecutor aiExecutor() { ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor(); executor.setCorePoolSize(4); executor.setMaxPoolSize(16); executor.setQueueCapacity(100); executor.setThreadNamePrefix("ai-task-"); executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy()); executor.initialize(); return executor; }

6.2 工具调用超时导致的"半截任务"

Agent 执行一个任务可能连续调用多个工具，如果某个工具卡住（比如查了个慢 SQL），整个任务就挂在那里。Harness 一般有整体超时，但工具级别的超时往往需要自己控制。我的做法是给每个工具方法加超时保护，用Future.get(timeout)或者信号量控制，超时后返回一个明确的错误让 Agent 决定是重试还是放弃。

这里有个反直觉的点：工具超时后不要直接抛异常终止，而是返回"该操作超时，请稍后重试或换一种方式"。因为 Agent 可能会根据这个信息调整策略，比如换个查询条件、或者告诉用户稍后再试。直接抛异常会让整个对话中断，体验很差。

6.3 模型返回格式不稳定引发的解析失败

模型输出是自然语言，即使你要求它返回 JSON，它也可能给你包一层 markdown 代码块，或者在 JSON 前后加一句"好的，结果如下"。如果代码里直接JSON.parse，就会频繁解析失败。

处理方式是容错解析：先尝试直接解析，失败后剥离可能的代码块标记再解析，再失败就用正则提取第一个完整的 JSON 对象。同时，在提示词里明确要求"只返回 JSON，不要任何额外文字"，能减少大部分问题。但容错逻辑必须留着，因为模型的行为不是 100% 可控的。

6.4 日志与可观测性缺失

AI 调用出问题时，如果没有详细的日志，你根本不知道是模型没返回、工具没调用、还是参数传错了。所以从第一天起就要把日志打全：每次模型请求的输入输出、每次工具调用的入参出参、每轮对话的耗时。这些日志在排查问题时是救命的。

但要注意脱敏。用户输入里可能有手机号、身份证号，工具返回里可能有敏感业务数据，日志里不能明文记录。RuoYi 有现成的脱敏工具，直接复用。

7. 上线前的配置调优与降级预案

7.1 超时与重试参数的取值逻辑

超时和重试这两个参数，取值不能拍脑袋。连接超时一般设 3 到 5 秒，因为网络握手正常都在毫秒级，超过这个数基本是网络问题，重试也没用。读取超时要看模型响应速度，一般设 30 到 60 秒，复杂推理任务可能更久。重试次数建议最多 1 次，因为 AI 调用不是幂等友好的场景，重试可能产生重复的工具调用副作用。

重试还要区分错误类型：网络超时可以重试，参数错误重试没意义，限流错误要退避后再试。一刀切的重试策略只会放大问题。

7.2 降级开关的设计

AI 功能必须能一键关掉。设计上分两级：全局开关（配置中心控制，关掉后所有 AI 接口返回"功能维护中"）和单功能开关（某个具体 Agent 出问题，只关它）。全局开关用于模型服务整体不可用时的紧急降级，单功能开关用于局部问题隔离。

开关状态要能动态刷新，不能改配置还得重启。RuoYi 集成了配置刷新能力的话直接用，没有的话用定时任务轮询配置中心也行。

7.3 成本控制的实际手段

AI 调用是花钱的，尤其是 token 消耗。控制成本有几个立竿见影的手段：限制单次对话的最大轮数（防止用户无限聊下去）、限制单次请求的最大 token（防止超长输入）、对高频用户做限流（防止刷接口）、缓存常见问题的回答（相同问题直接返回缓存）。

其中缓存最容易被忽略。很多后台系统的 AI 问答其实是重复的，比如"这个功能怎么用"，缓存命中率能到 30% 以上，省下来的成本很可观。缓存 key 用问题文本的哈希，注意设置合理的过期时间。

8. 我个人在集成过程中的几点体会

整套东西跑通之后回头看，最耗时间的不是写代码，而是调工具描述和排查上下文丢失这两件事。工具描述我前后改了七八版，每改一版 Agent 的调用准确率就上一个台阶，这个过程没有捷径，只能拿真实场景反复测。上下文丢失则集中在异步和权限两个环节，凡是跨线程的地方都要检查一遍用户上下文有没有正确传递。

另外一个体会是，别指望 Agent 一次就把复杂任务做对。真实场景里，一个需要调用三四个工具的任务，第一次成功率可能只有六七成。所以产品设计上要允许"重试"和"人工兜底"，把 AI 定位成"辅助"而不是"全自动"，这样即使它偶尔出错，业务也不会崩。等准确率通过持续调优稳定到九成以上，再考虑扩大它的自主权。

最后，纯 Java 集成这条路是走得通的，而且对 RuoYi 系团队来说是最平滑的选择。它不需要你引入新语言、新部署单元，复用现有的权限、日志、监控体系，出问题也在熟悉的排查路径里。代价是你要接受 Java 生态在 AI 编排这块相对年轻，一些高级特性可能不如其他语言栈丰富，但对绝大多数后台系统的智能化需求来说，够用了。