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

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

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

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

## 1. 核心技术决策

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

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

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

## 2. 部署与系统职责

```mermaid
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
```

| 组件 | 选型与责任 |
| --- | --- |
| Python API | FastAPI + Pydantic，校验输入、登记任务、读取结果、输出业务事件流 |
| 图运行 | LangGraph，自定义状态与节点；异步模型和 HTTP 调用 |
| 业务连接 | httpx 访问 Java 内部 Bridge；有限连接池、明确超时、只读重试 |
| 检查点 | `langgraph-checkpoint-postgres` 的异步持久化实现；初始化/迁移在发布任务执行 |
| 任务记录 | 独立 PostgreSQL 保存任务、方案、事件、执行记录；业务库继续使用现有 MySQL |
| 队列 | Redis Streams + consumer group；PostgreSQL outbox 保证提交任务后可补发，Redis 不作为唯一任务事实源 |
| 定时触发 | 优先复用项目现有 Quartz，发送场景事件；企业班次/节假日配置决定时间 |
| 文档 | 复用附件与知识库；大文件在对象存储，检查点仅存引用与摘要 |
| 可观测 | 结构化日志、trace_id、节点耗时、工具调用审计、指标；外部追踪平台按部署要求选配 |

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

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

## 3. 主图设计

```mermaid
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. 九个业务子图与复用节点

| 场景子图 | 核心节点顺序 | Java 领域依赖 | 主要新增内容 |
| --- | --- | --- | --- |
| `order_review` | 订单上下文 → 齐套 → 产能模拟 → 交期比较 → 评审方案 | CRM 合同、ERP 销售单、MPS/工单、库存、排程 | 订单行关联聚合、承诺日计算、影响订单列表 |
| `material_readiness` | 工单范围 → BOM 与物料映射 → 可用库存/在途 → 确定性分配 → 缺口合并 | MDM、MES BOM/WMS、ERP 采购、SRM | 跨工单分配策略、催交回执与净缺口快照 |
| `progress_patrol` | 计划基线 → 有效报工 → 日历/暂停记录 → 逾期计算 → 责任归口 | 工单/任务/报工、排班、HRM | 连续超期检测、待办去重与升级 |
| `reschedule` | 资源快照 → 当前方案 → 插单预览 → 影响差异 → 提交候选方案 | MES 排程、设备、班组、ERP/CRM | 多方案快照、审批与版本再验证 |
| `shipment_check` | 销售行 → 出库/库存/装箱 → OQC/冻结 → 可发量 → 阻断报告 | ERP、MES-WM、MES-QC | 发货前聚合视图 |
| `quality_containment` | 检验规则版本 → 越限判定 → 批次流转 → 影响面 → NCR/复验方案 | IQC/IPQC/OQC/RQC、NCR、库存 | 检验设备接入、隔离及停复线审批流程 |
| `equipment_patrol` | 计划窗口 → 有效记录 → 维修去重 → 工单影响 → 补检/保养方案 | 设备、点检/保养、维修、排班 | 可验证的机时采集、关键设备排序 |
| `outsource_reconciliation` | 外协单 → 发收退料/IQC → 合同版本 → 数量价差 → 核实清单 | 外协仓储、ERP、SRM | 合同损耗率、加工费口径与差异处理 |
| `complaint_trace` | 售后/批号解析 → 反向追溯 → 正向影响 → 报告附件 → 回复草稿 | 售后、CRM、ERP、批次/SN、质检报告 | 跨模块关系补全与证据断点任务 |

子图用独立 input/output schema，通过包装节点转换父子状态。默认采用每次调用独立的子图状态，继承父图检查点；不让不同订单共享领域消息历史。批量巡检可用 `Send` 分发独立工单，结果按对象键聚合，明确分页和并发上限。子图持久化模式及父图关系见 [Subgraphs](https://docs.langchain.com/oss/python/langgraph/use-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 校验；消息只保存必要的人机往来。

| 字段 | 类型/含义 | 合并策略 |
| --- | --- | --- |
| `task_id / case_id / graph_version` | 执行任务、业务案件、图版本 | 单一协调节点写 |
| `scenario_id / business_refs` | 场景与对象引用 | 验证后固定，修改需新方案版本 |
| `time_window / rule_versions` | 本次计算范围与规则版本 | 单一写入 |
| `snapshot_refs` | 各工具结果的存储引用、业务版本、采集时间 | 按 source_key 合并 |
| `evidence` | 证据 ID、来源对象、字段摘要、可信程度 | 按 evidence_id 去重合并；同 ID 冲突报错 |
| `findings` | 确定事实、推断、缺口与风险 | 按 finding_id 合并 |
| `proposal_ref` | 不可变动作方案 ID、版本、hash | 单一节点写入 |
| `approval_ref / command_refs` | BPM 实例与命令记录引用 | 按业务键去重 |
| `result_ref / status / errors` | 输出产物与任务状态 | 状态机控制 |

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

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

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

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

```text
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`，需要先核对编译依赖图。

```json
{
  "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](https://docs.langchain.com/oss/python/langgraph/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. 数据表与持久化边界

| Agent 自有表 | 核心用途/约束 |
| --- | --- |
| `agent_case` | 业务案件及关联对象、当前处理阶段 |
| `agent_task` | case/thread 映射、图版本、租约、状态；同任务单执行者 |
| `agent_run` | 每次执行/恢复的输入摘要、起止时间、错误与成本 |
| `agent_snapshot` | 数据来源、版本、采集时间、完整度、对象存储引用 |
| `agent_proposal` | 不可变方案版本、参数 hash、有效期 |
| `agent_command` | 命令 ID、幂等键、请求 hash、远端结果；执行权威结果在 Java |
| `agent_inbox / agent_outbox` | 可靠事件接收与发送；事件 ID 唯一 |
| `agent_followup` | 下次复查与升级条件、关闭原因 |
| `agent_ui_event` | 有序界面事件、SSE 重连游标 |
| 框架检查点表 | 由固定版本 saver 管理，不手工伪造或修改状态 |

Checkpointer 保存线程执行状态；跨任务的偏好与受审核知识可以使用 Store 或应用数据表，并按租户/用户命名空间隔离。实时库存、已变更审批、客户信用等事实每次重新查询，不从聊天记忆当作当前真值。[Checkpointers](https://docs.langchain.com/oss/python/langgraph/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](https://docs.langchain.com/oss/python/langgraph/streaming)

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

```text
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 是否覆盖催交/停复线等新流程；委外价格损耗与机时来源；各岗位动作授权。以上影响接口与上线范围，不妨碍先完成图、工具和数据契约设计。