docs/deployment/linux_codex_handoff.md

# Linux Codex Handoff

这份说明面向把仓库迁移到 Linux 服务器后，继续使用 Codex 无缝接手。

## 1. 这个交接包的目标

这个交接包优先保留以下内容：

- 仓库使命与长期目标
- 当前稳定的数据契约
- 架构文档与路线图
- Linux 首次实验清单
- 关键可执行代码
- 最小测试

也就是说，这个包优先保证：

1. Codex 在 Linux 上进入仓库后能快速读懂上下文
2. 你可以先跑通当前最稳定的受控实验链路
3. 不把巨大的历史数据和运行产物一股脑塞进迁移包

## 截至 2026-03-23 的交接补充

- Linux 上已经不只是“可开训”，而是实验 A 已完整训练结束并拿到首轮有效检测指标。
- 当前训练统一环境仍是 `lsy-agent`。
- 当前验证链路已经接通真实模型输出，且默认支持 `vllm` 推理。
- 迁移或接手时需要额外注意一件事：历史 vLLM 进程如果未清理，会长期占用 4 张卡，影响后续正式训练启动。
- 当前最值得保留的运行产物不是所有 `runs/`，而是实验 A 的训练日志、merged checkpoint 路径说明，以及验证结果摘要。

## 2. 建议保留在交接包中的内容

- `AGENTS.md`
- `README.md`
- `requirements.txt`
- `.env.example`
- `base_agent.py`
- `run_pipeline_silver.py`
- `agents/`
- `schemas/`
- `pipelines/`
- `tests/`
- `docs/`

其中最重要的文档读取顺序保持不变：

1. `AGENTS.md`
2. `README.md`
3. `docs/architecture.md`
4. `docs/roadmap.md`
5. `docs/current_status.md`
6. `docs/reference/repo_map.md`
7. `docs/deployment/deploy_linux.md`
8. `docs/deployment/linux_first_experiment_checklist.md`

## 3. 默认不放进交接包的大体积内容

以下内容通常不建议放进首次 Codex 迁移包：

- `clearn_base_data/`
- `base_data/`
- `runs/`
- `__pycache__/`
- 各类 `.pyc`
- 临时 jsonl、临时 notebook、临时测试文件

原因很简单：

- 这些内容体积大
- 很多是可再生成的运行产物
- 会显著拖慢首次传输和解压
- 不影响 Codex 先接手代码、文档和实验流程

## 4. Linux 上首次接手建议

解压后，建议先做以下动作：

1. 阅读 `AGENTS.md`
2. 阅读 `README.md`
3. 阅读 `docs/deployment/linux_first_experiment_checklist.md`
4. 创建虚拟环境并安装依赖
5. 配置 `.env`
6. 跑 `tests.test_reviewer`
7. 跑 `tests.test_gold_builder`

## 5. 如果之后要补回数据

如果你后续要在 Linux 上继续做实际实验，再单独补这些内容即可：

- 图片目录
- 历史 `runs/` 结果
- cleaned Silver 数据集
- Gold 数据集

建议把“代码与文档交接包”和“数据资产包”分开管理。

## 6. 当前最稳妥的 Linux 实验边界

当前最稳妥的稳定边界仍然是以下数据链路：

1. Silver 小样本试跑
2. cleaned Silver
3. Silver Eval
4. Gold 构建

训练链路已进入真实开训阶段，但仍需继续收敛训练框架兼容性、日志规范与评估闭环

以下模块目前还不应被视为已经可以无缝投入正式闭环实验：

- `SemanticEvaluator`
- `Orchestrator`

## 7. 给 Linux 上的 Codex 的一句话上下文

这个仓库当前的核心不是训练框架，而是稳定的结构化数据分层。任何继续开发都必须优先保护 `Raw -> Silver -> Gold -> Eval` 的边界，尤其不要把 Silver 审核逻辑和 Gold 训练格式转换混在一起。