Main & Detail Image Distillation

把一批参考主图和详情变成能执行的整套制作规则。每款的主图与详情是一个整体；详情先独立完成结构与设计分析，再检查整套一致性。

主图保留一组 7 张：首图 3 个版本 1、1-2、1-3，加上 2、3、4、5。详情是按商品内容确定的 N 个设计屏，不能预先固定为 7 屏、10 屏或参考文件数量。

核心原则

• 分析顺序固定。 详情多少屏 → 每屏的方向与内容 → 每屏怎样展示 → 整页节奏 → 主图和详情的风格、人物及商品一致性。不得用“主图第几张对应详情第几张”的卖点表代替这套分析。
• 先定义屏再统计。 一屏是有完整设计意图的视觉模块，不是一个文件，也不是手机可视高度。切片需要拼回；一张长图也可能跨几屏。记录每屏来源区域及顺序，边界不明确时先看图核实。
• 只蒸馏，不生产。 产出是规则文件，不交付客户商品图片；回测图只用于检验规则。
• 整套作为样本。 所有款式共同参与归纳，不先按风格拆组。缺失详情只记录限制；重复详情保留每套结构记录，设计频次按完全相同内容去重。
• 数字来自标注统计。 先逐张标注，再由 stats.py 统计；规则里的频次、位置、字号都引用 统计.md，不凭印象写。
• 风格从商品推导。 规则要写清楚“当前商品的颜色、图案、主题、杯型 → 服装、背景、道具、光线、文字颜色”的推导方法，不写“套用某个参考款的风格”。
• 文案先定，底图无营销文字，最后代码排字。 标题、说明、规格、装饰字和叠加 Logo 由 typeset.py 排；商品本体真实品牌字形和图案属于外观证据，必须保留，不能和待排文案一起抹掉。
• 整套共用设定。 记录主题、配色、字体、人物外观、商品结构和场景光线；写清哪些设定固定、哪些可随内容变化，不强制每屏相同背景或同一姿势。
• 参考事实只作参考。 容量、材料、功效、榜单和价格等不能自动移植到新商品；未核实的信息标待核实，不补写成商品事实。
• 用回测证明像不像。 规则写完必须拿一款重做并和原图并排比较，按差异改规则。
• 资料留在技能内部。 蒸馏文档和过程文件默认存入本技能缓存，不复制到桌面交付目录，不生成压缩包。
• 禁止非必要地强行添加光影。 如实统计参考光线，但不能把频次转为每张图必须补光的指令。生成规则和提示词必须保留此约束；曝光或光向冲突才允许最小修正，禁止无理由添加光束、光斑、轮廓光、窗影或夸张投影。

读取位置与输出位置

生成底图和最终图片优先使用原生 4K 或 2K：工具支持当前画面比例的原生 4K 时优先 4K，否则用 2K。4K 指长边 3840 或 4096 像素（按工具原生规格）；2K 方图为 2048×2048，3:4 竖图为 1536×2048。config/defaults.json 默认配置原生 2K；拿到同一比例的原生 4K 底图时，排字保留其像素尺寸。先核对工具的尺寸与总像素限制，禁止为追求 4K 改变既定比例或虚报分辨率；低清插值放大不等于原生高清。总览、网格和对比预览不受成品尺寸要求限制。

	规则
读取位置（主图与详情参考目录）	只用客户给的目录。客户没说时先问，禁止自行假设、搜索或沿用以前用过的目录
缓存位置	默认使用本技能 state/cache/<任务名>-已处理图片/，任务名由客户给，没给时取参考目录名。只有客户明确要求导出蒸馏文档到其他路径时才使用 --out；商品图交付到桌面的要求不等于导出蒸馏文档

输出目录结构：

state/cache/<任务名>-已处理图片/
├── 规则.md、提示词模板.md、layout.json、统计.md、回测记录.md   内部蒸馏资料
└── 过程文件/   manifest.json、annotations.json、grid/、sheets/、detail-screens/、stats.json、backtest/

• 输出目录不能放在参考数据目录里面；默认输出目录已存在且不是本 skill 建的，脚本会拒绝，改用 --out 或 --name。
• 同一输出目录只对应一份参考数据；重扫按路径及文件哈希保留未变标注，详情来源或顺序改变时恢复待复核状态。
• 任务文件只放本技能 state/cache/；用于生产的正式规则、脚本和配置仍放各自现有目录。
• 不生成 ZIP、7z、RAR 等压缩包，不把规则、提示词、统计、回测、标注、网格图或总览图混入最终商品图片文件夹。

Skill 目录

zhengliu-skill/
├── config/defaults.json      默认缓存目录后缀、目录关键词、枚举、输出尺寸、模糊词、必备章节
├── scripts/                  扫描、还原详情屏、统计、排字、对比及校验
├── references/               主图标注、详情标注、交付物规范、回测流程
├── state/cache/              任务蒸馏资料与过程缓存
└── agents/openai.yaml

所有命令用 python -B -X utf8 运行。$S 指本 Skill 的 scripts 目录，$O 指本次任务的缓存目录（命令行中仍称为“输出目录”）：

$S = Join-Path (Get-Location).Path 'scripts'

先进入当前 SKILL.md 所在的实际安装目录，再执行上面的命令；不要照抄其他电脑的路径。需要 Python 3.9+、Pillow、NumPy 和可读取图片的 AI 工具。在 Skill 根目录执行 python -m pip install -r requirements.txt 安装依赖。排字前按本机实际字体配置 layout.json；回测使用当前环境可用的生图工具，没有时按回测流程由用户提供底图。

流程

1. 扫描参考图

python -B -X utf8 "$S/scan_dataset.py" "<客户给的参考数据目录>" [--name <任务名>]

• 不加 --out 时写入本技能 state/cache/<任务名>-已处理图片/；脚本最后打印的“输出目录”就是之后各步的 $O。
• 批次下每个款式文件夹作为一套；直接给单套时使用 --single-set。脚本也会识别直接包含主图/详情/SKU 的单套目录，扫描后核对套数、分类及未识别文件。
• “主图/首图/main”和“详情/detail”都参与蒸馏；SKU、白底、商品图等记为商品输入；视频排除。最近一级明确目录名优先，关键词在 config/defaults.json。
• 输出文件清单、哈希重复标记、近似提示、总览和网格、主色板、annotations.json。近似图只提示，不自动删除；详情完全重复也不能使套内屏序消失。
• --no-preview 只索引，不能替代实际看图。无详情、疑似混款、无法判定边界等写明证据及限制。

2. 先还原并拆解详情

先读 [详情标注规范](references/detail-annotation-guide.md)。逐套打开全部详情，按视觉模块恢复顺序，在 annotations.json.detail_sets 填写：

1. 多少屏：总屏数、商品内容屏和附加说明屏分别计数；来源切片如何组合、连续页在哪里切开。
2. 每屏的设计方向与内容：本屏作用、核心信息、要展示哪些商品/颜色/结构/动作；为什么放在此处。
3. 怎么展示：商品数量角度状态、人物数量外观穿搭动作、场景道具、景别构图、分栏拼图、文案及字体、尺寸与留白、光线材质。
4. 整页怎么组织：内容推进、图型交替、密度与留白、重复和新增信息、上下屏衔接，以及不同商品增减屏的条件。

先填屏来源，运行下列命令还原预览，再看完整屏及顺序预览，核实后完善逐屏标注。sources 支持多片一屏、一片多屏，坐标为各原文件内的百分比。

python -B -X utf8 "$S/detail_screens.py" "$O" --style "<款式目录名>"

3. 标注主图，再检查整套一致性

按 [主图标注规范](references/annotation-guide.md) 填写 images 中 kind=main 的记录及 products。详情原文件只存来源信息，逐屏设计写在 detail_sets，不可混进主图图位统计。

完成两部分后填写 detail_sets.<款>.consistency：风格、人物外观设定、商品、场景光线，逐项写观察、可执行规则和本套主图/详情证据。人物检查发型发色、服装饰品、妆容、人数和造型延续，不推断真人身份；同一设定反复出现时绑定同一人物参考，新角色或换装要写依据。商品检查比例、结构、花色、配件、品牌字形和规格，防止混款。每标完一套运行：

python -B -X utf8 "$S/stats.py" "$O" --partial

按报错补齐缺项。全部标完后不加 --partial 再运行一次，返回码 0 才算标注完成。

4. 统计

stats.py 先输出详情屏数、每屏设计与展示、页面结构和整套一致性，再输出既有主图统计。详情频次区分套数与去重后的设计屏数；文字字高以完整屏宽度为基准，避免长图高度或切片数量改变字体尺度。主图保留按画高统计的原有规范，两者不能混用。

5. 写规则

按 [交付物规范](references/rules-template.md) 在 $O 写 规则.md、提示词模板.md、layout.json。必须回答以下问题：

问题	写在哪
新商品应有多少详情屏，增减依据是什么	规则.md「详情屏数与结构」「详情增减规则」
每屏什么方向、讲什么、怎样展示	规则.md「逐屏设计」；layout.json details
前后屏如何推进、密度与留白如何变化	规则.md「展示方式与页面节奏」
主图和详情共用哪些风格、人物及商品设定	规则.md「整套一致性」；layout.json detail_plan
第1–5张各放什么、新商品怎么分配卖点	规则.md「图位规划」
首图 3 个版本各用什么设计方向、彼此怎么区分	规则.md「首图方案」+ 统计.md「首图设计方向」
7 张图怎么命名	规则.md「命名」：1、1-2、1-3、2、3、4、5
画面风格、杯子的呈现方式怎么定	规则.md「商品风格推导」
文案写什么、几行、几个字、什么句式	规则.md「文案」
用什么字体、字的风格	规则.md「字体与字的风格」+ layout.json fonts
字和商品放在哪、字多大	规则.md「布局」+ layout.json slots
输出多大、1:1 与 3:4 的关系	规则.md「尺寸」
先出图还是图文一起出	规则.md「制作顺序」
客户商品图不是白底怎么办	规则.md「商品图输入规则」
每张图怎么写提示词	提示词模板.md（首图写“首图 1 / 1-2 / 1-3”，其余写“第N张”）

写完运行：

python -B -X utf8 "$S/check_rules.py" "$O"

校验标注及统计是否完成且一致、主图是否 7 张、详情是否覆盖当前规划全部 N 屏、屏序及画布、宽度字号基准、字体和提示词是否齐全。detail_plan 是本次选定回测款的具体计划，通用增减方法写在规则中；不能把这个 N 固定给所有新商品。返回码 0 才进入回测，校验通过不等于视觉回测通过。

6. 回测校准

按 [回测流程](references/backtest.md) 执行：选一款，只用它的商品图作输入，按规则走完整制作顺序；生成无字底图后排字：

$R = "$O/过程文件/backtest/round-1"
python -B -X utf8 "$S/typeset.py" --layout "$O/layout.json" --slot 1 --ratio 1:1 --base "$R/base/main/1.png" --texts "$R/texts/main/1.json" --out "$R/final/main/1.png"
python -B -X utf8 "$S/typeset.py" --layout "$O/layout.json" --detail detail-01 --base "$R/base/detail/detail-01.png" --texts "$R/texts/detail/detail-01.json" --out "$R/final/detail/detail-01.png"
python -B -X utf8 "$S/compare_sheet.py" --ref "$O/过程文件/detail-screens/<款式>" --gen "$R/final/detail" --detail --columns 4 --out "$R/compare-detail.jpg"

回测覆盖 7 张主图及全部 N 屏详情，逐屏和整页顺序都看；检查设计表达、图文对应、信息增量、人物及商品是否漂移。把“差异 → 原因 → 改动”写入 回测记录.md，最多 3 轮。无法生成底图时明确“规则已整理，视觉回测未完成”，不可声称整套验证通过。

7. 完成与保留缓存

$O 中 5 个蒸馏资料文件齐全、check_rules.py 通过、整套视觉回测记录写明结论后报告完成及剩余差异。缺失详情的款式、未知商品事实和未验证内容明确记录。资料保留在技能缓存；正式主图与详情由生产技能交付，不另建桌面蒸馏资料包。

追加或更换参考图

参考图有增减时重扫同一目录：未变文件保留标注，替换内容的文件清空图像标注，删除文件移出清单；受影响详情套保留旧拆屏供核对并转为 pending。复核切片边界、来源、顺序和一致性，再统计、更新规则、回测。旧 stats.json 不能用于证明新标注完成。

清空缓存与恢复初始状态

用户要求清空缓存、恢复成没用过的状态时，清理本技能 state/、历史 output/ 和 scripts/__pycache__/ 中的任务、底图、标注、日志、回测与旧产物；先核对路径、链接和活动进程，优先移入回收站。保留当前技能规则、脚本、配置、通用参考和空白模板。完成后不得把旧任务记录、清理日志或验证产物重新写回技能；下次任务从用户当前提供的素材开始，新建所需缓存。