image-layer-alignment-validator

用途

Image Layer Alignment Validator 用于检查两张图像图层能否作为同一场景或同一主体进行合成。它的目标不是对图像做泛泛的批评，而是判断基础层（base）与揭示层（reveal/after）在空间上是否兼容，从而决定是否适合用于揭示、前后对比、变形、蒙版合成或交互式光标揭示等效果。

主要能力

技能提供四种模式：

compare：分析两个本地图像文件，生成可视化与报告产物。
diagnose：检查已有报告或截图，解释揭示/变形效果为何看起来错位。
advise：把测得的偏移转化为具体修正方案，例如平移、缩放、裁剪、重新生成或接受现状。
threshold：针对严格的产品/人像工作与较宽松的创意揭示效果，调整验收阈值。

使用方式

工作流程如下：

确认恰好存在两个目标图层：基础层与揭示/后置层。
默认全部在本地分析。除非用户明确要求，不要把私密图像上传到外部服务。
当本地图像路径可用时，运行 scripts/compare_layers.py：

python3 $CODEX_SKILLS_DIR/image-layer-alignment-validator/scripts/compare_layers.py \
  --base /path/to/base.png \
  --reveal /path/to/reveal.png \
  --out /path/to/alignment-output

在给出结论前检查生成的产物。该脚本是确定性的前景/几何启发式方法，语义判断仍然重要。
如果主体不明确，阅读 references/subject-taxonomy.md，并明确说明所选择的主主体。
使用 references/alignment-rubric.md 对对齐情况打分。
报告测得的偏移，并给出具体的下一步操作。

证据产物

比较脚本会写出以下文件：

alignment-report.md：人类可读的指标、结论与建议修正。
alignment-metrics.json：机器可读的尺寸、边界框、偏移、IoU 与结论。
annotated-base.png：在基础层上检测到的主/次边界框。
annotated-reveal.png：在揭示层上检测到的主/次边界框。
side-by-side.png：带边界框的并排视觉对比。
overlay.png：将揭示层叠加在基础层上以便快速检查。
difference.png：放大的像素差异图。

判定规则

把测得的主主体边界框当作证据而非真理。当目视检查明显发现不同的主要对象时，应覆盖该结果。
结论优先使用归一化测量值，以便不同画布尺寸之间可比。
对于光标揭示或蒙版揭示，主主体通常应比背景更严格。背景、光照、纹理和小配件的差异可以变化而不导致该对图像不合格。
如果在预期揭示区域内主主体中心偏移肉眼可见，建议先做图像修正，再进行前端工作。
如果揭示图像确实是不同的主体，不要试图用 CSS/canvas 调参来掩盖。

安全与隐私

默认在本地处理本地图像。
除非用户明确要求该路径，不要把私密、客户、人脸、身份或未发布的创意图像上传到外部服务。
不要覆盖源图像。把报告与派生产物写入单独的输出目录。
建议重新生成时，描述预期的几何约束，而不是把私密图像细节嵌入可复用的技能文件。

验证与评估

在信任新阈值前，用有代表性的图像对验证脚本。
在返回结论前，检查 alignment-report.md 与至少一个可视化产物。
当前景检测失败时，把 inconclusive 视为有效结果。
对于严格效果，在任何平移、裁剪、缩放或重新生成步骤后重新运行脚本。
用包含已对齐图像对、轻微主体偏移、不同画布尺寸以及不相关揭示主体的示例对技能进行前向测试。

输出格式

Verdict: aligned | minor drift | misaligned | different subject | inconclusive
Evidence:
- Primary subject: ...
- Center drift: ... px (... normalized)
- BBox IoU: ...
- Scale delta: ...
- Secondary-object notes: ...
Action:
- ...
Artifacts:
- /absolute/path/alignment-report.md
- /absolute/path/side-by-side.png
- /absolute/path/overlay.png

资源

在判断什么算主主体、什么算次要对象时，阅读 references/subject-taxonomy.md。
在对输出打分或调整阈值时，阅读 references/alignment-rubric.md。
使用 scripts/compare_layers.py 获取本地确定性证据。

限制

资料未提供该技能的具体收费、价格、支持平台或性能效果数据。脚本为确定性的前景/几何启发式方法，语义判断仍需人工介入；当前景检测失败时结果可能为 inconclusive。