释放你的数据潜能，让分析像养龙虾一样简单爽快！ 🌊📊 龙虾问数 (DataClaw) 是一个智能的、AI 驱动的数据分析平台。通过自然语言与你的数据对话，瞬间生成可视化图表，轻松搭建仪表盘——从此告别繁琐的 SQL 语句！
受够了为了画个简单的柱状图而写半天复杂的 SQL 语句吗？龙虾问数就是你的私人数据科学家。借助强大的大语言模型 (LLM) 和智能 Agent 工作流，它能将你的自然语言提问精准转化为数据库查询，提取数据，并即时渲染出美观的可视化图表。
无论你是要查询庞大的 Supabase/PostgreSQL 数据库，还是随手丢进一个 CSV 文件，龙虾问数都能轻松拿捏！🚀
- 🗣️ 自然语言转 SQL: 用大白话提问！它能理解你的数据表结构，生成准确的 SQL，甚至在报错时进行自我纠正 (Self-correction)。
- 📚 智能知识库检索 (RAG): 支持上传 Word、PPT、PDF 等多种格式文档，通过向量检索增强回答，让你的私有文档“开口说话”。
- 📈 即时数据可视化: 拒绝枯燥的生肉表格，根据数据特征自动生成交互式图表。
- 🗂️ 动态多数据源: 无缝连接 PostgreSQL、Supabase，以及本地 CSV/Excel 文件上传解析。
- 🧠 灵活的模型接入: 原生集成 LiteLLM，支持随插随用 OpenAI、DeepSeek、智谱、通义千问 (DashScope)、火山引擎或任何兼容的 LLM 提供商。
- 🛠️ 强大的 Agent 技能拓展: 基于核心
nanobot框架（OpenClaw的精简版）构建。支持通过斜杠命令 (/) 快速调用自定义工具 (Skills)，完美贴合特定业务逻辑。 - 📊 可定制仪表盘 (Dashboard): 一键将对话中生成的图表固定到看板，拖拽布局，随时查看核心指标。
- 📦 智能产物管理 (Artifact): 自动提取对话中生成的各种文件（网页报告、PDF、PPT、图片等），提供一键内嵌预览与下载功能，让成果触手可及。
DataClaw 的架构主要由四个核心部分组成：
frontend/🎨: 闪亮的外壳。基于 React 19、Vite、TailwindCSS 和 Zustand 构建。拥有类似微信/ChatGPT的对话界面、支持流式思考过程渲染以及交互式图表展示。backend/⚙️: 强健的肌肉。一个 FastAPI 后端服务，负责管理项目、数据源连接、用户会话持久化以及作为 API 网关。nanobot/🧠: 智慧的大脑。核心的 AI Agent 框架，负责处理意图路由、NL2SQL 转换、Schema 缓存管理以及与 LLM 的底层交互。data/🗄️: 运行时数据目录。与代码目录解耦，存放上传文件、会话、技能工作区、报告与配置缓存。
graph TD
User([👤 用户 / 浏览器]) -->|HTTP / WebSocket| Frontend
subgraph DataClaw 系统
Frontend[🎨 frontend<br/>React / Vite / Zustand]
Backend[⚙️ backend<br/>FastAPI / 会话 / 数据源管理]
Nanobot[🧠 nanobot<br/>AI Agent / NL2SQL / RAG]
Data[🗄️ data<br/>运行时文件 / 产物缓存]
Frontend -->|REST API / SSE| Backend
Backend <-->|任务委派 / 函数调用| Nanobot
Backend -->|读写| Data
Nanobot -->|读写| Data
end
subgraph 外部服务与数据
LLM([🤖 LLM 供应商<br/>OpenAI, DeepSeek, 智谱等])
DB[(📊 数据源<br/>PostgreSQL, CSV, Supabase等)]
end
Nanobot <-->|Prompt / Completion| LLM
Backend <-->|连接 / 查询| DB
Nanobot -.->|Schema 检索 / SQL 执行| DB
准备好大显身手了吗？让我们把龙虾问数在你的本地跑起来！
在项目根目录下，复制并重命名环境配置模板：
cp .env.example .env请记得编辑根目录下的 .env 文件，填入你的实际配置（如 QQ 邮箱 SMTP 授权码等）。
QQ 邮箱获取 SMTP 授权码最新教程：
- 登录 QQ 邮箱网页版 (mail.qq.com)
- 点击页面顶部的“设置” -> “账号”选项卡
- 向下滚动找到“POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务”
- 确保“POP3/SMTP服务”已点击“开启”
- 点击下方的“生成授权码”，使用手机 QQ 扫码或按提示发送短信
- 验证通过后将获得一串 16位随机字母组合，将其复制填入
.env文件中的SMTP_PASSWORD字段
如需自行打包发布，请按以下顺序执行：先构建前端，再构建后端 wheel，并将产物输出到项目根目录 dist/（与 backend/ 同级）。
# 1) 构建前端静态资源
cd frontend
npm install
npm run build
# 2) 构建后端 wheel，并输出到根目录 dist/
cd ../backend
uv build --wheel --out-dir ../dist构建完成后，wheel 位于项目根目录 dist/，例如 dist/dataclaw-0.1.0-py3-none-any.whl。
请确保你已安装 Python 3.11+ 与 uv。生产模式使用已打包的 wheel（2.1 产物），无需安装 Node.js。
# 在项目根目录创建独立虚拟环境（不依赖 source 激活）
uv venv .venv
source .venv/bin/activate
# 安装已打包的 wheel 到该虚拟环境
uv pip install ./dist/dataclaw-*.whl
# 启动服务（默认 http://127.0.0.1:8000）
dataclaw start常用服务控制命令（同一虚拟环境）：
# 查看运行状态
dataclaw status
# 自定义监听地址/端口
dataclaw start --host 0.0.0.0 --port 8000
# 停止服务
dataclaw stop可选环境变量：
export DATA_ROOT=/absolute/path/to/data若未设置，默认使用仓库根目录下的 data/。服务状态文件与日志默认位于 DATA_ROOT/run/。
如果你要调试代码，请使用开发模式。开发模式直接跑源码，不依赖 wheel。
cd backend
# 安装/同步后端依赖（会在 backend/.venv 中准备环境）
uv sync
# 启动 FastAPI 服务器
uv run uvicorn main:app --reload --port 8000cd frontend
# 安装依赖（仅开发模式需要 Node.js）
npm install
# 启动 Vite 开发服务器
npm run dev提示：请确保 nanobot 核心库已根据项目工作区的要求正确链接或以可编辑模式 (editable mode) 安装。
若你希望使用聊天输入框中的语音输入能力，请单独启动 whisper 服务：
cd whisper
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt
uv run python main.py默认服务地址：http://localhost:8001
健康检查接口：GET /health
前端配置方式：
- 点击左下角用户名，打开菜单；
- 进入「语音输入配置」；
- 填写服务地址（例如
http://localhost:8001）； - 点击「测试连接」通过后保存。
系统首次注册的用户将自动成为管理员。您可以在登录页面直接点击“注册”按钮创建您的管理员账号（例如：用户名 admin，密码 admin），随后即可登录并管理项目、数据源和用户。
A2A（Agent2Agent）用于让 DataClaw 把任务委托给远端 Agent，并保持任务可跟踪（状态流、产物流、取消、重试）。
- 进入 Skills 页面，切到 A2A 标签页。
- 点击新增远端 Agent，填写：
name: 远端 Agent 名称base_url: 远端 DataClaw/A2A 网关地址（如https://agent-b.example.com）auth_scheme:none或bearerauth_token: 当auth_scheme=bearer时填写
- 点击健康检查，确认
healthy=true。 - 回到聊天页，开启 A2A Mode，选择
route_mode与目标 Agent 后发送问题。 - 在消息卡片与 A2A 任务面板中查看
SUBMITTED/WORKING/COMPLETED/FAILED等状态，可执行取消与重试。
route_mode 建议：
auto: 按项目灰度配置与策略自动决策local: 强制本地执行a2a: 强制远端 A2A 执行（需选远端 Agent）a2a_first: 先远端，失败按回退链执行local_first: 先本地，按需再回退
以下示例假设服务地址为 http://127.0.0.1:8000，并已获取登录令牌 ${TOKEN}。
示例 1：查看本机 A2A Agent Card
curl -H "Authorization: Bearer ${TOKEN}" \
http://127.0.0.1:8000/api/v1/a2a/agent-card示例 2：注册远端 Agent
curl -X POST http://127.0.0.1:8000/api/v1/a2a/remote-agents \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"project_id": 1,
"name": "Agent-B",
"base_url": "https://agent-b.example.com",
"auth_scheme": "bearer",
"auth_token": "remote-agent-token"
}'示例 3：以 A2A 优先模式发起任务
curl -X POST http://127.0.0.1:8000/api/v1/a2a/messages/send \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"project_id": 1,
"message": "请分析最近30天订单转化趋势并给出建议",
"session_id": "chat:demo-a2a",
"remote_agent_id": 3,
"route_mode": "a2a_first",
"fallback_chain": ["a2a", "local", "mcp"],
"idempotency_key": "demo-a2a-001"
}'返回结果中的 task.id 可用于订阅与管理任务。
示例 4：订阅任务流（SSE）
curl -N -H "Authorization: Bearer ${TOKEN}" \
http://127.0.0.1:8000/api/v1/a2a/tasks/<task_id>/subscribe你会收到类似事件：
TaskStatusUpdateEvent（状态变更）TaskArtifactUpdateEvent（产物更新）done（流结束）
示例 5：取消任务
curl -X POST -H "Authorization: Bearer ${TOKEN}" \
http://127.0.0.1:8000/api/v1/a2a/tasks/<task_id>/cancel示例 6：为任务配置 Webhook 回调（离线接收结果）
curl -X POST http://127.0.0.1:8000/api/v1/a2a/tasks/<task_id>/webhooks \
-H "Authorization: Bearer ${TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"target_url": "https://your-system.example.com/a2a/webhook",
"secret": "your-webhook-secret",
"auth_header": "Bearer your-internal-token"
}'场景：你有一个“本地数据分析 Agent”，还接入了“外部行业知识 Agent-B”。
- 在 Skills -> A2A 注册
Agent-B并完成健康检查。 - 在聊天页开启 A2A，选择
route_mode=a2a_first。 - 输入问题：
请结合外部行业知识与本地销量数据，生成本季度增长策略。 - 系统先尝试委托给
Agent-B；若远端异常则按回退链降级到本地/MCP。 - 在任务面板查看状态流与最终产物，必要时可取消或重试。
生产建议：
- 对业务侧请求始终传
idempotency_key，避免重复任务。 - 为长任务配置 webhook，避免客户端断线丢失进度。
- 在项目级 rollout 配置灰度比例，先小流量启用 A2A 再全量放开。
推荐在本机同时启动两个后端实例：
- 实例 A（调用方）：
http://127.0.0.1:8000 - 实例 B（被调用远端 Agent）：
http://127.0.0.1:8001
分别用两个终端启动（建议使用不同 DATA_ROOT，避免数据目录冲突）：
# 终端1：实例 A
cd backend
DATA_ROOT=/tmp/dataclaw-a uv run uvicorn main:app --reload --port 8000# 终端2：实例 B
cd backend
DATA_ROOT=/tmp/dataclaw-b uv run uvicorn main:app --reload --port 8001然后在两个实例分别注册并登录，拿到 token：
# 分别注册（每个实例首次注册用户会成为管理员）
curl -X POST http://127.0.0.1:8000/api/v1/auth/register \
-H "Content-Type: application/json" \
-d '{"username":"admin_a","email":"a@test.com","password":"admin12345"}'
curl -X POST http://127.0.0.1:8001/api/v1/auth/register \
-H "Content-Type: application/json" \
-d '{"username":"admin_b","email":"b@test.com","password":"admin12345"}'
# 登录并保存 token
TOKEN_A=$(curl -s -X POST http://127.0.0.1:8000/api/v1/auth/login \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "username=admin_a&password=admin12345" | jq -r '.access_token')
TOKEN_B=$(curl -s -X POST http://127.0.0.1:8001/api/v1/auth/login \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "username=admin_b&password=admin12345" | jq -r '.access_token')最后，在实例 A 中把实例 B 注册成远端 Agent（auth_token 使用 TOKEN_B）：
curl -X POST http://127.0.0.1:8000/api/v1/a2a/remote-agents \
-H "Authorization: Bearer ${TOKEN_A}" \
-H "Content-Type: application/json" \
-d "{
\"project_id\": 1,
\"name\": \"local-agent-b\",
\"base_url\": \"http://127.0.0.1:8001\",
\"auth_scheme\": \"bearer\",
\"auth_token\": \"${TOKEN_B}\"
}"完成后即可在实例 A 发起 A2A 任务、订阅任务流、取消任务，完成本地端到端联调。
DataClaw 支持连接多种类型的数据源，以满足不同场景的分析需求。你可以在界面的 Data Sources 菜单中点击 + 新建并配置它们。以下是常见数据源的详细接入指南：
▶ PostgreSQL (pgsql)
连接标准的关系型数据库。你既可以通过表单填充分散的参数，也可以直接粘贴完整的 Connection String。
- Host: 数据库的主机地址。如果你是在本地电脑运行了数据库（如使用 pgAdmin），请填入
127.0.0.1（不要填localhost，以避免 Unix Socket 解析错误）。 - Port: 默认一般为
5432。 - Database: 你要连接的具体数据库名称。
- Username / Password: 数据库的认证凭据（默认用户通常是
postgres）。 - Connection String (可选): 也可以直接输入类似
postgresql://postgres:你的密码@127.0.0.1:5432/你的数据库名的字符串，它将覆盖上述单独的输入框配置。
▶ Supabase
专门针对 Supabase 云端 PostgreSQL 数据库优化的连接方式，强制开启 SSL 且默认使用连接池以提高稳定性。
- 推荐直接使用 Connection String 配置：
进入你的 Supabase 项目控制台 ->
Project Settings->Database->Connection string-> 选择URI选项卡。 复制那串类似postgresql://postgres.[project-ref]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres?sslmode=require的链接并填入。 - 注意: Supabase 默认开启了 Transaction Pooler（端口 6543）。如果想要直连（Direct connection），请将端口改为
5432，并确保 URL 中包含sslmode=require。
▶ SQLite
轻量级的本地文件型数据库，非常适合快速测试或分析单机应用数据。
- File Upload: 你可以直接点击按钮，从本地上传
.db、.sqlite或.sqlite3后缀的数据库文件。文件会被安全地保存在服务端的上传目录中供分析使用。 - File Path (进阶): 如果服务部署在服务器上，且 SQLite 文件已存在于服务器的某个绝对路径中，你也可以直接在输入框中填入该文件的绝对路径（如
/data/my_app.db）。
▶ CSV
最常见的数据交换格式，即插即用，无需复杂的数据库配置。
- File Upload: 与 SQLite 类似，点击按钮选择本地的
.csv文件上传即可。系统会在后台利用 DuckDB 或 Pandas 等引擎将其虚拟化为一个可供 SQL 查询的表。 - 上传成功后，在对话界面中，你可以直接把这个 CSV 文件当作一张数据库表来“提问”！
有个好点子？发现了一个 Bug？非常欢迎你的加入！随时可以提交 Issue 或 Pull Request。让我们一起让数据分析变得更加有趣！
DataClaw 的开发深受以下优秀开源项目的启发，特此致谢：