@huicai/cli 2026.814.0 → 2026.1019.0

package/skills/ppt-chain/SKILL.md

@@ -17,12 +17,15 @@ version: 1.0.0
 
 ## 引擎决策表（双引擎，按需选）
 
-| 维度 | pptx-author（python-pptx） | slides-html（渲染管线，桌面端） |
+| 维度 | pptx-author（`create_deck`，四端都有） | slides-html（渲染管线，仅桌面端） |
 |---|---|---|
 | 可编辑性 | ✅ 原生可改 | ❌ 贴图（如实告知） |
-| 设计表现力 | 常规版式 | ✅ 渐变/精细排版/发布会级 |
+| 设计表现力 | 十三种版式，规整 | ✅ 渐变/精细排版/发布会级 |
 | 适用 | 日常汇报/需二次编辑/模板合规 | 对外发布/路演/交付 PDF |
-| 自检 | verify 页数标题 | ✅ 截图注入逐页自检闭环 |
+| 版式自检 | ✅ `pptx_inspect` 几何+度量机检，可自动修 | ✅ DOM 机检 + 截图注入看图 |
+
+两条路都有**机检**：必修项为 0 才算做完。区别只在"机器看得见什么"——
+PPTX 侧看的是形状坐标与文字度量，HTML 侧看的是真实渲染后的 DOM。
 
 品牌规范（色/字/logo）从 brand-design 的 VI 取;两引擎主题色系同源。
 
@@ -33,8 +36,11 @@ version: 1.0.0
    （中文字体!）;一页一图;
 3. **素材**：图片版权可用性;图标用 Emoji/内联 SVG（slides-html 禁外链）;
 4. **生成**：按引擎决策表;结构页型（封面/目录/章节/要点/图文/KPI/引用/结尾）套用;
-5. **自检**：验收清单（无溢出/无缺字/主题一致/页码/数字与来源核对——**讲错一个数,
-  整场信用清零**,同述职纪律）;
+5. **自检（两层，缺一不可）**：
+   ①**版式机检**——`pptx_inspect` 或 `slides_render` 的体检报告，必修项清零，
+     溢出/重叠/变形/越界这类"打开就看得见的事故"不许带到交付；
+   ②**内容核对**——数字与来源逐个对，**讲错一个数,整场信用清零**（同述职纪律）；
+     主题一致、页码、无缺字。机检管得了前者，管不了后者。
 6. **导出与演讲**：PDF（通用）/PPTX/放映页;讲稿按 260 字/分钟配时（okr-review 口径）,
    QA 预演（pr-comms 攻防表）。
 
@@ -57,5 +63,7 @@ slides-html 四主题选型+定制封面 → 逐页截图自检至无溢出 →
 
 ## 使用纪律
 
-大纲未确认不生成;数字未溯源不上页;PPTX 贴图版的不可编辑性**必须**提前告知;
+大纲未确认不生成;数字未溯源不上页;**版式机检必修项未清零不交付**;
+PPTX 贴图版的不可编辑性**必须**提前告知;
+坐标不自己算——用 `create_deck` 的结构化版式,手写 python-pptx 摆坐标是全部排版事故的来源;
 模板资产沉淀（好版式回写团队模板,knowledge-sop 管理）。

package/skills/ppt-chain/trigger-cases.json

@@ -0,0 +1,31 @@
+{
+  "skill": "ppt-chain",
+  "cases": [
+    {
+      "id": "pos-1",
+      "prompt": "要做个 PPT 但场景和素材还没定",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-2",
+      "prompt": "从数据到汇报，整条 PPT 链怎么走",
+      "shouldTrigger": true
+    },
+    {
+      "id": "pos-3",
+      "prompt": "经营月报的 PPT 全流程怎么排",
+      "shouldTrigger": true
+    },
+    {
+      "id": "neg-1",
+      "prompt": "直接生成一个 pptx 演示文稿",
+      "shouldTrigger": false,
+      "lexical": false
+    },
+    {
+      "id": "neg-2",
+      "prompt": "写一份 Word 报告",
+      "shouldTrigger": false
+    }
+  ]
+}

package/skills/pptx-author/SKILL.md

@@ -1,48 +1,101 @@
 ---
 name: pptx-author
-description: 生成 PPT 演示文稿。当用户说"做个 PPT/幻灯片/汇报材料/演示文稿/pptx"时使用。
-version: 1.0.0
+description: 生成 PPT/幻灯片演示文稿，并对成品做版式体检（文字溢出、元素重叠、图片变形、超出页面）。当用户说"做个 PPT/做几页幻灯片/汇报材料/演示文稿/pptx"，或说"PPT 排版有问题/幻灯片版式检查/修复溢出重叠"时使用。
+version: 2.0.0
 ---
 
-# PPT 生成（经 run_python 执行，python-pptx 已随托管运行时就绪）
+# PPT 生成与版式体检
 
-## 流程
+**PPT 的排版事故不是审美问题，是算术问题**：文字塞进一个拍脑袋定的框、图片同时给了宽和高、
+两块内容坐标算重了——这三件事在保存那一刻都不报错，等人打开 PPT 才看见。
+所以本技能的做法是：坐标不由你算，出片后再机检一遍。
 
-1. **大纲先行**：先在回复里给出逐页大纲（每页=标题 + ≤5 条要点 + 可选备注），页数建议 8–15；重要汇报让用户确认再生成。
-2. **选主题**：`read_skill_file` 读本技能 `scripts/pptx_deck.py`，内置四套配色主题——`navy`（深蓝商务，默认）/ `tech`（科技紫）/ `mono`(极简灰) / `warm`（活力橙）。用户有品牌色时改 `THEMES` 传自定义。
-3. **逐页构建**（16:9，helper 已处理版式/配色/字体）：
-   ```python
-   d = Deck(theme='navy')
-   d.add_cover('2026 上半年经营分析', '数据一部 · 2026-07')
-   d.add_agenda(['经营概览', '分区域表现', '问题与对策', '下半年计划'])
-   d.add_section('一、经营概览')
-   d.add_bullets('核心指标', ['营收 3.6 亿，同比 +18%', '毛利率 32.5%，环比 +1.2pct'], notes='强调同比口径')
-   d.add_image('分区域销售', '销售图.png', caption='华东领先，西南承压')
-   d.add_table('明细数据', [['地区','销售额','同比'], ['华东','1.2亿','+21%']])
-   d.add_end('谢谢，欢迎讨论')
-   d.save('经营分析.pptx')
-   ```
-4. **图表页**：先按 data-analysis 技能出 png（务必先设中文字体），再 `add_image` 插入——比 pptx 原生图表稳定且好看。
-5. **验收（必做）**：`verify('产物.pptx')` 重开打印页数与每页标题，对照大纲无缺页。
+## 一、生成：用 `create_deck`，不要自己摆坐标
 
-## 设计约束（避免"惨不忍睹"的 PPT）
+`create_deck(path, spec)` 是首选路径。你只给「每页讲什么」，引擎负责量与画：
+一页装不下先降字号（22→16pt），降到下限自动拆页并把标题改成「原标题（续）」；
+图片一律按原比例等比缩放居中（**不存在把图拉变形的写法**）；表格列宽按内容算、行多了自动分页；
+每次落盘后**自动跑一遍版式体检**，报告随结果返回。
 
-- 一页一个观点；要点每条 ≤20 字；超了就拆页或进备注。
-- 数字是主角：关键数字用 `add_kpi`（大数字卡片页）而非藏在句子里。
-- 不堆图：一页一图；表格 ≤7 行，更多的放 xlsx 附件并在页脚注明。
-- 中文字体 helper 已设（微软雅黑/苹方由播放机器渲染，不嵌字体）。
+```jsonc
+{ "theme": "navy", "footer": "数据一部 · 2026-07", "slides": [
+  { "layout": "cover",   "title": "2026 上半年经营分析", "subtitle": "数据一部", "meta": "2026-07-15" },
+  { "layout": "agenda",  "items": ["经营概览", "分区域表现", "问题与对策", "下半年计划"] },
+  { "layout": "section", "title": "经营概览", "no": "PART 01" },
+  { "layout": "kpi",     "title": "核心指标",
+    "kpis": [["3.6亿", "营业收入", "同比 +18%"], ["32.5%", "毛利率", "环比 +1.2pct"]] },
+  { "layout": "bullets", "title": "增长来自哪里", "lead": "结论：靠华东与订阅制",
+    "bullets": ["华东新签 12 家大客户", { "text": "产品侧", "sub": ["智能报表续费率 92%"] }],
+    "notes": "这里展开讲渠道的账" },
+  { "layout": "table",   "title": "分区域明细",
+    "rows": [["地区","销售额(万)","同比"], ["华东","12000","+21%"]], "note": "口径：含税" },
+  { "layout": "end",     "text": "谢谢，欢迎讨论" }
+]}
+```
 
-## 桌面端「炫酷版」提示
+**十三种版式**：cover 封面 / agenda 目录 / section 章节 / bullets 要点 / two_col 两栏 /
+kpi 大数字 / image 整幅图 / image_text 图文 / table 表格 / quote 引言 / compare 左右对照 /
+timeline 时间轴 / end 结尾。**六套主题**：navy（默认）/ tech / mono / warm / green / dark。
 
-python-pptx 走的是标准版式，追求设计感/动效的发布会级 PPT 属 M5-⑤ HTML 幻灯片管线（桌面端渲染导出）。用户明确要"炫酷/设计感"时：先用本技能出**结构定稿**，并说明设计版能力的边界。
+配图先出 png 再引用：工程图用 `render_diagram`，数据图表用 `run_python` + matplotlib（**先设中文字体**）。
 
-## 验收自查
+## 二、验收：`pptx_inspect` 必修项清零才算做完
 
-- [ ] verify 输出的页数与标题和大纲一致
-- [ ] 每页要点 ≤5 条、每条 ≤20 字（超限已拆页/进备注）
-- [ ] 插图的 png 中文显示正常（画图前设了字体）
+`create_deck` 已自动体检；**自己写 python-pptx 生成的更要手动跑一遍** `pptx_inspect(path=...)`。
+用户拿来一份别人做的 PPT 问"排版有没有问题"，也是这个工具。
+
+体检的十几类问题分三档：
+
+| 必修（打开就能看见的事故） | 建议（能读，但不专业） | 提示 |
+|---|---|---|
+| 文字溢出被切 / 框自动长高顶出页底 | 要点过多（>6）、单条过长（>25 字） | 标题跨页重复 |
+| 元素重叠（按文字**实际占位**比，不是按框比） | 整页文字过密（>220 字） | 配色过杂 |
+| 图片变形（宽高比≠原图）| 图片发虚（<96dpi） | 页面比例非 16:9 |
+| 超出页面边界、表格顶出页底 | 贴边过近（<0.22"）、标题跨页错位 | |
+| 字号 <10pt、对比度 <4.5:1 | 中文未设东亚字体 | |
+
+`pptx_inspect(path, fix=true)` 自动修**几何类**问题（图片恢复原比例、元素移回页内、
+文字缩字或加高文本框、表格缩排回写行高），**另存 `-已修复.pptx` 不覆盖原件**，并回报复检结果。
+改内容才能解决的（要点太多、表格太长、文案太啰嗦）它会如实说"需要拆页/精简"——**别假装修好了**。
+
+## 三、需要引擎没有的版式时
+
+才用 `run_python` 直接调建版内核（**不要复制粘贴源码**，import 即可）：
+
+```python
+import os, sys; sys.path.insert(0, os.path.join(os.environ['HUICAI_SKILLS_DIR'], 'pptx-author', 'scripts'))
+from pptx_deck import Deck
+d = Deck('navy', footer='数据一部')
+d.add_cover('标题', '副标题')
+d.add_bullets('要点', ['第一条', '第二条'])   # 装不下会自己降字号/拆页
+d.save('产物.pptx')                            # save 自动体检并打印报告
+```
+
+环境变量取不到时（老版本宿主）才退回 `read_skill_file` 读源码。
+**任何情况下都不要自己算 `Inches(...)` 坐标去摆版式**——那正是所有事故的来源。
+
+## 四、内容纪律（比排版更决定成败）
+
+- 大纲先行：每页 = 结论式标题 + ≤5 条要点，8–15 页；重要汇报**先让用户确认大纲再生成**。
+- 一页一个观点；一条要点 ≤20 字；展开的话进 `notes`（演讲备注），不进正文。
+- 数字是主角：关键数字用 `kpi` 版式做成大数字卡片，别藏在句子里；数字必须可溯源。
+- 表格 ≤7 行；更多的放 xlsx 附件并在 `note` 里注明。
+- 追求发布会级设计感 → 改用 `slides-html`（桌面端 HTML 渲染管线），本技能出结构定稿。
+
+## 五、交付自查
+
+- [ ] `pptx_inspect` 必修 = 0（做不到就如实告诉用户哪几页需要他决定删什么）
+- [ ] 页数与标题和确认过的大纲一致
+- [ ] 插图中文显示正常、清晰不糊
 - [ ] 文件名是中文描述性名称，已 print 产物清单
 
-## 附件
+## 附件（`read_skill_file` 按需读；日常用 `create_deck` 工具即可，不必读源码）
 
-- `scripts/pptx_deck.py` — Deck 构建器：四主题配色、cover/agenda/section/bullets/kpi/image/table/end 八种版式、`verify()` 重读校验；可直接执行自测
+- `scripts/pptx_layout.py` — 版式度量内核：中英文字宽表（对雅黑/苹方实测校准，
+  `python pptx_layout.py --calibrate` 可重新校准）、折行、几何、对比度。建版与体检**共用同一把尺**。
+- `scripts/pptx_deck.py` — Deck 建版器：十三版式、先量后画、自动拆页、`save()` 自带体检。直接执行 = 自测。
+- `scripts/pptx_check.py` — 体检与自动修复：`inspect()` / `report()` / `fix()`；也可 CLI 跑
+  `python pptx_check.py 汇报.pptx --fix`。
+- `scripts/pptx_build.py` — spec(JSON) → PPTX 的执行端（`create_deck` 工具走的就是它）。
+- `scripts/pptx_battery.py` — 压力测试：随机刁难内容 × 六主题 × 两画幅跑几百份，
+  断言零版式事故；并反向造缺陷验证体检不是瞎子。改了引擎必须重跑：`python pptx_battery.py 300`。

package/skills/pptx-author/scripts/pptx_battery.py

@@ -0,0 +1,178 @@
+# 版式引擎压力测试：拿刻意刁难的内容灌进去，断言**永远不产生版式事故**。
+#
+# 为什么要这么测：排版缺陷不像功能 bug 那样"必现"，它取决于这一页恰好有多少字、
+# 标题恰好多长、表格恰好多少列。人工试几页什么都试不出来，只有把
+# 「超长标题 × 超多要点 × 中英数混排 × 六套主题 × 两种画幅」交叉铺开跑几百份，
+# 才谈得上"确保不出现变形、重叠"。
+#
+# 运行：python pptx_battery.py [份数，默认 240]
+# 判据：每份产物的体检结果里，**几何类问题一条都不许有**（内容类告警允许——
+#       "要点太多"是在说内容该精简，不是版式坏了）。
+
+import os
+import random
+import sys
+import tempfile
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+import pptx_check                                            # noqa: E402
+from pptx_deck import Deck, _demo_png                        # noqa: E402
+from pptx_layout import THEMES                               # noqa: E402
+
+# 几何/可读性类：引擎自己生成的产物里出现任何一条，都是引擎的缺陷
+FORBIDDEN = {'overflow_v', 'overflow_h', 'overlap', 'out_of_slide', 'image_distort',
+             'tiny_shape', 'low_contrast', 'font_too_small', 'no_ea_font', 'off_grid',
+             'page_scroll', 'autofit_shrunk'}
+
+CJK = '经营分析渠道毛利率现金流客户续约交付实施顾问标准化复用行业模板签单回款'
+LAT = ['pipeline', 'ROI', 'NPS', 'OKR', 'SaaS', 'A/B', 'CAC', 'GMV', 'QoQ', 'YoY']
+
+
+def rand_text(rng, lo, hi):
+    n = rng.randint(lo, hi)
+    out = []
+    while sum(len(x) for x in out) < n:
+        r = rng.random()
+        if r < 0.62:
+            out.append(''.join(rng.choice(CJK) for _ in range(rng.randint(2, 8))))
+        elif r < 0.82:
+            out.append(rng.choice(LAT))
+        elif r < 0.95:
+            out.append(f'{rng.randint(1, 9999)}{rng.choice(["", "万", "%", "亿", ".5pct", "天"])}')
+        else:
+            out.append(rng.choice('，。：、（）+-—'))
+    return ''.join(out)[:n + 6]
+
+
+def make_deck(rng, png_big, png_small, i):
+    theme = rng.choice(list(THEMES))
+    d = Deck(theme, size=rng.choice(['16:9'] * 5 + ['4:3']),
+             footer=rand_text(rng, 0, 24) if rng.random() < 0.7 else '',
+             page_numbers=rng.random() < 0.85)
+    d.add_cover(rand_text(rng, 4, 40), rand_text(rng, 0, 30), rand_text(rng, 0, 20))
+    d.add_agenda([rand_text(rng, 2, 26) for _ in range(rng.randint(2, 9))])
+    d.add_section(rand_text(rng, 2, 34), no=rng.choice([None, 'PART 01', '一']),
+                  subtitle=rand_text(rng, 0, 30))
+    d.add_kpi(rand_text(rng, 2, 20),
+              [(rand_text(rng, 1, 9), rand_text(rng, 2, 18), rand_text(rng, 0, 12))
+               for _ in range(rng.randint(1, 6))],
+              caption=rand_text(rng, 0, 40) if rng.random() < 0.4 else '')
+    d.add_bullets(rand_text(rng, 2, 30),
+                  [rand_text(rng, 4, 60) for _ in range(rng.randint(1, 16))],
+                  lead=rand_text(rng, 0, 34) if rng.random() < 0.5 else '')
+    d.add_two_col(rand_text(rng, 2, 22),
+                  [rand_text(rng, 3, 34) for _ in range(rng.randint(1, 7))],
+                  [rand_text(rng, 3, 34) for _ in range(rng.randint(1, 7))],
+                  rand_text(rng, 0, 12), rand_text(rng, 0, 12))
+    d.add_compare(rand_text(rng, 2, 22), rand_text(rng, 2, 10),
+                  [rand_text(rng, 3, 30) for _ in range(rng.randint(1, 6))],
+                  rand_text(rng, 2, 10),
+                  [rand_text(rng, 3, 30) for _ in range(rng.randint(1, 6))])
+    d.add_image(rand_text(rng, 2, 24), rng.choice([png_big, png_small]),
+                caption=rand_text(rng, 0, 44))
+    d.add_image_text(rand_text(rng, 2, 24), png_big,
+                     [rand_text(rng, 3, 30) for _ in range(rng.randint(1, 6))],
+                     side=rng.choice(['left', 'right']), caption=rand_text(rng, 0, 30))
+    ncol = rng.randint(2, 7)
+    rows = [[rand_text(rng, 2, 10) for _ in range(ncol)]]
+    rows += [[rand_text(rng, 1, 16) for _ in range(ncol)] for _ in range(rng.randint(1, 24))]
+    d.add_table(rand_text(rng, 2, 22), rows, note=rand_text(rng, 0, 40))
+    d.add_timeline(rand_text(rng, 2, 22),
+                   [(rand_text(rng, 2, 8), rand_text(rng, 3, 26)) for _ in range(rng.randint(2, 6))])
+    d.add_quote(rand_text(rng, 6, 70), rand_text(rng, 0, 14))
+    d.add_end(rand_text(rng, 2, 20), rand_text(rng, 0, 26))
+    return d, theme
+
+
+def main(n=240):
+    rng = random.Random(20260831)
+    tmp = tempfile.mkdtemp(prefix='pptx-battery-')
+    png_big = _demo_png(os.path.join(tmp, 'big.png'), 1600, 900)
+    png_small = _demo_png(os.path.join(tmp, 'small.png'), 420, 640)
+    bad = []
+    pages = 0
+    warn_codes = {}
+    for i in range(n):
+        path = os.path.join(tmp, f'deck{i}.pptx')
+        try:
+            d, theme = make_deck(rng, png_big, png_small, i)
+            res = d.save(path, verbose=False)
+        except Exception as e:
+            bad.append((i, 'EXCEPTION', f'{type(e).__name__}: {e}'))
+            continue
+        pages += res['slides']
+        for f in res['findings']:
+            if f['code'] in FORBIDDEN or (f['code'] == 'table_overflow' and f['level'] == 'error'):
+                bad.append((i, f'{theme} p{f["page"]} {f["code"]}', f['detail']))
+            else:
+                warn_codes[f['code']] = warn_codes.get(f['code'], 0) + 1
+        for w in d.warnings:
+            if '内部版式冲突' in w:
+                bad.append((i, 'CLAIM', w))
+        os.remove(path)
+    print(f'跑了 {n} 份 · {pages} 页 · 六主题两画幅随机内容')
+    print('内容类告警（允许，属于"内容该精简"而非版式坏了）：'
+          + ('、'.join(f'{k}×{v}' for k, v in sorted(warn_codes.items())) or '无'))
+    if bad:
+        print(f'\n❌ 版式事故 {len(bad)} 条：')
+        for i, where, detail in bad[:25]:
+            print(f'  #{i} {where}  {detail[:110]}')
+        return 1
+    print('\n✅ 零版式事故：无溢出、无重叠、无变形、无越界、无小字、无低对比度')
+    return 0
+
+
+def detector_check():
+    """反向验证：故意造缺陷，体检必须抓得住（不然上面的"零事故"可能只是瞎子发的通行证）。"""
+    from pptx import Presentation
+    from pptx.util import Inches, Pt
+    tmp = tempfile.mkdtemp(prefix='pptx-detect-')
+    png = _demo_png(os.path.join(tmp, 'w.png'), 1600, 900)
+    prs = Presentation()
+    prs.slide_width, prs.slide_height = Inches(13.333), Inches(7.5)
+    b = prs.slide_layouts[6]
+    s = prs.slides.add_slide(b)
+    s.shapes.add_picture(png, Inches(1), Inches(1), width=Inches(4), height=Inches(4))   # 变形
+    s = prs.slides.add_slide(b)
+    for x in (1.0, 2.0):                                                                  # 重叠
+        tb = s.shapes.add_textbox(Inches(x), Inches(2), Inches(4), Inches(1))
+        r = tb.text_frame.paragraphs[0].add_run()
+        r.text = '压在一起的两块文字'
+        r.font.size = Pt(24)
+    s = prs.slides.add_slide(b)
+    tb = s.shapes.add_textbox(Inches(11), Inches(7), Inches(4), Inches(1))                # 越界
+    r = tb.text_frame.paragraphs[0].add_run()
+    r.text = '跑出页面'
+    r.font.size = Pt(18)
+    tb = s.shapes.add_textbox(Inches(1), Inches(1.5), Inches(5), Inches(1))               # 溢出
+    tf = tb.text_frame
+    tf.word_wrap = True
+    for i in range(8):
+        p = tf.paragraphs[0] if i == 0 else tf.add_paragraph()
+        r = p.add_run()
+        r.text = '这一段文字足够长，用来把文本框撑爆 %d' % i
+        r.font.size = Pt(20)
+    path = os.path.join(tmp, 'defects.pptx')
+    prs.save(path)
+    res = pptx_check.inspect(path)
+    got = {f['code'] for f in res['findings']}
+    want = {'image_distort', 'overlap', 'out_of_slide', 'overflow_v'}
+    miss = want - got
+    print('\n【反向验证】故意造 4 类缺陷 → 抓到：' + '、'.join(sorted(want & got)))
+    if miss:
+        print('❌ 漏检：' + '、'.join(sorted(miss)))
+        return 1
+    fixed = pptx_check.fix(path)
+    after = {f['code'] for f in pptx_check.inspect(fixed['saved'])['findings']}
+    if 'image_distort' in after or 'out_of_slide' in after:
+        print('❌ fix 后仍有几何类问题：' + '、'.join(sorted(after)))
+        return 1
+    print(f'   fix 修掉 {len(fixed["changed"])} 处，复检无变形/越界 ✓')
+    return 0
+
+
+if __name__ == '__main__':
+    n = int(sys.argv[1]) if len(sys.argv) > 1 and sys.argv[1].isdigit() else 240
+    code = main(n) | detector_check()
+    sys.exit(code)

package/skills/pptx-author/scripts/pptx_build.py

@@ -0,0 +1,119 @@
+# 结构化 spec → PPTX：模型只给"每页讲什么"，版式/字号/坐标/配色全由引擎算。
+#
+# 这是 create_deck 工具的执行端，也可以单独用：
+#   python pptx_build.py 大纲.json 产物.pptx
+#
+# 为什么不让模型直接写 python-pptx：写坐标就一定会有算错的坐标，
+# 那正是"文字出框、两块压在一起、图被拉长"的全部来源。
+# 模型擅长决定"这页讲什么"，不擅长也不该负责"这行字在 3.72 英寸处会不会撞到图"。
+
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from pptx_deck import Deck                                   # noqa: E402
+
+LAYOUTS = {
+    'cover': ('title',), 'agenda': ('items',), 'section': ('title',), 'bullets': ('title', 'bullets'),
+    'two_col': ('title', 'left', 'right'), 'kpi': ('title', 'kpis'), 'image': ('title', 'image'),
+    'image_text': ('title', 'image', 'bullets'), 'table': ('title', 'rows'), 'quote': ('text',),
+    'compare': ('title', 'left', 'right'), 'timeline': ('title', 'items'), 'end': (),
+}
+ALIAS = {  # 模型爱用的同义写法，都接住，别为了一个词名让整份 deck 失败
+    '封面': 'cover', '目录': 'agenda', 'toc': 'agenda', 'contents': 'agenda', '章节': 'section',
+    'divider': 'section', '要点': 'bullets', 'bullet': 'bullets', 'list': 'bullets', 'points': 'bullets',
+    '两栏': 'two_col', 'twocol': 'two_col', 'two-column': 'two_col', 'columns': 'two_col',
+    '指标': 'kpi', 'metrics': 'kpi', 'stats': 'kpi', '图': 'image', 'picture': 'image', 'chart': 'image',
+    '图文': 'image_text', 'imagetext': 'image_text', '表': 'table', '表格': 'table',
+    '引言': 'quote', '金句': 'quote', '对照': 'compare', '对比': 'compare', 'comparison': 'compare',
+    '时间轴': 'timeline', 'roadmap': 'timeline', '结尾': 'end', 'thanks': 'end', 'closing': 'end',
+}
+
+
+def norm_layout(v):
+    k = str(v or '').strip().lower()
+    return k if k in LAYOUTS else ALIAS.get(k) or ALIAS.get(str(v or '').strip())
+
+
+def build(spec, out_path, check=True):
+    """按 spec 建一份 PPTX。返回 {path, slides, outline, warnings, check}。"""
+    if not isinstance(spec, dict):
+        raise ValueError('spec 必须是对象')
+    slides = spec.get('slides') or spec.get('pages') or []
+    if not isinstance(slides, list) or not slides:
+        raise ValueError('spec.slides 不能为空：至少给一页（每页含 layout 与内容字段）')
+    d = Deck(theme=spec.get('theme', 'navy'), size=spec.get('size', '16:9'),
+             footer=spec.get('footer', ''), page_numbers=spec.get('page_numbers', True))
+    for i, sl in enumerate(slides, 1):
+        if not isinstance(sl, dict):
+            raise ValueError(f'第 {i} 页不是对象')
+        lay = norm_layout(sl.get('layout') or sl.get('type'))
+        if not lay:
+            raise ValueError(f'第 {i} 页 layout={sl.get("layout") or sl.get("type")!r} 不认识；'
+                             f'可选：{" / ".join(sorted(LAYOUTS))}')
+        miss = [k for k in LAYOUTS[lay] if not sl.get(k)]
+        if miss:
+            raise ValueError(f'第 {i} 页（{lay}）缺字段：{"、".join(miss)}')
+        try:
+            _emit(d, lay, sl)
+        except Exception as e:
+            raise ValueError(f'第 {i} 页（{lay}）建版失败：{e}') from e
+    res = d.save(out_path, check=check, verbose=False)
+    return dict(path=os.path.abspath(out_path), slides=len(d.prs.slides),
+                outline=[dict(page=n, layout=k, title=t) for n, k, t in d.outline()],
+                warnings=d.warnings, check=res)
+
+
+def _emit(d, lay, s):
+    g = s.get
+    if lay == 'cover':
+        d.add_cover(g('title'), g('subtitle', ''), g('meta', ''), g('notes'))
+    elif lay == 'agenda':
+        d.add_agenda(list(g('items')), g('title', '目录'), g('notes'))
+    elif lay == 'section':
+        d.add_section(g('title'), g('no'), g('subtitle', ''), g('notes'))
+    elif lay == 'bullets':
+        d.add_bullets(g('title'), g('bullets'), g('notes'), g('lead', ''))
+    elif lay == 'two_col':
+        d.add_two_col(g('title'), g('left'), g('right'), g('left_title', ''), g('right_title', ''), g('notes'))
+    elif lay == 'kpi':
+        d.add_kpi(g('title'), [tuple(k) if isinstance(k, (list, tuple)) else (str(k), '') for k in g('kpis')],
+                  g('notes'), g('caption', ''))
+    elif lay == 'image':
+        d.add_image(g('title'), g('image'), g('caption', ''), g('notes'))
+    elif lay == 'image_text':
+        d.add_image_text(g('title'), g('image'), g('bullets'), g('side', 'left'), g('caption', ''), g('notes'))
+    elif lay == 'table':
+        d.add_table(g('title'), g('rows'), g('notes'), g('col_widths'), g('note', ''))
+    elif lay == 'quote':
+        d.add_quote(g('text'), g('author', ''), g('notes'))
+    elif lay == 'compare':
+        d.add_compare(g('title'), g('left_title', '现状'), g('left'), g('right_title', '目标'), g('right'), g('notes'))
+    elif lay == 'timeline':
+        d.add_timeline(g('title'), g('items'), g('notes'))
+    elif lay == 'end':
+        d.add_end(g('text', '谢谢'), g('subtitle', ''), g('notes'))
+
+
+def main(argv):
+    if len(argv) < 2:
+        print('用法：python pptx_build.py <spec.json> <产物.pptx>')
+        return 2
+    with open(argv[0], encoding='utf-8') as f:
+        spec = json.load(f)
+    try:
+        r = build(spec, argv[1])
+    except Exception as e:
+        print(json.dumps(dict(error=str(e)), ensure_ascii=False))
+        return 1
+    import pptx_check
+    r['report'] = pptx_check.report(r['check']) if r.get('check') else ''
+    r['check'] = {k: r['check'][k] for k in ('ok', 'counts', 'slides', 'ratio')} if r.get('check') else None
+    print(json.dumps(r, ensure_ascii=False))
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv[1:]))