## 项目简介
### 项目概述
**全源灵动**是一个面向数据分析与知识检索场景的 AI 平台：用自然语言问数、自动生成图表与报告，并管理分析产物，帮助团队更快得到可验证、可复用的结论。
### 项目起源
数据分散在不同系统与文件中时，手写 SQL、手工出图、反复同步口径的成本高且难复用。全源灵动将“提问 → 查询 → 可视化 → 产出”串联为一条可复用的分析链路。
### 项目定位
- 目标用户：业务/数据分析、运营、产品、研发等需要自助分析与报告产出的角色
- 适用场景：NL2SQL 问数、知识库检索增强、自动图表与报告产出、任务委派与跟踪（A2A）
### 核心价值
- 更快：把“写 SQL / 查资料 / 出图”合并为一次对话驱动的分析流程
- 更稳：对关键结果提供可回溯的查询与产物（Artifact）
- 更灵活：支持多数据源与可配置的模型接入
## 整体架构与技术栈
### 系统架构图
```mermaid
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（推荐）
## 项目目录概览
```text
.
├── 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+
### 安装步骤
在项目根目录复制环境配置模板：
```bash
cp .env.example .env
```
### 运行步骤（Docker 全量启动）
```bash
docker compose up -d --build
```
访问地址：
- 前端：`http://localhost:10002/`
- 后端（直连）：`http://localhost:10001/docs`
运行时数据目录：
- 默认挂载 `./data` 到容器内 `/app/data`（对应 `DATA_ROOT=/app/data`），用于存放上传文件、会话与配置等。
### 默认账号
系统首次注册的用户将自动成为管理员（示例：用户名 `admin`，密码 `admin`）。
### 常见问题
- **后端构建失败（APT 连接失败）**：可使用国内镜像构建：
```bash
APT_CN_MIRROR=true docker compose build
```
- **接口返回 401**：需要先登录并携带 `Authorization: Bearer `
- **接口返回 422**：请求体不符合后端 schema（例如 A2A `message:send` 需要 `message.parts[0].data.project_id`）
## 运行示例截图
