SQLBot/AGENTS.md

SQLBot Agent 指南

SQLBot 让业务用户用自然语言提问，基于已配置的数据源生成并安全执行 SQL，返回数据、图表、分析和后续问题建议。领域词汇表见 CONTEXT.md。

仓库结构

路径	职责
backend/	Python 3.11 / FastAPI / SQLModel 后端。main.py 组装应用、MCP、中间件、静态资源和 xpack；业务域在 apps/，共享代码在 common/，迁移在 alembic/versions/，全部测试（含仓库守卫）在 tests/。
frontend/	Vue 3、TypeScript strict、Vite、Pinia、Vue Router 和 Element Plus。请求在 src/api/，共享实体在 src/entity/，状态在 src/stores/，路由在 src/router/，UI 在 src/views/ 和 src/components/。
g2-ssr/	Node.js 图表渲染服务，使用 @antv/g2-ssr；图表实现位于 charts/，目录内有独立 AGENTS.md。
installer/	离线安装、卸载、配置模板和服务控制脚本。
Dockerfile*、docker-compose.yaml、start.sh	容器组装和运行时进程启动。

商业扩展源码维护在独立仓库 dataease/sqlbot-xpack。它不是 submodule，也不是本仓库的固定子目录。本地 sqlbot-xpack/ checkout 会被主仓库忽略，永远不应出现在本仓库 PR 中。

xpack 工作流

默认使用开源版 SQLBot 工作流：把 sqlbot-xpack 视为版本范围由 backend/pyproject.toml 约束的已发布 wheel（精确版本冻结在不入库的 uv.lock）。不读取、不修改本地 xpack checkout。

只有任务确实需要修改或调试闭源 xpack 代码，或需要两个仓库联动验证时，才按 docs/agents/xpack.md 检查本地关联开关（AGENTS.local.env）并协调两个仓库的变更。

按需文档

触发条件	必读文档
修改业务逻辑、数据模型（SQLModel）、权限、Chat 问题流程、助手集成、前端信息架构，或需要命名和领域术语	CONTEXT.md
修改后端业务代码	docs/agents/backend.md
修改前端代码	docs/agents/frontend.md
修改或新增测试、执行验证	docs/agents/testing.md
修改用户可见文案或新增语言	docs/agents/i18n.md
修改认证、授权、SQL 执行、上传/下载、嵌入协议或前端渲染安全	docs/agents/security.md
修改 SQLModel 模型或 Alembic 迁移	docs/agents/migrations.md
修改 Dockerfile、installer、GitHub Actions 或发布产物	docs/agents/packaging.md
修改或调试闭源 xpack 代码、双仓库联动验证	docs/agents/xpack.md
修改图表渲染服务、后端图表配置或图表字段/输出契约	g2-ssr/AGENTS.md
领域边界仍不明确	docs/agents/domain-open-questions.md，并向使用者确认

全局硬规则

• 在正确仓库检查 status/diff；SQLBot 主仓库和 xpack 独立仓库不要混出同一个提交。
• 不要提交日志、构建产物、.env 值、密钥、本地路径、私有 registry 配置或生成的 xpack 产物。
• 提交信息和 PR 描述不添加 Co-Authored-By、"Generated with" 等任何 AI 工具署名行。
• 提交信息沿用仓库既有 conventional 风格：fix:、feat:、refactor: 等前缀（可带 scope），单行概述。
• 不要为了通过测试削弱安全守卫；安全、权限、SQL、Host、路径和嵌入认证改动必须有相关回归验证。
• 修改 Docker、installer 或路径配置时，核对前端构建产物、后端工作目录、/opt/sqlbot 数据目录、图表输出和日志挂载仍然一致。
• 依赖、lockfile 和版本号只在任务明确需要时更新；不要顺手刷新。
• 验证以构建和测试为准；除非用户明确要求，不构建 Docker 镜像、不启动完整运行栈。
• 除非用户明确要求，不要上传、发布或推送镜像 / wheel / 包。
• 变更涉及本文件或 docs/agents/ 描述的约定（目录职责、命令、流程）时，同步更新对应文档。