DataClaw/README.md

## 项目简介

<video src="../../Videos/Captures/全源灵动_30mb.mp4"></video>

### 项目概述

**全源灵动**是一个面向数据分析与知识检索场景的 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 <token>`
- **接口返回 422**：请求体不符合后端 schema（例如 A2A `message:send` 需要 `message.parts[0].data.project_id`）

## 运行示例截图

![image-20260513161644464](images/image-20260513161644464.png)

![image-20260513161419895](images/image-20260513161419895.png)

![image-20260513161428375](images/image-20260513161428375.png)

![image-20260513161445508](images/image-20260513161445508.png)

![image-20260513162417349](images/image-20260513162417349.png)

![image-20260513161532777](images/image-20260513161532777.png)

![image-20260513161554077](images/image-20260513161554077.png)

![image-20260513161558547](images/image-20260513161558547.png)

![image-20260513161604618](images/image-20260513161604618.png)

![image-20260513161610084](images/image-20260513161610084.png)

![image-20260513161616405](images/image-20260513161616405.png)

![image-20260513161621292](images/image-20260513161621292.png)

![image-20260513161626519](images/image-20260513161626519.png)