LangChain4j+LangGraph4j低代码智能体工作流实战架构-平芜编程栈

1. 这不是又一个“AI平台”PPT，而是一套能跑通真实业务闭环的低代码智能体工作流骨架

最近三个月，我带着团队在三个不同行业的客户现场落地了四套基于 LangChain4j + LangGraph4j 的智能体系统——从制造业设备报修工单自动分派，到金融信贷材料初筛+风险点标注，再到政务12345热线诉求分类与知识库联动响应。过程中最深的体会是：所谓“低代码智能体平台”，根本不是把几个组件拖拽拼起来就完事；它本质是一套面向业务逻辑抽象、而非技术细节编排的工程化契约体系。LangChain4j 提供的是原子级能力封装（比如 RAG 检索、工具调用、记忆管理），LangGraph4j 提供的是状态机驱动的流程拓扑定义能力，而“低代码”真正的价值，在于把这两者之间那层厚重的胶水——即业务规则映射、异常分支收敛、人机协同断点、审计日志埋点——全部沉淀为可配置、可复用、可版本化的元数据模型。你看到的“拖拽节点”，背后其实是 YAML 描述的 StateGraph Schema + Java 注解驱动的 Component Binding + Spring Boot 自动装配的 Runtime Executor。这不是炫技，而是把过去需要 3 天写死的审批流逻辑，压缩到 20 分钟内完成配置上线，并且能经受住每秒 800+ 并发请求的压测考验。关键词LangChain4j、LangGraph4j、低代码、工作流、智能体，每一个词在这里都不是孤立概念：LangChain4j 是能力底座，LangGraph4j 是流程引擎，低代码是交付形态，工作流是业务表达，智能体是运行实体。它适合两类人深度参考：一是正在选型企业级 AI 应用平台的技术负责人，需要看清底层架构是否具备生产级稳定性与扩展性；二是想摆脱“写死 Agent”的初级开发者，需要理解如何用声明式方式构建可维护、可观测、可灰度的智能体系统。下面我会拆解这套架构为什么必须这样设计，而不是简单套用官方 QuickStart 示例。

2. 架构设计核心思路：为什么放弃纯 LangChain4j 链式调用，也绕开 LangGraph4j 原生 Python 风格？

2.1 纯链式调用在真实业务中必然崩塌的三个硬伤

我最早用 LangChain4j 写过一个“合同条款审查 Agent”，流程是：加载 PDF → OCR 提取文本 → 分段 → RAG 检索条款库 → LLM 判定合规性 → 生成报告。表面看是标准 Chain，但上线后立刻暴露问题：

状态不可控：当 OCR 失败时，整个 Chain 就卡死，没有重试机制、没有降级路径、无法跳过该环节继续后续分析。LangChain4j 的Runnable链是线性执行模型，错误传播是单向的，你无法在第 3 步失败后，让第 5 步基于第 2 步的缓存结果继续执行。
上下文爆炸：每次调用都携带完整 MessageHistory，当一个工单处理涉及 7 轮人机交互+3 次外部 API 调用+2 次数据库查询时，MessageHistory 对象体积轻松突破 12MB，序列化/反序列化耗时占到总响应时间的 63%。这不是理论值，是我们在某省政务平台实测的 JFR 采样数据。
调试黑盒化：Chain 执行过程像一条隧道，你只能看到输入和最终输出，中间每个 Runnable 的输入输出、耗时、错误堆栈全被封装在RunnableLambda内部，无法在 Grafana 里单独监控“RAG 检索耗时”或“工具调用成功率”。

提示：LangChain4j 的Runnable设计哲学是函数式组合，它追求的是“一次成功”，而非“持续演进”。这在 PoC 阶段很优雅，但在需要 99.95% 可用率的生产环境里，就是定时炸弹。

2.2 为什么不用 LangGraph4j Python 版本直接移植？

LangGraph4j 是 LangGraph 的 Java 实现，但它不是简单翻译。Python 版本依赖asyncio和yield构建生成器式状态流转，而 Java 生态的异步模型（Project Reactor / CompletableFuture）与之存在根本性差异。我们曾尝试用 Project Reactor 模拟yield行为，结果发现：

状态快照成本失控：Python 中yield可以自然暂停协程并保存局部变量，Java 中要实现等效效果，必须手动序列化整个 State 对象。我们测试过将一个含 5 个 Map<String, Object> 字段的 State 序列化为 JSON，平均耗时 8.3ms，而一个典型工作流平均需 17 次状态快照，仅序列化就吃掉 141ms，远超业务容忍阈值（<200ms）。
调试体验断层：Python 的graph.invoke()返回一个可遍历的 generator，你可以next()逐帧查看状态；Java 的StateGraph#invoke()返回Mono<State>，你只能订阅 onComplete 或 onError，无法在 IDE 里像调试普通方法一样 Step Into 每个节点。
生态割裂严重：Python 版本天然集成 LangChain、LlamaIndex、Docker Compose 编排；Java 版本必须对接 Spring Boot Actuator、Micrometer、Logback MDC，而 LangGraph4j 官方文档对这些集成只字未提，所有适配都要自己造轮子。

注意：LangGraph4j 的价值不在于“复刻 Python”，而在于提供一套符合 JVM 生态习惯的状态机抽象。它的State接口强制你定义明确的字段，Node接口要求你声明输入/输出类型，Edge规则支持Condition函数式判断——这才是企业级开发真正需要的契约精神。

2.3 “低代码”不是降低技术门槛，而是提升业务语义表达精度

很多人误解“低代码”等于“无代码”或“可视化编程”。在这套架构里，“低代码”体现在三个层级：

配置层：用 YAML 定义 StateGraph 结构，包括节点名称、类型（tool_call,llm_invoke,human_input）、输入字段映射、输出字段绑定、条件边规则。例如一个“销售线索评分”节点，YAML 描述如下：
```
nodes: - name: "score_lead" type: "llm_invoke" input_mapping: lead_info: "$.lead_data" scoring_rules: "$.config.scoring_rules" output_mapping: score: "$.output.score" reason: "$.output.reason" llm_model: "qwen2.5-7b-chat"
```
编排层：通过@WorkflowComponent注解标记 Java 类，自动注册为可被 YAML 引用的节点实现。注解参数指定该组件支持的输入/输出 Schema、超时时间、重试策略、熔断阈值。例如：
```
@WorkflowComponent( id = "salesforce_sync", inputSchema = "LeadSyncInput", outputSchema = "LeadSyncResult", timeoutSeconds = 30, maxRetries = 2, circuitBreakerEnabled = true ) public class SalesforceSyncComponent { ... }
```
运行时层：Spring Boot 启动时扫描所有@WorkflowComponent，构建ComponentRegistry；加载 YAML 时解析为StateGraphDefinition；运行时根据当前 State 动态查找匹配的 Component 实例，注入其依赖（如RestTemplate,JdbcTemplate），执行并捕获结构化异常（ComponentExecutionException）。整个过程对业务开发者透明，他只需关注“这个节点该做什么”，无需关心“怎么调度、怎么容错、怎么埋点”。

这种设计让业务专家能用 Excel 描述工作流逻辑（节点、条件、数据流向），技术团队只需将 Excel 转为 YAML 并实现对应 Component，交付周期从 2 周缩短至 2 天。

3. 核心模块深度拆解：从 State 定义到 Runtime 执行的全链路实操

3.1 State 设计：不是万能 Map，而是带契约的强类型容器

LangGraph4j 的State接口看似简单，但实际使用中极易陷入“Map<String, Object> 泛滥”的陷阱。我们强制推行三原则：

字段必须显式声明：继承BaseState抽象类，每个业务字段用@StateField注解标记，并指定required = true/false、defaultValue、validator。例如：

public class ContractReviewState extends BaseState { @StateField(required = true) private String contractId; @StateField(required = false, defaultValue = "draft") private String status; @StateField(validator = "validateRiskScore") private BigDecimal riskScore; // validator 方法必须是 static，接收字段值和当前 State public static boolean validateRiskScore(BigDecimal score, ContractReviewState state) { return score != null && score.compareTo(BigDecimal.ZERO) >= 0 && score.compareTo(new BigDecimal("100")) <= 0; } }

状态变更必须原子化：禁止直接state.setXXX()，所有修改必须通过StateUpdater接口。我们提供ImmutableStateUpdater实现，每次更新返回新 State 实例，旧 State 保留用于审计回溯。例如：

public class ContractReviewStateUpdater implements StateUpdater<ContractReviewState> { @Override public ContractReviewState update(ContractReviewState oldState, Map<String, Object> updates) { // 使用 Builder 模式创建新实例，确保不可变性 return ContractReviewState.builder() .contractId(updates.get("contractId") != null ? (String) updates.get("contractId") : oldState.getContractId()) .status((String) updates.getOrDefault("status", oldState.getStatus())) .riskScore((BigDecimal) updates.getOrDefault("riskScore", oldState.getRiskScore())) .build(); } }

状态序列化必须可控：重写toString()为 JSON 格式，但排除敏感字段（如apiKey,password）；equals()和hashCode()基于业务关键字段计算，避免因日志字段差异导致状态误判。我们用 Jackson 的@JsonIgnore和自定义EqualsBuilder实现。

实操心得：State 设计阶段多花 2 小时，后期调试能省 20 小时。我们曾因一个List<Map<String, Object>>字段未加@StateField，导致状态快照序列化时出现循环引用，服务启动失败。后来强制要求所有 State 类必须通过StateValidator单元测试，验证字段声明完整性、默认值合理性、校验器有效性。

3.2 Node 实现：从“功能函数”到“可治理组件”的跃迁

LangGraph4j 的Node接口只有一个apply(State)方法，但生产环境需要更多契约：

输入/输出 Schema 显式化：每个 Node 必须声明inputSchema和outputSchema，我们用 JSON Schema 文件定义，并在@WorkflowComponent注解中引用。Spring Boot 启动时校验 YAML 中的input_mapping是否与 Schema 匹配。例如salesforce_sync的 inputSchema：
```
{ "type": "object", "properties": { "leadId": {"type": "string"}, "contactName": {"type": "string"}, "email": {"type": "string", "format": "email"} }, "required": ["leadId", "contactName"] }
```
执行上下文精细化：Node.apply()不再是裸 State，而是ExecutionContext对象，包含：
- State state：当前状态
- NodeConfig config：该节点的运行时配置（超时、重试、熔断）
- ComponentContext context：Spring 上下文，可获取BeanFactory
- AuditTrail auditTrail：审计追踪对象，自动记录执行时间、耗时、输入摘要、输出摘要、异常堆栈
- MetricsRecorder metrics：指标记录器，自动上报node_execution_count,node_execution_duration_seconds
异常分类治理：Node 执行抛出的异常必须继承WorkflowException，分为三类：
- BusinessException：业务规则拒绝（如“客户余额不足”），应返回给前端提示用户
- TechnicalException：技术故障（如 DB 连接超时），触发重试或降级
- FatalException：不可恢复错误（如 ClassNotFound），立即终止工作流并告警

我们提供@Retryable注解，自动包装 TechnicalException 并按配置重试，无需 Node 内部处理。

注意：Node 不是“函数”，而是“服务契约”。它的职责是“根据输入，产生确定性输出”，所有副作用（DB 写入、消息发送）必须通过SideEffectExecutor统一管理，确保状态变更与副作用解耦。这是实现幂等性的基础。

3.3 Edge 条件引擎：用 SpEL 表达式替代硬编码 if-else

LangGraph4j 的ConditionalEdge允许传入Function<State, String>作为条件判断，但我们发现硬编码函数难以维护。于是构建了 SpEL（Spring Expression Language）驱动的条件引擎：

YAML 中定义条件边：

edges: - source: "review_contract" target: "send_to_legal" condition: "#state.riskScore > 80 and #state.status == 'pending'" - source: "review_contract" target: "auto_approve" condition: "#state.riskScore <= 30" - source: "review_contract" target: "request_human_review" condition: "true" # default fallback

运行时解析 SpEL 表达式，编译为Expression对象缓存，避免每次执行都解析字符串。我们扩展了 SpEL 的EvaluationContext，注入常用工具类：
- DateUtils：日期计算
- StringUtils：字符串处理
- JsonPathUtils：JSONPath 查询（用于解析嵌套 JSON 字段）
- CustomFunctions：业务自定义函数（如isHighRiskIndustry(industryCode)）
条件执行结果自动记录到AuditTrail，包括表达式原文、求值结果、耗时。当条件判断失败时（如字段不存在），抛出ConditionEvaluationException，附带详细上下文，便于排查。

实操心得：SpEL 条件比硬编码灵活 10 倍，但性能差 3 倍。我们通过两级缓存优化：一级缓存Expression编译结果（key 为表达式字符串），二级缓存Expression.getValue()的执行结果（key 为expression+stateHash），实测将条件判断平均耗时从 12ms 降至 1.8ms。

3.4 Runtime 执行器：从 Mono 到可中断、可回滚、可审计的事务流

LangGraph4j 的StateGraph#invoke()返回Mono<State>，但这只是 Reactive Stream 的起点。我们构建了WorkflowExecutor，它是一个有状态的、可中断的执行器：

执行生命周期管理：
- start()：初始化 ExecutionId、开始时间、设置初始 State
- step()：执行单步（一个 Node），返回StepResult（包含新 State、是否结束、下一步目标）
- pause()：保存当前 State 到 Redis，释放线程，等待人工干预或定时唤醒
- resume()：从 Redis 加载 State，继续执行
- rollback()：按执行历史逆序调用CompensateAction，回滚已执行的副作用（如撤销已发邮件、删除已建工单）
线程模型隔离：每个 Workflow 实例绑定独立VirtualThread（Java 21），避免阻塞主线程。Node 执行时，VirtualThread自动继承MDC上下文，日志自动带上executionId和nodeId。
审计日志结构化：每步执行生成WorkflowAuditEvent，包含：
- executionId: UUID
- nodeId: 当前节点 ID
- stepNumber: 步骤序号
- startTime/endTime: 时间戳
- inputSummary: 输入字段摘要（脱敏后 JSON）
- outputSummary: 输出字段摘要
- error: 异常信息（仅 Business/Technical 异常，Fatal 不记录）
- metrics: 耗时、重试次数、API 调用数

该事件被异步发送到 Kafka，由 Flink 实时计算 SLA 达标率、节点瓶颈分布、人工干预频次等。

提示：WorkflowExecutor是整套架构的“心脏”。我们花了 3 周重写 LangGraph4j 的StateGraph，核心是替换其内部Mono链式调用为WorkflowExecutor的状态机驱动。这让我们能精确控制每一步的超时、重试、熔断，而不仅是整个工作流的超时。

4. 实操全流程：从零搭建一个“简历筛选智能体”工作流

4.1 需求分析与 State 定义

客户需求：HR 上传 PDF 简历，系统自动提取关键信息（姓名、电话、邮箱、工作经验年限、技能关键词），匹配 JD 要求，给出匹配度评分和理由，支持 HR 人工复核并覆盖结果。

State 字段设计：
- resumeId(String, required): 简历唯一标识
- pdfBytes(byte[], required): PDF 原始字节（仅首步使用，后续步骤清空以节省内存）
- extractedText(String, optional): OCR 提取的纯文本
- parsedInfo(ResumeInfo, optional): 解析后的结构化信息
- jdRequirements(JdRequirements, required): 职位 JD 要求（从配置中心加载）
- matchScore(BigDecimal, optional): 匹配度分数（0-100）
- matchReason(String, optional): 匹配理由摘要
- reviewStatus(String, enum: "pending", "approved", "rejected", "manual"): 人工复核状态
- reviewerComment(String, optional): 人工评论
State 校验器：
- parsedInfo非空时，parsedInfo.experienceYears必须 ≥ 0
- matchScore在 0-100 之间
- reviewStatus为 "manual" 时，reviewerComment必须非空

4.2 YAML 工作流编排（resume_screening.yaml）

name: "resume_screening_workflow" description: "自动简历筛选与人工复核工作流" initial_state: "upload_resume" nodes: - name: "upload_resume" type: "human_input" input_mapping: resumeId: "$.resumeId" pdfBytes: "$.pdfBytes" output_mapping: resumeId: "$.resumeId" pdfBytes: "$.pdfBytes" - name: "ocr_extract" type: "tool_call" tool_id: "pdf_ocr_tool" input_mapping: pdfBytes: "$.pdfBytes" output_mapping: extractedText: "$.output.text" - name: "parse_resume" type: "llm_invoke" llm_model: "qwen2.5-7b-chat" system_prompt: | 你是一个专业的简历解析助手。请从以下文本中提取：姓名、电话、邮箱、工作经验年限（精确到年）、技能关键词（最多5个，用逗号分隔）。 输出格式为 JSON，字段名严格为：name, phone, email, experienceYears, skills。 input_mapping: text: "$.extractedText" output_mapping: parsedInfo: "$.output" - name: "calculate_match_score" type: "llm_invoke" llm_model: "qwen2.5-7b-chat" system_prompt: | 你是一个招聘匹配度评估专家。请根据职位要求和候选人信息，计算匹配度分数（0-100）并给出简明理由。 职位要求：{{jdRequirements}} 候选人信息：{{parsedInfo}} 输出格式：{"score": 85.5, "reason": "3年Java经验匹配，熟悉Spring Boot，但缺少云原生经验。"} input_mapping: jdRequirements: "$.jdRequirements" parsedInfo: "$.parsedInfo" output_mapping: matchScore: "$.output.score" matchReason: "$.output.reason" - name: "auto_decision" type: "condition" conditions: - target: "send_to_hr" expression: "#state.matchScore >= 70" - target: "reject_candidate" expression: "#state.matchScore < 50" - target: "manual_review" expression: "true" - name: "send_to_hr" type: "tool_call" tool_id: "notify_hr_tool" input_mapping: resumeId: "$.resumeId" matchScore: "$.matchScore" matchReason: "$.matchReason" - name: "reject_candidate" type: "tool_call" tool_id: "notify_candidate_tool" input_mapping: resumeId: "$.resumeId" reason: "匹配度不足" - name: "manual_review" type: "human_input" input_mapping: resumeId: "$.resumeId" parsedInfo: "$.parsedInfo" matchScore: "$.matchScore" matchReason: "$.matchReason" output_mapping: reviewStatus: "$.reviewStatus" reviewerComment: "$.reviewerComment" edges: - source: "upload_resume" target: "ocr_extract" - source: "ocr_extract" target: "parse_resume" - source: "parse_resume" target: "calculate_match_score" - source: "calculate_match_score" target: "auto_decision" - source: "auto_decision" target: "send_to_hr" condition: "#state.matchScore >= 70" - source: "auto_decision" target: "reject_candidate" condition: "#state.matchScore < 50" - source: "auto_decision" target: "manual_review" condition: "true" - source: "send_to_hr" target: "end" - source: "reject_candidate" target: "end" - source: "manual_review" target: "end"

4.3 关键 Component 实现（精简版）

PDF OCR Tool (pdf_ocr_tool)：

@WorkflowComponent(id = "pdf_ocr_tool", inputSchema = "PdfOcrInput", outputSchema = "PdfOcrOutput") public class PdfOcrTool { private final Tesseract tesseract; // Apache Tika + Tesseract 集成 public PdfOcrOutput execute(PdfOcrInput input) { try { String text = tesseract.doOCR(input.getPdfBytes()); return new PdfOcrOutput(text); } catch (TesseractException e) { throw new TechnicalException("OCR failed", e); } } }

Notify HR Tool (notify_hr_tool)：

@WorkflowComponent(id = "notify_hr_tool", inputSchema = "NotifyHrInput", outputSchema = "NotifyHrOutput") public class NotifyHrTool { private final RestTemplate restTemplate; private final String hrApiUrl; public NotifyHrOutput execute(NotifyHrInput input) { HttpHeaders headers = new HttpHeaders(); headers.setContentType(MediaType.APPLICATION_JSON); HttpEntity<NotifyHrRequest> request = new HttpEntity<>( new NotifyHrRequest(input.getResumeId(), input.getMatchScore(), input.getMatchReason()), headers ); try { ResponseEntity<NotifyHrResponse> response = restTemplate.postForEntity( hrApiUrl, request, NotifyHrResponse.class ); return new NotifyHrOutput(response.getBody().getNotificationId()); } catch (HttpClientErrorException e) { throw new BusinessException("HR notification failed: " + e.getStatusCode()); } } }

Human Input Node：这是一个特殊 Node，它不执行逻辑，而是将当前 State 序列化为 JSON，存入 Redis 的workflow:pendingHash，生成一个带 JWT Token 的审核链接（如https://hr.example.com/review?token=xxx），并通过邮件发送给 HR。HR 点击链接后，前端加载该 State，渲染表单，提交后触发WorkflowExecutor.resume()。

4.4 运行时部署与可观测性配置

Spring Boot 配置 (application.yml)：

workflow: executor: max-concurrent: 50 # 最大并发工作流数 step-timeout: 30s # 单步超时 global-retry: 2 # 全局重试次数 state: cache-ttl: 24h # State 缓存 TTL audit: kafka-topic: workflow-audit-events batch-size: 100 # 审计日志批量发送 langchain4j: llm: qwen2.5-7b-chat: model-name: "qwen2.5-7b-chat" base-url: "http://llm-gateway:8000/v1" api-key: "${LLM_API_KEY}" timeout: 60s

Grafana 监控面板：
- 全局概览：工作流总数、成功率、平均耗时、各节点耗时占比饼图
- 节点下钻：点击calculate_match_score，查看其 P95 耗时趋势、错误率、调用 LLM 的 token 使用量
- 执行链路追踪：输入executionId，展示完整执行路径，高亮慢节点、失败节点、人工干预点
- 人工复核看板：待复核数量、平均复核时长、HR 处理效率排名
日志规范：
- 所有WorkflowAuditEvent写入 Loki，标签为job="workflow-executor",executionId,nodeId
- Node 执行日志使用logback-spring.xml配置 MDC，自动添加executionId和nodeId
- 错误日志必须包含executionId和stackTrace，便于关联审计日志

实操心得：部署后第一周，我们发现ocr_extract节点 P95 耗时高达 8.2s，远超预期。通过 Grafana 下钻发现，是 Tesseract 初始化耗时占了 7.5s。解决方案：将 Tesseract 实例预热为 Spring Bean，@PostConstruct中调用doOCR空字符串触发初始化。优化后 P95 降至 0.3s。这印证了“可观测性不是锦上添花，而是定位根因的唯一途径”。

5. 常见问题与避坑指南：来自四个真实项目的血泪总结

5.1 State 内存泄漏：从 2GB 堆内存到 200MB 的优化之路

问题现象：某制造客户的工作流服务，运行 48 小时后 Full GC 频繁，堆内存占用稳定在 2GB，jmap -histo显示java.util.HashMap$Node占比 45%。

根因分析：我们检查了ContractReviewState，发现其auditTrail字段是一个List<AuditEvent>，而每个AuditEvent包含完整的inputSummary和outputSummaryJSON 字符串。由于工作流最长可达 120 步，auditTrail累积了大量重复的、未脱敏的原始数据。更致命的是，State实例被WorkflowExecutor的ConcurrentHashMap缓存，GC 无法回收。

解决方案：

强制脱敏：AuditEvent构造时，对inputSummary和outputSummary执行 JSONPath 提取关键字段（如$.leadId,$.score），丢弃其余内容。
审计分离：WorkflowExecutor不在内存中维护auditTrail，而是每步执行后，立即将AuditEvent发送到 Kafka，内存中只保留executionId和lastStepTime。
State 缓存 TTL：设置State在ConcurrentHashMap中的 TTL 为 10 分钟，超时自动清理。

效果：堆内存峰值降至 200MB，Full GC 消失。

注意：永远不要在 State 中存储原始二进制数据（如 PDF bytes、图片）或完整日志。State 是“决策上下文”，不是“数据仓库”。大文件必须存对象存储，State 中只存 URL 或 ID。

5.2 LLM 调用雪崩：当 100 个并发请求同时打向同一个 LLM API

问题现象：某金融客户上线后，高峰期出现大量TimeoutException，LLM 服务端 CPU 100%，响应延迟飙升至 30s+。

根因分析：calculate_match_score节点使用qwen2.5-7b-chat模型，但未配置任何限流。100 个并发工作流同时进入该节点，瞬间发起 100 个 HTTP 请求到 LLM Gateway。

解决方案：

节点级限流：在@WorkflowComponent注解中增加rateLimit参数：
```
@WorkflowComponent( id = "calculate_match_score", rateLimit = "10/1s" // 每秒最多 10 次调用 )
```
我们基于 Resilience4j 实现，当超过阈值时，抛出RateLimitExceededException，触发WorkflowExecutor的降级逻辑（返回默认分数 50）。
模型级熔断：为每个 LLM 模型配置独立的CircuitBreaker，连续 5 次失败后熔断 30 秒，期间所有请求快速失败。
请求合并：对于相同jdRequirements和相似parsedInfo的请求，启用@Cacheable，缓存 LLM 输出（需注意缓存键包含jdRequirements的哈希值）。

效果：LLM 调用成功率从 62% 提升至 99.8%，平均延迟稳定在 1.2s。

提示：LLM 不是传统 API，它的吞吐量和延迟波动极大。必须把它当作“脆弱依赖”来治理，而不是“稳定服务”。

5.3 条件边失效：SpEL 表达式中的隐式类型转换陷阱

问题现象：auto_decision节点的条件#state.matchScore >= 70总是走manual_review分支，即使matchScore是85.5。

根因分析：matchScore字段在 State 中定义为BigDecimal，而 SpEL 表达式70是Integer。BigDecimal与Integer比较时，SpEL 默认调用BigDecimal.compareTo(Integer)，但BigDecimal没有接受Integer的compareTo方法，导致比较结果为null，条件判断失败。

解决方案：

显式类型转换：在 YAML 中写为#state.matchScore.compareTo(new java.math.BigDecimal('70')) >= 0
统一数值类型：在 State 定义中，所有数值字段统一用Double（牺牲精度换取兼容性），或在 SpEL 中强制转换：#state.matchScore.doubleValue() >= 70
条件校验工具：开发SpelValidator工具类，在 YAML 加载时静态分析所有表达式，检测潜在类型不匹配。

效果：条件判断 100% 准确，且SpelValidator成为 CI/CD 流水线的必检项。

实操心得：SpEL 很强大，但它的类型系统是动态的，容易在运行时才暴露问题。务必在本地单元测试中覆盖所有条件分支，用Mockito模拟各种 State 值。

5.4 人工复核中断：HR 关闭浏览器后工作流永久挂起

问题现象：HR 打开审核链接，未操作直接关闭浏览器，该工作流executionId永远停留在manual_review状态，既不超时也不失败。

根因分析：human_input节点将 State 存入 Redis 后，就认为“任务已交出”，没有设置超时监听。Redis 中的workflow:pendingHash 项永远不会过期。

解决方案：

Redis 过期键：human_input节点存入 Redis 时，设置EXPIRE为 24 小时。
后台巡检任务：Spring Boot 启动@Scheduled任务，每 5 分钟扫描workflow:pending，找出lastUpdate超过 2 小时的项，触发WorkflowExecutor.rollback()或WorkflowExecutor.forceEnd()。
前端心跳：HR 页面加载后，启动 WebSocket 心跳，服务端收到心跳则刷新 Redis 过期时间。

效果：无人工干预的工作流，最长挂起 2 小时后自动超时，通知管理员介入。