导读

本栏目是一套「数据分析 AI Agent 平台」的架构与设计文档（已做脱敏处理，用于个人复习）。平台是一个 FastAPI + Vue 3 全栈的数据分析系统，核心能力包括自然语言转 SQL（NL2SQL）、指标语义查询、归因分析、告警检测、固定看板、报表订阅，以及把 Agent 能力以 MCP 协议对内对外暴露。

按阅读顺序建议：

1. AI Agent 设计 —— 平台的 Agent 总体架构：Supervisor 模式、Tool-Calling、记忆机制、Skill 机制与 Prompt 系统。
2. Agent 查询层架构 —— 自然语言到数据查询的「分类 → 路由 → 生成/复用 → 执行 → 归一化」五阶段流水线。
3. MCP 设计 —— MCP Server/Client 双重角色：能力暴露与外部工具扩展、三层认证。
4. Worker 架构 —— 独立进程 + APScheduler 的 Worker 模型：告警、报表、ETL、看板预热、事件分析。
5. 数据中心接入设计方案 —— Repo 双轨数据、Redis 缓存、ETL 同步与降级策略。
6. 权限设计与权限矩阵 —— 角色体系、权限键清单、权限矩阵与 Agent/MCP 权限边界。
7. 日志系统架构 —— 目录级进程隔离的日志系统与查询工具。
8. API 接口文档 —— /api/v1/* 路由结构、契约对齐机制与高风险协议说明。
9. 评测体系总览 —— CI 门禁、Benchmark、E2E/Live Regression、效果评测与上线验收的五层体系。

说明：文档中的「示例业务 / game_a / region_a / dc.example.com」等为脱敏占位符；代码路径、表名、环境变量等保留原名。