|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Plan Mode |
| 6 | + |
| 7 | +When in plan mode, always write plan files to the project directory `.claude/plans/` instead of the default `~/.claude/plans/`. Use descriptive filenames based on the task topic (e.g., `common-agent-refactor-skill-mcp.md`). |
| 8 | + |
| 9 | +## Build & Run Commands |
| 10 | + |
| 11 | +```bash |
| 12 | +# Backend - start dev server (Sanic on port 8088) |
| 13 | +python serv.py |
| 14 | + |
| 15 | +# Backend - install dependencies |
| 16 | +uv add <package> --frozen # add new dependency without upgrading existing ones |
| 17 | +uv pip freeze > requirements.txt # regenerate lockfile after changes |
| 18 | + |
| 19 | +# Frontend - dev server |
| 20 | +cd web && pnpm install && pnpm dev |
| 21 | + |
| 22 | +# Docker |
| 23 | +make up # start services (docker-compose) |
| 24 | +make down # stop services |
| 25 | +make logs # view logs |
| 26 | +make build # build app image (~30s, requires base image) |
| 27 | +make build-base # rebuild base image (only when deps change) |
| 28 | + |
| 29 | +# Code formatting |
| 30 | +black . # line-length=88, target py311 |
| 31 | + |
| 32 | +# Tests (ad-hoc, organized by feature under tests/) |
| 33 | +python -m pytest tests/<subdir>/<test_file>.py |
| 34 | +``` |
| 35 | + |
| 36 | +## Architecture |
| 37 | + |
| 38 | +**Aix-DB** is an LLM-powered data analysis platform (ChatBI). Users ask questions in natural language; the system generates SQL, executes it, and returns visualized results. |
| 39 | + |
| 40 | +### Backend (Python 3.11, Sanic) |
| 41 | + |
| 42 | +``` |
| 43 | +serv.py # Entry point - Sanic app, autodiscovers controllers |
| 44 | +├── controllers/ # REST API blueprints (auto-registered via autodiscover) |
| 45 | +│ ├── llm_chat_api.py # Main chat endpoint: POST /dify/get_answer (SSE streaming) |
| 46 | +│ ├── db_chat_api.py # Database Q&A endpoints |
| 47 | +│ ├── skill_api.py # GET /system/skill/list |
| 48 | +│ └── datasource_api.py # Datasource CRUD |
| 49 | +├── services/ |
| 50 | +│ └── llm_service.py # Routes requests by qa_type to appropriate agent |
| 51 | +├── agent/ # Four independent agent systems |
| 52 | +│ ├── common_react_agent.py # COMMON_QA - general chat (LangChain + MCP) |
| 53 | +│ ├── text2sql/ # DATABASE_QA - Text-to-SQL (LangGraph StateGraph) |
| 54 | +│ ├── excel/ # FILEDATA_QA - Excel analysis (DuckDB) |
| 55 | +│ └── deepagent/ # REPORT_QA - deep research (deepagents library) |
| 56 | +│ ├── AGENTS.md # Agent instructions (loaded as memory) |
| 57 | +│ ├── skills/ # SKILL.md instruction documents |
| 58 | +│ └── tools/ # SQL tools + ToolCallManager (loop prevention) |
| 59 | +├── model/ # SQLAlchemy models + Pydantic schemas |
| 60 | +├── common/ # Utilities (LLM, MinIO, crypto, datasource connections) |
| 61 | +└── config/ # Environment loading, logging config |
| 62 | +``` |
| 63 | + |
| 64 | +### Request Flow (Chat) |
| 65 | + |
| 66 | +``` |
| 67 | +POST /dify/get_answer { query, qa_type, chat_id, datasource_id, ... } |
| 68 | + → llm_service.LLMRequest.exec_query() |
| 69 | + → qa_type routing: |
| 70 | + COMMON_QA → CommonReactAgent.run_agent() |
| 71 | + DATABASE_QA → Text2SqlAgent.run_agent() |
| 72 | + FILEDATA_QA → ExcelAgent.run_excel_agent() |
| 73 | + REPORT_QA → DeepAgent.run_agent() |
| 74 | + → SSE streaming response: data:{data:{messageType,content},dataType}\n\n |
| 75 | +``` |
| 76 | + |
| 77 | +### Agent Systems (independent, do not share code between them) |
| 78 | + |
| 79 | +- **Text2SqlAgent**: LangGraph StateGraph pipeline (datasource_selector → schema_inspector → sql_generator → permission_filter → sql_executor → chart_generator → summarizer) |
| 80 | +- **DeepAgent**: `deepagents.create_deep_agent()` with skills, multi-phase tracking (PLANNING→EXECUTION→SUB_AGENT→REPORTING), `<details>` HTML for thinking visibility |
| 81 | +- **CommonReactAgent**: `langchain.agents.create_agent()` with MCP tools via `MultiServerMCPClient` |
| 82 | +- **ExcelAgent**: Parses Excel to DuckDB, then SQL analysis pipeline |
| 83 | + |
| 84 | +### Frontend (Vue 3 + TypeScript + Vite) |
| 85 | + |
| 86 | +``` |
| 87 | +web/src/ |
| 88 | +├── views/chat/index.vue # Main chat interface (~3700 lines) |
| 89 | +├── views/skill-center.vue # Skill browsing page |
| 90 | +├── api/index.ts # Chat API (SSE fetch to /sanic/dify/get_answer) |
| 91 | +├── store/business/index.ts # Pinia store (qa_type, file_list, task_id) |
| 92 | +└── components/MarkdownPreview/ # Renders markdown + HTML (including <details>) |
| 93 | +``` |
| 94 | + |
| 95 | +### Key Patterns |
| 96 | + |
| 97 | +- **SSE format**: All agents stream responses as `data:{"data":{"messageType":"continue","content":"..."},"dataType":"t02"}\n\n` |
| 98 | +- **dataType values**: `t02` (text answer), `t04` (business/chart data), `t09` (stream end) |
| 99 | +- **Datasource support**: MySQL, PostgreSQL, Oracle, SQL Server, ClickHouse, DM, Doris, StarRocks (via SQLAlchemy or native drivers) |
| 100 | +- **MCP integration**: External mcp-hub service, configured via `MCP_HUB_COMMON_QA_GROUP_URL` env var |
| 101 | +- **Skills**: Markdown instruction documents (`SKILL.md` with YAML frontmatter) loaded as LLM context, not executable tools |
| 102 | +- **Auth**: JWT tokens in `Authorization: Bearer <token>` header, decoded via `services/user_service.decode_jwt_token()` |
| 103 | + |
| 104 | +### Environment |
| 105 | + |
| 106 | +Key env vars (see `.env.dev` and `docker/docker-compose.yaml`): |
| 107 | +- `DATABASE_URL` - PostgreSQL connection for app metadata |
| 108 | +- `LLM_MODEL_NAME`, `LLM_API_KEY`, `LLM_API_BASE` - LLM configuration |
| 109 | +- `MINIO_*` - File storage |
| 110 | +- `MCP_HUB_COMMON_QA_GROUP_URL` - MCP tool hub endpoint |
| 111 | +- `LANGFUSE_TRACING_ENABLED` - Enable observability tracing |
0 commit comments