全业务工业智能体 Python 项目设计草案

状态：方案讨论稿；仅设计，尚未实施。目标是为本仓库建立独立的 Python 智能体服务，并通过受控接口覆盖实际业务链路。

九个业务场景的触发、取证、计算、结果、审批边界与仓库接入核对见场景蓝图。

框架已确定为 LangGraph；以 LangGraph 技术方案为工程实现依据，其中明确了检查点存储、图状态与审批恢复细节，并修订早期存储建议。

企业初次上线与日常补录新增核心主线：WPS 等工作文件分析、多轮核对与业务入库，与运营场景并列建设。

1. 项目定位与边界

本仓库以 Spring Boot 模块承载业务规则、权限、审批和数据，Python 项目负责跨模块理解、检索、分析、规划与建议。用户从现有前端或业务单据发起任务；Java 网关鉴权并提供工具接口；Python 智能体生成带证据的建议或待审批操作；所有业务写入仍经原有 Java 服务完成。

设计目标是“一个智能体平台 + 多个领域能力包 + 跨领域流程”，而不是为每个模块复制一个聊天机器人。平台先接入全部业务对象的**目录和只读能力**，再按风险逐步开放可审批的动作。目录覆盖不等于第一版就有完整的自动执行能力。

仓库依据

docs/project-business/data/modules.json 给出了 MDM、CRM、SRM、ERP、生产、仓储、质量、质检报告、设备、售后、HRM、BPM、AI 的业务对象与上下游。
yudao-module-ai 已有模型配置、知识库和 AiChatApi；CRM 报价 OCR、ERP 来票 OCR、MES 质检建议与四类生产预测已有调用点。新 Python 服务应对接或逐步迁移这些能力，避免双套答案与配置。
yudao-module-mes 有设备、点检、维修、工单、库存、检验等领域；yudao-module-bi 有仪表盘与图表配置。archive、finance、research、ums、wxcp 在当前源码中缺少可直接证明的管理端控制器，先放入能力目录，待逐一核实接口后开放。
im 与 member 模块虽有代码，现有业务地图将其列为主链路未消费或遗留能力。默认不把它们作为首批生产工具。

2. 总体架构

flowchart LR
    U[Vue / 移动端 / 单据按钮] --> J[Java 智能体网关]
    J --> P[Python FastAPI 智能体服务]
    P --> O[任务编排与状态机]
    O --> R[领域工具目录]
    O --> K[知识检索]
    O --> M[模型与规则 / 预测器]
    R --> J
    J --> B[现有 Java 业务 Service / API]
    B --> D[(业务库)]
    O --> A[(智能体会话 / 证据 / 审计)]
    O --> H[人工审批队列]
    H --> J

责任划分

层	职责	不承担
Java 智能体网关	现有登录态、RBAC、数据范围、业务 API 封装、审批与幂等写入	模型推理与跨域规划
Python 智能体服务	意图路由、工具计划、证据汇总、约束校验、建议生成、会话审计	直连并修改业务表、绕过 BPM
领域工具	结构化查询、计算、模拟与受控命令；每个工具声明权限、字段和版本	返回不受控的整库数据
知识层	SOP、工艺、质检规范、产品手册、制度等文档检索	把知识文档当作实时库存或审批状态
规则与模型层	确定性校验、预测模型、LLM 语言解释	让 LLM 决定硬性业务规则

关键请求上下文：user_id、部门/数据范围、tenant_id（即使当前关闭也保留字段）、task_id、trace_id、场景、业务对象引用和权限快照。Python 不可信任前端传入的权限声明；每次工具调用由 Java 服务端按当前用户重新鉴权。

3. 领域能力图谱

下表是**目标工具目录**，不是对现有接口均已可用的声明。每行先交付只读工具和引用链接，写动作另行进行接口与权限核实。

领域	首批只读能力	后续建议或审批动作
MDM 主数据	物料/SKU、计量单位、仓库、批次属性查询；编码消歧	主数据重复项修订建议
CRM 销售	客户、商机、报价、合同、回款计划、销售目标摘要	跟进建议、合同风险提示、报价草稿
SRM 供应商	供应商资质、招投标、交付与绩效查询	资质到期提醒、候选供应商比较
ERP 采购/销售/资金	采购申请与订单、来票付款、销售订单、收款状态	缺货采购建议、订单异常解释、对账候选项
MES 生产	MPS、工单、工序任务、报工、工艺路线、工单 BOM	缺料/工时/风险/交付预测整合，排程方案模拟
MES 仓储	库存维度、占用、冻结、批次/SN、出入库事务	调拨/补货建议，追溯链生成
MES 质量	IQC/IPQC/OQC/RQC、指标、缺陷、NCR	检验判定建议、异常归因、NCR 处置草稿
质检报告	模板版本、报告实例、冻结快照引用	报告缺口解释与生成前检查
设备/工装/排班/能耗	设备状态、点检/维修、工装、班组、能耗记录	维修优先级、设备风险、排班冲突建议
售后	工单、维修、退货、质检与退款回调状态	客诉归因、退货进度解释、处理草稿
HRM	人员可用性、排班、考勤与交接状态的最小必要摘要	人力缺口建议；薪酬数据默认不进入通用会话
BPM	流程实例、当前任务、审批轨迹、业务回调状态	待办解释、审批材料缺口提示；审批决定仍由审批人执行
BI	指标定义、仪表盘聚合结果	跨域经营解释、异常钻取、指标口径引用
AI/知识	现有模型与知识库、OCR/预测调用登记	统一模型网关、提示词版本与评估
System/Infra	用户可见范围、字典、附件引用、任务/审计日志	管理配置建议；高权限工具单独审批
Archive/Finance/Research/UMS/WXCP	建立模块清单、核实是否有业务 API	有实际接口与责任人后加入工具目录
IM/Member	保留兼容入口，不在默认业务助手搜索范围内	业务确认启用后再接入

跨域语义层统一使用 BusinessRef(module, object_type, id, code) 和业务事件关系，避免在提示词中拼接表名。优先连接“销售订单→MPS→工单→领料/报工→质检→入库/出库→回款/售后”等真实单据引用；没有确定关联时明确显示“待核实”，不靠名称猜测。

4. 三个首要跨模块场景

A. 订单交付风险

输入销售订单或合同编号。读取 CRM 合同、ERP 销售订单、MPS/工单/报工、库存占用、采购到货、设备停机、质检阻断与历史交付。确定性计算缺口和预计完成范围；模型说明主要风险、证据、下一步与责任岗位。输出是“风险卡 + 证据引用 + 可选处理方案”，排程或采购仅生成草稿。

B. 质量异常追溯

输入 IQC/IPQC/OQC/RQC/NCR 或批次号。沿供应商、来料、库存批次、工单工序、设备、检验指标、销售出库和售后链路追溯。输出影响批次/订单清单、时间线、已知与未知环节。任何库存冻结、返工、退货和报废动作进入原有审批流。

C. 经营与现场异常问答

用户提问“本周交付为何下降？”之类问题。先识别可访问的 BI 指标口径，再查聚合数据和相关单据，引用具体时间范围与来源。区分事实、计算结果与推测；没有足够数据时给出缺失清单。该入口可覆盖全部已接入模块，但仅返回用户可见的数据。

5. 智能体工作机制

接收任务 → 鉴权/识别业务对象 → 选用场景模板 → 规划只读工具
→ 并行取证 → 校验时间、单位、口径与关联 → 规则/预测计算
→ 生成带来源的答案/方案 → 如需写入则形成待审批命令
→ Java 再鉴权与业务校验 → BPM/人工确认 → 执行并回读结果

工具调用使用 JSON Schema/Pydantic 输入输出。每个工具登记：name、domain、read_or_write、permission、data_scope、timeout、schema_version、idempotency_key。查询默认分页与限时；跨域任务限制最大步骤、最大工具调用次数和成本。失败时返回已核实部分与缺失证据，不伪造结论。

输出统一为 answer、facts[]、inferences[]、unknowns[]、citations[]、risk_level、proposed_actions[]、approval_required。每条来源包含业务对象、接口版本、采集时间和可在原系统打开的链接。对于金额、库存、合格判定、审批权限等硬约束，以业务服务返回的规则和状态为准。

6. Python 项目结构（拟）

industrial-agent/
  pyproject.toml
  src/industrial_agent/
    api/                 # FastAPI 路由：会话、任务、审批草稿、健康检查
    core/                # 状态机、计划器、工具调度、上下文、审计
    contracts/           # Pydantic DTO 与版本化工具契约
    domains/             # mdm/crm/srm/erp/mes/qc/aftersales/hrm/bpm/bi ...
    workflows/           # 交付风险、质量追溯、跨域问答
    integrations/        # Java 网关、模型、知识库、事件总线适配器
    policies/            # 权限范围、敏感字段、审批门槛、预算
    evaluation/          # 场景样本、回归指标、结果标注
  tests/
  docs/

建议选用 Python 3.11+、FastAPI、Pydantic、httpx；任务状态与审计存储采用仓库现有 MySQL/Redis 体系，但使用独立 schema/表和服务账号，不直接修改业务表。模型适配层兼容已有 AI 模型配置，具体复用方式要在实施前核对认证与 API。RAG 可以先消费现有 AI 知识库能力，不预设再次部署向量库。

Java ↔ Python 契约草案

POST /agent/tasks：带业务对象引用与用户意图，返回 task_id。
GET /agent/tasks/{id}：流式或轮询获取状态、证据和结果。
POST /agent/tasks/{id}/proposals：生成结构化待审批命令；不直接写业务单据。
POST /agent/tasks/{id}/approve：由 Java 网关与 BPM 处理审批，不接受 Python 自报审批通过。
领域工具由 Java 网关暴露内部 API，返回最小字段集、权限过滤结果及 source_ref；内部通信使用服务认证，用户上下文由网关签发并限时。

7. 方案选择

方案	形态	优点	代价/适用情况
A：统一问答层	Python 服务只调只读工具和知识库	接入快、风险低，适合先做统一入口	很难覆盖审批与执行闭环
B：平台 + 领域能力包（推荐）	统一任务编排、领域工具、跨域工作流、分级审批	能逐步覆盖所有业务，又保留各模块规则	需要建设 Java 网关和工具契约
C：多自治智能体群	每个领域独立规划与协商	领域团队可独立演进	协调、审计、权限和结果一致性复杂，当前不宜直接作为首版

推荐 B 的第一阶段只读运行，保留未来从单一编排器发展为领域专长智能体的接口。选择方案时重点比较：想先解决的跨域任务、现有 Java API 的可复用程度、是否允许智能体提交审批草稿，以及上线期限。

8. 分阶段落地与验收

业务和接口盘点：逐模块标记“已验证 API / 需新增 API / 暂无业务入口”；绘制对象关系与权限边界。验收：每个目标工具都有业务负责人、来源接口、字段、数据范围和测试样例。
平台骨架：Python API、工具注册、任务状态机、审计、模型适配、只读 Java 网关。验收：越权请求被拒绝；故障可追踪到 trace_id；答案有来源链接。
横向覆盖：接入上述所有实际业务模块的只读目录与至少一个关键查询，未实现模块明确标记不可用。验收：模块能力清单可自动检查，不将空模块展示成已接入。
深度场景：优先交付风险与质量追溯，其次经营问答、采购协同、设备维护、售后闭环。验收：与人工基准结果比对事实正确率、关联准确率、漏报率和响应时延。
受控执行：只对经过业务评审的命令开放草稿/提交，经 Java 再鉴权、幂等校验与 BPM 审批后执行。验收：重复请求不重复建单；拒绝审批不产生业务写入；可按单据回放审计链。

首批评估集应包含缺料、重复库存占用、质检不合格、已存在维修单、跨部门越权、已撤销审批、数据过期、接口超时、关联断链等案例。上线采用观察模式，先比对建议与人工处理，再扩大可执行范围。

9. 待选择与润色的问题

首个可演示闭环选“订单交付风险”、“质量异常追溯”还是“跨域经营问答”？
第一版是否只读，或允许创建**待审批草稿**？
用户入口优先放全局助手、业务单据侧栏，还是两者并行？
模型部署优先沿用现有 yudao-module-ai 配置，还是由 Python 独立管理？这需要核对当前模型服务的可调用接口与运维方式。

以上选定后，再收敛接口清单、交互流程、数据库表、部署图和验收样例，形成可实施版本。