# JY1.0 AI 助手、知识库与 DeepSeek 对接设计文档

## 1. 文档目标

本文档用于设计面向「景耀 JY1.0」MES 项目的 AI 助手。该助手应具备项目知识问答、业务功能解释、代码定位、开发辅助、排障分析、规范检查和可选业务数据查询能力，并通过 MCP 服务读取项目上下文，通过知识库检索长期知识，通过 DeepSeek 模型生成答案。

## 2. AI 助手定位

AI 助手面向三类用户：

| 用户 | 主要诉求 |
| --- | --- |
| 前端开发 | 快速理解页面、定位 API、生成符合项目规范的 Vue 2 代码 |
| 实施/运维 | 查询功能入口、解释业务流程、排查请求和权限问题 |
| 管理/业务人员 | 了解系统模块、查询功能说明、按权限查询只读业务状态 |

助手边界：

- 可以解释项目、检索代码、生成建议。
- 可以在授权后读取只读业务数据。
- 不默认执行生产写操作。
- 不保存用户密码、Cookie、token。
- 不绕过现有系统权限。

## 3. 总体架构

推荐架构：

```mermaid
flowchart LR
  U["用户"] --> UI["AI 助手界面"]
  UI --> API["AI 助手服务"]
  API --> LLM["DeepSeek API"]
  API --> RAG["知识库检索服务"]
  API --> MCP["JY1.0 MCP 服务"]
  MCP --> Code["项目代码/文档"]
  MCP --> Meta["项目索引"]
  RAG --> VDB["向量库"]
  RAG --> Doc["文档与代码片段"]
  API --> Audit["审计日志"]
  API -.可选只读.-> Biz["MES 业务只读接口"]
```

核心组件：

| 组件 | 职责 |
| --- | --- |
| AI 助手界面 | 聊天入口、问题输入、引用展示、审批确认 |
| AI 助手服务 | 会话管理、工具编排、RAG 编排、权限控制 |
| DeepSeek API | 自然语言理解、推理、答案生成 |
| MCP 服务 | 项目代码、结构、页面、API、规范工具 |
| 知识库 | 项目文档、代码摘要、业务流程、接口说明 |
| 向量库 | 语义检索 |
| 审计日志 | 记录工具调用、数据访问、用户问题 |
| 业务只读接口 | 可选，查询订单、库存、设备、任务等状态 |

## 4. DeepSeek 对接方案

### 4.1 模型选择

建议按任务选择模型：

| 任务 | 推荐模型 |
| --- | --- |
| 日常项目问答、代码解释 | `deepseek-chat` |
| 复杂设计、技术路线、长链路排障 | `deepseek-reasoner` |
| 低成本批量摘要 | `deepseek-chat` |

DeepSeek API 兼容 OpenAI 风格的 Chat Completions 接口。建议在服务端使用 OpenAI SDK 兼容方式接入，避免前端暴露 API Key。

### 4.2 配置方式

环境变量：

```bash
DEEPSEEK_API_KEY=你的密钥
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-chat
```

Node.js 示例：

```js
import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: process.env.DEEPSEEK_API_KEY,
  baseURL: process.env.DEEPSEEK_BASE_URL || 'https://api.deepseek.com'
})

export function chat(messages) {
  return client.chat.completions.create({
    model: process.env.DEEPSEEK_MODEL || 'deepseek-chat',
    messages: messages,
    temperature: 0.2
  })
}
```

### 4.3 调用策略

- 业务问答：先检索知识库，再调用 DeepSeek。
- 代码定位：先调用 MCP 工具，再让模型汇总。
- 复杂问题：先让模型生成检索计划，再调用 MCP/RAG，再二次回答。
- 代码生成：必须注入 `AGENTS.md` 规范和相似页面代码片段。
- 排障：必须附带请求链路、文件路径、后端 `name`、参数。

### 4.4 Prompt 基线

系统提示词建议：

```text
你是景耀 JY1.0 MES 项目的 AI 助手。项目使用 Vue 2、Element UI、Vuex、Vue Router、Axios、Webpack 4，不使用 Vue 3、TypeScript、Composition API。业务请求统一通过 MESCommonBase.ashx，使用 CreateData 和 ExecDatabase 构造请求。数据库字段和页面字段多为中文，回答和代码必须保留中文字段名。你必须优先根据知识库和 MCP 工具返回的项目事实回答；不确定时说明需要检索或确认。不得建议绕过权限、不得生成生产写库脚本、不得暴露密钥。
```

开发辅助提示词应补充：

```text
生成代码时遵循现有页面结构：div.app-container > el-card > 搜索栏 + el-table。使用 Vue 2 Options API、Element UI、.then().catch()，不新增第三方库。新增/编辑/删除优先使用全局工具方法。表格字段和请求参数使用后端中文字段名。
```

## 5. 知识库设计

### 5.1 知识库目标

知识库用于解决模型“不知道项目细节”的问题。它应覆盖：

- 项目规则。
- 业务模块说明。
- 页面与 API 映射。
- 后端过程名说明。
- 常见问题。
- 新增页面范式。
- 部署和配置说明。
- 历史变更与版本记录。

### 5.2 知识来源

| 来源 | 内容 | 入库方式 |
| --- | --- | --- |
| `AGENTS.md` | 项目 Agent 规则、代码规范 | 原文切片 |
| `docs/` | 设计文档、实施文档 | 原文切片 |
| `package.json` | 依赖和脚本 | 结构化摘要 |
| `src/router` | 路由机制 | 代码摘要 |
| `src/utils/request.js` | 请求封装 | 代码摘要 |
| `src/utils/curd.js` | 全局 CRUD 方法 | 代码摘要 |
| `src/views` | 页面功能、字段、后端调用 | 自动抽取摘要 |
| `src/api` | API 函数和后端 `name` | 自动抽取摘要 |
| `static/config.js` | 服务地址类型 | 脱敏摘要 |
| `static/项目档案.docx` | 项目档案 | docx 转文本后入库 |

### 5.3 知识分类

建议知识库分为以下集合：

| 集合 | 内容 |
| --- | --- |
| `project_rules` | AGENTS、编码规范、技术栈 |
| `architecture` | 路由、请求、状态、构建、部署 |
| `business_modules` | 模块和页面说明 |
| `api_operations` | 后端 `name`、参数、调用页面 |
| `fields` | 中文字段、表格列、表单项 |
| `faq` | 常见问题和排障 |
| `change_logs` | 提交记录、变更说明 |

### 5.4 文档切片规则

Markdown：

- 按标题层级切片。
- 每片 500 到 1200 中文字。
- 保留标题路径。
- 保留文件路径。

Vue 文件：

- template 摘要：页面结构、表格列、弹窗。
- script 摘要：data、methods、CreateData 调用。
- style 摘要：仅记录特殊样式。
- 大文件不整篇入库，使用结构化抽取。

API 文件：

- 每个导出函数作为一个知识单元。
- 提取函数名、type、name、param、UserID、ModularID。

后端过程：

- 每个 `name` 一个知识单元。
- 汇总调用文件和参数。

### 5.5 知识条目结构

```json
{
  "id": "api:仓储管理_采购件入库_循环执行",
  "collection": "api_operations",
  "title": "仓储管理_采购件入库_循环执行",
  "content": "该后端操作由采购件入库页面 submitInStorage 调用，用于批量执行采购件入库...",
  "metadata": {
    "source": "src/views/WarehouseManagement/PurchasePartsStorage/index.vue",
    "module": "WarehouseManagement",
    "type": "backend_name",
    "operationType": "12",
    "fields": ["物料流水号组", "实际到货数量组", "入库人员流水号"],
    "updatedAt": "2026-06-10"
  }
}
```

### 5.6 向量库选型

本地/内网优先：

| 方案 | 适用场景 |
| --- | --- |
| Chroma | 快速原型、本地部署简单 |
| Qdrant | 生产部署、性能和过滤较好 |
| Milvus | 大规模、多项目知识库 |
| SQLite + sqlite-vec | 单机轻量化 |

推荐路线：

- 原型阶段：Chroma 或 SQLite。
- 内网生产：Qdrant。
- 多系统统一知识库：Milvus。

### 5.7 Embedding 模型

DeepSeek 主要用于对话，不建议假设其提供可用的 embedding 服务。中文项目建议：

| 模型 | 特点 |
| --- | --- |
| `BAAI/bge-m3` | 中英多语、长文本、综合能力好 |
| `bge-large-zh-v1.5` | 中文语义检索效果好 |
| `text2vec-large-chinese` | 中文轻量方案 |

部署方式：

- 内网 GPU：本地 embedding 服务。
- 无 GPU：CPU 量化模型或商用 embedding API。

## 6. RAG 检索流程

标准流程：

1. 用户提问。
2. 意图识别：项目问答、代码定位、业务查询、开发生成、排障。
3. 查询改写：补充同义词，如“入库”扩展到“采购件入库、外协入库、自制件入库”。
4. 多路检索：
   - 向量检索文档。
   - BM25/关键词检索中文字段和后端 `name`。
   - MCP 工具检索代码结构。
5. 重排：优先同模块、同页面、同后端 `name`。
6. 构造上下文。
7. DeepSeek 生成答案。
8. 输出引用来源。
9. 记录审计。

回答必须包含：

- 结论。
- 文件/模块来源。
- 如果是代码建议，说明需修改哪些文件。
- 如果不确定，说明缺少什么信息。

## 7. AI 助手功能设计

### 7.1 项目问答

示例问题：

- “这个项目怎么新增一个页面？”
- “`CreateData` 参数怎么传？”
- “仓储管理有哪些页面？”
- “菜单权限是怎么生成路由的？”

实现：

- 检索 `project_rules`、`architecture`。
- 调用 MCP `list_business_modules` 或 `analyze_vue_page`。

### 7.2 业务功能解释

示例问题：

- “采购件入库页面做了什么？”
- “装配执行的开始、暂停、完成分别调用哪个后端过程？”
- “零件追溯在哪个页面？”

实现：

- MCP 分析页面。
- 检索 `business_modules`、`api_operations`。
- 输出操作流程、后端调用、关键字段。

### 7.3 代码定位

示例问题：

- “查找所有调用 `装配执行_完成装配` 的地方。”
- “哪个页面用了字段 `订单编号`？”
- “库存查询页面在哪里？”

实现：

- MCP `trace_backend_name`。
- MCP `find_chinese_field`。
- MCP `find_pages_by_keyword`。

### 7.4 新功能开发辅助

示例问题：

- “新增一个库存预警页面。”
- “给采购订单查询增加供应商筛选。”
- “新增一个导出按钮。”

实现：

- 检索相似页面。
- 注入项目规范。
- 生成最小改动方案。
- 调用规范检查工具。

输出：

- 修改文件。
- 代码片段。
- 后端需要提供的 `name` 和字段。
- 测试清单。

### 7.5 排障分析

示例问题：

- “登录后页面空白。”
- “接口提示账号登录失效。”
- “新增页面菜单点不开。”
- “入库按钮点了没反应。”

实现：

- 检索 FAQ。
- MCP 分析页面请求。
- 检查路由、Cookie、后端 `name`、参数、返回结构。

### 7.6 规范检查

示例问题：

- “检查这个页面是否符合项目规范。”
- “这次改动有没有用了 Vue 3 写法？”

实现：

- MCP `check_jy_conventions`。
- 输出问题等级、路径、行号、修复建议。

### 7.7 只读业务查询

可选能力：

- 查询订单状态。
- 查询库存汇总。
- 查询设备状态。
- 查询装配任务。
- 查询采购到货。

要求：

- 使用独立业务只读代理。
- 不允许任意 SQL。
- 绑定当前登录用户。
- 记录审计日志。
- 对敏感字段脱敏。

## 8. AI 助手服务接口设计

### 8.1 聊天接口

`POST /api/ai/chat`

请求：

```json
{
  "sessionId": "s001",
  "userId": "10001",
  "message": "采购件入库页面在哪里？",
  "context": {
    "currentRoute": "/WarehouseManagement/PurchasePartsStorage"
  }
}
```

响应：

```json
{
  "answer": "采购件入库页面位于 ...",
  "citations": [
    {
      "type": "code",
      "path": "src/views/WarehouseManagement/PurchasePartsStorage/index.vue"
    }
  ],
  "toolCalls": [
    {
      "name": "find_pages_by_keyword",
      "status": "success"
    }
  ]
}
```

### 8.2 知识库检索接口

`POST /api/knowledge/search`

```json
{
  "query": "动态路由",
  "collections": ["architecture", "project_rules"],
  "topK": 5
}
```

### 8.3 知识库重建接口

`POST /api/knowledge/rebuild`

```json
{
  "scope": "all",
  "force": false
}
```

### 8.4 页面分析接口

`POST /api/project/analyze-page`

```json
{
  "path": "src/views/AssemblyManagement/AssemblyExecution/index.vue"
}
```

## 9. 数据库与存储设计

### 9.1 会话表

| 字段 | 说明 |
| --- | --- |
| `id` | 会话 ID |
| `user_id` | 用户 ID |
| `title` | 会话标题 |
| `created_at` | 创建时间 |
| `updated_at` | 更新时间 |

### 9.2 消息表

| 字段 | 说明 |
| --- | --- |
| `id` | 消息 ID |
| `session_id` | 会话 ID |
| `role` | user/assistant/tool |
| `content` | 内容 |
| `metadata` | 引用、工具调用、token |
| `created_at` | 创建时间 |

### 9.3 知识文档表

| 字段 | 说明 |
| --- | --- |
| `id` | 文档 ID |
| `source_path` | 来源路径 |
| `collection` | 集合 |
| `title` | 标题 |
| `content_hash` | 内容哈希 |
| `metadata` | 元数据 |
| `updated_at` | 更新时间 |

### 9.4 工具审计表

| 字段 | 说明 |
| --- | --- |
| `id` | 审计 ID |
| `user_id` | 用户 |
| `tool_name` | 工具名 |
| `input` | 输入，敏感字段脱敏 |
| `output_summary` | 输出摘要 |
| `status` | success/error |
| `created_at` | 时间 |

## 10. 权限与安全设计

### 10.1 用户认证

可选方案：

- 与现有 MES 登录态集成。
- 独立 AI 助手账号。
- 内网单点登录。

建议：

- 前期使用独立账号和角色。
- 后期接入 MES Cookie/session，并复用角色权限。

### 10.2 权限矩阵

| 功能 | 开发 | 实施 | 业务 |
| --- | --- | --- | --- |
| 项目文档问答 | 允许 | 允许 | 部分允许 |
| 代码检索 | 允许 | 部分允许 | 禁止 |
| 代码生成 | 允许 | 禁止 | 禁止 |
| 业务功能解释 | 允许 | 允许 | 允许 |
| 只读业务查询 | 部分允许 | 允许 | 按角色 |
| 写业务数据 | 禁止 | 禁止 | 禁止 |
| 知识库重建 | 允许 | 禁止 | 禁止 |

### 10.3 防护措施

- API Key 只放服务端环境变量。
- 日志脱敏。
- 工具调用白名单。
- 禁止任意 SQL。
- 禁止任意 shell。
- 业务数据查询按角色过滤。
- 生产写操作默认禁用。

## 11. 前端集成方案

### 11.1 独立 AI 助手页面

在现有项目新增：

```text
src/views/AIAssistant/index.vue
```

功能：

- 左侧会话列表。
- 中间聊天窗口。
- 右侧引用来源。
- 支持复制答案、查看文件路径。
- 支持按模块选择上下文。

页面仍使用 Vue 2 + Element UI。

### 11.2 嵌入式浮窗

在 `src/views/layout/components/Navbar.vue` 增加 AI 入口，点击打开右侧抽屉。

适合：

- 当前页面上下文问答。
- “解释当前页面”。
- “检查当前页面问题”。

### 11.3 权限菜单

后端菜单需新增：

- AI 助手。
- AI 知识库管理。
- AI 审计日志。

对应路由仍通过动态菜单注入。

## 12. 知识库更新机制

### 12.1 手动更新

开发者点击“重建知识库”或执行脚本：

```bash
node scripts/build-knowledge.js --root D:/景耀/JY1.0
```

### 12.2 Git Hook 更新

在提交或部署后触发：

- 检测变更文件。
- 只重建变更页面/API/文档。
- 更新向量库和索引。

### 12.3 定时更新

每天夜间：

- 扫描 `docs`、`src/views`、`src/api`。
- 对比 hash。
- 增量更新。

## 13. 技术路线

### 阶段 1：文档与代码知识库

周期：1 到 2 周。

任务：

- 建立知识库目录。
- 编写项目规则、功能矩阵、API 映射文档。
- 搭建向量库。
- 实现 Markdown、Vue、JS 文件切片。
- 接入 DeepSeek 基础问答。

验收：

- 能回答项目技术栈、目录结构、请求规范。
- 能根据关键词找到页面。
- 回答带来源。

### 阶段 2：MCP 工具接入

周期：2 到 3 周。

任务：

- 实现 MCP 服务。
- 提供项目结构、页面分析、后端 `name` 反查工具。
- AI 助手支持工具调用。

验收：

- 能分析指定 Vue 页面。
- 能列出页面后端调用。
- 能检查代码规范。

### 阶段 3：开发辅助能力

周期：2 周。

任务：

- 新增页面生成 Prompt。
- 相似页面检索。
- 代码规范检查。
- 生成测试清单。

验收：

- 能生成符合 Vue 2 + Element UI + `CreateData` 风格的页面骨架。
- 能解释需要后端配置的菜单和过程名。

### 阶段 4：业务只读查询

周期：3 到 4 周。

任务：

- 梳理只读业务查询白名单。
- 建立业务查询代理。
- 接入用户权限。
- 增加审计。

验收：

- 能查询订单状态、库存概况、设备状态。
- 无任意 SQL 能力。
- 数据按用户权限过滤。

### 阶段 5：系统化运营

周期：持续。

任务：

- 增加问题反馈。
- 建立 FAQ。
- 统计高频问题。
- 自动生成模块文档。
- 结合提交记录生成变更说明。

## 14. 推荐代码仓库结构

建议在项目中新增：

```text
docs/
  JY1.0-MCP服务设计文档.md
  JY1.0-AI助手知识库与DeepSeek对接设计文档.md
  功能矩阵.md
  后端过程清单.md
  常见问题.md

mcp-server/
  package.json
  src/
    server.js
    tools/
      project.js
      vue.js
      api.js
      conventions.js
    resources/
      project.js
    indexer/
      scan.js
      parseVue.js
      parseApi.js

ai-assistant-server/
  package.json
  src/
    app.js
    llm/deepseek.js
    rag/search.js
    rag/ingest.js
    mcp/client.js
    auth/
    audit/
```

是否放在同一仓库取决于部署策略：

- 开发阶段可放同仓库，便于读取代码。
- 生产阶段建议 MCP/AI 服务独立仓库，JY1.0 仓库只保留文档和客户端入口。

## 15. 关键风险与应对

| 风险 | 影响 | 应对 |
| --- | --- | --- |
| 源码存在编码异常 | 解析中文字段困难 | 逐步 UTF-8 规范化，索引器容错 |
| 后端过程无正式文档 | AI 难以准确解释参数 | 从前端调用自动抽取，后续人工补全 |
| 页面内直接写请求较多 | API 映射分散 | MCP 扫描 `CreateData` 调用 |
| 任意 SQL 调用历史存在 | 安全风险 | AI 工具不暴露任意 SQL |
| DeepSeek 输出幻觉 | 错误建议 | 强制 RAG 引用和工具来源 |
| 生产数据敏感 | 合规风险 | 只读白名单、脱敏、审计 |

## 16. 验收清单

AI 助手上线前应验证：

- 能回答项目结构和技术栈。
- 能解释统一请求机制。
- 能检索所有主要业务模块。
- 能定位指定页面路径。
- 能反查后端 `name` 调用点。
- 能抽取页面表格字段。
- 能按项目规范生成 Vue 2 页面建议。
- 能接入 DeepSeek 且 API Key 不出现在前端。
- 知识库回答包含来源。
- 审计日志可查看。
- 默认不具备生产写库能力。

## 17. 参考资料

- Model Context Protocol 官方文档：https://modelcontextprotocol.io/
- DeepSeek API 官方文档：https://api-docs.deepseek.com/