JY1.0/docs/JY1.0-AI助手知识库与DeepSeek对接设计文档.md

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

1. 文档目标

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

2. AI 助手定位

AI 助手面向三类用户：

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

助手边界：

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

3. 总体架构

推荐架构：

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 配置方式

环境变量：

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

Node.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 基线

系统提示词建议：

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

开发辅助提示词应补充：

生成代码时遵循现有页面结构：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 知识条目结构

{
  "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

请求：

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

响应：

{
  "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

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

8.3 知识库重建接口

POST /api/knowledge/rebuild

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

8.4 页面分析接口

POST /api/project/analyze-page

{
  "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 助手页面

在现有项目新增：

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 手动更新

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

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. 推荐代码仓库结构

建议在项目中新增：

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/