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 训练格式转换混在一起。