ChatBL

---

项目概述

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 中匹配最相关标签，决定请求进入自由对话链还是数据请求链。

---

快速开始

桌面应用（推荐）

1. 从 GitHub Releases 下载 ChatBL-v0.2.0-windows-x64.zip
2. 解压，双击 ChatBL.exe
3. 浏览器自动打开配置页 → 填写 LLM API Key → 保存
4. 开始对话

无需安装 Python，无需配置命令行。

开发者模式

# 1. 克隆项目
git clone [email protected]: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 方法论

本项目全程采用 Vibe Coding（AI 辅助开发）范式构建。详见 docs/vibe-coding-methodology.md。

核心实践：

• 70/30 法则 — AI 写 70% 代码（样板、UI、测试、文档），人类负责架构/安全/产品决策
• 先建模式再批量生成 — 第一个 MCP 服务器手写，后续由 AI 复制模式
• 设计令牌驱动 UI — CSS 变量定义好后，AI 生成前端界面代码
• 每轮提交都经过代码审查 — AI 生成 → 安全检查 → 测试验证 → 提交

---

贡献指南

1. Fork 本仓库
2. 创建特性分支：git checkout -b feat/your-feature
3. 运行测试确保通过：pytest tests/
4. 提交代码：git commit -m "feat: your feature"
5. 推送并创建 Pull Request

添加新的 MCP 工具：

1. 在 data_agent/mcp_server/ 创建新服务器
2. 在 build_graph.py 的 mcp_server_config 中添加配置
3. 在 prompts.py 中更新相关提示词
4. 在 launcher.py 的 MCP_SERVERS 中注册

---

许可证

CC BY-NC-SA 4.0 — 非商业用途

更新日志

详见 CHANGELOG.md