Image Rating

Image Rating (P3)

Overview

本 skill 把 JushenRenji.src.llm_tools.llm_agent:rate_image_importance 的"图片重要性打分"步骤抽出来, 用 opencode 多轮决策 替代原有的 LLM 单次打分。

LESSONS 2026-04-15 Bug1 记过——某次公式图被 LLM 给到 0.92 高分,导致视频里出现长时间公式截图。 本 skill 在 prompt 里写明"公式/约束 ≤ 3 分,section=none",在 CLI 代码层 (_enforce_formula_constraint) 再 enforce 一遍作为双重保险。

Cross-conda invocation pattern

必须先激活 paperagent 环境:

source ~/miniconda3/etc/profile.d/conda.sh
conda activate paperagent
cd ~/Projects/VlogCutter/JushenRenji
python -m src.llm_tools.cli rate-images \
    --candidates cache/test_image_candidates.json \
    --target-count 5 \
    --out /tmp/scores.json

Tool: rate-images

多轮决策为候选图片打分 + 推荐 section,输出 score JSON。

Input candidates JSON schema

候选图片文件,JSON 数组,每项:

示例:

[
  {
    "image_index": 0,
    "caption": "Figure 1: Overall architecture of ViTacFormer",
    "figure_role": "method",
    "paper_context": "ViTacFormer: cross-modal transformer..."
  },
  {
    "image_index": 1,
    "caption": "Equation 3: Cross-attention loss function L_attn = ...",
    "figure_role": "method",
    "paper_context": "ViTacFormer..."
  }
]

CLI flags

输出 JSON schema

每张候选图对应一条记录,长度与输入相同:

[
  {
    "image_index": 0,
    "caption": "Figure 1: Overall architecture of ViTacFormer",
    "score": 8.5,
    "reason": "高层架构图,核心方法可视化",
    "recommended_section": "method",
    "rejected": false
  },
  {
    "image_index": 1,
    "caption": "Equation 3: Cross-attention loss...",
    "score": 3.0,
    "reason": "公式/约束截图,不适合长时间画面展示",
    "recommended_section": "none",
    "rejected": true
  }
]

CLI stdout (JSON contract)

成功:

{"ok": true, "scored": 5, "above_5": 3}

失败 (退码 1):

{"ok": false, "error": "candidates file not found: /tmp/x.json"}

评分维度

1. 视觉化效果: 架构图 / 流程图 / 对比图 > 公式图 / 纯文字截图
2. 信息密度: 总览图 > 局部细节图;单图能讲一个故事 > 多个零碎子图
3. 与脚本对应: 跟视频段落主题强相关的图分高(method 段配架构图 8 分;放配公式 3 分)
4. 重复检测: 同主题多图保留信息密度最高的,其余降权(避免视频里反复看同一架构)

硬约束

Bash 调用示例

cat > /tmp/cands.json <<'EOF'
[
  {"image_index": 0, "caption": "Figure 1: Overall architecture", "figure_role": "method", "paper_context": "ViTacFormer"},
  {"image_index": 1, "caption": "Equation 3: Loss function", "figure_role": "method", "paper_context": "ViTacFormer"},
  {"image_index": 2, "caption": "Figure 4: Quantitative comparison", "figure_role": "results", "paper_context": "ViTacFormer"}
]
EOF

JSR_NETWORK_PROFILE=gsjts python -m src.llm_tools.cli rate-images \
    --candidates /tmp/cands.json \
    --target-count 3 \
    --out /tmp/scores.json

期望输出:

{"ok": true, "scored": 3, "above_5": 2}

/tmp/scores.json 里 idx=0 (architecture) ≈ 8 分 method, idx=1 (equation) ≤ 3 分 none, idx=2 (quantitative) ≈ 7 分 results。

程序化调用 (Python)

src.llm_tools.llm_agent.rate_image_importance() 已新增 via_skill kwarg:

from src.llm_tools.llm_agent import rate_image_importance

# 默认走原 LLM 单次(行为不变)
scores = rate_image_importance(captions)

# 显式走 skill
scores = rate_image_importance(captions, via_skill=True)

或环境变量级开关:

JSR_USE_SKILL_RATE_IMAGES=1 python src/main.py --paper-link https://arxiv.org/abs/2506.15953

skill 失败 (subprocess 超时 / opencode 上游 404 / JSON 解析全错) 自动 fallback 到原 LLM 单次, 不会让主流程挂掉。返回值始终是 list[int] (legacy API 兼容)。

多轮决策流程 (CLI 内部)

_rate_images_via_opencode 通过 prompt 让 opencode 内部依次完成 3 轮:

1. Round 1 — 初步分: 基于 caption / figure_role / paper_context 给每张图打 0-10 分。
2. Round 2 — 自检: 视觉化效果差吗?跟其他高分图重复吗?caption 是否对应论文核心贡献?
3. Round 3 — 最终分 + section: 输出 score / recommended_section / reason / rejected。

每一轮失败都会优雅降级:

• opencode 全挂 → plain LLM 单次兜底
• plain LLM 也挂 → _fallback_default_scores 给每张图固定 5 分 + 按 figure_role 简单分流
• 全程公式图硬约束都 enforce(双重保险)

Error handling

CLI 在所有失败路径都输出合法 JSON 到 stdout:

{"ok": false, "error": "candidates must be JSON list"}

logging 全走 stderr,不污染 stdout。

Limitations

• opencode 当前主力模型不支持图片直输; 本 skill 是基于 caption + figure_role + paper_context 的文本推理。caption 越详细 → 评分越准。
• target_count 是软目标(不强求),实际保留张数取决于打分分布。
• subprocess 一次最多 240s timeout(opencode 路径); 超时自动走 plain LLM fallback。