MathLab

MathLab

一个面向深度学习/强化学习学习者的数学课件编译与部署仓库。

目标是把“抽象数学符号”转成“可执行的工程理解路径”：

• 课程 HTML（直觉 + 推导 + 工程映射）
• 练习代码（可运行）
• 测试用例（可验证）

---

1. 项目目标

MathLab 聚焦 3 件事：

1. 符号脱敏：把公式和符号映射为代码语义（例如 ∇ → gradient，E[] → 采样均值）
2. 工程落地：每一课都对应可执行练习和测试
3. 可持续交付：通过批处理 + 日部署形成稳定内容流水线

---

2. 教材与范围

当前教材根目录（配置）：

/mnt/ai/textbooks

当前覆盖方向：

• 统计学习方法（感知机、KNN、朴素贝叶斯、EM、HMM）
• 深度学习核心章节（计算图、卷积、注意力）
• 强化学习数学基础（Bellman 方程、价值迭代、策略迭代）

本仓库仅保留数学学习与课件生产相关内容。

---

3. 目录结构

.
├── courseware/                 # 正式课件输出（HTML/学习文档）
├── exercises/                  # 正式练习代码
├── tests/                      # 正式测试代码
├── staging/                    # 编译暂存区（批处理先输出到这里）
│   ├── course_dayN.html
│   ├── exercises/dayN_task.py
│   └── tests/test_dayN.py
├── skills/
│   ├── mathlab/                # 主技能（当前使用）
│   │   ├── SKILL.md
│   │   ├── config.yaml
│   │   └── scripts/
│   │       ├── check_env.py
│   │       ├── compile_day.py
│   │       ├── deploy_day.py
│   │       └── pdf_to_md.py
│   └── math-textbook-compiler/ # 历史/参考技能
├── templates/                  # 练习与测试模板
└── scripts/                    # 辅助脚本

---

4. 工作流

A) 批处理编译（通常每周一次）

将某一 Day 的主题编译到 staging/：

python3 skills/mathlab/scripts/compile_day.py --day 1 --topic "感知机"

输出：

• staging/course_day1.html
• staging/exercises/day1_task.py
• staging/tests/test_day1.py

B) 单日部署（通常每天一次）

将 staging 内容发布到正式目录并做 Git 交付：

python3 skills/mathlab/scripts/deploy_day.py --day 1 --topic "感知机"

部署动作包括：

1. 复制文件到 courseware/ exercises/ tests/
2. Git commit
3. 打 tag（如 v_day1_感知机）
4. 推送远程仓库

---

5. 环境依赖

推荐依赖：

• Python 3.10+
• pyyaml
• pytest
• numpy
• jinja2
• pdftotext（用于 PDF 转文本）

环境检查：

python3 skills/mathlab/scripts/check_env.py

---

6. 配置说明（skills/mathlab/config.yaml）

关键字段：

• textbook_path: 教材根目录
• textbooks: 教材列表、阶段与主题
• gogs_url: 远程仓库地址
• git_branch: 推送分支
• output: staging / courseware / exercises / tests 输出目录
• notification: 通知开关与模板

---

7. Git 远程规范

当前统一规范：

• 服务器：https://code.indigofloyd.space
• 组织：ClawLab
• 项目：mathlab

远程示例：

git remote set-url origin https://code.indigofloyd.space/ClawLab/mathlab.git

---

8. 课件设计原则

每个 Day 的课件建议保持固定结构：

1. 技术债与演进动机
2. 直觉建立
3. 符号解码字典（数学 → 代码）
4. 核心推导
5. 工程优化点
6. 今日靶机（练习任务）

这样可保证“理解-实现-验证”的闭环。

---

9. 后续开发协作约定

后续新增功能时，默认先给出思维导图式任务拆解（逻辑与层级），再进入编码执行。

目的：

• 让需求、模块边界、依赖关系透明
• 让实现过程可复盘、可教学

---

10. 常见命令速查

# 查看仓库状态
git status

# 编译 Day N
python3 skills/mathlab/scripts/compile_day.py --day N --topic "主题"

# 部署 Day N
python3 skills/mathlab/scripts/deploy_day.py --day N --topic "主题"

# 运行测试（示例）
pytest -q tests/

---

如果你希望，我可以在下一步把“每日自动化部署 + Feishu 附件推送”再整理成一套可直接复用的 SOP。