@yujp_vc/ppt-assistant 0.0.0-stage → 1.5.2

package/charts.py

@@ -0,0 +1,329 @@
+"""Validated native charts with embedded workbooks, shared styling and CSV input."""
+from __future__ import annotations
+
+import copy
+import csv
+import math
+from pathlib import Path
+
+from pptx.chart.data import BubbleChartData, CategoryChartData, XyChartData
+from pptx.dml.color import RGBColor
+from pptx.enum.chart import (XL_CHART_TYPE, XL_DATA_LABEL_POSITION,
+                             XL_LEGEND_POSITION, XL_MARKER_STYLE, XL_TICK_MARK)
+from pptx.util import Inches, Pt
+from pptx.oxml.xmlchemy import OxmlElement
+
+KINDS = {
+    'column': XL_CHART_TYPE.COLUMN_CLUSTERED,
+    'bar': XL_CHART_TYPE.BAR_CLUSTERED,
+    'line': XL_CHART_TYPE.LINE_MARKERS,
+    'area': XL_CHART_TYPE.AREA,
+    'stacked_column': XL_CHART_TYPE.COLUMN_STACKED,
+    'stacked_bar': XL_CHART_TYPE.BAR_STACKED,
+    'percent_column': XL_CHART_TYPE.COLUMN_STACKED_100,
+    'percent_bar': XL_CHART_TYPE.BAR_STACKED_100,
+    'donut': XL_CHART_TYPE.DOUGHNUT,
+    'pie': XL_CHART_TYPE.PIE,
+    'scatter': XL_CHART_TYPE.XY_SCATTER,
+    'bubble': XL_CHART_TYPE.BUBBLE,
+}
+PALETTE = ['176C88', 'D97706', '6366F1', '2A9D8F', 'C0392B', '64748B']
+
+
+def palette(colors: dict) -> list[str]:
+    """Lead every chart with the deck's accent so brand color stays consistent."""
+    ordered = [colors.get('accent', PALETTE[0]), *PALETTE[1:]]
+    result = []
+    for color in ordered:
+        if color not in result:
+            result.append(color)
+    return result
+
+
+def _numeric(value):
+    return type(value) in {int, float} and math.isfinite(value)
+
+
+def _color(value):
+    return (isinstance(value, str) and len(value) == 6
+            and all(c in '0123456789abcdefABCDEF' for c in value))
+
+
+def resolve_chart(spec: dict, base: Path) -> dict:
+    """Copy, load optional CSV and validate; never infer or synthesize missing values."""
+    if not isinstance(spec, dict):
+        raise ValueError('chart must be an object')
+    chart = copy.deepcopy(spec)
+    kind = chart.setdefault('kind', 'column')
+    if not isinstance(kind, str) or kind not in KINDS:
+        raise ValueError(f'unsupported chart kind: {kind}')
+    series = chart.get('series')
+    if not isinstance(series, list) or not 1 <= len(series) <= 6:
+        raise ValueError('chart requires 1–6 series')
+    if any(not isinstance(s, dict) or not isinstance(s.get('name'), str) or not s['name'].strip()
+           for s in series):
+        raise ValueError('every chart series needs a name')
+    if 'number_format' in chart and (not isinstance(chart['number_format'], str)
+                                       or not chart['number_format']):
+        raise ValueError('number_format must be a non-empty Excel format string')
+    if 'data_labels' in chart and type(chart['data_labels']) is not bool:
+        raise ValueError('data_labels must be boolean')
+    if 'data_file' in chart:
+        if kind in {'scatter', 'bubble'}:
+            raise ValueError('XY charts use explicit points, not category CSV')
+        if 'categories' in chart or any('values' in s for s in chart.get('series', [])):
+            raise ValueError('CSV and inline chart values cannot be mixed')
+        if not isinstance(chart['data_file'], str) or not chart['data_file'].strip():
+            raise ValueError('data_file must be a CSV path')
+        path = base / chart['data_file']
+        if path.suffix.lower() != '.csv':
+            raise ValueError('chart data_file must be a CSV file')
+        with path.open(encoding='utf-8-sig', newline='') as stream:
+            reader = csv.DictReader(stream)
+            rows = list(reader)
+            columns = [chart.get('category_column')] + [s.get('column') for s in chart.get('series', [])]
+            if any(not isinstance(c, str) or not c or c not in (reader.fieldnames or []) for c in columns):
+                raise ValueError('CSV category/series column is missing')
+            if len(set(reader.fieldnames)) != len(reader.fieldnames) or any(
+                    None in row or any(value is None for value in row.values()) for row in rows):
+                raise ValueError('CSV requires unique headers and complete rows; use empty cells for gaps')
+        chart['categories'] = [row[chart['category_column']] for row in rows]
+        for item in series:
+            try:
+                item['values'] = [float(row[item['column']]) if row[item['column']].strip()
+                                    else None for row in rows]
+            except (ValueError, AttributeError, KeyError) as error:
+                raise ValueError(f"CSV series {item.get('name')} contains invalid cells") from error
+    if kind in {'scatter', 'bubble'}:
+        count = 3 if kind == 'bubble' else 2
+        for s in series:
+            points = s.get('points')
+            if not isinstance(points, list) or not 1 <= len(points) <= 500:
+                raise ValueError('XY series requires 1–500 points')
+            if any(not isinstance(p, list) or len(p) != count or not all(_numeric(v) for v in p)
+                   or (count == 3 and p[2] <= 0) for p in points):
+                raise ValueError('XY points must be finite [x,y] or [x,y,positive_size]')
+    else:
+        categories = chart.get('categories')
+        if (not isinstance(categories, list) or not 1 <= len(categories) <= 40
+                or any(not isinstance(c, str) or not c.strip() for c in categories)):
+            raise ValueError('chart requires 1–40 non-empty category labels')
+        for s in series:
+            values = s.get('values')
+            if (not isinstance(values, list) or len(values) != len(categories)
+                    or any(v is not None and not _numeric(v) for v in values)
+                    or all(v is None for v in values)):
+                raise ValueError('chart values must match categories and contain finite numbers or null gaps')
+        if kind in {'pie', 'donut'}:
+            values = series[0]['values']
+            if (len(series) != 1 or len(categories) > 8
+                    or any(v is None or v < 0 for v in values) or sum(values) <= 0):
+                raise ValueError('pie/donut requires one non-negative series, positive total and at most 8 slices')
+        if kind.startswith('percent_'):
+            if '%' in chart.get('number_format', ''):
+                raise ValueError('percent stacks retain source counts; use y_axis.number_format for percentages')
+            if any(v is None or v < 0 for s in series for v in s['values']):
+                raise ValueError('percent stacks require non-negative, complete data')
+            if any(sum(s['values'][i] for s in series) <= 0 for i in range(len(categories))):
+                raise ValueError('each percent stack needs a positive total')
+        if chart.get('sort'):
+            if kind not in {'bar', 'column'} or len(series) != 1 or chart['sort'] not in ('ascending', 'descending'):
+                raise ValueError('sorting requires a single bar/column series and ascending/descending')
+            order = sorted(range(len(categories)), key=lambda i: (
+                series[0]['values'][i] is None,
+                (-series[0]['values'][i] if chart['sort'] == 'descending' else series[0]['values'][i])
+                if series[0]['values'][i] is not None else 0))
+            chart['categories'] = [categories[i] for i in order]
+            series[0]['values'] = [series[0]['values'][i] for i in order]
+    for s in series:
+        if 'color' in s and not _color(s['color']):
+            raise ValueError('series.color must be six hexadecimal digits')
+    for field in ('highlight',):
+        if not isinstance(chart.get(field, []), list) or any(
+                c not in chart.get('categories', []) for c in chart.get(field, [])):
+            raise ValueError('highlight must contain existing category labels')
+    for axis_name in ('x_axis', 'y_axis'):
+        axis = chart.get(axis_name, {})
+        if not isinstance(axis, dict):
+            raise ValueError(f'{axis_name} must be an object')
+        for field in ('title', 'number_format'):
+            if field in axis and not isinstance(axis[field], str):
+                raise ValueError(f'{axis_name}.{field} must be a string')
+        if 'font_size' in axis and (not _numeric(axis['font_size']) or not 9 <= axis['font_size'] <= 18):
+            raise ValueError('axis font_size must be between 9 and 18 points')
+        if 'label_interval' in axis and (axis_name != 'x_axis' or kind in {'scatter', 'bubble', 'pie', 'donut'}
+                                        or type(axis['label_interval']) is not int
+                                        or not 1 <= axis['label_interval'] <= 40):
+            raise ValueError('label_interval requires a category axis and an integer from 1 to 40')
+        for field in ('min', 'max', 'major_unit'):
+            if field in axis and not _numeric(axis[field]):
+                raise ValueError(f'{axis_name}.{field} must be finite')
+        if 'major_unit' in axis and axis['major_unit'] <= 0:
+            raise ValueError('axis major_unit must be positive')
+        if kind.startswith('percent_') and axis_name == 'y_axis' and (
+                axis.get('min', 0) != 0 or axis.get('max', 1) != 1
+                or axis.get('major_unit', .2) > 1):
+            raise ValueError('percent stack value axis uses 0–1, displayed as 0–100%')
+        if 'min' in axis and 'max' in axis and axis['min'] >= axis['max']:
+            raise ValueError('axis minimum must be below maximum')
+        if kind not in {'scatter', 'bubble', 'pie', 'donut'} and axis_name == 'x_axis' and any(
+                field in axis for field in ('min', 'max', 'major_unit')):
+            raise ValueError('category axis has no numeric bounds; use y_axis for value bounds, including bar charts')
+        if kind not in {'pie', 'donut'} and (axis_name == 'y_axis' or kind in {'scatter', 'bubble'}):
+            if kind.startswith('percent_'):
+                values = [0., 1.]
+            elif kind in {'scatter', 'bubble'}:
+                dimension = 0 if axis_name == 'x_axis' else 1
+                values = [p[dimension] for s in series for p in s['points']]
+            else:
+                values = [v for s in series for v in s['values'] if v is not None]
+                if 'stacked' in kind:
+                    values += [sum(max(s['values'][i] or 0, 0) for s in series)
+                               for i in range(len(chart['categories']))]
+                    values += [sum(min(s['values'][i] or 0, 0) for s in series)
+                               for i in range(len(chart['categories']))]
+            if any(v < axis.get('min', -math.inf) or v > axis.get('max', math.inf) for v in values):
+                raise ValueError('axis bounds would hide source values')
+            if kind in {'column', 'bar', 'area', 'stacked_column', 'stacked_bar'} and (
+                    axis.get('min', 0) > 0 or axis.get('max', 0) < 0):
+                raise ValueError('bar and area value axes must include zero')
+    return chart
+
+
+def draw_chart(slide, spec: dict, base: Path, box: tuple, font: str, colors: dict):
+    """Add a native PowerPoint chart and its editable workbook; box uses inches."""
+    spec = resolve_chart(spec, base)
+    chart_palette = palette(colors)
+    kind = spec['kind']
+    fmt = spec.get('number_format', '0.##')
+    if kind in {'scatter', 'bubble'}:
+        data = BubbleChartData() if kind == 'bubble' else XyChartData()
+        for s in spec['series']:
+            target = data.add_series(s['name'])
+            for point in s['points']:
+                target.add_data_point(*point)
+    else:
+        data = CategoryChartData()
+        data.categories = spec['categories']
+        for s in spec['series']:
+            data.add_series(s['name'], s['values'], fmt)
+    x, y, w, h = box
+    if kind in {'bar', 'stacked_bar', 'percent_bar'} and len(spec['categories']) > max(6, int(h * 3)):
+        raise ValueError('too many bar categories for the panel height; split the chart across pages')
+    chart = slide.shapes.add_chart(KINDS[kind], Inches(x), Inches(y), Inches(w), Inches(h), data).chart
+    # Explicit chart-area fill avoids theme white backgrounds in dark decks.
+    properties = OxmlElement('c:spPr')
+    fill = OxmlElement('a:solidFill')
+    rgb = OxmlElement('a:srgbClr')
+    rgb.set('val', colors['panel'])
+    fill.append(rgb)
+    properties.append(fill)
+    line = OxmlElement('a:ln')
+    line.append(OxmlElement('a:noFill'))
+    properties.append(line)
+    properties.append(OxmlElement('a:effectLst'))
+    chart._chartSpace.insert_element_before(properties, 'c:txPr', 'c:externalData',
+                                           'c:printSettings', 'c:userShapes', 'c:extLst')
+    chart.has_title = False
+    chart.has_legend = len(spec['series']) > 1 or kind in {'pie', 'donut'}
+    compact_composition = kind in {'pie', 'donut'} and h < 2.6
+    if chart.has_legend:
+        chart.legend.position = XL_LEGEND_POSITION.RIGHT if compact_composition else XL_LEGEND_POSITION.BOTTOM
+        chart.legend.include_in_layout = False
+        chart.legend.font.name = font
+        chart.legend.font.size = Pt(11 if w < 7 else 13)
+        chart.legend.font.color.rgb = RGBColor.from_string(colors['text'])
+    plot = chart.plots[0]
+    if kind in {'pie', 'donut'}:
+        area = chart._chartSpace.xpath('c:chart/c:plotArea')[0]
+        layout = OxmlElement('c:layout')
+        area.insert(0, layout)
+        manual = OxmlElement('c:manualLayout')
+        for tag, value in [('layoutTarget', 'inner'), ('xMode', 'factor'), ('yMode', 'factor'),
+                           ('wMode', 'factor'), ('hMode', 'factor'),
+                           ('x', '.05'), ('y', '.02'),
+                           ('w', '.7' if compact_composition else '.9'),
+                           ('h', '.95' if compact_composition else '.78')]:
+            element = OxmlElement('c:' + tag)
+            element.set('val', value)
+            manual.append(element)
+        layout.append(manual)
+    if kind == 'donut':
+        plot.hole_size = 65
+    if kind not in {'scatter', 'bubble', 'area'}:
+        plot.has_data_labels = spec.get('data_labels', not kind.startswith('percent_')
+                                       and len(spec.get('categories', [])) <= 8)
+        if plot.has_data_labels:
+            labels = plot.data_labels
+            labels.font.name, labels.font.size = font, Pt(10 if w < 7 else 13)
+            labels.font.color.rgb = RGBColor.from_string(colors['text'])
+            if kind in {'pie', 'donut'}:
+                labels.show_value, labels.show_percentage = False, True
+                labels.position = XL_DATA_LABEL_POSITION.CENTER
+                labels.font.color.rgb = RGBColor.from_string('FFFFFF')
+            else:
+                labels.number_format = fmt
+                labels.show_value = True
+                labels.position = (XL_DATA_LABEL_POSITION.CENTER if 'stacked' in kind or kind.startswith('percent_')
+                                   else XL_DATA_LABEL_POSITION.OUTSIDE_END if kind in {'bar', 'column'}
+                                   else XL_DATA_LABEL_POSITION.ABOVE)
+                if 'stacked' in kind or kind.startswith('percent_'):
+                    labels.font.color.rgb = RGBColor.from_string('FFFFFF')
+    for i, series in enumerate(chart.series):
+        color = spec['series'][i].get('color', chart_palette[i % len(chart_palette)])
+        series.format.fill.solid()
+        series.format.fill.fore_color.rgb = RGBColor.from_string(color)
+        series.format.line.color.rgb = RGBColor.from_string(color)
+        if kind in {'line', 'scatter'}:
+            series.marker.style = XL_MARKER_STYLE.CIRCLE
+            series.marker.size = 6
+            series.marker.format.fill.solid()
+            series.marker.format.fill.fore_color.rgb = RGBColor.from_string(color)
+            series.marker.format.line.color.rgb = RGBColor.from_string(color)
+            series.format.line.width = Pt(2.2)
+            if kind == 'scatter':
+                series.format.line.fill.background()
+        if kind in {'pie', 'donut'} or (len(chart.series) == 1 and spec.get('highlight')):
+            for j, point in enumerate(series.points):
+                point_color = chart_palette[j % len(chart_palette)] if kind in {'pie', 'donut'} else (
+                    colors['accent'] if spec['categories'][j] in spec['highlight'] else '94A3B8')
+                point.format.fill.solid()
+                point.format.fill.fore_color.rgb = RGBColor.from_string(point_color)
+                point.format.line.fill.background()
+    if kind not in {'pie', 'donut'}:
+        for name, axis in [('x_axis', chart.category_axis), ('y_axis', chart.value_axis)]:
+            options = spec.get(name, {})
+            axis.tick_labels.font.name = font
+            axis.tick_labels.font.size = Pt(options.get('font_size', 10 if w < 7 else 12))
+            axis.tick_labels.font.color.rgb = RGBColor.from_string(colors['muted'])
+            axis.format.line.color.rgb = RGBColor.from_string(colors['muted'])
+            axis.major_tick_mark = XL_TICK_MARK.NONE
+            axis.minor_tick_mark = XL_TICK_MARK.NONE
+            axis.has_title = bool(options.get('title'))
+            if axis.has_title:
+                frame = axis.axis_title.text_frame
+                frame.text = options['title']
+                for p in frame.paragraphs:
+                    p.font.name, p.font.size = font, Pt(11)
+                    p.font.color.rgb = RGBColor.from_string(colors['muted'])
+            if name == 'y_axis' or kind in {'scatter', 'bubble'}:
+                axis.tick_labels.number_format = options.get('number_format', '0%' if kind.startswith('percent_') else fmt)
+                for field, attribute in [('min', 'minimum_scale'), ('max', 'maximum_scale'), ('major_unit', 'major_unit')]:
+                    if field in options:
+                        setattr(axis, attribute, options[field])
+                if name == 'y_axis' and kind not in {'scatter', 'bubble', 'line'} and 'min' not in options:
+                    if all(v is None or v >= 0 for s in spec['series'] for v in s['values']):
+                        axis.minimum_scale = 0
+                axis.has_major_gridlines = name == 'y_axis'
+                if axis.has_major_gridlines:
+                    axis.major_gridlines.format.line.color.rgb = RGBColor.from_string('D5DCE5' if colors['panel'] == 'FFFFFF' else '3D506B')
+                    axis.major_gridlines.format.line.width = Pt(.5)
+            else:
+                interval = options.get('label_interval', max(1, math.ceil(len(spec['categories']) / max(4, int(w * 1.2)))))
+                skip = OxmlElement('c:tickLblSkip')
+                skip.set('val', str(interval))
+                axis._element.insert_element_before(skip, 'c:tickMarkSkip', 'c:noMultiLvlLbl', 'c:extLst')
+        if kind in {'bar', 'stacked_bar', 'percent_bar'}:
+            chart.category_axis.reverse_order = True
+            chart.value_axis._element.xpath('c:crosses')[0].set('val', 'max')
+    return chart

package/check.py

@@ -0,0 +1,236 @@
+#!/usr/bin/env python3
+"""
+check.py —— PPT 检查器：排版一致性 + 文字遮挡/溢出。
+
+检查项：
+  1. 字体一致性：是否出现模板外的字体。
+  2. 配色一致性：文字是否出现模板调色板外的颜色。
+  3. 标题对齐：各页主标题（最大字号）横向位置是否一致。
+  4. 文字遮挡：按「估算文字实际占用高度」检测文本框/图片重叠。
+  5. 文本溢出：按字号+框宽高估算文本是否放不下（启发式，非像素级精确）。
+  6. 出界：形状是否超出幻灯片边界。
+
+用法：
+    python3 check.py <input.pptx> [--json]
+"""
+import sys, math, json
+from pptx import Presentation
+
+# 模板允许的字体（含主题引用）
+OK_FONTS = {"华文中宋", "Noto Serif SC", "Noto Serif SC Bold", "微软雅黑", "等线",
+            "Microsoft YaHei", "Arial", "Calibri", "Calibri Light", "Wingdings"}
+# 允许的文字色（hex 大写）：中性色 + 全部 palette + 页面底色/封面辅助色
+OK_COLORS = {
+    "000000", "595959", "FFFFFF", "A5A5A5", "F4F6F9",
+    # original
+    "192D77", "C00000", "D24726", "E7E6E6", "44546A", "5B9BD5",
+    # coastal
+    "1B4965", "E07A5F", "62B6CB", "E3EEF6", "5FA8D3", "81B29A",
+    # ocean
+    "1D3557", "E63946", "457B9D", "F1FAEE", "A8DADC", "F4A261",
+    # aurora
+    "2A9D8F", "E76F51", "48CAE4", "E8F4F2", "90E0EF",
+    # indigo
+    "312E81", "E11D48", "6366F1", "EEF2FF", "818CF8", "F59E0B",
+    # institutional 体制内庄重
+    "1F3A5F", "C0392B", "C9A227", "EEF1F5", "6B7A99", "A8B4C8",
+    # rose 暖玫瑰
+    "8C3B4C", "C2576B", "E08E6F", "F6ECE7", "D9A08A", "9C7A6B",
+    # 封面辅助
+    "9FB3DB", "FFC799", "E6ECF6", "CFD9E9", "E2CE8C",
+    # 图片署名/辅助灰蓝/投影
+    "8A93A6", "C7CDD9",
+    # probation native_v2 paper theme
+    "15253F", "4D627A", "176C88", "F4F6FA",
+    "2DBE62", "4285E8", "F36C2B",
+}
+
+SLIDE_W = 12192000
+SLIDE_H = 6858000
+
+def _run_info(shape):
+    out = []
+    if not shape.has_text_frame:
+        return out
+    for para in shape.text_frame.paragraphs:
+        for r in para.runs:
+            size = r.font.size.pt if r.font.size else 18
+            font = r.font.name or ''
+            color = None
+            try:
+                s = str(r.font.color.rgb)
+                if len(s) == 6:
+                    color = s.upper()
+            except Exception:
+                pass
+            out.append((font, size, color))
+    return out
+
+def _bbox(shape):
+    try:
+        return (shape.left, shape.top, shape.width, shape.height)
+    except Exception:
+        return None
+
+def _disp_width(text):
+    """估算文本显示宽度（em 数）：CJK 等全角字符≈1，拉丁/数字≈0.55。"""
+    w = 0.0
+    for ch in text:
+        w += 1.0 if ord(ch) > 0x2E80 else 0.55
+    return w
+
+
+def _est_extent(shape):
+    """估算形状实际占用框：文字用估算高度，图片用全框。空文本返回 None。"""
+    bb = _bbox(shape)
+    if not bb:
+        return None
+    if not shape.has_text_frame:
+        return bb
+    txt = shape.text_frame.text
+    if not txt.strip():
+        return None
+    font_pt = 0
+    for _, size, _ in _run_info(shape):
+        if size > font_pt:
+            font_pt = size
+    if font_pt <= 0:
+        font_pt = 18
+    w_pt = bb[2] / 914400 * 72
+    cpl_em = max(0.5, w_pt / font_pt)   # 每行可容纳的 em 数
+    n_lines = 0
+    for line in txt.split('\n'):
+        n_lines += max(1, math.ceil(_disp_width(line) / cpl_em))
+    line_h_emu = int(font_pt * 1.25 / 72 * 914400)
+    est_h = n_lines * line_h_emu
+    return (bb[0], bb[1], bb[2], est_h)
+
+def _overlap(a, b):
+    if a[2] < 10000 or a[3] < 10000 or b[2] < 10000 or b[3] < 10000:
+        return False
+    ax2, ay2 = a[0]+a[2], a[1]+a[3]
+    bx2, by2 = b[0]+b[2], b[1]+b[3]
+    return not (ax2 <= b[0] or bx2 <= a[0] or ay2 <= b[1] or by2 <= a[1])
+
+def _overflow_est(text, font_pt, box):
+    if not text.strip() or not box:
+        return None
+    w_pt = box[2] / 914400 * 72
+    h_pt = box[3] / 914400 * 72
+    if font_pt <= 0:
+        font_pt = 18
+    cpl_em = max(0.5, w_pt / font_pt)
+    n_lines = 0
+    for line in text.split('\n'):
+        n_lines += max(1, math.ceil(_disp_width(line) / cpl_em))
+    fit_lines = max(1, int(h_pt / (font_pt * 1.25)))
+    if n_lines > fit_lines:
+        return {'need_lines': n_lines, 'fit_lines': fit_lines, 'font_pt': font_pt}
+    return None
+
+def check(path):
+    prs = Presentation(path)
+    report = {
+        'slides': len(prs.slides),
+        'fonts': {'unexpected': []},
+        'colors': {'unexpected': []},
+        'titles': [],
+        'overlap': [],
+        'overflow': [],
+        'out_of_bounds': [],
+    }
+    for i, slide in enumerate(prs.slides, 1):
+        shapes = list(slide.shapes)
+        # 主标题：本页最大字号文本（>=24pt）
+        best = None
+        for sh in shapes:
+            if not sh.has_text_frame or not sh.text_frame.text.strip():
+                continue
+            for _, size, _ in _run_info(sh):
+                if size >= 24 and (best is None or size > best[1]):
+                    best = (sh, size)
+        if best:
+            bb = _bbox(best[0])
+            if bb:
+                report['titles'].append({'slide': i, 'x_in': round(bb[0]/914400, 2),
+                                         'size': best[1], 'shape': best[0].name})
+        # 字体/颜色/出界
+        for sh in shapes:
+            name = sh.name or ''
+            for font, size, color in _run_info(sh):
+                if font and font not in OK_FONTS and not font.startswith('+'):
+                    report['fonts']['unexpected'].append((i, name, font, size))
+                if color and color not in OK_COLORS:
+                    report['colors']['unexpected'].append((i, name, color))
+            bb = _bbox(sh)
+            if bb and (sh.has_text_frame or sh.shape_type == 13):
+                if bb[0] < 0 or bb[1] < 0 or bb[0]+bb[2] > SLIDE_W or bb[1]+bb[3] > SLIDE_H:
+                    report['out_of_bounds'].append((i, name))
+        # 重叠（用估算占用框；跳过图片，因为图片作为背景/图文混排是刻意的）
+        extents = [(_est_extent(sh), sh) for sh in shapes]
+        for a in range(len(extents)):
+            for b in range(a+1, len(extents)):
+                ea, sa = extents[a]
+                eb, sb = extents[b]
+                if not ea or not eb:
+                    continue
+                if sa.shape_type == 13 or sb.shape_type == 13:
+                    continue
+                # A wireframe's segments intentionally meet and cross.  That
+                # is not text obstruction; keep line/text and text/text checks.
+                has_text_a = sa.has_text_frame and sa.text_frame.text.strip()
+                has_text_b = sb.has_text_frame and sb.text_frame.text.strip()
+                if not has_text_a and not has_text_b:
+                    continue
+                if _overlap(ea, eb):
+                    report['overlap'].append((i, sa.name, sb.name))
+        # 溢出
+        for sh in shapes:
+            if not sh.has_text_frame or not sh.text_frame.text.strip():
+                continue
+            font_pt = 18
+            for _, size, _ in _run_info(sh):
+                font_pt = size
+                break
+            est = _overflow_est(sh.text_frame.text, font_pt, _bbox(sh))
+            if est:
+                report['overflow'].append((i, sh.name, est))
+    return report
+
+def _fmt(report):
+    L = []
+    L.append("=== PPT 检查报告 ===")
+    L.append(f"页数: {report['slides']}")
+    L.append(f"\n【1. 字体】非模板字体: {len(report['fonts']['unexpected'])} 处")
+    for slide, sh, font, size in report['fonts']['unexpected']:
+        L.append(f"  第{slide}页 [{sh}] 字体={font} ({size}pt)")
+    L.append(f"\n【2. 配色】非模板文字色: {len(report['colors']['unexpected'])} 处")
+    for slide, sh, color in report['colors']['unexpected']:
+        L.append(f"  第{slide}页 [{sh}] 颜色=#{color}")
+    L.append("\n【3. 标题对齐】各页主标题横向位置:")
+    xs = [t['x_in'] for t in report['titles']]
+    for t in report['titles']:
+        L.append(f"  第{t['slide']}页 x={t['x_in']}in ({t['size']}pt)")
+    if xs:
+        mode = max(set(xs), key=xs.count)
+        dev = [t for t in report['titles'] if abs(t['x_in'] - mode) > 0.5]
+        L.append(f"  主流位置 {mode}in，偏离>0.5in: {len(dev)} 页")
+        for t in dev:
+            L.append(f"    第{t['slide']}页 x={t['x_in']}in")
+    L.append(f"\n【4. 文字遮挡】重叠: {len(report['overlap'])} 处")
+    for slide, na, nb in report['overlap']:
+        L.append(f"  第{slide}页: [{na}] 与 [{nb}] 重叠")
+    L.append(f"\n【5. 文本溢出】可能溢出: {len(report['overflow'])} 处")
+    for slide, sh, info in report['overflow']:
+        L.append(f"  第{slide}页 [{sh}] 需 {info['need_lines']} 行 > 可容 {info['fit_lines']} 行 ({info['font_pt']}pt)")
+    L.append(f"\n【6. 出界】: {len(report['out_of_bounds'])} 处")
+    for slide, sh in report['out_of_bounds']:
+        L.append(f"  第{slide}页 [{sh}] 超出边界")
+    return "\n".join(L)
+
+if __name__ == '__main__':
+    if len(sys.argv) < 2:
+        print("用法: python3 check.py <input.pptx> [--json]")
+        sys.exit(1)
+    rep = check(sys.argv[1])
+    print(_fmt(rep) if '--json' not in sys.argv else json.dumps(rep, ensure_ascii=False, indent=2))

package/config.json

@@ -0,0 +1,5 @@
+{
+  "pexels_key": "",
+  "template": "",
+  "logo": ""
+}

package/contact_sheet.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""Compose rendered slides into one contact sheet for a thumbnail review.
+
+Visual direction requires looking at the deck as a whole before inspecting a
+single page at full size. This tool is deliberately small: it only arranges the
+PNGs produced by ``render_ppt.py`` and writes one image plus optional page
+labels, so the reviewer can judge rhythm and density in one glance.
+"""
+from __future__ import annotations
+
+import argparse
+import re
+from pathlib import Path
+
+from PIL import Image, ImageDraw, ImageFont
+
+
+def natural_key(path: Path):
+    parts = re.split(r"(\d+)", path.stem)
+    return [int(part) if part.isdigit() else part for part in parts]
+
+
+def load_pages(source: Path) -> list[Path]:
+    if source.is_dir():
+        candidates = sorted(source.glob("*.png"), key=natural_key)
+    elif source.is_file() and source.suffix.lower() in {".png", ".jpg", ".jpeg"}:
+        candidates = [source]
+    else:
+        raise SystemExit("contact_sheet: pass a render directory (or one PNG)")
+    pages = [path for path in candidates if path.is_file()]
+    if not pages:
+        raise SystemExit(f"contact_sheet: no PNG pages in {source}")
+    return pages
+
+
+def label_font(size: int):
+    for path in ("/usr/share/fonts/opentype/noto/NotoSansCJK-Bold.ttc",
+                 "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf"):
+        try:
+            return ImageFont.truetype(path, size)
+        except OSError:
+            continue
+    return ImageFont.load_default()
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__,
+                                     formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("source", type=Path, help="directory from render_ppt.py")
+    parser.add_argument("--out", type=Path, required=True)
+    parser.add_argument("--cols", type=int, default=4)
+    parser.add_argument("--width", type=int, default=480, help="thumbnail width in px")
+    parser.add_argument("--gap", type=int, default=14)
+    parser.add_argument("--background", default="#0B1324")
+    parser.add_argument("--labels", action="store_true", help="draw page numbers")
+    args = parser.parse_args()
+
+    pages = load_pages(args.source)
+    thumbs = []
+    for page in pages:
+        with Image.open(page) as source:
+            image = source.convert("RGB")
+        height = max(1, round(image.height * args.width / image.width))
+        thumbs.append(image.resize((args.width, height), Image.LANCZOS))
+    label_h = 24 if args.labels else 0
+    cell_h = max(image.height for image in thumbs) + label_h
+    cols = max(1, min(args.cols, len(thumbs)))
+    rows = (len(thumbs) + cols - 1) // cols
+    width = cols * args.width + (cols + 1) * args.gap
+    height = rows * cell_h + (rows + 1) * args.gap
+    sheet = Image.new("RGB", (width, height), args.background)
+    draw = ImageDraw.Draw(sheet)
+    font = label_font(max(12, args.width // 32))
+    for index, image in enumerate(thumbs):
+        left = args.gap + (index % cols) * (args.width + args.gap)
+        top = args.gap + (index // cols) * (cell_h + args.gap)
+        sheet.paste(image, (left, top + label_h + (cell_h - label_h - image.height) // 2))
+        if args.labels:
+            text = f"{index + 1:02d}"
+            draw.text((left + 2, top + 3), text, fill="#FFFFFF", font=font)
+    args.out.parent.mkdir(parents=True, exist_ok=True)
+    sheet.save(args.out, "PNG")
+    print(f"contact_sheet: {len(thumbs)} pages -> {args.out} ({sheet.width}x{sheet.height})")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())