docs/reference/repo_map.md

# Repo Map

这个文档用于帮助后续代理快速识别仓库中的关键目录、关键脚本和推荐调用入口。

## 最高优先级上下文

新会话开始时优先阅读：

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

## 论文对齐文档

- `docs/paper_alignment.md`
  记录 AgriAgent 论文构想、当前仓库可支撑的材料、尚未完成的实验，以及下一步最应该补齐的证据链。后续写论文或设计实验时应优先查看。

## 截至 2026-03-31 的关键新增定位

- 实验 A 正式训练日志：`runs/logs/tomato-exp-a-official_20260323-201257.log`
- 实验 A merged 模型：`runs/mid/qwen3_5_35b_a3b_exp_a_official/v4-20260323-201311/checkpoint-151-merged/`
- 实验 A 验证结果目录：`runs/validation_eval/qwen3_5_35b_a3b_exp_a_official/`
- 实验 B 正式训练日志：`runs/logs/tomato-exp-b-attr_20260331-192847.log`
- 实验 B merged 模型：`runs/mid/qwen3_5_35b_a3b_exp_b_attr/v1-20260331-192847/checkpoint-145-merged/`
- 实验 B 首轮验证结果目录：`runs/validation_eval/qwen3_5_35b_a3b_exp_b_attr/`
- 实验 A/B 三联对比图目录：`runs/validation_compare/exp_a_vs_b_20260331_201545/`
- 当前验证推理入口：`pipelines/run_validation_inference.py`，默认支持 `vllm` 与 `transformers` 双后端，且已修复 assistant 输出模板丢失问题
- 当前可视化入口：`pipelines/visualize_validation_comparison.py`
- 当前重要回归测试：`tests/test_semantic_evaluator.py`，已覆盖字符串 bbox + think 包裹输出，以及 assistant 模板转显式 JSON 约束

## 顶层目录说明

### `agents/`

放置核心智能体实现。

关键文件：

- `agents/cognitive_annotator.py`
  云端多模态标注智能体。输入图像，输出单图多目标结构化结果。
- `agents/multimodal_reviewer.py`
  审核智能体。负责 bbox 坐标转换、业务校验、超小框过滤。
- `agents/vlm_operator.py`
  训练操作器骨架；训练命令模板已先落在 `scripts/`，后续应回填这里。
- `agents/semantic_evaluator.py`
  语义评估器；当前已支持结构化 prediction vs reference 对比。
- `agents/orchestrator.py`
  闭环编排器骨架。

### `schemas/`

放置当前数据契约定义。

关键文件：

- `schemas/annotation.py`
  Raw annotation 相关 TypedDict。
- `schemas/review.py`
  Silver record 相关 TypedDict。
- `schemas/dataset_record.py`
  Gold 和训练样本相关 TypedDict。

说明：

- 当前所有实现都应优先遵守这里的最新数据契约。

### `pipelines/`

放置当前最重要的可执行数据流程脚本。

关键文件：

- `pipelines/gold_builder.py`
  从 Silver 聚合生成 Gold，并输出发布摘要与抽样检查。
- `pipelines/check_gold_regression.py`
  对比两版 Gold 发布摘要，输出回归检查结论。
- `pipelines/manual_qc.py`
  对 Silver 做按图抽样人工复核。
- `pipelines/evaluate_silver_dataset.py`
  对 Silver 做结构化评估和风险样本导出。
- `pipelines/clean_silver_dataset.py`
  对既有 Silver 做规则清洗和重建。
- `pipelines/evaluate_semantic_predictions.py`
  对结构化预测结果做逐图语义评估。
- `pipelines/export_swift_sft_dataset.py`
  将 Gold 导出为 Swift / Megatron-SWIFT grounding 训练数据，支持 `official` 和 `attr_enhanced` 两种实验模式。
- `pipelines/run_validation_inference.py`
  对 Swift `val.jsonl` 运行真实模型验证推理，当前已支持把 `assistant` 模板转成显式输出约束。
- `pipelines/visualize_validation_comparison.py`
  生成 GT / 实验 A / 实验 B 的三联对比图，便于肉眼排查空框、漏检和属性差异。

### `runs/`

放置所有运行快照和产物。

当前重要子目录：

- `runs/silver/`
  Silver 主链路运行快照和数据集输出。
- `runs/evaluation/`
  Silver 评估摘要、报告和风险预览图。
- `runs/silver_cleaning/`
  Silver 清洗摘要和被丢弃记录。
- `runs/manual_qc/`
  人工复核清单和预览图。
- `runs/gold/`
  正式 Gold 发布目录。
- `runs/gold_regression/`
  Gold 回归检查报告。
- `runs/swift_data/`
  训练数据导出结果，包括实验 A / B 两套 grounding 数据。

### `tests/`

放置当前最小测试。

关键文件：

- `tests/test_reviewer.py`
  reviewer 的 bbox 换算和超小框过滤测试。
- `tests/test_gold_builder.py`
  Gold 聚合行为测试。
- `tests/test_gold_regression.py`
  Gold 回归检查测试。
- `tests/test_semantic_evaluator.py`
  结构化语义评估测试。
- `tests/test_swift_sft_export.py`
  Swift / Megatron-SWIFT 训练数据导出测试。

### `docs/`

放置项目说明和协作文档。

关键文件：

- `docs/architecture.md`
- `docs/roadmap.md`
- `docs/current_status.md`
- `docs/paper_alignment.md`
- `docs/reference/repo_map.md`
- `docs/deployment/deploy_linux.md`

## 当前最重要的数据资产

### 原始全量新版 Silver

- `runs/silver/full_rerun_20260311_210637/silver_dataset.jsonl`

### 当前推荐优先使用的 cleaned Silver

- `runs/silver/full_rerun_20260311_210637_cleaned/silver_dataset.jsonl`

### 最近一次 Silver 清洗摘要

- `runs/silver_cleaning/silver_clean_20260311_223551/summary.json`

### 最近一次 cleaned Silver 评估摘要

- `runs/evaluation/silver_eval_20260311_223604/summary.json`

### 当前正式 Gold 基线

- `runs/gold/gold_release_v1/gold_dataset.jsonl`

### 当前 Qwen3.5 训练数据

- `runs/swift_data/qwen3_5_35b_a3b_exp_a_official_v2/`
- `runs/swift_data/qwen3_5_35b_a3b_exp_b_attr_v2/`

### 当前训练脚本

- `scripts/train_qwen3_5_35b_a3b_exp_a_official.sh`
- `scripts/train_qwen3_5_35b_a3b_exp_b_attr.sh`

## 推荐调用入口

### 1. Silver 主链路

```bash
python run_pipeline_silver.py --process-limit 10
```

常用环境变量：

- `QWEN_API_KEY`
- `QWEN_BASE_URL`
- `QWEN_MODEL`
- `PROCESS_LIMIT`
- `MIN_BBOX_1000_SIDE`
- `MIN_BBOX_1000_AREA`

### 2. 评估 Silver 数据集

```bash
python -m pipelines.evaluate_silver_dataset \
  --silver-dataset-path <silver_jsonl_path> \
  --risk-sample-size 12
```

建议用途：

- 新 Silver 重跑后第一时间做结构测评。
- 导出高风险图做人工复核。
- 对比原始 Silver 和 cleaned Silver 的质量变化。

### 3. 清洗既有 Silver 数据集

```bash
python -m pipelines.clean_silver_dataset \
  --input <source_silver_jsonl> \
  --output <target_silver_jsonl> \
  --min-bbox-1000-side 20 \
  --min-bbox-1000-area 400
```

建议用途：

- reviewer 规则升级后快速重建 Silver。
- 不重新请求模型 API 的情况下发布 cleaned Silver 新版本。

### 4. 人工复核

```bash
python -m pipelines.manual_qc \
  --silver-dataset-path <silver_jsonl_path> \
  --sample-size 12
```

建议用途：

- 对小样本或高风险图做人工复核。
- 重点检查 bbox grounding、target selection、成熟度与漏标/乱标。

### 5. Gold 构建

```bash
python -m pipelines.gold_builder \
  --silver-dataset-path <silver_jsonl_path> \
  --output-dir runs/gold/gold_release_v1
```

建议用途：

- 在 cleaned Silver 稳定后生成正式 Gold。
- 统一产出 `gold_dataset.jsonl`、`summary.json`、`report.md`、`sample_check.jsonl`。
- 保持训练格式生成逻辑不回流污染 Silver 阶段。

### 6. Gold 回归检查

```bash
python -m pipelines.check_gold_regression \
  --baseline runs/gold/gold_release_v1 \
  --candidate runs/gold/gold_release_v2
```

建议用途：

- 发布新 Gold 前后对比图像数、目标数和分布漂移。
- 检查路径重写和质量检查布尔项是否退化。
- 生成 `summary.json` 和 `report.md` 作为版本说明附件。

### 7. Semantic Evaluator

```bash
python -m pipelines.evaluate_semantic_predictions \
  --reference-dataset-path runs/gold/gold_release_v1/gold_dataset.jsonl \
  --prediction-dataset-path runs/predictions/model_a_predictions.jsonl
```

建议用途：

- 比较模型结构化预测结果与 Gold 基线的差异。
- 输出逐图结果、风险样本和整体摘要。
- 为后续漏标挖掘与伪标签筛选提供基础评估层。

### 8. 导出 Qwen3.5 训练数据

```bash
python -m pipelines.export_swift_sft_dataset \
  --gold-dataset-path runs/gold/gold_release_v1/gold_dataset.jsonl \
  --output-dir runs/swift_data/qwen3_5_35b_a3b_exp_a_official_v1 \
  --export-mode official
```

```bash
python -m pipelines.export_swift_sft_dataset \
  --gold-dataset-path runs/gold/gold_release_v1/gold_dataset.jsonl \
  --output-dir runs/swift_data/qwen3_5_35b_a3b_exp_b_attr_v1 \
  --export-mode attr_enhanced
```

建议用途：

- 将正式 Gold 转成 Swift / Megatron-SWIFT grounding 训练输入。
- 保持训练格式转换与 Gold 发布逻辑解耦。
- 对比官方一致版和属性增强版的训练收益。

### 9. 启动 Qwen3.5-35B-A3B 训练

```bash
conda activate lsy-agent
bash scripts/train_qwen3_5_35b_a3b_exp_a_official.sh
```

```bash
conda activate lsy-agent
bash scripts/train_qwen3_5_35b_a3b_exp_b_attr.sh
```

建议用途：

- 当前优先跟踪实验 A 的正式训练，并统一查看 `runs/logs/` 中的日志。
- 实验 A 跑通后，再做实验 B 对照。
- 训练相关命令、依赖安装与版本检查统一在 `lsy-agent` 中执行。
- 正式训练默认使用 `--attention_backend unfused`。

## 后续代理必须遵守的事实

- 当前任务是单图多目标，不是单图单目标。
- 当前主链路不再包含病害字段。
- bbox 在模型侧统一按 `0-1000` 相对坐标理解。
- Silver 是每目标一行，Gold 是按图聚合。
- 当前更推荐使用 cleaned Silver 作为后续构建和复核输入。
- 评估与清洗都已有可直接调用的脚本，不需要重复手写临时分析逻辑。
- 正式 Gold 基线已经是 `runs/gold/gold_release_v1/`，不是待完成事项。
- 当前 `Qwen3.5-35B-A3B` 训练数据和训练脚本都已准备完成。
- 训练环境 `lsy-agent` 已验收通过，实验 A 正式训练已进入 step 级训练循环。
- Linux 迁移前后的标准运行说明见 `docs/deployment/deploy_linux.md`。