zhaojie
11eef49271
- 新增 .agents/summary/ 完整文档（架构、组件、接口、数据模型、流程、依赖） - 新增 AGENTS.md（AI 助手导航） - 更新 README.md - 修复 dashboard.html 租户模态框多余 </div> 导致保存按钮失效 - 更新 .gitignore 排除虚拟环境文件
97 lines
3.9 KiB
Markdown
97 lines
3.9 KiB
Markdown
# AGENTS.md — TSP 智能助手
|
||
|
||
> AI 助手代码导航指南。详细文档见 `.agents/summary/index.md`。
|
||
|
||
## 项目概述
|
||
|
||
TSP 智能助手是一个 AI 驱动的多租户客服与工单管理系统。Python 3.11+ / Flask 3.x / SQLAlchemy 2.x。入口文件 `start_dashboard.py`。
|
||
|
||
## 目录导航
|
||
|
||
```
|
||
src/
|
||
├── config/unified_config.py # UnifiedConfig 单例，所有配置从 .env 加载
|
||
├── core/
|
||
│ ├── models.py # 所有 SQLAlchemy ORM 模型（11 个表）
|
||
│ ├── database.py # DatabaseManager 单例，session 管理
|
||
│ ├── llm_client.py # LLMClient — OpenAI-compatible API (Qwen)
|
||
│ ├── auth_manager.py # JWT + SHA-256 认证
|
||
│ ├── cache_manager.py # Redis 缓存
|
||
│ └── vector_store.py # Embedding 向量存储
|
||
├── dialogue/
|
||
│ ├── dialogue_manager.py # 核心对话处理，调用 LLM + 知识库
|
||
│ └── realtime_chat.py # WebSocket 实时聊天管理
|
||
├── knowledge_base/
|
||
│ └── knowledge_manager.py # 知识库 CRUD + TF-IDF/Embedding 搜索
|
||
├── integrations/
|
||
│ ├── feishu_service.py # 飞书 API 客户端
|
||
│ ├── feishu_longconn_service.py # 飞书长连接事件订阅
|
||
│ └── workorder_sync.py # 工单 ↔ 飞书多维表格双向同步
|
||
├── agent/react_agent.py # ReAct Agent（工具调度循环）
|
||
├── analytics/
|
||
│ ├── analytics_manager.py # 数据分析
|
||
│ └── alert_system.py # 预警规则引擎
|
||
└── web/
|
||
├── app.py # Flask 应用工厂 + 路由
|
||
├── service_manager.py # 懒加载服务注册中心
|
||
├── decorators.py # @handle_errors, @require_json, @resolve_tenant_id, @rate_limit
|
||
├── websocket_server.py # 独立 WebSocket 服务器 (port 8765)
|
||
└── blueprints/ # 16 个 Flask Blueprint（每个领域一个文件）
|
||
```
|
||
|
||
## 关键模式
|
||
|
||
### 多租户
|
||
所有核心表含 `tenant_id` 字段。`@resolve_tenant_id` 装饰器从请求中提取。查询时必须过滤 `tenant_id`。
|
||
|
||
### 服务获取
|
||
Blueprint 通过 `ServiceManager` 懒加载获取服务实例，不要直接实例化业务类。
|
||
|
||
### API 装饰器栈
|
||
典型 API 端点模式：
|
||
```python
|
||
@bp.route('/api/xxx', methods=['POST'])
|
||
@handle_errors()
|
||
@require_json(['field1', 'field2'])
|
||
def create_xxx():
|
||
...
|
||
```
|
||
|
||
### 配置
|
||
所有配置通过 `get_config()` 获取，从 `.env` 加载。不要硬编码配置值。参考 `.env.example` 了解所有可用变量。
|
||
|
||
## 入口与启动
|
||
|
||
- `start_dashboard.py` — 主入口，启动 Flask + WebSocket + 飞书长连接（3 个线程）
|
||
- `start_feishu_bot.py` — 独立飞书机器人入口
|
||
- `init_database.py` — 数据库初始化
|
||
|
||
## 数据库
|
||
|
||
- 开发: SQLite (`data/tsp_assistant.db`)
|
||
- 生产: MySQL via PyMySQL
|
||
- ORM: SQLAlchemy 2.x，模型定义在 `src/core/models.py`
|
||
- 核心表: `Tenant`, `WorkOrder`, `ChatSession`, `Conversation`, `KnowledgeEntry`, `Alert`, `Analytics`, `VehicleData`, `User`
|
||
|
||
## 外部集成
|
||
|
||
- **LLM**: Qwen/DashScope (OpenAI-compatible API)，通过 `LLMClient` 调用
|
||
- **飞书**: `lark-oapi` SDK，长连接模式接收消息，API 模式发送消息和操作多维表格
|
||
- **Redis**: 可选缓存层，`REDIS_ENABLED` 控制
|
||
|
||
## 详细文档
|
||
|
||
完整文档体系在 `.agents/summary/` 目录：
|
||
- `index.md` — 文档索引（推荐作为 AI 上下文入口）
|
||
- `architecture.md` — 架构图和设计模式
|
||
- `components.md` — 组件职责
|
||
- `interfaces.md` — API 列表
|
||
- `data_models.md` — 数据模型 ER 图
|
||
- `workflows.md` — 关键流程时序图
|
||
- `dependencies.md` — 依赖说明
|
||
|
||
## Custom Instructions
|
||
<!-- This section is for human and agent-maintained operational knowledge.
|
||
Add repo-specific conventions, gotchas, and workflow rules here.
|
||
This section is preserved exactly as-is when re-running codebase-summary. -->
|