Data Agent 数据智能分析平台1 项目概述1.1 项目定位1.2 核心能力1.3 设计目标与非目标1.4 总体规模截至 v0.15.32 系统架构2.1 架构总览2.2 六层分层智能问答链路视角2.3 工程目录结构2.4 技术栈3 功能模块说明3.1 认证与安全模块 13.2 权限中心模块 23.3 数据源管理模块 33.4 语义层模块 43.5 知识库模块 53.6 模型管理模块 63.7 工作流模块 73.8 智能问答模块 8系统核心3.9 作业调度模块 93.10 消息与公告模块 103.11 仪表盘模块 113.12 系统管理模块 123.13 手工文件管理模块 13v0.15.24 智能问答 32 步工作流4.1 阶段一 · 听懂问题4.2 阶段二 · 找对数据4.3 阶段三 · 查得出来4.4 阶段四 · 算得可信4.5 阶段五 · 说得明白4.6 关键可靠性设计5 数据库设计5.1 总览6 API 体系6.1 统一约定7 安全设计1 项目概述1.1 项目定位Data Agent 是企业级数据分析智能体系统位于「业务用户」与「业务数据源」之间的智能编排层向下通过语义层理解指标口径与表结构通过 MCP 网关安全访问数据源向上承接业务语言把模糊的自然语言问题转成可执行、可解释、可复现的查询与分析任务。一句话概括让业务用户用口语问数让每一条结论都带口径、带 SQL、带权限标签。1.2 核心能力能力说明自然语言问数32 步五阶段工作流意图理解 → 口径锁定 → 查询生成 → 执行校验 → 结论呈现口径可信每个回答附带指标口径说明、原始 SQL、数据范围与权限标签权限不可绕过行级权限双层校验Agent 层前置过滤 数据源层原生权限二次兜底可解释可复现每次回答可回溯到具体查询语句、执行耗时与数据版本越用越准问答自动沉淀进知识库沉淀的唯一可复用资产是 SQL支撑同类问题复用调度自动化任务/作业/参数/调度用例支持数据同步、SQL 执行、Python 作业与手工表格入湖1.3 设计目标与非目标设计目标自然语言问数、口径可信、权限不可绕过、可解释可复现、越用越准。本期非目标不替代业务系统原生事务操作不做实时写入回写仅查询分析不覆盖非结构化数据的语义检索禁止离线模式所有功能必须经数据库 API 实现。1.4 总体规模截至 v0.15.3指标数值后端 REST 接口433 个341 条路径数据库表110 张AGENT_BI 95 张 SAP 15 张共 1488 列前端页面34 个含智能问答、调度监控大屏、MCP 网关等功能模块13 个全部完成回归测试脚本16 套 Python 回归 多套浏览器真机取证脚本全量通过2 系统架构2.1 架构总览系统采用前后端分离 六层分层架构。浏览器端 Vue 3 单页应用通过 HTTP/JSONBearer Token访问 FastAPI 应用层应用层经 MCP 网关这一唯一出口访问数据源经模型服务访问大模型与向量化能力所有业务数据统一落在达梦 DM8。2.2 六层分层智能问答链路视角层职责接入层Vue 3 SPAHash 路由ERP 风格左侧菜单Vite 开发服务 :5173应用层FastAPI :3001按模块拆分 router / service统一响应结构与审计工作流层32 步链路编排模块 7 可视化配置经审批生效语义层业务域 / 语义表 / 指标口径 / 大宽表问答检索与 SQL 生成的依据数据访问层MCP 网关唯一出口限流默认 5 QPS、熔断、高危拦截、调用审计数据层达梦 DM8AGENT_BI 业务库 SAP 源模拟库 本地文件存储2.3 工程目录结构AI AGENT/ ├── backend/ # FastAPI 后端 │ ├── app/ │ │ ├── config.py # 全局配置APP_VERSION、数据库、模型等 │ │ ├── core/ # database达梦连接、安全、响应封装 │ │ ├── routers/ # 18 个路由模块与前端模块一一对应 │ │ ├── services/ # 业务服务chat/scheduler/knowledge/... │ │ └── main.py # FastAPI 入口、静态资源、路由注册 │ ├── data/manual_files/ # 手工文件落盘目录 │ ├── uploads/theme/ # 登录页背景等主题资源 │ └── run.py # uvicorn 启动脚本reloadFalse ├── frontend/ # Vue3 Vite TS Element Plus │ ├── src/api/ # 接口封装axios │ ├── src/views/ # 34 个页面组件 │ ├── src/router/ # hash 路由 菜单权限过滤 │ └── src/stores/ # Pinia 状态 ├── database/ │ └── init_tables.py # 表结构唯一真相源建表 种子数据 幂等迁移 ├── scripts/ # 回归脚本 / 迁移脚本 / 交付导出脚本 ├── start_all.bat # 一键启动自动拉起达梦 后端 前端 ├── restart_all.bat / stop_all.bat ├── PROJECT_SPECIFICATION.md # 项目规格书规格真相源 └── DEV_CHANGELOG.md # 开发变更日志v0.1.0 ~ v0.15.3 全量2.4 技术栈层技术说明后端Python 3.14 FastAPI uvicorn端口 3001reloadFalse改后端代码必须重启数据库驱动dmPython达梦官方驱动占位符?元数据只读ALL_TABLES/ALL_TAB_COLUMNS前端Vue 3Composition API Vite TypeScript Element Plus Pinia端口 5173hash 路由数据库达梦 DM8127.0.0.1:5236用户 INSPECT / Inspect2026模式 AGENT_BI、SAP向量能力bge-m31024 维向量以 JSON 存 CLOBnumpy 计算余弦相似度无外部向量库大模型OpenAI 兼容接口模型管理模块统一配置支持 Key 校验、余额查询、配额管控进程编排Windows batGBK 编码start_all.bat内建自动拉起 dmserver3 功能模块说明系统共 13 个功能模块全部完成。下表为模块全景其后按模块说明核心能力。#模块主要页面核心表1认证登录页、个人设置SYS_USER、SYS_USER_PROFILE2权限中心用户/角色/权限/目录权限SYS_ROLE、SYS_PERMISSION、SYS_ROLE_PERMISSION、SYS_USER_ROLE、SYS_DATA_PERMISSION3数据源管理数据源管理页DS_SOURCE、DS_DIRECTORY、DS_TABLE_FIELD4语义层业务域/表管理/指标管理/大宽表SEM_DOMAIN、SEM_TABLE、SEM_METRIC、SEM_WIDE_TABLE5知识库知识库页面KB_DOCUMENT、KB_CHUNK、KB_QA_DEPOSIT6模型管理模型管理页LLM_MODEL_CONFIG、LLM_QUOTA_RULE/USAGE/ALERT7工作流工作流配置页WF_WORKFLOW、WF_WORKFLOW_NODE/EDGE、WF_PROMPT_HISTORY8智能问答智能问答页会话/回收站CHAT_SESSION、CHAT_MESSAGE、CHAT_MCP_LOG、CHAT_QUOTA_*9作业调度任务/作业/数据同步/调度监控/SQL 控制台SCH_TASK/JOB/RUN、SCH_SCHEDULE_CASE、SCH_DATA_SYNC_*10消息与公告消息中心、公告管理、审批中心、我的待办MSG_MESSAGE、MSG_ANNOUNCEMENT、APR_*11仪表盘仪表盘聚合查询无独立业务表12系统管理文件/空间/日志/数据字典/系统设置/主题/审计/MCP 网关FILE_、SYS_LOG_、SYS_SETTING、SYS_AUDIT_LOG、CHAT_MCP_LOG13手工文件管理手工文件管理页MF_FOLDER、MF_FILE、MANUAL_INLAKE_DATA3.1 认证与安全模块 1账号密码登录JWT 鉴权不开放自助注册allow_register可配置。登录安全连续失败 5 次锁定可配置锁定时长持久化到用户表管理员可解锁与重置密码。密码策略最小长度、默认密码均可配置系统设置 security 组。个人设置修改密码、昵称、头像。3.2 权限中心模块 2RBAC用户-角色-权限三级关联菜单可见性 用户权限码 ∩ 页面叶子编码。数据权限get_permission_scope()给出 companyCodes × projectCodes 二维范围贯穿问答过滤、手工文件目录、数据同步等所有模块。目录权限数据源目录的读/写授权DS_DIRECTORY_PERMISSION。3.3 数据源管理模块 3数据源连接配置、连接测试表字段元数据采集DS_TABLE_FIELD。数据源目录树 目录权限。是语义层、调度同步、SQL 控制台的统一数据入口。3.4 语义层模块 4业务域SEM_DOMAIN→ 语义表SEM_TABLE含真实字段清单→ 指标SEM_METRIC含口径、SQL 模板、多版本。大宽表SEM_WIDE_TABLESQL 编辑、刷新、物化供问答「路径A」直接取数。指标版本管理与文档关联SEM_METRIC_VERSION、SEM_METRIC_DOC_RELATION。3.5 知识库模块 5文档编辑、分片向量化KB_CHUNK 存向量 JSON、AI 训练LLM 抽取摘要/关键词/问题拼入索引文本失败降级 raw。语义检索双门槛MIN_COS0.45硬下限有字面佐证重叠 ≥0.12只需过下限无佐证需STRONG_COS0.62。问答沉淀KB_QA_DEPOSITSQL 是唯一可复用资产历史 ANSWER 仅作快照展示绝不直接当答案返回。沉淀语义守卫纯指代短问句「这几个月呢」不入沉淀。3.6 模型管理模块 6LLM / Embedding / 自定义模型配置连接探测probe 真实对话校验modechat。余额查询支持四类服务商自动解析无公开接口的如实提示。配额管控规则/用量/告警三表LLM_QUOTA_RULE/USAGE/ALERT。注意probe 通过 ≠ Key 可用部分服务商 /models 不校验必须真实调用验证。3.7 工作流模块 732 步五阶段可视化编辑节点画布节点/连线/提示词模板。配置驱动问答运行时走审批生效WF_PROMPT_HISTORY 记录提示词历史。3.8 智能问答模块 8系统核心会话管理置顶/收藏/重命名/批量删除/回收站与彻底清理v0.15.3。消息流快捷提问、消息删除、导出、重新生成、引用来源展示。配额问答配额规则 用量统计管理员可配置用户额度并重置今日用量。32 步执行链路详见第 4 章。3.9 作业调度模块 9任务SCH_TASK→ 作业SCH_JOB含 SQL/脚本/同步三类→ 作业参数SCH_JOB_PARAM支持dir类手工文件参数与派生占位符。调度用例SCH_SCHEDULE_CASE CRON 表达式 任务依赖 发布流程 冲突拦截。运行实例SCH_TASK_RUN / SCH_JOB_RUN与重跑批次SCH_RERUN_BATCH。数据同步SCH_DATA_SYNC_CONFIG一表一同步、字段映射、并行分桶、同步日志。SQL 控制台多段 SQL 执行、SQL 授权SCH_SQL_GRANT、执行历史。Python 运行环境与依赖包管理SCH_PY_ENV / SCH_PY_PKG。3.10 消息与公告模块 10站内消息未读/已读、公告发布需审批、审批中心定义/实例/任务、我的待办。3.11 仪表盘模块 11统计卡片、图表、最近活动数据全部来自真实 API 聚合。3.12 系统管理模块 12文件管理FILE_FOLDER/FILE_RECORD通用网盘式结构。空间管理数据资产目录、空间看板、配额与预警。日志管理系统/调度/AI 问询三类日志。数据字典、系统设置分组键值、审计日志全量操作留痕。主题管理32 项可视化配置、6 套预设、实时预览驱动登录页外观与全站令牌。MCP 网关v0.13.8问答取数唯一出口限流 5 QPS、熔断、高危拦截、监控大屏与日志页。3.13 手工文件管理模块 13v0.15.2三层目录公司代码 / (项目代码 | COMMON) / YYYYMM按用户权限自动生成。表格真实落盘backend/data/manual_files 数据库登记csv/xlsx 纯标准库解析预览.xls 如实提示不支持。文件登记含入湖跟踪入湖作业、目标表、行数、状态。Python 作业dir参数DEFAULT_VALUE 公司|项目|月份派生占位符${名__files}/${名__count}/${名__exists}内置参数manualRoot。示例作业「手工表格入湖」建表 DELETE ... WHERE SRC_FILE ?幂等写入。4 智能问答 32 步工作流问答链路分五阶段共 32 步。只有步骤 12路径 B由 LLM 生成 SQL路径 A大宽表直取与复用路径不经 LLM。4.1 阶段一业务用户提出问题意图理解、任务规划、加载用户权限域大模型拆解问题要素向语义层查询指标定义与表信息语义层返回指标口径并提示多版本口径存在歧义时发起澄清确认业务确认查询条件与业务范围锁定口径并裁剪查询范围4.2 阶段二检索候选表、字段注释与数据血缘语义层返回表结构与关联关系判断走大宽表还是 LLM 生成按用户权限自动过滤表、字段与行数据注入上下文交由大模型生成查询语句仅路径 B 执行Data Agent 产出查询草稿4.3 阶段三静态校验查询语句拦截高危查询封装标准化查询并转发至数据源数据源层行级权限二次校验与脱敏执行查询返回结果集与性能统计4.4 阶段四结果校验与异常识别校验不通过时回退重试大模型做业务归因推理生成结论并推荐下钻维度并行发起下钻查询返回下钻明细与各维度贡献度交叉验证主指标与下钻明细是否对齐4.5 阶段五渲染图表与报告导出聚合数据图表并生成业务结论返回自然语言结论与数据依据为结论附加可复核信息交付完整分析给业务用户沉淀问答并回灌知识库数据打标 复用机制知识库隔离检索支撑后续复用4.6 关键可靠性设计SQL 接地三道防线LLM 生成 SQL 必须注入目标表真实字段清单_validate_sql_columns()读ALL_TAB_COLUMNS兜底校验校验失败按规则回退到指标 SQL 模板回退必须换语句禁止假重试。多轮上下文追问自动继承上一轮的意图/指标/维度显式维度优先。维度枚举枚举型问题分 list/count 两型作答分组维度按月聚合走SUBSTR(col,1,6)避免按天拆分。复用机制默认关闭可按用户开启regenerate 永不复用复用与绕过全程审计留痕。降级如实LLM 不可用、语义层无命中、执行失败均如实告知并记录 degraded绝不伪造数据。5 数据库设计5.1 总览数据库达梦 DM8用户 INSPECT业务模式AGENT_BI95 张表 源模拟模式SAP15 张表共 110 张表、1488 列。命名规范表名/列名全大写下划线后端出参小驼峰分页统一data.items。主键全部为ID INT IDENTITY(1,1) PRIMARY KEY逻辑外键命名*_ID/*_CODE不建物理外键约束由应用层保证。时间CREATED_AT DATETIME DEFAULT SYSDATE、UPDATED_AT。大字段JSON/长文本用 CLOB向量以 JSON 存 CLOB。5.4 数据库设计约定开发纪律database/init_tables.py是表结构唯一真相源CREATE TABLE IF NOT EXISTS_ensure_columns()幂等补列老库可直接原地升级。达梦不支持ADD COLUMN IF NOT EXISTS新增列必须「先查 ALL_TAB_COLUMNS再逐个 ALTER TABLE COMMENT」。索引无IF NOT EXISTS-2260 已存在需 try/except 兜底。保留字ROWS、COMMENT建表/查询时避免直接使用。存量库不补新种子键新增配置项一律用独立幂等迁移脚本scripts/_migrate_*.py。库字符集为 GBK脚本读写中文需显式PYTHONIOENCODINGutf-8并包TextIOWrapper。6 API 体系6.1 统一约定统一响应{ code: 0, message: ok, data: ... }业务失败 code 非 0鉴权失败 401越权 403参数错误 422。分页请求page / page_size可选keyword过滤响应data.items[]data.total。认证Authorization: Bearer tokenGET /api/auth/config、GET /api/system/theme等为公开接口。错误可读所有错误返回中文可读 message禁止裸抛堆栈。6.2 接口分布v0.15.3 实测 433 个前缀数量模块/api/scheduler82作业调度任务/作业/同步/SQL 控制台/Python 环境/api/system54系统管理设置/日志/字典/空间/文件/主题/审计/api/chat30智能问答会话/消息/配额/回收站/api/permission21权限中心用户/角色/权限/数据权限/api/semantic18语义层/api/knowledge16知识库/api/models15模型管理/api/workflow15工作流/api/file14文件管理/api/approval13审批中心/api/data-source12数据源管理/api/announcement11公告/api/manual-files11手工文件管理/api/auth10认证/api/message7消息/api/mcp-gateway6MCP 网关/api/dashboard5仪表盘/api/health1健康检查7 安全设计层面机制认证JWT密码哈希存储连续失败 5 次锁定并持久化管理员解锁/重置授权RBAC菜单/按钮级 数据权限公司 × 项目二维范围 目录权限问答取数MCP 网关唯一出口限流 5 QPS、熔断、高危 SQL 拦截、逐次审计CHAT_MCP_LOGSQL 生成字段白名单接地 _validate_sql_columns()兜底 高危语句静态拦截步骤 14行级权限Agent 层前置过滤步骤 11 数据源层二次校验与脱敏步骤 16审计SYS_AUDIT_LOG 全量操作留痕含 UA、结果、耗时三类运行日志分类归档传输默认内网部署前后端同源Vite 代理 / Nginx 反代Token 不落 URL