项目简介

项目概述

全源灵动是一个面向数据分析与知识检索场景的 AI 平台：用自然语言问数、自动生成图表与报告，并管理分析产物，帮助团队更快得到可验证、可复用的结论。

项目起源

数据分散在不同系统与文件中时，手写 SQL、手工出图、反复同步口径的成本高且难复用。全源灵动将“提问 → 查询 → 可视化 → 产出”串联为一条可复用的分析链路。

项目定位

• 目标用户：业务/数据分析、运营、产品、研发等需要自助分析与报告产出的角色
• 适用场景：NL2SQL 问数、知识库检索增强、自动图表与报告产出、任务委派与跟踪（A2A）

核心价值

• 更快：把“写 SQL / 查资料 / 出图”合并为一次对话驱动的分析流程
• 更稳：对关键结果提供可回溯的查询与产物（Artifact）
• 更灵活：支持多数据源与可配置的模型接入

整体架构与技术栈

系统架构图

graph TD
  User([用户/浏览器]) -->|HTTP| WebUI[前端 WebUI]
  WebUI -->|REST/SSE| API[后端 API]
  API -->|读写| Data[(DATA_ROOT)]
  API -->|连接/查询| DB[(数据源)]
  API -->|调用| LLM([外部 LLM])

技术栈分类

• 后端：FastAPI（Python 3.11+）
• 前端：React 19 + Vite + TailwindCSS + Zustand
• 数据库：
  • 业务元数据/会话：SQLite（默认落在 DATA_ROOT）
  • 数据分析数据源：PostgreSQL / ClickHouse / 上传文件（CSV/Excel 等）
• 部署：Docker Compose（推荐）

项目目录概览

.
├── dataclaw-api/          # 后端 FastAPI（API 网关、会话与数据源管理、Agent 能力）
├── dataclaw-ui/           # 前端 React + Vite（Nginx 生产静态托管）
├── agent-core/            # Agent 核心（nanobot）
├── dataclaw-voice/        # Whisper 语音服务（可选）
├── data/                  # 运行时数据目录（可挂载为 DATA_ROOT）
└── docker-compose.yml     # 一键启动

核心业务功能

• 自然语言转 SQL：理解数据表结构，生成/修正 SQL 并执行查询
• 知识库检索（RAG）：上传多种格式文档，向量检索增强问答
• 即时可视化：根据数据特征生成交互式图表
• 动态多数据源：PostgreSQL / Supabase / 本地文件上传解析等
• 模型配置：支持接入 OpenAI 兼容接口的外部模型服务
• 产物管理（Artifact）：自动提取与管理报告/图片/PDF/PPT 等结果文件
• A2A 任务委派与跟踪：把任务委派到远端 Agent，并可订阅状态与产物

实际应用场景示例

1. 运营日报/周报：提问“近 7 天新增用户趋势与转化漏斗”，自动生成图表与报告
2. 产品指标分析：对留存、转化、渠道贡献等指标进行归因分析，并固化仪表盘
3. 知识库问答：上传制度/方案/投标文件等，自动总结与检索引用

帮助解决的核心问题

• SQL 门槛高、分析链路长、结果难复用
• 多数据源/多口径带来的协作成本高
• 报告产出与分享效率低

快速开始

环境要求

• Docker Desktop（推荐）
• （本地开发模式可选）Python 3.11+、Node.js 20+

安装步骤

在项目根目录复制环境配置模板：

cp .env.example .env

运行步骤（Docker 全量启动）

docker compose up -d --build

访问地址：

• 前端：http://localhost:10002/
• 后端（直连）：http://localhost:10001/docs

运行时数据目录：

• 默认挂载 ./data 到容器内 /app/data（对应 DATA_ROOT=/app/data），用于存放上传文件、会话与配置等。

默认账号

系统首次注册的用户将自动成为管理员（示例：用户名 admin，密码 admin）。

常见问题

• 后端构建失败（APT 连接失败）：可使用国内镜像构建：

APT_CN_MIRROR=true docker compose build

• 接口返回 401：需要先登录并携带 Authorization: Bearer <token>
• 接口返回 422：请求体不符合后端 schema（例如 A2A message:send 需要 message.parts[0].data.project_id）

运行示例截图