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

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

九个业务场景的触发、取证、计算、结果、审批边界与仓库接入核对见 [场景蓝图](industrial-agent-scenario-blueprint.md)。

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

企业初次上线与日常补录新增核心主线：[WPS 等工作文件分析、多轮核对与业务入库](industrial-agent-document-onboarding-design.md)，与运营场景并列建设。

## 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. 总体架构

```mermaid
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. 智能体工作机制

```text
接收任务 → 鉴权/识别业务对象 → 选用场景模板 → 规划只读工具
→ 并行取证 → 校验时间、单位、口径与关联 → 规则/预测计算
→ 生成带来源的答案/方案 → 如需写入则形成待审批命令
→ 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 项目结构（拟）

```text
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. 分阶段落地与验收

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

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

## 9. 待选择与润色的问题

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

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