# CLAUDE.md

> [!URGENT]
> 1. 本项目是**学习驱动的科研重构项目**：通过分层重建 OmniOPD 参考实现来学习论文方法，同时产出可作为后续研究基座的干净代码库。学习优先——用户要逐章理解每个模块，**不要一次性替用户写完所有代码**；每章先讲清楚，重构任务由用户主导、你配合。
> 2. 所有思考过程和回复必须使用**简体中文**。

## 1. 项目元数据

- **论文**: OmniOPD (arXiv:2606.01476v2)，logit-free 的 chunk 级 on-policy 蒸馏。PDF 在 `references/2606.01476v2.pdf`
- **参考实现**: `references/ars-opd/`（**只读、不入 git**），核心在 `trl/trl/experimental/distillation/`
- **Conda 环境**: `ars-opd`（Python 3.11）；远程环境建在 `/data` 下（根分区已满）
- **版本管理**: git，远程 `git@gitea.iomgaa.online:iomgaa/ars-opd-rebuild.git`，本地 push → 远程 pull 同步

## 2. 架构哲学（Ousterhout 深模块，非 Clean Architecture）

- **模块按论文概念划分，不按技术角色划分**。判据：看到论文某公式能说出它在哪个文件；打开一个文件能说出它对应论文哪一节。
- **纯逻辑核心 / IO 边缘**：`similarity.py`、`chunking.py`、`estimator.py` 是纯逻辑模块——只依赖 torch/numpy 标准运算，**禁止** import transformers / vllm / openai / requests；所有外部 IO 收口在 `teacher.py`（API/vLLM 客户端）与 `trainer.py`（模型编排）。纯逻辑模块必须能在本地 CPU 上用 toy 数据测试。
- **不做防御性膨胀**：不写接口层/工厂/注册表；一个模块从上读到下能看懂全部流程。但纯逻辑模块必须有单元测试（对拍参考实现）。
- **配置显式化**：所有实验参数走 `configs.py` 的 dataclass；**严禁**硬编码路径、模型名、URL（参考实现里的 `/fsx` 硬编码是反面教材）。密钥走 `.env`。

## 3. 模块 ↔ 论文映射（单一事实源）

| 模块 | 论文 | 内容 |
|------|------|------|
| `ars_opd/similarity.py` | §3.2.1 式(3) | 语义相似度 φ（rouge1 / edit_distance） |
| `ars_opd/estimator.py` | §3.2.2 式(4)(5) | MC 估计 + Dirichlet 贝叶斯平滑 π̂ |
| `ars_opd/chunking.py` | §3.2.3 式(6)(7) | 熵计算 + peak-entropy chunk 选择 |
| `ars_opd/teacher.py` | §3.2.1 | teacher rollout 采样（OpenAI 兼容 API + 缓存 / vLLM） |
| `ars_opd/trainer.py` | §3.2.4 式(8) | chunk 蒸馏损失 + trust-region KL 锚定，编排全流程 |

## 4. 常用命令

```bash
conda activate ars-opd && pytest tests/ -x -q     # 单元测试（本地 CPU）
conda activate ars-opd && ruff check ars_opd/ --fix && ruff format ars_opd/
```

## 5. 本地-远程规则

> [!CRITICAL]
> - 远程机 gpu-a800-060：8×A800-80G，**只允许用其中 4 块**；所有 GPU 命令必须显式 `CUDA_VISIBLE_DEVICES=<idx>`，先 `nvidia-smi` 确认空闲卡，严禁自动选卡。
> - 远程**根分区仅剩 12G**：conda 环境、HF 缓存（`HF_HOME`）、模型、checkpoint、数据集一律放 `/data/zym/` 下。
> - 长任务用 tmux 跑，日志不缓存（`python -u` / `PYTHONUNBUFFERED=1`），确保可实时检查。
> - 远程机器上不改代码，只 `git pull` + 跑脚本；本地不跑训练。

## 6. 学习工作流

1. 章节文档在 `docs/`，按 `docs/00-roadmap.md` 的分层顺序推进；每章结构：论文精读 → 参考实现解剖（带行号）→ 重构任务 → 验证方式。
2. 重构一个模块前，先对照参考实现列出其全部行为（含 trick 和 workaround），逐一确认保留/替代/删除。
3. 每个纯逻辑模块完成后，用 toy 数据对拍参考实现的对应逻辑（参考其 `validate_mc_estimator.py` / `validate_chunk_mc_estimator.py`）。
4. 文档规范：优先表格与公式，代码块 ≤15 行（展示思路用伪代码，完整代码引用文件路径），引用参考实现必须带 `文件:行号`。
5. **每层完成后做接口回看**：逐模块自问"接口是否比实现简单得多"（深模块判据）；若某接口的参数/约定复杂到接近实现本身，先记录并重构，再进入下一层。规则来源与哲学对照见 `docs/appendix-claudemd-decisions.md`。

## 7. 代码规范（教学导向）

**注释分工**：`docs/` 章节负责讲原理，代码注释负责做索引，两者不重复。代码注释只写三类内容：

| 类型 | 要求 | 示例 |
|------|------|------|
| 论文锚点 | 实现论文公式/机制的函数，docstring 首行标出处；关键行旁给公式本体 | `# 式(5): π̂ = (k_sem + α·π̄) / (N + α)` |
| 非显然约束 | 只解释"为什么必须这样"及违反后果，不解释"这行在干什么"；load-bearing 的反直觉点必须写 | `# π̂ 必须 detach：否则学生通过抬高自身先验自我强化，训练塌缩` |
| 差异标注 | 凡有意偏离论文或参考实现处，注明对方做法与我们的理由 | `# 参考实现(trainer:2205)对 chunk 内取 mean，论文式(8)为 sum，此处从论文` |

**类型与 shape**：
- 模块间公共接口（`ars_opd/` 各模块导出的函数/类）强制完整类型注解——接口注解本身就是教学信息；模块内私有 helper 从宽。
- 类型注解表达不了张量 shape，故 shape 是硬要求：docstring 注明参数/返回的 shape，函数体内关键变换旁加行注释（如 `# (B, T, V) -> (B, T)`）。
- docstring 用中文，含功能、参数、返回、关键实现细节。

**其余硬规则**：
- **严禁** `except Exception: pass`；出错直接报错，不用默认值兜底。
- 提交信息用中文，说明"这一步对应哪一章/哪个模块"。