AutoControlCourse/README_MODULE.md

自动控制原理AI+数智平台 - 模块化架构说明

📁 项目结构

AutoControl/
├── app.py                    # 原始完整程序（已废弃，保留作参考）
├── app_main.py              # 新的主程序入口 ⭐ 使用这个启动
├── config.py                # 配置文件：API密钥、系统参数
├── utils.py                 # 工具函数：解析、验证、格式化
├── analysis.py              # 分析功能：时域、频域、根轨迹
├── ai_chat.py               # AI聊天：DeepSeek/Gemini接口
├── ui_styles.py             # CSS样式：480+行现代化样式
├── ui_components.py         # UI组件：横幅、知识卡片HTML
└── README_MODULE.md         # 本文件

🚀 快速开始

方法1：使用新的模块化主程序（推荐）

python app_main.py

方法2：使用原始完整程序

python app.py

📦 模块说明

1. config.py - 配置管理

功能： 集中管理所有配置常量

内容：

• API_KEY: DeepSeek API密钥
• API_BASE_URL: API基础URL
• API_MODEL: 使用的模型名称
• DEFAULT_NUM_COEFFS: 默认分子系数
• DEFAULT_DEN_COEFFS: 默认分母系数
• TIME_SPAN: 时间范围设置
• SERVER_PORT: 服务器端口
• PROJECT_INFO: 项目信息字典

修改配置：

# 在 config.py 中修改
API_KEY = "你的API密钥"
SERVER_PORT = 8080  # 更改端口

2. utils.py - 工具函数库

功能： 提供数据处理和格式化工具

主要函数：

• coeffs_to_latex(coeffs, var='s'): 系数转LaTeX多项式
• parse_coefficients(coeffs_str): 解析系数字符串
• validate_transfer_function(num, den): 验证传递函数
• format_complex_number(c): 格式化复数显示

使用示例：

from utils import parse_coefficients, validate_transfer_function

num = parse_coefficients("1,2,3")
den = parse_coefficients("1,4,5,2")
is_valid, msg = validate_transfer_function(num, den)

3. analysis.py - 核心分析功能

功能： 控制系统的时域、频域、根轨迹分析

主要函数：

• display_transfer_function(num_str, den_str): 显示传递函数
• time_domain_analysis(num_str, den_str): 时域分析（阶跃/脉冲响应）
• frequency_domain_analysis(num_str, den_str, K): 频域分析（Bode/Nyquist图）
• root_locus_analysis(num_str, den_str, log_k): 根轨迹分析

返回值：

• 图表：matplotlib Figure对象
• 文本：性能指标、极点位置等

4. ai_chat.py - AI聊天功能

功能： 与DeepSeek/Gemini大模型交互

主要函数：

• chat_with_ai(message, history): 异步聊天函数（支持流式输出）

特点：

• 支持对话历史记录
• 流式响应（实时显示）
• 自动错误处理
• Emoji状态指示

系统提示词：

你是一位精通自动控制原理的专家教授，擅长用通俗易懂的方式解释复杂概念。
回答要准确、专业，适当使用LaTeX公式，并举例说明。

5. ui_styles.py - CSS样式定义

功能： 提供480+行现代化CSS样式

函数：

• get_custom_css(): 返回完整CSS字符串

样式特点：

• 渐变背景和阴影效果
• 动画过渡效果
• 响应式设计（移动端适配）
• 暗色主题支持
• Emoji彩色显示修复

6. ui_components.py - UI组件库

功能： 提供HTML组件和知识卡片

主要函数：

• get_main_title(): 主标题
• get_subtitle(): 副标题
• get_project_info_banner(): 项目信息横幅
• get_tab_tip(tab_name): 标签页提示
• get_time_domain_knowledge_card(): 时域知识卡片
• get_frequency_domain_knowledge_card(): 频域知识卡片
• get_root_locus_knowledge_card(): 根轨迹知识卡片
• get_ai_example_questions(): AI示例问题

7. app_main.py - 主程序入口

功能： 简化的主程序，组装所有模块

代码行数： ~350行（相比原来的2134行减少84%）

结构：

# 导入所有模块
from config import *
from utils import *
from analysis import *
from ai_chat import *
from ui_styles import *
from ui_components import *

# 使用Gradio构建UI
with gr.Blocks(css=get_custom_css()) as demo:
    # UI布局
    # 事件绑定
    pass

# 启动服务器
demo.launch()

🎯 模块化的优势

1. 易于维护

• 每个模块职责单一，代码清晰
• 修改某个功能只需编辑对应模块
• 减少代码重复，提高复用性

2. 易于扩展

• 添加新功能：创建新模块或在现有模块添加函数
• 添加新UI：在ui_components.py添加新函数
• 添加新样式：在ui_styles.py修改CSS

3. 易于调试

• 模块独立，可单独测试
• 错误定位更快速
• 日志和异常处理更精确

4. 团队协作友好

• 不同开发者可并行工作在不同模块
• 代码冲突减少
• 代码审查更高效

📝 常见修改场景

场景1：更改API密钥

文件： config.py

API_KEY = "sk-新的密钥"

场景2：添加新的分析功能

文件： analysis.py

def new_analysis_function(num_str, den_str):
    """新的分析功能"""
    # 实现代码
    return figure, metrics

文件： app_main.py（添加UI和事件绑定）

from analysis import new_analysis_function

# 添加UI组件
new_button = gr.Button("新分析")
new_output = gr.Plot()

# 绑定事件
new_button.click(fn=new_analysis_function, inputs=[...], outputs=[...])

场景3：修改知识卡片内容

文件： ui_components.py

def get_time_domain_knowledge_card():
    return """
    <div class='knowledge-card'>
        <!-- 修改HTML内容 -->
    </div>
    """

场景4：调整样式颜色

文件： ui_styles.py

def get_custom_css():
    return """
    .main-title {
        background: linear-gradient(135deg, #新颜色1, #新颜色2);
    }
    """

场景5：更改默认参数

文件： config.py

DEFAULT_DEN_COEFFS = "1,8,15,8"  # 更改默认分母系数
SERVER_PORT = 8080               # 更改服务器端口

🔧 依赖库

gradio>=5.0.0
numpy>=1.21.0
matplotlib>=3.5.0
scipy>=1.7.0
control>=0.9.0
aiohttp>=3.8.0  # AI聊天功能

安装命令：

pip install gradio numpy matplotlib scipy control aiohttp

⚠️ 注意事项

1. 首次运行： 需要在config.py中配置DeepSeek API密钥才能使用AI聊天功能
2. 端口冲突： 如果7860端口被占用，修改config.py中的SERVER_PORT
3. 模块导入： 所有模块必须在同一目录下
4. Python版本： 建议使用Python 3.8+

📊 代码对比

指标	原版 (app.py)	模块化版本
总代码行数	2134行	分散在7个文件
主程序行数	2134行	350行 (↓84%)
可维护性	⭐⭐	⭐⭐⭐⭐⭐
可扩展性	⭐⭐	⭐⭐⭐⭐⭐
团队协作	⭐⭐	⭐⭐⭐⭐⭐

🎓 学习建议

1. 初学者： 先运行app_main.py，熟悉整体功能
2. 进阶学习： 阅读各模块代码，理解功能实现
3. 高级应用： 尝试添加新功能或修改现有模块
4. 问题排查： 参考模块注释和本文档

📮 联系方式

项目负责人： 魏鹏飞 教授
邮箱： pengfeiwei@nwpu.edu.cn
单位： 西北工业大学
资助： 2025年校级本科生建设项目

---

最后更新： 2025年1月
版本： 2.0 (模块化架构)