真人头像 + 卡通校服身体 批量生成
用途
把一组学生真人照片，逐个转成「写实头部（原照片原样裁切）+ 扁平卡通 Q 版身体（穿校服）」的全身立绘，最终交付透明背景 PNG，可直接贴到课件、班级墙、点名表、PPT 上。
三条铁律（任何情况下不得违反）：
- 头部必须是原照片的写实质感——保留皮肤毛孔、发丝、照片纹理；一旦出现卡通/动漫/插画风格即为失败，必须重做。
- 校服不得凭空想象——只能用内置默认款，或用用户实际上传的校服图片，见「校服参数规则」。
- 不得张冠李戴——批量时必须逐张核对「原图 ↔ 成品」的对应关系。
何时使用
- 用户发来一批学生照片，要做卡通头像 / 班级形象 / 校服形象。
- 用户要求「真人头 + 卡通身体」「真人头像不动，只换身体」。
- 用户要求给某位同学重做头像（如视线朝下、头部被卡通化、衣服不对）。
- 用户要求更换校服款式。
用户只发一张已处理过的照片且未说明需求时，按「重做该张」处理：回查编号 → 目检 → 重做 → 抠图 → 替换。
输入参数
| 参数 | 必填 | 说明 |
|---|---|---|
photos |
✅ | 学生真人照片，一张一位；顺序 = 用户的发送顺序（编号依据） |
uniform |
❌ | 校服款式。未提供时使用内置默认款，见下节 |
uniform_image |
❌ | 校服参考图。仅当用户明确要求换校服时，必须由其亲自上传 |
start_index |
❌ | 起始编号，默认 1；已有前序批次时接续（如 31） |
prefix |
❌ | 文件名前缀，默认 S（S01、S02…） |
output_dir |
❌ | 输出根目录，默认工作区下 class-avatars/ |
校服参数规则（三条，必须遵守）
- 默认：不传校服时用内置默认款——红白运动服（白色运动外套 + 深酒红插肩袖 + 红白条纹立领/袖口/下摆 + 红色嵌线口袋 + 藏青运动裤带两侧双白条 + 白运动鞋）。完整文案见
references/prompt-library.md。 - 换款必须先拿到图：用户说「换一种校服 / 用这款校服」但没有上传校服图片时，不得自行假设款式、不得套用其他款式、不得凭描述生成。停下来按下方文案索要图片，拿到图之后再继续。
- 有图才用图：用户上传校服图后，把该图作为
image2传入，并先目检这张图，按图中真实可见的颜色与款式写出描述填进提示词（不得沿用默认款文案，也不得把图中没有的元素写进去）。
缺少必要输入时的提示文案
场景 A：用户要求换校服但没给图
> 收到，换校服可以做。不过校服款式我不能替您猜——麻烦您直接发一张这款校服的图片（实物照、效果图、同学穿着照都行），我按图上的颜色和款式生成。
> 拿到图片后立刻开始；在此之前不会改动任何已完成的头像。
> 如果您其实想用上一批那套红白运动服，直接说一声就行。
场景 B：用户没发照片
> 还差学生照片——请把要做的同学照片发给我（一次可发多张），我按发送顺序编号。
> 只做某一位的话，发他的一张照片即可。
场景 C：校服图看不清款式（过暗 / 只拍到局部 / 被遮挡）
> 这张校服图我看不全（写明具体原因：只拍到局部 / 光线太暗 / 被挡住），按它生成容易和实物对不上。
> 麻烦再补一张能看清上衣颜色与裤子款式的照片；或者说「就用默认红白运动服」，我按默认款继续。
场景 D：照片里有多个人 / 看不清脸
> 第 N 张照片里有几位同学（或脸被遮挡、侧脸太暗），我无法确定要给谁做，头部也裁不出来。
> 麻烦补一张该同学单人、正脸清晰的照片，我再做这一位。
执行流程
每一步的输出直接作为下一步的输入，不得跳步；批量作业开始前先读 references/troubleshooting.md。
步骤 0 — 归集照片并记录顺序
- 输入：用户粘贴的照片（落在
~/.workbuddy/clipboard-images/）。 - 动作：按批次时间戳前缀
ls | grep "<批次时间戳>" | sort得到清单，写入<output_dir>/batch_list.txt。排序结果即编号顺序，它决定后续所有对应关系。 - 输出：
batch_list.txt（N 行）；确认 N 与用户发送张数一致。
步骤 1 — 确定校服文案
- 输入：
uniform_image（可选）。 - 动作：无图 → 取
references/prompt-library.md的默认款文案；有图 → 目检图片后据实改写衣服描述。 - 输出：一段身体描述字符串，供步骤 2 拼装。
步骤 2 — 建目录并生成图像
- 目录：
<output_dir>/gen/（原始生成）、renamed/（编号后）、sheets/（对照表）、transparent/（最终交付）。 - 生成参数：
size=1024x1536、quality=medium、input_fidelity=high、image1=学生照片；有校服图时image2=校服图。 - 防冲突（必做）：每轮最多 3 张并行；每张提示词开头加唯一前缀
Student NN.（NN = 该生在本批的两位序号）。输出文件名由提示词前缀 + 时间戳构成，同秒生成会互相覆盖，前缀唯一即可彻底避免。 - 每轮结束必须
ls核对：本轮文件是否齐全、前缀是否覆盖到位；缺哪张就单独补生成（不要整批重跑）。 - 输出：
gen/下 N 个文件（此时为白底 RGB，属正常，步骤 5 抠图处理）。
步骤 3 — 建立映射并编号
- 输入：
gen/文件 +batch_list.txt。 - 动作：确认每个
Student_NN__*.png对应第 NN 位同学，写成mapping.txt，每行NN|生成文件绝对路径。 - 运行：
python scripts/rename_results.py --mapping mapping.txt --dest renamed/ --prefix S --start 31 - 输出：
renamed/S31.png …，并打印每张的模式 / 透明占比报告（此阶段为 RGB 白底，不必惊慌）。
步骤 4 — 生成对照表并逐张目检（防张冠李戴）
- 运行：
python scripts/make_sheets.py --src-list batch_list.txt --src-dir <照片目录> --result-dir renamed/ --out-dir sheets/ --prefix S --start 31 --pairs 4 - 动作：逐张打开对照表目检，确认每对左右是同一位同学（看发型、眼镜、脸型、衣物颜色），同时确认头部未被卡通化、姿态自然。
- 发现错配或被卡通化 → 记下编号 → 回到步骤 2 单独重做 → 重跑步骤 3、4。
- 输出：
sheets/check_part*.jpg（每页 4 对，左原图右成品）。此步不可省略，是防止张冠李戴的唯一手段。
步骤 5 — 云端抠图
- 先取凭证（有时效，过期报
INVALID_SHORT_KEY）；首次调用或报错时重新获取一次。 - 运行：
python scripts/batch_matting.py --src-dir renamed/ --dest transparent/ --token <token> - 脚本逐张调用云端抠图并落到
transparent/，末尾打印失败编号；针对失败项换新凭证单独重跑。 - 输出：
transparent/S31.png …（RGBA）。
步骤 6 — 校验与总览
- 运行：
python scripts/verify_and_sheet.py --src-dir transparent/ --prefix S --start 31 --end 63 --out _final_sheet.jpg - 判读：模式必须为 RGBA；透明占比 0.20–0.35 属正常（全身小人约占画面 1/4–1/3），低于 0.10 才算异常需重抠。抽查占比最低的 1–2 张确认边缘干净、无残底。
- 输出：
transparent/_final_sheet*.jpg总览图（浅色底、带编号）。
步骤 7 — 交付
- 用文件呈现工具交付：总览图排第一位，再附 2–3 张单张 PNG 供抽查。
- 说明中写清：编号范围、存放路径、总张数、校服款式、核对结果（共几对、是否发现错配、如何处理）。
单张重做流程
用户发来一张照片（通常是已做过但不满意）时：
- 用文件名哈希回查它在
batch_list.txt中的序号 → 得到编号（如第 8 位、起始 31 → S38）。 - 打开现有成品目检，判断问题类型：头部卡通化 / 视线朝下 / 衣服不对 / 换错人。
- 针对性改提示词重做（头部卡通化 → 强化写实约束；视线朝下 → 追加"正视镜头"约束，见
references/prompt-library.md的可选补丁段），仍要保留Student NN.前缀。 - 抠图后原地替换
transparent/S38.png，重跑步骤 6 校验。 - 交付时说明具体改了什么。
脚本清单
| 脚本 | 用途 | 关键参数 |
|---|---|---|
scripts/rename_results.py |
按映射编号 + 检查透明通道 | --mapping --dest --prefix --start |
scripts/make_sheets.py |
生成「原图 vs 成品」对照表 | --src-list --src-dir --result-dir --out-dir --pairs |
scripts/batch_matting.py |
批量云端抠图 | --src-dir --dest --token |
scripts/verify_and_sheet.py |
透明度校验 + 总览图 | --src-dir --prefix --start --end --out |
环境：Pillow（已装在 ~/.workbuddy/binaries/python/envs/default）；抠图脚本固定路径为
C:/Program Files/WorkBuddy/resources/app.asar.unpacked/resources/plugins/workbuddy-builtin/skills/buddy-image-processing/scripts/buddy-image-processing.py。
已知坑
并行覆盖、文件名冲突、凭证时效、透明占比误判等所有踩过的坑记在 references/troubleshooting.md，批量作业前先读一遍，不要凭感觉重蹈覆辙。
