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. -->
|