minimal-agent 0.8.2 → 0.10.0

package/skills/pptx/scripts/deck_helpers.mjs

@@ -0,0 +1,224 @@
+/* eslint-disable */
+// ============================================================================
+//  skills/pptx/scripts/deck_helpers.mjs
+//  ----------------------------------------------------------------------------
+//  可复用的「原生 addShape 矢量原语」库（结构图路线）。import 即用，省得每次重写
+//  并重新踩 PptxGenJS 的坑。这些图形是 **PowerPoint 原生对象**，天然每个独立可选中、
+//  可改色、可移动、内部文字可重排 —— 比 SVG 还省事（连「转换为形状」都不用）。
+//
+//  用法（Node，不要 Bun —— 见 pptxgenjs.md 文首铁律）：
+//    import PptxGenJS from 'pptxgenjs';
+//    import { drawCard, drawNode, drawArrow, connect, drawTitle, drawFooter, inkFor } from './deck_helpers.mjs';
+//    const pres = new PptxGenJS(); pres.layout = 'LAYOUT_WIDE';
+//    const s = pres.addSlide(); s.background = { color: '0F172A' };
+//    drawTitle(s, '§1', '架构全景', { bg: '0F172A' });   // 深底 → 标题自动取白字
+//    const a = { x: 1, y: 3, w: 2.5, h: 1.2 }, b = { x: 5, y: 3, w: 2.5, h: 1.2 };
+//    drawNode(s, a.x, a.y, a.w, a.h, '输入'); drawNode(s, b.x, b.y, b.w, b.h, '输出');
+//    connect(s, a, b);                                    // 由两形状边框自动算端点，绝不残桩
+//
+//  说明：位置/尺寸默认值按 LAYOUT_WIDE（13.3" × 7.5"）调好；其它 layout 自己传坐标。
+//  颜色一律 6 位 hex、不带 '#'、不带 8 位透明度（透明度走 opacity/transparency 字段）。
+//
+//  内嵌的 PptxGenJS 踩坑防御（每条都曾真实损坏文件或产出难看页，别绕过）：
+//   - 阴影/option 对象 **每次新建**：PptxGenJS 会 in-place 把值转成 EMU，复用同一对象损坏后续形状。
+//   - 颜色禁 '#' 前缀、禁 8 位 hex（assertColor 兜底）。
+//   - roundRect 不要叠矩形 accent 条当左边框（盖不住圆角）；要精确对齐色条用 rect。
+//   - 标题下不画双下划线 accent line（AI 生成 PPT 的典型痕迹，用留白/底色代替）。
+//   - **文字对比**：drawTitle / drawNode / drawSectionBadge 会按背景断言可读（assertReadable），
+//     暗字暗底直接抛错 —— 别绕过去手写不检查的 addText。不确定字色就用 inkFor(bg) 自动取。
+//   - **连线**：drawArrow 守卫最短长度（< 0.25" 抛错，杜绝残桩箭头）；连两个形状一律用
+//     connect(from, to)（自动算边到边端点），别手填易飘/易残桩的坐标。
+// ============================================================================
+
+const MIN_CONNECTOR_LEN = 0.25; // 英寸：短于此基本是端点重合/算错的残桩箭头（AI PPT 典型缺陷）
+
+function assertColor(c) {
+  if (typeof c === 'string' && (c.startsWith('#') || c.length === 8)) {
+    throw new Error(`bad color "${c}": 用 6 位 hex、不带 #；透明度用 opacity/transparency 字段`);
+  }
+  return c;
+}
+
+// ──────────────── 对比度原语（WCAG 2.1）：把「强对比」从口号变成生成期断言 ────────────────
+
+function hexToRgb(hex) {
+  const h = String(hex).replace(/^#/, '');
+  if (!/^[0-9a-fA-F]{6}$/.test(h)) throw new Error(`bad hex "${hex}": 需 6 位十六进制`);
+  return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16));
+}
+
+// 相对亮度（WCAG 2.1）：0（纯黑）~ 1（纯白）。
+export function relLuminance(hex) {
+  const [r, g, b] = hexToRgb(hex)
+    .map((v) => v / 255)
+    .map((c) => (c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4));
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+// 对比比（WCAG）：1（同色，最差）~ 21（黑白，最佳）。
+export function contrastRatio(a, b) {
+  const la = relLuminance(a);
+  const lb = relLuminance(b);
+  const hi = Math.max(la, lb);
+  const lo = Math.min(la, lb);
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+// 给定背景，返回 dark / light 里与之对比更高的一个（自动选可读字色）。
+export function inkFor(bg, { dark = '0F172A', light = 'FFFFFF' } = {}) {
+  return contrastRatio(dark, bg) >= contrastRatio(light, bg) ? dark : light;
+}
+
+// 对比不足直接抛错（生成期就炸，附自救提示）：把「画不出不可读文字」变成硬约束。
+export function assertReadable(fg, bg, { min = 4.5, label = '' } = {}) {
+  const r = contrastRatio(fg, bg);
+  if (r < min) {
+    throw new Error(
+      `文字对比度不足：字色 ${fg} / 底色 ${bg} = ${r.toFixed(2)}:1 < ${min}:1` +
+        `${label ? `（${label}）` : ''}。用 inkFor(bg) 自动取可读字色，或换背景。`,
+    );
+  }
+  return r;
+}
+
+// 尽力从 slide 读已设置的背景色（标准 s.background = { color } 写法）；读不到返回 undefined。
+function readSlideBg(slide) {
+  try {
+    const b = slide && slide.background;
+    if (b && typeof b.color === 'string') return b.color;
+    const bk = slide && slide.bkgd;
+    if (bk && typeof bk.color === 'string') return bk.color;
+  } catch {
+    /* 内部结构因版本而异，读不到就算了：契约是显式传 bg */
+  }
+  return undefined;
+}
+
+// 阴影：⚠️ 每次返回新对象，绝不复用（PptxGenJS in-place mutate 会损坏第二个形状）。
+export const makeShadow = (o = {}) => ({
+  type: 'outer', blur: 8, offset: 2, angle: 90, color: '000000', opacity: 0.12, ...o,
+});
+
+// 矩形（无圆角）：用于需要精确对齐的标题底色/分隔条/色块。
+export function drawRect(slide, x, y, w, h, { fill = '1E2761', line, lineWidth = 0, shadow = false } = {}) {
+  slide.addShape('rect', {
+    x, y, w, h,
+    fill: { color: assertColor(fill) },
+    ...(line ? { line: { color: assertColor(line), width: lineWidth } } : { line: { type: 'none' } }),
+    ...(shadow ? { shadow: makeShadow() } : {}),
+  });
+}
+
+// 圆角卡片：内容卡/分组容器。
+export function drawCard(slide, x, y, w, h, { fill = 'F8FAFC', border = 'E2E8F0', borderWidth = 1, radius = 0.08, shadow = true } = {}) {
+  slide.addShape('roundRect', {
+    x, y, w, h,
+    fill: { color: assertColor(fill) },
+    line: { color: assertColor(border), width: borderWidth },
+    rectRadius: radius,
+    ...(shadow ? { shadow: makeShadow() } : {}),
+  });
+}
+
+// 架构图节点（圆角矩形/矩形/椭圆 + 居中文字）。kind ∈ round | rect | oval。
+// 文字色与填充色对比不足直接抛错（节点字多为大字，按 AA 大字 3:1 把关）。
+export function drawNode(slide, x, y, w, h, label, { kind = 'round', fill = '1E2761', textColor = 'FFFFFF', fontFace = 'Calibri', fontSize = 12, bold = true, radius = 0.06 } = {}) {
+  const shape = kind === 'oval' ? 'ellipse' : kind === 'rect' ? 'rect' : 'roundRect';
+  slide.addShape(shape, {
+    x, y, w, h,
+    fill: { color: assertColor(fill) },
+    line: { color: 'FFFFFF', width: 1 },
+    ...(shape === 'roundRect' ? { rectRadius: radius } : {}),
+  });
+  if (label) {
+    assertReadable(textColor, fill, { min: 3, label: `node "${String(label).replace(/\n/g, ' ')}"` });
+    slide.addText(label, { x, y, w, h, fontFace, fontSize, bold, color: assertColor(textColor), align: 'center', valign: 'middle', margin: 0 });
+  }
+}
+
+// 连线（带可选箭头）。支持任意方向（用 flipV 处理向上）。
+// ⚠️ 守卫最短长度：端点几乎重合（< 0.25"）时抛错，杜绝「残桩/无连接箭头」这一 AI PPT 典型缺陷。
+//    要连两个形状请用 connect(slide, from, to)——由形状边框自动算端点，永不残桩、永不飘。
+export function drawArrow(slide, x1, y1, x2, y2, { color = '94A3B8', width = 1.5, dashed = false, arrow = true } = {}) {
+  const dx = x2 - x1;
+  const dy = y2 - y1;
+  const len = Math.hypot(dx, dy);
+  if (len < MIN_CONNECTOR_LEN) {
+    throw new Error(
+      `连线过短：长度 ${len.toFixed(3)}" < ${MIN_CONNECTOR_LEN}"（端点 (${x1},${y1})→(${x2},${y2}) 几乎重合）。` +
+        '残桩/无连接箭头是 AI PPT 的典型缺陷；连两个形状请用 connect(slide, from, to)。',
+    );
+  }
+  const x = Math.min(x1, x2);
+  const y = Math.min(y1, y2);
+  const w = Math.abs(dx) || 0.001; // 垂直线给 PptxGenJS 一个极小正宽；总长已由 len 守卫保证
+  const h = Math.abs(dy) || 0.001;
+  slide.addShape('line', {
+    x, y, w, h,
+    flipV: y2 < y1,
+    line: { color: assertColor(color), width, ...(dashed ? { dashType: 'dash' } : {}), ...(arrow ? { endArrowType: 'triangle' } : {}) },
+  });
+}
+
+// 连接两个形状：传两个矩形 {x,y,w,h}（英寸），算「中心连线裁到各自边框」得到边到边端点再画箭头。
+// → 端点永远贴住两个真实锚点，杜绝飘移/残桩。两矩形重叠时抛错（没有合理的可见连线）。
+export function connect(slide, from, to, opts = {}) {
+  for (const [n, r] of [['from', from], ['to', to]]) {
+    if (!r || ['x', 'y', 'w', 'h'].some((k) => typeof r[k] !== 'number')) {
+      throw new Error(`connect(): ${n} 需为 {x,y,w,h} 数值矩形（英寸）`);
+    }
+  }
+  const overlap = !(
+    from.x + from.w <= to.x ||
+    to.x + to.w <= from.x ||
+    from.y + from.h <= to.y ||
+    to.y + to.h <= from.y
+  );
+  if (overlap) {
+    throw new Error('connect(): 两个形状重叠，无法画出有意义的连线（先检查布局是否叠加）。');
+  }
+  const center = (r) => ({ cx: r.x + r.w / 2, cy: r.y + r.h / 2 });
+  // 从矩形中心朝 (tx,ty) 方向射线与该矩形边框的交点。
+  const edge = (r, tx, ty) => {
+    const { cx, cy } = center(r);
+    const dx = tx - cx;
+    const dy = ty - cy;
+    const hw = r.w / 2;
+    const hh = r.h / 2;
+    const tdx = dx === 0 ? Infinity : hw / Math.abs(dx);
+    const tdy = dy === 0 ? Infinity : hh / Math.abs(dy);
+    const t = Math.min(tdx, tdy);
+    return { x: cx + dx * t, y: cy + dy * t };
+  };
+  const a = center(from);
+  const b = center(to);
+  const p1 = edge(from, b.cx, b.cy);
+  const p2 = edge(to, a.cx, a.cy);
+  drawArrow(slide, p1.x, p1.y, p2.x, p2.y, opts);
+}
+
+// 章节徽章（小色块 + 文字），放在标题左上。文字落在 slide 背景上，按背景把可读性把关。
+export function drawSectionBadge(slide, x, y, label, { color = '00A896', textColor, fontFace = 'Consolas', fontSize = 14, bg } = {}) {
+  drawRect(slide, x, y, 0.35, 0.32, { fill: color });
+  const background = bg ?? readSlideBg(slide);
+  const ink = textColor ?? (background ? inkFor(background) : '0F172A');
+  if (background) assertReadable(ink, background, { min: 3, label: 'section badge label' });
+  slide.addText(label, { x: x + 0.4, y: y - 0.02, w: 4, h: 0.36, fontFace, fontSize, bold: true, color: assertColor(ink), valign: 'middle', margin: 0 });
+}
+
+// 标题栏（徽章 + 大标题）。⚠️ 不画标题下的双下划线。
+// 传 bg（或 slide 已设 background）时：标题色默认按背景自动取可读色（inkFor），并断言对比 ≥3:1（大字）。
+// 不传也读不到背景时：保持近黑默认、不断言（向后兼容；但深色页务必传 bg，否则暗字暗底看不清）。
+export function drawTitle(slide, badge, title, { x = 0.5, badgeColor = '00A896', titleColor, titleSize = 28, fontFace = 'Consolas', w = 12.3, bg } = {}) {
+  const background = bg ?? readSlideBg(slide);
+  const ink = titleColor ?? (background ? inkFor(background) : '0F172A');
+  if (background) assertReadable(ink, background, { min: 3, label: 'title' });
+  drawSectionBadge(slide, x, 0.35, badge, { color: badgeColor, bg: background });
+  slide.addText(title, { x, y: 0.75, w, h: 0.7, fontFace, fontSize: titleSize, bold: true, color: assertColor(ink), valign: 'middle', margin: 0 });
+}
+
+// 页脚（左侧文档名 + 右侧页码）。次要文字，按设计可较弱，不强制对比断言。
+export function drawFooter(slide, text, pageLabel, { y = 7.15, x = 0.5, leftW = 8, rightX = 11.3, color = '94A3B8', fontFace = 'Calibri' } = {}) {
+  if (text) slide.addText(text, { x, y, w: leftW, h: 0.25, fontFace, fontSize: 9, color: assertColor(color), align: 'left', valign: 'middle', margin: 0 });
+  if (pageLabel) slide.addText(pageLabel, { x: rightX, y, w: 1.5, h: 0.25, fontFace, fontSize: 9, color: assertColor(color), align: 'right', valign: 'middle', margin: 0 });
+}

package/skills/pptx/scripts/layout_lint.py

@@ -0,0 +1,293 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+layout_lint.py —— PPTX「布局/对比」确定性质量闸门（与 opc_check.py 互补）。
+
+为什么需要这个脚本？
+====================
+opc_check.py 管「OPC 合规 = PowerPoint 能否干净打开」（硬阻断）。但合规的包仍可能
+「能打开却难看」：文字与背景对比过低看不清、形状互相叠加、极短/无连接的残桩箭头。
+这些缺陷此前只靠「soffice 截图 + 子 agent 眼检」的视觉 QA 抓——对**其他 agent / 弱模型**
+不可靠（会跳过、会看漏）。
+
+本脚本做**不依赖渲染、纯解析 OOXML** 的确定性检查：只读 slide xml 的坐标/颜色，把
+「可计算」的三类缺陷在产物上拦下，给弱模型一道绕不过的防呆门槛。它**不替代**视觉 QA
+（主题色/跨形状层叠/文字截断等仍需眼睛），是其前置硬门槛。
+
+和 opc_check.py 一样：只用标准库（zipfile / xml.etree / math / re），忠实于最终消费者
+（Office），不依赖任何宽容的高层库。
+
+检查项（任一命中 → 非零退出码 + 人话问题 + 修复提示）
+====================================================
+A. 残桩/过短连线：连接符或 line 类形状长度 < 0.2"（端点重合/算错的残桩箭头，AI PPT 典型缺陷）。
+B. 形状叠加：两个非背景、非包含、非连线形状的包围盒显著相交。
+C. 低对比文字（限可靠场景）：形状有显式 solidFill 且其文字 run 有显式颜色时，二者对比
+   低于阈值（大字 3:1 / 正文 4.5:1，WCAG）。
+
+   局限（诚实声明）：不解析 theme/scheme 引用色，也不解析「文字浮于其它背景形状之上」的
+   跨形状 z-order 层叠——那些由 deck_helpers 的 assertReadable / drawTitle(bg) 与视觉 QA
+   覆盖。本脚本只抓「能确定、误报近零」的场景，避免像宽容库一样用噪声侵蚀信任。
+
+用法
+====
+    python layout_lint.py <file.pptx>            # 校验，无缺陷退出 0，有缺陷退出 1
+    python layout_lint.py <file.pptx> --verbose  # 额外打印 PASSED 明细
+"""
+
+import argparse
+import math
+import re
+import sys
+import zipfile
+import xml.etree.ElementTree as ET
+
+EMU_PER_INCH = 914400.0
+
+# OOXML 命名空间（presentationml / drawingml），固定不变。
+P = "{http://schemas.openxmlformats.org/presentationml/2006/main}"
+A = "{http://schemas.openxmlformats.org/drawingml/2006/main}"
+
+# 判定「连线/连接符」用的 prstGeom 前缀（line 类原语）。
+LINE_PREFIXES = ("straightConnector", "bentConnector", "curvedConnector")
+
+# 阈值
+MIN_CONNECTOR_IN = 0.2     # 短于此判残桩连线
+OVERLAP_MIN_AREA = 0.02    # 叠加最小绝对面积（in²），压住浮点/贴边噪声
+OVERLAP_MIN_FRAC = 0.10    # 叠加须 > 较小形状面积的 10%，才算「显著」
+BIG_BG_FRAC = 0.80         # 面积 ≥ 画布 80% 视为满铺背景，不参与叠加判定
+
+
+# ──────────────── 对比度（WCAG 2.1，与 deck_helpers.mjs 同一套公式） ────────────────
+
+def _hex_to_rgb(h: str):
+    h = h.strip().lstrip("#")
+    if not re.fullmatch(r"[0-9a-fA-F]{6}", h):
+        raise ValueError(f"非 6 位 hex：{h}")
+    return tuple(int(h[i:i + 2], 16) for i in (0, 2, 4))
+
+
+def _rel_luminance(h: str) -> float:
+    def chan(c: float) -> float:
+        c = c / 255.0
+        return c / 12.92 if c <= 0.03928 else ((c + 0.055) / 1.055) ** 2.4
+
+    r, g, b = _hex_to_rgb(h)
+    return 0.2126 * chan(r) + 0.7152 * chan(g) + 0.0722 * chan(b)
+
+
+def _contrast(a: str, b: str) -> float:
+    la, lb = _rel_luminance(a), _rel_luminance(b)
+    hi, lo = max(la, lb), min(la, lb)
+    return (hi + 0.05) / (lo + 0.05)
+
+
+# ──────────────── XML 提取小工具 ────────────────
+
+def _local(el) -> str:
+    return el.tag.split("}")[-1]
+
+
+def _xfrm(el):
+    """返回该形状自身的 (x, y, w, h)（英寸），取不到返回 None。只看自身 xfrm，不下钻子形状。"""
+    holder = el.find(P + "spPr")
+    if holder is None:
+        holder = el.find(P + "grpSpPr")
+    xf = holder.find(A + "xfrm") if holder is not None else None
+    if xf is None:
+        xf = el.find(P + "xfrm")  # graphicFrame 用 p:xfrm
+    if xf is None:
+        return None
+    off = xf.find(A + "off")
+    ext = xf.find(A + "ext")
+    if off is None or ext is None:
+        return None
+    try:
+        return (
+            int(off.get("x")) / EMU_PER_INCH,
+            int(off.get("y")) / EMU_PER_INCH,
+            int(ext.get("cx")) / EMU_PER_INCH,
+            int(ext.get("cy")) / EMU_PER_INCH,
+        )
+    except (TypeError, ValueError):
+        return None
+
+
+def _name(el) -> str:
+    c = el.find(".//" + P + "cNvPr")
+    if c is not None and c.get("name"):
+        return c.get("name")
+    return _local(el)
+
+
+def _is_connector(el) -> bool:
+    if _local(el) == "cxnSp":
+        return True
+    if _local(el) == "sp":
+        g = el.find(P + "spPr/" + A + "prstGeom")
+        prst = g.get("prst") if g is not None else None
+        if prst == "line" or (prst and prst.startswith(LINE_PREFIXES)):
+            return True
+    return False
+
+
+def _shape_fill(el):
+    sf = el.find(P + "spPr/" + A + "solidFill/" + A + "srgbClr")
+    return sf.get("val") if sf is not None and sf.get("val") else None
+
+
+def _low_contrast_runs(el, fill):
+    """形状有显式 fill 时，逐文字 run 检查显式字色与 fill 的对比，返回不达标项。"""
+    out = []
+    for r in el.findall(".//" + A + "r"):
+        rpr = r.find(A + "rPr")
+        if rpr is None:
+            continue
+        clr = rpr.find(A + "solidFill/" + A + "srgbClr")
+        if clr is None or not clr.get("val"):
+            continue  # 主题/方案色不在 v1 范围（局限已在文首声明）
+        run_color = clr.get("val")
+        try:
+            ratio = _contrast(run_color, fill)
+        except ValueError:
+            continue
+        try:
+            sz = int(rpr.get("sz")) if rpr.get("sz") else 0
+        except ValueError:
+            sz = 0
+        bold = rpr.get("b") in ("1", "true")
+        large = sz >= 1800 or (sz >= 1400 and bold)  # WCAG 大字：≥18pt 或 ≥14pt 粗体
+        min_ratio = 3.0 if large else 4.5
+        if ratio < min_ratio:
+            t = r.find(A + "t")
+            snippet = (t.text or "").strip()[:20] if t is not None else ""
+            out.append((run_color, fill, ratio, min_ratio, snippet))
+    return out
+
+
+def check_layout(path: str, verbose: bool = False) -> list:
+    """对 pptx 做布局/对比检查，返回问题列表（空 = 无可计算缺陷）。"""
+    problems = []
+
+    if not zipfile.is_zipfile(path):
+        return [f"不是合法的 zip/OOXML 包：{path}"]
+
+    with zipfile.ZipFile(path, "r") as zf:
+        names = zf.namelist()
+
+        # 画布尺寸（取不到则按 LAYOUT_WIDE 13.333"×7.5" 兜底）。
+        slide_w, slide_h = 13.333, 7.5
+        if "ppt/presentation.xml" in names:
+            try:
+                pres = ET.fromstring(zf.read("ppt/presentation.xml"))
+                sz = pres.find(P + "sldSz")
+                if sz is not None and sz.get("cx") and sz.get("cy"):
+                    slide_w = int(sz.get("cx")) / EMU_PER_INCH
+                    slide_h = int(sz.get("cy")) / EMU_PER_INCH
+            except (ET.ParseError, ValueError):
+                pass
+        slide_area = slide_w * slide_h
+
+        slide_names = sorted(
+            (n for n in names if re.fullmatch(r"ppt/slides/slide\d+\.xml", n)),
+            key=lambda n: int(re.search(r"(\d+)", n.rsplit("/", 1)[-1]).group(1)),
+        )
+
+        for sn in slide_names:
+            try:
+                root = ET.fromstring(zf.read(sn))
+            except ET.ParseError:
+                continue  # 良构由 opc_check 负责，这里跳过
+            tree = root.find(P + "cSld/" + P + "spTree")
+            if tree is None:
+                continue
+            label = sn.rsplit("/", 1)[-1]
+            rects = []  # 非连线、非满铺背景形状的 (x, y, w, h, name)
+
+            for el in list(tree):
+                if _local(el) not in ("sp", "cxnSp", "pic", "graphicFrame", "grpSp"):
+                    continue
+                box = _xfrm(el)
+
+                # ── A. 残桩/过短连线 ──
+                if _is_connector(el):
+                    if box is not None:
+                        length = math.hypot(box[2], box[3])
+                        if length < MIN_CONNECTOR_IN:
+                            problems.append(
+                                f'{label}: 残桩/过短连线「{_name(el)}」长度 {length:.3f}" '
+                                f'< {MIN_CONNECTOR_IN}"（端点几乎重合，疑似无连接的残桩箭头）'
+                            )
+                    continue  # 连线不参与叠加判定（穿过形状属正常）
+
+                # ── C. 低对比文字（仅 sp，限显式色对） ──
+                if _local(el) == "sp":
+                    fill = _shape_fill(el)
+                    if fill:
+                        for rc, fc, ratio, minr, snippet in _low_contrast_runs(el, fill):
+                            tip = f"「{snippet}…」" if snippet else ""
+                            problems.append(
+                                f"{label}: 低对比文字{tip}字色 {rc} / 底色 {fc} = "
+                                f"{ratio:.2f}:1 < {minr}:1（看不清；改字色或底色，用 inkFor(bg)）"
+                            )
+
+                # ── B. 收集叠加候选 rect ──
+                if box is not None:
+                    x, y, w, h = box
+                    if w * h >= BIG_BG_FRAC * slide_area:
+                        continue  # 满铺背景，不参与叠加
+                    rects.append((x, y, w, h, _name(el)))
+
+            # ── B. 两两包围盒比对 ──
+            for i in range(len(rects)):
+                ax, ay, aw, ah, an = rects[i]
+                for j in range(i + 1, len(rects)):
+                    bx, by, bw, bh, bn = rects[j]
+                    ix, iy = max(ax, bx), max(ay, by)
+                    ix2, iy2 = min(ax + aw, bx + bw), min(ay + ah, by + bh)
+                    if ix2 <= ix or iy2 <= iy:
+                        continue  # 不相交
+                    # 包含关系 = 正常（如卡片内文字），跳过
+                    a_in_b = ax >= bx and ay >= by and ax + aw <= bx + bw and ay + ah <= by + bh
+                    b_in_a = bx >= ax and by >= ay and bx + bw <= ax + aw and by + bh <= ay + ah
+                    if a_in_b or b_in_a:
+                        continue
+                    inter = (ix2 - ix) * (iy2 - iy)
+                    smaller = min(aw * ah, bw * bh)
+                    if inter > OVERLAP_MIN_AREA and inter > OVERLAP_MIN_FRAC * smaller:
+                        problems.append(
+                            f'{label}: 形状叠加「{an}」×「{bn}」重叠 {inter:.2f} in²'
+                            f"（约占较小形状 {inter / smaller * 100:.0f}%；拉开间距 ≥0.3\"）"
+                        )
+
+        if verbose and not problems:
+            print("PASSED 布局/对比检查：无残桩连线 / 无显著叠加 / 无低对比文字")
+
+    return problems
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="PPTX 布局/对比 确定性质量闸门（与 opc_check.py 互补，仅依赖标准库）"
+    )
+    parser.add_argument("file", help="要校验的 .pptx 文件")
+    parser.add_argument("-v", "--verbose", action="store_true", help="打印 PASSED 明细")
+    args = parser.parse_args()
+
+    problems = check_layout(args.file, verbose=args.verbose)
+    if problems:
+        print(f"布局/对比检查 FAILED —— {args.file} 存在 {len(problems)} 处问题：")
+        for p in problems:
+            print("  - " + p)
+        print(
+            "提示：对比用 deck_helpers 的 inkFor(bg)/assertReadable；"
+            "连线用 connect(from, to)；叠加拉开间距 ≥0.3\"。"
+            "（本检查不替代视觉 QA。）"
+        )
+        return 1
+
+    print(f"布局/对比检查 PASSED —— {args.file} 无可计算的布局/对比缺陷（视觉 QA 仍需进行）。")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/pptx/scripts/layout_lint_test.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+layout_lint_test.py —— layout_lint.py 的回归锚（stdlib unittest，仿 opc_check 测试风格）。
+
+手搓最小 OOXML（只含 presentation.xml + 一张 slide）分别命中 A/B/C 三类缺陷，
+外加一个「干净例」与一个「卡内文字（包含关系）不应误报」例，断言标记/通过。
+不依赖 PptxGenJS / python-pptx，只用标准库 zip 出最小包喂给 check_layout。
+
+运行：python skills/pptx/scripts/layout_lint_test.py
+"""
+
+import os
+import sys
+import tempfile
+import unittest
+import zipfile
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from layout_lint import check_layout  # noqa: E402
+
+EMU = 914400  # 每英寸
+
+
+def emu(inches):
+    return int(round(inches * EMU))
+
+
+PRESENTATION = (
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+    '<p:presentation xmlns:p="http://schemas.openxmlformats.org/presentationml/2006/main" '
+    'xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main">'
+    '<p:sldSz cx="12192000" cy="6858000" type="screen16x9"/>'
+    '</p:presentation>'
+)
+
+
+def filled_text_sp(x, y, w, h, fill, text_color, text="文字", sz=2800, bold=True, name="Box"):
+    """带显式 solidFill + 显式字色文字 run 的矩形 sp。"""
+    bold_attr = ' b="1"' if bold else ""  # 别在 f-string 表达式里写反斜杠（Py<3.12 报错）
+    return (
+        f'<p:sp><p:nvSpPr><p:cNvPr id="2" name="{name}"/><p:cNvSpPr/><p:nvPr/></p:nvSpPr>'
+        f'<p:spPr><a:xfrm><a:off x="{emu(x)}" y="{emu(y)}"/>'
+        f'<a:ext cx="{emu(w)}" cy="{emu(h)}"/></a:xfrm>'
+        f'<a:prstGeom prst="rect"><a:avLst/></a:prstGeom>'
+        f'<a:solidFill><a:srgbClr val="{fill}"/></a:solidFill></p:spPr>'
+        f'<p:txBody><a:bodyPr/><a:p><a:r>'
+        f'<a:rPr lang="zh-CN" sz="{sz}"{bold_attr}>'
+        f'<a:solidFill><a:srgbClr val="{text_color}"/></a:solidFill></a:rPr>'
+        f'<a:t>{text}</a:t></a:r></a:p></p:txBody></p:sp>'
+    )
+
+
+def plain_rect_sp(x, y, w, h, name="Plain"):
+    """无填充、无文字的矩形（纯叠加候选）。"""
+    return (
+        f'<p:sp><p:nvSpPr><p:cNvPr id="9" name="{name}"/><p:cNvSpPr/><p:nvPr/></p:nvSpPr>'
+        f'<p:spPr><a:xfrm><a:off x="{emu(x)}" y="{emu(y)}"/>'
+        f'<a:ext cx="{emu(w)}" cy="{emu(h)}"/></a:xfrm>'
+        f'<a:prstGeom prst="rect"><a:avLst/></a:prstGeom></p:spPr>'
+        f'<p:txBody><a:bodyPr/><a:p/></p:txBody></p:sp>'
+    )
+
+
+def connector(x, y, w, h, name="Conn"):
+    return (
+        f'<p:cxnSp><p:nvCxnSpPr><p:cNvPr id="5" name="{name}"/><p:cNvCxnSpPr/><p:nvPr/></p:nvCxnSpPr>'
+        f'<p:spPr><a:xfrm><a:off x="{emu(x)}" y="{emu(y)}"/>'
+        f'<a:ext cx="{emu(w)}" cy="{emu(h)}"/></a:xfrm>'
+        f'<a:prstGeom prst="straightConnector1"><a:avLst/></a:prstGeom></p:spPr></p:cxnSp>'
+    )
+
+
+def slide_xml(*shapes):
+    body = "".join(shapes)
+    return (
+        '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+        '<p:sld xmlns:p="http://schemas.openxmlformats.org/presentationml/2006/main" '
+        'xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main">'
+        f'<p:cSld><p:spTree>{body}</p:spTree></p:cSld></p:sld>'
+    )
+
+
+def build_pptx(slide_body):
+    fd, path = tempfile.mkstemp(suffix=".pptx")
+    os.close(fd)
+    with zipfile.ZipFile(path, "w", zipfile.ZIP_DEFLATED) as z:
+        z.writestr("ppt/presentation.xml", PRESENTATION)
+        z.writestr("ppt/slides/slide1.xml", slide_body)
+    return path
+
+
+class LayoutLintTest(unittest.TestCase):
+    def setUp(self):
+        self._paths = []
+
+    def tearDown(self):
+        for p in self._paths:
+            try:
+                os.remove(p)
+            except OSError:
+                pass
+
+    def _run(self, slide_body):
+        path = build_pptx(slide_body)
+        self._paths.append(path)
+        return check_layout(path)
+
+    def test_clean_deck_passes(self):
+        # 两个不重叠、高对比的填充框 + 一条正常长度连线 → 零问题。
+        problems = self._run(
+            slide_xml(
+                filled_text_sp(1, 1, 3, 1.2, "F8FAFC", "0F172A", name="A"),   # 深字浅底
+                filled_text_sp(6, 1, 3, 1.2, "1E2761", "FFFFFF", name="B"),   # 白字深底
+                connector(4.1, 1.6, 1.8, 0.0, name="A→B"),                    # 1.8" 长，正常
+            )
+        )
+        self.assertEqual(problems, [], f"干净例不应报问题：{problems}")
+
+    def test_short_connector_flagged(self):
+        problems = self._run(slide_xml(connector(2, 2, 0.05, 0.0, name="Stub")))
+        self.assertTrue(any("残桩" in p or "过短连线" in p for p in problems), problems)
+
+    def test_overlap_flagged(self):
+        # A=(1,1,3,3) 与 B=(3,3,3,3) 重叠 1in²，互不包含 → 标记。
+        problems = self._run(
+            slide_xml(plain_rect_sp(1, 1, 3, 3, name="A"), plain_rect_sp(3, 3, 3, 3, name="B"))
+        )
+        self.assertTrue(any("叠加" in p for p in problems), problems)
+
+    def test_low_contrast_flagged(self):
+        # 深底(1E2761) + 深字(0F172A) ≈ 1.3:1 < 3 → 标记。
+        problems = self._run(
+            slide_xml(filled_text_sp(1, 1, 4, 1.5, "1E2761", "0F172A", text="看不清的标题"))
+        )
+        self.assertTrue(any("低对比" in p for p in problems), problems)
+
+    def test_containment_not_flagged_as_overlap(self):
+        # 小文字框完全落在大卡片内（= 卡内文字），不应被当成叠加。
+        problems = self._run(
+            slide_xml(
+                plain_rect_sp(1, 1, 5, 3, name="Card"),
+                filled_text_sp(1.3, 1.3, 3, 1, "F8FAFC", "0F172A", name="Label"),
+            )
+        )
+        self.assertFalse(any("叠加" in p for p in problems), problems)
+
+    def test_full_bleed_background_not_overlap(self):
+        # 满铺背景(0,0,13.333,7.5) 不参与叠加，即便上面压着内容框也不报叠加。
+        problems = self._run(
+            slide_xml(
+                plain_rect_sp(0, 0, 13.333, 7.5, name="BG"),
+                filled_text_sp(1, 1, 4, 1.2, "F8FAFC", "0F172A", name="Content"),
+            )
+        )
+        self.assertFalse(any("叠加" in p for p in problems), problems)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)