diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..a3330f8 --- /dev/null +++ b/.gitignore @@ -0,0 +1,49 @@ +# AutoControl - 自动控制原理AI+数智平台 + +.DS_Store +*.pyc +__pycache__/ +*.py[cod] +*$py.class + +# 虚拟环境 +venv/ +env/ +ENV/ +.venv +.conda/ + +# IDE 配置 +.vscode/ +.idea/ +*.swp +*.swo +*~ + +# Jupyter Notebook +.ipynb_checkpoints + +# 环境变量文件 +.env +.env.local + +# 日志文件 +*.log + +# 临时文件 +*.tmp +*.bak + +# 系统文件 +Thumbs.db +Desktop.ini + +# 打包文件 +dist/ +build/ +*.egg-info/ + +# API 密钥配置(如果单独管理) +config.json +secrets.json +api_keys.txt diff --git a/API_CONFIG.md b/API_CONFIG.md new file mode 100644 index 0000000..8d2625b --- /dev/null +++ b/API_CONFIG.md @@ -0,0 +1,201 @@ +# API 配置指南 + +本文档详细说明如何配置 DeepSeek 和 Gemini API。 + +## 📋 目录 + +- [DeepSeek API 配置](#deepseek-api-配置) +- [Gemini API 配置](#gemini-api-配置) +- [常见问题](#常见问题) + +--- + +## 🚀 DeepSeek API 配置 + +### 1. 获取 API 密钥 + +1. 访问 [DeepSeek 平台](https://platform.deepseek.com/) +2. 注册账号并登录 +3. 进入 [API Keys 页面](https://platform.deepseek.com/api_keys) +4. 点击"创建新密钥" +5. 复制生成的 API 密钥(格式:`sk-xxxxxxxxxxxxxxxx`) + +### 2. 配置到应用 + +编辑 `app.py` 文件的配置区域(第 7-28 行): + +```python +# ==================== API 配置 ==================== +API_KEY = "sk-your-api-key-here" # 粘贴您的 DeepSeek API 密钥 +API_BASE_URL = "https://api.deepseek.com/v1" +API_MODEL = "deepseek-chat" # 或 "deepseek-coder" +API_TYPE = "deepseek" +# ================================================== +``` + +### 3. 可用模型 + +| 模型名称 | 适用场景 | 特点 | +|---------|---------|------| +| `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" +python app.py +``` + +**Linux/Mac:** +```bash +export DEEPSEEK_API_KEY="sk-your-key" +python app.py +``` + +然后在代码中读取: +```python +import os +API_KEY = os.environ.get("DEEPSEEK_API_KEY", "") +``` + +### 方法 2:配置文件 + +创建 `config.json`(不要提交到 Git): + +```json +{ + "api_key": "sk-your-key", + "api_base_url": "https://api.deepseek.com/v1", + "api_model": "deepseek-chat", + "api_type": "deepseek" +} +``` + +在代码中加载: +```python +import json + +with open('config.json', 'r') as f: + config = json.load(f) + API_KEY = config['api_key'] + API_BASE_URL = config['api_base_url'] + # ... +``` + +--- + +## ❓ 常见问题 + +### Q1: API 请求失败,显示 401 错误 + +**原因**:API 密钥无效或未配置 + +**解决**: +1. 检查 API 密钥是否正确复制(无多余空格) +2. 确认密钥未过期或被删除 +3. 重新生成密钥并更新配置 + +### Q2: 网络连接错误 + +**原因**:网络问题或 API 服务不可达 + +**解决**: +1. DeepSeek 用户:检查国内网络连接 +2. Gemini 用户:可能需要配置网络代理 +3. 尝试切换到 DeepSeek API(国内友好) + +### Q3: 回复速度慢或超时 + +**原因**:网络延迟或 API 负载高 + +**解决**: +1. 检查网络连接速度 +2. 调整超时设置(app.py 中的 `ClientTimeout`) +3. 尝试切换模型(如 flash 版本) + +### Q4: 公式不渲染 + +**原因**:Chatbot 未启用 LaTeX 支持 + +**解决**: +确认 `gr.Chatbot` 包含 `latex_delimiters` 参数: +```python +chatbot = gr.Chatbot( + latex_delimiters=[ + {"left": "$$", "right": "$$", "display": True}, + {"left": "$", "right": "$", "display": False} + ] +) +``` + +### Q5: 如何限制 API 调用成本? + +**建议**: +1. 在 API 平台设置使用限额 +2. 代码中添加 `max_tokens` 限制 +3. 监控 API 使用情况 +4. 使用轻量级模型(如 flash 版本) + +--- + +## 📞 获取帮助 + +- **DeepSeek 文档**:https://platform.deepseek.com/docs +- **Gemini 文档**:https://ai.google.dev/docs +- **项目 Issues**:[GitHub Issues 链接] + +--- + +最后更新:2025年10月15日 diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..1fa6f77 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,60 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +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). + +## [1.0.0] - 2025-10-15 + +### Added +- ✨ 时域分析功能(阶跃响应、脉冲响应、性能指标计算) +- ✨ 频域分析功能(Bode 图、Nyquist 图、稳定裕度) +- ✨ 根轨迹分析功能(动态轨迹绘制、增益调节、极点跟踪) +- ✨ AI 智能问答功能(支持 DeepSeek 和 Gemini API) +- 🎨 现代化 UI 设计(渐变色、卡片布局、可滚动知识区) +- 📚 详细的知识卡片(时域、频域、根轨迹理论) +- 🔧 对数增益滑块(精确调节 0.1 到 1000 范围) +- 💬 LaTeX 公式渲染(聊天机器人内数学公式支持) +- 📊 英文图表标签(避免中文显示问题) + +### Features +- 支持任意阶次线性时不变(LTI)系统分析 +- 实时参数调节和图表更新 +- 流式 AI 对话响应 +- 标签页切换自动加载数据 +- 可折叠的知识点章节 + +### Documentation +- 📄 完整的 README.md +- 📄 API 配置指南(API_CONFIG.md) +- 📄 快速上手指南(QUICK_START.md) +- 📄 依赖列表(requirements.txt) +- 📄 .gitignore 配置 +- 📄 MIT 开源许可证 + +## [Unreleased] + +### Planned +- [ ] 状态空间分析模块 +- [ ] 离散系统分析支持 +- [ ] 更多控制器设计工具(PID 调优、极点配置) +- [ ] 系统对比功能(多个传递函数对比) +- [ ] 导出分析报告(PDF/Word) +- [ ] 历史记录保存 +- [ ] 更多 AI 模型支持 +- [ ] 多语言界面(英文版) +- [ ] 移动端适配 + +--- + +## Version History + +### v1.0.0 (2025-10-15) +- 🎉 首次正式发布 +- 包含四大核心功能模块 +- 完整的文档和配置文件 + +--- + +**Note**: For detailed commit history, see the [Git log](https://github.com/your-repo/commits). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6af4bef --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,171 @@ +# 贡献指南 + +感谢您对本项目的关注!我们欢迎任何形式的贡献。 + +## 🤝 如何贡献 + +### 报告 Bug + +如果您发现了 Bug,请: + +1. 在 [Issues](https://github.com/your-repo/issues) 中搜索是否已有相同问题 +2. 如果没有,创建新 Issue,包含: + - 清晰的标题 + - Bug 复现步骤 + - 预期行为 vs 实际行为 + - 系统环境(操作系统、Python 版本等) + - 错误截图或日志(如果有) + +### 提出新功能 + +如果您有新功能建议: + +1. 创建 Feature Request Issue +2. 描述功能的用途和价值 +3. 提供可能的实现思路(可选) + +### 提交代码 + +#### 准备工作 + +1. Fork 本仓库 +2. 克隆到本地: + ```bash + git clone https://github.com/your-username/AutoControl.git + cd AutoControl + ``` +3. 创建新分支: + ```bash + git checkout -b feature/your-feature-name + ``` + +#### 开发规范 + +**代码风格**: +- 遵循 PEP 8 Python 代码规范 +- 使用有意义的变量名和函数名 +- 添加必要的注释和文档字符串 + +**提交信息**: +``` +(): + + + +