dsh-ppt-studio 1.1.5 → 1.2.1

package/scripts/verify-products.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+/**
+ * 产物一致性（**本机专用**：需要 PowerPoint COM 渲染，故不进 npm test）。
+ * 流程：手画生成器 → 导出到**非锁定名** pptx → COM 渲染 13 张命名 PNG → 与基线比对
+ *   · 硬不变量：layout 摘要（走 verify-handdrawn ✓）
+ *   · 次要不变量：13 张 PNG 的 sha256（差异只报不改 ✓）
+ * 用法：npm run verify:products
+ */
+import { execFileSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { readFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+const ROOT = new URL('..', import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, '$1')
+const OUT = join(ROOT, '..', 'ppt-deliverable', '手画12+1')
+const sha = (p) => createHash('sha256').update(readFileSync(p)).digest('hex')
+const run = (cmd) => execFileSync('node', cmd, { cwd: ROOT, stdio: 'inherit' })
+
+console.log('… 1/3 重出手画页面与产物（导出到非锁定名，避免 PowerPoint 占用）')
+run(['examples/hand-drawn/gen/gen13-attach.cjs'])
+run(['examples/hand-drawn/gen/gen-1113.cjs'])
+
+console.log('… 2/3 硬不变量：layout 摘要与基线')
+const vh = execFileSync('node', ['scripts/verify-handdrawn.mjs'], { cwd: ROOT, encoding: 'utf8' })
+process.stdout.write(vh.split('\n').slice(-3).join('\n') + '\n')
+if (!/与基线一致/.test(vh)) { console.log('✗ 摘要与基线不一致'); process.exit(1) }
+
+console.log('… 3/3 次要不变量：13 张 PNG sha')
+const base = JSON.parse(readFileSync(join(ROOT, 'scripts', 'fixtures', 'handdrawn-baseline.json'), 'utf8'))
+let same = 0, diff = 0, miss = 0
+for (const [name, h] of Object.entries(base.pngs ?? {})) {
+  const f = join(OUT, name)
+  if (!existsSync(f)) { miss++; continue }
+  if (sha(f) === h) same++; else { diff++; console.log('   ⚠ 像素差异：' + name) }
+}
+console.log('   相同 ' + same + '｜差异 ' + diff + '｜缺失 ' + miss + (miss ? '（交付目录不在本机 ⇒ 跳过像素比对）' : diff ? '（像素差异属环境/渲染差异，硬不变量已过 ✓）' : ' ✓'))
+console.log('==== 产物一致性：通过 ====')

package/scripts/verify-shape.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * 折线形态自证（X3）：`node scripts/verify-shape.mjs`
+ *
+ * 为什么单独成脚本：`verify:route` 的断言针对"密集夹具的交叉"，而这里要守的是**形态底线**
+ * （折返尖刺、端点悬在图形内部）——跨**所有**交付面跑，任何一批新内容都能被它兜住。
+ *
+ * 三条断言：
+ *   ① **无折返尖刺**：连续三点共线且中间点折返（用户实测图 10 顶端那根多余线就是这个）；
+ *   ② **无端点悬空于图形内部**：端点落在某个图形**内部**（离轮廓 >2px）⇒ 看起来"戳进盒子"；
+ *   ③ 检查覆盖 12 族夹具 + 两个从零批次（缺目录时跳过并说明，不假装通过）。
+ */
+import { readFileSync, readdirSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+
+let pass = 0
+let fail = 0
+const failures = []
+const ok = (name, cond, detail = '') => {
+  if (cond) { pass++; console.log(`✓ ${name}${detail ? ` — ${detail}` : ''}`) }
+  else { fail++; failures.push(name); console.log(`✗ ${name}${detail ? ` — ${detail}` : ''}`) }
+}
+
+const spikesOf = (pts) => {
+  let n = 0
+  for (let i = 1; i + 1 < pts.length; i++) {
+    const a = pts[i - 1]; const b = pts[i]; const c = pts[i + 1]
+    const sameX = Math.abs(a[0] - b[0]) < 0.5 && Math.abs(b[0] - c[0]) < 0.5
+    const sameY = Math.abs(a[1] - b[1]) < 0.5 && Math.abs(b[1] - c[1]) < 0.5
+    if ((sameX && (b[1] - a[1]) * (c[1] - b[1]) < 0) || (sameY && (b[0] - a[0]) * (c[0] - b[0]) < 0)) n++
+  }
+  return n
+}
+const rectOf = (b) => Array.isArray(b) ? { x: b[0], y: b[1], w: b[2], h: b[3] } : b
+/** 端点是否"悬在某个图形内部"（离轮廓 >2px） */
+const insideAny = (pt, boxes) => {
+  for (const b of boxes) {
+    if (b.role === 'decoration') continue
+    if (pt[0] > b.r.x + 2 && pt[0] < b.r.x + b.r.w - 2 && pt[1] > b.r.y + 2 && pt[1] < b.r.y + b.r.h - 2) return b.id
+  }
+  return null
+}
+
+/** 待检面：directory → 名称（缺目录则跳过） */
+const latest = readdirSync(tmpdir()).filter((d) => d.startsWith('pptd-families-')).sort().pop()
+const targets = [
+  ['既有 12 族夹具', latest ? join(tmpdir(), latest) : null],
+  ['从零批次 fresh-sea（当前交付批次）', 'examples/archive/fresh-sea-family'],
+]
+
+for (const [label, dir] of targets) {
+  if (!dir || !existsSync(join(dir, 'preview', 'layout.json'))) {
+    console.log(`… 跳过 ${label}（尚无 preview/layout.json；先跑对应渲染）`)
+    continue
+  }
+  const layout = JSON.parse(readFileSync(join(dir, 'preview', 'layout.json'), 'utf8'))
+  let spike = 0
+  let floating = 0
+  const spikeAt = []
+  const floatAt = []
+  layout.pages.forEach((page, pi) => {
+    // 只把**内容图形**当"盒子"：分组容器（声明了 contains 的板）与 role:decoration 都是结构件，
+    // 连线端点落在里面是正常画法（第一版没排除容器 ⇒ 误报 5~7 处，实测修正）。
+    const boxes = (page.elements ?? [])
+      .filter((e) => e.kind === 'shape' && e.bounds && e.role !== 'decoration' && !(e.contains ?? []).length)
+      .map((e) => ({ id: e.id, r: rectOf(e.bounds), role: e.role }))
+    for (const e of (page.elements ?? [])) {
+      if (e.kind !== 'line' || !Array.isArray(e.points)) continue
+      const sp = spikesOf(e.points)
+      if (sp) { spike += sp; spikeAt.push(`p${pi + 1}:${e.id}`) }
+      if (e.role === 'decoration' || e.roleReason) continue
+      for (const pt of [e.points[0], e.points[e.points.length - 1]]) {
+        const hit = insideAny(pt, boxes)
+        if (hit) { floating++; floatAt.push(`p${pi + 1}:${e.id}→${hit}`) }
+      }
+    }
+  })
+  ok(`${label}：**无折返尖刺**`, spike === 0, spike ? `${spike} 处（${spikeAt.slice(0, 4).join(', ')}）` : `${layout.pages.length} 页`)
+  ok(`${label}：**无端点悬在图形内部**`, floating === 0, floating ? `${floating} 处（${floatAt.slice(0, 4).join(', ')}）` : '全部端点贴边或落在图形外')
+}
+
+console.log(`\n==== verify-shape 结果：${pass} 通过 / ${fail} 失败 ====`)
+if (fail) { console.log(`失败项：${failures.join('；')}`); process.exit(1) }

package/scripts/visual-pair-batch.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * 并排对照工具（批量版，等价于被回滚删除的 visual-pair.mjs）—— S4 交付用
+ *
+ * 用法：
+ *   node scripts/visual-pair-batch.mjs --old <旧图目录> --new <新图目录> --out <输出目录> [--width 1400]
+ *
+ * 配对规则：按文件名开头的两位页号（01..13）配对。
+ * 输出：<输出目录>/对比-NN.png —— 上=旧（红字），下=新（绿字），同宽同缩放。
+ *
+ * 纪律（写进工具，而非只在口头）：
+ *   · 先图后数：结论前必须先看渲染图；坐标与门禁数字只作辅助。
+ *   · 改了引擎必须重出产物：对照图里的"新"必须来自重出后的 PNG。
+ *   · 对照图要能一眼判对：同内容、同缩放、上下并排、标注来源。
+ */
+import { mkdirSync, readdirSync, writeFileSync, existsSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { tmpdir } from 'node:os'
+
+const argv = process.argv.slice(2)
+const arg = (n, d = null) => { const i = argv.indexOf(`--${n}`); return i >= 0 && argv[i + 1] ? argv[i + 1] : d }
+const oldDir = arg('old')
+const newDir = arg('new')
+const outDir = arg('out')
+const width = Number(arg('width', '1400'))
+if (!oldDir || !newDir || !outDir) {
+  console.log('用法：node scripts/visual-pair-batch.mjs --old <旧图目录> --new <新图目录> --out <输出目录>')
+  process.exit(2)
+}
+const py = process.env.PPTD_PYTHON ?? 'C:\\Users\\11867\\.dsh\\dsh-runtimes\\dsh-primary-runtime\\dependencies\\python\\python.exe'
+if (!existsSync(py)) { console.log('✗ 找不到 python：' + py); process.exit(1) }
+
+const index = (dir) => {
+  const m = new Map()
+  for (const f of readdirSync(dir)) {
+    const mm = /^(\d{2})/.exec(f)
+    if (mm && /\.png$/i.test(f) && !m.has(mm[1])) m.set(mm[1], join(dir, f))
+  }
+  return m
+}
+const A = index(oldDir)
+const B = index(newDir)
+const pairs = [...A.keys()].filter((k) => B.has(k)).sort()
+if (!pairs.length) { console.log('✗ 没有可配对的页'); process.exit(1) }
+mkdirSync(outDir, { recursive: true })
+const listFile = join(tmpdir(), 'visual-pair-list.txt')
+writeFileSync(listFile, pairs.map((k) => `${k}\t${A.get(k)}\t${B.get(k)}`).join('\n'), 'utf8')
+
+const pySrc = [
+  'import sys',
+  'from PIL import Image, ImageDraw',
+  "rows = [l.rstrip().split(chr(9)) for l in open(sys.argv[1], encoding='utf-8') if l.strip()]",
+  'out_dir = sys.argv[2]',
+  'W = int(sys.argv[3])',
+  'for code, oldf, newf in rows:',
+  '    a = Image.open(oldf).convert("RGB")',
+  '    b = Image.open(newf).convert("RGB")',
+  '    a = a.resize((W, max(1, int(a.height * W / a.width))))',
+  '    b = b.resize((W, max(1, int(b.height * W / b.width))))',
+  '    bar = 26',
+  '    im = Image.new("RGB", (W, a.height + b.height + bar * 2), "white")',
+  '    d = ImageDraw.Draw(im)',
+  '    d.text((8, 7), "OLD  " + oldf.replace(chr(92), "/").split("/")[-1], fill=(180, 0, 0))',
+  '    im.paste(a, (0, bar))',
+  '    d.text((8, bar + a.height + 7), "NEW  " + newf.replace(chr(92), "/").split("/")[-1], fill=(0, 110, 0))',
+  '    im.paste(b, (0, bar * 2 + a.height))',
+  '    im.save(out_dir + "/对比-" + code + ".png")',
+  '    print("对比-" + code + ".png")',
+].join('\n')
+const pyFile = join(tmpdir(), 'visual-pair-batch.py')
+writeFileSync(pyFile, pySrc, 'utf8')
+const r = spawnSync(py, [pyFile, listFile, resolve(outDir), String(width)], { encoding: 'utf8' })
+process.stdout.write(r.stdout ?? '')
+if (r.stderr) process.stderr.write(r.stderr)
+console.log(`共 ${pairs.length} 张对照图 → ${outDir}`)
+process.exit(r.status ?? 1)

package/skills/ppt-studio-diagram/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: ppt-studio-diagram
+description: 复杂图绘制总纲：何时调用哪个机制（attach/正交化/结构声明/门禁 code 对照）、12 类图的配方索引、验证纪律与坑表。
+whenToUse: 要画任何非模板化的复杂图（流程/泳道/层级/时序/状态机/漏斗/环/矩阵/时间轴/对比/分层）或手画遇阻、门禁报错时加载。
+---
+# 复杂图绘制总纲（手画 + 按需查阅子 skill）
+
+> **优先级**：用户指令 > 本手册经验值 > 工具默认。本手册给的是启发式与反例，**不定义任何门禁数值**；
+
+## 铁律（每条都有代价换来的）
+1. **先图后数**：任何"画好了/修好了"的结论，必须**先渲染并亲眼看图**才能下；坐标与门禁数字只作辅助。
+2. **改了引擎/改了页 ⇒ 必须重出产物**（PNG/pptx）并替换到位；只改代码不重出 = 未完成。
+3. **出图必过门禁**：`node scripts/verify-*.mjs` 与 `npm test`；有错先定位再改，绝不改门禁迁就图。
+4. **占位必预留**：标题带 / 标签带 / 徽标栏 / 导轨栏，**先算好空间再摆元素**；后摆的东西不许压已有的。
+5. **连线端点必须落在元素边上**：线的端点若不与任何元素边重合，引擎会**吸附**到附近元素 ⇒ 出现莫名长线。
+6. **能力边界如实标注**：引擎不支持的东西（阴影/高光/手绘笔触）不要假装；要么不用，要么标"近似/不支持"。
+7. **每条边都必须有标签**：图上任何转移/连线都要能读出"从哪到哪、什么条件"；缺标签 = **内容缺失**。门禁抓不到（实测主链 5 条标签全丢，门禁仍 0 错）——只能靠看图与旧版并排发现。
+8. **有意重叠要声明**：`expectedOverlaps` 只用于**真有意**的穿入（如回路进分组容器），并写明理由；绝不用来掩盖缺陷。
+
+## 固定流程
+1. 读子 skill 拿**配方数值**（一族一份：骨架 → 流向 → 尺寸/间距 → 该族坑 → 检查清单）。
+2. 生成 `elements:`（显式坐标）→ `resolveDeck` → `renderDeck`（出 HTML+layout.json）。
+3. `verifyDeck` 逐页过门禁 → 有错就改（对照 pitfalls）。
+4. `exportPptx` → **真渲染 PNG**（COM；不可用则 Edge 无头截预览 HTML）。
+5. **自己读图**：看层级/留白/避让/连线语义（谁指向谁）→ 不满意就地改 → 回到 2。
+6. 交付：PNG + pptx + 一句"这页看什么"的说明。
+
+## 两条看图通路
+- COM：`lib/msrender.js` 的 `renderPptxToPng(pptx, outDir, { pages: [...] })`（导出物必须能被 PowerPoint 打开）。
+- 备用：Edge 无头截预览 HTML —— `msedge --headless=new --window-size=W,H --screenshot=out.png file:///...html`（视口要按画布比例设，否则画面会挤在角落）。

package/skills/ppt-studio-diagram/capability-matrix.md

@@ -0,0 +1,22 @@
+# 能力边界（capability-matrix）
+
+> 交付时必须如实标注：**不支持的要么不用，要么标"近似"**；能让它在写入时就**报错**最好。
+
+## 支持（预览与 OOXML 两端同源）
+| 能力 | 说明 |
+|---|---|
+| 纯色 / **线性渐变**填充 | fill 对象形如 {type:'gradient', stops:[{pos,color}], angle}；预览转 CSS linear-gradient、导出转 a:gradFill |
+| 形状图元 | rect / roundRect / ellipse / triangle / parallelogram / diamond / pentagon / hexagon / chevron / octagon / star5 |
+| **custGeom 任意路径** | path.w/h + moveTo/lnTo/quadBezTo/cubicBezTo/arcTo/close ⇒ 梯形等自定义几何 |
+| 折线 / 虚线 / 两端箭头 | line.points 支持 N 点；dash: dash；arrow: true|false|'end'|'both' |
+| 分组与包含 | contains 声明"我包住谁"；跨容器穿入用 expectedOverlaps 声明 |
+
+## 不支持（如实标注，勿假装）
+| 能力 | 现状 |
+|---|---|
+| **逐形状阴影 / 卡片高光** | 导出层只有主题级 effectStyleLst，无逐形状 a:outerShdw；预览端无 box-shadow ⇒ 只能近似为"纯色/渐变 + 描边" |
+| 手绘笔触质感 | 无 ⇒ 明确标"不支持真笔触" |
+| 3 段以上复杂渐变 | 能写 stops 但视觉收益有限，建议 2 段 |
+
+## 规矩
+写"引擎画不出来的值"应当**直接报错**（例如 elevation 只允许 none），绝不静默无效。

package/skills/ppt-studio-diagram/composition.md

@@ -0,0 +1,22 @@
+# 构图技法（composition）
+
+## 标题体系
+- 大标题 25pt bold（深色）@ (60,34)，宽 ≤720。
+- 分栏/分层标签用 ①②③ + 14pt bold 主色，放在各栏上方一行。
+
+## 容器与分组
+- 需要"这几位是一组"时，用**软填充容器**（浅紫 #EDE9FE 一类）包住整组，而不是只画个线框。
+- 容器**必须把内部所有元素写进 contains**；连线穿容器要按纪律精确声明。
+
+## 形状对比与色调层级
+- 端点/决策用 **parallelogram / diamond**，过程用 rect/roundRect，数量递减用 **custGeom 梯形**。
+- 层级靠三件事：**字号级差**（25/15/13/11）、**色彩重量**（主色 vs accent vs 浅底）、**形状差异**。
+
+## 留白
+- 内容占中间带（约 y 130..470），四边留 ≥40px；宁少勿挤。
+- 一页只允许**一处** accent 高亮（多了等于没有重点）。
+
+## 参考稿驱动
+拿到参考图时：先量它的结构（标题位置与字号、分几栏/几层、容器与形状、回路走哪、留白比例），再用同一结构画我们的内容 —— **不要凭感觉仿"风格"**。
+
+

package/skills/ppt-studio-diagram/mechanisms.md

@@ -0,0 +1,141 @@
+# 机制调度手册（何时调用哪个机制）
+
+> **动笔前先读权威规则**：`ppt_schema` 工具（源码 `src/scaffold.js` 的 `SCHEMA_REF`）里写着引擎的全部词汇与硬规则。
+> 本文件是"**什么时候该用哪一条**"的索引；两者冲突时**以 SCHEMA_REF 为准**。
+
+## 0. 三条总纲（血泪换来的）
+
+1. **连边一律优先 `attach`，绝不手算像素。**
+   实测教训：某页我手写"卡片右沿 x=628"，引擎 `attach` 解析后是 **608** —— 我错了 20px 而不自知。
+   `attach: { from: { ref: <id>, side: top|right|bottom|left }, to: { … } }` ⇒ 引擎把两端锚到**真实边缘**，
+   并把"你写的坐标被改了多少"记成 `attach-override` 警告（**不是报错，是透明提示**）。
+2. **错与警都要逐条读；警告不解释不许收工。**
+   实测教训：我连续几轮"门禁 0 错"就收工，结果用户反馈的问题（竖线穿字、折点贴箭头、箭头没接上）
+   **全都在警告里早就报了**：`line-crossing` / `arrow-end-short-run` / `arrow-end-gap`。
+   0 错 ≠ 没问题；**0 错只说明"没有不可声明级缺陷"**。
+3. **刻意设计要"声明"，不要靠"绕过"。**
+   环/放射/漏斗的斜段、汇流交叉、装饰底板，都该 `role: decoration` 或 `roleReason: "…"` 明说；
+   **不要**用 `expectedOverlaps` 去盖"压字/压盒"（那是掩盖真实缺陷）。
+
+## 1. 连接线与箭头
+
+| 想要的效果 | 用什么 | 备注 |
+|---|---|---|
+| 端点贴到某个元素的边 | **`attach`** | 首选；斜边形状（parallelogram/triangle/diamond）也接到**真实斜边** |
+| 折线只用横/竖段 | 交给引擎（默认自动正交化） | 显式 `elements` 的折线**已自动**过 `orthogonalize` |
+| 箭头前留足直段（≥18px） | 交给引擎（默认自动修） | **已自动生效**；修不了（会造折返）就原样保留并由 `arrow-end-short-run` 报出 |
+| 刻意保留斜段（环形/放射/漏斗） | `role: decoration` 或 `roleReason` | 引擎的自动正交化对"斜段折线"自动跳过，但**警告仍会报** ⇒ 要声明 |
+| 端点刻意留空（2–10px 缝） | `roleReason: "…"` | 否则报 `line-end-off-edge`/`arrow-end-gap` |
+
+## 2. 门禁 code 对照表（看到 → 怎么做）
+
+| code | 级别 | 含义 | 处置 |
+|---|---|---|---|
+| `line-crossing` | 警示 | 两条线交叉（+型） | 换车道/换进出边；刻意汇流 ⇒ `roleReason` |
+| `line-end-off-edge` | 警示 | 端点离元素 2–10px 没接上 | **改 `attach`**（首选）或声明刻意留空 |
+| `arrow-end-gap` | 警示 | 带箭头端点没接到目标 | 同上 |
+| `arrow-end-short-run` | 警示 | 箭头前直段 <18px | 挪拐点；**`attach` 通常直接消灭它** |
+| `arrow-tip-inside-shape` | 警示 | 箭头插进图形内部 | 改 `attach` 到边缘；刻意插入 ⇒ `roleReason` |
+| `line-diagonal-segment` | 警示 | 折线有斜段 | 连接线改轴对齐；刻意（环/放射）⇒ `role: decoration` |
+| `attach-override` | 警示 | 你的手写坐标与 attach 解析不一致 | **正常**；想清零就把 points 改成解析后的真实值 |
+| `hotspot` / `density` | 建议 | 密集区/信息密度提示 | 信息性，可保留；但要**明说是建议级** |
+| `content-collision` | **错** | 文字互压 | **不可声明豁免**，必须改布局 |
+| `unexpected-overlap` | **错** | 设计外重叠 | 改布局，或按层级正确声明 |
+
+## 3. 结构声明的正确姿势
+
+- 容器（象限框、泳道带、软底板）**必须把内部元素写进 `contains`**；无内容的形状**省略** `contains`（不写空数组）。
+- **声明闭包**：嵌套承载只需声明**相邻层**（card×inBox、inBox×inText），隔层组合由传递自动通过。
+- 语义性底板/背景带优先 `role: decoration`（豁免重叠），不要用 `expectedOverlaps` 盖。
+- 跨容器连线（泳道跨道）**必然穿带** ⇒ 只把**真正相交**的元素对写进 `expectedOverlaps`；过度声明会产生 `declared-stale` 噪音。
+
+## 4. 渲染与交付通路（别在这栽跟头）
+
+1. **渲染前确认没有进程占用目标 pptx**（尤其 PowerPoint 开着）——否则 COM 会**静默渲染内存里的旧副本**，
+   导出还会 EBUSY 失败。对策：导出到**带时间戳的新文件名**。
+2. **重出前先清空输出目录**，否则旧 PNG 残留会被当成新图复制。
+3. **读图通路按路径缓存** ⇒ 大改后的页面要**复制到新文件名再读**。
+4. 复跑 `smoke.mjs` 前先 `Remove-Item examples\smoke\.tmp-home -Recurse -Force`（它非幂等，残留即崩）。
+5. **"崩"与"断言红"要分清**：崩多为环境/残留，红才是真回归。
+6. **改了引擎必须重出产物**；只改源码不重出 = 用户看到的还是旧的。
+
+## 5. 一页图的固定动作单
+
+1. 读 `SCHEMA_REF`（机制词汇 + 本节对照表）；
+2. 写 `elements`：**连边用 `attach`**、容器写 `contains`、刻意设计写 `role/roleReason`；
+3. `resolveDeck` → `renderDeck` → `verifyDeck`：**错清零，且逐条解释每一条警**；
+4. 导出 → **真渲染 PNG** → **自己读图**（层级/留白/避让/语义）→ 不满意回第 2 步；
+5. 与旧版/参考稿**并排对照**，记录"更好/持平/变差"及依据。
+
+## 6. 各子 skill 的专属机制速查
+
+| 子 skill | 必用机制 / 专属要点 |
+|---|---|
+| tree | 父→子折线用 `attach(bottom→top)`；同组子树加**分组容器**（contains 相邻层） |
+| matrix | 象限框为容器，**格内卡片写进其 contains**；高亮**唯一** |
+| timeline | 刻度线 `attach` 到标签/主轴端点（避免 4px 缝）；里程碑**只高亮一个** |
+| swimlane | 跨道箭头用 `attach` 两端 + 只声明**真正相交**的泳道带；带 contains 本道任务 |
+| compare | 面板 contains 要点卡；中间标记**宽度 ≤ 间隙**（36px 落进 40px） |
+| loop | 环形弦 = 刻意斜段 ⇒ `role: decoration` + `roleReason: 环形语义`；端点用 `attach` |
+| funnel | 用 **custGeom 梯形**（矩形堆叠是台阶不是漏斗）；段间边界相接不算重叠 |
+| steps-ring | 真圆用 `ellipse`（浅填充+主色描边）+ 编号小圆点；点与标签留 ≥24px |
+| sequence | 生命线 `attach` 到参与者卡底边；消息标签加**白底芯片**；汇流交叉写 `roleReason` |
+| state | 转移标签贴箭头上方 **4px**，卡距≥标签宽（70px）；返工回边走**外圈车道** |
+| flow | 起止 `roundRect`、末步 accent；异常回边标签放**车道上方**独立一行 |
+| layers | 层带 contains 层内卡；层间箭头用 `attach`（left/right 边） |
+
+## 7. 契约：2 点直连线 ≠ 折线（2026-09 实测确认，**别再踩**）
+
+| 形态 | 导出 | 规则 |
+|---|---|---|
+| **2 点直连线**（含斜向！） | `<p:cxnSp>`（带 `flipH`/`flipV`） | **受支持的连接符** ✓ —— **绝对不要正交化它** ✗ |
+| **n≥3 折线** | 一帧 `p:sp` + `custGeom` 开放路径 | **保证轴对齐** ✓（斜段会被自动拆成横/竖两段） |
+
+**实测事故**：我曾把"折线永远轴对齐"套到 2 点斜连线上 ⇒ 它们被拆成 custGeom ✗ ⇒
+`cxnSp` 数归零 ⇒ smoke 的 **6 条连线方向专项断言全崩**（`✗ 连线：全部 6 条 cxnSp 已导出` +
+`TypeError … reading 'flipH'`）✓。**这是代码真错，不是 fixture** ✗。
+
+**实现现状**（`src/pptd/route-geometry.js` 的 `routePolyline`）：
+```js
+if (raw.length < 3) return raw                    // 2 点直连线：原样（cxnSp 契约）
+const fixed = orthogonalize(arrowEndRuns(orthogonalize(raw), arrow))
+return hasFoldback(fixed) ? raw : fixed           // 折返守卫：不造尖刺，交门禁报
+```
+**豁免声明**（`layout.js`，只看显式声明）：`orthogonal: false` ／ `role: decoration` ／ `roleReason: '…'`。
+
+**推论**：环形/放射图若用 **2 点弦**（如 06/08）⇒ **本来就不会被正交化** ✓，
+此时写 `role: decoration` 只为**消掉 `line-diagonal-segment` 警告** ✓（属警告清理，不是功能必需）。
+
+## 8. 泛用性不降级（G3）：手画是**一等公民**，不是退路
+
+**引擎的既定教义**（`SCHEMA_REF` 第 6 条原文）："一页可以**既用 diagram 又手写元素**（缝合页）；
+assistant 想要家族库没有的图，就按上面几条手写 elements 拼出来——**这是被支持的路径，不是退路**。"
+
+
+**机制层面手画与族已等价**（G1 完成后）：
+| 能力 | 族 | 手画 |
+|---|---|---|
+| 正交化 + 箭头端 ≥18px + 折返守卫 | ✅ | ✅ **同一份实现**（`route-geometry.js`） |
+| `attach` 锚边（含**斜边真实轮廓**） | ✅ | ✅ 同一实现 |
+| 线×文字 / 线×线 / 贴边 / 尖端入形 / 斜段 等检查 | ✅ | ✅ 同一门禁 |
+| 结构声明（`contains`／`expectedOverlaps`／`role`） | ✅ | ✅ 同一套 |
+| **自由构图**（族没有的图） | ❌ 受族模板限 | ✅ **不受限**（图 13 即样例） |
+
+⇒ 泛用性**严格更强** ✓：族覆盖范围内按 skill 配方调用机制 ✓；范围外退化为手画但**机制不减** ✓。
+
+
+
+### 补充 code（§2 对照表增补）
+
+| code | 严重级 | 含义 | 怎么修 |
+|---|---|---|---|
+| `unknown-key` | **warning（不阻断）** | 页面级/元素级出现**未知键**（拼写错误或残留字段）——过去会被静默忽略，可能悄悄出空页/漏项 | 改对键名；若是合法新字段，说明白名单漏项（`scripts/check-unknown-keys.mjs` 会在本仓示例上**直接报失败**逼你补） |
+
+
+## 门禁与 skill 的分工（发版前确立的原则）
+
+- **skill 管「做法选择」**（调不调、调哪个、用哪种画法）—— **由模型自由决定**；
+- **门禁只锁两类东西**：① **事实**（几何/文本的客观缺陷，如箭头前直段 <18px、线穿文字）；② **声明自洽**（你声明了 A 与 B 的关系就必须自洽，如 `contains` / `attach` / `badgeOf` / `roleReason`）；
+- **风格、审美、表达取向一律不进 error**（要不要分组容器、环用卡片还是真圆 ⇒ 属 skill 建议与参考对照）；
+- **error 只能来自事实或声明自相矛盾；启发式只能出 warning**；
+- 每条警告都必须有**处置结论**（见 `docs/17`）；**不许用声明掩盖真缺陷**。

package/skills/ppt-studio-diagram/pitfalls.md

@@ -0,0 +1,97 @@
+# 踩坑索引（症状 → 根因 → 修法）
+
+
+## A. 校验与结构声明
+
+| # | 症状（门禁/报错原话） | 根因 | 修法 |
+|---|---|---|---|
+| A1 | `contains: non-empty array of element ids` | 给**没有内容**的形状写了 `contains: []` | 无内容就**整个省略** `contains` |
+| A2 | `contains 声明不成立：父盒未真正包含子元素（pad=0）` | 子元素实际**不在**父盒矩形内（常见于"父盒加高/挪动，子元素没跟着动"） | 改父盒尺寸时**同步重排内部**（三处一起改：盒 / 标题 / 副标题） |
+| A3 | `"xxx" 不是本页元素 id（防呆）` | `contains` 里引用了**不存在**的元素（或漏发该元素） | 先发元素再引用；或删掉该 id |
+| A4 | `unexpected-overlap：容器 × 内部卡片` | 容器**没登记**住在里面的元素（象限容器→风险卡、泳道带→本道任务） | 容器的 `contains` 列出**全部**内部元素 id |
+| A5 | `relation-invalid：容器 × 芯片内文字` | 把**芯片里的文字**当成了外层带的子元素（它属于芯片） | 文字只登记在**直接父级**的 `contains` 里 |
+| A6 | `declared-stale：预期重叠声明已失效` | `expectedOverlaps` **过度声明**（声明了一对实际不相交的元素） | 只声明**真正相交**的对；删掉多余的 |
+
+## B. 连线与几何
+
+| # | 症状 | 根因 | 修法 |
+|---|---|---|---|
+| B1 | 页面上出现**莫名长横线**，或线端点"吸附"到别的元素上 | 线的端点**不在任何元素边上** ⇒ 引擎自动吸附 | 端点**精确落在元素边**（x = 卡左边/右边，y = 卡心） |
+| B2 | `unexpected-overlap：卡 × 线`（交叠十几像素） | 线的起点画在卡**内部**（如 `A.x + 6`） | 端点改到**卡边**（`A.x`）并声明 `side: left` 等 |
+| B3 | `unexpected-overlap：泳道带 × 跨道连线` | 跨道连线**必然**穿带（泳道图的设计本质） | 按纪律**显式声明** `expectedOverlaps` 并写明"属设计意图"，**不得改门禁** |
+| B4 | 回边竖管**压住卡下标签** | 车道基准没让开标签带 | 车道整体下移（≥ 标签带高 + 8px）；标签放在车道**上方** |
+| B5 | `style-connector-off-target：还有 4.0px` | 连接符尖端离目标轮廓太远 | 尖端**贴住**目标边（±2.5px 内） |
+| B6 | 环形图连线从卡心出发、压住卡片 | 同 B2 | 用**卡边 + 沿环方向**裁剪端点（`off ≈ 半卡宽`） |
+
+## C. 文字与间距
+
+| # | 症状 | 根因 | 修法 |
+|---|---|---|---|
+| C1 | `text-overflow：估算宽 65px / 容器 44px` | 节点多于列宽、或左对齐槽位没重算 | 槽宽从卡片重算；**放不下按度量自动缩字号**（下限 9pt） |
+| C2 | `content-collision：标题 × 副标题`（交叠 2px） | 两行文字框挨太紧 | 拉开 ≥4px；或加高父盒并两行一起重排 |
+| C3 | `style-badge-too-tight`（徽标压字） | 徽标竖栏居中，压到第二行文字 | **有副标题时徽标与标题同行** |
+| C4 | `style-contrast-low：1.22:1`（白字压浅蓝渐变） | 浅色/渐变底上硬用白字 | 文字色按**对比度自动选**；渐变要按 **stops 两端取最差**判 |
+| C5 | 标签被线穿过 | 标签落在车道上 | 标签移到车道**上方**一行 |
+
+## D. 工程与流程（我踩过、代价最大的）
+
+| # | 症状 | 根因 | 修法 |
+|---|---|---|---|
+| D1 | `ReferenceError: require is not defined in ES module scope` | 脚本存成 `.mjs` 却用 `require` | CJS 用 `.cjs`；ESM 用 `import` |
+| D2 | 脚本语法错、输出乱码/`ParserError`，反复改不对 | 把带 `\n`、引号的复杂 JS **塞进 PowerShell here-string** ⇒ 转义层层叠加 | **用文件工具直接写脚本文件**（字节可控）或**直接写 YAML** |
+| D3 | `Slides.Item : Integer out of range. 2 is not in…` | 渲染请求的页数 > pptx 实际页数 | 按 `ctx.pages.length` **动态**传页数 |
+| D4 | 改了引擎"看起来修好了"，用户打开的还是旧文件 | **只改代码没重出产物** | 铁律：改了引擎/页面 ⇒ **重出 pptx/PNG 并替换到位** |
+| D5 | 只看坐标就宣布"修好了"，实际图上仍有问题 | 数值 ≠ 观感 | 铁律：**先读图再下结论**；图与门禁互补，二者都给 |
+| D6 | 补丁"语法正确、构建通过"，目标却没变化 | 锚点落在**别的族/别的分支**（8 个族共用相似代码） | **插桩定位**（在可疑函数里放唯一标记，渲染后看 notes 是否出现）；或先算**函数区间**只改区间内 |
+| D7 | 门禁/合规抓不到"内容缺失"（如标签全丢） | 门禁只查几何与可读性，不查语义完整性 | 与**旧版并排读图**对照内容；把"每条边都要有标签"写进清单 |
+| D8 | 复杂度量爆炸：改了盒高，子元素掉出盒外 | 尺寸改动**没有联动** | 改尺寸时**同时**检查：父盒、内部元素、连线端点 |
+
+## E. 渲染与交付通路（2026-09 实测补充）
+
+| # | 症状 | 根因 | 修法 |
+|---|---|---|---|
+| E1 | 交付的 PNG 与源码/门禁不一致（改了页面但图没变），且 sha 与旧版一字不差 | **有进程打开着目标 pptx（尤其 PowerPoint）**⇒ COM `Presentations.Open` 拿到的是**内存里的旧副本**，静默渲染旧内容 | 渲染前确认没有进程占用该 pptx；**重出前先清空输出目录**，避免旧 PNG 残留被当成新图复制 |
+| E2 | `exportPptx` 抛 `open … .pptx`（EBUSY/EPERM）、管线中断 | 同上，文件被 PowerPoint 锁住 | 请用户关闭后重出；或导出到新文件名 |
+| E3 | 复制出的 PNG 是别的/更早的页面 | 复制步骤依赖渲染器输出名（`01.png…`），若渲染失败/被锁则**复制的是上次残留** | 渲染后校验输出文件的时间戳/sha 再复制；失败就中断，别静默复制 |
+| E4 | 读图复核时看到的是旧图（同路径读两次结果完全相同） | 看图通路**按路径缓存**了归一化副本 | 复核大改后的页面时，**复制到新文件名再读**（或改路径） |
+
+## B7. 斜边 prst 的端点：轮廓 ≠ bbox
+
+| 症状 | 根因 | 修法 |
+|---|---|---|
+| 平行四边形/chevron 等斜边形状旁边，箭头看着"没接上"（留 ~15px 缝） | `parallelogram` 的路径是 `(0,h)→(x1,0)→(w,0)→(w−x1,h)`，`x1 = adj/100000 × min(w,h)`（默认 adj=25000）⇒ **腰高处可见边比 bbox 内缩 x1/2** | 端点按**轮廓**算：左/右侧各内缩 `x1/2`（118 高时约 15px） |
+| 按轮廓修完反而报 `unexpected-overlap 形状×线` | **门禁按 bbox 判形状** ⇒ 端点进入 bbox 必报重叠 | 这属 bbox×斜边轮廓的**固有偏差**，按纪律 `expectedOverlaps` **显式声明并写明理由**（不是掩盖缺陷）；或改从**上下边**接入（水平边无内缩，最干净） |
+
+| E5 | `node scripts/smoke.mjs` 第二次跑**必然崩溃**（`templates.js:334 目标目录已存在 deck.yaml，拒绝覆盖`） | smoke **非幂等**：它固定用 `examples/smoke/.tmp-home/_ws` 做模板物化目标，跑完不清理 ⇒ 残留 | 复跑前先 `Remove-Item examples\smoke\.tmp-home -Recurse -Force`。另：**"崩"与"断言红"要分清**——崩多为环境/残留，红才是真回归；盲目把崩当成自己的代码问题会浪费整轮 |
+
+**E5 补充（2026-09 实测第二次踩到）**：只清 `.tmp-home` 不够 —— smoke 还会改写多种 fixture
+（`band-smoke / media-smoke / overlap-smoke / scaffold-smoke / v3-smoke / smoke`）。
+实测现象：`✗ 连线：全部 6 条 cxnSp 已导出` + `TypeError: Cannot read properties of undefined (reading 'flipH')`
+（看似"导入导出坏了"，实为**残留副本**）。稳妥配方：
+
+```powershell
+Remove-Item examples\smoke\.tmp-home -Recurse -Force -ErrorAction SilentlyContinue
+git checkout -- examples     # 把被 smoke 改写的跟踪 fixture 恢复原样
+node scripts/smoke.mjs
+```
+
+判据：**同一 HEAD 下上一轮 322/0、这一轮崩溃 ⇒ 先怀疑 fixture，再怀疑代码**（本阶段两次都是 fixture）。
+
+
+
+## F. 流程坑（发版准备期实测，血泪级）
+
+- **F1 清 fixture 只能用 `git checkout -- examples/smoke`** —— 用 `git checkout -- examples` 会连 `examples/hand-drawn/gen/*.cjs` 一起回滚，把刚做的手画/生成器修改一并抹掉（实测损失过一次修复）。
+- **F2 参数化功能必须同时测「缺省路径」** —— `const X = argv[2] || X` 这类自引用（TDZ）会被「只测带参数路径」短路掩盖 ⇒ 缺省路径必崩且躲过全部测试；生成器现由 `check-generators.mjs`（语法级）兜底，运行期覆盖仍未做（见已知限制）。
+- **F3 改基线必须留痕** —— `--capture` 曾整文件覆写导致上次原因丢失；现保留 `history` + 支持 `--reason`，且 `verify-handdrawn` 会**断言** history 与 reason 存在。
+- **F4 破坏性脚本先只读定位、全量断言，再动手** —— 边定位边删 ⇒「定位失败时已删一半」；范式：Phase A 打印现场 + 断言 ⇒ Phase B 执行（异常即 `git reset --hard`）。
+- **F5 多步脚本里每个判据都要单独取退出码** —— 曾在 `check-*` 子检查失败时因 `$LASTEXITCODE` 取到的是别的命令而**误提交**（后经 amend 更正）⇒ 判据不过不提交。
+- **F6 Windows 工具链三坑** —— `npm`/`tar` 是垫片 ⇒ 必须 `execSync`（`execFileSync` 直接 ENOENT）；命令输出带 `\r` ⇒ 精确匹配前先去掉；检查器扫描要排除自身（词表自指）。
+
+## G. 发布通道坑（2026-09-30 实测）
+
+- **G1 推 tag ≠ 发布** ✗ —— `publish.yml` 由 **`release` 事件**触发（OIDC 受信发布）⇒ 只推 `v1.2.1` 不会发；必须创建 GitHub Release。1.2.1 首次就因此静默没发（registry 停在 1.2.0）。
+- **G2 别把本地 `npm publish` 的失败当发布失败** ✗ —— 本机无 npm 凭据（E401）是**设计如此**；发布判据只能是 **registry 现状**（`npm view … version`）。
+- **G3 创建 Release 就等于发布** ✗ —— 未获用户明确指令不得创建 Release；撤回需**删 Release + `gh run cancel`**（本地 pack 的 tag 不会自动发）。
+- **G4 skill 的 frontmatter 是 YAML** ✗ —— 描述里写 `role: decoration` 这类含 **`: `** 的纯量会导致该 skill **静默解析失败**（症状：14 个对、1 个不见）⇒ 描述里用全角「：」或加引号。
+- **G5 用自己的注册器自证** ✓ —— 改完 skill 立刻跑 `bundledSkillNames()`（插件自带扫描器）确认数量与名字，**别等装到用户机器上才发现**。

package/skills/ppt-studio-diagram/routing.md

@@ -0,0 +1,17 @@
+# 连线规则（routing）
+
+## 端点
+- **端点必须落在元素边上**（x = 卡左边/右边，y = 卡心）。落在卡内 ⇒ 门禁报"卡 × 线"；落在空中 ⇒ 引擎会**自动吸附**到附近元素，画出莫名长线。
+- 有 `attach` 能力时优先用锚定；否则手工把坐标算到边上。
+
+## 折线与车道
+- 正交折线：先竖后横或先横后竖，转角 90°；拐点尽量落在元素间距中线。
+- **回边走外圈车道**（图上/图下），车道基准要让开所有预留带（标题带、标签带）。
+- 回边标签放在**车道上方独立一行**，不允许压在车道上。
+
+## 标签遮罩
+- 标签必须落在线上时，用**白底小圆角芯片**承载文字（芯片写进 contains），模拟"遮罩"效果。
+- 连线贴边判据：尖端距目标轮廓 **≤2.5px**。
+
+## 跨容器
+- 泳道/分组容器内的连线必然穿容器 ⇒ 把**真正相交**的元素对写进 `expectedOverlaps` 并写明"设计意图"；过度声明会产生 declared-stale 噪音。

package/skills/ppt-studio-diagram/text-and-spacing.md

@@ -0,0 +1,16 @@
+# 文字与间距（text-and-spacing）
+
+## 字号级差（一页内固定用这几档）
+25（页标题）/ 16（面板标题·卡片标题）/ 13–15（卡内主文）/ 11–12（副标题·注解·标签）。
+
+## 槽位与自动缩字
+- 形状内文字**必须写进该形状的 contains**；无内容的形状**省略 contains**（不能写空数组）。
+- 文字放不下时：先**从卡片重算槽宽**，再按度量**自动缩字号**（下限 9pt）；宁可缩字，不要溢出。
+- 左对齐时槽宽 = 卡宽 − 左侧让位（徽标栏）− 右侧留白；**徽标与标题同行**，不要把徽标竖着居中（会压第二行）。
+
+## 行距与互压
+- 同一盒内两行文字框间隔 ≥4px；改了盒高要**同时重排内部两行**（否则 contains 不成立）。
+
+## 对比度
+- 文字与底色对比度 **≥3:1**；渐变底要按 **stops 的最亮端与最暗端分别判、取最差**（不许用平均值）。
+- 浅色/渐变底上不要默认白字：按对比度**自动选**字色。

package/skills/ppt-studio-diagram/verify.md

@@ -0,0 +1,50 @@
+# 验收流程（verify）
+
+## 固定五步（每页都要走完）
+1. 按子 skill 配方生成显式 `elements`（不手写"裸坐标"乱撞）。
+2. `resolveDeck` → `renderDeck`（产出预览 HTML 与 layout.json）。
+3. **过门禁**：`verifyDeck` 逐页 0 错（关系/重叠/溢出/对比度/贴边）；有错按 pitfalls 定位后再改。
+4. `exportPptx` → **真渲染 PNG**。
+5. **自己读图**：看层级、留白、避让、连线语义（谁指向谁）；不满意就地改，回到第 2 步。
+
+## 两条看图通路
+- **COM（首选）**：lib/msrender.js 的 renderPptxToPng(pptx, outDir, { pages })；页数要按实际页数传（传大了报 Slides.Item 越界）。
+- **Edge 无头（备用）**：msedge --headless=new --window-size=W,H --screenshot=out.png file:///...preview.html —— 视口要按画布比例设，否则画面挤在角落。
+
+## 判定口径（同内容对照时）
+① **内容一致**（语义/数据/标签不丢 —— 门禁抓不到，只能靠与旧版并排读图）；② **可读性不降**（字号/对比度/避让，门禁可量化）；③ **观感不降**（构图/层级/留白，人眼判定）。
+
+## 铁律
+先图后数；改了引擎/页面必须**重出产物并替换**；边界能力如实标注；不用 expectedOverlaps 掩盖真实缺陷。
+
+## 铁律之二：**警告也要逐条读**（2026-09 血的教训）
+
+> 我连续多轮"门禁 0 错"就收工 ⇒ 用户连续反馈：竖线穿字、折点贴着箭头、箭头没接上平行四边形。
+> 回查发现**这些全都在警告里早就报了**：`line-crossing`、`arrow-end-short-run`、`line-end-off-edge`、`arrow-tip-inside-shape`。
+> ⇒ **0 错 ≠ 没问题**；0 错只等于"没有不可声明级缺陷"。
+
+收工前必须做到：
+1. 打印本页**全部警告**（按 code 分组计数）；
+2. 每条警告给一句**处置结论**：改布局 / 改 `attach` / 写 `roleReason` 声明 / 判定为**信息性建议**（`hotspot`/`density`）；
+3. **一条不解释就不许收工**。
+
+配套索引见 `mechanisms.md`（何时用哪个机制 + 门禁 code 对照表）。
+
+## 铁律之三：验证输出的"看法"（2026-09，三次踩坑）
+
+1. **验证输出一律原文落屏，不许过滤成摘要** ✗
+   我连续三次把 smoke/probe 输出 `Select-String` 成几行摘要 ⇒ 失败断言**没留下** ⇒ 无法归因，
+   只能猜（其中两次猜错）✓。至少保留**失败行 + 其上下文**；宁可刷屏。
+2. **判据只看汇总行与退出码** ✓
+   `==== 结果：N 通过 / M 失败 ====` ／ `node --check` 的 exit code ／ `抓取断言：全部命中`。
+   **绝不要用 `grep ✗` 当失败探测器** ✗ —— smoke 正文里**故意造错的 fixture** 自身就带 `[✗]`，
+   会把"通过用例的内部内容"当成失败 ✓（我被骗过一次 ✓）。
+3. **复跑 smoke 前先清 fixture** ✓
+   ```powershell
+   Remove-Item examples\smoke\.tmp-home -Recurse -Force -ErrorAction SilentlyContinue
+   git checkout -- examples
+   ```
+4. **归因顺序：先 fixture，后代码 —— 但别停在 fixture** ✓
+   同一 HEAD 上轮绿、本轮崩 ⇒ **先怀疑 fixture 残留** ✓（本阶段三次如此）；
+   但本轮实测反例：`cxnSp` 断言崩**是代码真错** ✗（我把 2 点斜连线正交化了 ✓）⇒
+   怀疑过 fixture 之后，**必须再核对一次"我的改动是否真的违反契约"** ✓。