Skip to content

yzsp-studio/mediakit-shared-suite / ppt

飞书幻灯片:创建和编辑幻灯片。创建演示文稿、读取幻灯片内容、管理幻灯片页面(创建、删除、读取、局部替换)。当用户需要创建或编辑幻灯片、读取或修改单个页面时使用。

FileKindSize
SKILL.mdskill md40.1 KB
references/cli/lark-slides-add-slide.mdmarkdown7.3 KB
references/cli/lark-slides-create.mdmarkdown10.5 KB
references/cli/lark-slides-delete-slide.mdmarkdown2.7 KB
references/cli/lark-slides-history.mdmarkdown6.9 KB
references/cli/lark-slides-media-upload.mdmarkdown5.5 KB
references/cli/lark-slides-replace-slide.mdmarkdown14.8 KB
references/cli/lark-slides-screenshot.mdmarkdown5.4 KB
references/cli/lark-slides-update-slide.mdmarkdown11.6 KB
references/cli/lark-slides-xml-presentation-slide-get.mdmarkdown3.6 KB
references/cli/lark-slides-xml-presentation-slide-replace.mdmarkdown7.3 KB
references/cli/lark-slides-xml-presentations-get.mdmarkdown9.4 KB
references/refine/academic-research.mdmarkdown7.3 KB
references/refine/brand-storytelling.mdmarkdown8.3 KB
references/refine/business-pitch.mdmarkdown8.0 KB
references/refine/business-review.mdmarkdown8.3 KB
references/refine/fallback.mdmarkdown7.8 KB
references/refine/learning-and-training.mdmarkdown8.5 KB
references/refine/strategy-and-analysis.mdmarkdown8.1 KB
references/refine/technical-presentation.mdmarkdown8.1 KB
references/style/academic-research.mdmarkdown18.5 KB
references/style/brand-storytelling.mdmarkdown34.1 KB
references/style/business-pitch.mdmarkdown12.2 KB
references/style/business-review.mdmarkdown19.6 KB
references/style/fallback.mdmarkdown8.7 KB
references/style/learning-and-training.mdmarkdown20.8 KB
references/style/slide-taxonomy.mdmarkdown13.6 KB
references/style/strategy-and-analysis.mdmarkdown8.4 KB
references/style/technical-presentation.mdmarkdown15.6 KB
references/workflow/error-handling.mdmarkdown9.6 KB
references/workflow/local-compat.mdmarkdown5.3 KB
references/workflow/slides-editing.mdmarkdown34.6 KB
references/workflow/template-editing-main.mdmarkdown36.6 KB
references/workflow/template-editing-organizer.mdmarkdown24.4 KB
references/workflow/validation-visual.mdmarkdown7.1 KB
references/workflow/validation-xml.mdmarkdown31.9 KB
references/workflow/windows-compat.mdmarkdown6.3 KB
references/xml/fonts.mdmarkdown7.6 KB
references/xml/iconpark-index.jsonconfig729.4 KB
references/xml/iconpark.mdmarkdown2.1 KB
references/xml/slides_chart_demo.xmlconfig69.2 KB
references/xml/slides_xml_schema_definition.xmlconfig228.6 KB
references/xml/xml-schema-quick-ref.mdmarkdown34.7 KB
scripts/atomize_svg_to_slide.pyscript80.2 KB
scripts/atomize_svg_to_slide_test.pyscript5.5 KB
scripts/color_contrast_check.pyscript36.4 KB
scripts/color_contrast_check_test.pyscript28.9 KB
scripts/embed_svg_validator.pyscript56.7 KB
scripts/embed_svg_validator_test.pyscript18.2 KB
scripts/gen_svg_charts.pyscript48.8 KB
scripts/gen_svg_relations.pyscript42.6 KB
scripts/iconpark_tool.pyscript12.1 KB
scripts/iconpark_tool_test.pyscript7.7 KB
scripts/lint_inspect.pyscript23.3 KB
scripts/lint_inspect_test.pyscript13.2 KB
scripts/parse_template.pyscript114.0 KB
scripts/purge_deck.pyscript11.4 KB
scripts/safe_update_slide.pyscript21.0 KB
scripts/svg_lib/_baseline.pyscript50.9 KB
scripts/svg_lib/_boxplot_skin.pyscript21.5 KB
scripts/svg_lib/_common.pyscript46.6 KB
scripts/svg_lib/charts/__init__.pyscript853 B
scripts/svg_lib/charts/_shared.pyscript8.6 KB
scripts/svg_lib/charts/boxplot.pyscript26.9 KB
scripts/svg_lib/charts/calheat.pyscript45.7 KB
scripts/svg_lib/charts/candle.pyscript39.1 KB
scripts/svg_lib/charts/event_timeline.pyscript66.6 KB
scripts/svg_lib/charts/funnel.pyscript54.6 KB
scripts/svg_lib/charts/gantt.pyscript53.6 KB
scripts/svg_lib/charts/marimekko.pyscript26.9 KB
scripts/svg_lib/charts/matrix_heat.pyscript52.3 KB
scripts/svg_lib/charts/nested_donut.pyscript61.2 KB
scripts/svg_lib/charts/percent_grid.pyscript38.6 KB
scripts/svg_lib/charts/pyramid.pyscript44.8 KB
scripts/svg_lib/charts/quadrant.pyscript76.8 KB
scripts/svg_lib/charts/ridge.pyscript28.7 KB
scripts/svg_lib/charts/sankey.pyscript48.9 KB
scripts/svg_lib/charts/violin.pyscript37.2 KB
scripts/svg_lib/charts/waterfall.pyscript52.3 KB
scripts/svg_lib/svg_palettes.pyscript52.7 KB
scripts/svg_relation_lib/__init__.pyscript2.0 KB
scripts/svg_relation_lib/_viewbox.pyscript10.5 KB
scripts/svg_relation_lib/attributes/__init__.pyscript1.4 KB
scripts/svg_relation_lib/attributes/_resolver.pyscript1.3 KB
scripts/svg_relation_lib/attributes/_test_attrs.pyscript11.8 KB
scripts/svg_relation_lib/attributes/_test_pipeline.pyscript12.5 KB
scripts/svg_relation_lib/attributes/apply.pyscript5.3 KB
scripts/svg_relation_lib/attributes/category.pyscript1.5 KB
scripts/svg_relation_lib/attributes/confidence.pyscript1.5 KB
scripts/svg_relation_lib/attributes/directional.pyscript1.4 KB
scripts/svg_relation_lib/attributes/highlight.pyscript1.6 KB
scripts/svg_relation_lib/attributes/signed.pyscript1.7 KB
scripts/svg_relation_lib/attributes/size.pyscript1.3 KB
scripts/svg_relation_lib/attributes/status.pyscript2.1 KB
scripts/svg_relation_lib/attributes/temporal.pyscript2.5 KB
scripts/svg_relation_lib/attributes/typed.pyscript1.6 KB
scripts/svg_relation_lib/attributes/weighted.pyscript1.4 KB
scripts/svg_relation_lib/chrome.pyscript9.1 KB
scripts/svg_relation_lib/engine.pyscript11.5 KB
scripts/svg_relation_lib/layouts/__init__.pyscript383 B
scripts/svg_relation_lib/layouts/bloom_v2.pyscript37.9 KB
scripts/svg_relation_lib/layouts/c4_container_v2.pyscript35.1 KB
scripts/svg_relation_lib/layouts/column_stack.pyscript5.3 KB
scripts/svg_relation_lib/layouts/fishbone_v2.pyscript38.1 KB
scripts/svg_relation_lib/layouts/hub_fanout.pyscript15.5 KB
scripts/svg_relation_lib/layouts/osi_stack_v2.pyscript32.8 KB
scripts/svg_relation_lib/layouts/vertical_chain.pyscript4.5 KB
scripts/svg_relation_lib/palettes.pyscript8.9 KB
scripts/svg_relation_lib/palettes_ext.pyscript17.2 KB
scripts/svg_relation_lib/presets/__init__.pyscript297 B
scripts/svg_relation_lib/presets/_chrome.pyscript1.6 KB
scripts/svg_relation_lib/presets/hero_embed_01_AL_fishbone_v2.pyscript21.7 KB
scripts/svg_relation_lib/presets/hero_embed_02_PY_pmf_v2.pyscript16.5 KB
scripts/svg_relation_lib/presets/hero_embed_03_BL_bloom_v2.pyscript44.0 KB
scripts/svg_relation_lib/presets/hero_embed_04_J1_osi_v2.pyscript46.2 KB
scripts/svg_relation_lib/presets/hero_embed_05_MP_mindmap_v2.pyscript28.6 KB
scripts/svg_relation_lib/presets/hero_embed_07_TX_taxonomy_v2.pyscript64.7 KB
scripts/svg_relation_lib/presets/hero_embed_08_KP_kpi_v2.pyscript79.5 KB
scripts/svg_relation_lib/presets/hero_embed_09_E2_5why_v2.pyscript39.4 KB
scripts/svg_relation_lib/presets/hero_embed_10_CS_c4_v2.pyscript173.5 KB
scripts/svg_relation_lib/presets/hero_embed_32_CU2_curriculum_v2.pyscript66.1 KB
scripts/svg_relation_lib/presets/hero_embed_49_FT_faulttree_v2.pyscript69.4 KB
scripts/svg_relation_lib/render.pyscript28.0 KB
scripts/svg_relation_lib/render/render_bl_bloom_tests.pyscript8.2 KB
scripts/svg_relation_lib/render/render_cu2_curriculum_variants.pyscript19.6 KB
scripts/svg_relation_lib/render/render_e2_5why_variants.pyscript8.9 KB
scripts/svg_relation_lib/render/render_ft_faulttree_variants.pyscript12.8 KB
scripts/svg_relation_lib/render/render_j1_osi_tests.pyscript12.0 KB
scripts/svg_relation_lib/render/render_py_pmf_variants.pyscript13.0 KB
scripts/svg_relation_lib/render/render_tx_taxonomy_variants.pyscript17.6 KB
scripts/svg_relation_lib/schemas/__init__.pyscript280 B
scripts/svg_relation_lib/schemas/graph.pyscript1.5 KB
scripts/svg_relation_lib/schemas/tree.pyscript11.2 KB
scripts/svg_relation_lib/skeletons.pyscript15.3 KB
scripts/svg_relation_lib/skins/__init__.pyscript1.3 KB
scripts/svg_relation_lib/skins/_base.pyscript10.0 KB
scripts/svg_relation_lib/skins/annual_report_ivory.pyscript9.1 KB
scripts/svg_relation_lib/skins/art_deco.pyscript27.1 KB
scripts/svg_relation_lib/skins/arxiv_clean.pyscript9.1 KB
scripts/svg_relation_lib/skins/arxiv_pastel.pyscript9.0 KB
scripts/svg_relation_lib/skins/bain_scarlet.pyscript9.0 KB
scripts/svg_relation_lib/skins/bauhaus_primary.pyscript9.2 KB
scripts/svg_relation_lib/skins/bcg_forest.pyscript9.0 KB
scripts/svg_relation_lib/skins/bloomberg_amber.pyscript9.2 KB
scripts/svg_relation_lib/skins/blueprint_grid.pyscript9.6 KB
scripts/svg_relation_lib/skins/boardroom_navy.pyscript29.9 KB
scripts/svg_relation_lib/skins/chalkboard_slate.pyscript9.0 KB
scripts/svg_relation_lib/skins/coursera_indigo.pyscript9.0 KB
scripts/svg_relation_lib/skins/couture_noir.pyscript33.0 KB
scripts/svg_relation_lib/skins/deloitte_lime.pyscript8.9 KB
scripts/svg_relation_lib/skins/duolingo_cream.pyscript20.4 KB
scripts/svg_relation_lib/skins/editorial.pyscript6.4 KB
scripts/svg_relation_lib/skins/editorial_atelier.pyscript60.7 KB
scripts/svg_relation_lib/skins/editorial_atelier_lark.pyscript19.6 KB
scripts/svg_relation_lib/skins/editorial_atelier_tokens.mdmarkdown13.6 KB
scripts/svg_relation_lib/skins/engineering_kraft.pyscript9.0 KB
scripts/svg_relation_lib/skins/goldman_slate.pyscript9.1 KB
scripts/svg_relation_lib/skins/hermes_orange.pyscript9.0 KB
scripts/svg_relation_lib/skins/ib_editorial.pyscript28.9 KB
scripts/svg_relation_lib/skins/journal_ivory.pyscript29.7 KB
scripts/svg_relation_lib/skins/khan_teal.pyscript9.0 KB
scripts/svg_relation_lib/skins/luxury_manual.pyscript20.4 KB
scripts/svg_relation_lib/skins/manuscript_sepia.pyscript9.1 KB
scripts/svg_relation_lib/skins/mbb_consulting.pyscript32.8 KB
scripts/svg_relation_lib/skins/medical_chart.pyscript22.6 KB
scripts/svg_relation_lib/skins/monocle_ecru.pyscript9.1 KB
scripts/svg_relation_lib/skins/napkin.pyscript6.3 KB
scripts/svg_relation_lib/skins/notebook_grid.pyscript9.2 KB
scripts/svg_relation_lib/skins/oxford_indigo.pyscript9.1 KB
scripts/svg_relation_lib/skins/pitch_bauhaus.pyscript9.1 KB
scripts/svg_relation_lib/skins/pitch_ivory.pyscript18.7 KB
scripts/svg_relation_lib/skins/pitch_midnight.pyscript9.1 KB
scripts/svg_relation_lib/skins/pitch_neon.pyscript32.2 KB
scripts/svg_relation_lib/skins/pitch_sunset.pyscript9.1 KB
scripts/svg_relation_lib/skins/registry.pyscript8.5 KB
scripts/svg_relation_lib/skins/riso_duotone.pyscript9.0 KB
scripts/svg_relation_lib/skins/roland_terracotta.pyscript9.0 KB
scripts/svg_relation_lib/skins/saas_product.pyscript38.6 KB
scripts/svg_relation_lib/skins/strategic_briefing.pyscript31.3 KB
scripts/svg_relation_lib/skins/swiss_grid.pyscript8.9 KB
scripts/svg_relation_lib/skins/symposium_ash.pyscript9.2 KB
scripts/svg_relation_lib/skins/technical_whitepaper.pyscript23.7 KB
scripts/svg_relation_lib/skins/terminal_matrix.pyscript9.2 KB
scripts/svg_relation_lib/skins/wabi_sabi.pyscript9.3 KB
scripts/svg_relation_lib/skins/wsj_broadsheet.pyscript9.1 KB
scripts/sxsd_validator.pyscript38.4 KB
scripts/template_lint_all.pyscript48.1 KB
scripts/xml_inspect.pyscript19.8 KB
scripts/xml_inspect_test.pyscript17.7 KB
scripts/xml_lint.pyscript226.8 KB
scripts/xml_lint_test.pyscript346.9 KB

scripts/template_lint_all.py

View on GitHub
#!/usr/bin/env python3
"""template_lint_all.py — template-editing 分支专用的聚合 lint 入口。

一次跑三项检查:
1. xml_lint.py                XML schema / 几何 / 溢出 / 重叠 / ID 唯一性等通用检查
2. color_contrast_check.py    文字靠色(默认阈值 2.25)
3. 占位符 diff                source-slides/slide-NN.xml 与 authored 相同文本片段 → warn

Step 5 每页写入前必跑:
    python3 template_lint_all.py \\
      --authored <authoring/slide-NN.xml> \\
      --source <source-slides/slide-NN.xml> \\
      --skill-root <SKILL_ROOT>

判定:任一子项 status=blocked(xml_lint 有 error / 靠色有 FAIL)→ overall status=blocked,
禁止 +add-slide / +update-slide。占位符 diff 只产 warn,不阻断写入,但要 MainAgent 判断是否漏改。

stdout:JSON envelope,含 summary + 三项子结果 + 占位符 diff 详情。
"""
from __future__ import annotations

import argparse
import json
import re
import subprocess
import sys
import xml.etree.ElementTree as ET
from pathlib import Path


# 占位符黑名单(命中就是 warn,且 message 带明确"疑似占位符"标签)
PLACEHOLDER_BLACKLIST = [
    "添加标题", "点击输入", "点击此处", "占位", "占位符",
    "示例文本", "示例文字", "示例内容", "示例",
    "Lorem ipsum", "Lorem", "Click to add", "Add title",
    "Add subtitle", "Add text", "Placeholder", "Sample text",
    "asdas", "想搞设计", "论文就是用来",
    "亮亮图文", "淘宝",
    "副标题",
]

# 模板骨架 label 白名单(命中就降级为 info、不报 warn;这些是模板设计的一部分保留合理)
SKELETON_WHITELIST = {
    # 通用骨架 label
    "目录", "章节", "内容", "标题", "副标题内容",
    "页脚", "页眉", "关键词", "备注",
    # 常见英文对照
    "CONTENTS", "OUTLINE", "AGENDA", "CHAPTER", "SECTION",
    "TITLE", "SUBTITLE", "OVERVIEW", "INTRODUCTION", "CONCLUSION",
    "APPENDIX", "REFERENCE", "REFERENCES", "THANKS", "THANK YOU",
    "BACKGROUND", "METHOD", "METHODS", "RESULTS", "DISCUSSION",
    # 通用装饰词(长度 >=4 但没意义)
    "SLIDE", "PAGE", "PART", "STEP",
}

# 中文常见极短装饰(<4 会被长度过滤掉,这里覆盖恰好 4 字的)
SKELETON_WHITELIST |= {"研究背景", "研究方法", "研究框架", "研究结论"}


def _extract_texts(xml_path: Path) -> list[str]:
    """从 XML 里抽出所有 <a:t> / <t> / text() 文本,做基本清洗后返回。"""
    if not xml_path.exists():
        return []
    try:
        tree = ET.parse(str(xml_path))
    except ET.ParseError:
        return []
    root = tree.getroot()
    texts: list[str] = []
    for elem in root.iter():
        tag = elem.tag.rsplit("}", 1)[-1]
        if tag == "t" and elem.text:
            t = elem.text.strip()
            if t:
                texts.append(t)
    return texts


def _is_meaningful_text(t: str) -> bool:
    """判断文本是否有意义(有内容差异检查的价值)。"""
    if len(t) < 4:
        return False
    # 纯数字
    if re.fullmatch(r"[\d\s.,%]+", t):
        return False
    # 纯符号
    if re.fullmatch(r"[\W_]+", t):
        return False
    return True


def _classify_common_text(t: str) -> tuple[str, str]:
    """把 source/authored 都出现的文本分类,返回 (severity, reason).

    severity ∈ {"info", "warn"}
    reason 描述为什么这样判定。
    """
    # 黑名单 → warn
    for kw in PLACEHOLDER_BLACKLIST:
        if kw in t:
            return "warn", f"疑似占位符(命中黑名单词 '{kw}')——MainAgent 忘了替换成实际内容"
    # 白名单精确匹配 → info(不报)
    if t in SKELETON_WHITELIST or t.upper() in SKELETON_WHITELIST:
        return "info", "模板骨架 label,保留合理"
    # 其他 → warn
    return "warn", "该文本在模板 source 和 authored 中都出现且未修改——可能是漏改的原文,也可能是模板设计要保留的部分,请 MainAgent 判断"


def check_placeholders(source_xml: Path, authored_xml: Path) -> dict:
    """做 source vs authored 的相同文本 diff,返回 warning 清单。"""
    source_texts = set(_extract_texts(source_xml))
    authored_texts = _extract_texts(authored_xml)

    common: list[dict] = []
    seen: set[str] = set()
    for t in authored_texts:
        if t in seen:
            continue
        if t not in source_texts:
            continue
        if not _is_meaningful_text(t):
            continue
        seen.add(t)
        severity, reason = _classify_common_text(t)
        common.append({"text": t, "severity": severity, "reason": reason})

    warn_count = sum(1 for c in common if c["severity"] == "warn")
    info_count = sum(1 for c in common if c["severity"] == "info")

    return {
        "checked": True,
        "warning_count": warn_count,
        "info_count": info_count,
        "issues": common,
        "note": (
            "warn = source-slides 和 authoring 中都出现且未修改的文本,可能是漏改的占位内容。"
            "如果确实是模板骨架 label(如'目录'、'CONTENTS'),可忽略;否则 MainAgent 必须去 Edit authoring 改掉。"
        ),
    }


def _run_subscript(script_path: Path, args: list[str], timeout: int = 60) -> dict:
    """跑一个子脚本,返回 {ok, stdout_json, stderr, returncode}."""
    cmd = ["python3", str(script_path)] + args
    try:
        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
    except subprocess.TimeoutExpired:
        return {"ok": False, "error": f"timeout after {timeout}s"}
    except FileNotFoundError as e:
        return {"ok": False, "error": f"script not found: {e}"}

    out = proc.stdout.strip()
    idx = out.find("{")
    parsed = None
    if idx >= 0:
        try:
            parsed = json.loads(out[idx:])
        except json.JSONDecodeError:
            parsed = None
    # ok 判定收紧:必须 returncode=0 且 stdout 是合法 JSON(避免 rc!=0 时只要有一段 '{' 就当成功)
    ok = (proc.returncode == 0) and (parsed is not None)
    return {
        "ok": ok,
        "returncode": proc.returncode,
        "stdout_json": parsed,
        "stderr": proc.stderr[:500],
    }


def check_overflow_covers_below(authored_xml: Path, xml_lint_json: dict | None) -> dict:
    """检查"文本 A 溢出后是否几何覆盖同页其他 shape B"。

    两条路径:
    (1) xml_lint 已经报了 text_overflows_container 的场景——直接从 related_objects 拿 bbox 和 overflow.bottom
    (2) 兜底:任何含文本的 shape(含 rect 塞正文这种),自己估算 estimated_height,
        与 declared height 对比。这条路径覆盖 xml_lint 漏掉的场景。

    返回 {checked, fail_count, issues}。fail_count > 0 时 status=blocked。
    """
    # 从 authored XML 抽同页所有 shape 的 bbox
    try:
        tree = ET.parse(str(authored_xml))
        root = tree.getroot()
    except ET.ParseError:
        return {"checked": False, "reason": "authored xml parse failed", "fail_count": 0, "issues": []}

    def local(tag: str) -> str:
        return tag.rsplit("}", 1)[-1]

    # 找到每一页(如果整份 XML 有 <presentation><slide>...)
    slides_nodes: list[ET.Element] = []
    root_local = local(root.tag)
    if root_local == "slide":
        slides_nodes = [root]
    elif root_local == "presentation":
        for child in root:
            if local(child.tag) == "slide":
                slides_nodes.append(child)
    else:
        slides_nodes = [root]

    issues: list[dict] = []

    for slide_idx, slide in enumerate(slides_nodes, start=1):
        # 抽本页所有 shape/img
        page_shapes: list[dict] = []
        for shp in slide.iter():
            if local(shp.tag) not in ("shape", "img"):
                continue
            try:
                x = float(shp.get("topLeftX") or shp.get("left") or 0)
                y = float(shp.get("topLeftY") or shp.get("top") or 0)
                w = float(shp.get("width") or 0)
                h = float(shp.get("height") or 0)
            except (TypeError, ValueError):
                continue
            if w <= 0 or h <= 0:
                continue
            sid = shp.get("id")
            # 抽文本 + font size(取第一个 span 或 content 的 fontSize)
            texts: list[str] = []
            font_sizes: list[float] = []
            for span in shp.iter():
                if local(span.tag) in ("span", "t") and (span.text or "").strip():
                    texts.append(span.text.strip())
                fs = span.get("fontSize")
                if fs:
                    try:
                        font_sizes.append(float(fs))
                    except (TypeError, ValueError):
                        pass
            text = "".join(texts)
            # 取"最常出现"或第一个非零 fontSize
            font_size = font_sizes[0] if font_sizes else 14.0
            # 估算行高(fontSize * 1.4)
            line_h = font_size * 1.4
            # 简易估算文本占的行数(按字符宽度 ~ 0.6 * fontSize,中文按 1 * fontSize)
            def _char_w(ch: str, fs: float) -> float:
                if '一' <= ch <= '鿿':  # 中日韩汉字
                    return fs * 1.0
                return fs * 0.55
            # 减去 padding
            avail_w = max(w - 14, 1)  # 左右各留 7 padding 估
            avail_h = max(h - 8, 1)   # 上下各留 4 padding 估
            if text:
                line_widths = 0.0
                lines = 1
                for ch in text:
                    cw = _char_w(ch, font_size)
                    if line_widths + cw > avail_w:
                        lines += 1
                        line_widths = cw
                    else:
                        line_widths += cw
                estimated_h = lines * line_h + 8  # + padding
            else:
                estimated_h = 0.0

            page_shapes.append({
                "id": sid,
                "type": shp.get("type") or local(shp.tag),
                "x": x, "y": y, "w": w, "h": h,
                "x_end": x + w, "y_end": y + h,
                "text": text[:80],
                "font_size": font_size,
                "estimated_h": estimated_h,
                "overflow_bottom": max(0.0, estimated_h - h),  # 兜底估算
            })

        # 从 xml_lint 的 slide 结果里拿"确定溢出"的框(更精确)
        xml_lint_overflows: dict[str, float] = {}  # id -> bottom_over
        if xml_lint_json and xml_lint_json.get("slides"):
            slides_from_lint = xml_lint_json["slides"]
            if slide_idx - 1 < len(slides_from_lint):
                for err in slides_from_lint[slide_idx - 1].get("errors", []):
                    if err.get("code") != "text_overflows_container":
                        continue
                    overflow = err.get("overflow") or err.get("measurement", {}).get("overflow") or {}
                    bottom_over = overflow.get("bottom", 0) or 0
                    if bottom_over <= 0:
                        continue
                    related = err.get("related_objects") or []
                    if related:
                        rid = related[0].get("element_id")
                        if rid:
                            xml_lint_overflows[rid] = max(xml_lint_overflows.get(rid, 0), bottom_over)

        # 对每个溢出的框(xml_lint 精确报的 OR 兜底估算的),与同页其他 shape 做相交
        for a in page_shapes:
            if not a.get("id"):
                continue  # 无 id 的 shape 跳过 · 避免全部聚合到 None key 误判
            # 兜底估算与 xml_lint 报的取较大
            precise = xml_lint_overflows.get(a["id"], 0)
            over = max(precise, a["overflow_bottom"])
            if over <= 2:  # <=2px 忽略
                continue
            a_y_real_end = a["y_end"] + over
            for b in page_shapes:
                if b["id"] == a["id"]:
                    continue
                # 水平必须相交
                if b["x_end"] <= a["x"] or b["x"] >= a["x_end"]:
                    continue
                # b 起点必须在 a 声明范围之下(不然是原生几何重叠,xml_lint 的 bbox_overlap 会报)
                if b["y"] < a["y_end"]:
                    continue
                # b 起点必须在 a 实际结束之上
                if b["y"] >= a_y_real_end:
                    continue
                # 纵向相交
                ovl_top = max(a["y_end"], b["y"])
                ovl_bot = min(a_y_real_end, b["y_end"])
                ovl_h = ovl_bot - ovl_top
                if ovl_h <= 2:
                    continue
                issues.append({
                    "severity": "fail",
                    "code": "text_overflow_covers_below",
                    "slide_number": slide_idx,
                    "overflowing_shape": a["id"],
                    "overflowing_shape_type": a["type"],
                    "overflowing_text": a["text"],
                    "covered_shape": b["id"],
                    "covered_shape_type": b["type"],
                    "covered_text": b["text"],
                    "overflow_bottom_px": round(over, 1),
                    "vertical_overlap_px": round(ovl_h, 1),
                    "source": "xml_lint" if precise > 0 else "heuristic_estimate",
                    "reason": (
                        f"slide {slide_idx} 文本框 {a['id']}(type={a['type']}, 高 {a['h']:.0f}px)"
                        f"估算需要 {a['h'] + over:.0f}px 才装得下'{a['text'][:30]}...',"
                        f"溢出约 {over:.0f}px 向下覆盖到 {b['id']}(type={b['type']}, "
                        f"内容'{b['text'][:20]}...')——两段文字会在渲染时挤成一团。"
                        f"修复:加大 {a['id']} 的 height、缩短文本、或把 {b['id']} 往下挪至少 {ovl_h:.0f}px。"
                    ),
                })

    return {
        "checked": True,
        "fail_count": len(issues),
        "issues": issues,
        "note": (
            "text_overflow_covers_below = 文本 A 因为 estimated_height > declared_height 溢出容器,"
            "溢出部分向下覆盖到同页其他独立 shape B。特别处理 rect 类型塞正文的场景(xml_lint 的 "
            "text_overflows_container 不覆盖这种)。命中即 FAIL,必须修复才能写入。"
        ),
    }


def check_unexpected_wrapping(authored_xml: Path) -> dict:
    """检查"文本被强制换行到多行"——单行框但文本估算宽度超容器可用宽度。

    典型场景:模板里的封面/署名/单行 label 文本框,宽度是"刚好装下预期文本"设计的;
    MainAgent 复用时新文本长了 1-2 个字,或者忘算 bullet marginLeft/indent 吃掉的可用宽度,
    结果实际渲染时被强制换行,最后 1 个字断到下一行——视觉上很难看。

    xml_lint 的 text_may_overflow_shape 只在 wrap="false" 时才报;默认 wrap 允许多行时它不报,
    但这些"意外换行"通常也是不该发生的(模板设计意图就是单行)。

    严重度:warn(启发式估算有 ±15% 误差,不宜阻断)。
    """
    try:
        tree = ET.parse(str(authored_xml))
        root = tree.getroot()
    except ET.ParseError:
        return {"checked": False, "reason": "authored xml parse failed", "warning_count": 0, "issues": []}

    def local(tag: str) -> str:
        return tag.rsplit("}", 1)[-1]

    # 找每一页
    slides_nodes: list[ET.Element] = []
    root_local = local(root.tag)
    if root_local == "slide":
        slides_nodes = [root]
    elif root_local == "presentation":
        for child in root:
            if local(child.tag) == "slide":
                slides_nodes.append(child)
    else:
        slides_nodes = [root]

    def _char_w(ch: str, fs: float) -> float:
        """启发式字宽估算(相对 fontSize)。"""
        code = ord(ch)
        # CJK 汉字(U+4E00-U+9FFF)
        if 0x4E00 <= code <= 0x9FFF:
            return fs * 1.0
        # 全角标点(U+3000-U+303F、U+FF00-U+FFEF 大部分)
        if 0x3000 <= code <= 0x303F or (0xFF01 <= code <= 0xFF5E and code >= 0xFF01):
            return fs * 1.0
        # 半角标点
        if ch in ".,;:!?()[]{}<>-'\"`~ ":
            return fs * 0.35
        # 数字
        if ch.isdigit():
            return fs * 0.55
        # 英文字母 / 其他
        return fs * 0.55

    def _estimate_line_widths(text: str, fs: float) -> float:
        """返回单行整体宽度(不考虑换行)。"""
        return sum(_char_w(ch, fs) for ch in text)

    issues: list[dict] = []

    for slide_idx, slide in enumerate(slides_nodes, start=1):
        for shp in slide.iter():
            if local(shp.tag) != "shape":
                continue
            stype = shp.get("type")
            if stype not in ("text",):
                # 只关心 type="text" shape;rect 塞正文由 overflow_covers_below 处理
                continue
            try:
                w = float(shp.get("width") or 0)
                h = float(shp.get("height") or 0)
            except (TypeError, ValueError):
                continue
            if w <= 0 or h <= 0:
                continue
            sid = shp.get("id")

            # 找 content 节点抽 padding / autoFit / wrap
            content = None
            for c in shp:
                if local(c.tag) == "content":
                    content = c; break
            if content is None:
                continue
            wrap = content.get("wrap")
            if wrap == "false":
                # wrap=false 场景 xml_lint 已经在管
                continue
            try:
                pad_left = float(content.get("paddingLeft") or 0)
                pad_right = float(content.get("paddingRight") or 0)
                pad_top = float(content.get("paddingTop") or 0)
                pad_bottom = float(content.get("paddingBottom") or 0)
            except (TypeError, ValueError):
                pad_left = pad_right = pad_top = pad_bottom = 0

            # 遍历 <p> 节点抽 marginLeft / indent + 文本 + fontSize
            # 每个 <p> 是独立段落,独立估算
            paragraphs: list[dict] = []
            for p in content.iter():
                if local(p.tag) != "p":
                    continue
                try:
                    p_margin_left = float(p.get("marginLeft") or 0)
                    p_indent = float(p.get("indent") or 0)
                except (TypeError, ValueError):
                    p_margin_left = p_indent = 0
                p_text = ""
                p_fs = None
                for sp in p.iter():
                    lname = local(sp.tag)
                    if lname == "span" and sp.text:
                        p_text += sp.text
                        if p_fs is None:
                            try:
                                p_fs = float(sp.get("fontSize") or 0) or None
                            except (TypeError, ValueError):
                                pass
                if not p_text.strip():
                    continue
                # fallback fontSize:content 上的
                if p_fs is None:
                    try:
                        p_fs = float(content.get("fontSize") or 14)
                    except (TypeError, ValueError):
                        p_fs = 14.0
                paragraphs.append({
                    "text": p_text,
                    "font_size": p_fs,
                    "margin_left": p_margin_left,
                    "indent": p_indent,
                })

            if not paragraphs:
                continue

            # 是否为 bullet list(多个 <li>)或普通段落——bullet dot 会再占约 fontSize 宽
            has_bullet = False
            for x in content.iter():
                if local(x.tag) == "li":
                    has_bullet = True; break

            # 对每段估算是否会换行
            for p_info in paragraphs:
                text = p_info["text"]
                fs = p_info["font_size"]
                margin_l = p_info["margin_left"]
                indent = p_info["indent"]
                bullet_indent = fs * 1.2 if has_bullet else 0
                avail_w = max(1.0, w - pad_left - pad_right - margin_l - indent - bullet_indent)
                line_w = _estimate_line_widths(text, fs)

                # 估算行高
                line_h = fs * 1.4

                # 声明可容纳的行数
                avail_h = max(1.0, h - pad_top - pad_bottom)
                declared_line_capacity = max(1, int(avail_h / line_h))

                # 估算实际需要的行数(math.ceil,line_w / avail_w 后向上取整)
                import math
                estimated_lines = max(1, math.ceil(line_w / avail_w))

                if line_w <= avail_w:
                    # 单行装得下
                    continue

                # 会换行
                severity = "warn"
                # 单行框(h 只能装 1 行)却需要多行 → 更严重的"文字会掉出框"
                if declared_line_capacity == 1 and estimated_lines > 1:
                    reason_short = "单行框强制换行——最后 1-2 个字会掉到下一行、超出框底部"
                elif estimated_lines > declared_line_capacity:
                    reason_short = f"文本估算需要 {estimated_lines} 行,但框只够 {declared_line_capacity} 行"
                else:
                    reason_short = f"文本估算需要 {estimated_lines} 行(模板设计意图可能是单行)"

                issues.append({
                    "severity": severity,
                    "slide_number": slide_idx,
                    "shape_id": sid,
                    "text": text[:60],
                    "font_size": fs,
                    "shape_width": round(w, 1),
                    "shape_height": round(h, 1),
                    "avail_width": round(avail_w, 1),
                    "estimated_line_width": round(line_w, 1),
                    "estimated_lines": estimated_lines,
                    "declared_line_capacity": declared_line_capacity,
                    "has_bullet": has_bullet,
                    "reason": (
                        f"slide {slide_idx} shape {sid} '{text[:30]}': "
                        f"估算行宽 {line_w:.0f}px > 可用宽 {avail_w:.0f}px(框宽 {w:.0f} - padding {pad_left+pad_right:.0f} "
                        f"- marginLeft {margin_l:.0f} - indent {indent:.0f}"
                        f"{' - bullet ' + f'{bullet_indent:.0f}' if has_bullet else ''})。{reason_short}。"
                        f"修法:加宽 shape width、缩短文本、去掉 bullet/indent,或明确设 wrap=\"false\" 让 xml_lint 严格拦截。"
                    ),
                })

    return {
        "checked": True,
        "warning_count": len(issues),
        "issues": issues,
        "note": (
            "unexpected_wrapping = type=text shape 的正文估算宽度 > 可用宽度(考虑 padding/margin/indent/bullet),"
            "渲染时会强制换行——通常模板设计是单行 label,MainAgent 复用时新文本长了 1-2 个字就掉行。"
            "启发式估算 ±15% 误差,因此是 warn 不阻断;MainAgent 收到 warn 后看 reason 里的 estimated vs avail 数字判断是否需要改。"
        ),
    }


# ----- 稀疏度检测(防"页眉页脚 + 几段纯文字"的空稿)-----

# 视觉元素(非文字)标签:shape 里 type != "text" 的算视觉,img/embed/chart/icon/line/table 都算
VISUAL_TAGS = {"img", "embed", "chart", "icon", "line", "table"}
# 文字类元素标签
TEXT_TAGS = {"text"}
# 长段落判定阈值:单个 text shape 正文超过这么多字符算"长段落"
LONG_PARAGRAPH_CHAR_THRESHOLD = 80


def _shape_text_length(shape_node, local_fn) -> int:
    """取一个 shape 节点内所有文字的字符数总和。
    飞书 SXSD 的文字包在 <content><p><span>text</span></p></content>;
    pptx 原生用 <a:t>text</a:t>。两种都要扫。
    """
    total = 0
    for elem in shape_node.iter():
        # 拿元素自身的 text(不含子节点)
        if elem.text:
            s = elem.text.strip()
            if s:
                total += len(s)
        # elem.tail 是尾部文本(下一个兄弟节点前的文字),一般是空但也扫一下
        if elem.tail:
            s = elem.tail.strip()
            if s:
                total += len(s)
    return total



# ---------- 模板拷贝过拟合检测(active_rebuild 页专用) ----------

def check_template_copy_overfit(authored_path: Path, source_path: Path | None,
                                 page_role: str | None,
                                 threshold_ratio: float = 0.70) -> dict:
    """检测 authored 页是否照抄了 source 页的大部分 shape(模板生搬硬套)。

    只对 active_rebuild 页生效 —— fixed_template 页本来就是"保留版式只改文字",
    shape id 大量复用是正常的。

    判定逻辑:
    - 提取 authored 页所有 shape/line/img/icon 的 id
    - 提取 source 页所有 shape/line/img/icon 的 id
    - shared_ratio = intersect(authored_ids, source_ids) / len(authored_ids)
    - shared_ratio > 0.70 → FAIL (模板拷贝过拟合)

    Returns:
        {
          "checked": bool,
          "reason": str (若 skipped),
          "authored_shape_count": int,
          "source_shape_count": int,
          "shared_id_count": int,
          "shared_ratio": float,
          "threshold": float,
          "status": "ok" | "blocked",
          "fail_count": 0 or 1,
          "issues": [...]
        }
    """
    result = {
        "checked": False,
        "fail_count": 0,
        "issues": [],
    }

    if (page_role or "").lower() != "active_rebuild":
        result["reason"] = (
            f"template_copy_overfit 仅对 active_rebuild 页检测(fixed_template 保留版式属正常)。"
            f"本页 page_role={page_role}"
        )
        return result

    if source_path is None or not source_path.exists():
        result["reason"] = "缺 --source 参数,无法对比 authored vs source shape id"
        return result

    result["checked"] = True

    try:
        authored_xml = authored_path.read_text(encoding="utf-8")
        source_xml = source_path.read_text(encoding="utf-8")
    except Exception as e:
        result["reason"] = f"read failed: {e}"
        return result

    # 提 shape/line/img/icon 的 id 属性
    id_pattern = re.compile(r'<(?:shape|line|img|icon|table|chart|embed|polyline)\b[^>]*\bid="([^"]+)"')
    authored_ids = set(id_pattern.findall(authored_xml))
    source_ids = set(id_pattern.findall(source_xml))

    authored_n = len(authored_ids)
    source_n = len(source_ids)
    if authored_n == 0:
        result["reason"] = "authored 页无 shape id,跳过"
        return result

    shared_ids = authored_ids & source_ids
    shared_ratio = len(shared_ids) / authored_n

    result.update({
        "authored_shape_count": authored_n,
        "source_shape_count": source_n,
        "shared_id_count": len(shared_ids),
        "shared_ratio": round(shared_ratio, 3),
        "threshold": threshold_ratio,
    })

    if shared_ratio > threshold_ratio:
        result["fail_count"] = 1
        result["status"] = "blocked"
        result["issues"].append({
            "code": "template_copy_overfit",
            "severity": "error",
            "message": (
                f"authored 页 {authored_n} 个 shape 中,{len(shared_ids)} 个({shared_ratio*100:.1f}%)的 id 与 source 页相同,"
                f"超过 {threshold_ratio*100:.0f}% 门槛。"
                f"active_rebuild 页应该按 refine-examples 的 sub-type 范本从零建骨架,"
                f"只保留跨页复用的 brand_assets(背景/页眉/页脚/装饰线),不要 cp source 保留内容占位符和装饰群。"
            ),
        })
    else:
        result["status"] = "ok"

    return result


# ---------- refine 触发规则(跟 template-editing-organizer.md 5.2 · active_rebuild 5 信号对齐) ----------
REFINE_SIGNAL_RULES = [
    ("visual_elements",           "≤",   12,   "装饰/图表偏少 · 大概率是纯文字空稿"),
    ("long_paragraph_char_ratio", ">",   0.60, "单长段占据全页文字主导(页眉页脚 + 一大段典型模式)"),
    ("total_elements",            "<",   20,   "元素太少 · 范本页型骨架至少 20 个 shape"),
    ("total_text_chars",          "<",   30,   "漏填 / 内容太少(仅 <data> 里的文字 · 不含演讲者备注 <note>)"),
    ("text_ratio",                ">",   0.80, "几乎全是文字块 · 装饰不足"),
]


def _compute_refine_triggers(authored_counts: dict, page_role: str | None) -> dict:
    """基于 6 个 refine 启动信号,产生 refine_triggers 字段。

    页型 = fixed_template 时返回 {"applicable": False, ...}——refine 只对 active_rebuild 页有意义。
    """
    if page_role is None:
        return {
            "applicable": False,
            "reason": (
                "⚠️ --page-role 未传!refine_triggers 无法计算 —— 这不是'本页不适用 refine',"
                "而是调用方漏参数。请从 page-plan 该行「页型策略」列取值 "
                "(fixed_template / active_rebuild),加 --page-role <值> 重跑本条 lint。"
            ),
            "signal_error": "missing_page_role_argument",
        }
    if (page_role or "").lower() != "active_rebuild":
        return {
            "applicable": False,
            "reason": f"refine 仅对 active_rebuild 页生效;本页 page_role={page_role}",
        }

    ve = int(authored_counts.get("visual_shape", 0) or 0) + int(authored_counts.get("visual_other", 0) or 0)
    te = int(authored_counts.get("text", 0) or 0)
    tot = int(authored_counts.get("total", 0) or 0)
    lpr = float(authored_counts.get("long_paragraph_char_ratio", 0.0) or 0.0)
    tc = int(authored_counts.get("total_text_chars", 0) or 0)
    mf = float(authored_counts.get("max_font_size", 0.0) or 0.0)
    tr = (te / tot) if tot else 0.0

    signal_values = {
        "visual_elements": ve,
        "long_paragraph_char_ratio": round(lpr, 3),
        "total_elements": tot,
        "total_text_chars": tc,
        "text_ratio": round(tr, 3),
        "max_font_size": mf,
    }

    triggered = []
    passed = []
    for name, op, threshold, note in REFINE_SIGNAL_RULES:
        v = signal_values[name]
        hit = False
        if op == "≤":  hit = v <= threshold
        elif op == "<":  hit = v < threshold
        elif op == ">":  hit = v > threshold
        entry = {
            "signal": name,
            "value": v,
            "operator": op,
            "threshold": threshold,
            "note": note,
        }
        (triggered if hit else passed).append(entry)

    return {
        "applicable": True,
        "should_refine": len(triggered) > 0,
        "hit_count": len(triggered),
        "triggered": triggered,
        "passed": passed,
        "summary": (
            f"命中 {len(triggered)}/{len(REFINE_SIGNAL_RULES)} 个 refine 启动信号 · 应该 refine"
            if triggered
            else f"{len(REFINE_SIGNAL_RULES)} 个信号全部通过 · 无需 refine(客观指标已达范本水平)"
        ),
    }


def _classify_slide_elements(slide_node, local_fn) -> dict:
    """扫一个 slide 下 <data> 里的元素,分类计数。
    text_shape = shape 里 type="text" 或 text 元素;visual_shape = shape 里 type != "text";
    visual_other = img/embed/chart/icon/line/table
    额外统计:text_shape_char_lengths(每个文字 shape 的字符数列表)
    **只扫 <data> 内容 · 不扫 <note>(演讲者备注) · 不扫 <style>**——refine 启动信号只看视觉呈现的内容。
    """
    counts = {"text": 0, "visual_shape": 0, "visual_other": 0}
    text_char_lengths: list[int] = []
    max_font_size = 0

    # 只扫 <data> 节点(slide → data → 元素);找不到 data 就返回空计数(不退回扫 slide 直接子节点,避免误算 note)
    data_nodes = [c for c in slide_node if local_fn(c.tag) == "data"]

    for container in data_nodes:
        for child in container:
            tag = local_fn(child.tag)
            if tag == "shape":
                shape_type = (child.get("type") or "").lower()
                if shape_type == "text":
                    counts["text"] += 1
                    text_char_lengths.append(_shape_text_length(child, local_fn))
                    # 扫本 shape 内所有 content/font 找最大字号
                    for content in child.iter():
                        # 字号:<content fontSize="XX"> 或 <font size="XX">
                        fs = content.get("fontSize") if content.get("fontSize") else content.get("size")
                        if fs:
                            try:
                                fs_v = float(fs)
                                if fs_v > max_font_size:
                                    max_font_size = fs_v
                            except (TypeError, ValueError):
                                pass
                else:
                    counts["visual_shape"] += 1
            elif tag in VISUAL_TAGS:
                counts["visual_other"] += 1
            elif tag in TEXT_TAGS:
                counts["text"] += 1
                text_char_lengths.append(_shape_text_length(child, local_fn))
            # 其他标签(如 note)不计入 —— 已通过只扫 <data> 排除
    counts["total"] = counts["text"] + counts["visual_shape"] + counts["visual_other"]
    counts["text_char_lengths"] = text_char_lengths
    counts["max_font_size"] = max_font_size
    counts["long_paragraph_count"] = sum(
        1 for n in text_char_lengths if n >= LONG_PARAGRAPH_CHAR_THRESHOLD
    )
    counts["long_paragraph_chars"] = sum(
        n for n in text_char_lengths if n >= LONG_PARAGRAPH_CHAR_THRESHOLD
    )
    counts["total_text_chars"] = sum(text_char_lengths)
    return counts


def check_sparsity(authored_xml: Path, source_xml: Path | None,
                   page_role: str | None = None,
                   min_total: int = 3,
                   max_text_ratio: float = 0.90,
                   min_density_ratio: float = 0.60,
                   min_long_paragraphs_for_dominated: int = 1,
                   max_long_paragraph_char_ratio: float = 0.70) -> dict:
    """检测内容页是否过于稀疏或被长段落主导("页眉页脚 + 几段纯文字"这种空稿)。

    4 个门槛(默认 active_rebuild 页 fail 触发 blocked;fixed_template 页降级为 info):
    - total_elements >= min_total(默认 3,避免误伤 cover)
    - text_ratio <= max_text_ratio(默认 0.90,避免误伤 toc)
    - density_ratio >= min_density_ratio(默认 0.60,需 source;无则跳)
    - **not dominated_by_paragraphs**:长段落(≥ 80 字符 text shape)数 < 2
      或 长段落字符占全页字符 <= 60%(防止大段纯文字堆砌)

    page_role 传 "fixed_template" 时所有 issue 降 severity 为 info(不 blocked)
    """
    try:
        tree = ET.parse(str(authored_xml))
        root = tree.getroot()
    except Exception as e:
        return {"checked": False, "error": f"parse authored failed: {e}"}

    def local(tag: str) -> str:
        return tag.split("}", 1)[1] if "}" in tag else tag

    root_local = local(root.tag)
    if root_local == "slide":
        slides = [root]
    elif root_local == "presentation":
        slides = [c for c in root if local(c.tag) == "slide"]
    else:
        slides = [root]

    if not slides:
        return {"checked": False, "error": "no slide found in authored xml"}

    authored_counts = _classify_slide_elements(slides[0], local)

    # fixed_template 页的 issue 都降级为 info(不阻断)
    is_fixed_template = (page_role or "").lower() == "fixed_template"
    fail_severity = "info" if is_fixed_template else "fail"

    result: dict = {
        "checked": True,
        "page_role": page_role or "unknown",
        "authored": authored_counts,
        "thresholds": {
            "min_total": min_total,
            "max_text_ratio": max_text_ratio,
            "min_density_ratio": min_density_ratio,
            "long_paragraph_char_threshold": LONG_PARAGRAPH_CHAR_THRESHOLD,
            "min_long_paragraphs_for_dominated": min_long_paragraphs_for_dominated,
            "max_long_paragraph_char_ratio": max_long_paragraph_char_ratio,
        },
        "issues": [],
    }

    # 门槛 1: total >= min_total
    total = authored_counts["total"]
    if total < min_total:
        result["issues"].append({
            "code": "too_few_elements",
            "severity": fail_severity,
            "message": f"整页元素总数 {total} < {min_total}",
            "hint": "参考规则 5.2.2「默认视觉化 · 纯段落是例外」—— 加 KPI 数字带 / 编号卡片 / 时间线 / 三线表 / SVG 图 / 图 + 文",
        })

    # 门槛 2: text_ratio <= max_text_ratio
    if total > 0:
        text_ratio = authored_counts["text"] / total
        result["authored"]["text_ratio"] = round(text_ratio, 3)
        if text_ratio > max_text_ratio:
            result["issues"].append({
                "code": "text_ratio_too_high",
                "severity": fail_severity,
                "message": f"文字类元素占比 {text_ratio:.0%} > {max_text_ratio:.0%}",
                "hint": "把长段落拆成结构化视觉表达(KPI 数字 / 编号卡 / 三线表 / 时间线 / SVG 图)",
            })

    # 门槛 3: dominated_by_paragraphs —— 长段落数 + 长段落字符占比双重判定
    long_p_count = authored_counts["long_paragraph_count"]
    long_p_chars = authored_counts["long_paragraph_chars"]
    total_chars = authored_counts["total_text_chars"]
    long_p_ratio = long_p_chars / total_chars if total_chars > 0 else 0
    result["authored"]["long_paragraph_char_ratio"] = round(long_p_ratio, 3)
    if long_p_count >= min_long_paragraphs_for_dominated and long_p_ratio > max_long_paragraph_char_ratio:
        result["issues"].append({
            "code": "dominated_by_paragraphs",
            "severity": fail_severity,
            "message": (
                f"页面被大段文字主导:{long_p_count} 个长段落(≥{LONG_PARAGRAPH_CHAR_THRESHOLD} 字)"
                f"占全页文字的 {long_p_ratio:.0%}(阈值 {max_long_paragraph_char_ratio:.0%})"
            ),
            "hint": "把长段落拆成结构化视觉表达(KPI 数字 / 编号卡 / 三线表 / 时间线 / SVG 图 / 图 + 文)",
        })

    # 门槛 4: density_ratio >= min_density_ratio(需要 source)
    if source_xml and source_xml.exists():
        try:
            s_tree = ET.parse(str(source_xml))
            s_root = s_tree.getroot()
            s_root_local = local(s_root.tag)
            if s_root_local == "slide":
                s_slides = [s_root]
            elif s_root_local == "presentation":
                s_slides = [c for c in s_root if local(c.tag) == "slide"]
            else:
                s_slides = [s_root]
            if s_slides:
                source_counts = _classify_slide_elements(s_slides[0], local)
                result["source"] = source_counts
                if source_counts["total"] > 0:
                    ratio = total / source_counts["total"]
                    result["density_ratio"] = round(ratio, 3)
                    if ratio < min_density_ratio:
                        result["issues"].append({
                            "code": "density_below_source",
                            "severity": fail_severity,
                            "message": (
                                f"新页元素数 {total} 只有源模板页 {source_counts['total']} 的 {ratio:.0%}"
                                f"(低于 {min_density_ratio:.0%})"
                            ),
                            "hint": "参考源模板页的元素密度补充结构性视觉;不用照搬示例文字,加 KPI 数字 / 编号卡 / 分栏 / 图表让画面填满",
                        })
        except Exception as e:
            result["source_parse_error"] = str(e)
    else:
        result["density_check_skipped"] = "no source xml"

    fail_count = sum(1 for i in result["issues"] if i["severity"] == "fail")
    info_count = sum(1 for i in result["issues"] if i["severity"] == "info")
    result["fail_count"] = fail_count
    result["info_count"] = info_count
    result["status"] = "blocked" if fail_count > 0 else "ok"

    return result


def main() -> int:
    ap = argparse.ArgumentParser(description="template-editing 分支专用的聚合 lint")
    ap.add_argument("--authored", required=True, help="MainAgent 写好的 authoring/slide-NN.xml")
    ap.add_argument("--source", help="对应的 source-slides/slide-NN.xml(用于占位符 diff);不传则跳过 diff")
    ap.add_argument("--skill-root", required=True,
                    help="skill 根目录(找 xml_lint.py / color_contrast_check.py)")
    ap.add_argument("--contrast-threshold", type=float, default=2.25)
    ap.add_argument("--page-role", choices=["fixed_template", "active_rebuild"], default=None,
                    help="页型策略,从 page-plan 该页的「页型策略」列取。传 fixed_template 时 sparsity_check 只报 info 不 block(cover/toc/chapter 天然元素少或纯文字);不传时按 active_rebuild 严格判定")
    args = ap.parse_args()

    authored_path = Path(args.authored).resolve()
    if not authored_path.exists():
        print(json.dumps({"ok": False, "error": f"authored not found: {authored_path}"}))
        return 2

    skill_root = Path(args.skill_root).resolve()
    xml_lint_script = skill_root / "scripts" / "xml_lint.py"
    contrast_script = skill_root / "scripts" / "color_contrast_check.py"
    if not xml_lint_script.exists():
        print(json.dumps({"ok": False, "error": f"xml_lint.py not found under {skill_root}"}))
        return 3
    if not contrast_script.exists():
        print(json.dumps({"ok": False, "error": f"color_contrast_check.py not found under {skill_root}"}))
        return 3

    # (1) xml_lint
    xml_lint_res = _run_subscript(xml_lint_script, ["--input", str(authored_path)], timeout=60)
    xml_lint_summary = (xml_lint_res.get("stdout_json") or {}).get("summary", {})
    xml_lint_error_count = xml_lint_summary.get("error_count", -1)

    # (2) 靠色
    contrast_res = _run_subscript(
        contrast_script,
        ["--xml", str(authored_path), "--format", "json",
         "--threshold", str(args.contrast_threshold)],
        timeout=60,
    )
    contrast_summary = (contrast_res.get("stdout_json") or {}).get("summary", {})
    contrast_has_blocking = contrast_summary.get("has_blocking_issues", False)

    # (3) 占位符 diff(可选)
    placeholder_res: dict | None = None
    if args.source:
        source_path = Path(args.source).resolve()
        if source_path.exists():
            placeholder_res = check_placeholders(source_path, authored_path)
        else:
            placeholder_res = {"checked": False, "error": f"source not found: {source_path}"}
    else:
        placeholder_res = {"checked": False, "reason": "no --source passed, placeholder diff skipped"}

    # (4) 溢出压邻居(基于 xml_lint 报的 text_overflows_container 做二次分析)
    overflow_covers_res = check_overflow_covers_below(
        authored_path, xml_lint_res.get("stdout_json")
    )

    # (5) 意外换行(单行框被强制多行)
    wrapping_res = check_unexpected_wrapping(authored_path)

    # (6) 稀疏度检测(防"页眉页脚 + 几段纯文字"的空稿)
    source_path_for_sparsity = Path(args.source).resolve() if args.source else None
    sparsity_res = check_sparsity(authored_path, source_path_for_sparsity,
                                  page_role=args.page_role)

    # (7) 模板拷贝过拟合检测(active_rebuild 页专用;防"authored 页 shape 90% 来自 source 页")
    overfit_res = check_template_copy_overfit(authored_path, source_path_for_sparsity,
                                              page_role=args.page_role)

    # 聚合 status
    blocked = False
    reasons: list[str] = []
    if xml_lint_error_count > 0:
        blocked = True
        reasons.append(f"xml_lint has {xml_lint_error_count} errors")
    elif xml_lint_error_count < 0:
        # 子脚本失败/超时导致 error_count 为默认 -1 · 也要 block(否则错误被静默掩盖)
        blocked = True
        reasons.append("xml_lint subscript failed or returned no summary")
    if contrast_has_blocking:
        blocked = True
        reasons.append("color_contrast_check has FAIL")
    if overflow_covers_res.get("fail_count", 0) > 0:
        blocked = True
        reasons.append(
            f"text_overflow_covers_below has {overflow_covers_res['fail_count']} FAIL "
            "(某文本溢出后压到了同页其他文本框,用户视觉上会看到两段文字重叠)"
        )
    if sparsity_res.get("fail_count", 0) > 0:
        blocked = True
        codes = [i["code"] for i in sparsity_res.get("issues", [])]
        reasons.append(
            f"sparsity_check has {sparsity_res['fail_count']} FAIL "
            f"({', '.join(codes)}) —— 页面过于稀疏/文字化,参考 5.2.2「默认视觉化」补结构化视觉"
        )
    if overfit_res.get("fail_count", 0) > 0:
        blocked = True
        reasons.append(
            f"template_copy_overfit FAIL —— authored 页 {overfit_res['shared_ratio']*100:.0f}% 的 shape id 与 source 相同,"
            f"意味着几乎照抄模板 shape。active_rebuild 页应该按 refine-examples 的 sub-type 范本从零建骨架,"
            "只保留跨页复用的 brand_assets(背景/页眉/页脚/装饰线)。请重新生成本页。"
        )

    placeholder_warn_count = (placeholder_res or {}).get("warning_count", 0)
    wrapping_warn_count = (wrapping_res or {}).get("warning_count", 0)

    output = {
        "ok": True,
        "authored": str(authored_path),
        "status": "blocked" if blocked else "ready_to_write",
        "block_reasons": reasons,
        "placeholder_warnings": placeholder_warn_count,
        "wrapping_warnings": wrapping_warn_count,
        "summary": {
            "xml_lint_errors": xml_lint_error_count,
            "contrast_blocking": contrast_has_blocking,
            "placeholder_warn_count": placeholder_warn_count,
            "overflow_covers_below_fail_count": overflow_covers_res.get("fail_count", 0),
            "unexpected_wrapping_warn_count": wrapping_warn_count,
            "sparsity_fail_count": sparsity_res.get("fail_count", 0),
            # 元素分布信号(非阻断,供 Organizer 判断 refine 启动条件)
            "page_role": sparsity_res.get("page_role"),
            "total_elements": (sparsity_res.get("authored") or {}).get("total"),
            "text_elements": (sparsity_res.get("authored") or {}).get("text"),
            "visual_elements": (
                (sparsity_res.get("authored") or {}).get("visual_shape", 0)
                + (sparsity_res.get("authored") or {}).get("visual_other", 0)
            ),
            "long_paragraph_count": (sparsity_res.get("authored") or {}).get("long_paragraph_count"),
            "long_paragraph_char_ratio": (sparsity_res.get("authored") or {}).get("long_paragraph_char_ratio"),
            "total_text_chars": (sparsity_res.get("authored") or {}).get("total_text_chars"),
            "max_font_size": (sparsity_res.get("authored") or {}).get("max_font_size"),
            "refine_triggers": _compute_refine_triggers(sparsity_res.get("authored") or {}, sparsity_res.get("page_role")),
        },
        "checks": {
            "xml_lint": {
                "status": xml_lint_summary.get("status"),
                "error_count": xml_lint_error_count,
                "warning_count": xml_lint_summary.get("warning_count", 0),
                "raw": xml_lint_res.get("stdout_json"),
            },
            "color_contrast": {
                "has_blocking": contrast_has_blocking,
                "issue_count": contrast_summary.get("issue_count", 0),
                "raw": contrast_res.get("stdout_json"),
            },
            "placeholder_diff": placeholder_res,
            "overflow_covers_below": overflow_covers_res,
            "unexpected_wrapping": wrapping_res,
            "sparsity": sparsity_res,
            "template_copy_overfit": overfit_res,
        },
    }
    print(json.dumps(output, ensure_ascii=False, indent=2))
    return 0 if not blocked else 1


if __name__ == "__main__":
    sys.exit(main())
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall