说明文档更新

API_CONFIG.md

@@ -1,201 +1,640 @@
 # API 配置指南
 
-本文档详细说明如何配置 DeepSeek 和 Gemini API。
+> 本文档详细说明如何为自动控制理论AI+数智平台配置 DeepSeek 和 Gemini API，包括密钥获取、配置方法、参数调优与常见问题排查。
-
-## 📋 目录
-
-- [DeepSeek API 配置](#deepseek-api-配置)
-- [Gemini API 配置](#gemini-api-配置)
-- [常见问题](#常见问题)
 
 ---
 
-## 🚀 DeepSeek API 配置
+## 一、API 概述
 
-### 1. 获取 API 密钥
+### 1.1 平台支持的 AI API
 
-1. 访问 [DeepSeek 平台](https://platform.deepseek.com/)
+本平台目前支持以下 AI API 提供商：
-2. 注册账号并登录
-3. 进入 [API Keys 页面](https://platform.deepseek.com/api_keys)
-4. 点击"创建新密钥"
-5. 复制生成的 API 密钥（格式：`sk-xxxxxxxxxxxxxxxx`）
 
-### 2. 配置到应用
+| API 提供商 | 支持模型 | 访问地区 | 推荐程度 |
+|------------|----------|----------|----------|
+| DeepSeek | deepseek-chat / deepseek-coder | 中国大陆 | ⭐⭐⭐⭐⭐ 首选 |
+| Gemini (Google) | gemini-1.5-flash / gemini-1.5-pro | 部分受限 | ⭐⭐⭐ |
 
-编辑 `app.py` 文件的配置区域（第 7-28 行）：
+### 1.2 为什么需要 API
+
+AI 智能问答模块依赖外部大语言模型 API 来实现：
+- 自动控制理论专业问题的理解和回答
+- LaTeX 数学公式的正确生成
+- 多轮对话的上下文记忆
+
+### 1.3 配置优先级
+
+```
+┌─────────────────────────────────────────┐
+│  推荐配置顺序                            │
+├─────────────────────────────────────────┤
+│                                         │
+│  1. DeepSeek API（国内访问，速度快）    │
+│         ↓                               │
+│  2. Gemini API（需要代理）              │
+│         ↓                               │
+│  3. 本地部署（需高配置服务器）          │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## 二、DeepSeek API 配置
+
+### 2.1 DeepSeek 简介
+
+DeepSeek 是国内领先的 AI 大模型服务提供商，提供：
+- **deepseek-chat**：通用对话模型，适合教育场景
+- **deepseek-coder**：代码专用模型，适合技术问题
+- **价格优惠**：相比 OpenAI 等海外服务商更具性价比
+- **国内访问**：无需代理，网络延迟低
+
+### 2.2 获取 API 密钥
+
+**Step 1：访问 DeepSeek 平台**
+
+打开浏览器，访问：https://platform.deepseek.com/
+
+**Step 2：注册/登录账号**
+
+- 使用手机号或邮箱注册
+- 已注册用户直接登录
+
+**Step 3：进入 API Keys 管理页面**
+
+登录后，点击顶部导航栏的 "API Keys"：
+```
+https://platform.deepseek.com/api_keys
+```
+
+**Step 4：创建新密钥**
+
+1. 点击 "创建新密钥" 按钮
+2. 输入密钥名称（可自定义，如 "AutoControlCourse"）
+3. 点击确认
+4. **立即复制密钥**（只显示一次！）
+
+**密钥格式示例：**
+```
+sk-2292af2428d7419897ca1fb6e99ba6bc
+```
+
+### 2.3 配置到项目
+
+**方法一：直接编辑 config.py（最简单）**
+
+1. 打开项目根目录下的 `config.py` 文件
+2. 找到 API 配置区域
+3. 将 `API_KEY` 替换为您的密钥
 
 ```python
 # ==================== API 配置 ====================
-API_KEY = "sk-your-api-key-here"  # 粘贴您的 DeepSeek API 密钥
+API_KEY = "sk-2292af2428d7419897ca1fb6e99ba6bc"  # 替换为您的密钥
 API_BASE_URL = "https://api.deepseek.com/v1"
 API_MODEL = "deepseek-chat"  # 或 "deepseek-coder"
 API_TYPE = "deepseek"
 # ==================================================
 ```
 
-### 3. 可用模型
+**方法二：使用环境变量（推荐用于生产环境）**
 
-| 模型名称 | 适用场景 | 特点 |
+1. **Windows PowerShell：**
-|---------|---------|------|
-| `deepseek-chat` | 通用对话 | 平衡性能，推荐使用 |
-| `deepseek-coder` | 代码相关 | 代码理解和生成能力强 |
-
-### 4. 费用说明
-
-- 新用户通常有免费额度
-- 按 token 计费，价格实惠
-- 详见 [定价页面](https://platform.deepseek.com/pricing)
-
----
-
-## 🌐 Gemini API 配置
-
-### 1. 获取 API 密钥
-
-1. 访问 [Google AI Studio](https://aistudio.google.com/app/apikey)
-2. 使用 Google 账号登录
-3. 点击"Get API Key"
-4. 创建或选择项目
-5. 复制生成的 API 密钥
-
-### 2. 配置到应用
-
-编辑 `app.py` 文件的配置区域：
-
-```python
-# ==================== API 配置 ====================
-API_KEY = "AIzaSy-your-gemini-api-key-here"
-API_BASE_URL = "https://generativelanguage.googleapis.com/v1beta"
-API_MODEL = "gemini-1.5-flash"  # 或其他可用模型
-API_TYPE = "gemini"
-# ==================================================
-```
-
-### 3. 可用模型
-
-| 模型名称 | 特点 |
-|---------|------|
-| `gemini-1.5-flash` | 快速响应，适合实时交互 |
-| `gemini-1.5-pro` | 更强大的理解和生成能力 |
-| `gemini-pro` | 经典版本 |
-
-### 4. 注意事项
-
-- Gemini API 在某些地区可能需要网络代理
-- 中国大陆用户推荐使用 DeepSeek API
-
----
-
-## 🔒 安全建议
-
-### 方法 1：环境变量（推荐）
-
-不要直接在代码中硬编码 API 密钥，使用环境变量：
-
-**Windows PowerShell：**
 ```powershell
-$env:DEEPSEEK_API_KEY="sk-your-key"
+$env:DEEPSEEK_API_KEY="sk-2292af2428d7419897ca1fb6e99ba6bc"
 python app.py
 ```
 
-**Linux/Mac：**
+2. **Linux / macOS：**
 ```bash
-export DEEPSEEK_API_KEY="sk-your-key"
+export DEEPSEEK_API_KEY="sk-2292af2428d7419897ca1fb6e99ba6bc"
 python app.py
 ```
 
-然后在代码中读取：
+3. **在 config.py 中读取环境变量：**
 ```python
 import os
+
 API_KEY = os.environ.get("DEEPSEEK_API_KEY", "")
 ```
 
-### 方法 2：配置文件
+**方法三：创建独立配置文件**
-
-创建 `config.json`（不要提交到 Git）：
 
+1. 在项目根目录创建 `config.json`：
 ```json
 {
-  "api_key": "sk-your-key",
+  "api_key": "sk-2292af2428d7419897ca1fb6e99ba6bc",
   "api_base_url": "https://api.deepseek.com/v1",
   "api_model": "deepseek-chat",
   "api_type": "deepseek"
 }
 ```
 
-在代码中加载：
+2. 在 `config.py` 中加载：
 ```python
 import json
+import os
 
-with open('config.json', 'r') as f:
+config_path = os.path.join(os.path.dirname(__file__), "config.json")
-    config = json.load(f)
+if os.path.exists(config_path):
-    API_KEY = config['api_key']
+    with open(config_path, "r") as f:
-    API_BASE_URL = config['api_base_url']
+        config_data = json.load(f)
-    # ...
+        API_KEY = config_data.get("api_key", "")
+        API_BASE_URL = config_data.get("api_base_url", "https://api.deepseek.com/v1")
+        API_MODEL = config_data.get("api_model", "deepseek-chat")
+        API_TYPE = config_data.get("api_type", "deepseek")
+else:
+    API_KEY = ""
+    API_BASE_URL = "https://api.deepseek.com/v1"
+    API_MODEL = "deepseek-chat"
+    API_TYPE = "deepseek"
+```
+
+### 2.4 DeepSeek 可用模型
+
+| 模型名称 | 适用场景 | 特点 | 推荐场景 |
+|----------|----------|------|----------|
+| deepseek-chat | 通用对话 | 平衡性能与成本 | ⭐ 日常学习问答 |
+| deepseek-coder | 代码相关 | 代码理解能力强 | 专业开发者 |
+
+### 2.5 费用说明
+
+| 项目 | 说明 |
+|------|------|
+| 新用户优惠 | 通常有免费额度 |
+| 计费方式 | 按 token 用量计费 |
+| 价格水平 | 比 OpenAI 低约 80% |
+| 查看用量 | https://platform.deepseek.com/usage |
+| 详细定价 | https://platform.deepseek.com/pricing |
+
+### 2.6 速率限制
+
+| 账户类型 | RPM（每分钟请求数） | TPM（每分钟 Token 数） |
+|----------|---------------------|------------------------|
+| 免费用户 | 60 | 100,000 |
+| 付费用户 | 最高可达 2000 | 根据套餐 |
+
+---
+
+## 三、Gemini API 配置
+
+### 3.1 Gemini 简介
+
+Gemini 是 Google 开发的 AI 大模型，具备：
+- **gemini-1.5-flash**：快速响应，适合实时交互
+- **gemini-1.5-pro**：更强大的理解和生成能力
+- **多模态**：支持文本、图像等多种输入
+
+**注意：** Gemini API 在中国大陆可能需要网络代理才能访问。
+
+### 3.2 获取 API 密钥
+
+**Step 1：访问 Google AI Studio**
+
+打开浏览器，访问：https://aistudio.google.com/app/apikey
+
+**Step 2：登录 Google 账号**
+
+使用您的 Google 账号登录。
+
+**Step 3：获取 API 密钥**
+
+1. 点击 "Get API Key"
+2. 选择或创建项目
+3. 点击 "Create API Key"
+4. 复制生成的密钥
+
+**密钥格式示例：**
+```
+AIzaSy-your-gemini-api-key-here
+```
+
+### 3.3 配置到项目
+
+编辑 `config.py` 文件：
+
+```python
+# ==================== API 配置 ====================
+API_KEY = "AIzaSy-your-gemini-api-key-here"
+API_BASE_URL = "https://generativelanguage.googleapis.com/v1beta"
+API_MODEL = "gemini-1.5-flash"  # 或 "gemini-1.5-pro"
+API_TYPE = "gemini"
+# ==================================================
+```
+
+### 3.4 Gemini 可用模型
+
+| 模型名称 | 特点 | 适用场景 | 响应速度 |
+|----------|------|----------|----------|
+| gemini-1.5-flash | 快速响应 | 实时交互 | ⚡⚡⚡⚡⚡ |
+| gemini-1.5-pro | 更强能力 | 复杂问题 | ⚡⚡⚡ |
+| gemini-pro | 经典版本 | 一般对话 | ⚡⚡⚡⚡ |
+
+### 3.5 网络访问说明
+
+| 地区 | 访问状态 | 解决方案 |
+|------|----------|----------|
+| 中国大陆 | 可能受限 | 使用 DeepSeek API 或配置代理 |
+| 港澳台 | 基本正常 | 直连或使用代理 |
+| 其他地区 | 正常 | 直连 |
+
+---
+
+## 四、配置参数详解
+
+### 4.1 完整配置参数表
+
+| 参数名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| API_KEY | string | "" | API 密钥，必填 |
+| API_BASE_URL | string | "https://api.deepseek.com/v1" | API 基础 URL |
+| API_MODEL | string | "deepseek-chat" | 模型名称 |
+| API_TYPE | string | "deepseek" | API 类型：deepseek 或 gemini |
+| SERVER_NAME | string | "0.0.0.0" | 监听网络接口 |
+| SERVER_PORT | int | 7860 | 监听端口 |
+| SHARE | bool | True | 是否创建公开链接 |
+
+### 4.2 API_KEY 配置
+
+**格式：** `sk-` 开头（DeepSeek）或 `AIzaSy` 开头（Gemini）
+
+**常见错误：**
+- 密钥包含多余空格（复制时容易带入）
+- 密钥过期或被删除
+- 密钥未激活对应服务
+
+**排查方法：**
+1. 确认密钥完整复制（无前后空格）
+2. 在官网控制台确认密钥状态
+3. 确认密钥已绑定正确的产品/服务
+
+### 4.3 API_BASE_URL 配置
+
+| API 类型 | 正确 URL | 错误示例 |
+|----------|----------|----------|
+| DeepSeek | https://api.deepseek.com/v1 | https://api.deepseek.com/ |
+| Gemini | https://generativelanguage.googleapis.com/v1beta | 其他 URL |
+
+### 4.4 API_MODEL 配置
+
+**DeepSeek 模型：**
+
+| 模型 | 上下文长度 | 适用场景 |
+|------|------------|----------|
+| deepseek-chat | 64K tokens | 通用对话，推荐 |
+| deepseek-coder | 64K tokens | 代码相关问题 |
+
+**Gemini 模型：**
+
+| 模型 | 上下文长度 | 适用场景 |
+|------|------------|----------|
+| gemini-1.5-flash | 1M tokens | 快速响应 |
+| gemini-1.5-pro | 1M tokens | 复杂任务 |
+| gemini-pro | 32K tokens | 一般对话 |
+
+---
+
+## 五、流式响应配置
+
+### 5.1 什么是流式响应
+
+流式响应（Streaming）是指 AI 边生成答案边返回，用户可以实时看到回答内容，而不必等待完整答案生成完毕。
+
+**优点：**
+- 减少等待感
+- 及时了解回答方向
+- 支持长答案的快速预览
+
+### 5.2 当前配置
+
+本平台默认启用流式响应，配置位于 `chatbot.py`：
+
+```python
+payload = {
+    "model": config.API_MODEL,
+    "messages": messages_for_api,
+    "stream": True,        # 启用流式响应
+    "temperature": 0.7,   # 创造性参数
+    "max_tokens": 2048    # 最大 Token 数
+}
+```
+
+### 5.3 参数调优
+
+| 参数 | 取值范围 | 说明 | 调整建议 |
+|------|----------|------|----------|
+| temperature | 0.0 ~ 2.0 | 创造性控制，值越低越确定 | 学习问答建议 0.3~0.7 |
+| max_tokens | 1 ~ 32768 | 单次回复最大 Token 数 | 长回答设为 4096 |
+| top_p | 0.0 ~ 1.0 | 核采样参数 | 通常保持默认 1.0 |
+| frequency_penalty | -2.0 ~ 2.0 | 频率惩罚 | 保持默认 0.0 |
+| presence_penalty | -2.0 ~ 2.0 | 存在惩罚 | 保持默认 0.0 |
+
+---
+
+## 六、系统提示词配置
+
+### 6.1 系统提示词的作用
+
+系统提示词（System Prompt）定义了 AI 助手的角色定位、回答风格和专业范围。本平台的默认提示词位于 `chatbot.py`。
+
+### 6.2 默认提示词
+
+```python
+system_prompt = """你是一位精通自动控制原理的专家教授。请用清晰、准确、专业的中文来回答有关自动控制课程内容的问题。
+
+重要规则：
+1. 当需要表达数学公式时，必须使用 LaTeX 格式
+2. 行内公式使用 $公式$ 或 \\(公式\\)
+3. 独立公式使用 $$公式$$ 或 \\[公式\\]
+4. 例如：传递函数可以写成 $G(s) = \\frac{K}{s(s+1)}$
+5. 二阶系统标准形式：$$G(s) = \\frac{\\omega_n^2}{s^2 + 2\\zeta\\omega_n s + \\omega_n^2}$$
+
+请在适当的时候使用公式和示例来辅助解释。"""
+```
+
+### 6.3 自定义提示词
+
+根据教学需求，您可以修改系统提示词：
+
+**修改方法：** 编辑 `chatbot.py` 中的 `system_prompt` 变量。
+
+**示例1：强化公式推导**
+```python
+system_prompt = """你是一位严谨的自动控制原理教授。在回答问题时：
+1. 注重公式的推导过程
+2. 每一步推导都要清晰呈现
+3. 适当使用 LaTeX 公式
+4. 结合实例帮助理解"""
+```
+
+**示例2：简化回答风格**
+```python
+system_prompt = """你是一位friendly的自动控制课程助教。请用简洁、易懂的语言回答问题：
+1. 尽量少用专业术语
+2. 多用生活实例类比
+3. 重要公式用 LaTeX 展示"""
+```
+
+**示例3：英文问答模式**
+```python
+system_prompt = """You are an expert professor of Automatic Control Theory.
+Answer questions in English using LaTeX for mathematical formulas.
+Focus on clarity and practical examples."""
 ```
 
 ---
 
-## ❓ 常见问题
+## 七、安全建议
 
-### Q1: API 请求失败，显示 401 错误
+### 7.1 密钥安全原则
 
-**原因**：API 密钥无效或未配置
+**❌ 不要做的事情：**
+- 在代码中硬编码密钥并提交到 Git
+- 在公开场合分享密钥
+- 使用过于简单的密钥
 
-**解决**：
+**✅ 推荐的做法：**
-1. 检查 API 密钥是否正确复制（无多余空格）
+- 使用环境变量存储密钥
-2. 确认密钥未过期或被删除
+- 将敏感配置文件加入 .gitignore
-3. 重新生成密钥并更新配置
+- 定期更换密钥
+- 为不同项目使用不同的密钥
 
-### Q2: 网络连接错误
+### 7.2 .gitignore 配置
 
-**原因**：网络问题或 API 服务不可达
+确保以下文件不会被提交到 Git：
 
-**解决**：
+```
-1. DeepSeek 用户：检查国内网络连接
+# API 配置文件
-2. Gemini 用户：可能需要配置网络代理
+config.json
-3. 尝试切换到 DeepSeek API（国内友好）
+secrets.json
+.env
 
-### Q3: 回复速度慢或超时
+# Python
+__pycache__/
+*.pyc
+*.pyo
 
-**原因**：网络延迟或 API 负载高
+# IDE
+.vscode/
+.idea/
 
-**解决**：
+# 模型权重（较大文件）
-1. 检查网络连接速度
+Model/data/*.pth
-2. 调整超时设置（app.py 中的 `ClientTimeout`）
+```
-3. 尝试切换模型（如 flash 版本）
 
-### Q4: 公式不渲染
+### 7.3 生产环境部署
 
-**原因**：Chatbot 未启用 LaTeX 支持
+**推荐做法：**
 
-**解决**：
+1. **使用环境变量**
-确认 `gr.Chatbot` 包含 `latex_delimiters` 参数：
+```bash
+# Docker 部署
+docker run -p 7860:7860 \
+  -e DEEPSEEK_API_KEY="sk-xxx" \
+  autocontrol-course
+```
+
+2. **使用配置服务**
+- AWS Secrets Manager
+- Azure Key Vault
+- HashiCorp Vault
+
+3. **限制 API 访问**
+- 设置 API 密钥的使用 IP 白名单
+- 配置请求频率限制
+- 开启使用量告警
+
+---
+
+## 八、常见问题排查
+
+### 8.1 API 请求失败
+
+**问题1：401 Unauthorized**
+
+| 可能原因 | 解决方法 |
+|----------|----------|
+| API 密钥无效 | 检查密钥是否正确复制 |
+| 密钥已过期 | 在平台控制台重新创建密钥 |
+| 密钥未激活 | 确认密钥已绑定正确服务 |
+
+**问题2：403 Forbidden**
+
+| 可能原因 | 解决方法 |
+|----------|----------|
+| 账户余额不足 | 充值或等待免费额度刷新 |
+| 权限不足 | 检查账户权限设置 |
+| 服务未开通 | 在控制台开通对应服务 |
+
+**问题3：429 Rate Limit**
+
+| 可能原因 | 解决方法 |
+|----------|----------|
+| 请求过于频繁 | 降低请求频率 |
+| 超出 TPM/RPM 限制 | 等待或升级套餐 |
+| 并发数过高 | 减少并发请求数 |
+
+**解决方法：**
+1. 等待一段时间后重试
+2. 配置请求间隔（如每次提问间隔 2 秒）
+3. 升级到更高配额套餐
+
+### 8.2 网络连接问题
+
+**问题：Connection Error / Timeout**
+
+**排查步骤：**
+
+1. **检查网络连接**
+```bash
+# 测试 API 端点是否可达
+curl -I https://api.deepseek.com/v1
+```
+
+2. **检查代理设置（如需要）**
+```python
+# 在 chatbot.py 中配置代理
+import os
+os.environ["HTTP_PROXY"] = "http://proxy.example.com:8080"
+os.environ["HTTPS_PROXY"] = "http://proxy.example.com:8080"
+```
+
+3. **增加超时时间**
+```python
+# 在 aiohttp 请求中增加 timeout
+async with session.post(api_url, json=payload, headers=headers,
+                        timeout=aiohttp.ClientTimeout(total=120)) as response:
+```
+
+### 8.3 回复质量问题
+
+**问题：回复内容不准确**
+
+**解决方法：**
+
+1. **优化系统提示词**
+   - 明确指定回答风格
+   - 强调专业领域要求
+   - 添加示例回答
+
+2. **调整 temperature 参数**
+   - 降低 temperature（0.3~0.5）使回答更确定
+   - 提高 temperature（0.7~1.0）使回答更有创造性
+
+3. **优化提问方式**
+   - 提供更多上下文
+   - 明确问题范围
+   - 指出具体困惑点
+
+**问题：回复速度慢**
+
+**解决方法：**
+
+1. **使用较轻量的模型**
+   - DeepSeek：选择 deepseek-chat 而非 deepseek-coder
+   - Gemini：选择 gemini-1.5-flash
+
+2. **减少 max_tokens**
+   - 根据实际需求设置合理的最大长度
+   - 避免生成过长的回答
+
+3. **检查网络延迟**
+   - 选择距离更近的 API 端点
+   - 考虑使用 CDN 加速
+
+### 8.4 公式渲染问题
+
+**问题：LaTeX 公式不显示**
+
+**可能原因：**
+
+1. **Chatbot 未启用 LaTeX**
+2. **MathJax 加载失败**
+3. **公式语法错误**
+
+**解决方法：**
+
+1. 确认 `gr.Chatbot` 配置包含 `latex_delimiters`：
 ```python
 chatbot = gr.Chatbot(
     latex_delimiters=[
         {"left": "$$", "right": "$$", "display": True},
-        {"left": "$", "right": "$", "display": False}
+        {"left": "$", "right": "$", "display": False},
+        {"left": "\\[", "right": "\\]", "display": True},
+        {"left": "\\(", "right": "\\)", "display": False}
     ]
 )
 ```
 
-### Q5: 如何限制 API 调用成本？
+2. 刷新页面重试
 
-**建议**：
+3. 检查 LaTeX 语法是否正确
-1. 在 API 平台设置使用限额
-2. 代码中添加 `max_tokens` 限制
-3. 监控 API 使用情况
-4. 使用轻量级模型（如 flash 版本）
 
 ---
 
-## 📞 获取帮助
+## 九、API 使用成本优化
 
-- **DeepSeek 文档**：https://platform.deepseek.com/docs
+### 9.1 成本构成
-- **Gemini 文档**：https://ai.google.dev/docs
+
-- **项目 Issues**：[GitHub Issues 链接]
+API 使用成本主要由以下因素决定：
+
+| 因素 | 说明 | 优化建议 |
+|------|------|----------|
+| 输入 Token 数 | 问题文本长度 | 精简提问 |
+| 输出 Token 数 | 回答文本长度 | 限制 max_tokens |
+| 请求次数 | 提问频率 | 减少无效请求 |
+| 模型单价 | 不同模型价格不同 | 选择性价比模型 |
+
+### 9.2 优化策略
+
+**策略1：精简提问**
+- 移除问题中不必要的修饰词
+- 明确指出核心疑问
+- 提供必要的上下文但不过度
+
+**策略2：合理限制输出长度**
+- 根据问题类型设置 max_tokens
+- 简单问题设置较短限制
+- 复杂问题允许更长回答
+
+**策略3：缓存常用回答**
+- 实现本地缓存机制
+- 避免重复提问相同问题
+- 减少 API 调用次数
+
+**策略4：选择合适模型**
+- 日常问答：使用轻量模型（flash 版本）
+- 复杂问题：按需使用强大模型
+
+### 9.3 预算设置
+
+在 DeepSeek 控制台设置用量限制：
+
+1. 访问 https://platform.deepseek.com/
+2. 进入 "用量限制" 设置
+3. 设置月度预算上限
+4. 开启用量告警
 
 ---
 
-最后更新：2025年10月15日
+## 十、获取帮助
+
+### 10.1 官方文档
+
+| 资源 | 链接 |
+|------|------|
+| DeepSeek 文档 | https://platform.deepseek.com/docs |
+| Gemini 文档 | https://ai.google.dev/docs |
+| Gradio 文档 | https://gradio.app/docs |
+
+### 10.2 技术支持
+
+| 渠道 | 联系方式 |
+|------|----------|
+| 项目问题 | GitHub Issues |
+| API 问题 | 平台官方支持 |
+| 使用咨询 | 课程教师/助教 |
+
+---
+
+**最后更新：2026年4月7日**

CHANGELOG.md

@@ -1,76 +1,379 @@
-# Changelog
+# 更新日志 (Changelog)
 
-All notable changes to this project will be documented in this file.
+> 本文档记录自动控制理论AI+数智平台的所有重要更新，包括新增功能、功能改进、问题修复与技术变更。
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+本文档格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 规范，并遵循 [语义化版本 (SemVer)](https://semver.org/lang/zh-CN/) 约定。
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## 版本命名规范
+
+版本号格式：`主版本.次版本.修订号`
+
+| 标识 | 含义 |
+|------|------|
+| 主版本 (MAJOR) | 不兼容的重大架构变更 |
+| 次版本 (MINOR) | 向后兼容的新功能添加 |
+| 修订号 (PATCH) | 向后兼容的问题修复 |
+
+---
 
 ## [1.2.0] - 2026-04-07
 
-### Added
+> **重要更新：新增算例演示模块与完整混动模型联动**
-- ✨ 新增“算例演示（Case Demo）”标签页，位于根轨迹与智能问答之间
-- ✨ 新增 `case_demo_functions.py`，支持参数化工况运行完整混动模型
-- ✨ 新增图文输出：转速响应、功率分配、电气状态、关键时刻数据表
-- ✨ 新增算例结果自动解读（最大转速误差、SOC变化、平均功率、平均燃油流量）
 
-### Changed
+### Added（新增功能）
-- 🔧 `Model/src/series_hybrid_sim.py` 改为按 Model 目录定位 GPR 数据与权重
-- 🔧 `requirements.txt` 固定关键依赖版本并加入 PyTorch CPU 下载源
-- 🔧 文档更新：README 与 GUIDANCE 同步为“五大功能”结构与最新运行方式
 
-### Removed
+#### 🧪 算例演示模块（Case Demo）
-- 🧹 精简 `Model` 目录：移除 `scripts/`、`EngineData.xlsx`、`.git/`、`.claude/`、`README.md`、`LICENSE`、`environment.yml`、`figures/`、`.gitignore`
+
+本版本最核心的更新是新增了完整的算例演示模块，通过串联式混合动力系统模型展示控制系统设计在实际工程中的应用。
+
+**阶段零：模型训练**
+- 新增 `case_demo_functions.py` 模块，作为算例演示的核心入口
+- 新增 GPR（高斯过程回归）模型训练/加载功能
+  - 支持从头训练（需要 botorch/gpytorch/sklearn）
+  - 支持加载已有 .pth 权重文件
+  - 生成训练/验证结果可视化（散点图、方差热力图）
+- 新增 NN 模型训练（知识蒸馏）功能
+  - 将 GPR 教师模型的知识蒸馏到轻量级 MLP
+  - 可视化训练损失曲线、燃油流量与功率的 parity plot
+  - 支持自定义 epochs、learning_rate、hidden_size 参数
+
+**阶段一：发动机控制器设计**
+- 新增基于 NN 代理模型的涡轴发动机动态仿真
+- 新增 PID 控制器（增量式）
+  - 可调参数：Kp、Ki、Kd
+  - 支持输入/输出量程归一化
+- 新增 MPC 控制器（模型预测控制）
+  - 纯 Python 实现的投影梯度下降求解器
+  - 可调参数：预测时域、功率跟踪权重、控制增量权重、超调限制
+  - 支持超调量硬约束（5%）
+
+**阶段二：电机控制器设计**
+- 新增永磁同步电机（PMSM）离散时间动力学模型
+- 新增 d/q 轴电流控制与 MTPA 控制策略
+- 新增 PID / MPC 两种控制器
+- 新增负载扰动测试（60% 时刻施加 150% 额定负载）
+
+**阶段三：能量管理策略设计**
+- 新增基于规则的功率跟随策略
+- 新增 SOC 滞环控制（防止模式频繁切换）
+- 新增完整混动系统仿真（发动机 + 电机 + 电池）
+- 新增三联图输出（转速响应/功率分配/电气状态）
+- 新增关键时刻数据表（8 个关键时刻点）
+
+**模型核心模块（Model/src/）**
+
+| 文件 | 功能 | 关键特性 |
+|------|------|----------|
+| `lightweight_model.py` | NN 代理模型 | MLP 3→64→64→2，Tanh 激活，归一化处理 |
+| `engine_gpr_class.py` | GPR 模型 | 高斯过程回归，支持批量预测 |
+| `distill_gpr_to_nn.py` | 知识蒸馏脚本 | CSV 直接训练或 GPR 蒸馏 |
+| `engine_dynamic_sim.py` | 涡轴发动机仿真 | 燃油执行机构 + 转子动力学 |
+| `motor_sim.py` | PMSM 电机仿真 | SVPWM、Clarke/Park 变换、损耗模型 |
+| `battery_sim.py` | 电池仿真 | OCV-SOC 查表、内阻模型、安时积分 |
+| `mpc_controller.py` | MPC 控制器 | 投影梯度下降、硬约束处理 |
+| `increPID.py` | 增量式 PID | 归一化缩放、自动抗积分饱和 |
+| `series_hybrid_sim.py` | 混动系统总成 | 功率平衡、滞环控制 |
+
+### Changed（功能变更）
+
+#### 📁 Model 目录结构优化
+
+为提高项目可维护性，对 Model 目录进行了精简：
+
+**移除的文件/目录：**
+- `scripts/` 目录（功能已整合到 `case_demo_functions.py`）
+- `EngineData.xlsx`（原始数据，已被 CSV 替代）
+- `.git/`（子模块 Git 历史）
+- `.claude/`（IDE 配置）
+- `README.md`（已整合到主项目文档）
+- `LICENSE`（已使用主项目许可证）
+- `environment.yml`（conda 环境配置）
+- `figures/`（输出目录）
+- `.gitignore`（已使用主项目配置）
+
+**保留的核心文件：**
+- `Model/src/` — 所有源代码
+- `Model/data/` — 模型权重与数据文件
+- `requirements.txt` — 依赖列表
+
+#### 模型路径解析改进
+
+`series_hybrid_sim.py` 等文件改为按 Model 目录定位资源：
+
+```python
+# 旧方式（可能因工作目录而失败）
+nn_pth = "Model/data/engine_nn_proxy.pth"
+
+# 新方式（基于脚本位置定位）
+MODEL_DATA_PATH = os.path.join(os.path.dirname(__file__), "..", "data")
+nn_pth = os.path.join(MODEL_DATA_PATH, "engine_nn_proxy.pth")
+```
+
+#### 依赖版本锁定
+
+`requirements.txt` 更新如下：
+
+| 依赖 | 新版本 | 变更说明 |
+|------|--------|----------|
+| gradio | 4.44.1 | 升级到最新稳定版 |
+| gradio-client | 1.3.0 | 新增 |
+| pydantic | 2.10.6 | 升级 |
+| pydantic-core | 2.27.2 | 升级 |
+| huggingface_hub | 0.23.0 | 新增 |
+| numpy | 1.26.4 | 锁定版本 |
+| control | 0.9.4 | 锁定版本 |
+| matplotlib | 3.9.4 | 升级 |
+| aiohttp | 3.13.5 | 升级 |
+| pillow | 10.4.0 | 升级 |
+| torch | 2.4.1+cu121 | 新增（GPU 版本） |
+| botorch | 0.14.0 | 新增（GPR 依赖） |
+| gpytorch | 1.14 | 新增（GPR 依赖） |
+| pyro-ppl | 1.9.1 | 新增（GPR 依赖） |
+| pandas | 2.3.3 | 新增（数据处理） |
+| scipy | >=1.10 | 新增（数值计算） |
+| scikit-learn | 1.7.1 | 新增（数据归一化） |
+| psutil | >=5.9 | 新增（系统监控） |
+
+**PyTorch 下载源配置：**
+```txt
+--extra-index-url https://download.pytorch.org/whl/cu121
+```
+
+#### 文档同步更新
+
+- `README.md`：同步为"五大功能"结构，新增算例演示详解
+- `GUIDANCE.md`：新增四阶段操作指南、混动系统架构说明
+- `API_CONFIG.md`：新增 API 配置详解、安全建议
+- `CHANGELOG.md`：新增详细版本记录
+
+### Removed（移除功能）
+
+| 移除项 | 原位置 | 替代方案 |
+|--------|--------|----------|
+| 独立训练脚本 | `Model/scripts/distill_gpr_to_nn.py` | 已整合到 `case_demo_functions.py` |
+| Excel 数据文件 | `Model/EngineData.xlsx` | 使用 `Model/data/Cleaned_Engine_Data_Full.csv` |
+| conda 环境文件 | `Model/environment.yml` | 使用 `requirements.txt` |
+
+### Fixed（问题修复）
+
+| 问题 | 修复内容 |
+|------|----------|
+| Model 路径解析错误 | 改用 `__file__` 相对定位，避免工作目录影响 |
+| GPR 训练缺少依赖提示 | 新增清晰的依赖安装指引 |
+| 模型权重未找到 | 提供更详细的错误提示与解决步骤 |
+
+---
+
+## [1.1.0] - 2026-02-15
+
+> **功能增强与问题修复**
+
+### Added（新增功能）
+
+| 功能 | 说明 |
+|------|------|
+| 实时在线人数统计 | 页面顶部显示当前在线用户数与历史总人数 |
+| 总访问人数统计 | 持久化记录累计访问人数 |
+| 系统资源监控 | 显示 CPU、内存、GPU 使用率 |
+| 页面自动刷新 | 每 10 秒更新在线人数，每 3 秒更新系统资源 |
+
+### Changed（功能变更）
+
+| 变更项 | 变更内容 |
+|--------|----------|
+| 在线统计存储 | 从内存改为 JSON 文件持久化 |
+| 统计更新频率 | 在线人数每 10 秒刷新，资源每 3 秒刷新 |
+| 界面布局优化 | 顶部状态栏与系统监控整合 |
+
+### Fixed（问题修复）
+
+| 问题 | 修复内容 |
+|------|----------|
+| 页面刷新导致在线人数重置 | 改用 Session ID 跟踪用户会话 |
+| 多用户并发统计不准 | 添加线程锁保护共享状态 |
+
+---
 
 ## [1.0.0] - 2025-10-15
 
-### Added
+> **首次正式发布**
-- ✨ 时域分析功能（阶跃响应、脉冲响应、性能指标计算）
-- ✨ 频域分析功能（Bode 图、Nyquist 图、稳定裕度）
-- ✨ 根轨迹分析功能（动态轨迹绘制、增益调节、极点跟踪）
-- ✨ AI 智能问答功能（支持 DeepSeek 和 Gemini API）
-- 🎨 现代化 UI 设计（渐变色、卡片布局、可滚动知识区）
-- 📚 详细的知识卡片（时域、频域、根轨迹理论）
-- 🔧 对数增益滑块（精确调节 0.1 到 1000 范围）
-- 💬 LaTeX 公式渲染（聊天机器人内数学公式支持）
-- 📊 英文图表标签（避免中文显示问题）
 
-### Features
+### Added（新增功能）
-- 支持任意阶次线性时不变（LTI）系统分析
-- 实时参数调节和图表更新
-- 流式 AI 对话响应
-- 标签页切换自动加载数据
-- 可折叠的知识点章节
 
-### Documentation
+#### 🎯 核心分析功能
-- 📄 完整的 README.md
-- 📄 API 配置指南（API_CONFIG.md）
-- 📄 快速上手指南（QUICK_START.md）
-- 📄 依赖列表（requirements.txt）
-- 📄 .gitignore 配置
-- 📄 MIT 开源许可证
 
-## [Unreleased]
+**1. 时域分析模块**
+- 单位阶跃响应分析与绘图
+- 单位脉冲响应分析与绘图
+- 自动性能指标计算：
+  - 上升时间 (Rise Time)
+  - 峰值时间 (Peak Time)
+  - 超调量 (Overshoot)
+  - 调节时间 (Settling Time)
+  - 稳态值 (Steady State Value)
+- 传递函数系数解析与 LaTeX 渲染
 
-### Planned
+**2. 频域分析模块**
-- [ ] 状态空间分析模块
+- Bode 图绘制（幅频特性 + 相频特性）
-- [ ] 离散系统分析支持
+- Nyquist 图绘制（极坐标频率响应）
-- [ ] 更多控制器设计工具（PID 调优、极点配置）
+- 自动增益裕度 (GM) 计算
-- [ ] 系统对比功能（多个传递函数对比）
+- 自动相位裕度 (PM) 计算
-- [ ] 导出分析报告（PDF/Word）
+- 稳定性自动判断
-- [ ] 历史记录保存
+
-- [ ] 更多 AI 模型支持
+**3. 根轨迹分析模块**
-- [ ] 多语言界面（英文版）
+- 完整根轨迹自动绘制
-- [ ] 移动端适配
+- 对数增益滑块（log₁₀(K) 范围 -4 到 4）
+- 实时极点位置显示
+- 动态坐标范围调整
+- 阻尼比等值线参考
+
+**4. AI 智能问答模块**
+- DeepSeek API 集成
+- Gemini API 备用支持
+- 流式响应（实时显示生成过程）
+- 多轮对话上下文记忆
+- LaTeX 数学公式渲染
+- 自动控制原理专业问答
+
+#### 🎨 界面设计
+
+| 特性 | 说明 |
+|------|------|
+| 渐变色标题 | 紫色渐变视觉效果 |
+| 卡片式布局 | 分组清晰，层次分明 |
+| 可滚动知识卡片 | 节省屏幕空间 |
+| 可折叠章节 | 按需展开 |
+| 实时参数更新 | 图表即时反映变化 |
+| 标签页联动 | 切换自动加载数据 |
+| 平滑动画效果 | 悬停、滚动动效 |
+
+#### 📚 知识卡片内容
+
+| 模块 | 知识点 |
+|------|--------|
+| 时域分析 | 二阶系统标准形式、阻尼比与响应特性、性能指标公式、稳态误差分析 |
+| 频域分析 | Bode 图绘制技巧、稳定裕度定义、稳定性判断准则、频域-时域对应关系 |
+| 根轨迹 | 基本规则、起点终点、渐近线、分离点、s 平面稳定性区域 |
+
+#### 🔧 交互设计
+
+| 特性 | 实现 |
+|------|------|
+| 对数增益滑块 | log₁₀(K) 范围 -4~4，对应 K = 0.0001~10000 |
+| 传递函数输入 | 系数从高次幂到常数项，逗号分隔 |
+| 实时预览 | 显示传递函数 LaTeX 公式 |
+| 松开更新 | 滑块释放后才更新图表，避免卡顿 |
+
+### Documentation（文档）
+
+| 文档 | 内容 |
+|------|------|
+| README.md | 项目简介、功能说明、快速开始、技术栈 |
+| GUIDANCE.md | 学生使用指南、详细教程、示例库 |
+| API_CONFIG.md | DeepSeek/Gemini API 配置指南 |
+| CHANGELOG.md | 版本更新记录 |
+| requirements.txt | Python 依赖列表 |
+| .gitignore | Git 忽略配置 |
+
+### Features（技术特性）
+
+| 特性 | 说明 |
+|------|------|
+| 任意阶次 LTI 系统 | 支持任意阶次线性时不变系统分析 |
+| python-control 集成 | 复用成熟控制系统工具箱 |
+| 英文图表标签 | 避免中文显示问题 |
+| LaTeX 公式渲染 | Chatbot 内数学公式支持 |
 
 ---
 
-## Version History
+## [Unreleased] - 开发中
 
-### v1.0.0 (2025-10-15)
+> 以下为计划中但尚未发布的功能
-- 🎉 首次正式发布
+
-- 包含四大核心功能模块
+### Planned（计划功能）
-- 完整的文档和配置文件
+
+| 功能 | 状态 | 说明 |
+|------|------|------|
+| 状态空间分析模块 | 🔄 计划中 | 状态空间模型构建、能控性/能观性分析 |
+| 离散系统分析支持 | 🔄 计划中 | 离散传递函数、Z变换、根轨迹 |
+| PID 控制器自动调参 | 🔄 计划中 | Ziegler-Nichols、遗传算法优化 |
+| 极点配置设计工具 | 🔄 计划中 | 通过状态反馈实现指定极点位置 |
+| 系统对比功能 | 🔄 计划中 | 多个传递函数对比分析 |
+| 分析报告导出 | 🔄 计划中 | PDF/Word 格式报告生成 |
+| 历史记录保存 | 🔄 计划中 | 本地保存分析历史 |
+| 更多 AI 模型支持 | 🔄 计划中 | Claude、GPT-4 等 |
+| 多语言界面 | 🔄 计划中 | 英文版界面 |
+| 移动端适配 | 🔄 计划中 | 响应式布局优化 |
 
 ---
 
-**Note**: For detailed commit history, see the [Git log](https://github.com/your-repo/commits).
+## 版本历史
+
+| 版本 | 日期 | 重大变更 |
+|------|------|----------|
+| 1.2.0 | 2026-04-07 | 新增算例演示模块、混动模型联动、精简 Model 目录 |
+| 1.1.0 | 2026-02-15 | 新增在线统计、系统资源监控、持久化存储 |
+| 1.0.0 | 2025-10-15 | 首次正式发布，四大核心功能 + AI 问答 |
+
+---
+
+## 分支管理
+
+| 分支 | 用途 |
+|------|------|
+| `master` | 主分支，稳定版本 |
+| `feature/case-demo-model-minimal` | 算例演示模块开发分支 |
+
+### 合并策略
+
+```bash
+# 功能完成后，创建 Pull Request
+git checkout -b feature/your-feature
+git add .
+git commit -m "feat: add new feature"
+git push -u origin feature/your-feature
+
+# 合并到 master
+git checkout master
+git merge feature/your-feature
+git push origin master
+```
+
+---
+
+## 贡献者
+
+| 贡献者 | 角色 | 主要贡献 |
+|--------|------|----------|
+| 魏鹏飞 | 项目负责人 | 整体架构设计、核心算法 |
+| 项目团队 | 开发 | 各功能模块实现 |
+
+---
+
+## 提交信息规范
+
+本项目采用 [Conventional Commits](https://www.conventionalcommits.org/) 规范：
+
+| 类型 | 说明 |
+|------|------|
+| `feat:` | 新功能 |
+| `fix:` | 问题修复 |
+| `docs:` | 文档更新 |
+| `style:` | 代码格式调整（不影响功能） |
+| `refactor:` | 代码重构 |
+| `perf:` | 性能优化 |
+| `test:` | 测试相关 |
+| `chore:` | 构建/工具变更 |
+
+**示例：**
+```bash
+git commit -m "feat: add MPC controller for engine design"
+git commit -m "fix: resolve path resolution issue in Model loading"
+git commit -m "docs: update README with new case demo section"
+```
+
+---
+
+**注意：** 详细的 Git 提交历史请参阅 `git log` 或 GitHub 仓库的 Commit 页面。

README.md

@@ -1,218 +1,516 @@
-# 🎛️ 自动控制原理AI+数智平台
+# 自动控制理论AI+数智平台
 
 > 交互式控制系统分析与设计工具 | 时域·频域·根轨迹·算例演示·AI问答
 
-一个基于 Gradio 构建的现代化自动控制原理学习平台，集成了系统分析工具、完整混动模型算例演示与 AI 智能问答功能。
+[![Python Version](https://img.shields.io/badge/Python-3.10%2B-blue)](https://www.python.org/)
+[![Gradio](https://img.shields.io/badge/Gradio-4.44.1-orange)](https://gradio.app/)
+[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)
 
-## ✨ 核心功能
+## 项目简介
 
-### 📊 1. 时域分析 (Time Domain Analysis)
+自动控制理论AI+数智平台是一个基于 Gradio 构建的现代化自动控制原理学习平台，集成了系统分析工具、完整混动模型算例演示，和AI智能问答功能。本项目为西北工业大学2025年校级本科生建设项目成果。
 
-- **阶跃响应分析**：观察系统对单位阶跃输入的响应
+平台旨在为自动控制理论课程提供交互式、数智化的学习环境，使学生能够直观理解控制系统的时域响应、频域特性、根轨迹分析等核心概念，并通过完整的混合动力系统算例演示，将理论知识与工程实践相结合。
-- **脉冲响应分析**：观察系统对单位脉冲输入的响应
-- **性能指标计算**：
-  - 上升时间 (Rise Time)
-  - 峰值时间 (Peak Time)
-  - 超调量 (Overshoot)
-  - 调节时间 (Settling Time)
-  - 稳态值 (Steady State Value)
 
-**知识要点**：
+---
-- 二阶系统标准形式
-- 阻尼比与自然频率参数说明
-- 时域性能指标公式
-- 稳态误差分析
 
-### 🌊 2. 频域分析 (Frequency Domain Analysis)
+## 核心功能
 
-- **Bode 图绘制**：幅频特性和相频特性
+本平台提供五大核心功能模块，涵盖经典控制理论分析与现代控制系统设计：
-- **Nyquist 图绘制**：极坐标频率响应
-- **稳定裕度计算**：
-  - 增益裕度 (Gain Margin, GM)
-  - 相位裕度 (Phase Margin, PM)
-  - 增益交越频率
-  - 相角交越频率
-- **稳定性评估**：自动判断系统稳定性
 
-**知识要点**：
+### 1. 时域分析 (Time Domain Analysis)
-- 增益裕度与相位裕度定义
-- 稳定性判断准则
-- 频域指标与时域性能的关系
-- Bode 图读数技巧
 
-### 🎯 3. 根轨迹分析 (Root Locus Analysis)
+时域分析是研究控制系统在时间域内对输入信号响应特性的方法，是自动控制理论的基础分析方法之一。
 
-- **根轨迹绘制**：自动绘制完整根轨迹图
+**主要功能：**
-- **增益调节**：对数滑块精确调节增益 K
+- **阶跃响应分析**：观察系统对单位阶跃输入的响应，这是控制系统分析中最常用的测试信号
-- **极点跟踪**：实时显示当前增益下的闭环极点位置
+- **脉冲响应分析**：观察系统对单位脉冲（δ函数）输入的响应，用于分析系统的固有特性
-- **动态视角**：自动调整坐标范围，聚焦关键区域
+- **性能指标计算**：自动计算并显示系统的关键时域性能指标
 
-**知识要点**：
+**计算的性能指标：**
-- 根轨迹法基本原理
+| 指标 | 符号 | 定义 | 物理意义 |
-- 幅值条件与相角条件
+|------|------|------|----------|
-- 根轨迹的基本性质（起点、终点、渐近线、分离点）
+| 上升时间 | $t_r$ | 响应从稳态值的10%上升到90%所需时间 | 反映系统响应速度 |
-- s 平面稳定性区域
+| 峰值时间 | $t_p$ | 响应达到第一个峰值的时间 | 反映系统阻尼特性 |
-- 阻尼比等值线
+| 超调量 | $\sigma\%$ | 峰值超过稳态值的百分比 | 反映系统振荡程度 |
+| 调节时间 | $t_s$ | 响应进入并保持在稳态值±2%区间的时间 | 反映系统 settling 速度 |
+| 稳态值 | $y(\infty)$ | 时间趋于无穷时系统的输出值 | 反映系统最终行为 |
 
-### 🧪 4. 算例演示 (Case Demo)
+**二阶系统标准形式：**
 
-- **完整混动模型**：调用 `Model/src/series_hybrid_sim.py` 进行系统级仿真
+二阶系统是自动控制理论中最重要的系统类型，其标准传递函数为：
-- **参数化工况**：支持工况模板、仿真时长、步长、SOC、初始发动机功率与缩放系数
-- **图文结果**：输出三联图（转速响应/功率分配/电气状态）与关键数据表
-- **教学解读**：自动生成指标摘要（最大转速误差、SOC变化、平均功率与燃油流量）
 
-### 🤖 5. AI 智能问答 (Q&A)
+$$G(s) = \frac{\omega_n^2}{s^2 + 2\zeta\omega_n s + \omega_n^2}$$
 
+其中：
+- $\omega_n$ — 自然频率（rad/s），表示系统无阻尼时的固有振荡频率
+- $\zeta$ — 阻尼比，表示系统阻尼程度的相对量
+
+**阻尼比与系统响应关系：**
+
+| 阻尼比范围 | 系统类型 | 响应特性 |
+|------------|----------|----------|
+| $\zeta = 0$ | 无阻尼 | 持续等幅振荡 |
+| $0 < \zeta < 1$ | 欠阻尼 | 振荡衰减，响应快速 |
+| $\zeta = 1$ | 临界阻尼 | 最快无振荡响应 |
+| $\zeta > 1$ | 过阻尼 | 无振荡，但响应较慢 |
+
+**稳态误差分析：**
+
+稳态误差是系统长期运行后实际输出与期望输出之间的差值，是评价系统控制精度的重要指标。对于单位反馈系统：
+
+$$e_{ss} = \lim_{t\to\infty} e(t) = \lim_{s\to0} \frac{R(s)}{1+G(s)H(s)}$$
+
+---
+
+### 2. 频域分析 (Frequency Domain Analysis)
+
+频域分析通过研究系统对不同频率正弦信号的响应特性来分析系统性能，是经典控制理论的核心方法之一。
+
+**主要功能：**
+- **Bode 图绘制**：同时显示幅频特性曲线和相频特性曲线
+- **Nyquist 图绘制**：以极坐标形式展示系统频率响应
+- **稳定裕度计算**：定量评估系统的相对稳定性
+
+**Bode 图（波特图）：**
+
+Bode 图包含两个子图：
+- **幅频特性图**：显示增益（单位：dB）随频率变化的关系
+- **相频特性图**：显示相位（单位：度）随频率变化的关系
+
+对数频率特性的优点：
+1. 可以将频率范围压缩，便于观察宽频带内的特性
+2. 幅值相乘转化为对数相加，简化串联系统计算
+3. 渐近线近似作图简便实用
+
+**Nyquist 稳定判据：**
+
+Nyquist 图是基于复变函数理论的稳定性判据。对于闭环系统：
+
+$$T(s) = \frac{G(s)}{1 + G(s)}$$
+
+稳定性条件：当 $\omega$ 从 $-\infty$ 变化到 $+\infty$ 时，$G(j\omega)H(j\omega)$ 轨迹顺时针包围 $(-1, j0)$ 点 $P$ 圈，其中 $P$ 为开环不稳定极点数。
+
+**稳定裕度（Stability Margins）：**
+
+| 裕度类型 | 定义 | 计算公式 | 经验要求 |
+|----------|------|----------|----------|
+| 增益裕度 GM | 相角为 $-180°$ 时，闭环增益还能增大多少 | $GM = \frac{1}{|G(j\omega_g)|}$ | $GM > 1.0$（即 $GM_{dB} > 0$） |
+| 相位裕度 PM | 增益为1（0dB）时，相位还能滞后多少 | $PM = 180° + \angle G(j\omega_c)$ | $PM > 45°$ |
+
+**稳定性判断准则：**
+- $GM > 0$ dB 且 $PM > 0°$ → **系统稳定**
+- $GM < 0$ dB 或 $PM < 0°$ → **系统不稳定**
+
+**频域指标与时域性能的关系：**
+
+| 频域指标 | 时域对应 | 经验公式 |
+|----------|----------|----------|
+| 带宽 $\omega_b$ | 上升时间 $t_r$ | $t_r \approx \frac{1.8}{\omega_b}$ |
+| 相位裕度 PM | 超调量 $\sigma\%$ | $\sigma\% \approx 100 \times e^{-\pi PM/(90-PM)}$ |
+| 增益裕度 GM | 稳定余量 | GM 越大，系统对不确定性越不敏感 |
+
+---
+
+### 3. 根轨迹分析 (Root Locus Analysis)
+
+根轨迹法是一种图解方法，用于分析系统闭环极点随增益 K 变化的轨迹，是控制系统设计的核心工具。
+
+**主要功能：**
+- **完整根轨迹绘制**：自动绘制开环增益从0到无穷变化时的闭环极点轨迹
+- **增益调节**：通过滑块精确调节增益 K，实时观察极点位置变化
+- **极点跟踪**：显示当前增益下闭环极点的精确位置
+- **动态坐标**：自动调整坐标系范围，聚焦关键区域
+
+**根轨迹的基本规则：**
+
+1. **起点与终点**：
+   - 起点（K=0）：开环传递函数的极点（$n$ 个）
+   - 终点（K→∞）：开环传递函数的零点（$m$ 个），剩余 $n-m$ 个趋向无穷
+
+2. **渐近线**：
+   - 当 $K \to \infty$ 时，根轨迹趋向 $n-m$ 条渐近线
+   - 渐近线与实轴的夹角：$\phi_a = \frac{(2k+1)180°}{n-m}$
+
+3. **分离点与会合点**：
+   - 根轨迹在实轴上相邻两分支之间的某点分离或会合
+   - 分离点坐标可通过求解 $\frac{dK}{ds} = 0$ 得到
+
+4. **与虚轴的交点**：
+   - 根轨迹与虚轴的交点对应的增益和频率可通过劳斯判据确定
+
+**s平面稳定性区域：**
+
+| 极点位置 | 系统状态 | 物理意义 |
+|----------|----------|----------|
+| 左半平面（Re(s) < 0） | 稳定 | 响应最终衰减 |
+| 虚轴（Re(s) = 0） | 临界稳定 | 持续振荡 |
+| 右半平面（Re(s) > 0） | 不稳定 | 响应发散 |
+
+**阻尼比等值线：**
+
+在 s 平面上，阻尼比 $\zeta$ 等于常数的曲线是通过原点的射线。对于二阶系统：
+
+$$\zeta = \cos(\theta)$$
+
+其中 $\theta$ 是该射线与负实轴的夹角。阻尼比越大，射线越接近负实轴，系统响应越平稳但越缓慢。
+
+---
+
+### 4. 算例演示 (Case Demo)
+
+算例演示模块是本平台的特色功能，通过完整的串联式混合动力系统模型，展示控制系统设计在实际工程中的应用。
+
+**模块架构（四阶段设计）：**
+
+```
+阶段零：模型训练
+├── GPR模型训练/加载（高斯过程回归）
+└── NN模型训练（知识蒸馏）
+
+阶段一：发动机控制器设计
+├── PID控制器
+└── MPC控制器（模型预测控制）
+
+阶段二：电机控制器设计
+├── PID控制器
+└── MPC控制器（模型预测控制）
+
+阶段三：能量管理策略设计
+├── 规则型能量管理（基于SOC滞环）
+└── 完整混动系统仿真
+```
+
+**发动机模型（Engine Model）：**
+
+基于高斯过程回归（GPR）和神经网络（NN）代理模型的涡轴发动机动态仿真：
+
+- **输入变量**：高度 $H$ (m)、马赫数 $Ma$、转速 $N$ (RPM)
+- **输出变量**：燃油流量 $W_f$ (kg/h)、输出功率 $P$ (kW)
+
+**发动机动态特性：**
+$$\tau_f \frac{dW_f}{dt} + W_f = W_{f,cmd}$$
+$$T \frac{dN}{dt} = K(W_f - W_{f,eq}(N))$$
+
+其中 $\tau_f$ 是燃油执行机构时间常数，$K$ 是转子惯性增益。
+
+**电机模型（Motor Model）：**
+
+永磁同步电机（PMSM）离散时间动力学模型：
+
+- **d/q轴电流控制**：$i_d = 0$ 控制（MTPA）
+- **转矩方程**：$T_e = 1.5n_p[\psi_f + (L_d - L_q)i_d]i_q$
+- **机械方程**：$J\frac{d\omega}{dt} = T_e - T_L - B\omega$
+
+**电池模型（Battery Model）：**
+
+等效电路模型，包含：
+- **开路电压** OCV：与 SOC 相关的非线性查表
+- **内阻**：$R_{in} = 0.15 \Omega$
+- **SOC 更新**：安时积分法
+
+$$SOC_{k+1} = SOC_k - \frac{I_k \cdot \Delta t}{C_{capacity}}$$
+
+**能量管理策略（EMS）：**
+
+基于规则的功率跟随策略，配合 SOC 滞环控制：
+
+| SOC 区间 | 工作模式 | 控制策略 |
+|----------|----------|----------|
+| $SOC < SOC_{low}$ | 充电模式 | 发动机输出固定功率 $P_{charge}$ |
+| $SOC > SOC_{high}$ | 功率跟随 | 发动机输出 = 电机需求 + 储备功率 + SOC补偿 |
+| 滞环区间内 | 保持 | 维持前一模式 |
+
+**MPC控制器（模型预测控制）：**
+
+滚动时域优化控制器，核心思想：
+
+1. **预测模型**：利用系统线性化模型预测未来 H 步状态
+2. **优化目标**：$\min \sum_{k=1}^{H} [\|w_k - w_{ref}\|^2_{Q} + \|\Delta u_k\|^2_{R}]$
+3. **约束处理**：执行机构限幅、超调量硬约束
+
+本平台使用纯 Python 实现的投影梯度下降求解器，替代传统的 SLSQP / GEKKO 方案，避免 Fortran ABI 兼容性问题。
+
+**PID控制器（增量式）：**
+
+增量式 PID 控制器公式：
+
+$$\Delta u(k) = k_p[e(k) - e(k-1)] + k_i e(k) + k_d[e(k) - 2e(k-1) + e(k-2)]$$
+
+特点：
+- 计算增量而非绝对量，避免积分饱和
+- 支持输入/输出量程归一化，便于参数调节
+
+---
+
+### 5. AI 智能问答 (Q&A)
+
+AI 问答模块集成了 DeepSeek API，提供24小时在线的自动控制理论学习助手。
+
+**主要功能：**
 - **专业教学助手**：精通自动控制原理的 AI 教授
-- **流式响应**：实时显示 AI 回复过程
+- **流式响应**：实时逐字显示 AI 回复，支持多轮对话
 - **LaTeX 公式渲染**：完美支持数学公式显示
-- **上下文记忆**：支持多轮对话
+- **上下文记忆**：支持多轮连续对话，理解对话上下文
 
-**支持的 API**：
+**支持的 API：**
-- DeepSeek API
+| API 提供商 | 模型选择 | 特点 |
+|------------|----------|------|
+| DeepSeek | deepseek-chat / deepseek-coder | 国内访问，中文优化 |
 
-## 🚀 快速开始
+**提问技巧：**
 
-### 环境要求
+✅ **推荐的问题类型：**
+- 概念解释："请解释传递函数的定义和物理意义"
+- 公式推导："如何推导二阶系统的超调量公式？"
+- 例题讲解："如何用劳斯判据判断这个系统的稳定性？"
+- 参数分析："PID控制器中三个参数分别如何影响系统响应？"
 
-- Python 3.10+
+❌ **应避免的问题：**
-- pip 包管理器
+- 过于宽泛："帮我做作业"（建议具体描述问题）
+- 缺乏上下文："这个对吗？"（请提供具体系统参数）
 
-### 安装步骤
+---
 
-1. **克隆项目**
+## 系统要求
+
+### 运行环境
+
+| 项目 | 要求 |
+|------|------|
+| Python 版本 | 3.10+ |
+| 操作系统 | Windows / Linux / macOS |
+| 内存 | 建议 8GB 以上 |
+| 显卡 | 可选（用于 GPR 训练加速，CPU 模式也可运行） |
+
+### 浏览器要求
+
+推荐使用以下浏览器的最新版本以获得最佳体验：
+- Google Chrome 90+
+- Microsoft Edge 90+
+- Mozilla Firefox 88+
+- Apple Safari 14+
+
+---
+
+## 快速开始
+
+### 方式一：使用 pip 安装（推荐）
+
+**1. 克隆项目**
 
 ```bash
 git clone <your-repo-url>
-cd AutoControl
+cd AutoControlCourse
 ```
 
-2. **安装依赖**
+**2. 创建虚拟环境（推荐）**
 
 ```bash
-pip install -r requirements.txt
+# 使用 venv
-```
+python -m venv my_gradio_env
+source my_gradio_env/bin/activate  # Linux/macOS
+# 或
+my_gradio_env\Scripts\activate  # Windows
 
-或使用 conda：
+# 或使用 conda
-
-```bash
 conda create -n autocontrol python=3.10
 conda activate autocontrol
+```
+
+**3. 安装依赖**
+
+```bash
 pip install -r requirements.txt
 ```
 
-3. **配置 API 密钥**
+**4. 配置 API 密钥**
 
-编辑 `config.py` 文件中的配置区域：
+编辑 `config.py` 文件中的 API 配置区域：
 
 ```python
 # ==================== API 配置 ====================
 API_KEY = "your-api-key-here"  # 填入您的 DeepSeek API 密钥
 API_BASE_URL = "https://api.deepseek.com/v1"
 API_MODEL = "deepseek-chat"
-API_TYPE = "deepseek"  # 或 "gemini"
+API_TYPE = "deepseek"
 # ==================================================
 ```
 
-**获取 DeepSeek API 密钥**：
+**获取 DeepSeek API 密钥：**
-- 访问 https://platform.deepseek.com/api_keys
+1. 访问 https://platform.deepseek.com/api_keys
-- 注册并创建 API 密钥
+2. 注册并登录账号
-- 复制密钥到配置文件
+3. 点击"创建新密钥"
+4. 复制生成的密钥并填入配置
 
-4. **运行应用**
+**5. 运行应用**
 
 ```bash
 python app.py
 ```
 
-或使用 conda 环境：
+**6. 访问应用**
 
-```bash
+浏览器将自动打开，或手动访问：
-conda run -n autocontrol python app.py
-```
-
-5. **访问应用**
-
-浏览器自动打开，或手动访问：
 ```
 http://localhost:7860
 ```
 
-## 📖 使用指南
+### 方式二：使用 Docker（可选）
 
-### 输入系统传递函数
+```bash
+# 构建镜像
+docker build -t autocontrol-course .
 
-在任意标签页的输入框中输入传递函数的分子和分母系数：
+# 运行容器
-
+docker run -p 7860:7860 \
-**示例 1：一阶系统**
+  -e API_KEY="your-api-key" \
-```
+  autocontrol-course
-分子: 1
-分母: 1,1
-传递函数: G(s) = 1/(s+1)
 ```
 
-**示例 2：二阶系统**
+---
+
+## 项目结构
+
 ```
-分子: 4
+AutoControlCourse/
-分母: 1,2,4
+├── app.py                        # Gradio 主入口，事件绑定与界面布局
-传递函数: G(s) = 4/(s²+2s+4)
+├── ui_components.py               # 各功能标签页的 UI 组件定义
+├── analysis_functions.py          # 时域/频域/根轨迹分析核心计算函数
+├── case_demo_functions.py        # 算例演示模块（混动模型四阶段仿真）
+├── chatbot.py                    # AI 智能问答（DeepSeek API 集成）
+├── user_stats.py                 # 在线人数统计与数据持久化
+├── config.py                     # 全局配置（API密钥、服务器端口等）
+├── requirements.txt              # Python 依赖列表
+│
+├── Model/                        # 混动模型核心代码
+│   ├── src/
+│   │   ├── lightweight_model.py  # NN代理模型（MLP，用于替代GPR）
+│   │   ├── engine_gpr_class.py   # GPR高斯过程回归模型
+│   │   ├── distill_gpr_to_nn.py  # 知识蒸馏脚本（GPR→NN）
+│   │   ├── engine_dynamic_sim.py  # 涡轴发动机动态仿真
+│   │   ├── motor_sim.py          # PMSM永磁同步电机仿真
+│   │   ├── battery_sim.py        # 电池等效电路仿真
+│   │   ├── mpc_controller.py     # MPC模型预测控制器
+│   │   ├── increPID.py           # 增量式PID控制器
+│   │   └── series_hybrid_sim.py  # 串联混动系统总成
+│   └── data/
+│       ├── Cleaned_Engine_Data_Full.csv  # 发动机标定数据
+│       ├── engine_gpr_model.pth           # GPR模型权重
+│       └── engine_nn_proxy.pth            # NN代理模型权重
+│
+└── assets/                       # 静态资源
+    ├── styles.css                # 自定义CSS样式
+    └── knowledge_cards_html.py   # 各模块知识卡片HTML内容
 ```
 
-**示例 3：三阶系统**
+---
-```
+
-分子: 1
+## 技术栈
-分母: 1,6,11,6
+
-传递函数: G(s) = 1/(s³+6s²+11s+6)
+### 前端框架
+- **Gradio 4.44.1**：快速构建机器学习 Web 界面的 Python 库
+- **Custom CSS**：现代化样式定制，支持响应式布局
+
+### 核心计算库
+| 库名 | 版本 | 用途 |
+|------|------|------|
+| NumPy | 1.26.4 | 数值计算基础库 |
+| python-control | 0.9.4 | 控制系统分析工具箱 |
+| Matplotlib | 3.9.4 | 图表绑制 |
+| PyTorch | 2.4.1 | 神经网络推理（CPU模式） |
+
+### AI 集成
+| 库名 | 用途 |
+|------|------|
+| aiohttp | 异步HTTP请求，流式响应 |
+| DeepSeek API | AI问答后端服务 |
+
+### 其他依赖
+| 库名 | 用途 |
+|------|------|
+| pandas | 数据处理（发动机CSV数据读取） |
+| scikit-learn | 数据归一化预处理 |
+| psutil | 系统资源监控（CPU/内存/显存） |
+
+---
+
+## 算例演示模块详解
+
+### 阶段零：模型训练
+
+**GPR 模型训练/加载：**
+
+高斯过程回归是一种非参数概率模型，适合小样本、高维插值。
+
+```python
+# 运行模式
+mode = "load"   # 加载已有模型（推荐）
+mode = "train"  # 从头训练（需要 botorch/gpytorch）
 ```
 
-**输入格式**：
+**NN 模型训练（知识蒸馏）：**
-- 系数从最高次项到常数项
-- 用逗号分隔（支持中文或英文逗号）
-- 支持小数和负数
-- 例如：`1, 2.5, -3, 4` 表示 s³ + 2.5s² - 3s + 4
 
-### 调节系统增益
+将 GPR 模型的知识蒸馏到轻量级 MLP 中，用于实时控制仿真。
 
-频域分析和根轨迹分析都支持增益调节：
+关键参数：
+- **训练轮数 (Epochs)**：越多越精确，推荐 3000
+- **学习率 (LR)**：推荐 1e-3 ~ 5e-3
+- **隐藏层宽度**：推荐 64（平衡精度与速度）
 
-- **对数滑块**：log₁₀(K) 范围 -1 到 3
+### 阶段一：发动机控制器设计
-  - -1 对应 K = 0.1
-  - 0 对应 K = 1
-  - 1 对应 K = 10
-  - 2 对应 K = 100
-  - 3 对应 K = 1000
 
-- **实时显示**：下方数字框显示实际增益值
+**PID 控制参数：**
-- **松开更新**：滑块松开后才更新图表，避免卡顿
+- **Kp（比例增益）**：增大可加快响应，但过大导致振荡
+- **Ki（积分增益）**：消除稳态误差，过大导致超调
+- **Kd（微分增益）**：抑制振荡，改善动态特性
 
-### AI 问答技巧
+**MPC 控制参数：**
+- **预测时域 (Horizon)**：前看步数，越长越激进
+- **功率跟踪权重 W_power**：越高则功率跟踪越紧
+- **控制增量权重 W_dcost**：越高则控制变化越平缓
+- **超调限制**：5% 硬约束
 
-**高效提问方式**：
+### 阶段二：电机控制器设计
 
-✅ **好的问题**：
+**仿真设置：**
-- "请解释 PID 控制器的三个参数如何影响系统性能？"
+- 仿真时长：5~60秒可调
-- "如何根据 Bode 图判断系统的稳定裕度？"
+- 仿真步长：0.02s / 0.05s / 0.1s
-- "为什么阻尼比为 0.707 时系统响应最佳？"
+- 目标转速：500~5000 RPM
-- "推导二阶系统的超调量公式"
+- 负载转矩：10~400 Nm
 
-❌ **避免的问题**：
+**负载扰动测试：**
-- "帮我做作业"（太模糊）
+在仿真60%时刻自动施加150%负载扰动，检验控制器抗扰能力。
-- "这个对吗？"（缺少上下文）
-- "答案是什么？"（没有提供问题描述）
 
-**公式显示**：
+### 阶段三：能量管理策略设计
-AI 回复中的数学公式会自动渲染，支持以下格式：
-- 行内公式：`$公式$` 或 `\(公式\)`
-- 块级公式：`$$公式$$` 或 `\[公式\]`
 
-## 🎨 界面特色
+**SOC 滞环控制参数：**
+
+| 参数 | 含义 | 推荐值 |
+|------|------|--------|
+| SOC目标值 | 功率跟随模式下的补偿基准 | 60% |
+| SOC下限阈值 | 低于此值进入充电模式 | 30% |
+| SOC上限阈值 | 高于此值退出充电模式 | 70% |
+
+**功率规则参数：**
+
+| 参数 | 含义 | 推荐值 |
+|------|------|--------|
+| 发动机最小功率 | 最低运转功率 | 20 kW |
+| 发动机最大功率 | 峰值输出功率 | 300 kW |
+| 充电模式功率 | 充电时发动机输出 | 200 kW |
+| SOC补偿增益 | SOC偏差修正力度 | 50 kW/ΔSOC |
+
+---
+
+## 界面特色
 
 ### 现代化设计
 
 - **渐变色标题**：紫色渐变视觉效果
 - **卡片式布局**：分组清晰，层次分明
-- **可滚动知识卡片**：长文档不占据过多空间
+- **可滚动知识卡片**：长文档不占用过多屏幕空间
-- **可折叠章节**：按需展开知识点
+- **可折叠章节**：按需展开，节省视线
 
 ### 响应式交互
 
@@ -226,64 +524,15 @@ AI 回复中的数学公式会自动渲染，支持以下格式：
 - **嵌入式公式**：页面内直接显示 LaTeX 公式
 - **表格对比**：性能指标、稳定准则表格化
 - **颜色编码**：稳定/不稳定用绿/红色标识
-- **图标辅助**：emoji 增强视觉识别
+- **图标辅助**：Emoji 增强视觉识别
 
-## 🛠️ 技术栈
+---
 
-### 前端框架
+## 高级配置
-- **Gradio 4.x**：快速构建机器学习 Web 界面
-- **Custom CSS**：现代化样式定制
-
-### 计算库
-- **NumPy**：数值计算
-- **python-control**：控制系统分析
-- **Matplotlib**：图表绘制
-
-### AI 集成
-- **aiohttp**：异步 HTTP 请求
-- **DeepSeek API**：智能问答后端
-- **流式响应**：提升用户体验
-
-## 📁 项目结构
-
-```text
-AutoControlCourse/
-├── app.py                     # Gradio 入口与事件绑定
-├── ui_components.py           # 各标签页 UI 组件
-├── analysis_functions.py      # 时域/频域/根轨迹计算
-├── case_demo_functions.py     # 算例演示模块（调用 Model）
-├── chatbot.py                 # AI 问答
-├── user_stats.py              # 在线人数统计
-├── config.py                  # API 与运行配置
-├── Model/
-│   ├── src/                   # 混动模型核心代码
-│   └── data/                  # 运行所需模型权重与数据
-└── requirements.txt           # 依赖列表
-```
-
-## 🔧 高级配置
-
-### 算例演示说明
-
-- 仿真时长是模型时间，不等于程序实际等待时间
-- 电池功率符号定义：正值放电，负值充电
-- 若参数超限，程序会在安全范围内自动裁剪
-
-### 自定义系统提示词
-
-修改 `chat_with_ai` 函数中的 `system_prompt`：
-
-```python
-system_prompt = """
-你是一位[角色定义]。
-请用[语言风格]来回答有关[领域]的问题。
-[其他要求...]
-"""
-```
 
 ### 调整图表样式
 
-在 `matplotlib` 绘图代码中修改：
+在 `analysis_functions.py` 中的 matplotlib 绑图代码里修改：
 
 ```python
 # 修改图表大小
@@ -296,48 +545,156 @@ ax.plot(x, y, color='#667eea', linewidth=2)
 ax.grid(True, alpha=0.3, linestyle='--')
 ```
 
-## 📚 参考资料
+### 自定义系统提示词
+
+修改 `chatbot.py` 中的 `system_prompt`：
+
+```python
+system_prompt = """
+你是一位精通自动控制原理的专家教授。
+请用清晰、准确、专业的中文来回答问题。
+重要规则：
+1. 当需要表达数学公式时，必须使用 LaTeX 格式
+2. 行内公式使用 $公式$ 或 \\(公式\\)
+3. 独立公式使用 $$公式$$ 或 \\[公式\\]
+"""
+```
+
+### 自定义工况模板
+
+修改 `case_demo_functions.py` 中的 `_profile_points` 函数：
+
+```python
+def _profile_points(profile_name):
+    if profile_name == "我的自定义工况":
+        return [
+            (0., 1500., 50.),    # (时间, 目标转速, 负载转矩)
+            (10., 3000., 200.),
+            (30., 2800., 150.),
+            (50., 1800., 60.)
+        ]
+    # ... 其他工况
+```
+
+---
+
+## 常见问题
+
+### Q1: 运行时提示 "psutil 未安装"
+
+不影响主要功能，仅系统资源监控不可用。忽略此提示或执行：
+
+```bash
+pip install psutil
+```
+
+### Q2: 算例演示提示 "engine_nn_proxy.pth not found"
+
+需要先完成**阶段零**的 NN 模型训练（约2~5分钟）。
+
+### Q3: GPR 训练失败，提示缺少 botorch/gpytorch
+
+GPR 训练需要额外依赖。安装方法：
+
+```bash
+pip install botorch gpytorch scikit-learn
+```
+
+或直接选择 "load" 模式加载已有模型。
+
+### Q4: AI 问答返回 "API_KEY 未配置"
+
+请在 `config.py` 中填入有效的 DeepSeek API 密钥。
+
+### Q5: 图表显示中文乱码
+
+本平台图表使用英文标签以避免中文显示问题。如需修改，编辑 `analysis_functions.py` 中的 `plt.title()`、`plt.xlabel()` 等。
+
+---
+
+## 参考资料
 
 ### 经典教材
-- 《自动控制原理》- 胡寿松
+
-- 《现代控制工程》- Katsuhiko Ogata
+1. 胡寿松.《自动控制原理》（第七版）. 科学出版社, 2019.
-- 《反馈控制理论》- John Doyle
+2. Katsuhiko Ogata. *Modern Control Engineering* (5th Edition). Prentice Hall, 2010.
+3. Richard C. Dorf, Robert H. Bishop. *Modern Control Systems* (14th Edition). Pearson, 2021.
+4. John Doyle, Bruce Francis, Allen Tannenbaum. *Feedback Control Theory*. Macmillan, 1992.
 
 ### 在线资源
+
 - [python-control 官方文档](https://python-control.readthedocs.io/)
 - [DeepSeek API 文档](https://platform.deepseek.com/docs)
-- [Gradio 官方文档](https://www.gradio.app/docs)
+- [Gradio 官方文档](https://gradio.app/docs)
+- [PyTorch 文档](https://pytorch.org/docs/)
 
-## 🤝 贡献指南
+---
+
+## 贡献指南
 
 欢迎提交 Issue 和 Pull Request！
 
 ### 贡献方向
+
 - 🐛 修复 Bug
-- ✨ 添加新功能（如状态空间分析）
+- ✨ 添加新功能（如状态空间分析模块）
 - 📝 改进文档
 - 🎨 优化界面设计
 - 🧪 添加测试用例
 
-## 📄 许可证
+### 开发环境设置
+
+```bash
+# 克隆仓库
+git clone <your-repo-url>
+cd AutoControlCourse
+
+# 创建开发分支
+git checkout -b feature/your-feature-name
+
+# 安装开发依赖
+pip install -r requirements.txt
+pip install pytest black flake8
+
+# 代码格式化
+black .
+
+# 运行测试
+pytest
+```
+
+---
+
+## 更新日志
+
+详细更新日志请参阅 [CHANGELOG.md](CHANGELOG.md)。
+
+---
+
+## 许可证
 
 本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。
 
-## 🙏 致谢
+---
+
+## 致谢
 
 - **Gradio**：提供优秀的 Web 界面框架
 - **python-control**：强大的控制系统分析库
 - **DeepSeek**：高质量的 AI 服务
 - 所有贡献者和使用者
 
-## 📞 联系方式
+---
 
-- 项目地址：[GitHub Repository URL]
+## 联系方式
-- 问题反馈：[Issues URL]
+
-- 邮箱：[your-email@example.com]
+- **项目负责人**：魏鹏飞
+- **电子邮件**：pengfeiwei@nwpu.edu.cn
+- **机构**：西北工业大学
+- **项目地址**：https://github.com/your-repo
 
 ---
 
-**⭐ 如果这个项目对您有帮助，请给它一个 Star！**
+**⭐ 如果这个项目对您的学习有帮助，请给它一个 Star！**
 
 最后更新：2026年4月7日

data_usage/usage_stats.json

@@ -1,4 +1,4 @@
 {
   "total_users": 37,
-  "last_saved_at": 1775560914.9575145
+  "last_saved_at": 1775561044.8460488
 }