ChatBL 是一个 LangGraph 驱动的智能数据分析助手，支持桌面应用和浏览器双模式。用自然语言提问，AI 自动完成：
- 数据可视化 — AI 生成 Python 代码绘制柱状图、折线图、饼图等
- 知识库检索 — 上传文档，基于 RAG（BM25 + 向量混合检索）语义查询
- 智能路由 — Tag 系统自动识别请求类型，分流到对应处理链
- 多轮对话 — 上下文延续、追问、澄清反问
- 图表管理 — 内置图表管理器，预览/下载/批量删除/按时间筛选
适用人群： 业务运营（无需 SQL）、数据科学家（减少重复工作）、产品经理（直接获取数据洞察）
用户 → FastAPI :9008 → Intent Classifier (Tag 匹配)
│
┌──────────┼──────────┐
▼ ▼ ▼
自由对话 数据请求 代码生成
│ │ │
└──────────┼──────────┘
▼
LangGraph Pipeline Agent
(确定性管线 · 4 MCP 服务器)
│
┌──────────┴──────────┐
▼ ▼
Python Chart MCP :9002 RAG MCP :9006
(沙箱代码执行+绘图) (LlamaIndex 混合检索)
│ │
└──────────┬──────────┘
▼
结果/图表 → 前端 SSE 流式渲染
管线阶段： prepare → route_by_type → gen(计划生成) → exec(工具调用) → guards(安全检查) → answer(格式化回复)
Tag 路由： TagMatcher 使用 LLM 语义重排策略，从 TagStore 中匹配最相关标签，决定请求进入自由对话链还是数据请求链。
- 从 GitHub Releases 下载
ChatBL-v0.2.0-windows-x64.zip - 解压，双击
ChatBL.exe - 浏览器自动打开配置页 → 填写 LLM API Key → 保存
- 开始对话
无需安装 Python，无需配置命令行。
# 1. 克隆项目
git clone git@github.com:Fengerss/ChatBL.git
cd ChatBL
# 2. 安装依赖
pip install -r requirements.txt
# 3. 配置环境
cp .env.example .env # 编辑填入 LLM API Key
# 4. 一键启动（桌面窗口 + 后端 + MCP 服务）
python launcher.py
# 或无 GUI 模式（纯浏览器）
CHATBL_NO_GUI=1 python launcher.py浏览器访问 http://localhost:9008，首次使用会自动弹出配置向导。
| 功能 | 示例 | 处理链 |
|---|---|---|
| 自然对话 | "你好"、"今天天气怎么样" | Pipeline → LLM 自然作答 |
| 数据可视化 | "绘制银耳月销量柱状图" | gen_sql → exec_sql → gen_analysis → exec_analysis |
| 代码执行 | "写一段冒泡排序" | Pipeline → Python 沙箱执行 |
| 知识库检索 | "查询销售考核标准" | RAG 混合检索 → LLM 整合 |
| 多轮上下文 | "查银耳销量" → "那按月分组呢" | Tag 系统跨 QA 上下文注入 |
| 澄清反问 | "分析一下数据"（模糊输入） | 图前意图识别 → 选项 → 选择后进图 |
| 图表管理 | 预览/下载/批量删除/按时间筛选 | 侧边栏图表管理面板 |
| Skill 管理 | 新增/导入/扫描 Skill | 侧边栏 Skill 管理面板 |
| 本地数据库 | CSV/Excel 上传、数据预览 | 侧边栏本地数据库面板 |
| 层级 | 技术 | 用途 |
|---|---|---|
| AI Agent | LangGraph + LangChain | 确定性 pipeline（compile → routing → guards） |
| 工具协议 | MCP + 直接 @tool 函数 | MCP（Python/RAG）+ 直接工具（DB/ML） |
| LLM | DeepSeek / 可配置 | 自然语言理解与代码生成 |
| 意图路由 | TagStore + TagMatcher | LLM 语义重排，智能分流 |
| 后端 | FastAPI + Uvicorn | HTTP API + SSE 流式 |
| 前端 | Vanilla JS + Tailwind CSS | 单文件 SPA，零构建依赖 |
| 可视化 | Matplotlib | 图表生成（沙箱安全执行） |
| RAG | LlamaIndex + 豆包 Embedding | BM25 + 向量混合检索 |
| 桌面打包 | pywebview + PyInstaller | 原生窗口 + .exe 分发 |
langGraph_agent/
├── launcher.py # 桌面启动器（一键启动所有服务）
├── start_all.py # 开发环境启动脚本
├── chatbl.spec # PyInstaller 打包配置
├── requirements.txt
├── .env.example # 环境变量模板
│
├── frontend/
│ ├── index.html # Vanilla JS SPA（对话+配置+图表管理）
│ └── icon.ico # 应用图标
│
├── data_agent/
│ ├── chatbi_graph/
│ │ ├── chat_api.py # FastAPI 服务（25+ API 端点）
│ │ ├── prompts.py # Supervisor/Worker LLM 提示词
│ │ ├── intent_classifier.py # 意图分类器 + 置信度门控
│ │ ├── tag_matcher.py # Tag 语义匹配（3 层策略）
│ │ ├── tag_store.py # Tag 持久化存储
│ │ ├── execute_graph.py # CLI 交互模式
│ │ └── llm.py # LLM 单例配置
│ ├── mcp_server/
│ │ ├── python_chart_mcp.py # Python 沙箱 + 绘图 (:9002)
│ │ └── rag_mcp.py # 知识库 RAG (:9006)
│ ├── core/ # Pipeline 核心（compile/nodes/routing/guards）
│ ├── tools/ # 工具函数（SQLite/ML/Common）
│ └── skills/ # 可注入 Skill（6 个预置）
│
├── tests/ # 测试用例（15 个文件）
├── memory/ # 项目记忆（踩坑/模块状态）
├── knowledge_base/ # RAG 知识库文档
├── output_plots/ # 生成的图表
├── docs/ # 设计文档 + 需求分析
├── graphify-out/ # 知识图谱（代码库查询）
└── logs/ # 运行日志
本项目全程采用 Vibe Coding（AI 辅助开发）范式构建。详见 docs/vibe-coding-methodology.md。
核心实践：
- 70/30 法则 — AI 写 70% 代码（样板、UI、测试、文档），人类负责架构/安全/产品决策
- 先建模式再批量生成 — 第一个 MCP 服务器手写，后续由 AI 复制模式
- 设计令牌驱动 UI — CSS 变量定义好后，AI 生成前端界面代码
- 每轮提交都经过代码审查 — AI 生成 → 安全检查 → 测试验证 → 提交
- Fork 本仓库
- 创建特性分支：
git checkout -b feat/your-feature - 运行测试确保通过：
pytest tests/ - 提交代码：
git commit -m "feat: your feature" - 推送并创建 Pull Request
添加新的 MCP 工具：
- 在
data_agent/mcp_server/创建新服务器 - 在
build_graph.py的mcp_server_config中添加配置 - 在
prompts.py中更新相关提示词 - 在
launcher.py的MCP_SERVERS中注册
CC BY-NC-SA 4.0 — 非商业用途
详见 CHANGELOG.md