# MES-Manager_View DeepSeekV4Pro AI 助手与 MCP 服务设计文档

## 1. 背景与目标

本设计用于在 `MES-Manager_View` 中建设一个类似 `C:\work\Project\Mes\HL_MES_manager` 的网页内置 AI 助手，名称为 `DeepSeekV4Pro AI 助手`。助手需要具备以下能力：

| 目标 | 说明 |
| --- | --- |
| 项目功能 MCP 化 | 将 `MES-Manager_View` 中页面、接口、菜单、查询、质量管理、SPC 分析等功能整理为 MCP 工具，由本地服务统一暴露。 |
| 质量管理数据查询 | 支持用户用自然语言查询质量管理相关页面和数据，例如质量追溯、质量 Andon、质量数据、线体质量、巡检、物料质量等。 |
| SPC 图文展示 | 支持查询并图文并茂展示 SPC 分析中的基本趋势图、样本趋势图、直方图、正态分布图、过程能力分析图、排列图、X-R 图、X-S 图等。 |
| 网页内助手 | 在前端页面全局挂载可拖拽、可折叠、可清空、可调整大小的 AI 对话浮窗。 |
| 表格化回答 | AI 回答优先使用规范 HTML 表格；涉及图表时返回图表说明、统计摘要、数据表和可渲染图表配置。 |
| 不改底层逻辑 | 不修改现有业务页面、后端 `.ashx`、数据库存储过程、现有接口语义，只新增 AI 组件、MCP 服务、知识库与配置，并调用现有函数或接口。 |

## 2. 现状梳理

### 2.1 当前项目结构

| 模块 | 当前位置 | 说明 |
| --- | --- | --- |
| 前端入口 | `src/App.vue` | 当前只渲染 `router-view`，尚未挂载 AI 助手。 |
| 路由 | `src/router/index.js`、`src/router/getRouter.js` | 登录后动态菜单由后端返回，前端根据 `component` 映射到 `src/views`。 |
| 全局请求 | `src/utils/request.js` | 主要通过 `window.g.baseURL + /submit/MESCommonBase.ashx` 调用通用后端接口。 |
| 运行配置 | `static/config.js`、`dist/static/config.js` | 当前包含 `baseURL`、MQTT、打印模板等配置，未包含 AI MCP 地址。 |
| SPC 接口 | `src/api/SPCanalysis/*` | 已封装趋势图、直方图、正态分布、过程能力、X-R、X-S、排列图等接口。 |
| SPC 页面 | `src/views/SearchData/*` | 包含 `SPC_Analysis`、`sampleTrendChart`、`histogram`、`processCapabilityAnalysis`、`arrangeChart`、`QualityData_XR`、`QualityData_XS` 等页面。 |
| 质量管理页面 | `src/views/QualityAssurance/*`、`src/views/AndonSystem/*`、`src/views/SearchData/QualityDatasearch` | 包含质量数据、质量 Andon、巡检、条码、线体质量、装配质量等相关功能。 |

### 2.2 参考项目能力

`HL_MES_manager` 中已存在以下可参考内容：

| 参考内容 | 路径 | 可复用思想 |
| --- | --- | --- |
| AI 前端组件 | `src/components/DeepSeekAssistant/index.vue` | 全局浮窗、拖拽、折叠、清空、HTML 表格渲染、调用本地 AI 服务。 |
| AI 挂载方式 | `src/App.vue` | 在 `router-view` 后挂载 `deep-seek-assistant`。 |
| MCP 服务 | `mcp-server/server.js` | 本地 HTTP 服务、MCP JSON-RPC、DeepSeek 代理、知识库检索、只读查询。 |
| 知识库构建 | `mcp-server/build-knowledge-base.js` | 从静态分析 CSV 生成 JSON 知识库。 |
| 文档产物 | `docs/*.csv`、`docs/hl-mes-knowledge-base.json` | 页面调用、接口映射、SQL 表对象、模块摘要。 |
| 启停脚本 | `scripts/*.ps1`、`scripts/*.bat` | 日常启动、停止、状态检查。 |

### 2.3 当前项目关键差异

| 差异项 | 当前项目情况 | 设计处理 |
| --- | --- | --- |
| 前端未挂 AI 组件 | `MES-Manager_View` 没有 `components/DeepSeekAssistant` | 新增组件，不改现有业务组件。 |
| 没有 MCP 服务目录 | 当前无 `mcp-server`、`docs` 分析产物、`scripts` AI 脚本 | 新增独立服务目录和脚本。 |
| SPC 接口使用独立 `ip` | `src/api/ipAddress.js` 指向 `http://localhost:57966` | MCP 服务读取配置并调用 SPC `.ashx` 接口。 |
| 通用业务接口使用 `baseURL` | `static/config.js` 中 `baseURL` 当前为 `http://127.0.0.1:10050` | MCP 服务可配置 `MES_BACKEND_URL`，默认只读。 |
| 质量/SPC 结果格式不统一 | 有的接口返回数组，有的返回字符串拼接，有的返回分页对象 | MCP 服务增加标准化适配层，转为表格数据和图表数据。 |

## 3. 总体架构

### 3.1 架构分层

| 层级 | 新增内容 | 职责 |
| --- | --- | --- |
| 前端 AI 组件层 | `src/components/DeepSeekAssistant` | 展示对话、发送问题、展示 HTML 表格、展示图表卡片、触发页面跳转。 |
| 前端配置层 | `static/config.js` | 增加 AI MCP 服务地址配置，例如 `aiMcpURL`。 |
| MCP 服务层 | `mcp-server/server.js` | 暴露 MCP tools、代理 DeepSeek、调用知识库、调用只读 MES/SPC 接口、生成 HTML 表格和图表结构。 |
| 知识库层 | `docs/*.csv`、`docs/wc-spc-knowledge-base.json` | 存储页面、接口、函数、质量模块、SPC 图表、字段映射、查询入口。 |
| 静态分析层 | `mcp-server/build-knowledge-base.js` 及分析脚本 | 扫描 `src/views`、`src/api`、`src/assets/img/api`，提取接口调用和业务功能。 |
| 业务系统层 | 现有 `.ashx`、`MESCommonBase.ashx`、SPC 接口 | 保持不变，由 MCP 服务按只读规则调用。 |

### 3.2 数据流

| 场景 | 数据流 |
| --- | --- |
| 用户咨询项目功能 | 前端助手发送问题到 MCP 服务；MCP 服务检索知识库；必要时调用 DeepSeek 整理；返回 HTML 表格。 |
| 用户要求打开页面 | MCP 服务通过知识库匹配页面路径；前端助手收到 `navigate` 动作后调用 `$router.push`。 |
| 用户查询质量数据 | MCP 服务识别质量模块和查询条件；调用知识库中的只读接口或只读 SQL 白名单；返回数据表、字段说明和查询来源。 |
| 用户查看 SPC 图 | MCP 服务识别图表类型；调用对应 SPC 接口；标准化为 ECharts option、统计摘要、明细表；前端助手渲染图表和表格。 |
| DeepSeek 智能回答 | MCP 服务把知识库摘要、查询结果、图表摘要作为上下文发送给 DeepSeek；要求输出 HTML 表格化答案。 |

## 4. 修改范围与不修改范围

### 4.1 允许新增或调整的内容

| 类型 | 文件或目录 | 修改方式 |
| --- | --- | --- |
| 新增 | `src/components/DeepSeekAssistant/index.vue` | 新增 AI 助手组件，参考 `HL_MES_manager`，适配中文编码和 SPC 图表展示。 |
| 小范围调整 | `src/App.vue` | 只增加组件引入和挂载，不改变 `router-view`、`provide/reload` 逻辑。 |
| 小范围调整 | `static/config.js`、必要时 `dist/static/config.js` | 增加 `window.g.aiMcpURL`，不改变现有 `baseURL`、MQTT、打印配置。 |
| 新增 | `mcp-server/*` | 新增本地 AI MCP 服务，独立运行。 |
| 新增 | `docs/*` | 生成静态分析文档和知识库文件。 |
| 新增 | `scripts/*` | 新增启动、停止、状态检查脚本。 |
| 小范围调整 | `package.json` | 增加 AI MCP 启动、停止、知识库构建脚本；必要时增加 `mssql` 依赖。 |

### 4.2 明确不修改的内容

| 不修改对象 | 原因 |
| --- | --- |
| 现有业务页面查询逻辑 | 避免影响生产页面行为和用户习惯。 |
| `src/api/SPCanalysis/*` 原函数签名 | AI 服务可参考和调用接口语义，但不改变已有页面引用。 |
| `src/utils/request.js` 的拦截、登录态、超时等逻辑 | 避免影响全局请求和权限。 |
| 后端 `.ashx`、数据库存储过程、数据库表结构 | 本次只做前端 AI 与 MCP 服务设计。 |
| 动态菜单生成逻辑 | AI 页面跳转通过已有路由能力实现，不改变权限菜单来源。 |

## 5. MCP 服务设计

### 5.1 服务定位

MCP 服务是一个运行在本机或内网服务器上的 Node.js 服务，作用是把 `MES-Manager_View` 项目的页面、接口、函数和数据查询能力包装成标准 MCP 工具。浏览器不直接访问 DeepSeek API，也不保存 DeepSeek 密钥。

| 项目 | 设计 |
| --- | --- |
| 默认端口 | `3100` 或由环境变量 `AI_MCP_PORT` 配置。 |
| DeepSeek 密钥 | 只放在 `mcp-server/.env.local` 或服务器环境变量中。 |
| MES 通用接口 | 默认读取 `MES_BACKEND_URL`，可指向 `window.g.baseURL + /submit/MESCommonBase.ashx`。 |
| SPC 接口地址 | 默认读取 `SPC_BACKEND_URL`，对应当前 `src/api/ipAddress.js` 中的 `http://localhost:57966`。 |
| 数据库连接 | 可选，只允许只读账号，只查询知识库白名单对象。 |
| 输出格式 | HTML 表格、结构化数据、图表配置、页面跳转动作。 |

### 5.2 服务端点

| 端点 | 方法 | 用途 |
| --- | --- | --- |
| `/health` | GET | 检查服务、DeepSeek、知识库、SQL、SPC 接口配置状态。 |
| `/mcp` | POST | MCP JSON-RPC 入口，支持工具列表和工具调用。 |
| `/api/tools` | GET | 前端或调试时查看可用 MCP 工具。 |
| `/api/assistant/chat` | POST | 前端 AI 助手聊天入口，返回 HTML、图表、动作。 |
| `/api/chart/render-data` | POST | 可选，用于前端按图表 ID 拉取标准化图表数据。 |

### 5.3 MCP 工具清单

#### 5.3.1 项目知识类工具

| 工具名 | 作用 | 输入 | 输出 |
| --- | --- | --- | --- |
| `project_summary` | 返回项目模块、接口数量、质量/SPC 能力总览 | 无 | HTML 总览表 |
| `list_feature_modules` | 列出所有页面模块 | 模块关键字、分页参数 | 模块表 |
| `search_project_functions` | 按关键字搜索页面、接口、函数 | `query`、`limit` | 页面和接口匹配表 |
| `get_view_calls` | 查看某个页面调用了哪些接口或数据库操作 | `view`、`limit` | 调用清单表 |
| `get_api_file_mapping` | 查看某个 API 文件封装了哪些后端接口 | `apiFile`、`limit` | API 映射表 |
| `get_module_knowledge` | 返回指定模块的知识库详情 | `module` | 模块、页面、接口、查询入口 |
| `reload_project_index` | 重新加载知识库 | 无 | 状态表 |

#### 5.3.2 页面导航类工具

| 工具名 | 作用 | 示例问题 | 输出 |
| --- | --- | --- | --- |
| `find_page_route` | 根据自然语言匹配页面 | “打开 SPC 分析页面” | 候选页面表 |
| `navigate_to_page` | 返回前端可执行跳转动作 | “进入质量数据查询” | `navigate` 动作和页面表 |

说明：MCP 服务只返回动作建议，真正跳转由前端助手调用当前 Vue Router 完成，不绕过现有权限体系。

#### 5.3.3 质量管理数据工具

| 工具名 | 作用 | 数据来源 |
| --- | --- | --- |
| `list_quality_modules` | 列出质量相关功能模块 | `src/views/QualityAssurance`、`src/views/AndonSystem`、`src/views/SearchData` |
| `search_quality_functions` | 搜索质量管理相关页面和接口 | 知识库 |
| `query_quality_data` | 根据自然语言查询质量数据 | 知识库只读接口、只读 SQL 白名单、通用 MES 接口 |
| `quality_data_summary` | 对质量数据做数量、异常、时间范围、工位等摘要 | 查询结果 |
| `quality_field_dictionary` | 解释质量数据字段含义 | 知识库字段映射 |

质量数据查询需要遵守以下规则：

| 规则 | 说明 |
| --- | --- |
| 只读 | 只允许查询类接口、`SELECT` SQL、分页查询。 |
| 白名单 | 只能调用知识库识别出的查询接口或白名单表/视图。 |
| 限制行数 | 默认最多返回 100 行，用户要求更多时仍需要上限控制。 |
| 条件明确 | 查询质量明细时必须有时间范围、工位、条码、机型、测量项等至少一个过滤条件；缺少条件时返回条件提示表。 |
| 禁止写操作 | 新增、修改、删除、导入、审核、提交、上传、执行类接口不开放给 AI 自动调用。 |

#### 5.3.4 SPC 分析工具

| 工具名 | 图表能力 | 当前项目对应位置 |
| --- | --- | --- |
| `spc_list_dimensions` | 查询可选工位、机型、测量位置、测量项目 | `CreateData('11', 'SPC分析_去重字段_查询', ...)` 及相关质量查询接口 |
| `spc_query_raw_data` | 查询 SPC 明细数据 | `GetDataTableByConditent` 类接口 |
| `spc_sample_trend_chart` | 样本趋势图 | `src/api/SPCanalysis/sampleTrendChart.js` |
| `spc_basic_trend_chart` | 基本趋势图 | `src/api/SPCanalysis/basicTrendTap.js` |
| `spc_histogram_chart` | 直方图 | `src/api/SPCanalysis/histogram.js` |
| `spc_normal_distribution_chart` | 正态分布图 | `src/api/SPCanalysis/normal_distribution.js` |
| `spc_process_capability_chart` | 过程能力分析 | `src/api/SPCanalysis/processCapabilityAnalysis.js` |
| `spc_pareto_chart` | 排列图 | `src/api/SPCanalysis/arrangeChart.js` |
| `spc_xr_chart` | X-R 控制图 | `src/api/SPCanalysis/QualityData_XR.js` |
| `spc_xs_chart` | X-S 控制图 | `src/api/SPCanalysis/QualityData_XS.js` |
| `spc_chart_explain` | 解释 SPC 结果、异常点、规格线、Cp/Cpk | 标准化图表结果和 DeepSeek |

### 5.4 SPC 入参模型

| 参数 | 含义 | 是否必填 | 默认策略 |
| --- | --- | --- | --- |
| `chartType` | 图表类型，如 `sampleTrend`、`histogram`、`xr`、`xs` | 是 | 由自然语言识别，无法识别时返回候选表 |
| `startTime` | 开始日期 | 是 | 可默认最近 7 天，但需在回答中明示 |
| `endTime` | 结束日期 | 是 | 默认当天 |
| `opName` | 工位号或工位名称 | 建议必填 | 缺少时先查询候选工位 |
| `measureName` | 测量位置 | 视图表而定 | 缺少时根据工位返回候选 |
| `measureContent` | 测量项目 | 视图表而定 | 缺少时根据工位和测量位置返回候选 |
| `model` | 机型或零件号 | 可选 | 用户未指定时不加过滤 |
| `sampleSize` | 样本容量 | 可选 | 默认沿用现有页面常用值 `5` |
| `sampleNumber` | 样本个数 | 可选 | 默认沿用现有页面常用值 `20` |
| `usl` | 上规格限 | 过程能力/正态分布需要 | 用户未提供时使用接口返回或提示输入 |
| `lsl` | 下规格限 | 过程能力/正态分布需要 | 用户未提供时使用接口返回或提示输入 |
| `pageSize` | 明细表页大小 | 可选 | 默认 20，最大 100 |
| `pageCurrent` | 当前页 | 可选 | 默认 1 |

### 5.5 SPC 输出模型

每次 SPC 图表查询统一返回以下结构，前端助手据此渲染：

| 输出块 | 内容 | 展示方式 |
| --- | --- | --- |
| 查询条件 | 时间、工位、机型、测量位置、测量项目、样本参数 | HTML 表格 |
| 统计摘要 | 最大值、最小值、平均值、标准差、Cp、Cpk、USL、LSL、异常点数量等 | HTML 表格 |
| 图表数据 | ECharts option 或内部标准图表模型 | 前端图表容器渲染 |
| 明细数据 | 原始测量值、单位、发动机号、生产日期等 | HTML 表格 |
| 解释结论 | 趋势说明、异常提示、规格线说明、建议关注点 | HTML 表格或短段落 |
| 来源信息 | 调用的页面、API 文件、后端 `.ashx`、接口 `type` | HTML 表格 |

前端不执行 AI 生成的任意 JavaScript。图表渲染只使用 MCP 服务返回的可信结构化图表模型，由内置渲染器转成 ECharts 配置。

## 6. 前端 AI 助手设计

### 6.1 组件能力

| 能力 | 说明 |
| --- | --- |
| 全局可见 | 在 `src/App.vue` 中挂载，所有业务页面可使用。 |
| 可拖拽 | 支持鼠标拖动，位置自动限制在浏览器视口内。 |
| 可折叠 | 支持最小化，减少遮挡业务页面。 |
| 可调整大小 | 支持小、中、大三种窗口尺寸。 |
| 可清空 | 支持清空当前聊天记录。 |
| HTML 表格渲染 | 对助手返回的 HTML 做安全过滤后展示。 |
| 图表渲染 | 识别响应中的 `charts` 数组，使用 ECharts 渲染图表。 |
| 页面跳转 | 识别 `actions` 中的 `navigate` 动作，通过 `$router.push` 进入页面。 |
| 错误提示 | MCP 服务不可用、接口不可用、条件不足时以表格展示原因和处理建议。 |

### 6.2 前端响应展示规范

| 响应类型 | 展示规范 |
| --- | --- |
| 普通问答 | 一个或多个 HTML 表格，标题清晰，字段不拥挤。 |
| 数据查询 | 先展示查询条件，再展示摘要，再展示明细表。 |
| 图表分析 | 先展示图表，再展示统计摘要和数据表。 |
| 多候选结果 | 展示候选表，提示用户补充筛选条件。 |
| 错误 | 展示错误类型、原因、建议处理、关联配置。 |

### 6.3 HTML 安全策略

| 策略 | 说明 |
| --- | --- |
| 禁止脚本 | 删除 `script`、事件属性、`javascript:` 链接。 |
| 白名单标签 | 只允许表格、标题、段落、列表、强调、代码等展示标签。 |
| 图表结构化 | 图表不通过 HTML 内嵌脚本实现，只通过结构化数据渲染。 |
| 外链控制 | 外部链接默认新窗口打开，不自动执行。 |

## 7. 知识库建设设计

### 7.1 静态分析范围

| 分析对象 | 目标 |
| --- | --- |
| `src/views/**/*.vue` | 提取页面路径、页面标题、导入的 API、`CreateData`、`ExecDatabase`、`RawSQL`、ECharts 调用。 |
| `src/api/**/*.js` | 提取封装函数、`.ashx` 地址、`type`、参数名、业务域。 |
| `src/assets/img/api/**/*.js` | 提取历史遗留 API 文件中的业务接口。 |
| `src/router/**/*.js` | 提取静态路由、动态路由生成规则。 |
| `src/icons/svg` | 辅助识别菜单和模块名称。 |

### 7.2 产物文件

| 文件 | 内容 |
| --- | --- |
| `docs/wc-spc-static-analysis.md` | 项目结构、模块数量、接口数量、质量/SPC 摘要。 |
| `docs/view-database-calls.csv` | 页面中的查询、增删改、RawSQL、通用接口调用。 |
| `docs/view-database-calls-summary.csv` | 按页面汇总调用数量、业务域、接口名。 |
| `docs/view-api-imports.csv` | 页面与 API 文件导入关系。 |
| `docs/api-name-mapping.csv` | API 文件中的函数、`.ashx`、`type`、参数映射。 |
| `docs/raw-sql-table-mapping.csv` | 前端出现的 SQL 和表对象。 |
| `docs/spc-chart-mapping.csv` | SPC 页面、API、图表类型、参数、返回格式映射。 |
| `docs/quality-module-mapping.csv` | 质量管理页面、接口、字段、可查询能力映射。 |
| `docs/wc-spc-knowledge-base.json` | MCP 服务运行时加载的统一知识库。 |

### 7.3 知识库字段设计

| 字段 | 说明 |
| --- | --- |
| `module` | 一级模块，如 `QualityAssurance`、`SearchData`、`AndonSystem`。 |
| `view` | 页面文件路径。 |
| `routePath` | 可推导的路由路径。 |
| `title` | 页面中文名称，优先来自菜单或文件名映射。 |
| `domains` | 业务域，如质量数据、SPC、ANDON、MES。 |
| `apiFiles` | 页面导入的 API 文件。 |
| `backendEndpoints` | `.ashx` 地址和 `type`。 |
| `queryable` | 是否允许 AI 自动查询。 |
| `writeOperation` | 是否为写操作，写操作默认禁用。 |
| `chartTypes` | 页面支持的图表类型。 |
| `fieldMap` | 字段中文名、含义、单位、是否用于筛选。 |
| `keywords` | 搜索关键字和中文分词片段。 |

## 8. DeepSeekV4Pro 调用策略

### 8.1 模型职责

| 职责 | 说明 |
| --- | --- |
| 意图识别 | 判断用户是在问功能、查数据、看图、跳转页面还是解释结果。 |
| 条件补全 | 从自然语言中抽取时间、工位、机型、测量项、图表类型。 |
| 结果解释 | 对查询结果和 SPC 图表进行中文解释。 |
| 表格生成 | 尽可能使用 HTML 表格组织回答。 |

### 8.2 服务端优先规则

| 规则 | 说明 |
| --- | --- |
| 可确定数据先查数据 | 明确的数据查询不只让模型猜测，先由 MCP 工具查询真实数据。 |
| 图表先生成结构化结果 | SPC 图表由服务端按接口返回构造，不让模型自由编造。 |
| 模型只做表达和解释 | DeepSeek 负责总结、归纳、提示风险，不负责直接执行数据库写操作。 |
| 无密钥也可运行 | 未配置 DeepSeek 密钥时，助手仍可基于本地知识库返回表格结果。 |

### 8.3 Prompt 输出约束

| 约束 | 说明 |
| --- | --- |
| 使用中文 | 默认中文回答。 |
| 优先 HTML 表格 | 除简短确认外，所有结构化结果使用表格。 |
| 不编造数据 | 没有查询到真实数据时说明“未查询到”或“条件不足”。 |
| 明示来源 | 数据结果必须展示来源接口或页面。 |
| 不输出可执行脚本 | 不返回任意可执行 JavaScript；图表通过结构化 `charts` 输出。 |

## 9. 质量管理数据查询设计

### 9.1 质量模块识别范围

| 模块路径 | 质量相关能力 |
| --- | --- |
| `src/views/QualityAssurance` | 巡检、物料数据、条码、线体质量、装配质量、生产计划完成等。 |
| `src/views/SearchData/QualityDatasearch` | SPC 数据导入、质量数据查询、趋势分析基础数据。 |
| `src/views/SearchData/SPC_Analysis` | SPC 综合分析。 |
| `src/views/SearchData/QualityData_XR` | X-R 图分析。 |
| `src/views/SearchData/QualityData_XS` | X-S 图分析。 |
| `src/views/AndonSystem/qualityAndon*` | 质量 Andon 与统计。 |

### 9.2 查询流程

| 步骤 | 处理 |
| --- | --- |
| 1. 识别意图 | 判断用户是否查询质量管理数据。 |
| 2. 匹配模块 | 根据“巡检、条码、线体质量、质量 Andon、SPC、测量值”等关键字匹配知识库模块。 |
| 3. 抽取条件 | 抽取时间、工位、条码、发动机号、机型、测量位置、测量项目等条件。 |
| 4. 检查安全 | 确认调用为只读查询，且来源在知识库白名单内。 |
| 5. 执行查询 | 调用通用 MES 接口、SPC `.ashx` 或只读 SQL。 |
| 6. 标准化结果 | 统一为 `columns`、`rows`、`summary`。 |
| 7. 生成回答 | 返回 HTML 条件表、摘要表、数据表、来源表。 |

### 9.3 条件不足时的处理

当问题类似“帮我查质量数据”但缺少关键条件时，助手不直接全表查询，而返回如下提示表：

| 需要补充项 | 示例 |
| --- | --- |
| 时间范围 | 今天、最近 7 天、2026-05-01 到 2026-05-27 |
| 数据类型 | SPC、巡检、条码、质量 Andon、线体质量 |
| 过滤条件 | 工位、机型、测量位置、测量项目、发动机号 |
| 返回数量 | 前 20 条、前 100 条、按异常汇总 |

## 10. SPC 图文并茂展示设计

### 10.1 图表类型与输出内容

| 图表 | 输出内容 | 说明 |
| --- | --- | --- |
| 基本趋势图 | 折线图、规格线、明细表 | 用于查看测量值随时间或样本变化趋势。 |
| 样本趋势图 | 样本均值/点位趋势、明细表 | 对应 `QualityData_TrendPicture.ashx`。 |
| 直方图 | 柱状分布、频数表 | 对应 `QualityData_Histogram.ashx`。 |
| 正态分布图 | 正态曲线、频数柱、USL/LSL/中心线、Cp/Cpk | 对应 `QualityData_NormalDistribution.ashx`。 |
| 过程能力图 | Cp/Cpk 指标、规格限、分布图 | 组合直方图和正态分布数据。 |
| 排列图 | 柱状图、累计折线、占比表 | 对应 `QualityData_Pareto.ashx`。 |
| X-R 图 | 均值图、极差图、控制线、异常点表 | 对应 `QualityData_XR.ashx`。 |
| X-S 图 | 均值图、标准差图、控制线、异常点表 | 对应 `QualityData_XS.ashx`。 |

### 10.2 图表回答结构

| 展示顺序 | 内容 |
| --- | --- |
| 1 | 图表标题和查询条件表。 |
| 2 | ECharts 图表区域，可展示一张或多张图。 |
| 3 | SPC 统计指标表，例如平均值、标准差、Cp、Cpk、USL、LSL、UCL、LCL。 |
| 4 | 异常点或超限点表。 |
| 5 | 明细数据表，默认前 20 条。 |
| 6 | AI 解释表，包括趋势判断、是否超规格、建议关注点。 |
| 7 | 数据来源表，列出页面、API、`.ashx` 和接口 `type`。 |

### 10.3 图表渲染原则

| 原则 | 说明 |
| --- | --- |
| 使用已有 ECharts | 当前项目 `main.js` 已挂载 `Vue.prototype.$echarts`，AI 组件可复用。 |
| 不依赖业务页面 DOM | AI 图表在助手组件内部独立容器渲染，不读取现有页面的 `myChart`。 |
| 不修改现有绘图函数 | 可复刻其数据解析规则到 MCP 标准化层，但不改页面内 `drawLine`。 |
| 图表可追溯 | 每个图表响应带 `chartType`、调用接口、查询条件。 |
| 多图支持 | X-R、X-S 可返回两个图表，过程能力可返回分布图和指标表。 |

## 11. 安全与权限设计

| 风险 | 控制措施 |
| --- | --- |
| DeepSeek 密钥泄露 | 密钥只存在 MCP 服务端环境变量或 `.env.local`，不写入前端。 |
| AI 执行写操作 | MCP 工具默认禁用新增、修改、删除、导入、审核、提交、上传、执行类接口。 |
| SQL 注入 | 只允许白名单表/视图；禁止拼接用户原始 SQL；禁止分号、多语句和写关键字。 |
| 越权访问 | 前端跳转仍走现有路由和菜单权限；数据查询建议使用只读服务账号。 |
| 大量数据拖垮系统 | 默认限制 100 行，图表限制合理时间范围，超出时提示收窄条件。 |
| HTML 注入 | 前端过滤脚本和事件属性，图表不执行模型返回脚本。 |
| 生产接口误调用 | `call_mes_backend` 默认只允许查询类接口；写接口需要明确关闭。 |

## 12. 配置设计

### 12.1 前端配置项

| 配置项 | 说明 | 示例含义 |
| --- | --- | --- |
| `window.g.aiMcpURL` | AI MCP 服务地址 | 浏览器调用本地或内网 AI 服务。 |
| `window.g.baseURL` | 现有 MES 后端地址 | 保持原值，不因 AI 改动。 |

### 12.2 MCP 服务环境变量

| 变量 | 说明 |
| --- | --- |
| `AI_MCP_PORT` | MCP 服务端口。 |
| `DEEPSEEK_API_KEY` | DeepSeek API 密钥。 |
| `DEEPSEEK_BASE_URL` | DeepSeek API 地址。 |
| `DEEPSEEK_MODEL` | 模型名称，按实际账号支持的模型配置。 |
| `MES_BACKEND_URL` | 通用 MES 后端接口地址。 |
| `SPC_BACKEND_URL` | SPC 专用 `.ashx` 后端地址。 |
| `AI_MCP_ALLOW_BACKEND_CALLS` | 是否允许调用 MES 后端，默认仅只读查询。 |
| `AI_MCP_ALLOW_SQL_QUERY` | 是否允许直接查询 SQL Server，默认可关闭。 |
| `SQL_SERVER`、`SQL_DATABASE`、`SQL_USER`、`SQL_PASSWORD` | 只读数据库连接配置。 |

## 13. 任务节点与实施计划

### 阶段 1：项目静态分析与知识库设计

| 节点 | 工作内容 | 产出 | 验收标准 |
| --- | --- | --- | --- |
| 1.1 | 扫描 `src/views`、`src/api`、`src/assets/img/api` | 初始 CSV | 能列出页面、API、接口名、`.ashx`、`type`。 |
| 1.2 | 专项识别质量模块 | `quality-module-mapping.csv` | 能列出质量相关页面和查询入口。 |
| 1.3 | 专项识别 SPC 图表模块 | `spc-chart-mapping.csv` | 每种 SPC 图表能映射到 API 文件和接口。 |
| 1.4 | 构建 JSON 知识库 | `wc-spc-knowledge-base.json` | MCP 服务可加载，`/health` 显示模块数量。 |

### 阶段 2：MCP 服务基础能力

| 节点 | 工作内容 | 产出 | 验收标准 |
| --- | --- | --- | --- |
| 2.1 | 新增 `mcp-server` 基础服务 | `server.js` | `/health`、`/mcp`、`/api/tools` 可访问。 |
| 2.2 | 增加项目知识工具 | MCP tools | 能按关键字查询项目功能和页面。 |
| 2.3 | 增加页面导航工具 | `navigate` 动作 | 问“打开 SPC 分析”能返回正确候选页面。 |
| 2.4 | 增加 DeepSeek 代理 | 聊天接口 | 浏览器不暴露 API key，服务端可调用模型。 |

### 阶段 3：质量管理查询能力

| 节点 | 工作内容 | 产出 | 验收标准 |
| --- | --- | --- | --- |
| 3.1 | 建立质量数据查询白名单 | 查询工具配置 | 写接口不出现在可调用工具中。 |
| 3.2 | 实现 `query_quality_data` | MCP 工具 | 能按时间、工位、条码等查询质量数据。 |
| 3.3 | 实现质量摘要 | 摘要表 | 返回数量、异常、时间范围、关键字段统计。 |
| 3.4 | 条件不足提示 | HTML 提示表 | 无条件全量查询被拦截并提示补充条件。 |

### 阶段 4：SPC 图表能力

| 节点 | 工作内容 | 产出 | 验收标准 |
| --- | --- | --- | --- |
| 4.1 | 标准化 SPC 入参 | 参数解析器 | 能从自然语言抽取时间、工位、图表类型。 |
| 4.2 | 接入样本趋势、基本趋势 | MCP 图表工具 | 返回趋势图、明细表、来源表。 |
| 4.3 | 接入直方图、正态分布、过程能力 | MCP 图表工具 | 返回分布图、Cp/Cpk、规格线表。 |
| 4.4 | 接入排列图、X-R、X-S | MCP 图表工具 | 返回多图、控制线、异常点表。 |
| 4.5 | 图表解释 | AI 解释结果 | 能解释趋势、超限、异常点和建议关注项。 |

### 阶段 5：前端助手集成

| 节点 | 工作内容 | 产出 | 验收标准 |
| --- | --- | --- | --- |
| 5.1 | 新增 AI 助手组件 | `DeepSeekAssistant` | 可拖拽、可折叠、可清空。 |
| 5.2 | 挂载到 `App.vue` | 全局助手 | 登录后各页面均可看到助手。 |
| 5.3 | HTML 表格渲染 | 消息展示 | 表格样式规范，长字段不撑破窗口。 |
| 5.4 | 图表渲染 | ECharts 容器 | SPC 查询可展示图表和表格。 |
| 5.5 | 页面跳转动作 | 路由联动 | AI 能打开匹配到的项目页面。 |

### 阶段 6：脚本、配置与验收

| 节点 | 工作内容 | 产出 | 验收标准 |
| --- | --- | --- | --- |
| 6.1 | 增加启动脚本 | `scripts/start-daily.*` | 一键启动 MCP 服务。 |
| 6.2 | 增加停止和状态脚本 | `scripts/stop-ai.*`、`scripts/ai-status.*` | 能查看和停止服务。 |
| 6.3 | 增加 package 脚本 | `ai:mcp`、`kb:build` 等 | 命令可执行。 |
| 6.4 | 编写使用说明 | `mcp-server/README.md` | 说明配置、启动、常见问题。 |
| 6.5 | 最终测试 | 验收清单 | 功能问答、质量查询、SPC 图表均通过。 |

## 14. 验收用例

| 编号 | 用户问题 | 期望结果 |
| --- | --- | --- |
| A1 | “项目里有哪些质量管理功能？” | 返回质量模块表，包含页面、接口数量、可查询能力。 |
| A2 | “打开 SPC 分析页面” | 返回页面表并跳转到匹配的 SPC 页面。 |
| A3 | “查询最近 7 天某工位的质量数据前 20 条” | 返回查询条件表、数据表、来源表。 |
| A4 | “画某工位某测量项最近 7 天的样本趋势图” | 返回趋势图、统计摘要表、明细表。 |
| A5 | “看这个测量项目的过程能力，USL 是 10，LSL 是 5” | 返回过程能力图、Cp/Cpk 表、规格线表和解释。 |
| A6 | “生成 X-R 控制图” | 条件完整时返回均值图和极差图；条件不足时返回补充条件表。 |
| A7 | “删除质量数据” | 拒绝执行，返回安全说明表。 |
| A8 | “查全部质量表所有数据” | 拒绝全量查询，提示补充时间和过滤条件。 |

## 15. 关键技术约束

| 约束 | 处理方案 |
| --- | --- |
| Vue 版本较旧 | 沿用 Vue 2、Element UI、ECharts 4，不引入新前端框架。 |
| 编码显示可能存在历史问题 | 新增文件统一 UTF-8，避免复制乱码文本；页面展示文字重新整理。 |
| 现有接口返回格式复杂 | MCP 服务做适配层，不要求现有接口改造。 |
| 动态菜单由后端控制 | 知识库只用于推荐和跳转，权限仍由现有系统控制。 |
| DeepSeek 模型名称需按实际账号确认 | 配置项保留 `DEEPSEEK_MODEL`，默认值可按环境调整。 |

## 16. 最终交付清单

| 类型 | 交付物 |
| --- | --- |
| 前端组件 | `src/components/DeepSeekAssistant/index.vue` |
| 前端挂载 | `src/App.vue` 的最小变更 |
| 前端配置 | `static/config.js` 增加 `aiMcpURL` |
| MCP 服务 | `mcp-server/server.js`、`mcp-server/build-knowledge-base.js`、`mcp-server/README.md` |
| 知识库文档 | `docs/*.csv`、`docs/wc-spc-static-analysis.md`、`docs/wc-spc-knowledge-base.json` |
| 运维脚本 | `scripts/start-daily.*`、`scripts/stop-ai.*`、`scripts/ai-status.*` |
| 包脚本 | `package.json` 中新增 AI 和知识库脚本 |
| 验收说明 | 使用说明、配置说明、验收用例 |

## 17. 实施原则总结

| 原则 | 说明 |
| --- | --- |
| 新增优先 | 尽量新增组件、服务、文档和配置，不改原业务逻辑。 |
| 只读优先 | AI 自动查询默认只读，写操作禁止。 |
| 真实数据优先 | 能调用现有接口查到真实数据时，不让模型猜测。 |
| 表格优先 | 回答、错误、来源、摘要都尽量表格化。 |
| 图表结构化 | SPC 图表用标准结构渲染，不执行模型生成脚本。 |
| 可追溯 | 每条数据回答都展示来源页面、接口或表对象。 |