minimal-agent 0.8.2 → 0.10.0

package/skills/pptx/scripts/opc_check.py

@@ -0,0 +1,339 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+opc_check.py —— OOXML（pptx/docx/xlsx 本质都是 OPC zip 包）的「忠实合规校验 + 重打包」工具。
+
+为什么需要这个脚本？
+====================
+pptx/docx/xlsx 文件本质是一个遵循 OPC（Open Packaging Conventions, ECMA-376 第 2 部分）
+规范的 zip 包。PowerPoint / Word / Excel 打开文件时会做**严格的 OPC 校验**，任何一处不合规
+都可能被判「需要修复」、修复后内容丢失。
+
+但是——「某个库能 load/import ≠ 目标程序（PowerPoint/Word/Excel）能干净打开」。
+python-pptx / python-docx / openpyxl 这类库非常宽容：它们会忽略 zip 里的目录条目、不在乎
+[Content_Types].xml 是不是第一个条目，照样 load 成功。于是「用 python-pptx 重新打开来验证」
+会**误报通过**，让损坏的包溜过验收闸门（这正是本仓库踩过的坑：PptxGenJS 在 Bun 下用 JSZip
+产出含 19 个目录条目 + STORE 无压缩的非合规包，python-pptx 照常加载，PowerPoint 却判损坏）。
+
+因此本脚本**绝不依赖任何宽容的高层库**，只用标准库（zipfile / xml.etree / posixpath / re），
+直接从 zip 字节层面 + OPC 规范层面做校验，忠实于最终消费者（Office）。
+
+校验项（任一不合规 → 非零退出码 + 打印具体问题）
+================================================
+1. zip 里没有目录条目（条目名以 "/" 结尾的应为 0 个）。
+   —— Office 严格 OPC 校验不接受目录条目；JSZip/Bun 常错误地写入它们。
+2. [Content_Types].xml 是 zip 的第一个条目。
+   —— OPC 规范虽未强制顺序，但 Office 的快速解析依赖它在前；不在首位常触发「需要修复」。
+3. 所有 .rels 里的内部 Target（TargetMode != External）都能解析到真实存在的部件。
+   —— 悬空关系（指向不存在的部件）是最常见的「文件损坏」根因。
+4. 没有 0 字节的媒体文件（ppt/media/、word/media/、xl/media/ 下）。
+   —— 空图片 = 渲染失败 / 修复时被丢弃。
+5. 所有 .xml / .rels 都是良构（well-formed）XML。
+   —— 坏 XML 直接导致 Office 拒绝加载该部件。
+
+6. [Content_Types].xml 里的 <Override PartName="..."> 都能解析到真实存在的部件。
+   —— 「孤儿 Override」是「opc_check 报 PASSED 但 PowerPoint 判修复」的最常见根因：
+   OPC 规范允许这种孤儿，但 PowerPoint 严格对账「声明 vs 实物」时把数量严重不符的包判损坏。
+   典型成因：生成端把另一种 part 的数量当成这种 part 的数量
+   （例如 18 张 slide 却声明了 18 个 slideMaster{n}.xml，实际只有 1 个母版）。
+
+用法
+====
+    python opc_check.py <file>                 # 校验，合规退出 0，不合规退出 1
+    python opc_check.py <file> --verbose       # 同上，额外打印每项 PASSED 明细
+    python opc_check.py --repack <in> <out>    # OPC 重打包：把不合规包修回合规
+
+重打包（--repack）做了什么？
+===========================
+读入源包里所有**非目录**条目，按「[Content_Types].xml 第一、_rels/.rels 第二、其余其后」的
+顺序，用 DEFLATE 压缩重写一个干净 zip，并自动删除 [Content_Types].xml 里的孤儿 Override。
+这样即便生成器（如 Bun 下的 PptxGenJS）产出不合规包，也能一步修回合规——重打包后再跑一次校验即应全绿。
+"""
+
+import argparse
+import posixpath
+import re
+import sys
+import zipfile
+import xml.etree.ElementTree as ET
+
+# OPC 关系命名空间：.rels 文件里 <Relationship> 元素所在的命名空间，固定不变。
+RELATIONSHIPS_NS = "http://schemas.openxmlformats.org/package/2006/relationships"
+CONTENT_TYPES_NS = "http://schemas.openxmlformats.org/package/2006/content-types"
+
+# 三大 OOXML 家族放媒体（图片等）的目录前缀，用于「0 字节媒体」检查。
+MEDIA_DIRS = ("ppt/media/", "word/media/", "xl/media/")
+
+CONTENT_TYPES = "[Content_Types].xml"
+
+# 避免清理 [Content_Types].xml 后 ElementTree 写出 ns0 前缀。
+ET.register_namespace("", CONTENT_TYPES_NS)
+
+
+def _normalize_part_target(rels_name: str, target: str) -> str:
+    """
+    把一条关系里的 Target 解析成「包内绝对部件名」（不带前导 /）。
+
+    OPC 里 .rels 的 Target 是相对于「该 .rels 所描述部件所在目录」的相对路径：
+    - 根关系 _rels/.rels 描述的是包根 → 基准目录是包根 ""。
+    - 部件关系 <dir>/_rels/<part>.xml.rels 描述的是 <dir>/<part>.xml → 基准目录是 <dir>。
+    Target 也可能以 "/" 开头表示「相对包根的绝对路径」。
+    返回归一化后的 posix 路径（用 posixpath，因为 zip 内部一律用正斜杠）。
+    """
+    if target.startswith("/"):
+        # 绝对路径：直接去掉前导斜杠即为部件名。
+        return target.lstrip("/")
+
+    # 求 .rels 的基准目录。rels_name 形如 "_rels/.rels" 或 "ppt/_rels/presentation.xml.rels"。
+    # 基准目录 = .rels 所在目录的父目录（因为 _rels 子目录描述的是其上一级里的部件）。
+    rels_dir = posixpath.dirname(rels_name)          # 如 "ppt/_rels"
+    base_dir = posixpath.dirname(rels_dir)           # 如 "ppt"（根关系时为 ""）
+    joined = posixpath.join(base_dir, target) if base_dir else target
+    # posixpath.normpath 处理 "../" 等相对段，得到干净的部件名。
+    return posixpath.normpath(joined)
+
+
+def _content_type_override_parts(root: ET.Element) -> set[str]:
+    """返回 [Content_Types].xml 声明的 Override PartName 集合（不带前导 /）。"""
+    return {
+        child.get("PartName", "").lstrip("/")
+        for child in list(root)
+        if child.tag == f"{{{CONTENT_TYPES_NS}}}Override" and child.get("PartName")
+    }
+
+
+def _orphan_content_type_overrides(content_types_xml: bytes, present_parts: set[str]) -> list[str]:
+    """找出 [Content_Types].xml 中声明了、但 zip 里不存在的 Override 部件。"""
+    root = ET.fromstring(content_types_xml)
+    return sorted(_content_type_override_parts(root) - present_parts)
+
+
+def _clean_content_type_overrides(content_types_xml: bytes, present_parts: set[str]) -> bytes:
+    """
+    删除 [Content_Types].xml 中指向不存在部件的 Override。
+
+    若 XML 不良构，故意让 ET.ParseError 冒泡；调用方应保留原有失败语义，
+    不能用清理掩盖坏 XML。
+    """
+    root = ET.fromstring(content_types_xml)
+    removed = False
+
+    for child in list(root):
+        if child.tag != f"{{{CONTENT_TYPES_NS}}}Override":
+            continue
+        part_name = child.get("PartName", "").lstrip("/")
+        if part_name and part_name not in present_parts:
+            root.remove(child)
+            removed = True
+
+    if not removed:
+        return content_types_xml
+
+    return ET.tostring(root, encoding="utf-8", xml_declaration=True)
+
+
+def _clean_content_type_overrides_for_repack(content_types_xml: bytes, present_parts: set[str]) -> bytes:
+    """重打包路径的容错包装：坏 XML 保持原样，交给最终 check_compliance 报错。"""
+    try:
+        return _clean_content_type_overrides(content_types_xml, present_parts)
+    except ET.ParseError:
+        return content_types_xml
+
+
+def check_compliance(path: str, verbose: bool = False) -> list:
+    """
+    对 OOXML 文件做忠实 OPC 合规校验，返回「问题列表」（空列表 = 合规）。
+    每个问题是一段人话描述的字符串，方便直接打印给用户/喂回 LLM 排障。
+    """
+    problems = []
+
+    # 先确认它确实是个 zip（OOXML 包损坏到连 zip 都不是时，这里就拦下）。
+    if not zipfile.is_zipfile(path):
+        return [f"不是合法的 zip 包（OOXML 文件本质必须是 zip）：{path}"]
+
+    with zipfile.ZipFile(path, "r") as zf:
+        infos = zf.infolist()
+        # namelist 保持 zip 物理顺序，用于「第一个条目」判定。
+        names = [i.filename for i in infos]
+
+        # 现存的所有「真实部件」名集合（排除目录条目），供关系 Target 解析时核对存在性。
+        present_parts = {i.filename for i in infos if not i.filename.endswith("/")}
+
+        # ---- 校验项 1：没有目录条目 ----
+        dir_entries = [n for n in names if n.endswith("/")]
+        if dir_entries:
+            problems.append(
+                "zip 含目录条目（OPC 不允许，Office 会判损坏）："
+                + ", ".join(dir_entries)
+            )
+        elif verbose:
+            print("PASSED [1] 无目录条目")
+
+        # ---- 校验项 2：[Content_Types].xml 是第一个条目 ----
+        if CONTENT_TYPES not in present_parts:
+            problems.append(f"缺少 {CONTENT_TYPES}（OPC 必备部件）")
+        elif names and names[0] != CONTENT_TYPES:
+            problems.append(
+                f"{CONTENT_TYPES} 不是 zip 的第一个条目（首位是 '{names[0]}'）；"
+                "Office 严格解析依赖它在最前，可用 --repack 修复"
+            )
+        elif verbose:
+            print(f"PASSED [2] {CONTENT_TYPES} 位于首位")
+
+        # ---- 校验项 5（先做，因为 3 要解析 .rels XML）：所有 .xml/.rels 良构 ----
+        # 把良构检查提前，能在解析 .rels 之前就把坏 XML 的部件挑出来，避免下面重复报错。
+        malformed = set()
+        for info in infos:
+            n = info.filename
+            if n.endswith("/"):
+                continue
+            if n.lower().endswith(".xml") or n.lower().endswith(".rels"):
+                try:
+                    ET.fromstring(zf.read(n))
+                except ET.ParseError as e:
+                    malformed.add(n)
+                    problems.append(f"XML 不良构（Office 无法加载该部件）：{n} —— {e}")
+        if verbose and not malformed:
+            print("PASSED [5] 所有 .xml/.rels 均为良构 XML")
+
+        # ---- 校验项 3：所有 .rels 内部 Target 都能解析到真实部件 ----
+        dangling = []
+        for info in infos:
+            n = info.filename
+            if not n.lower().endswith(".rels") or n in malformed:
+                continue
+            try:
+                root = ET.fromstring(zf.read(n))
+            except ET.ParseError:
+                continue  # 已在校验项 5 报过
+            for rel in root.iter("{%s}Relationship" % RELATIONSHIPS_NS):
+                # 外部关系（TargetMode="External"，如 URL/超链接）不要求包内存在，跳过。
+                if rel.get("TargetMode") == "External":
+                    continue
+                target = rel.get("Target")
+                if not target:
+                    continue
+                part = _normalize_part_target(n, target)
+                if part not in present_parts:
+                    dangling.append(f"{n} → Target '{target}'（解析为部件 '{part}'，不存在）")
+        if dangling:
+            problems.append(
+                "存在悬空关系（.rels 指向不存在的部件，Office 会判损坏）：\n  "
+                + "\n  ".join(dangling)
+            )
+        elif verbose:
+            print("PASSED [3] 所有内部关系 Target 均指向存在的部件")
+
+        # ---- 校验项 6：[Content_Types].xml 的 <Override> 必须指向真实部件 ----
+        # 与校验项 3 对称：3 校验「关系指向」，6 校验「声明指向」。
+        # 依赖校验项 5（[Content_Types].xml 良构）：若已记入 malformed 则跳过。
+        if CONTENT_TYPES in present_parts and CONTENT_TYPES not in malformed:
+            try:
+                orphan = _orphan_content_type_overrides(zf.read(CONTENT_TYPES), present_parts)
+            except ET.ParseError:
+                pass
+            else:
+                if orphan:
+                    problems.append(
+                        "[Content_Types].xml 声明了 zip 里不存在的部件"
+                        "（PowerPoint 打开时常判「需要修复」）：\n  "
+                        + "\n  ".join(orphan)
+                    )
+                elif verbose:
+                    print("PASSED [6] Content_Types Override 全部指向存在的部件")
+
+        # ---- 校验项 4：没有 0 字节媒体文件 ----
+        empty_media = [
+            i.filename
+            for i in infos
+            if (not i.filename.endswith("/"))
+            and i.file_size == 0
+            and any(i.filename.startswith(d) for d in MEDIA_DIRS)
+        ]
+        if empty_media:
+            problems.append(
+                "存在 0 字节媒体文件（空图片，渲染/修复时会被丢弃）："
+                + ", ".join(empty_media)
+            )
+        elif verbose:
+            print("PASSED [4] 媒体文件均非空")
+
+    return problems
+
+
+def repack(src: str, dst: str) -> None:
+    """
+    OPC 重打包：读入源包所有非目录条目，清理孤儿 Override，再用 DEFLATE 重写干净 zip。
+    顺序约定：[Content_Types].xml 第一 → _rels/.rels 第二 → 其余其后（保持源相对顺序）。
+    """
+    with zipfile.ZipFile(src, "r") as zin:
+        # 只取真实部件，丢弃所有目录条目（这正是修复非合规包的关键一步）。
+        parts = [(i.filename, zin.read(i.filename)) for i in zin.infolist()
+                 if not i.filename.endswith("/")]
+
+    present_parts = {name for name, _ in parts}
+    parts = [
+        (
+            name,
+            _clean_content_type_overrides_for_repack(data, present_parts)
+            if name == CONTENT_TYPES
+            else data,
+        )
+        for name, data in parts
+    ]
+
+    def sort_key(item):
+        name = item[0]
+        if name == CONTENT_TYPES:
+            return (0, name)        # Content_Types 永远第一
+        if name == "_rels/.rels":
+            return (1, name)        # 根关系第二
+        return (2, name)            # 其余按名次序其后
+
+    parts.sort(key=sort_key)
+
+    with zipfile.ZipFile(dst, "w", compression=zipfile.ZIP_DEFLATED) as zout:
+        for name, data in parts:
+            # 显式指定 DEFLATE，杜绝源包里 STORE（无压缩）残留——Office 对 STORE 的兼容性更差。
+            zout.writestr(name, data, compress_type=zipfile.ZIP_DEFLATED)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="OOXML（pptx/docx/xlsx）忠实 OPC 合规校验 + 重打包工具（仅依赖标准库）"
+    )
+    parser.add_argument("file", help="要校验的 OOXML 文件（或 --repack 模式下的输入文件）")
+    parser.add_argument(
+        "--repack",
+        metavar="OUT",
+        help="重打包模式：把 file 修回合规并写到 OUT（例：--repack fixed.pptx）",
+    )
+    parser.add_argument("-v", "--verbose", action="store_true", help="打印每项 PASSED 明细")
+    args = parser.parse_args()
+
+    if args.repack:
+        repack(args.file, args.repack)
+        # 重打包后立刻自检，确保产物确实合规，否则别假装成功。
+        problems = check_compliance(args.repack, verbose=args.verbose)
+        if problems:
+            print(f"重打包到 {args.repack} 后仍存在 {len(problems)} 个问题：")
+            for p in problems:
+                print("  - " + p)
+            return 1
+        print(f"重打包完成且合规：{args.repack}")
+        return 0
+
+    problems = check_compliance(args.file, verbose=args.verbose)
+    if problems:
+        print(f"OPC 合规校验 FAILED —— {args.file} 存在 {len(problems)} 类问题：")
+        for p in problems:
+            print("  - " + p)
+        print("提示：可用 `python opc_check.py <in> --repack <out>` 一步修回合规。")
+        return 1
+
+    print(f"OPC 合规校验 PASSED —— {args.file} 是干净的 OPC 包，可被 Office 安全打开。")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/pptx/scripts/svg_fallback.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/* eslint-disable */
+// ============================================================================
+//  skills/pptx/scripts/svg_fallback.mjs
+//  ----------------------------------------------------------------------------
+//  「真 SVG 配图」落 pptx 的兜底修复管线（Node + sharp）。生成 deck 后跑一次。
+//
+//  Usage:
+//    node skills/pptx/scripts/svg_fallback.mjs deck.pptx              # 原地修复（自动备份 .bak）
+//    node skills/pptx/scripts/svg_fallback.mjs deck.pptx -o out.pptx  # 写到新文件
+//
+//  为什么需要这一步？（实测确诊，见 svg.md）
+//  ========================================
+//  PptxGenJS 的 addImage({path:'x.svg'}) 在 **Node** 下会写出 PowerPoint 原生 SVG 结构
+//  （slide xml 里 <a:blip r:embed=PNG> + <asvg:svgBlip r:embed=SVG>，{96DAC541-...} 扩展），
+//  其中 .svg 部件是真 SVG —— 所以现代 PowerPoint 能渲染、能「转换为形状」取消组合编辑。
+//  **但** PptxGenJS 在 Node 下不栅格化 SVG 的 PNG 兜底（官方 issue #401，源码直接
+//  rel.data = IMG_BROKEN / 或把 SVG 字节原样写进 .png）。后果：凡是读 PNG 兜底的消费者
+//  （LibreOffice 视觉 QA、旧版 PowerPoint、缩略图）全破图。
+//
+//  本脚本做两件事，一步交付一个「现代 + 旧版都不破图、且 OPC 合规」的 deck：
+//    1. 对每个 ppt/media/*.svg，用 sharp 渲染一张**真** PNG，覆盖它配对的兜底 .png；
+//    2. 调 opc_check.py --repack 做合规重打包（去目录条目 / [Content_Types].xml 置首 /
+//       DEFLATE / 删孤儿 Override），再 opc_check 自校验。
+//  —— 注：PptxGenJS 产出的包即便不含 SVG 也常需重打包，故本脚本对任何 deck 都安全幂等。
+//
+//  配对方式：解析每张 slide 的 blipFill —— <a:blip r:embed=A> 内嵌 <asvg:svgBlip r:embed=B>，
+//  经该 slide 的 .rels 把 A→兜底 .png、B→真 .svg 解析成具体部件路径（既覆盖 path 形态，
+//  也覆盖 base64 data 形态的 IMG_BROKEN 兜底）。
+// ============================================================================
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import JSZip from 'jszip';
+import sharp from 'sharp';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const OPC_CHECK = path.join(__dirname, 'opc_check.py');
+const PNG_MAX_WIDTH = 1600; // 兜底 PNG 够清晰即可（真正显示走 svgBlip）；上限防超大
+
+// ---- args -----------------------------------------------------------------
+const argv = process.argv.slice(2);
+const inPath = argv.find((a) => !a.startsWith('-'));
+const outIdx = argv.findIndex((a) => a === '-o' || a === '--out');
+const outPath = outIdx >= 0 ? argv[outIdx + 1] : inPath;
+if (!inPath) {
+  console.error('usage: node svg_fallback.mjs <deck.pptx> [-o <out.pptx>]');
+  process.exit(2);
+}
+
+// ---- 把 slide 同级目录 + rels Target 解析成部件绝对路径 --------------------
+function resolvePart(fromDir, target) {
+  // target 形如 "../media/image-1-2.svg"，相对 slide 的 _rels 上一级（即 slide 同级目录）
+  return path.posix.normalize(path.posix.join(fromDir, target));
+}
+
+async function main() {
+  const buf = fs.readFileSync(inPath);
+  const zip = await JSZip.loadAsync(buf);
+
+  // 收集所有 slide xml
+  const slidePaths = Object.keys(zip.files).filter(
+    (n) => /^ppt\/slides\/slide\d+\.xml$/.test(n),
+  );
+
+  const pairs = []; // { pngPart, svgPart }
+  for (const sp of slidePaths) {
+    const xml = await zip.file(sp).async('string');
+    const dir = path.posix.dirname(sp); // ppt/slides
+    const relsPath = `${dir}/_rels/${path.posix.basename(sp)}.rels`;
+    const relsFile = zip.file(relsPath);
+    if (!relsFile) continue;
+    const relsXml = await relsFile.async('string');
+    const rid2target = {};
+    for (const m of relsXml.matchAll(/<Relationship\b[^>]*\bId="([^"]+)"[^>]*\bTarget="([^"]+)"[^>]*\/?>/g)) {
+      rid2target[m[1]] = m[2];
+    }
+    // blipFill 里 a:blip(r:embed=PNG) 包住 asvg:svgBlip(r:embed=SVG)
+    for (const m of xml.matchAll(/<a:blip\b[^>]*\br:embed="([^"]+)"[^>]*>[\s\S]*?<asvg:svgBlip\b[^>]*\br:embed="([^"]+)"/g)) {
+      const pngTgt = rid2target[m[1]];
+      const svgTgt = rid2target[m[2]];
+      if (!pngTgt || !svgTgt) continue;
+      pairs.push({
+        pngPart: resolvePart(dir, pngTgt),
+        svgPart: resolvePart(dir, svgTgt),
+      });
+    }
+  }
+
+  if (pairs.length === 0) {
+    console.log('[svg_fallback] 未发现 SVG 配图（asvg:svgBlip）—— 仅做 OPC 合规重打包。');
+  }
+
+  // 逐对：sharp 渲染真 PNG，覆盖兜底
+  let fixed = 0;
+  for (const { pngPart, svgPart } of pairs) {
+    const svgFile = zip.file(svgPart);
+    const pngFile = zip.file(pngPart);
+    if (!svgFile || !pngFile) {
+      console.warn(`[svg_fallback] 跳过：缺部件 ${svgPart} 或 ${pngPart}`);
+      continue;
+    }
+    const svgBuf = await svgFile.async('nodebuffer');
+    const png = await sharp(svgBuf, { density: 220 })
+      .resize({ width: PNG_MAX_WIDTH, withoutEnlargement: false })
+      .png()
+      .toBuffer();
+    zip.file(pngPart, png); // 覆盖
+    fixed++;
+    console.log(`[svg_fallback] 兜底已渲染：${pngPart}  (${png.length} bytes, 真 PNG)`);
+  }
+
+  // 生成中间包（jszip 可能带目录条目/顺序问题 —— 交给 opc_check --repack 归一化）
+  const tmp = path.join(
+    path.dirname(path.resolve(outPath)),
+    `.svgfix-${path.basename(outPath)}.tmp.pptx`,
+  );
+  const outBuf = await zip.generateAsync({ type: 'nodebuffer', compression: 'DEFLATE' });
+  fs.writeFileSync(tmp, outBuf);
+
+  // 备份原文件（原地写时）
+  if (path.resolve(outPath) === path.resolve(inPath)) {
+    fs.copyFileSync(inPath, `${inPath}.bak`);
+  }
+
+  // opc_check --repack 归一化到最终路径
+  const rp = spawnSync('python', [OPC_CHECK, tmp, '--repack', outPath], { stdio: 'inherit' });
+  fs.rmSync(tmp, { force: true });
+  if (rp.status !== 0) {
+    console.error('[svg_fallback] 重打包失败');
+    process.exit(rp.status ?? 1);
+  }
+
+  // 自校验
+  const vr = spawnSync('python', [OPC_CHECK, outPath, '-v'], { stdio: 'inherit' });
+  console.log(`[svg_fallback] 完成：修复 ${fixed} 张 SVG 兜底 → ${outPath}`);
+  process.exit(vr.status ?? 0);
+}
+
+main().catch((e) => {
+  console.error('[svg_fallback] ERROR:', e.message);
+  process.exit(1);
+});

package/skills/pptx/svg.md

@@ -0,0 +1,67 @@
+# SVG 配图（可编辑矢量美术）
+
+PPT 的可编辑性命脉是「图形是矢量、可逐元素改」。本指南讲**美术配图**怎么用 SVG 做到，
+以及 SVG 落 pptx 那一步的**已知坑 + 兜底管线**（实测确诊，下文给数据）。
+
+> 结构图（框图/流程图/色块）不一定要 SVG —— 见下「图形决策规则」。
+
+## 图形决策规则（先选对路线，再动手）
+
+| 内容 | 用什么 | 为什么 |
+|------|--------|--------|
+| 标题 / 正文 / 项目符号 / 表格 —— **任何文字** | **原生 `addText`** | 可编辑、可重排、可改字号；**绝不**把文字烤进图片 |
+| 框图 / 流程图 / 时序 / 色块布局（元素需独立可编辑、常含活文字） | **原生 `addShape`** | PptxGenJS 原生对象，点一下就选中改色/移动/改字，**连「取消组合」都不用**。复用 `scripts/deck_helpers.mjs` |
+| 背景 / 渐变 / 插画 / 图标 / 曲线 / Logo —— addShape 表现不了的美术 | **SVG**（本指南） | 矢量、丰富（渐变/路径/曲线），PowerPoint 365 可「转换为形状」取消组合编辑 |
+| 真实照片 / 已有位图素材 | `addImage(png/jpg)` | 本就是位图；封面/封底装饰 ≤2 张为宜 |
+
+一句话：**文字 addText，结构 addShape，美术 SVG，照片 addImage。** 拿不准就退到 addShape（最稳）。
+
+## 写「可取消组合」的 SVG
+
+目标：用户在 PowerPoint 365 里右键 SVG →「图形格式 → 转换为形状」→「取消组合」后，得到一组**干净、独立、可改色**的形状。为此：
+
+- **一个语义元素一个 `<g>`**（背景、色块、圆、流线各自分组）——转换为形状后就是一个个独立对象。
+- **`viewBox` 用目标显示比例**：封面满铺用 `viewBox="0 0 1330 750"`（对齐 13.3"×7.5"）；图标用 `0 0 100 100`。比例对了，放进 slide 不变形。
+- **避免栅格化滤镜**（`feGaussianBlur`/`feImage` 等）——转换为形状时会塌成位图，失去可编辑性。要阴影用 PptxGenJS 的 `shadow`，要发光用渐变近似。
+- **文字尽量别写进 SVG `<text>`**：放回 pptx 原生文字层（`addText`），既可编辑又能被 markitdown 抽取做内容 QA。SVG 里只放纯图形。
+- 渐变/不透明度 SVG 原生支持，放心用（`<linearGradient>`/`<radialGradient>`/`opacity`）——这正是 addShape 给不了的表现力。
+
+参考 `examples/assets/cover-bg.svg`（满铺背景）和 `examples/assets/icon-spark.svg`（图标）。
+
+## 落 pptx：嵌入 + 兜底管线（关键，别跳）
+
+### 怎么嵌
+
+```javascript
+// Node 跑（不要 Bun）。把 SVG 当图片加，PptxGenJS 会写出 PowerPoint 原生 SVG 结构。
+slide.addImage({ path: 'assets/cover-bg.svg', x: 0, y: 0, w: 13.3, h: 7.5 });
+```
+
+### 为什么必须再跑一步 `svg_fallback.mjs`（实测确诊）
+
+PptxGenJS 在 **Node** 下嵌 SVG 时：
+- ✅ slide xml 会写出 PowerPoint 原生 SVG 结构：`<a:blip r:embed=PNG>` 内嵌 `<asvg:svgBlip r:embed=SVG>`（`{96DAC541-...}` 扩展），`.svg` 部件是**真 SVG** → 现代 PowerPoint 能渲染、能「转换为形状」。
+- ❌ 但 **PNG 兜底不会被栅格化**（官方 [issue #401](https://github.com/gitbrent/PptxGenJS/issues/401)）：那个 `.png` 部件实际装的是 SVG 字节（或 IMG_BROKEN）。凡是读 PNG 兜底的消费者——**LibreOffice 视觉 QA、旧版 PowerPoint、缩略图**——全破图。
+- ❌ 且 PptxGenJS 产出的 zip 常含目录条目 / `[Content_Types].xml` 不在首位，本就需要合规重打包。
+
+所以**生成 deck 后必跑**：
+
+```bash
+node skills/pptx/scripts/svg_fallback.mjs deck.pptx           # 原地修（留 deck.pptx.bak）
+node skills/pptx/scripts/svg_fallback.mjs deck.pptx -o out.pptx
+```
+
+它做两件事，一步交付「现代 + 旧版都不破图、且 OPC 合规」的 deck：
+1. 用 `sharp` 把每个 `ppt/media/*.svg` 渲染成**真** PNG，覆盖配对的兜底 `.png`；
+2. 调 `opc_check.py --repack` 合规重打包（去目录条目 / Content_Types 置首 / DEFLATE / 删孤儿 Override）+ 自校验。
+
+对不含 SVG 的 deck 也安全幂等（只做合规重打包）。依赖：`sharp`（npm）+ `python`。
+
+### 用户侧验证可编辑性
+
+把 deck 在 **PowerPoint 365 / 2019+** 打开 → 点 SVG 图 → 右键「图形格式」→「转换为形状」→ 再右键「组合 → 取消组合」→ 每个 `<g>` 成为可单独改色/移动的形状。旧版 PowerPoint 看到的是 `svg_fallback` 渲染的清晰 PNG（不破图，但不可拆）。
+
+## 完整跑通的范例
+
+`examples/hybrid_example.mjs` —— 3 页演示文字/结构/美术三路混用，末尾自动跑 `svg_fallback.mjs`。
+直接 `node skills/pptx/examples/hybrid_example.mjs`，产物 OPC 校验全绿、含 2 张可转换为形状的 SVG。

package/skills/tts-zh/SKILL.md

@@ -3,7 +3,18 @@ name: tts-zh
 description: 当用户说"中文配音"、"中文 TTS"、"语音合成"、"文字转语音"、"tts-zh"，或在 workflow 里要把中文文本转成 mp3 时使用。优先用 MiniMax T2A API，失败时 fallback 到 edge-tts 离线方案，输出 mp3 到指定路径。
 ---
 
-# tts-zh —— 中文 TTS（minimax 主 + edge-tts 兜底）
+# tts-zh —— 中文 TTS
+
+优先调用内核 `GenerateSpeech` 工具。该工具从统一 ConfigService 安全读取 MiniMax
+凭据；**不要**用 Bash、`echo`、`env` 或 curl 获取/传递 API Key。
+
+## 环境变量
+
+| 变量 | 必需性 | 说明 |
+|---|---|---|
+| `MINIMAX_API_KEY` | minimax 路径必需 | MiniMax API key；缺则直接走 edge-tts fallback |
+| `MINIMAX_GROUP_ID` | minimax 路径必需 | MiniMax GroupId（T2A 接口 query 参数）；缺则直接走 edge-tts fallback |
+| `MINIMAX_BASE_URL` | 可选 | 自定义网关地址，默认 `https://api.minimax.chat` |
 
 ## 输入约定
 
@@ -25,7 +36,13 @@ text=今天天气真好 output=./assets/audio_0.mp3 voice=female-shaonv speed=1.
 
 仔细取 text / output / voice / speed。text 可能包含空格甚至标点，按"剩余串"策略提取。
 
-### 2. 优先尝试 MiniMax T2A
+### 2. 调用受控工具
+
+调用 `GenerateSpeech`，传入 `text`、`output`、`voice`、`speed`。成功后直接返回产物。
+
+下列 shell 示例仅用于历史说明，不应由 Agent 执行。
+
+### 3. 旧版 MiniMax T2A 说明
 
 #### 2.1 取 key + group id