# MathLab

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

目标是把“抽象数学符号”转成“可执行的工程理解路径”：
- 课程 HTML（直觉 + 推导 + 工程映射）
- 练习代码（可运行）
- 测试用例（可验证）

---

## 1. 项目目标

MathLab 聚焦 3 件事：

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

---

## 2. 教材与范围

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

`/mnt/ai/textbooks`

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

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

---

## 3. 目录结构

```text
.
├── 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/`：

```bash
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 交付：

```bash
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 转文本）

环境检查：

```bash
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`

远程示例：

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

---

## 8. 课件设计原则

每个 Day 的课件建议保持固定结构：
1. 技术债与演进动机
2. 直觉建立
3. 符号解码字典（数学 → 代码）
4. 核心推导
5. 工程优化点
6. 今日靶机（练习任务）

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

---

## 9. 后续开发协作约定

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

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

---

## 10. 常见命令速查

```bash
# 查看仓库状态
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。