企业官网建设流程全解析

1. 为什么 Java 仍是构建 AI Agent 框架的理性选择——从“被质疑”到“被重估”的真实现场

最近在几个技术群和线下交流中，总有人一提“AI Agent”，下意识就切到 Python 或 Rust 栈：Python 有 LangChain、LlamaIndex 的成熟生态，Rust 有 recent.ai、llm-chain 的高性能声量。而当我拿出一个基于 Spring Boot 的 Java Agent 框架原型——JavaManus——演示它如何调度大模型、管理工具链、执行 ReAct 推理循环、并稳定跑在生产级 Tomcat 上时，现场沉默了三秒，然后有人问：“Java 做 Agent？不是写 ERP 和银行核心系统的吗？”

这恰恰是我要说的起点。不是 Java “能不能”做 AI Agent，而是它“为什么必须”在特定场景下承担这个角色——尤其当你的 Agent 要嵌入已有 Java 生态：比如银行风控系统要接入 LLM 做规则解释生成，电商中台要让 Agent 实时调用库存、订单、优惠券等 Spring Cloud 微服务，或者政务平台要求全链路审计日志、国密 SM4 加密、JVM 级内存监控。这些需求，Python 的 GIL 锁、进程隔离、依赖冲突，Rust 的 GC 缺失与 JNI 适配成本，都会在落地时变成硬伤。

JavaManus 不是一个“为了用 Java 而用 Java”的玩具项目。它的设计锚点非常具体：让已有 Java 工程师无需切换技术栈，就能把 LLM 能力像注入一个 Service Bean 一样，无缝织入现有业务逻辑流。它不替代 LangChain，而是补位——补的是企业级 Java 应用在 AI 化进程中缺失的“协议层”：统一的 Prompt 编排契约、可插拔的 Tool Registry、带事务回滚的 Action 执行器、与 Spring AOP 深度耦合的 Observation Hook。关键词里没写的但实际贯穿始终的，是ReAct（Reasoning + Acting）范式在 JVM 上的工程化落地：不是简单调 API，而是让模型输出的 JSON Action 指令，能被 Java 反射精准解析、参数校验、事务包装、异常兜底、结果归一化。

我试过用 Python 写一个同等功能的 Agent 调度器，再通过 REST 调用 Java 微服务——光是序列化/反序列化耗时就占到单次推理延迟的 37%；换成 gRPC，又得维护两套 proto 定义和版本兼容。而 JavaManus 直接在 Spring Context 里注册 Tool Bean，Agent Runtime 通过 ApplicationContext.getBean() 拿到实例，调用就是本地方法调用，毫秒级响应。这不是性能炫技，是当你每天处理 200 万次用户咨询意图解析时，省下的每 15ms 都意味着少开两台 32C64G 的推理节点。

所以，这篇不是“Java vs Python 的语言战争”，而是一份给 Java 工程师的实操地图：告诉你当公司 CTO 说“下周上线客服 Agent”时，你手头只有 Spring Boot 2.7、MyBatis-Plus、Redis 和一套老但稳定的 Dubbo 服务，该怎么在两周内搭出一个可灰度、可监控、可回滚的 Agent 框架。它不教你怎么训练大模型，但会告诉你怎么让 Qwen2-7B 的 output 字符串，安全地变成OrderService.cancelOrder(orderId)这行代码的执行入口。

2. JavaManus 的骨架拆解：四个核心模块如何协同完成一次 ReAct 循环

JavaManus 的设计哲学是“分层不割裂”——所有模块都运行在同一个 ClassLoader 下，共享 Spring 的生命周期管理，但职责边界极其清晰。整个框架不依赖任何外部 Agent SDK，所有能力都来自对 Spring Boot 自动装配机制的深度利用。下面以一次典型的 ReAct 循环为例（用户问：“帮我查下昨天下单但还没发货的订单，取消掉”），逐层拆解四个核心模块的协作链路。

2.1 Prompt Orchestrator：不只是模板拼接，而是语义契约编排器

很多 Java 开发者第一反应是用String.format()或 Thymeleaf 渲染 Prompt。JavaManus 的 Prompt Orchestrator 完全摒弃这种做法，它把 Prompt 视为一种可验证、可版本化、可灰度的“接口契约”。

它由三部分组成：

• Schema Registry：定义每个 Agent 的输入 Schema（如UserQuery）、输出 Schema（如ReActAction），使用 Jackson 注解驱动，支持@JsonSubTypes处理多态 Action。
• Template Engine：不基于字符串，而是基于 AST 解析。例如{tool_call}占位符会被解析为ToolCallNode，其子节点包含tool_name、arguments等字段，渲染时自动注入当前可用 Tool 列表的描述文本。
• Context Injector：在渲染前动态注入上下文变量。比如用户历史订单 ID 列表，不是简单塞进字符串，而是通过ContextProviderSPI 接口实现，可对接 Redis 缓存、MySQL 历史表、甚至 Kafka 流式聚合结果。

实测对比：纯字符串模板在用户 query 含特殊字符（如"订单号：#ABC-2024!"）时，常因转义失败导致 LLM 输出格式错乱；而 AST 渲染器将#识别为注释符号，自动转义为\#，保证 JSON 结构完整。更重要的是，当你要灰度测试新 Prompt 版本时，只需在application.yml中配置prompt.version: v2，Orchestrator 就会加载对应 Schema 和 Template，旧版本流量走 v1，新版本走 v2，完全无侵入。

提示：不要在 Prompt 中硬编码业务规则。JavaManus 强制要求所有规则判断（如“未发货订单才能取消”）必须封装成 Tool，Prompt 只负责引导模型识别意图并生成 Action，避免模型幻觉污染业务逻辑。

2.2 Tool Registry：让 Java 方法成为 LLM 可调用的“原子能力”

这是 JavaManus 最具 Java 特色的设计。它不把 Tool 当作 HTTP endpoint，而是当作 Spring Bean 的增强版。每个 Tool 必须实现Tool接口：

public interface Tool { String name(); // 对应 LLM 输出中的 tool_name String description(); // 供 Prompt 渲染器生成工具描述 Class<? extends ToolInput> inputType(); // 输入 DTO 类型，用于自动 JSON 反序列化 <T> T execute(ToolInput input, ToolContext context) throws ToolException; }

注册方式极其简单：在任意@Component类上加@ToolBean注解，框架自动扫描并注册。例如：

@Component @ToolBean public class CancelOrderTool implements Tool { @Override public String name() { return "cancel_order"; } @Override public String description() { return "取消指定订单。仅适用于状态为 '已支付' 且 '未发货' 的订单。"; } @Override public Class<CancelOrderInput> inputType() { return CancelOrderInput.class; } @Override public Object execute(ToolInput input, ToolContext context) { CancelOrderInput dto = (CancelOrderInput) input; // 此处可直接注入 OrderService、TransactionTemplate 等 Spring Bean return orderService.cancelOrder(dto.getOrderId()); } }

关键细节在于ToolContext：它携带了本次 Agent 调用的完整上下文，包括traceId、userId、tenantId，以及最重要的TransactionStatus。这意味着execute()方法内发生的数据库操作，天然处于 Spring 的事务管理之下——如果 LLM 先调用query_order获取订单状态，再调用cancel_order，两个 Tool 的 DB 操作可被同一个事务包裹，避免状态不一致。

我踩过的坑：早期把 Tool 当作普通工具类，直接 new 实例，结果无法注入@AutowiredBean，更无法参与事务。后来强制要求所有 Tool 必须是 Spring 管理的 Bean，并在ToolRegistry初始化时校验ApplicationContext是否可用，否则启动失败。这个设计让 Java 工程师写 Tool 的体验，和写一个普通 Service 几乎无异。

2.3 ReAct Executor：控制流引擎，而非简单的 if-else 分支

LLM 输出的 ReAct Action 是结构化 JSON，典型格式如下：

{ "thought": "用户要取消未发货订单，需先查询订单状态", "action": "query_order", "action_input": {"order_id": "ORD-20240520-001"} }

JavaManus 的ReActExecutor不是写个switch(action)就完事。它是一个状态机驱动的执行器，核心状态包括THINKING、ACTING、OBSERVING、FINISHING。每次状态迁移都触发对应的 Hook：

• ACTING状态：调用ToolRegistry.getTool(action).execute(...)，捕获所有异常并转换为标准化ToolExecutionResult。
• OBSERVING状态：将 Tool 执行结果（成功或失败）格式化为 Observation 文本，注入到 Prompt 上下文，供下一轮推理使用。
• FINISHING状态：当 LLM 输出{"final_answer": "已为您取消订单 ORD-20240520-001"}时，执行最终答案提取，并触发onFinish回调。

最实用的特性是Action Pipeline：允许为某个 Tool 配置前置/后置处理器。例如cancel_orderTool 可配置PreCancelValidator（校验用户权限、订单状态）和PostCancelNotifier（发短信通知），这些 Processor 也是 Spring Bean，可自由注入其他服务。Pipeline 配置在tool-config.yml中：

tools: cancel_order: preProcessors: [preCancelValidator] postProcessors: [postCancelNotifier, updateKpiCounter]

这比在每个 Tool 内硬编码校验逻辑干净得多，也便于 A/B 测试不同校验策略。

2.4 Observation Manager：让“观察”成为可审计、可追踪的一等公民

ReAct 的OBSERVATION不是 LLM 的黑盒反馈，而是 JavaManus 的核心数据资产。Observation Manager 负责三件事：

• 结构化解析：将 LLM 返回的 Observation 字符串（如"订单 ORD-20240520-001 状态：已支付，未发货"）解析为ObservationDTO，字段包括orderId、status、isShippable等，便于后续条件判断。
• 持久化归档：默认写入 MySQL 的agent_observation_log表，字段含trace_id、step_id、tool_name、input_json、output_json、duration_ms、is_success。表结构支持按trace_id快速回溯整个 Agent 执行链路。
• 实时推送：通过 Spring Event 发布ObservationEvent，监听器可做实时告警（如连续 5 次query_order失败触发运维告警）、指标上报（Prometheus）、或写入 Elasticsearch 供运营分析。

一个真实案例：某次上线后发现refund_tool调用成功率骤降。我们没去查 LLM 日志，而是直接在 Kibana 中筛选tool_name: refund_tool AND is_success: false，发现 92% 的失败都发生在input_json中reason字段为空。追查发现前端传参时漏了退款原因，Observation Manager 的结构化解析立刻暴露了这个上游缺陷，修复周期从 3 天缩短到 2 小时。

3. Spring Boot 的深度缝合：如何让 Agent 框架像原生组件一样呼吸

JavaManus 的最大优势，不是它有多酷炫，而是它“不突兀”。它不强迫你改写现有代码，而是像 Spring Security 或 Spring Data JPA 那样，成为你项目里一个安静但有力的基础设施。这种无缝感，来自于对 Spring Boot 自动装配机制的极致运用。

3.1 Starter 的魔法：一行依赖，全自动装配

JavaManus 提供javamanus-spring-boot-starter。你在pom.xml中添加：

<dependency> <groupId>com.javamanus</groupId> <artifactId>javamanus-spring-boot-starter</artifactId> <version>1.2.0</version> </dependency>

启动类加上@EnableJavaManus（一个空注解），框架就自动完成以下动作：

• 扫描所有@ToolBean，注册到ToolRegistry；
• 创建PromptOrchestratorBean，加载classpath:/prompts/下的模板文件；
• 初始化ReActExecutor，注入ToolRegistry和ObservationManager；
• 配置AgentProperties，读取application.yml中的javamanus.*配置项；
• 注册AgentAutoConfiguration，这是真正的装配中枢。

关键在于AgentAutoConfiguration的条件装配逻辑。它使用@ConditionalOnClass检测是否引入了spring-web，若有，则自动配置AgentController（提供/v1/agent/chatREST 接口）；若检测到spring-cloud-starter-openfeign，则自动启用FeignToolInvoker，让 Tool 可直接调用 Feign Client；若存在redis-starter，则ObservationManager默认使用 Redis 作为缓存层。

这种“有啥用啥”的策略，避免了传统框架常见的“过度配置”问题。你不用为不用的功能写一堆@ConditionalOnMissingBean，框架自己就懂。

3.2 AgentController：REST 接口背后的三层拦截

AgentController是对外暴露的唯一入口，但它绝不是简单的@RestController。它内置了三层拦截器，每一层都解决一个关键问题：

• Trace Interceptor：基于 Sleuth 或自研 TraceID 生成器，为每次请求生成唯一trace_id，并注入到ThreadLocal<AgentContext>中。这个AgentContext在整个 ReAct 循环中透传，确保 Observation Log、Metrics、Error Log 都能关联到同一链路。
• Rate Limit Interceptor：不是用 Redis 计数器那种粗粒度限流，而是基于userId+tenantId的滑动窗口限流。配置项javamanus.rate-limit.per-user=10表示每个用户每分钟最多发起 10 次 Agent 请求。限流失败时返回429 Too Many Requests，并附带Retry-After头。
• Fallback Interceptor：当 LLM 服务不可用（HTTP 503 或超时），自动降级到预设的 Fallback Strategy。策略可配置为RULE_BASED（执行硬编码规则）、CACHE_FIRST（查 Observation 缓存）、或DIRECT_RESPONSE（返回静态提示语）。降级过程对前端完全透明，AgentController返回的仍是标准 JSON 格式。

实测效果：在一次大促期间，LLM 服务因 GPU 显存不足出现 30% 超时。由于启用了CACHE_FIRST降级，用户看到的响应延迟从平均 8s 降到 1.2s，错误率从 28% 降至 0.3%，业务方完全没感知到底层故障。

3.3 Metrics & Health：让 Agent 成为可观测系统的一部分

JavaManus 的指标体系完全融入 Spring Boot Actuator。访问/actuator/metrics，你能看到这些指标：

• javamanus.agent.request.count：总请求数，标签status=success|failed|fallback
• javamanus.tool.execution.time：各 Tool 执行耗时，P95/P99 分位值
• javamanus.prompt.render.time：Prompt 渲染耗时
• javamanus.llm.api.latency：LLM API 调用延迟（需配置llm.client.type=rest）

Health Indicator 更实用：/actuator/health中新增javamanus健康组，状态取决于：

• ToolRegistry是否注册了至少一个 Tool；
• PromptOrchestrator能否成功加载默认模板；
• 配置的 LLM Endpoint 是否可连通（通过curl -I探针）。

这意味着，你的 Kubernetes liveness probe 可以直接检查/actuator/health/javamanus，如果 Agent 框架自身不可用，Pod 就会被重启，而不是让故障蔓延到业务层。

注意：不要在application.yml中把 LLM 的 API Key 写死。JavaManus 强制要求从Environment或 Vault 中读取，启动时校验llm.api.key是否为空，为空则抛出IllegalStateException，防止密钥泄露风险。

4. ReAct 在 Java 中的落地难点：从理论到生产的 7 个关键决策点

ReAct 范式在论文里很美，但落到 Java 生产环境，每个环节都有“看起来简单，做起来要命”的细节。JavaManus 的设计，本质上是对这 7 个关键决策点的逐一攻坚。

4.1 Action 名称的大小写与下划线之争：为什么必须强制 snake_case？

LLM（尤其是开源模型）对 Action 名称的格式极其敏感。我们测试过 Qwen、ChatGLM、Phi-3，它们在 prompt 中看到queryOrder时，大概率输出{"action": "queryOrder"}，但 Java 的方法命名规范是queryOrder，而 Spring 的@ToolBean注解要求name()返回query_order。如果放任不统一，就会出现 LLM 输出queryOrder，而ToolRegistry查不到queryOrderTool，只能 fallback 到错误处理。

解决方案：JavaManus 在ToolRegistry初始化时，对所有 Tool 的name()做标准化处理——强制转为snake_case。同时，在 Prompt 模板中，所有 Tool 描述都写成query_order格式。这样，无论 LLM 怎么输出，框架层都做一次映射：

public Tool getTool(String actionName) { String normalized = StringUtils.camelToSnake(actionName); // queryOrder -> query_order return tools.get(normalized); }

这个看似微小的决策，避免了 80% 的 Action 调用失败。它背后的理念是：让 LLM 的输出格式，向 Java 的工程规范靠拢，而不是反过来。

4.2 Tool 输入参数的强类型校验：JSON 反序列化的陷阱

LLM 生成的action_inputJSON，经常不符合预期。比如query_order的输入 DTO 定义为：

public class QueryOrderInput { @NotBlank private String orderId; @Min(1) private Integer page; }

但 LLM 可能输出：

{"order_id": "ORD-123", "page": "1"} // page 是字符串，不是整数

Jackson 默认会静默转换"1"为1，但一旦遇到{"page": "abc"}，就会抛JsonMappingException，导致整个 ReAct 循环中断。

JavaManus 的解法是：在ReActExecutor的ACTING阶段，不直接objectMapper.readValue(json, inputType)，而是先用JsonNode解析，再手动校验每个字段类型，再转换。伪代码如下：

JsonNode node = objectMapper.readTree(json); // 校验 page 字段是否存在且为数字 if (!node.has("page") || !node.get("page").isNumber()) { throw new ToolInputException("page must be a number"); } // 类型安全转换 QueryOrderInput input = objectMapper.treeToValue(node, QueryOrderInput.class);

这个过程增加了 2ms 开销，但换来的是 100% 的输入鲁棒性。线上数据显示，未加此校验时，Tool 执行失败率 12.7%；加入后降至 0.3%。

4.3 Observation 的“噪声过滤”：如何让 LLM 看到干净的信号

LLM 的推理质量，极度依赖 Observation 的质量。如果 Observation 是"查询失败：数据库连接超时"，LLM 很可能继续尝试重试，而不是转向人工客服。JavaManus 内置了 Observation Filter 链：

• ErrorNormalizerFilter：将各种数据库异常（SQLTimeoutException、SQLException）统一转为"数据库繁忙，请稍后再试"；
• PIIScrubberFilter：自动脱敏 Observation 中的手机号、身份证号、银行卡号（正则匹配 + AES 加密）；
• LengthTruncatorFilter：截断超过 500 字符的 Observation，避免 LLM 上下文溢出。

这些 Filter 也是 Spring Bean，可通过observation.filters配置启用/禁用。最有效的组合是error-normalizer + pii-scrubber，它让 LLM 看到的永远是结构清晰、安全合规、长度可控的 Observation，显著提升final_answer的准确率。

4.4 多轮对话的状态管理：为什么不用 Redis 存 session？

很多方案用 Redis 存sessionId -> conversationHistory。JavaManus 选择在内存中维护ConversationState，理由很实在：单次 Agent 调用的平均耗时是 1.8s，而 Redis 网络 RTT 是 0.8ms，看似可以忽略，但当 QPS 达到 5000 时，每秒额外产生 4000 次 Redis IO，成为瓶颈。

JavaManus 的方案是：每个请求分配一个ConversationState实例，通过ThreadLocal绑定到当前线程。State 包含history（List ）、context（Map<String, Object>）、maxSteps（防死循环）。当 ReAct 循环结束，State 自动销毁。

当然，这要求应用服务器是单线程模型（Tomcat 默认是）。对于 Netty 或 WebFlux 场景，JavaManus 提供WebFluxConversationManager，用Mono.deferContextual替代ThreadLocal。这种“因地制宜”的设计，比一刀切的 Redis 方案更高效。

4.5 LLM 客户端的容错重试：不是简单 retry，而是策略重试

JavaManus 的LlmClient支持三种重试策略：

• EXPONENTIAL_BACKOFF：默认，失败后等待baseDelay * 2^retryCountms；
• CIRCUIT_BREAKER：连续 3 次失败，熔断 30s，期间所有请求直接 fallback；
• ROUTING：配置多个 LLM Endpoint（如qwen-api,glm-api），失败时自动路由到下一个。

最关键的是，重试时不重放整个 ReAct 循环，只重放最后一次 LLM 调用。因为之前的 Tool 执行结果（Observation）已经缓存，重试只需把history中最后一条THINKING+OBSERVATION发送给新 LLM。这节省了 70% 的重试成本。

4.6 Token 使用的精确计量：为什么不能只看 response.length()

LLM 的 token 计数，直接影响成本和性能。JavaManus 集成了tiktoken-jvm，对 Prompt 和 Response 分别计数。但它做了更细粒度的事：区分输入 token 和输出 token。

配置项javamanus.llm.max-output-tokens=512，表示只限制模型生成的 token 数，不限制输入。因为输入 token（Prompt + History）是固定的，而输出 token 是变量。如果只用response.length()估算，误差高达 40%（中文字符 vs token）。

JavaManus 在LlmClient返回后，立即调用tiktoken.encodingForModel("qwen2").encode(response)精确计数，并记录到 Micrometer 的llm.output.tokens指标中。运维团队据此优化 Prompt 长度，将平均输出 token 从 320 降到 210，LLM 成本下降 34%。

4.7 Agent 的灰度发布：如何让 1% 的用户先用新 Prompt？

JavaManus 的灰度能力不依赖网关，而是内置于PromptOrchestrator。它支持两种灰度策略：

• Header-based：检查请求 HeaderX-JavaManus-Prompt-Version: v2，优先使用 v2；
• Traffic-based：配置javamanus.prompt.traffic-ratio=0.01，1% 流量随机使用 v2。

更强大的是A/B Test 模式：可同时启用 v1 和 v2，将相同用户 query 分发到两个 Agent 实例，比较final_answer的人工评分、用户点击率、任务完成率，数据自动上报到ab_test_result表。这让我们在上线新 Prompt 前，用真实流量验证效果，而不是靠主观判断。

5. 从 Demo 到生产：JavaManus 在三个真实场景中的落地实践

理论讲完，现在看它怎么在真实战场发挥作用。以下是我在金融、电商、政务三个领域，用 JavaManus 搭建 Agent 的实战复盘。没有 PPT 式的成功，只有踩坑后的修正。

5.1 场景一：银行智能柜员助手（金融风控合规场景）

需求：客户在手机银行 App 问“我的信用卡额度还能提多少？”，Agent 需调用风控系统查询当前额度、近 6 个月账单、逾期记录，再结合监管规则（如《商业银行信用卡业务监督管理办法》第 32 条）计算可提升额度，并生成合规话术。

JavaManus 实现：

• Tool：QueryCreditLimitTool（查额度）、CheckOverdueTool（查逾期）、CalculateRaiseTool（计算可提升额）；
• Prompt：在 System Prompt 中嵌入监管条文摘要，并强调“所有回答必须引用具体条款编号”；
• Observation Filter：启用RegulationComplianceFilter，自动检查final_answer中是否包含《办法》第XX条，不包含则拒绝返回。

踩坑与修复：

• 初期 LLM 常虚构条款编号（如“《办法》第999条”）。解决方案：在CalculateRaiseTool的execute()中，强制返回结构化结果{ "max_raise": 5000, "regulation_ref": "第32条" }，Prompt 中明确指令“只能从 Tool 返回的regulation_ref中引用”。
• 风控系统响应慢（平均 1.2s），导致整体延迟超标。修复：将QueryCreditLimitTool和CheckOverdueTool设为@Async，并发调用，总耗时降至 0.7s。

效果：上线后，92% 的额度咨询由 Agent 自动完成，人工坐席压力下降 35%，合规审核通过率 100%（此前人工回复有 8% 的条款引用错误）。

5.2 场景二：跨境电商售后自助（多语言、多商户场景）

需求：平台上有 200+ 商户，每个商户有自己的退货政策（如“7 天无理由”、“仅限尺码问题”）。用户用英文问：“I want to return this dress because it's too small.”，Agent 需识别商品、归属商户、查询该商户政策、生成退货指引。

JavaManus 实现：

• Tool：QueryMerchantPolicyTool（根据商品 ID 查商户政策）、GenerateReturnGuideTool（生成多语言退货步骤）；
• Prompt：System Prompt 中定义多语言指令：“If user speaks English, reply in English. If Chinese, reply in Chinese.”；
• Context Injector：TenantContextProvider根据tenant_id注入当前商户的 policy 文本。

踩坑与修复：

• LLM 对“too small”理解不准，常误判为“质量问题”而非“尺码问题”，触发错误政策。修复：在QueryMerchantPolicyTool返回的 Observation 中，强制标注{"issue_type": "size_mismatch", "policy_applies": true}，Prompt 中指令“必须依据issue_type字段选择政策”。
• 多商户政策文本过长（平均 800 字），挤占 LLM 上下文。修复：PolicySummarizerTool用 MiniCPM 模型实时摘要政策到 100 字以内，再注入 Prompt。

效果：支持 8 种语言，商户政策变更后，Agent 自动生效（无需重新训练），售后工单量下降 41%，NPS 提升 22 点。

5.3 场景三：政务热线知识库（高可靠性、低延迟场景）

需求：12345 热线后台，市民问：“新生儿落户需要什么材料？”，Agent 需从结构化知识库（MySQL）查最新政策，生成清单，并支持追问（如“在北京海淀区怎么办？”）。

JavaManus 实现：

• Tool：QueryPolicyTool（查政策）、QueryDistrictTool（查区级细则）；
• ReAct Executor：启用MAX_STEPS=3，防无限追问；
• Observation Manager：所有 Observation 写入 MySQL，并开启 binlog，供审计系统实时同步。

踩坑与修复：

• 知识库更新频繁（每周 3 次），但QueryPolicyTool的缓存（Caffeine）未及时失效。修复：在知识库更新后，发送PolicyUpdateEvent，监听器调用toolCache.invalidateAll()。
• 市民追问“海淀区”时，LLM 常忽略前序上下文，重复问落户材料。修复：在 Prompt 的history部分，用---分隔每轮，并加前缀User: ... / Assistant: ...，强化对话结构。

效果：平均响应时间 420ms（低于 500ms SLA），政策准确率 99.2%（人工抽检），审计系统可追溯每条回答的原始知识库快照。

6. JavaManus 的边界与未来：它不是万能的，但解决了最关键的“最后一公里”

写到这里，必须坦诚 JavaManus 的局限性。它不是一个通用 AI 平台，而是一个高度聚焦的“Java Agent 协议层”。它的价值，不在于取代 LangChain，而在于解决企业 Java 应用在拥抱 AI 时，那个最痛的“最后一公里”：如何让 LLM 的能力，像调用一个本地 Java 方法一样简单、可靠、可运维。

它的边界很清晰：

• 不做模型训练/微调：它假设你已有可用的 LLM API（Qwen、GLM、或私有部署的 Llama）；
• 不做前端交互：它只提供 REST/SDK 接口，UI 由业务方自行开发；
• 不做复杂记忆管理：长时记忆（如用户画像）需业务方通过Context Injector接入自有系统；
• 不做多模态：目前只支持 text-in/text-out，图像/语音需前置服务转换。

但正是这些“不做”，让它足够轻、足够稳、足够贴合 Java 工程师的思维习惯。你不需要学 Python 的 async/await，不用研究 Rust 的 ownership，只要你会写@Service、@Transactional、@Scheduled，你就能在两天内，让一个已有 Spring Boot 项目，获得 Agent 能力。

最后分享一个真实技巧：在application-dev.yml中，把javamanus.llm.client.type=mock，MockClient 会返回预设的 JSON，让你在没 LLM 服务时，也能完整调试 Tool 链路和 Prompt 编排。这个MockMode是我们团队每天必开的开关，它让开发效率提升了不止一倍。

JavaManus 的名字，源自 “Java Manus”（拉丁语“Java 之手”）。它不试图成为大脑，而是成为那双稳定、精准、可信赖的手——帮你把 AI 的力量，真正握在自己手中。