autowzry-agent

2025-11-14 架构统一化

时间: 2025-11-14 晚上 主题: 架构整改、模块通用性验证和数据模块清理

架构整改：统一收集器

问题发现

正确原则

整改内容

  1. 扩展兼容层 (environment/compatibility.py)
    • 新增参数：video_path, skip_frames
    • 离线模式自动创建VideoReader
    • 新增方法：get_frame_metadata() - 统一获取帧元数据
    • 更新capture_screen() - 统一返回格式并更新计数器
  2. 创建统一收集器 (data/unified_frame_collector.py)
    • 通用设计：只调用compat.capture_screen()
    • 支持两种模式：--mode offline / --mode online
    • 相同的逐帧标注格式
    • 相同的HDF5输出结构
  3. 废弃旧收集器
    • 标记data/raw_frame_collector.py为 [DEPRECATED]
    • 标记data/online_frame_collector.py为 [DEPRECATED]
    • 添加迁移指南到文件头部
  4. 更新文档
    • 更新quickstart.md - 使用unified_frame_collector
    • 创建docs/ARCHITECTURE_REFACTOR_PLAN.md - 详细整改计划
    • 添加架构说明

架构对比

错误做法（已废弃）：
├── raw_frame_collector.py（视频专用）
├── online_frame_collector.py（在线专用）
└── 代码重复，违反通用性原则

正确做法：
CompatibilityLayer（统一数据源）
    ├─ offline模式 → VideoReader
    └─ online模式 → autowzry.lite_当前画面()
           ↓
UnifiedFrameCollector（通用）
    └─ 只调用 compat.capture_screen()

使用方式

# 离线模式（视频）
python data/unified_frame_collector.py --mode offline --video moive/1.mp4 --skip-frames 14

# 在线模式（设备）
python data/unified_frame_collector.py --mode online --config config.yaml --interval 0.5

模块通用性检查完成

检查结果

  1. ✅ 完全合规的模块（7个）:
    • data/per_frame_annotator.py - 只操作HDF5，完全通用
    • data/flexible_frame_loader.py - 只加载HDF5，完全通用
    • data/unified_frame_collector.py + per_frame_annotator.py - 正确使用兼容层
    • data/unified_frame_collector.py - 新统一收集器，完全通用
    • scripts/test_local_pipeline.py - 配置驱动，完全通用
    • environment/compatibility.py - 兼容层本身
    • environment/action_space.py - 纯数据定义
  2. ⚠️ 部分合规的模块（2个）:
    • scripts/collect_spectate.py:
      • 核心逻辑通用（正确使用compat.capture_screen()）
      • 但硬编码mode='online'（应用层脚本，可接受）
      • 建议：添加--mode参数支持
    • data/replay_buffer.py:
      • 通用但只支持传统格式（observations, actions, rewards, dones）
      • 不支持逐帧格式（frame_000000/image等）
      • 需要：创建FlexibleReplayBuffer或添加格式适配
  3. ❌ 已废弃的模块（2个）:
    • data/raw_frame_collector.py - [DEPRECATED]
    • data/online_frame_collector.py - [DEPRECATED]

关键发现

FlexibleReplayBuffer 创建完成

核心功能

  1. 自动格式检测: 自动识别传统格式和逐帧格式
  2. 双格式支持:
    • 传统格式: observations/actions/rewards/dones 数组
    • 逐帧格式: frame_000000/image/action/reward/done 组
  3. 灵活字段处理: 支持部分标注的数据
  4. 统计分析: 显示字段完整性（Action: 100%，Reward: 100%等）
  5. 兼容原接口: 与 ReplayBuffer 接口完全兼容

关键特性

测试结果

[Test 1] 传统格式加载:
  Loaded: 108 transitions
  State shape: (4, 540, 960)
  ✅ 采样成功: (32, 4, 540, 960)

[Test 2] 逐帧格式加载:
  Loaded: 19 transitions (from 20 frames, 100% annotated)
  State shape: (540, 960, 3)
  ✅ 采样成功: (8, 540, 960, 3)

Data 模块清理完成

删除的文件

  1. ❌ data/raw_frame_collector.py - 视频专用收集器（违反架构原则）
  2. ❌ data/online_frame_collector.py - 在线专用收集器（违反架构原则）

替代方案

Data 模块最终结构

data/
├── __init__.py
├── unified_frame_collector.py + per_frame_annotator.py          # 传统格式收集
├── replay_buffer.py                 # 传统格式回放缓冲区
├── unified_frame_collector.py       # 统一收集器（新架构）
├── per_frame_annotator.py           # 逐帧标注器（新架构）
├── flexible_frame_loader.py         # 逐帧加载器（新架构）
└── flexible_replay_buffer.py        # 灵活回放缓冲区（新架构）

文档更新和Bug修复

文档更新

Bug 修复