{"id":49511832,"url":"https://github.com/secary/chat-bi","last_synced_at":"2026-05-01T20:04:21.864Z","repository":{"id":354360086,"uuid":"1223241177","full_name":"secary/chat-bi","owner":"secary","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-28T07:32:57.000Z","size":2196,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-28T09:27:58.809Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/secary.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-28T06:18:49.000Z","updated_at":"2026-04-28T07:33:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/secary/chat-bi","commit_stats":null,"previous_names":["secary/chat-bi"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/secary/chat-bi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/secary%2Fchat-bi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/secary%2Fchat-bi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/secary%2Fchat-bi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/secary%2Fchat-bi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/secary","download_url":"https://codeload.github.com/secary/chat-bi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/secary%2Fchat-bi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32510823,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-01T20:04:20.661Z","updated_at":"2026-05-01T20:04:21.854Z","avatar_url":"https://github.com/secary.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 零眸智能 ChatBI\n\n面向银行业务场景的对话式数据分析 Demo，让用户用中文自然语言完成问数、文件导入、语义别名维护和经营决策建议生成。\n\n## 快速开始（Docker 全栈）\n\n生产式本地运行会构建前端静态产物，并由 nginx 提供页面：\n\n```bash\n# 1. 复制环境变量模板，填入 LLM API Key\ncp .env.example .env\n\n# 2. 启动所有服务\ndocker compose up -d --build\n\n# 3. 浏览器访问\nopen http://localhost:5173\n```\n\n服务端口：\n\n| 服务 | 宿主机端口 |\n|------|-----------|\n| frontend | 5173 |\n| backend | 8000 |\n| MySQL | 3307 |\n\n容器名前缀为 `chatbi-prod-*`，项目名为 `chatbi-prod`。\n\n## 本地开发启动\n\n### 方式 A：Docker 热更新\n\n推荐日常开发使用，前后端源码会挂载进容器：\n\n```bash\ndocker compose --env-file .env.dev -f docker-compose.dev.yml up -d --build\n\n# 浏览器访问\nopen http://localhost:5174\n```\n\n开发环境端口：\n\n| 服务 | 宿主机端口 |\n|------|-----------|\n| frontend | 5174 |\n| backend | 8001 |\n| MySQL | 3308 |\n\n- 修改 `backend/` 或 `skills/`：后端自动 reload，无需重建镜像。\n- 修改 `frontend/`：Vite 自动热更新，无需重建镜像。\n- 修改依赖文件、Dockerfile 或系统依赖：需要重新 `--build`。\n- 修改 `database/init.sql`：已有 `database/mysql-data-dev/` 不会自动重放，需重置开发数据目录后再启动。\n- 容器名前缀为 `chatbi-dev-*`，可以和生产式本地运行并存。\n\n### 方式 B：宿主机启动前后端\n\n```bash\n# Backend\npython -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -r requirements.txt\nuvicorn backend.main:app --reload --port 8000\n\n# Frontend（另开终端）\ncd frontend \u0026\u0026 npm install \u0026\u0026 npm run dev\n```\n\nMySQL 仍需 Docker：\n\n```bash\ndocker compose up -d demo-mysql\n```\n\n## 技术栈\n\n| 层 | 技术 |\n|----|------|\n| 前端 | React 18 + TypeScript + Vite + Tailwind CSS + ECharts 5 |\n| 后端 | FastAPI + Python 3.11 + LiteLLM |\n| 数据库 | MySQL 8.0（Docker） |\n| 流式 | Server-Sent Events（SSE） |\n| 质量 | black + ruff；ESLint + Prettier |\n\n## 项目结构\n\n```\nchat-bi/\n├── AGENTS.md                        # AI Agent 项目地图（规则事实源）\n├── CLAUDE.md                        # 指向 AGENTS.md 的入口\n├── .env.example                     # 环境变量模板\n├── docker-compose.yml               # 生产式本地：MySQL + Backend + Frontend\n├── docker-compose.dev.yml           # 开发热更新编排\n├── data/\n│   └── chatbi_sales.csv             # 示例销售数据（文件导入演示用）\n├── database/\n│   └── init.sql                     # 表结构、演示数据、语义层元数据\n├── backend/\n│   ├── main.py                      # FastAPI 入口，POST /chat SSE + POST /upload\n│   ├── config.py                    # 环境变量读取（业务库 + 日志库）\n│   ├── trace.py                     # Trace-ID 链路日志写入（best-effort）\n│   ├── agent/\n│   │   ├── protocol.py              # SkillResult 统一协议定义\n│   │   ├── prompt_builder.py        # 读取 SKILL.md，构造 System Prompt\n│   │   ├── planner.py               # LiteLLM 调用，生成 Skill 执行计划\n│   │   ├── executor.py              # 定位并执行 Skill 脚本，归一化结果\n│   │   ├── formatter.py             # SkillResult → SSE 消息\n│   │   └── runner.py                # plan → execute → format 主循环\n│   └── renderers/\n│       ├── chart.py                 # 构造 ECharts option\n│       └── kpi.py                   # 构造 KPI 卡片数据\n├── frontend/\n│   └── src/\n│       ├── types/message.ts         # 消息类型定义\n│       ├── api/client.ts            # SSE 流式客户端（透传 X-Trace-Id）\n│       ├── hooks/useChat.ts         # 对话状态管理\n│       └── components/\n│           ├── MessageBubble.tsx    # 消息分发渲染\n│           ├── ThinkingBubble.tsx   # 思考步骤（可折叠）\n│           ├── ChartRenderer.tsx    # ECharts 图表\n│           ├── KPICards.tsx         # KPI 卡片\n│           └── ChatInput.tsx        # 输入框（支持文件拖拽/选择）\n├── skills/\n│   ├── _shared/                     # 脚本共用的数据库连接与协议输出工具\n│   ├── chatbi-semantic-query/       # 自然语言问数\n│   ├── chatbi-alias-manager/        # 语义别名管理\n│   ├── chatbi-decision-advisor/     # 经营决策建议\n│   └── chatbi-file-ingestion/       # CSV/XLSX 文件导入校验\n└── tests/\n    ├── test_agent_skill_protocol.py # SkillResult 协议单测\n    ├── test_file_ingestion_skill.py # 文件导入 Skill 单测\n    ├── test_trace_logging.py        # 链路日志单测\n    └── test_upload_api.py           # 上传接口单测\n```\n\n## 架构流程\n\n```\n用户输入（文字 / 文件）\n  → React 前端（透传 X-Trace-Id）\n  ┌─ POST /upload → 文件校验 → 返回预览 JSON（chatbi-file-ingestion Skill）\n  └─ POST /chat（SSE）\n       → FastAPI → AgentRunner\n           → prompt_builder 读取 skills/*/SKILL.md\n           → planner 生成 Skill 执行计划（LiteLLM）\n           → executor 执行 Skill 脚本 → MySQL chatbi_demo\n           → 统一 SkillResult 协议（kind / text / data / charts / kpis）\n           → formatter 转换为 SSE 消息\n           → renderers 构造 ECharts option / KPI 卡片\n       → SSE 流式返回\n  → 前端渲染（thinking / text / chart / kpi_cards / error）\n  → trace.py 将各节点日志写入 MySQL chatbi_logs（best-effort）\n```\n\n## Skills\n\n| Skill | 功能 |\n|-------|------|\n| `chatbi-semantic-query` | 将自然语言转换为 SQL，查询 `chatbi_demo` 并返回表格与图表 |\n| `chatbi-alias-manager` | 维护 `alias_mapping`，将业务别名映射到标准字段名 |\n| `chatbi-decision-advisor` | 先计算指标事实，再按确定性规则生成经营决策建议 |\n| `chatbi-file-ingestion` | 读取 CSV/XLSX，识别表头、校验类型并返回预览 JSON |\n\n每个 Skill 的触发条件、工作流和安全边界见 `skills/\u003cskill-name\u003e/SKILL.md`。\n\n## 环境变量\n\n关键变量见 `.env.example`：\n\n| 变量 | 说明 |\n|------|------|\n| `LLM_MODEL` | LiteLLM 模型名（如 `gpt-4o-mini`、`MiniMax-M2.7`） |\n| `OPENAI_API_KEY` | LLM API Key |\n| `API_BASE` | LLM API Base URL（可选，OpenAI-compatible 代理用） |\n| `CHATBI_DB_HOST` | 业务库主机（容器内默认 `demo-mysql`） |\n| `CHATBI_DB_PORT` | 业务库端口（容器内默认 `3306`） |\n| `CHATBI_DB_USER` | 业务库用户（默认 `demo_user`） |\n| `CHATBI_DB_PASSWORD` | 业务库密码（默认 `demo_pass`） |\n| `CHATBI_DB_NAME` | 业务库库名（默认 `chatbi_demo`） |\n| `CHATBI_LOG_DB_HOST` | 日志库主机（未配置时回退到业务库） |\n| `CHATBI_LOG_DB_PORT` | 日志库端口 |\n| `CHATBI_LOG_DB_USER` | 日志库用户 |\n| `CHATBI_LOG_DB_PASSWORD` | 日志库密码 |\n| `CHATBI_LOG_DB_NAME` | 日志库库名（默认 `chatbi_logs`） |\n| `FRONTEND_API_BASE_URL` | 前端指向的后端地址（默认 `http://localhost:8000`） |\n\n环境文件建议：\n\n| 环境 | env 文件 | Compose |\n|------|----------|---------|\n| 生产式本地 / 测试 | `.env` | `docker-compose.yml` |\n| 开发热更新 | `.env.dev`（本地，Git 忽略） | `docker-compose.dev.yml` |\n\n## 开发文档\n\n| 主题 | 路径 |\n|------|------|\n| Agent 规则与工作方式 | [AGENTS.md](AGENTS.md) |\n| 系统架构与模块边界 | [docs/architecture/README.md](docs/architecture/README.md) |\n| 编码规范 | [docs/conventions/README.md](docs/conventions/README.md) |\n| 当前迭代任务 | [docs/plans/current-sprint.md](docs/plans/current-sprint.md) |\n| 项目目标与验收标准 | [docs/goal.md](docs/goal.md) |\n| Skill 能力说明 | `skills/\u003cskill-name\u003e/SKILL.md` |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsecary%2Fchat-bi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsecary%2Fchat-bi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsecary%2Fchat-bi/lists"}