自动曝光校正
触发：执行AEV
用户输入 执行AEV 就按本流程执行，不用再问他"要不要修""用哪种方式"：
执行AEV+ 一张图（或多个附件）→ 逐张处理。执行AEV+ 目录路径 → 批量处理。执行AEV（不带图）→ 取本轮/最近一次会话里的图片；确实没有就问一句要图。- 用户没说口令、但明确说"这图太亮/太暗/泛白/帮我修修曝光"→ 同样走本流程。
装好后先自检：python3 scripts/selftest.py，确认依赖与本机读写都正常再开工。
覆盖范围：所有图片
| 维度 | 支持情况 | 处理方式 |
|---|---|---|
| 格式 | JPG / JPEG / PNG / WEBP / BMP / TIFF | 直接读；HEIC 等先转 JPG |
| 比例 | 横图、竖图、方图、长截图、超宽全景 | 长边等比压到 2048 再送模型，不裁切 |
| 尺寸 | 小图（<1000px）到大图（>8000px） | 小图先放大防涂抹，大图先缩 |
| 数量 | 单张、多张、整个目录 | 单张走默认流程；批量报张数与额度 |
| 题材 | 照片、人像、静物、建筑、夜景、截图、证件、票据、商品图 | 一律接；内容敏感类自动改本地，不拒绝 |
| 曝光问题 | 过曝、欠曝、逆光、泛白眩光、发灰、基本正常 | 判 ok 时不硬修，除非 --force |
不会因为"这张图不适合"而拒绝执行：能走生成式就走生成式；不能走就自动改本地； 生成结果验收不通过还会再回落一次本地版。任何输入都要给出一张能看的图和一份报告。
核心思路
曝光问题分两类，能不能救取决于数据还在不在：
- 欠曝：暗部数据还在，本地曲线就能真实恢复。
- 过曝 / 泛白：三通道到 255 的区域数据已丢失，眩光还会把整幅画面的黑场抬起来（p01 从 3% 抬到 30%）。本地只能压成均匀浅灰，只有生成式重绘才能补回层次。
所以主路径是：直方图诊断 → 生成式重打光 → 自动验收，本地确定性校正留作兜底与对照。
0. 自动选路（先判断，再动手）
| 场景 | 路径 | 原因 |
|---|---|---|
| 一般图片修曝光（默认） | 内置生图工具 | 走豆包账号额度，不用配 Key，效果最好 |
| 一批图（≥10 张）、要无人值守、要固定参数复跑 | 方舟脚本（pipeline.py） | 能脚本化批处理，消耗方舟免费张数 |
| 证件、票据、扫描件、UI 截图、小字海报、白底商品图 | 本地（--mode local） | 生成式会写错字、改结构；这是"自动降级"而非"拒绝" |
| 涉密、隐私、不允许出网 | 本地 | 图片不出本机 |
| 夜景/弱光 | 任一 | 已有夜景保护，不会提亮成白天 |
1. 内置生图工具路径（默认，三步）
Step 1｜诊断并生成提示词
python3 scripts/prepare.py -i photo.jpg -o ./exposure_fixed
stdout 是 JSON，取四个字段：
status "ready" → 继续；"ok_no_change" → 曝光正常，直接告诉用户不用修
model_input 送模型的图片（极端曝光时已做过轻度归一化）
prompt_file 校正提示词（已按判定与目标亮度生成，不要自己另写）
size_hint target_width / target_height / note
Step 2｜调用内置生图工具
- 用环境里可用的参考图生图工具（豆包内通常是
image_edit，也有的环境是image_gen带参考图）： 参考图 =model_input，提示词 =prompt_file的内容，width/height取size_hint（长边 ≤2048，保持原比例）。 - 坑：图像工具通常只收公网 URL，本地文件必须先上传换成 URL（豆包内用
FileBatchUpload），不能直接传绝对路径。 - 以照片为主、需要保住原构图时用参考图模式；
prompt.txt已写明"绝不重绘内容"，别再追加风格词。 - 模型取默认即可（豆包内置
seedream_5.0_flash）；要更好效果可换seedream_5.0_pro，代价是更慢、更贵。
Step 3｜验收出图
python3 scripts/finish.py --before photo.jpg --after generated.png -o ./exposure_fixed \
--source doubao --model seedream_5.0_flash --quota "豆包每日免费次数"
产出 *_fixed.png、*_compare.jpg、report.md，stdout 的 verify.status 为
pass / partial / fail。
fail时finish.py会自动用本地确定性校正补一版（*_local.png+*_compare_local.jpg）， 并把status标成done_local_after_reject，此时直接交付本地版、并在说明里点明"生成式改动了内容"。- 加
--no-local-fallback可关掉这个自动补版。
2. 方舟脚本路径（批量 / 可复算）
python3 scripts/ark_client.py --check # 先看 Key 与模型是否就绪
python3 scripts/pipeline.py -i ./photos -o ./exposure_fixed # auto：优先方舟，失败退本地
python3 scripts/pipeline.py -i ./photos -o ./out --mode ark # 强制方舟，失败直接报错
- 免费额度按张：
doubao-seedream-5-0-lite50 张、4.5/4.0各 200 张、flash无免费额度 0.12 元/张。 默认模型链已按"先烧免费额度"排序；批量前先报「这批 N 张，吃掉 N 张免费额度」。 - 无 Key 时
--mode ark会直接以退出码 1 失败，不会假装成功。 - 计费、模型 ID、报错速查见
references/ark-setup.md。
3. 本地路径（保内容）
python3 scripts/pipeline.py -i doc.jpg -o ./out --mode local
python3 scripts/correct_local.py in.jpg -o out.png --target 0.46
泛白（眩光抬起黑场）判定下会在线性空间剥离加性偏移，色相不会偏；这是本地路径对泛白片的关键处理。
4. 诊断（不花钱，先给结论）
python3 scripts/analyze.py <图片或目录> --pretty
输出判定（overexposed / underexposed / backlit / low_contrast / slightly_over / ok）、
平均亮度、死白死黑占比、p01（最暗处被抬到多少），以及建议目标亮度与 EV。
判定规则与阈值见 references/diagnosis-rules.md（要解释"为什么这么判"或用户质疑时再读）。
判为 ok 时不要硬修，除非用户要求 --force。
目标亮度不是死数：calibrate_plan() 会按这张图实际能到多亮（护住高光的前提下）自动下调，
报告里 plan.target_limited=true 就是这个信号。高光护不住时不要硬拉，如实说明物理上限。
5. 验收口径（exposure_lib.verify()）
- pass：亮度进目标 ±10%、没新增死白、结构相似度 ≥0.62、宽高比变化 ≤3%、清晰度没掉（仅生成式查）。
- partial：亮度或死白没完全达标，通常是物理上限（残存死白、太阳本身），如实说明。
- fail：结构漂移、被裁切、过度平滑。改用本地结果。
结构相似度是亮度无关的高通余弦，所以"整体压暗 30%"不会被误判成改内容； 真出现换脸、改字、删物体时它会明显掉下来。
6. 交付
- 图片用本环境的图片展示方式交付（豆包内是
<RichMediaCard>）：至少给*_fixed.png与*_compare.jpg（对比图最直观）。 - 报告：单张给要点（判定、前后亮度、验收状态、限制）；批量给
report.md。 - 必须说清走的哪条路：内置工具 / 方舟 / 本地。本地结果就不要说成"生成式重建"。
- 不要隐瞒限制：校正后仍有死白时明确指出"该区域原始数据已丢失，只能近似重建"。
7. 输出话术模板
判定：过曝（泛白型），平均亮度 80%，最暗处被眩光抬到 30%，没有黑场。 处理：豆包内置生图模型（
seedream_5.0_flash）生成式重打光，输出 2048×1536。 结果：平均亮度 80% → 50%，最暗处 30% → 4%，结构相似度 0.77（构图未变），验收通过。
8. 常见故障
| 现象 | 处置 |
|---|---|
| 结构相似度低 / 出现换脸、改文字 | finish.py 已自动给本地版；要纯本地就直接 --mode local |
| 生成图被裁切 / 比例变了 | width/height 没按 size_hint 传，重出一次 |
| HEIC / RAW / GIF 读不出来 | 先转成 JPG（magick 或 sips），再跑本流程 |
| 超大图（>8000px）很慢或报错 | 先缩到长边 4096 再跑，验收仍按原图比对 |
| 长截图（超长竖图）细节糊 | 生成式对超长图不友好，改 --mode local |
| 提亮后噪点多 | 欠曝 +3EV 以上的正常代价，降 --target 或提示配合降噪 |
| 方舟报 401 | Key 无效，--save-key 重写 |
| 方舟报 404 模型名 | 脚本自动换候选；仍失败看 references/ark-setup.md 的完整模型 ID |
| 批处理慢 | 本地 2–4 秒/张；生成式 10–60 秒/张，先给用户预估 |
9. 边界
- 只调曝光/明暗/反差，不做白平衡、磨皮、美颜、去路人、抠图、超分；用户要这些时说明不在范围内。
- 不做视频逐帧校正。
- 生成式是"重绘而非解码"，纹理可能被微调；法证级一致、带文字的场景一律走本地。
参考文件
references/ark-setup.md：方舟开通、API Key、免费张数与计费、模型 ID、报错速查references/diagnosis-rules.md：指标定义、判定阈值、目标亮度、物理限制references/prompt-recipes.md：生成式提示词结构、重试升级、不适用场景