优化skill调用，生成相关文档说明

2026-04-07 16:54:05 +08:00
parent 3984cffe23
commit 9b98b55060
10 changed files with 373 additions and 21 deletions
--- a/.kiro/steering/product.md
+++ b/.kiro/steering/product.md
@@ -0,0 +1,25 @@
+# Product Overview
+
+TSP Assistant (TSP智能助手) is an AI-powered customer service and work order management system built for TSP (Telematics Service Provider) vehicle service providers.
+
+## What It Does
+
+- Intelligent dialogue with customers via WebSocket real-time chat and Feishu (Lark) bot integration
+- Work order lifecycle management with AI-generated resolution suggestions
+- Knowledge base with semantic search (TF-IDF + cosine similarity, optional local embedding model)
+- Vehicle data querying by VIN
+- Analytics dashboard with alerts, performance monitoring, and reporting
+- Multi-tenant architecture — data is isolated by `tenant_id` across all core tables
+- Feishu multi-dimensional table (多维表格) bidirectional sync for work orders
+
+## Key Domain Concepts
+
+- **Work Order (工单)**: A support ticket tied to a vehicle issue. Can be dispatched to module owners, tracked through statuses, and enriched with AI suggestions.
+- **Knowledge Entry (知识库条目)**: Q&A pairs used for retrieval-augmented responses. Verified entries have higher confidence.
+- **Tenant (租户)**: Logical isolation unit (e.g., a market or region). All major entities carry a `tenant_id`.
+- **Agent**: A ReAct-style LLM agent with registered tools (knowledge search, vehicle query, analytics, Feishu messaging).
+- **Chat Session (对话会话)**: Groups multi-turn conversations; tracks source (websocket, API, feishu_bot).
+
+## Primary Language
+
+The codebase, comments, log messages, and UI are predominantly in **Chinese (Simplified)**. Variable names and code structure follow English conventions.
--- a/.kiro/steering/structure.md
+++ b/.kiro/steering/structure.md
@@ -0,0 +1,79 @@
+# Project Structure
+
+```
+├── src/                        # Main application source
+│   ├── main.py                 # TSPAssistant facade class (orchestrates all managers)
+│   ├── agent_assistant.py      # Agent-enhanced assistant variant
+│   ├── agent/                  # ReAct LLM agent
+│   │   ├── react_agent.py      # Agent loop with tool dispatch
+│   │   └── llm_client.py       # Agent-specific LLM client
+│   ├── core/                   # Core infrastructure
+│   │   ├── models.py           # SQLAlchemy ORM models (all entities)
+│   │   ├── database.py         # DatabaseManager singleton, session management
+│   │   ├── llm_client.py       # QwenClient (OpenAI-compatible LLM calls)
+│   │   ├── cache_manager.py    # In-memory + Redis caching
+│   │   ├── redis_manager.py    # Redis connection pool
+│   │   ├── vector_store.py     # Vector storage for embeddings
+│   │   ├── embedding_client.py # Local embedding model client
+│   │   ├── auth_manager.py     # Authentication logic
+│   │   └── ...                 # Performance, backup, query optimizer
+│   ├── config/
+│   │   └── unified_config.py   # UnifiedConfig singleton (env → dataclasses)
+│   ├── dialogue/               # Conversation management
+│   │   ├── dialogue_manager.py # Message processing, work order creation
+│   │   ├── conversation_history.py
+│   │   └── realtime_chat.py    # Real-time chat manager
+│   ├── knowledge_base/
+│   │   └── knowledge_manager.py # Knowledge CRUD, search, import
+│   ├── analytics/              # Monitoring & analytics
+│   │   ├── analytics_manager.py
+│   │   ├── alert_system.py
+│   │   ├── monitor_service.py
+│   │   ├── token_monitor.py
+│   │   └── ai_success_monitor.py
+│   ├── integrations/           # External service integrations
+│   │   ├── feishu_client.py    # Feishu API client
+│   │   ├── feishu_service.py   # Feishu business logic
+│   │   ├── feishu_longconn_service.py  # Feishu event subscription (long-conn)
+│   │   ├── workorder_sync.py   # Feishu ↔ local work order sync
+│   │   └── flexible_field_mapper.py    # Feishu field mapping
+│   ├── vehicle/
+│   │   └── vehicle_data_manager.py
+│   ├── utils/                  # Shared helpers
+│   │   ├── helpers.py
+│   │   ├── encoding_helper.py
+│   │   └── semantic_similarity.py
+│   └── web/                    # Web layer
+│       ├── app.py              # Flask app factory, middleware, blueprint registration
+│       ├── service_manager.py  # Lazy-loading service singleton registry
+│       ├── decorators.py       # @handle_errors, @require_json, @resolve_tenant_id, @rate_limit
+│       ├── error_handlers.py   # Unified API response helpers
+│       ├── websocket_server.py # Standalone WebSocket server
+│       ├── blueprints/         # Flask blueprints (one per domain)
+│       │   ├── alerts.py, workorders.py, conversations.py, knowledge.py
+│       │   ├── auth.py, tenants.py, chat.py, agent.py, vehicle.py
+│       │   ├── analytics.py, monitoring.py, system.py
+│       │   ├── feishu_sync.py, feishu_bot.py
+│       │   └── test.py, core.py
+│       ├── static/             # Frontend assets (JS, CSS)
+│       └── templates/          # Jinja2 HTML templates
+├── config/                     # Runtime config files (field mappings)
+├── data/                       # SQLite DB file, system settings JSON
+├── logs/                       # Log files (per-startup subdirectories)
+├── scripts/                    # Migration and utility scripts
+├── start_dashboard.py          # Main entry point (Flask + WS + Feishu)
+├── start_feishu_bot.py         # Standalone Feishu bot entry point
+├── init_database.py            # DB initialization script
+├── requirements.txt            # Python dependencies
+├── nginx.conf                  # Nginx reverse proxy config
+└── .env / .env.example         # Environment configuration
+```
+
+## Key Patterns
+
+- **Singleton managers**: `db_manager`, `service_manager`, `get_config()` — instantiated once, imported globally.
+- **Blueprint-per-domain**: Each functional area (workorders, alerts, knowledge, etc.) has its own Flask blueprint under `src/web/blueprints/`.
+- **Service manager with lazy loading**: `ServiceManager` in `src/web/service_manager.py` provides thread-safe lazy initialization of all service instances. Blueprints access services through it.
+- **Decorator-driven API patterns**: Common decorators in `src/web/decorators.py` handle error wrapping, JSON validation, tenant resolution, and rate limiting.
+- **Multi-tenant by convention**: All DB queries should filter by `tenant_id`. The `@resolve_tenant_id` decorator extracts it from request body, query params, or session.
+- **Config from env**: No hardcoded secrets. All configuration flows through `UnifiedConfig` which reads from `.env` via `python-dotenv`.
--- a/.kiro/steering/tech.md
+++ b/.kiro/steering/tech.md
@@ -0,0 +1,67 @@
+# Tech Stack & Build
+
+## Language & Runtime
+
+- Python 3.11+
+
+## Core Frameworks & Libraries
+
+| Layer | Technology |
+|---|---|
+| Web framework | Flask 3.x + Flask-CORS |
+| ORM / Database | SQLAlchemy 2.x (MySQL via PyMySQL, SQLite for dev) |
+| Real-time comms | `websockets` library (standalone server on port 8765) |
+| Caching | Redis 5.x client + hiredis |
+| LLM integration | OpenAI-compatible API (default provider: Qwen/通义千问 via DashScope) |
+| Embedding | `sentence-transformers` with `BAAI/bge-small-zh-v1.5` (local, optional) |
+| NLP | jieba (Chinese word segmentation), scikit-learn (TF-IDF) |
+| Feishu SDK | `lark-oapi` 1.3.x (event subscription 2.0, long-connection mode) |
+| Data validation | pydantic 2.x, marshmallow |
+| Auth | JWT (`pyjwt`), SHA-256 password hashing |
+| Monitoring | psutil (in-process), Prometheus + Grafana (Docker) |
+
+## Configuration
+
+- All config loaded from environment variables via `python-dotenv` → `src/config/unified_config.py`
+- Singleton `UnifiedConfig` with typed dataclasses (`DatabaseConfig`, `LLMConfig`, `ServerConfig`, etc.)
+- `.env` file at project root (see `.env.example` for all keys)
+
+## Common Commands
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Initialize / migrate database
+python init_database.py
+
+# Start the full application (Flask + WebSocket + Feishu long-conn)
+python start_dashboard.py
+
+# Start only the Feishu bot long-connection client
+python start_feishu_bot.py
+
+# Run tests
+pytest
+
+# Code formatting
+black .
+isort .
+
+# Linting
+flake8
+mypy .
+```
+
+## Deployment
+
+- Docker + docker-compose (MySQL 8, Redis 7, Nginx, Prometheus, Grafana)
+- Nginx reverse proxy in front of Flask (port 80/443 → 5000)
+- Default ports: Flask 5000, WebSocket 8765, Redis 6379, MySQL 3306
+
+## Code Quality Tools
+
+- `black` for formatting (PEP 8)
+- `isort` for import sorting
+- `flake8` for linting
+- `mypy` for type checking