Skip to content

REVIEW_TASK.md

Latest commit

 

History

History
129 lines (94 loc) · 5.28 KB

REVIEW_TASK.md

File metadata and controls

129 lines (94 loc) · 5.28 KB
Raw

AI Video Dubber — Multi-Round Review Task

项目信息

  • 路径：/Users/eric_jiang/.openclaw/workspace/ai-video-dubber
  • 虚拟环境：.venv/bin/python3
  • 语言：Python 3.11+
  • 架构：chunked pipeline + Gemini multimodal optimization + ElevenLabs TTS

执行要求

每轮修改完后运行 .venv/bin/python3 -m pytest tests/ -x -q（如果没有 tests/ 则自己写基础测试）。 每轮最后 git commit 一次，消息格式 "review(round-N): 改了什么"。

Round 1：冗余代码 & 死代码清理

目标文件：

  • dubber/adapters/server_bridge.py — 检查是否还被引用，删除死代码
  • dubber/adapters/claude_code.py — 检查是否被使用
  • 所有 *.py — 找未使用 import（用 autoflake 或手动检查）
  • 找重复定义：同一逻辑在 pipeline.py、orchestrator.py、init.py 里是否有重复

具体要做：

  1. grep -rn "from dubber.adapters.server_bridge" . --include="*.py" 找引用
  2. grep -rn "from dubber.adapters.claude_code" . --include="*.py" 找引用
  3. 找重复定义的 run_transcription、run_translation、run_tts、run_render
  4. dubber/services/init.py 里有没有重复导出
  5. 删除确定没用的代码，合并重复实现

Round 2：互相矛盾 & 逻辑错误

必须修复：

  1. max_ratio 统一：

    • dubber/services/audio.py apply_atempo(max_ratio=1.5) 默认值改为 1.3
    • dubber/agent/orchestrator.py PipelineConfig 加 speed_max: float = 1.3 和 speed_min: float = 0.75
    • 所有调用 apply_atempo 的地方都传 max_ratio 明确值

  2. _fill_missing_translations 在 src != tgt 时 fallback 用源文（中文字符）→ TTS 合成中文音频进英文轨

    • 修复：fallback 时应调用单条翻译，或跳过该 segment 的 TTS

  3. segment_timing op 在 optimization_loop 里的 param normalization：

    • 已有 start_time→start, end_time→end 映射，检查 orchestrator 里其他调用处是否也有同样问题

  4. sync_state 调用：梳理哪些地方需要 sync，哪些是多余的，去掉重复 sync

Round 3：Gemini Prompt 优化

gemini_analyzer.py 里的所有 prompt 需要：

  1. analyze_transcription prompt：

    • 明确要求返回 start_time/end_time 为 float 秒数（不是字符串）
    • 明确 speaker_id 格式：spk_0, spk_1, spk_2...
    • 删除冗余描述

  2. analyze_translation prompt：

    • suggested_params 里的字段名必须和 ops 一致：
      • segment_timing: 用 start 和 end（float），不用 start_time
      • emotion_change: 用 emotion（string）
      • translation_fix: 用 text（string）
      • speed_adjust: 用 factor（float）
    • segment_index 改成 index（和 ops 保持一致）

  3. _build_prompt（optimization 迭代）：

    • 同上，suggested_params 字段名和 ops 完全一致
    • 增加 JSON schema 约束（列出每个 op 的参数类型）
    • 限制一次最多返回 10 个 issues（防止批量覆盖）

  4. analyze_speakers prompt：

    • segment_assignments 里必须有 segment_index（int）和 speaker_id（string）
    • 每个 speaker 必须有 gender: "male"/"female"/"unknown"

Round 4：错误处理 & 健壮性

  1. _run_chunked：chunk 处理失败时继续处理其他 chunk（wrap try/except，记录失败 chunk）
  2. _merge_chunk_segments：TTS 文件 copy 失败不中断，记录警告
  3. optimization_loop.py：
    • Gemini 返回非法 JSON → 跳过本轮迭代，不 crash
    • score 解析 KeyError → 用默认值 50
  4. subprocess.run 调用全部加 timeout=120 和 stderr 捕获
  5. gemini_analyzer.py 里 _call 方法：网络超时重试 2 次（间隔 5s）

Round 5：代码结构优化

  1. 把 orchestrator.py 里的 _optimize_transcription、_optimize_translation、_optimize_speakers 方法拆到 dubber/agent/step_optimizer.py
  2. 速度常量集中：在 dubber/constants.py 定义： 
    SPEED_MIN = 0.75
SPEED_MAX = 1.3
DEFAULT_GEMINI_MODEL = "google/gemini-2.5-flash"
  3. PipelineConfig 引用 constants，不再硬编码
  4. gemini_analyzer.py 价格计算加注释（来源：OpenRouter 定价页）

Round 6（Agent Skill 视角）优化

完成 Round 1-5 后，从"好用的 OpenClaw Skill"角度思考：

  1. openclaw_skill.py 的 DubberSkill.execute() 是否支持流式进度回调？Agent 调用时能看到 pipeline 进度
  2. skill.yaml 的 tools 定义是否足够清晰，参数描述是否让 LLM 能正确调用
  3. 是否需要增加 get_status 工具（查询某个 project 的当前处理状态）
  4. 是否需要增加 cancel_job 工具
  5. Error 返回格式是否统一（建议统一为 {"success": false, "error": "...", "error_code": "TRANSCRIPTION_FAILED"}）

Round 7：最终测试

写或完善 tests/ 目录下的测试：

  1. test_segment_timing.py：测试 timing op 参数名 normalization
  2. test_rephrase_loop.py：测试两轮 rephrase 逻辑
  3. test_translation_retry.py：mock 网络失败，测试 3 次 retry
  4. test_pipeline_e2e.py：用 mock 数据跑完整 pipeline（不真实调用 API）

所有测试通过后，git commit -m "review: all rounds complete"。

完成后通知

运行：openclaw system event --text "ai-video-dubber review complete: all 7 rounds done" --mode now