SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsimage-alt-title-filler

image-alt-title-filler

Writing & research

View repository

Updated 10-16 08:38

About this skill

Image Alt/Title Filler (Scripted Version)

Core Features

✅ Scripted Operations - Both search and replacement are done by the script, fast ✅ Model Only Views Images - The model is only responsible for reading images to generate descriptions, and does not perform text operations ✅ Batch Processing - Supports processing large numbers of images in batches ✅ Fallback Mechanism - Automatically uses context inference when image reading fails ✅ Complete Ledger - Records change details for each image ✅ Preview Mode - Must preview before execution to ensure data safety ✅ Automatic Backup - Automatically creates a timestamped backup file before execution

3-File Pattern (follows planning-with-files)

This skill uses the 3-file pattern of planning-with-files:

File Purpose Update Timing
task_plan.md Tracks progress of workflow phases A-D After each phase is completed
notes.md Records batch processing findings (optional) When processing batches
image_ledger.md Final deliverable: image change ledger After step D is completed

Workflow

  1. Before starting: Create task_plan.md, define 4 phases
  2. After each phase: Update task_plan.md, mark as completed
  3. When processing batches: Optionally record to notes.md
  4. After completion: image_ledger.md serves as the final deliverable

Hard Rules

  • ❌ Do not delete any image references
  • ❌ Do not modify src paths
  • ❌ Do not rename image files
  • ✅ Every image must appear in the change ledger
  • ✅ When the image can be read, it must be generated based on image content (not the filename)
  • ✅ When the image cannot be read, it must fall back to context inference and be marked FALLBACK_CONTEXT
  • ⚠️ Must first run --dry-run preview, and only execute formally after confirming there are no errors

Usage Workflow

Step 0: Create task plan (required!)

⚠️ Follow the planning-with-files principles

Create task_plan.md:

# Task Plan: 图片 Alt/Title 补全

## Goal
为 [文档名] 的所有图片生成语义化的 alt/title

## Phases
- [ ] Phase A: 提取图片清单
- [ ] Phase B: 生成批次任务
- [ ] Phase C: 处理批次（看图生成描述）
- [ ] Phase D: 应用补丁并验证

## Status
**Currently in Phase A** - 准备提取图片清单

Step A: Extract image list

python scripts/01_extract_manifest.py --target_md <你的文档.md> --out_dir .

Output: manifest.json - Contains the location and context information of all images

After completion: Update task_plan.md, mark Phase A as completed

Step B: Generate batch tasks

python scripts/02_make_batch_prompts.py --manifest manifest.json --out_dir batches --batch_size 8

Output: batches/batch_001.md, batch_002.md, ... - Processing tasks for each batch

After completion: Update task_plan.md, mark Phase B as completed

Step C: Process batches (execute in IDE)

Open batches/batch_001.md, follow the prompts:

  1. Open image files one by one - Use the Read tool to view local images
  2. Generate alt/title - Generate concise Chinese descriptions based on image content
  3. Save results - Save the results as results/batch_001.results.json
  4. Optional: Record findings to notes.md

Result Format Example:

{
  "batch": 1,
  "results": [
    {
      "index": 0,
      "src": "images/architecture.png",
      "new_alt": "系统架构图展示微服务间的调用关系",
      "new_title": "系统架构图展示微服务间的调用关系",
      "fallback": false,
      "note": ""
    },
    {
      "index": 1,
      "src": "images/missing.png",
      "new_alt": "Redis 缓存穿透解决方案流程图",
      "new_title": "Redis 缓存穿透解决方案流程图",
      "fallback": true,
      "note": "图片无法打开，基于上下文推断"
    }
  ]
}

Repeat processing for all batches until complete.

After completion: Update task_plan.md, mark Phase C as complete

Step D: Apply Patch

D1: Preview Changes (Required!)

⚠️ Safety Requirement: Must preview first, execute only after confirming correctness

python scripts/03_apply_patch.py \
  --target_md <你的文档.md> \
  --manifest manifest.json \
  --results_dir results \
  --out_md patched.md \
  --out_ledger image_ledger.md \
  --update_policy smart \
  --title_policy same_as_alt \
  --max_len_alt 40 \
  --max_len_title 40 \
  --dry-run

Preview Output:

  • Show the number of images to be updated
  • Show the first 3 change examples
  • Will not actually modify files

Checkpoints:

  1. Whether the image count is correct
  2. Whether the src paths match
  3. Whether the change examples are reasonable
  4. Whether there are unexpected overwrites

After completion: Record the preview results in task_plan.md

D2: Formally Apply Patch

⚠️ Execute only after the preview is confirmed correct

python scripts/03_apply_patch.py \
  --target_md <你的文档.md> \
  --manifest manifest.json \
  --results_dir results \
  --out_md patched.md \
  --out_ledger image_ledger.md \
  --update_policy smart \
  --title_policy same_as_alt \
  --max_len_alt 40 \
  --max_len_title 40

Output:

  • patched.md - Updated document
  • image_ledger.md - Complete change ledger (final deliverable)
  • Automatically create backup files (with timestamp)

After completion: Update task_plan.md, mark Phase D as complete

Step E: Verify Results

# 1. 检查账本文件
cat image_ledger.md

# 2. 对比原文件和新文件
diff <你的文档.md> patched.md

# 3. 确认无误后替换原文件
cp patched.md <你的文档.md>

Parameter Description

update_policy (Update Policy)

  • always - Always update alt/title
  • smart - Smart update (keep if the original content does not look like a filename)
  • empty_only - Only update empty alt/title

title_policy (Title Policy)

  • same_as_alt - title is the same as alt (recommended)
  • keep - Keep the original title unchanged
  • update - Update title independently

max_len_alt / max_len_title

  • Limit the maximum length of alt/title (default 40 characters)

ledger_format (Ledger Format)

  • table - Table summary format (default, recommended)
    • One image per row, easy to browse quickly
    • Includes statistics (total, updated, retained, downgraded)
    • Similar to the old version format
  • detailed - Detailed item-by-item format
    • Includes original snippet and new snippet code blocks
    • Suitable for scenarios where specific changes need to be viewed

Backup Options

  • --no-backup - Do not create backup files (fully trust the process)
  • --auto-cleanup-backup - Automatically delete backup files after successful execution (recommended)
    • A backup will still be created (to prevent write errors)
    • Automatically clean up after verifying the output file is successful
    • Avoid accumulating backup files

Directory Structure

Skill directory (contains only scripts)

.codex/skills/image-alt-title-filler/
├── SKILL.md                          # 本文件
├── scripts/
│   ├── 01_extract_manifest.py        # 提取图片清单
│   ├── 02_make_batch_prompts.py      # 生成批次任务
│   └── 03_apply_patch.py             # 应用补丁
├── SAFETY_REVIEW.md                  # 安全审查报告
└── CHANGELOG.md                      # 版本更新记录

Working directory (created at execution time)

working_directory/
├── task_plan.md              # 任务计划（遵循 planning-with-files）
├── notes.md                  # 批次处理笔记（可选）
├── manifest.json             # 提取的图片元数据
├── batches/                  # 批次任务
│   ├── batch_001.md
│   └── batch_002.md
├── results/                  # AI 生成的描述
│   ├── batch_001.results.json
│   └── batch_002.results.json
├── patched.md                # 更新后的文档
└── image_ledger.md           # 最终交付物：变更账本

Quick Start Example

# 0. 创建任务计划
cat > task_plan.md <<'EOF'
# Task Plan: 图片 Alt/Title 补全

## Goal
为 node/中间件/redis/redis实战.md 的所有图片生成语义化的 alt/title

## Phases
- [ ] Phase A: 提取图片清单
- [ ] Phase B: 生成批次任务
- [ ] Phase C: 处理批次
- [ ] Phase D: 应用补丁并验证

## Status
**Currently in Phase A**
EOF

# A. 提取图片
python scripts/01_extract_manifest.py --target_md "node/中间件/redis/redis实战.md" --out_dir .

# 更新 task_plan.md: 标记 Phase A 完成

# B. 生成批次（每批 8 张图）
python scripts/02_make_batch_prompts.py --manifest manifest.json --out_dir batches --batch_size 8

# 更新 task_plan.md: 标记 Phase B 完成

# C. 在 IDE 中打开 batches/batch_001.md，按提示处理
# 更新 task_plan.md: 标记 Phase C 完成

# D1. 预览变更（必须！）
python scripts/03_apply_patch.py \
  --target_md "node/中间件/redis/redis实战.md" \
  --manifest manifest.json \
  --results_dir results \
  --out_md patched.md \
  --out_ledger image_ledger.md \
  --dry-run

# D2. 确认预览无误后，正式执行（使用表格格式 + 自动清理备份）
python scripts/03_apply_patch.py \
  --target_md "node/中间件/redis/redis实战.md" \
  --manifest manifest.json \
  --results_dir results \
  --out_md patched.md \
  --out_ledger image_ledger.md \
  --ledger_format table \
  --auto-cleanup-backup

# 更新 task_plan.md: 标记 Phase D 完成

# E. 检查账本并替换原文件
cat image_ledger.md
cp patched.md "node/中间件/redis/redis实战.md"

Notes

  1. ⚠️ Safety First - Must first execute --dry-run preview, then formally execute after confirming correctness
  2. Automatic Backup - A backup file is automatically created during formal execution (format:原文件名.backup_时间戳.md）
  3. Image Paths - The script automatically handles relative paths and absolute paths
  4. Batch Size - 5-10 images per batch is recommended, to avoid processing too many at once
  5. Downgrade Handling - When an image cannot be opened, infer based on context and mark fallback: true
  6. Ledger Check - Be sure to check after completion image_ledger.md Confirm all images have been processed

FAQ

Q: Why process in batches? A: To avoid timeouts or memory issues caused by processing too many images at once; batch processing is more stable.

Q: What should I do if an image cannot be opened? A: Set fallback: true, infer and generate descriptions based on context, and the script will automatically mark them.

Q: How can I update only empty alt/title? A: Use the --update_policy empty_only parameter.

Q: Can I customize the length of alt and title? A: Yes, use --max_len_alt and --max_len_title parameters.