MOM 工业智能体：LangGraph 定制技术方案

设计版本：v1，2026-10-21。阶段：技术方案评审，尚未实施。
业务范围承接 全模块设计 与 九场景蓝图。本方案确定使用 Python + LangGraph；具体依赖版本在实施时完成兼容验证后写入锁文件。

新增并列核心能力：企业工作文件理解与多轮补录。协调主图增加 document_onboarding 路由，补录暂存、字段证据、多轮人工修订、依赖导入与对账作为专用子图。实施顺序调整为先完成主数据补录闭环，再逐步联动运营场景；期初与历史迁移采用专门业务接口。

统一授权详见 菜单、按钮与数据权限方案：主图增加能力加载与计划授权节点，所有查询/操作复用 Java 当前用户权限；模型可用工具、字段、产物与恢复过程均受约束。

1. 核心技术决策

采用独立 Python 项目 mom-industrial-agent，以 LangGraph StateGraph 编排业务流程。设计为**协调主图 + 九个场景子图 + 全模块领域工具 + 统一命令执行通道**。查询、计算、建议与执行有明确节点和数据契约。

LLM 负责自然语言意图、业务对象消歧、文档解释、证据总结和候选行动；库存可用量、金额、工序约束、检验规则、权限与审批结论由确定性代码及 Java 业务服务负责。模型输出必须经过结构校验和领域策略校验，才能成为工具输入。

主图采用明确路由；场景子图以预定义流程为主。仅在知识检索或原因分析节点中允许有预算的动态工具循环。框架支持用状态、节点和边表达这种流程，节点可以执行普通计算或模型调用。LangGraph Graph API

2. 部署与系统职责

flowchart TB
    UI[现有 Vue / 移动端] --> GW[Java Agent 网关：身份与数据范围]
    GW --> API[Python FastAPI：任务入口 / SSE]
    API --> DB[(Agent PostgreSQL：任务与检查点)]
    API --> Q[Redis Streams：任务分发]
    Q --> W[LangGraph Worker]
    W --> GRAPH[协调图与场景子图]
    GRAPH --> MODEL[模型适配层]
    GRAPH --> KNOW[知识检索适配层]
    GRAPH --> BRIDGE[Java Agent Bridge：领域查询与命令]
    BRIDGE --> SVC[CRM / ERP / SRM / MES / HRM / BI / System]
    BRIDGE --> BPM[现有 BPM 审批]
    SVC --> MYSQL[(现有业务 MySQL)]
    SVC --> OUT[业务 Outbox]
    BPM --> OUT
    OUT --> EVENTS[事件接入 / 去重 / 路由]
    EVENTS --> Q
    GRAPH --> DB

这修订了早期“全部沿用 MySQL/Redis”的建议：LangGraph 生产检查点优先采用官方文档列出的 PostgreSQL 实现，减少自研检查点适配工作；开发可用 SQLite，内存检查点仅供单元测试。Persistence

API 与 Worker 可独立扩容。同一个业务任务只允许一个 Worker 持有执行租约；续租、fencing token 和命令幂等共同处理进程失联。Python 服务无需迁移 Java 业务数据，也不持有业务数据库写权限。

3. 主图设计

flowchart TD
    START([请求 / 业务事件]) --> AUTH[validate_context：核验身份与对象范围]
    AUTH --> INTENT[resolve_request：结构化意图与对象]
    INTENT --> CLEAR{对象和范围明确？}
    CLEAR -->|否| CLARIFY[clarify：interrupt 等待补充]
    CLARIFY --> INTENT
    CLEAR -->|是| ROUTE[route_scenario：白名单场景路由]
    ROUTE --> SUB[场景子图：取证 / 计算 / 校验]
    SUB --> CHECK[validate_evidence：完整度与新鲜度]
    CHECK -->|不足| PARTIAL[生成缺口报告]
    CHECK -->|充分| PROPOSE[构建结果与动作方案]
    PROPOSE --> POLICY{动作策略判定}
    POLICY -->|只读结果| PUBLISH[保存并发布结果]
    POLICY -->|需审批| SUBMIT[幂等登记方案与 BPM 申请]
    SUBMIT --> WAIT[await_approval：interrupt]
    WAIT --> RECHECK[重新核验审批 / 权限 / 数据版本]
    RECHECK -->|通过| EXEC[执行明确授权的命令]
    RECHECK -->|过期| SUB
    RECHECK -->|拒绝| REJECT[记录拒绝 / 关闭动作]
    POLICY -->|规则授权的内部待办| EXEC
    EXEC --> VERIFY[按命令号查询并验证结果]
    VERIFY --> PUBLISH
    PARTIAL --> PUBLISH
    REJECT --> PUBLISH
    PUBLISH --> END([结束本轮 / 登记后续事件订阅])

节点职责：

• validate_context：接受 Java 签发的限时用户委托或系统巡检身份；业务对象必须在当前范围内。身份与访问令牌不放入可持久化图状态。
• resolve_request：输出 scenario_id + business_refs + time_window + requested_action。对象歧义时产生待补充项，不能自行从同名客户中选择。
• route_scenario：按配置允许的场景与权限路由，模型不生成任意 Python 函数名或 URL。
• validate_evidence：判断数据缺失、来源冲突、单位不一致和快照过期；失败时可输出部分结果，但阻止相关写操作。
• POLICY：由代码按动作类型与用户授权判定审批要求；文本中出现“已批准”不能改变该结果。
• VERIFY：区分“命令已接收”“审批中”“单据已创建”“业务完成”；前端据此展示状态。

4. 九个业务子图与复用节点

子图用独立 input/output schema，通过包装节点转换父子状态。默认采用每次调用独立的子图状态，继承父图检查点；不让不同订单共享领域消息历史。批量巡检可用 Send 分发独立工单，结果按对象键聚合，明确分页和并发上限。子图持久化模式及父图关系见 Subgraphs。

全模块以领域工具包覆盖：mdm / crm / srm / erp / mes_pro / mes_wm / mes_qc / mes_dv / mes_cal / mes_energy / qcreport / aftersales / hrm / bpm / bi / system / infra / ai_knowledge。Archive、Finance、Research、UMS、WXCP 等先登记能力清单，核实实际接口后启用；IM/Member 默认关闭。经营问答、成本分析作为后续跨域图，复用同一工具层。

5. 状态与身份模型

不要把所有业务数据塞进 messages。图状态采用明确的业务字段，边界 DTO 使用 Pydantic 校验；消息只保存必要的人机往来。

并行节点仅返回自己负责的局部更新；共享结果字段配置 reducer，避免并行覆盖。同一条证据重放后不重复计数。状态保存 JSON 可序列化值与引用，禁止把连接池、HTTP 客户端、凭据、完整附件放进检查点。

conversation_id 是用户对话；case_id 是业务问题生命周期；task_id 对应一次完整图执行，作为 thread_id 的服务端映射；run_id 是一次运行或恢复尝试。一个对话可有多个案件和任务。审批恢复使用原 thread；定时复查建立新任务并关联原 case，避免旧图状态无限增长。

请求时的权限快照仅用于审计。每次查询、审批恢复和写入都由 Java 检查最新权限。恢复任务重新取得受控访问上下文，不依赖几天前已过期的登录 token。

6. 重点子图：齐套分析的真实计算口径

load_workorders
  → resolve_bom_and_units
  → fetch_material_snapshot（库存、冻结、占用、采购在途）
  → validate_snapshot
  → allocate_supply_across_orders
  → calculate_shortages
  → aggregate_by_material_and_supplier
  → explain_with_evidence
  → propose_expedite_tasks

一个批次巡检先统一加载物料供应快照，再按确定的工单优先级分配供应。逐工单独立读取同一库存会重复承诺同一批物料，因此不能简单并行计算后相加。优先级、替代料规则、计量单位和允许损耗必须版本化。

库存服务提供权威的可分配量及其口径。冻结与占用可能重叠，不能未经验证就重复扣减；也要区分本工单占用与其它工单占用、已领物料和在途预计到货。前期蓝图的简化净可用公式以本节为实施依据。

跨模块读取未必是同一个数据库事务快照，因此结果记录每个来源的版本与采集时间。仅将结果称作“截至某时点的评估”；执行领料或采购等动作时，由原业务事务重新校验，不把分析快照当库存锁。

7. 工具协议与 Java 对接

内部接口建议放在 yudao-module-ai 的 bridge 入口；调用各模块已有 Service/API，并补足缺失的只读聚合 API。公共 DTO 放在相应 *-api 模块，遵循现有 Maven 依赖方向，防止 AI 与 MES 相互依赖。大型接入可独立为 yudao-module-agent，需要先核对编译依赖图。

{
  "tool": "mes.material.readiness_snapshot",
  "schema_version": "1",
  "request_id": "uuid",
  "task_id": "uuid",
  "arguments": {"work_order_ids": [101, 102]},
  "response": {
    "data_ref": "snapshot-id",
    "source_versions": {"workorder:101": "revision"},
    "observed_at": "ISO-8601",
    "completeness": "partial",
    "missing": ["purchase_delivery_confirmation"]
  }
}

上例是契约形状示意，实际请求和响应分别传输。用户/租户身份来自服务端签发的委托上下文，不接受模型生成的身份字段。工具登记包括领域、读写级别、权限码、schema、超时、分页上限、可重试错误和敏感字段策略。

现有代码可利用的具体入口包括：

• MesProTaskController：POST /mes/pro/task/auto-schedule/preview 与 /auto-schedule。正式执行说明为重新校验预览并整批原子提交，接入时继续调用该业务规则。当前预览说明有 09–18 点及周末/节假日约束；夜班、多班与额外换型约束需扩展并验证。
• MesProAiController：四类生产预测，作为既有建议能力对接，确定性计算结果优先。
• MesProWorkOrderController：工单进度与计划查询；MesWmBatchController：前后向及工序追溯。
• 点检、维修、NCR、外协发料/入库、销售出库等控制器已有对象入口，需通过 Bridge 暴露最小字段集。

这些 HTTP 路径是源码中的 Controller 相对路径；部署的 /admin-api 等前缀、鉴权和数据范围须在联调中确认。Python 不通过超级管理员账号转发全部业务请求。

8. 审批恢复与业务幂等

LangGraph interrupt() 用于暂停等待，恢复使用同一 thread 下的 Command(resume=...)。恢复会从中断节点起点重跑，因此审批节点只读取已登记方案并发出中断，建单、发通知等副作用放在独立的幂等节点。不能用泛化异常捕获吞掉中断。Interrupts

完整流程：

1. prepare_proposal 冻结参数、业务版本、证据引用、有效期，生成 proposal_id + version + hash。
2. register_approval 通过 Java 幂等创建审批记录；事务提交后由 outbox 通知。
3. await_approval 中断并释放 Worker，不保持 HTTP 或数据库连接等待。
4. BPM 回调先落 inbox 去重，验证审批实例、动作 hash 与签署权限；若图尚未到中断点，事件保留等待，不能丢弃。
5. Worker 持有任务租约，读取对应 interrupt；用经过验证的审批记录引用恢复，禁止前端直接提交任意 resume 值。
6. revalidate 再查权限、审批撤销状态、参数 hash、对象版本和有效期。数据变更需重算，动作参数变更须重新审批。
7. execute_command 带稳定 command_id、幂等键和期望版本交给 Java。幂等键由场景、方案版本、动作类型及业务对象构成，同一批准动作重放时保持不变。
8. Java 在同一业务事务内登记命令结果与业务变更，唯一约束拦截重复请求；重试返回原业务单号。
9. 网络超时属于“结果未知”，按命令 ID 查询结果，不能直接当失败再建新单。回读成功后才向前端显示“已执行”。

检查点不提供外部系统的 exactly-once 保证。业务一致性依赖 Java 事务、命令去重、版本校验与对账补偿。跨模块长流程拆成可核对的命令序列；中途失败停止后续动作，补偿仅调用业务允许的撤销接口，并保留人工处理入口。

9. 事件、主动巡检与恢复

建议事件类型：sales.delivery_changed、purchase.delivery_confirmed、production.feedback_approved、quality.inspection_completed、equipment.repair_changed、warehouse.receipt_completed、bpm.approval_decided。名称为拟定契约，需要新增发布适配。

事件至少包含 event_id、event_type、aggregate_ref、aggregate_version、occurred_at、schema_version 和租户。业务事务写 outbox，异步发布；Python inbox 用事件 ID 去重，按对象版本处理乱序，按事件关联唤醒案件或启动复查。

定时器与事件接入负责发起/恢复图，LangGraph 本身不充当生产定时调度服务。等待期间不使用长时间 sleep。跟进记录含下次检查时间、责任人、截止时间、升级策略与停止条件；通知记录保存渠道回执，未变化的巡检结果不反复提醒。

10. 数据表与持久化边界

Checkpointer 保存线程执行状态；跨任务的偏好与受审核知识可以使用 Store 或应用数据表，并按租户/用户命名空间隔离。实时库存、已变更审批、客户信用等事实每次重新查询，不从聊天记忆当作当前真值。Checkpointers

图版本固定到任务，升级保留旧版本 Worker 直至挂起任务结束，或做经过测试的状态迁移。部署时不能随意重命名等待中的节点/删除状态字段。配置检查点与产物保留期，业务审计按企业要求单独留存。

11. 模型、知识与界面协议

模型网关按能力选择文本、结构化输出和视觉模型，密钥保留服务端。短期用现有 AiChatApi 适配自然语言说明；若其仅返回文本，则 Python 使用 JSON schema 校验并有限修复。需要原生工具调用时新增协议适配，不假设现有字符串接口已提供该能力。

知识检索传入领域、物料/产品、标准版本、生效日期和权限过滤。证据记录文档 ID、版本、页码/段落、附件引用；工艺变更按业务发生时间选有效版本。检索文档作为内容数据，不能改变工具权限或业务规则。

前端采用稳定的业务 SSE 协议：task_started、step_completed、evidence_added、result_ready、approval_required、command_submitted、command_verified、task_failed。前端不消费原始 checkpoint、内部 prompt 或完整工具返回。服务端将 LangGraph 流事件转换成上述协议并过滤权限；断线后按 event_id 补发。官方支持状态更新、消息及自定义流，选定版本后固定适配器并覆盖协议测试。Streaming

12. Python 工程目录与依赖策略

mom-industrial-agent/
  pyproject.toml / uv.lock
  src/mom_agent/
    api/                  # tasks、cases、results、SSE；内部事件接入
    runtime/              # Worker、租约、恢复、图版本注册
    graphs/
      coordinator.py
      scenarios/          # 九个场景 StateGraph
      shared/             # 证据校验、方案、审批、命令回读
    state/                # 父子图状态、reducer、schema 迁移
    domains/              # 覆盖所有实际业务模块的工具契约
    calculators/          # 齐套分配、工时、差异等可测试计算
    integrations/         # Java、模型、知识库、通知渠道
    policies/             # 权限需求、动作等级、预算、数据有效期
    persistence/          # PostgreSQL 检查点与应用表
    events/               # inbox/outbox、事件关联、跟进任务
    observability/        # 日志、指标、trace
  tests/unit/ contracts/ graph/ recovery/ scenarios/
  evaluations/            # 脱敏真实案例、基准结果与标注
  migrations/
  deploy/                 # 容器、配置示例、运行手册

Python 3.11+；依赖锁定 LangGraph、checkpoint-postgres、Pydantic、FastAPI、httpx、数据库驱动与模型适配包的兼容组合。只采用已验证所需 API；不自动跟随最新版本，不为初期方案引入额外多智能体框架。

13. 验收与实施拆分

第一包：图运行底座、Java 委托身份、只读工具、检查点、SSE、任务/事件表。通过“挂起后重启仍能恢复、同任务并发受控、越权隔离、事件不丢不重复”的验收。

第二包：齐套、工单巡检和交期评审三图。用脱敏真实工单对比人工基准；检验同批库存不被重复分配、冻结占用不被重复扣减、来源缺失不生成确定性承诺。

第三包：审批与写命令。覆盖回调先到/重复到、审批后业务变化、执行后网络断开、写成功但检查点未保存、审批撤销等故障注入；重跑不重复建单。

第四包：质量/追溯、设备、发货、委外；补充全模块查询图、经营问答与成本口径。场景开放前逐项核对真实数据与业务接口，不以存在 Controller 作为完整可用的证据。

完成标准：九场景各有节点图、输入输出契约、权限清单、人工边界、失败路径和真实样本；每个结果可追溯来源，每个动作可关联审批和业务单号。时延、模型成本和并发目标在真实数据规模压测后设定，不沿用宣传图中的耗时或交付周期。

14. 本轮已确定与后续评审点

已确定：Python 独立项目、LangGraph 自定义编排、主图与九场景子图、Java 保留业务执行与审批、生产持久化检查点、事件驱动跟进、证据卡输出。

后续评审：新增 PostgreSQL 的部署资源；首批模型与数据出域要求；现有 BPM 是否覆盖催交/停复线等新流程；委外价格损耗与机时来源；各岗位动作授权。以上影响接口与上线范围，不妨碍先完成图、工具和数据契约设计。