StrideFlow AI - 马拉松训练教练

一个基于 AI 的智能马拉松/半程马拉松训练计划生成和动态调整系统。

💡 设计哲学 (Design Philosophy)

本项目旨在探索 AI Agent 在垂直领域的深度应用，通过 RAG (检索增强) 与 Quality Gate (质量门控) 构建闭环，解决通用大模型在专业场景下的幻觉与不可控问题。

1. 动态适应 (Dynamic Adaptation): 针对真实场景中的不确定性（如缺练、受伤），系统具备“感知-决策-调整”的闭环能力，而非静态的单次生成。
2. 循证科学 (Evidence-Based): 摒弃“黑盒”生成，通过 RAG 挂载专业运动科学知识库，确保训练建议的可解释性与专业度。
3. 安全可控 (Safety & Control): 引入确定性的规则引擎作为 AI 输出的“护栏”，自动校验周跑量增幅与减量逻辑，保障训练计划的安全性。

功能特性

• 🎯 个性化训练计划: 根据您的目标、当前水平和训练时间生成12周结构化训练计划
• 🔄 智能重新安排: 当您错过训练时，AI会自动调整计划，保持训练进度
• 📊 专业界面: 采用运动科技风格的深色主题界面
• 🧠 模块化提示词: 使用XML模板管理提示词，易于维护和迭代

项目结构

StrideFlow-AI/
├── app.py                 # Streamlit 主应用
├── config_rag.py         # RAG 配置（路径、Top-K、开关等）
├── CONFIG.md              # API 与 401 排查说明
├── test_api.py            # API 配置验证脚本
├── prompts/               # 提示词模板目录
│   ├── generator_v1.xml   # 训练计划生成提示词
│   └── rescheduler_v1.xml # 计划重新安排提示词
├── rag/                   # RAG 模块（分块、索引、检索）
│   ├── chunk_utils.py     # 文本分块（TXT/MD）
│   ├── indexer.py         # 建索引（Chroma + BGE）
│   └── retriever.py       # 检索与格式化
├── data/
│   └── books/             # 将 TXT/MD 书籍放于此目录（Chroma 索引在 data/chroma，已 gitignore）
├── docs/                  # 文档
├── requirements.txt       # Python 依赖
└── README.md

安装和运行

1. 安装依赖

pip install -r requirements.txt

2. 配置 API（DeepSeek）

本项目使用 DeepSeek API（OpenAI 兼容接口）。在项目根目录创建 .env 文件：

OPENAI_API_KEY=sk-你的DeepSeek密钥
OPENAI_BASE_URL=https://api.deepseek.com

详细步骤与 401 排查见 CONFIG.md。

3. 运行应用

streamlit run app.py

应用将在浏览器中打开，默认地址: http://localhost:8501

使用说明

生成训练计划

1. 在左侧边栏填写您的信息：

   • 目标比赛类型（半程/全程马拉松）
   • 当前5公里最佳成绩
   • 每周训练天数（3-6天）
   • 目标比赛日期

2. 点击"生成我的训练计划"按钮

3. 系统将根据您的信息生成个性化的12周训练计划

记录训练和重新安排

1. 在「对话补充」区域输入您的训练反馈（如「周二没跑」）
2. 点击「发送」后再点击「根据对话更新计划」
3. AI 会智能调整您的训练计划，确保训练进度不受影响

知识库 RAG（可选）

若希望生成/更新计划时参考跑步或营养书籍：

1. 将 TXT 或 Markdown 格式的电子书放入项目目录 data/books/
2. 在侧边栏展开「📚 知识库 RAG」，勾选「启用 RAG」，点击 「重建知识库」
3. 首次建索引会从 Hugging Face 下载 BGE 模型（需联网），之后生成或更新计划时会自动注入检索到的片段

不放入书籍或不建索引时，行为与未启用 RAG 时一致，不影响正常使用。

提示词模板

generator_v1.xml

用于生成初始训练计划的XML模板，包含：

• 用户画像信息
• 训练计划生成指令
• 配速计算逻辑
• 阶段化训练原则

rescheduler_v1.xml

用于动态调整训练计划的XML模板，包含：

• 重新安排规则
• 调整指导原则
• 安全考虑因素

技术架构

• 前端: Streamlit
• 提示词管理: Python string.Template + XML 格式
• LLM: DeepSeek API（OpenAI 兼容），模型名等可通过环境变量配置（见 CONFIG.md）

故障排除

API调用失败

如果遇到API调用失败，请按以下步骤排查：

1. 检查API配置

   # 运行测试脚本
   python test_api.py

2. 常见错误及解决方案

   • 401 Unauthorized: API密钥无效或过期

     • 检查 .env 文件中的 OPENAI_API_KEY 是否正确
     • 确认API密钥有足够的权限

   • 404 Not Found: 端点或模型不存在

     • 检查 OPENAI_BASE_URL 是否正确（DeepSeek应为 https://api.deepseek.com）
     • 确认模型名称为 deepseek-chat

   • 429 Rate Limit: 请求频率过高

     • 等待一段时间后重试
     • 检查API配额限制

   • Connection Error: 网络连接问题

     • 检查网络连接
     • 检查防火墙和代理设置

3. 查看详细错误信息

   • 在应用界面中点击错误信息下方的"详细错误信息"展开按钮
   • 查看完整的错误堆栈信息

4. 验证配置

   • 在侧边栏展开"⚙️ API配置状态"查看当前配置
   • 确认所有必要的环境变量都已设置

待办事项

• 训练计划导出为 Markdown（主区「下载计划」）
• 导出 PDF/Excel
• 训练数据可视化增强
• 更多训练类型与个性化选项

许可证

MIT License