excel2ppt-studio 0.7.1__py3-none-any.whl

excel2ppt_studio/__init__.py

@@ -0,0 +1,3 @@
+"""Excel2PPT Studio 核心包。"""
+
+__version__ = "0.7.1"

excel2ppt_studio/__main__.py

@@ -0,0 +1,3 @@
+from excel2ppt_studio.cli import main
+
+raise SystemExit(main())

excel2ppt_studio/cli.py

@@ -0,0 +1,312 @@
+"""命令行入口：``e2p inspect|suggest|build``。"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from collections.abc import Sequence
+
+from .core.excel_images import ExcelImageError
+from .core.excel_reader import ExcelDataError, read_excel
+from .core.mapping import ProfileError, build_profile, load_profile, save_profile
+from .core.model import Profile
+from .core.renderer import RenderError, render
+from .core.template_health import check_template
+from .core.template_scanner import TemplateError, scan_template
+from .core.verifier import VerifyError, verify_file
+
+
+def _print_fields(info) -> None:
+    print(f"模板：{info.path}")
+    print(
+        f"第 {info.slide_index} 页 / 共 {info.slide_count} 页  "
+        f"尺寸 {info.width / 360000:.2f}×{info.height / 360000:.2f} cm"
+    )
+    if info.warnings:
+        print("警告：")
+        for w in info.warnings:
+            print(f"  - {w}")
+    print()
+    header = f"{'ID':<12}{'类型':<8}{'角色':<10}{'位置(cm)':<26}{'内容 / 槽位'}"
+    print(header)
+    print("-" * 96)
+    for f in info.fields:
+        x, y, w, h = f.rect.cm
+        pos = f"({x},{y}) {w}×{h}"
+        if f.kind == "table" and f.table:
+            content = f"表格 {f.table.rows}×{f.table.cols}"
+        elif f.kind == "image":
+            content = f"图片 {f.image.width_px}×{f.image.height_px}" if f.image else "图片"
+        elif f.kind == "chart":
+            content = "图表"
+        else:
+            content = (f.text or "").replace("\n", " / ")[:40]
+        slots = f"  [槽位: {', '.join(f.slot_names)}]" if f.slot_names else ""
+        print(f"{f.id:<12}{f.kind:<8}{f.role:<10}{pos:<26}{content}{slots}")
+    print()
+    print(f"共 {len(info.fields)} 个元素，其中带槽位 {sum(1 for f in info.fields if f.slots)} 个。")
+
+
+def cmd_inspect(args: argparse.Namespace) -> int:
+    info = scan_template(args.template, args.slide)
+    if args.json:
+        with open(args.json, "w", encoding="utf-8") as f:
+            json.dump(info.to_dict(), f, ensure_ascii=False, indent=2)
+            f.write("\n")
+        print(f"已写出：{args.json}")
+    else:
+        _print_fields(info)
+    return 0
+
+
+def cmd_suggest(args: argparse.Namespace) -> int:
+    info = scan_template(args.template, args.slide)
+    sheet = read_excel(args.excel, args.sheet or None, args.header_row)
+    profile, notes = build_profile(
+        args.template,
+        args.excel,
+        info,
+        sheet.sheet,
+        sheet.columns,
+        args.threshold,
+        header_row=args.header_row,
+    )
+    print(f"Excel：{os.path.abspath(args.excel)} / 工作表「{sheet.sheet}」")
+    print(f"数据行：{len(sheet.rows)}  列：{', '.join(sheet.column_names)}")
+    print()
+    total_slots = sum(len(f.slots) for f in info.fields if f.kind == "text")
+    print(f"自动匹配 {len(profile.bindings)} 项（文本槽位共 {total_slots} 个）")
+    for note in notes:
+        print(f"  ! {note}")
+    out = args.out or "profile.json"
+    save_profile(profile, out)
+    print(f"\nProfile 已保存：{os.path.abspath(out)}")
+    print("请人工检查后执行：e2p build --profile <该文件> --out <输出.pptx>")
+    return 0
+
+
+def cmd_titles(args: argparse.Namespace) -> int:
+    from .core.titles import TitleError, generate_titles, load_titles, resolve_api_key
+
+    sheet = read_excel(args.excel, args.sheet or None, args.header_row)
+    if args.column not in sheet.column_names:
+        print(f"错误：列不存在：{args.column}。可用列：{'、'.join(sheet.column_names)}", file=sys.stderr)
+        return 1
+
+    def to_text(value) -> str:
+        if value is None:
+            return ""
+        if hasattr(value, "isoformat"):
+            return value.isoformat()
+        return str(value).strip()
+
+    items = []
+    for row in sheet.rows[: args.limit or None]:
+        text = to_text(row.get(args.column))
+        if text:
+            items.append((to_text(row.get(args.key)) or str(len(items) + 1), text))
+
+    try:
+        if args.from_file:
+            titles = load_titles(args.from_file)
+        else:
+            titles = generate_titles(
+                items,
+                resolve_api_key(args.api_key),
+                args.base_url,
+                args.model,
+            )
+    except TitleError as exc:
+        print(f"错误：{exc}", file=sys.stderr)
+        return 1
+
+    out = args.out or "titles.json"
+    with open(out, "w", encoding="utf-8") as f:
+        json.dump(titles, f, ensure_ascii=False, indent=1)
+        f.write("\n")
+    print(f"已生成 {len(titles)} 条短标题 → {os.path.abspath(out)}")
+    long_titles = [(k, v) for k, v in titles.items() if len(v) > 16]
+    if long_titles:
+        print(f"警告：{len(long_titles)} 条超过 16 字，建议人工压缩。")
+    return 0
+
+
+def cmd_build(args: argparse.Namespace) -> int:
+    profile: Profile = load_profile(args.profile)
+    excel = args.excel or profile.excel
+    template = args.template or profile.template
+    if not excel or not template:
+        print("错误：Profile 缺少 Excel 或模板路径，请用 --excel/--template 指定。", file=sys.stderr)
+        return 1
+
+    def progress(done: int, total: int) -> None:
+        if not args.quiet and not getattr(args, "json", False):
+            print(f"\r渲染 {done}/{total}", end="", flush=True)
+
+    result = render(template, profile, out=args.out, excel=excel, on_progress=progress)
+    if args.json:
+        print(
+            json.dumps(
+                {
+                    "ok": True,
+                    "output": result.output,
+                    "rows": result.rows,
+                    "slides": result.slides,
+                    "replaced": result.replaced,
+                    "warnings": result.warnings,
+                },
+                ensure_ascii=False,
+            )
+        )
+        return 0
+    if not args.quiet:
+        print()
+    print(f"完成：{result.rows} 行数据 → {result.slides} 页幻灯片，替换 {result.replaced} 处")
+    if result.warnings:
+        print("警告：")
+        for w in result.warnings:
+            print(f"  - {w}")
+    print(f"输出：{result.output}")
+    return 0
+
+
+def cmd_web(args: argparse.Namespace) -> int:
+    from .web.app import run
+
+    run(host=args.host, port=args.port, open_browser=not args.no_browser)
+    return 0
+
+
+def cmd_verify(args: argparse.Namespace) -> int:
+    result = verify_file(
+        args.template,
+        args.output,
+        slide_index=args.slide,
+        allow_image_resize=not args.strict_images,
+        max_pages=args.max_pages,
+    )
+    if getattr(args, "json", False):
+        data = result.to_dict()
+        data["ok"] = result.ok
+        print(json.dumps(data, ensure_ascii=False))
+        return 0 if result.ok else 1
+    print(f"校验：{result.pages_checked} 页 / {result.shapes_checked} 个元素")
+    for issue in result.issues:
+        page = f"（第 {issue.page + 1} 页）" if issue.page is not None else ""
+        print(f"  [{issue.level}] {issue.message}{page}")
+    if result.ok:
+        print("结论：通过（无结构性差异）")
+        return 0
+    print("结论：失败（存在版式/格式差异）")
+    return 1
+
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    report = check_template(args.template, args.slide, args.excel)
+    if getattr(args, "json", False):
+        print(json.dumps(report.to_dict(), ensure_ascii=False))
+        return 0 if not report.errors else 1
+    print(f"模板体检：{report.score} 分（{report.template}）")
+    for issue in report.issues:
+        tag = {"error": "错误", "warning": "警告", "info": "信息"}.get(issue.level, issue.level)
+        ref = f" [{issue.field_id}]" if issue.field_id else ""
+        print(f"  [{tag}] {issue.message}{ref}")
+    return 0 if not report.errors else 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="e2p",
+        description="Excel2PPT Studio：按单页 PPT 模板把 Excel 逐行生成多页幻灯片。",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_inspect = sub.add_parser("inspect", help="查看模板元素清单")
+    p_inspect.add_argument("template", help="模板 .pptx 路径")
+    p_inspect.add_argument("--slide", type=int, default=0, help="母版页索引，从 0 开始（默认 0）")
+    p_inspect.add_argument("--json", help="把清单写成 JSON")
+    p_inspect.set_defaults(func=cmd_inspect)
+
+    p_suggest = sub.add_parser("suggest", help="按列名自动生成初始映射")
+    p_suggest.add_argument("--excel", required=True, help="Excel 路径")
+    p_suggest.add_argument("--template", required=True, help="模板 .pptx 路径")
+    p_suggest.add_argument("--slide", type=int, default=0, help="母版页索引（默认 0）")
+    p_suggest.add_argument("--sheet", help="工作表名（默认第一个）")
+    p_suggest.add_argument("--header-row", type=int, default=1, help="表头行号（默认 1）")
+    p_suggest.add_argument("--threshold", type=int, default=60, help="相似度阈值 0-100（默认 60）")
+    p_suggest.add_argument("--out", help="Profile 输出路径（默认 profile.json）")
+    p_suggest.set_defaults(func=cmd_suggest)
+
+    p_titles = sub.add_parser("titles", help="用 AI 生成 ≤16 字语义短标题")
+    p_titles.add_argument("--excel", required=True, help="Excel 路径")
+    p_titles.add_argument("--sheet", help="工作表名（默认第一个）")
+    p_titles.add_argument("--column", required=True, help="问题描述列名")
+    p_titles.add_argument("--key", default="序号", help="序号列名（默认「序号」）")
+    p_titles.add_argument("--header-row", type=int, default=1, help="表头行号（默认 1）")
+    p_titles.add_argument("--limit", type=int, default=0, help="只处理前 N 行（0 = 全部）")
+    p_titles.add_argument("--out", help="输出 JSON（默认 titles.json）")
+    p_titles.add_argument("--api-key", help="DeepSeek/OpenAI 兼容 API key（或 DEEPSEEK_API_KEY）")
+    p_titles.add_argument("--base-url", default="https://api.deepseek.com", help="API 基址")
+    p_titles.add_argument("--model", default="deepseek-chat", help="模型名")
+    p_titles.add_argument("--from-file", help="不调 API，直接读取已生成的 {序号:标题} JSON")
+    p_titles.set_defaults(func=cmd_titles)
+
+    p_build = sub.add_parser("build", help="按 Profile 生成 PPT")
+    p_build.add_argument("--profile", required=True, help="Profile JSON 路径")
+    p_build.add_argument("--excel", help="覆盖 Profile 里的 Excel 路径")
+    p_build.add_argument("--template", help="覆盖 Profile 里的模板路径")
+    p_build.add_argument("--out", help="输出 .pptx 路径")
+    p_build.add_argument("--quiet", action="store_true", help="不打印进度")
+    p_build.add_argument("--json", action="store_true", help="输出 JSON（供脚本/插件解析）")
+    p_build.set_defaults(func=cmd_build)
+
+    p_web = sub.add_parser("web", help="启动本地 Web 向导")
+    p_web.add_argument("--host", default="127.0.0.1", help="监听地址（默认 127.0.0.1）")
+    p_web.add_argument("--port", type=int, default=8765, help="端口（默认 8765）")
+    p_web.add_argument("--no-browser", action="store_true", help="不自动打开浏览器")
+    p_web.set_defaults(func=cmd_web)
+
+    p_verify = sub.add_parser("verify", help="校验输出与模板是否零漂移")
+    p_verify.add_argument("--template", required=True, help="模板 .pptx")
+    p_verify.add_argument("--output", required=True, help="生成结果 .pptx")
+    p_verify.add_argument("--slide", type=int, default=0, help="模板母版页索引（默认 0）")
+    p_verify.add_argument("--max-pages", type=int, default=0, help="最多校验几页（0 = 全部）")
+    p_verify.add_argument(
+        "--strict-images",
+        action="store_true",
+        help="图片尺寸变化也视为错误（默认只告警，因为 contain 会等比缩放）",
+    )
+    p_verify.add_argument("--json", action="store_true", help="输出 JSON（供脚本/插件解析）")
+    p_verify.set_defaults(func=cmd_verify)
+
+    p_doctor = sub.add_parser("doctor", help="模板体检：结构、可映射性、格式一致性")
+    p_doctor.add_argument("--template", required=True, help="模板 .pptx")
+    p_doctor.add_argument("--slide", type=int, default=0, help="模板页索引（默认 0）")
+    p_doctor.add_argument("--excel", help="可选：Excel 路径，用于交叉检查图片列")
+    p_doctor.add_argument("--json", action="store_true", help="输出 JSON")
+    p_doctor.set_defaults(func=cmd_doctor)
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if getattr(args, "json", False):
+        # JSON 供脚本/插件解析：固定 UTF-8，避免 Windows 管道按 GBK 编码
+        for stream in (sys.stdout, sys.stderr):
+            if hasattr(stream, "reconfigure"):
+                stream.reconfigure(encoding="utf-8")
+    try:
+        return int(args.func(args))
+    except (TemplateError, ExcelDataError, ExcelImageError, ProfileError, RenderError, VerifyError) as exc:
+        print(f"错误：{exc}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print("已取消。", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

excel2ppt_studio/core/__init__.py

@@ -0,0 +1 @@
+"""核心能力：解析、映射、渲染。"""

excel2ppt_studio/core/excel_images.py

@@ -0,0 +1,85 @@
+"""从 xlsx 包内提取 WPS「嵌入单元格图片」（DISPIMG）。
+
+与 `excel2ppt` 技能同源，改为抛异常而非 ``sys.exit``，并支持内容哈希缓存。
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import zipfile
+
+
+class ExcelImageError(Exception):
+    """Excel 内嵌图片提取失败（可读中文信息）。"""
+
+
+def extract_cell_images(
+    xlsx_path: str, out_dir: str, only: set[str] | None = None
+) -> dict[str, str]:
+    """提取 ``xl/cellimages.xml`` 引用的图片，返回 ``{图片ID: 本地路径}``。
+
+    ``only`` 非空时只落盘这些 ID，避免为预览一页解压整包 300MB 图片。
+    图片按内容 SHA256 命名，重复内容只落盘一次。
+    """
+    if not os.path.isfile(xlsx_path):
+        raise ExcelImageError(f"Excel 文件不存在：{xlsx_path}")
+    os.makedirs(out_dir, exist_ok=True)
+
+    id_to_file: dict[str, str] = {}
+    skipped = 0
+    with zipfile.ZipFile(xlsx_path, "r") as z:
+        names = set(z.namelist())
+        if "xl/cellimages.xml" not in names:
+            raise ExcelImageError(
+                "该 Excel 内没有 xl/cellimages.xml，未发现 WPS「嵌入单元格图片」。\n"
+                "  典型原因：①图片是浮动图片而非嵌入单元格；②文件经其他软件转存丢失了 cellimages。\n"
+                "  处理：在 WPS 中选中图片设为「嵌入单元格」后另存，或改用无图模式。"
+            )
+        if "xl/_rels/cellimages.xml.rels" not in names:
+            raise ExcelImageError("Excel 缺少 xl/_rels/cellimages.xml.rels，cellimages 引用关系丢失。")
+
+        ci = z.read("xl/cellimages.xml").decode("utf-8")
+        ids = re.findall(r'name="(ID_[A-Fa-f0-9]+)"', ci)
+        rids = re.findall(r'r:embed="(rId\d+)"', ci)
+
+        rels = z.read("xl/_rels/cellimages.xml.rels").decode("utf-8")
+        rid_to_media = dict(
+            re.findall(r'Id="(rId\d+)"[^>]*Target="(media/image\d+\.\w+)"', rels)
+        )
+
+        for image_id, rid in zip(ids, rids, strict=False):
+            if only is not None and image_id not in only:
+                continue
+            media = rid_to_media.get(rid)
+            if not media:
+                skipped += 1
+                continue
+            member = f"xl/{media}"
+            if member not in names:
+                skipped += 1
+                continue
+            data = z.read(member)
+            digest = hashlib.sha256(data).hexdigest()[:16]
+            ext = media.rsplit(".", 1)[-1].lower()
+            path = os.path.join(out_dir, f"{digest}.{ext}")
+            if not os.path.exists(path):
+                with open(path, "wb") as f:
+                    f.write(data)
+            id_to_file[image_id] = path
+
+    if skipped:
+        # 调用方负责转成 WARNING；这里只保留计数，不静默
+        id_to_file["__skipped__"] = str(skipped)
+    return id_to_file
+
+
+def list_dispimg_ids(xlsx_path: str) -> dict[str, str]:
+    """只解析 ID → media 成员名，不解压图片（用于快速识别图片列）。"""
+    with zipfile.ZipFile(xlsx_path, "r") as z:
+        if "xl/cellimages.xml" not in z.namelist():
+            return {}
+        ci = z.read("xl/cellimages.xml").decode("utf-8")
+        ids = re.findall(r'name="(ID_[A-Fa-f0-9]+)"', ci)
+        return {i: "" for i in ids}

excel2ppt_studio/core/excel_reader.py

@@ -0,0 +1,256 @@
+"""读取 Excel：表头校验、类型推断、行数据。
+
+约定：首行（``header_row``）必须是表头；表头不得为空或重复。
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+from openpyxl import load_workbook
+
+from .model import Column
+
+_IMAGE_ID = re.compile(r"^ID_[A-Fa-f0-9]{6,}$")
+_DISPIMG_FORMULA = re.compile(r"DISPIMG\(\s*\"?(ID_[A-Fa-f0-9]+)\"?", re.IGNORECASE)
+_IMAGE_PATH = re.compile(r"\.(png|jpe?g|bmp|gif|webp)$", re.IGNORECASE)
+_MAX_SCAN = 200
+
+
+class ExcelDataError(Exception):
+    """Excel 结构或数据不符合约定。"""
+
+
+@dataclass
+class SheetData:
+    path: str
+    sheet: str
+    columns: list[Column] = field(default_factory=list)
+    rows: list[dict[str, Any]] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+    @property
+    def column_names(self) -> list[str]:
+        return [c.name for c in self.columns]
+
+    @property
+    def header_columns(self) -> dict[str, str]:
+        return {c.name: c.name for c in self.columns}
+
+
+def _cell_text(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, (_dt.datetime, _dt.date)):
+        return value.isoformat(sep=" ") if isinstance(value, _dt.datetime) else value.isoformat()
+    return str(value).strip()
+
+
+def _infer_dtype(name: str, values: list[Any]) -> str:
+    sample = [v for v in values if v is not None and _cell_text(v) != ""]
+    if not sample:
+        return "text"
+    texts = [_cell_text(v) for v in sample]
+    if any(_IMAGE_ID.match(t) or _DISPIMG_FORMULA.search(t) for t in texts):
+        return "image"
+    path_like = sum(1 for t in texts if _IMAGE_PATH.search(t))
+    if path_like >= max(1, int(len(texts) * 0.6)):
+        return "image"
+    nums = 0
+    dates = 0
+    bools = 0
+    for v in sample:
+        if isinstance(v, bool):
+            bools += 1
+        elif isinstance(v, (int, float)):
+            nums += 1
+        elif isinstance(v, (_dt.datetime, _dt.date)):
+            dates += 1
+    total = len(sample)
+    if bools == total:
+        return "bool"
+    if dates >= total * 0.8:
+        return "date"
+    if nums >= total * 0.8:
+        return "number"
+    return "text"
+
+
+def _read_header(ws, header_row: int) -> tuple[list[str], list[str]]:
+    values = [ws.cell(row=header_row, column=c).value for c in range(1, ws.max_column + 1)]
+    # 右侧因残留格式撑出的空列不算表头：从尾部裁掉，中间的空列仍然报错
+    while values and _cell_text(values[-1]) == "":
+        values.pop()
+    names: list[str] = []
+    warnings: list[str] = []
+    seen: set[str] = set()
+    for idx, v in enumerate(values, start=1):
+        text = _cell_text(v)
+        if not text:
+            raise ExcelDataError(
+                f"第 {idx} 列表头为空（表头行 = 第 {header_row} 行）。"
+                "请补全表头，或把 header_row 指到真正的表头行。"
+            )
+        if text in seen:
+            # 真实台账常见重名列（如两个「归档率」），自动加序号并在结果里告警
+            suffix = 2
+            while f"{text}({suffix})" in seen:
+                suffix += 1
+            renamed = f"{text}({suffix})"
+            warnings.append(f"表头「{text}」重复，已重命名为「{renamed}」")
+            text = renamed
+        seen.add(text)
+        names.append(text)
+    if not names:
+        raise ExcelDataError(f"第 {header_row} 行没有检测到表头。")
+    return names, warnings
+
+
+def _header_merged_ranges(path: str, sheet: str, header_row: int) -> list[str]:
+    """仅在表头出现空单元格时调用：用非只读模式确认是否由合并导致。"""
+    try:
+        wb = load_workbook(path, data_only=True, read_only=False)
+    except Exception:  # noqa: BLE001 - 检测失败不影响主流程
+        return []
+    try:
+        ws = wb[sheet]
+        return [
+            str(rng)
+            for rng in ws.merged_cells.ranges
+            if rng.min_row <= header_row <= rng.max_row
+        ]
+    except Exception:  # noqa: BLE001
+        return []
+    finally:
+        try:
+            wb.close()
+        except Exception:  # noqa: BLE001
+            pass
+
+
+def _uncached_formula_count(
+    path: str, sheet: str, header_row: int, max_col: int
+) -> int:
+    """统计「有公式但没有缓存值」的单元格数（文件未在 Excel/WPS 中重算保存）。"""
+    count = 0
+    wb_f = None
+    wb_v = None
+    try:
+        wb_f = load_workbook(path, data_only=False, read_only=True)
+        wb_v = load_workbook(path, data_only=True, read_only=True)
+        ws_f = wb_f[sheet]
+        ws_v = wb_v[sheet]
+        for row in ws_f.iter_rows(min_row=header_row + 1, max_col=max_col):
+            for cell in row:
+                value = cell.value
+                if isinstance(value, str) and value.startswith("="):
+                    cached = ws_v.cell(row=cell.row, column=cell.column).value
+                    if cached in (None, ""):
+                        count += 1
+    except Exception:  # noqa: BLE001 - 公式扫描失败不影响主流程
+        return 0
+    finally:
+        for wb in (wb_f, wb_v):
+            if wb is not None:
+                try:
+                    wb.close()
+                except Exception:  # noqa: BLE001
+                    pass
+    return count
+
+
+def read_excel(
+    path: str,
+    sheet: str | None = None,
+    header_row: int = 1,
+) -> SheetData:
+    """读取指定工作表，返回列元数据与逐行字典。"""
+    try:
+        wb_values = load_workbook(path, data_only=True, read_only=True)
+    except Exception as exc:  # noqa: BLE001 - 统一转为可读错误
+        raise ExcelDataError(f"无法打开 Excel：{path}（{exc}）") from exc
+
+    try:
+        if sheet is None:
+            sheet = wb_values.sheetnames[0]
+        if sheet not in wb_values.sheetnames:
+            raise ExcelDataError(
+                f"工作表不存在：{sheet}。可用工作表：{'、'.join(wb_values.sheetnames)}"
+            )
+        ws = wb_values[sheet]
+        try:
+            names, header_warnings = _read_header(ws, header_row)
+        except ExcelDataError as exc:
+            # 只有表头为空时才值得用非只读模式检查合并（大文件打开代价高）
+            merged = _header_merged_ranges(path, sheet, header_row)
+            if merged:
+                raise ExcelDataError(
+                    f"表头行（第 {header_row} 行）存在合并单元格：{'、'.join(merged[:5])}。"
+                    "请先在 Excel/WPS 中取消合并，把表头拆成单行后再试。"
+                ) from exc
+            raise
+
+        raw_rows: list[list[Any]] = []
+        for row in ws.iter_rows(min_row=header_row + 1, max_col=len(names), values_only=True):
+            if all(_cell_text(v) == "" for v in row):
+                continue
+            raw_rows.append(list(row))
+
+        if not raw_rows:
+            raise ExcelDataError(f"工作表「{sheet}」在表头之后没有有效数据行。")
+
+        warnings: list[str] = list(header_warnings)
+        if any(v is None for r in raw_rows for v in r):
+            uncached = _uncached_formula_count(path, sheet, header_row, len(names))
+            if uncached:
+                warnings.append(
+                    f"{uncached} 个公式单元格没有缓存值（文件可能未在 Excel/WPS 中重算保存），"
+                    "这些单元格会被当作空值处理。"
+                )
+
+        columns: list[Column] = []
+        for c_idx, name in enumerate(names):
+            values = [r[c_idx] for r in raw_rows[:_MAX_SCAN]]
+            dtype = _infer_dtype(name, values)
+            samples = [_cell_text(v) for v in values if _cell_text(v)][:5]
+            columns.append(Column(index=c_idx, name=name, dtype=dtype, samples=samples))
+
+        rows: list[dict[str, Any]] = []
+        for r in raw_rows:
+            rows.append({name: r[c_idx] for c_idx, name in enumerate(names)})
+
+        return SheetData(
+            path=path, sheet=sheet, columns=columns, rows=rows, warnings=warnings
+        )
+    finally:
+        wb_values.close()
+
+
+def read_dispimg_formulas(path: str, sheet: str | None = None) -> dict[tuple[int, int], str]:
+    """读取公式文本，返回 ``{(行, 列): 图片ID}``，用于识别 DISPIMG 单元格。
+
+    ``sheet`` 为 None 时按工作表顺序查找，返回第一个含 DISPIMG 的工作表结果
+    （台账常把「使用说明」放在第一页，不能只看第一页）。
+    """
+    wb = load_workbook(path, data_only=False, read_only=True)
+    try:
+        candidates = [sheet] if sheet else list(wb.sheetnames)
+        for name in candidates:
+            if name not in wb.sheetnames:
+                continue
+            ws = wb[name]
+            out: dict[tuple[int, int], str] = {}
+            for row in ws.iter_rows():
+                for cell in row:
+                    if isinstance(cell.value, str):
+                        m = _DISPIMG_FORMULA.search(cell.value)
+                        if m:
+                            out[(cell.row, cell.column)] = m.group(1)
+            if out:
+                return out
+        return {}
+    finally:
+        wb.close()