image-layer-alignment-validator

图像图层对齐验证器

使用此技能检查两个图像图层能否合成为同一场景或主体。目标不是进行一般的图像点评，而是判断底图图层和揭示图层在空间上是否兼容。

模式

• compare：分析两个本地图像文件，并生成视觉及报告文件。
• diagnose：检查现有报告或截图，并解释揭示效果／变形效果为何看起来未对齐。
• advise：将测得的偏移量转化为具体修复方案：平移、缩放、裁剪、重新生成或接受现状。
• threshold：针对严格的产品／人像工作或更宽松的创意揭示效果，调整验收阈值。

工作流

1. 确认目标图层恰好有两个：底图和揭示／后续图层。

2. 默认在本地完成所有分析。除非用户明确要求，否则不要将私人图像上传到外部服务。

3. 有本地图像路径时，运行 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
   

4. 作出判断前，先检查生成的文件。该脚本采用确定性的前景／几何启发式方法；语义判断仍然很重要。

5. 如果主体不明确，请阅读 references/subject-taxonomy.md，并明确说明所选的主要主体。

6. 使用 references/alignment-rubric.md 评估对齐情况。

7. 报告测得的偏移量，并给出具体的后续操作。

证据文件

对比脚本会写入：

• 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 获取本地的确定性证据。