DataPilot Analytics 是一个面向企业场景的 AI 数据分析工作台原型，旨在打通“数据接入 → 元数据治理 → 即时分析 → AI 看板生成 → 局部编辑与脱敏导出”的端到端闭环体验。
与盲目追求文本直出 SQL 的玩具项目不同，DataPilot Analytics 坚持数据、分析结构（Manifest）与画布渲染三层解耦。通过受控的运行时 Agent、白名单图表推荐字典、确定性布局校验器与微创式局部 Patch 机制，既能让企业用户用自然语言完成“指哪打哪”的局部看板微调，又绝不推翻重构整张报表。
项目原生支持主流大模型（Anthropic Claude、OpenAI、Google Gemini、NVIDIA NIM 及企业兼容接口），并内置高鲁棒性的本地规则引擎双轨回退：即使未配置任何大模型 API Key，也能完整体验看板生成与局部调整。
📌 真实与模拟边界说明：当前项目已实现完整的前端界面、ECharts/自绘 SVG 渲染、参数化服务端数仓聚合、真实模型后端网关、BYOK 会话内存管理及细粒度数据权限原型。多租户 SSO、分布式计算及生产级密钥托管见 实现现状说明。
统一掌握企业数据全貌：数据源健康状态、数仓分层（DWD / DWS / ADS）、核心指标与即席分析报表。
基于结构化 Manifest 驱动渲染指标卡、趋势折线图、对比柱状图与多维筛选联动；右侧停靠式 AI 助手支持自然语言对话与微创式局部修改（Surgical In-Place Editing）。
灵活拖拽维度与度量进行服务端全表安全聚合，一键将即席结果固化为看板组件；报表门户支持模版库与多端自适应。
| 能力模块 | 核心特性说明 |
|---|---|
| 🔌 多源接入与 ODS 同步 | • 支持本地 SQLite，以及通过直连或 SSH 加密隧道连接 PostgreSQL、MySQL、SQL Server • 自动化表结构扫描、数据质量评分（空值率、去重值、均值与四分位数、异常检测） • 手动全量同步至本地 ODS 数仓，单表支持 10 万行覆盖写入，失败表隔离不阻断 |
| 📚 保护型数据目录与关联 | • 统一维护数据源、物理表、字段画像、语义指标与数据字典 • 人工保护锁：用户修正后的元数据永久锁定，后续 AI 重新扫描绝不覆盖覆盖人工资产 • 可视化拖拽连线定义数仓实体表关联（LEFT / INNER），自动预检基数并生成联合模型数据集 |
| ⚡ 即时多维分析 (Ad-hoc) | • 拖拽维度与度量，服务端全表参数化安全聚合（求和、均值、去重计数等） • 告别前端 500 行抽样失真；一键将即席分析结果转化为持久化看板组件并生成 Query Receipt |
| 🤖 受控 AI 引擎与局部 Patch | • 任务级 Agent / Skill 规则编译加载，内置 FT 视觉词汇表与图表推荐字典 • 微创式局部 Patch：支持位置指代（左上角）、标题搜索或点击组件定向修改 • 双轨安全兜底：模型故障、超时或校验不通过时，自动无缝切换到确定性本地规则引擎 |
| 🎨 Semi Design 看板引擎 | • 严格遵循字节跳动 Semi Design 企业级设计令牌，提供克制专业的亮/暗双主题 • 基于 react-grid-layout 的自由拖拽调整与网格吸附缩放• 指标卡、柱线图、明细表与多层级结构化洞察（核心结论 / 关键发现 / 行动建议） • 图表间跨维度 Cross-Filter 交互联动 |
| 📦 离线独立 HTML 导出 | • 一键导出单文件 HTML，内嵌最小脱敏数据投影与轻量运行时 • 无需任何服务器或数据库依赖，在纯离线环境下依然可交互筛选、图表联动与悬浮查看 |
| 🔒 企业权限与内存凭据安全 | • 基于角色的访问控制（RBAC），支持数据集预览/分析/导出策略，以及行级范围和字段脱敏 • 内存凭据保险库：关系型数据库密码、SSH 私钥及用户 BYOK 模型 API Key 仅暂存于服务端内存，绝不落盘持久化 |
DataPilot Analytics 严格遵守数据源 → 治理目录 → 结构化 Manifest → 渲染引擎的单向数据流与闭环反馈：
graph TD
subgraph 多源数据接入
sqlite["SQLite 本地 / 导入"]
pg["PostgreSQL 直连 / SSH"]
mysql["MySQL 直连 / SSH"]
mssql["SQL Server 直连 / SSH"]
end
subgraph 数据目录与语义治理
scan["元数据扫描与质量画像"]
sync["手动全量同步 ODS 数仓"]
catalog["保护型数据字典与指标清单"]
relation["可视化数仓关系建模"]
end
subgraph 分析与探索
adhoc["即时多维分析 Ad-hoc"]
dashboard["分析报表 / 动态看板"]
end
subgraph 双轨AI编排引擎
llm["真实 LLM API"]
rules["确定性规则回退引擎"]
validator["运行时结构与权限校验器"]
patch["结构化 Manifest Patch"]
end
subgraph 企业级展现与交付
canvas["Semi Design 画布渲染"]
export["独立离线 HTML / 图片导出"]
end
sqlite --> scan
pg --> scan
mysql --> scan
mssql --> scan
scan --> sync
sync --> catalog
catalog --> relation
relation --> adhoc
adhoc --> dashboard
catalog --> llm
catalog --> rules
dashboard --> llm
dashboard --> rules
llm --> patch
rules --> patch
patch --> validator
validator --> canvas
canvas --> export
- 结构化 Manifest 为唯一可编辑事实源：看板组件类型、字段映射、布局与主题全部由结构化 JSON 描述，HTML 仅为渲染介质，杜绝散落的数据硬编码。
- 微创修改而非全量重绘：局部修改只下发单组件的
updateWidget/updateFilterPatch，避免模型重写破坏其他已精心调整好的组件。 - 确定性降级保证高可用：AI 服务异常或配置未就绪时，界面明确提示原因并切换到本地规则，始终给用户可用反馈。
| 层级 | 技术选型 | 说明 |
|---|---|---|
| 前端框架 | React 18 + TypeScript + Vite 8 | 极速热重载，严谨的组件化与静态类型约束 |
| UI 设计系统 | @douyinfe/semi-ui (Semi Design) | 字节跳动企业级设计语言，深度采用 CSS Variables 令牌与亮/暗模式 |
| 网格布局 | react-grid-layout | 支持自由拖拽、网格吸附与自适应尺寸拉伸 |
| 图表与可视化 | 自绘 SVG / 响应式 DOM 渲染引擎 | 内置点位防遮挡、横轴安全刻度重算、Cross-Filter 联动 |
| 服务端 | Node.js + Express + TSX | 处理数据库适配、参数化查询、SSH 隧道转发与 AI 代理 |
| 本地数仓与驱动 | SQLite 3 (datapilot-warehouse.sqlite)、pg、mysql2、mssql、ssh2 |
支持直连与 SSH 跳板机隧道 |
| AI 适配层 | OpenAI-compatible 与 Anthropic 官方客户端适配器 | 支持流式、结构化 JSON Mode 及会话级 BYOK 临时凭据管理 |
- Node.js:
^20.19.0或>=22.12.0 - 包管理器:
npm(推荐npm ci)
git clone https://github.com/Drawoh-eh/DataPilot-Analytics.git
cd DataPilot-Analytics
npm ci项目内置了生成本地 SQLite 仿真零售数据的脚本，包含订单明细与客户行为：
npm run db:init生成的文件存放在
data/local/（已加入.gitignore），不会污染仓库或篡改用户自定义数据库。
npm run dev浏览器打开 http://127.0.0.1:5173/。
零配置可用：即使尚未配置任何大模型密钥，系统也会启用确定性本地规则引擎，支持完整体验看板生成、主题切换、图表类型切换与筛选器添加！
系统支持两种模型配置模式：
直接在工作台右下角点击 “系统设置” → “模型连接”：
- 支持 NVIDIA NIM、OpenAI、Anthropic Claude、Google Gemini、Ollama 或任意兼容 OpenAI 协议的企业网关。
- 密钥仅保存在本机后端服务内存中，会话关闭或手动断开即销毁，绝不写入浏览器存储或持久化到磁盘。
复制环境变量模版并启动：
cp .env.example .env编辑 .env：
# 示例：配置 NVIDIA NIM
AI_PROVIDER=openai-compatible
AI_API_KEY=nvapi-your-key-here
AI_MODEL=nvidia/nemotron-3-super-120b-a12b
AI_BASE_URL=https://integrate.api.nvidia.com/v1
# 示例：配置 Anthropic Claude
# AI_PROVIDER=anthropic
# AI_API_KEY=sk-ant-your-key-here
# AI_MODEL=claude-3-5-sonnet-20241022
# 示例：配置 Google Gemini (兼容接口)
# AI_PROVIDER=openai-compatible
# AI_API_KEY=your-gemini-key
# AI_MODEL=gemini-1.5-pro
# AI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/详细供应商配置、Token 参数与 Hindsight 记忆配置参见 真实模型 API 配置指南。
- 连接数据源：在“数据源清单”中选择 SQLite、PostgreSQL、MySQL 或 SQL Server，填写连接信息（可勾选 SSH 隧道）。
- 探查与质检：一键预览源表，系统自动扫描字段结构并生成质量事实（记录数、空值率、高频值分布、均值四分位）。
- 人工元数据锁定：在“元数据确认”中补齐业务名称与计算口径，已人工确认的内容永久锁定。
- 数仓全量同步：多选关键表，一键全量抽取至本地数仓，完成 ODS 落地并记录读写行数与同步状态。
- 构建关联模型：拖拽两表连接线配置多对一/一对一关联，验证基数后生成可供即时分析的联合数据集。
- 即席探索或一键成板：
- 在“即时分析”中拖拽维度度量，服务端全表聚合，结果一键加入看板；
- 在“分析报表”右侧 AI 助手输入自然语言（例如“分析不同渠道的新增用户转化与收入趋势”），即可秒级生成多组件分析看板。
项目配备了严格的回归测试脚本，覆盖前端运行时、模型网关适配、SQLite 数仓与关系型连接器：
# 运行前端与运行时渲染回归
npm run test:runtime
# 运行真实模型后端适配器测试
npm run test:ai
# 运行 SQLite 数仓与参数化聚合测试
npm run test:db
# 运行 PostgreSQL / MySQL / SQL Server 关系型连接器回归
npm run test:connectors
# 静态类型检查与生产构建
npm run buildnpm run build
npm run start- 项目支持通过 GitHub Actions 实现自动化部署，详细操作与 Caddy HTTPS 反向代理配置参见 Azure 部署说明。
- 部署安全清单：
- 严禁将
.env、凭据文件与真实业务data/目录提交至公共仓库； - 生产环境建议开启系统登录身份认证并强制启用 HTTPS；
- 关系型数据库连接建议使用具备只读权限的最小化特权账号。
- 严禁将
| 文档 | 作用与涵盖内容 |
|---|---|
| 📋 实现现状说明 (真实 vs 模拟) | 核心必读：明确区分哪些是真实落地代码、哪些是展示层原型模拟 |
| 🔌 数据源适配器说明 | 深入介绍关系型连接器、SSH 隧道机制与 ODS 同步契约 |
| 🤖 真实模型 API 配置指南 | 覆盖 Claude、OpenAI、Gemini、NVIDIA NIM 的参数调整与记忆配置 |
| ☁️ Azure 部署与运维指南 | 涵盖 Linux VM 搭建、Caddy HTTPS 证书配置与 CI/CD 自动部署 |
| 🎨 设计规范与设计令牌参考 | Semi Design 设计令牌、亮暗色彩映射与图表调色板字典 |
| 🤝 开发协作约定 (AGENTS.md) | 针对 Agent 与协同开发者的架构约束、修改协议与目录边界 |
| 📝 版本更新日志 | 每次功能更新与重大变更的追踪记录 |
本项目采用 MIT License 开源协议。