Velab (Vehicle Laboratory) 是一个面向 FOTA (Firmware Over-The-Air) 故障根因分析 的多智能体（Multi-Agent）智能诊断平台。
该项目通过 LLM 驱动的 Orchestrator 协调多个专项 Agent（日志分析、Jira 检索、文档检索），实现从海量原始数据到结构化诊断结论的自动化流转，并支持 SSE 实时的思维链展示。
- ✅ 多智能体协同诊断: Log Analytics + Jira + Doc Retrieval 三路证据融合
- ✅ 纯 Python async 编排: 高性能、易调试、完全可控
- ✅ 双供应商 Fallback: Claude 主力 + OpenAI 备用，自动切换
- ✅ 时间窗口裁剪: 快速通道 2~5 分钟完成诊断（vs 30 分钟全量解析）
- ✅ 语义缓存: 预估 50~70% 缓存命中率，显著降低成本
- ✅ 防幻觉护栏: 引用 ID 断言验证 + 置信度量化计算
- ✅ 可追溯证据链: 每条结论都能回溯到原始日志行号
- ✅ 生产级部署: systemd + Nginx + 完整运维文档
Velab/
├── backend/ # FastAPI 后端服务
│ ├── agents/ # Agent 实现（Log/Jira/Doc）
│ ├── api/ # RESTful API接口（22个端点）
│ ├── models/ # SQLAlchemy ORM模型
│ ├── services/ # 核心服务（Parser/TimeAlignment/WorkspaceManager）
│ ├── tasks/ # Arq异步任务队列
│ ├── tests/ # API单元测试和集成测试（50+测试用例）
│ ├── data/ # 数据持久化层
│ │ ├── logs/ # 原始日志
│ │ ├── eval/ # 评测用例与报告
│ │ ├── jira_mock/ # Mock Jira 工单数据
│ │ └── workspaces/ # Agent 运行时 Markdown 工作区
│ └── README.md # Backend 部署文档
│
├── gateway/ # LiteLLM API 中转层
│ └── ...
├── web/ # Next.js 前端
│ └── ...
├── docs/ # 项目文档
│ ├── Agent内存_Markdown化重构方案.md # 核心内存架构设计（NEW）
│ ├── Workspace评测基准报告.md # 评测结果与性能基准（NEW）
│ └── ...
└── scripts/ # 统一部署脚本
└── deploy-all.sh # 单机开发环境一键部署
cd gateway
cp .env.example .env
# 编辑 .env，填入真实的 API Keys
./scripts/start.shcd backend
cp .env.example .env
# 编辑 .env，配置 DEPLOYMENT_MODE 和其他参数
./scripts/start-dev.shBackend 开发环境依赖：
- PostgreSQL：默认
127.0.0.1:5432，数据库fota_db - Redis：默认
127.0.0.1:6379
如果本地数据库结构需要重建，可执行：
cd backend
./scripts/reset_db.sh --yes该脚本会删除并重建 fota_db，再基于当前 ORM 模型重新建表。
cd web
npm install
npm run dev默认访问地址为 http://localhost:3000。
如果提示已有 Next.js dev server 正在运行，说明 3000 端口已被现有开发进程占用。此时优先复用现有 3000 进程，或先结束旧进程后再启动。
# Backend 健康检查
curl http://localhost:8000/health
# Web 首页
curl http://localhost:3000/
# Gateway 健康检查（如果启动了）
curl http://localhost:4000/health
# API 文档
open http://localhost:8000/docs详细部署步骤请参考：
┌─────────────────────────────────────┐
│ 中国服务器 │
│ ┌─────────┐ ┌──────────┐ │
│ │ Web前端 │ │ Backend │ │
│ │ Nginx │ │ FastAPI │ │
│ └─────────┘ └──────────┘ │
│ │ │
│ │ HTTPS (跨境) │
└────────────────────┼─────────────────┘
│
▼
┌─────────────────────────────────────┐
│ 美国 CN2 GIA 服务器 │
│ ┌─────────────────────────────┐ │
│ │ Gateway (LiteLLM Proxy) │ │
│ │ - Key Pool 轮转 │ │
│ │ - Fallback 机制 │ │
│ └─────────────────────────────┘ │
└─────────────────────────────────────┘
┌─────────────────────────────────────┐
│ 海外云服务器 │
│ ┌─────────┐ ┌──────────┐ │
│ │ Web前端 │ │ Backend │ │
│ │ Nginx │ │ FastAPI │ │
│ └─────────┘ └──────────┘ │
│ │ │
│ │ 直连（无需中转） │
└────────────────────┼─────────────────┘
│
▼
Claude/OpenAI API
| 模块 | 完成度 | 状态 |
|---|---|---|
| 基础设施与部署 | 100% | ✅ 完成 |
| 离线预处理管线 | 100% | ✅ 完成 |
| 数据库与API | 100% | ✅ 完成 |
| 任务队列集成 | 100% | ✅ 完成 |
| API测试 | 100% | ✅ 完成 |
| MVP核心功能 | 100% | ✅ 完成 |
| 前端交互功能 | 100% | ✅ 完成 |
| Agent 工作区内存重构 (Sprint 5) | 100% | ✅ 完成 |
| 后端核心逻辑（在线诊断增强） | 90% | 🚧 进行中 |
| 数据与演示场景 | 40% | 🚧 进行中 |
| 评测与验收 (基准测试) | 100% | ✅ 完成 |
总体进度: 约 93%
详细任务清单请查看：
- TODO.md - 项目任务清单（最新）
- MVP实施总结报告 - MVP实施详细报告
- P0任务实施进度报告 - P0离线预处理管线实施报告
- CLAUDE.md - 完整项目文档（开发指南、API 文档、部署指南）⭐ 推荐首先阅读
- TODO.md - 项目任务清单（最新进度）
- Agent内存重构方案 - Agent 工作区记忆架构设计文档 ⭐
- Workspace评测报告 - 系统性能与诊断质量基准报告 ⭐
- 日志源类型以真实样本为准：
android、fota_hmi、dlt、mcu、ibdu - Web 上传统一通过 Next.js 代理路由转发到 Backend
- 上传流程依赖 Case 元数据和文件元数据入库，因此 PostgreSQL 不可用时页面上传会失败
- “提交解析”后后端任务会自动执行时间对齐；UI 上“时间对齐”按钮用于手动补跑
- MVP实施总结报告 - MVP实施详细报告 ⭐ 最新完成
- P0任务实施进度报告 - P0离线预处理管线实施报告
- AI专家项目分析报告 - 项目深度分析（⭐⭐⭐⭐⭐ 4.8/5.0）
- FOTA智能诊断平台_可行性方案（修订版v6） - 系统架构设计与可行性分析（最终执行版）
- Backend README - Backend 部署文档
- Gateway README - Gateway 部署文档
- Web README - 前端部署文档
- 生产部署指南 - 生产环境完整部署指南
- FOTA_LLM_API中转方案 - LLM API 中转架构
- LLM_429限流防御方案 - 限流防御策略（五层防御）
| 层次 | 技术 |
|---|---|
| 后端框架 | Python 3.12 + FastAPI |
| AI 编排 | 纯 Python async + OpenAI function-calling |
| LLM 供应商 | Claude（主力）+ OpenAI（Fallback） |
| 任务队列 | Arq（原生 async/await） |
| 数据库 | PostgreSQL |
| 向量检索 | TF-IDF baseline（预留 embedding 接口） |
| 缓存 | Redis |
| 前端框架 | Next.js 16 + React 19 + TypeScript 6 |
| 前端样式 | Tailwind CSS 4 |
| 前端测试 | Vitest 4.1 + React Testing Library 16.3 + MSW 2.12 |
| 服务部署 | Python Virtualenv + Systemd（反 Docker） |
⚠️ 请勿提交任何包含真实 API Key 的.env文件⚠️ .env文件权限应设置为600⚠️ 生产环境必须使用 HTTPS（Let's Encrypt 或 Cloudflare SSL）⚠️ 定期轮换 API Keys⚠️ 原始日志数据需脱敏处理后再送 LLM
如有问题，请查看：
- ✅ 反 Docker：生产部署使用 Systemd 管理 Python 虚拟环境
- ✅ 务实选型：优先选择成熟稳定的技术栈
- ✅ 可追溯性：每个结论都能回溯到原始数据
- ✅ 防幻觉：引用 ID 断言验证 + 置信度量化计算
- ✅ 可观测性：从 Day 1 起内建结构化日志和监控
项目状态: 🚧 开发中（Sprint 4 批量实现已完成，进入部署加固与演示场景准备阶段） 最后更新: 2026-04-13 维护团队: AI 开发专家