docs/roadmap.md

# Roadmap

## 2026-05-31 全量标注修订闭环

三组中型模型已经完成全量 `2620` 图推理。漏标挖掘已升级为标注修订挖掘：

1. 不再把所有 unmatched prediction 直接追加为漏标。
2. 新增 `add_missing_label`、`split_existing_annotation`、`boundary_expansion_review`、
   `ambiguous_overlap_review` 和 `possible_split_component` 分类。
3. 只有明确新增候选允许自动 append。
4. 同一旧 GT 下的多个小番茄候选聚合为 split case，交给 `VLMJudgeAgent` 判断是否 replace。
5. 第一版使用 OpenAI `gpt-5.5` 批量主审，并对 split、低置信和抽样 case 做人工复核。

详细流程与统计见 `docs/analysis/full_annotation_revision_workflow_20260531.md`。

## 2026-05-24 训练时间表更新

当前主线应从“把语义文本直接混入检测输出”调整为“利用 LLM / VLM 先验知识驱动低人工参与的数据闭环”。语义信息优先进入数据生产、审核、风险判定、伪标签筛选和蒸馏过程，检测输出本身保持尽量简单。

详细 8 周推进表见 `docs/analysis/training_timeline_20260524.md`。

当前最近最重要的推进顺序：

1. 基于人工复核结果生成修正版验证 GT，并重算 A/B/B-lite 指标。
2. 将漏标挖掘扩展到全量数据集，但先做自动分流，避免人工全量复核。
3. 新增 `VLMJudgeAgent` / `SemanticVerifier`：对中低置信漏标候选做二次视觉语义裁判。
4. 实现 `ConsistencyChecker` 最小闭环，特别是成熟度、遮挡和 bbox 合理性检查。
5. 落地半成熟颜色比例一致性检查。
6. 基于语义过滤后的增量数据训练 C closed-loop 版本。
7. 再推进边缘小模型蒸馏和跨作物最小迁移验证。

在完成前 4 项之前，不建议继续启动新的大规模属性增强训练。

## 2026-05-01 论文对齐更新

当前论文构想为 `AgriAgent: Semantic-Aware Multi-Agent Annotation Distillation for Edge-Oriented Tomato Maturity Detection`。路线图需要从“把链路跑通”升级为“补齐可写入论文的证据链”。

当前已经具备：

- Gold v1 数据资产：`2620` 张图像、`22793` 个目标。
- 实验 A 中型模型检测基线：`precision=0.9145`、`recall=0.8857`、`f1=0.8999`。
- 实验 B 属性增强路线首轮结果：`occlusion_accuracy_on_matched=0.7953`，但低召回受输出协议问题影响。
- 三联可视化结果：`runs/validation_compare/exp_a_vs_b_20260331_201545/`。

当前最重要的推进顺序：

1. 重跑修复协议后的实验 B 验证推理。
2. 整理实验 A / B 同口径表格和错误案例。
3. 为半成熟标签补颜色比例一致性检查。
4. 落地漏标挖掘与伪标签候选筛选。
5. 训练边缘小模型并采集资源指标。
6. 设计并执行消融实验。
7. 在核心结果稳定后再推进跨作物泛化实验。

## 2026-03-31 里程碑更新

- Stage 3 已从“实验 A 完整训练 + 验证闭环已跑通”推进到“实验 B 正式训练已完成”。
- 实验 A 检测基线仍成立：`precision=0.9145`、`recall=0.8857`、`f1=0.8999`。
- 实验 B 已完成首轮验证，当前结果为 `precision=0.9341`、`recall=0.3699`、`f1=0.53`、`occlusion_accuracy_on_matched=0.7953`。
- 当前新增的关键事实不是实验 B 已经失败，而是首轮验证存在明显的输出协议问题：
  1. 属性增强版 `val.jsonl` 含有 `attribute_text` 输出模板。
  2. 旧版 `run_validation_inference.py` 在推理请求构造时丢掉了该模板。
  3. 这会让实验 B 更容易输出长段分析文本，导致 `parse_failure_count=26`。
- `run_validation_inference.py` 已修复为把 `assistant` 模板转成显式 JSON 输出约束。
- 当前下一阶段重点应切换为：
  1. 在 GPU 空闲后重跑实验 B 验证推理。
  2. 重新做实验 A / B 的 detection 与属性对齐对照。
  3. 只有在验证口径稳定后，再继续收敛 `vllm` 性能参数和训练策略。

## Stage 0: Repository Foundation

目标：

- 建立基础 Agent 骨架。
- 明确数据分层原则。
- 明确多目标主链路与训练格式的职责边界。

当前状态：

- 已完成基础 Agent 骨架。
- 已落地新版多目标 `annotator -> reviewer -> silver` 主链路。
- 已落地 `gold_builder`、`manual_qc`、`evaluate_silver_dataset`、`clean_silver_dataset`。
- 已补 Linux 迁移所需的基础工程文件和最小测试。

## Stage 1: Stabilize Silver Data

目标：

- 把新版 Silver 稳定为长期可复用结构化资产。
- 继续收敛拥挤场景中的噪声框和重复框。
- 形成“原始 Silver + cleaned Silver + evaluation summary”的版本化工作流。

当前进展：

- 已完成全量新版 Silver 重跑：`2620` 图、`23222` 条记录。
- 已完成全量 Silver 结构评估。
- 已识别并处理极拥挤图中的超小框问题。
- reviewer 已加入默认超小框过滤：
  - `MIN_BBOX_1000_SIDE=20`
  - `MIN_BBOX_1000_AREA=400`
- 已产出 cleaned Silver：`22793` 条记录。
- 当前推荐下游默认使用 cleaned Silver。

剩余待办：

1. 继续压缩高 IoU 重复框。
2. 做更系统的 cleaned Silver 抽样人工复核。
3. 形成更明确的 Silver 版本命名与发布说明。

## Stage 2: Build Gold Data Layer

目标：

- 基于 cleaned Silver 产出正式 Gold。
- 保持 Gold 构建与 Silver 审核逻辑彻底解耦。
- 为后续训练模板适配留出独立层。

当前进展：

- `gold_builder` 已按 `image_path` 聚合同图多目标 Silver 记录。
- Gold 构建脚本已具备稳定 CLI。
- Gold 构建脚本已支持发布目录输出：`gold_dataset.jsonl`、`summary.json`、`report.md`、`sample_check.jsonl`。
- Gold 回归检查脚本已支持对比基线版与候选版。
- Gold 最小聚合测试已补齐。
- 已发布正式 Gold：`runs/gold/gold_release_v1`。

剩余待办：

1. 为未来不同训练模板继续预留独立转换步骤。
2. 把 Gold 回归检查纳入正式发布流程。
3. 继续固化 Gold 发布说明和版本说明模板。

## Stage 3: Implement VLMOperator

目标：

- 接通本地中型模型与边缘模型训练链路。

当前进展：

- 已基于 `gold_release_v1` 导出两套 `Qwen3.5-35B-A3B` grounding 训练数据：
  - 实验 A：官方一致版
  - 实验 B：属性增强版
- 已补齐两套 Megatron-SWIFT 训练脚本：
  - `scripts/train_qwen3_5_35b_a3b_exp_a_official.sh`
  - `scripts/train_qwen3_5_35b_a3b_exp_b_attr.sh`
- 已完成独立训练环境 `lsy-agent` 的核心依赖验收。
- 实验 A 已完成正式训练与验证闭环。
- 实验 B 已完成正式训练，训练产物已落盘。

剩余待办：

1. 在修复后的验证口径下重跑实验 B，并确认 detection 结果是否回升。
2. 继续规范训练产物目录、日志目录与元数据。
3. 将已验证训练命令和日志约定回填到 `VLMOperator`。
4. 实现 `train_model(model_tier, dataset_path)`。

## Stage 4: Implement SemanticEvaluator

目标：

- 让中型模型评估、漏标挖掘与伪标签回流真正进入闭环。

当前状态：

- 第一版结构化评估链路已落地：
  - 支持 reference / prediction 逐图对比
  - 支持逐图结果、风险样本和 summary 输出
  - 真实模型推理已接通
  - 当前正在修正属性增强版验证推理的输出协议问题

剩余待办：

1. 基于 `missing_label_candidates` 和人工复核结果，沉淀全量漏标候选自动分流规则。
2. 实现 `VLMJudgeAgent` / `SemanticVerifier`，用于减少人工复核：
   - 输入：原图、候选 bbox、已有 GT、模型支持数、成熟度/遮挡投票。
   - 输出：`accept_missing_label`、`reject_false_positive`、`uncertain`、`judge_reason`、`confidence`。
   - 只对 `support=1/2`、属性冲突、贴边、小目标、密集遮挡等中低置信候选调用。
   - `support>=3` 且一致性高的候选默认自动通过，只做抽样审计。
3. 继续补齐任务相关指标，特别是成熟度单类指标、半成熟召回和属性一致性。
4. 设计高置信伪标签回流机制。
5. 输出论文可用的错误案例清单和可视化索引。

## Stage 5: Implement Orchestrator

目标：

- 把当前分散脚本升级为可控的闭环状态机。

剩余待办：

1. 管理数据版本。
2. 管理训练轮次与模型版本。
3. 定义触发条件与停止条件。
4. 串联 Annotator、Reviewer、Cleaner、GoldBuilder、Evaluator、Operator。

## Stage 6: Edge Model Delivery

目标：

- 在数据层和中型模型迭代稳定后推进边缘模型部署。
- 支撑论文中的 edge-oriented distillation 结果。

剩余待办：

1. 明确边缘候选模型，优先在 `0.8B/2B` 或实际可用的小模型中选择一条主线。
2. 构建 edge 专用 Gold 或蒸馏数据。
3. 训练边缘小模型。
4. 评估边缘侧速度、显存、吞吐、参数量和准确性。
5. 与实验 A 的中型模型和传统检测基线做对照。
6. 记录部署约束与性能指标。

## Stage 8: Paper Experiments

目标：

- 将当前工程结果转化为论文可复现证据。

剩余待办：

1. 数据集章节：整理来源、分辨率、采集环境、类别分布、训练/验证/测试划分。
2. 主结果表：比较实验 A、实验 B、边缘小模型和传统检测基线。
3. 半成熟分析：报告半成熟单类指标、标注一致性和典型错误案例。
4. 消融实验：去语义标注、去审核 Agent、去漏标挖掘、去蒸馏。
5. 资源表：统计参数量、显存占用、推理延迟和吞吐。
6. 泛化实验：选择苹果或其他具有颜色演变规律的数据集做最小迁移验证。

## Stage 7: Engineering Hardening

目标：

- 让仓库从“可运行实验工程”升级为“可迁移、可维护、可迭代工程”。

当前进展：

- 已补 `requirements.txt`。
- 已补 `.env.example`。
- 已补 `docs/deployment/deploy_linux.md`。
- 关键数据脚本已补稳定 CLI。
- 已补最小测试。
- 已补训练数据导出脚本与训练脚本。
- 已完成训练环境依赖验收。

剩余待办：

1. 建立 `configs/` 体系。
2. 继续扩充测试与回归检查。
3. 标准化 `runs/`、`artifacts/`、版本说明。
4. 跟踪并沉淀一次正式训练端到端结果，补齐训练与评估闭环文档。
5. 继续完善 `docs/reference/repo_map.md`，降低新会话接手成本。