上传照片一键处理（压缩到指定KB·改尺寸·换底色）
「文件大小不能超过 20KB」「照片尺寸须为 295×413」——报名、考试、政务、招聘系统里的这些硬性要求，把无数人卡在最后一步。本 Skill 用一条命令，把用户手上那张照片压到指定大小、改成精确尺寸、换成白/红/蓝底，直接输出可以上传的文件，并当场校验是否达标。
为什么免费：全部逻辑（压缩、缩放、换底色、转格式、校验）都跑在本地脚本里，基于 Pillow，规则库与预设也打包在 Skill 内。不联网、不调后端、不要 API Key、不上传用户照片——处理身份证照、证件照这类私密图片零风险。
它做什么：压缩到指定 KB 以内（自动在画质与尺寸间找最优解）/ 缩放到精确像素尺寸（等比留边或裁剪填满）/ 白底红底蓝底互换（纯色背景照）/ JPG·PNG·WebP 互转 / 自动去除 EXIF（含拍摄定位）/ 内置常见规格预设 / 成品校验。
何时使用
用户说以下任何一句时：
- "照片太大了，传不上去" / "图片太大怎么压小" / "压缩到 20KB 以内"
- "照片尺寸不对" / "帮我改成 295×413" / "要按 1:1 裁一下"
- "换白底 / 红底 / 蓝底" / "证件照底色不对"
- "把这个 PNG 转成 JPG" / "上传材料太大" / "报名照片怎么弄"
- "这些照片批量处理一下"
使用流程
第 1 步：问清上传要求
先向用户确认（不知道就按报名系统的提示照抄）：最大体积（KB/MB）、像素尺寸（宽×高）、底色（白/红/蓝）、格式（JPG/PNG）。常见要求可直接套内置预设：
python scripts/photo_toolkit.py presets
预设只是常见参考值，最终以报名/办理系统的官方要求为准；用户能提供准确要求时，用命令行参数覆盖预设。
第 2 步：看一眼原图
python scripts/photo_toolkit.py probe photo.jpg
输出尺寸、格式、体积、DPI、长宽比，并提示是否小于目标尺寸（原图不够大时需要提醒用户换图，放大只会更模糊）。
第 3 步：一键处理
python scripts/photo_toolkit.py fit --input photo.jpg --max-kb 20 --width 295 --height 413 --bg white --format jpg --out photo_ok.jpg
常用参数：
| 参数 | 作用 | 默认 |
|---|---|---|
--input |
源图片（可传多个，配合 --out-dir 批量） |
必填 |
--out / --out-dir |
输出文件 / 批量输出目录 | 源目录 <原名>_ok.<扩展名> |
--max-kb / --min-kb |
目标体积上下限（KB） | 不限 |
--width / --height |
目标像素尺寸（同时给出即按精确尺寸处理） | 保持原尺寸 |
--fit |
cover 裁剪填满 / contain 等比留边 / stretch 拉伸 |
cover |
--anchor |
center / top（人像照常用 top 保头部） |
center |
--bg |
white / red / blue / #RRGGBB / none |
不换底 |
--bg-tol |
换底色容差（越大替换越多，背景不纯时调大） | 60 |
--bg-mode |
corner 只替换四角连通的背景 / global 全图近色替换 |
corner |
--format |
jpg / png / webp |
跟随原图（不支持则 jpg） |
--dpi |
写入 DPI（部分系统要求 300） | 不写入 |
--preset |
套用内置预设，如 id-photo-1inch |
无 |
--json |
输出结构化结果 | 关闭 |
一个例子：考试报名一寸照（≤20KB、295×413、白底、JPG）：
python scripts/photo_toolkit.py fit --input photo.jpg --preset exam-1inch-20k --out photo_ok.jpg
退出码含义：
| 退出码 | 含义 | 你要做什么 |
|---|---|---|
0 |
✅ 处理成功且满足全部约束 | 把输出文件路径告诉用户，可直接上传 |
3 |
🟡 处理成功但有提醒 | 告诉用户提醒点（如画质已到低档、换底色可能不完美） |
2 |
🚫 约束无法同时满足 | 如实告知冲突点（如"固定 295×413 时压不到 20KB"），给出取舍建议 |
1 |
输入或运行错误 | 检查文件路径、格式、依赖（Pillow） |
体积压不下来或尺寸不够时的取舍建议，见 references/methodology.md。
第 4 步：校验成品（免费增值，别省略）
处理完务必跑一次校验，确认输出的文件真的达标：
python scripts/photo_toolkit.py verify --input photo_ok.jpg --max-kb 20 --width 295 --height 413 --format jpg
全部通过退出码为 0，任一项不通过为 2，并逐项列出实际值。批量时对每个输出文件都跑一次。
第 5 步：帮用户兜底
- 原图太小：目标尺寸大于原图时，脚本会提醒；直接告知用户"需要重拍或换一张更大的原图"，不要硬放大。
- 人像换底色：纯色背景照效果最好；背景杂乱的照片用
--bg-mode global并调--bg-tol（30/60/90 试），仍不理想就建议用户用专业抠图工具，脚本不强行伪造。 - 隐私：脚本重存图片会自动丢弃 EXIF（拍摄时间、GPS 定位），可主动告知用户这一点。
- 批量：
--input a.jpg b.jpg c.jpg --out-dir out/，逐个校验后再一起交付。
注意
- 纯本地：不联网、不上传照片、不产生任何费用，证件照、身份证照可放心处理。
- 依赖 Pillow：首次使用先跑
python scripts/photo_toolkit.py check；若提示缺失，运行python -m pip install Pillow。Windows 上若python不可用，改用py；macOS/Linux 可用python3。 - 不伪造、不美化：只做压缩、缩放、底色替换、格式转换，不做换脸、磨皮、证件信息修改。
- 换底色是纯色替换：基于背景颜色连通区域识别，对纯色背景照有效，复杂背景效果有限，报告会如实说明。
- 规格预设会随常见要求更新，版本号见报告底部
规格库 2026.09-r1。
