说明文档更新

2026-04-07 19:33:49 +08:00
parent cf9a1a2654
commit 0500304584
5 changed files with 2232 additions and 593 deletions
@@ -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/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+本文档格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/) 规范，并遵循 [语义化版本 (SemVer)](https://semver.org/lang/zh-CN/) 约定。
+
+---
+
+## 版本命名规范
+
+版本号格式：`主版本.次版本.修订号`
+
+| 标识 | 含义 |
+|------|------|
+| 主版本 (MAJOR) | 不兼容的重大架构变更 |
+| 次版本 (MINOR) | 向后兼容的新功能添加 |
+| 修订号 (PATCH) | 向后兼容的问题修复 |
+
+---

 ## [1.2.0] - 2026-04-07

-### Added
- ✨ 新增“算例演示（Case Demo）”标签页，位于根轨迹与智能问答之间
- ✨ 新增 `case_demo_functions.py`，支持参数化工况运行完整混动模型
- ✨ 新增图文输出：转速响应、功率分配、电气状态、关键时刻数据表
- ✨ 新增算例结果自动解读（最大转速误差、SOC变化、平均功率、平均燃油流量）
+> **重要更新：新增算例演示模块与完整混动模型联动**

-### Changed
- 🔧 `Model/src/series_hybrid_sim.py` 改为按 Model 目录定位 GPR 数据与权重
- 🔧 `requirements.txt` 固定关键依赖版本并加入 PyTorch CPU 下载源
- 🔧 文档更新：README 与 GUIDANCE 同步为“五大功能”结构与最新运行方式
+### Added（新增功能）

-### Removed
- 🧹 精简 `Model` 目录：移除 `scripts/`、`EngineData.xlsx`、`.git/`、`.claude/`、`README.md`、`LICENSE`、`environment.yml`、`figures/`、`.gitignore`
+#### 🧪 算例演示模块（Case Demo）
+
+本版本最核心的更新是新增了完整的算例演示模块，通过串联式混合动力系统模型展示控制系统设计在实际工程中的应用。
+
+**阶段零：模型训练**
+- 新增 `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
- 支持任意阶次线性时不变（LTI）系统分析
- 实时参数调节和图表更新
- 流式 AI 对话响应
- 标签页切换自动加载数据
- 可折叠的知识点章节
+### Added（新增功能）

-### 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
- [ ] 状态空间分析模块
- [ ] 离散系统分析支持
- [ ] 更多控制器设计工具（PID 调优、极点配置）
- [ ] 系统对比功能（多个传递函数对比）
- [ ] 导出分析报告（PDF/Word）
- [ ] 历史记录保存
- [ ] 更多 AI 模型支持
- [ ] 多语言界面（英文版）
- [ ] 移动端适配
+**2. 频域分析模块**
+- Bode 图绘制（幅频特性 + 相频特性）
+- Nyquist 图绘制（极坐标频率响应）
+- 自动增益裕度 (GM) 计算
+- 自动相位裕度 (PM) 计算
+- 稳定性自动判断
+
+**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 页面。