dsh-ppt-studio 1.1.4 → 1.2.0

package/scripts/handdrawn-option-probe.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ *
+ *   · `pyramid: true` ⇒ 反向（逐段**放宽**的金字塔，而不是收窄的漏斗）
+ *   · `minRatio`      ⇒ 末段宽度相对首段的比例（末段宽 = 首段宽 × ratio）
+ * 本探针用**显式 custGeom 元素**把两种变体画出来并过门禁（不需要族代码）。
+ *
+ * 用法：node scripts/handdrawn-option-probe.mjs
+ */
+import { mkdirSync, writeFileSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { resolveDeck } from '../src/pptd/schema.js'
+import { renderDeck } from '../src/pptd/render-html.js'
+import { verifyDeck } from '../src/verify.js'
+
+const ROOT = new URL('..', import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, '$1')
+const dir = join(ROOT, 'examples', 'option-probe')
+mkdirSync(join(dir, 'pages'), { recursive: true })
+writeFileSync(join(dir, 'deck.yaml'), [
+  'version: 1', 'title: 选项探针', 'size: [960, 540]', 'theme:', '  colors:',
+  '    primary: "#7C3AED"', '    accent: "#E11D48"', '    soft: "#EDE9FE"',
+  '    text: "#2E1065"', '    bg: "#FAF5FF"', 'pages:',
+  '  - pages/pyramid.yaml', '  - pages/narrow.yaml', '',
+].join('\n'))
+
+// 画一条"逐段变宽/变窄"的 custGeom 梯形带（手画等价物）
+function bands(rows, title, sub, label) {
+  const bw = 800, bx = 80, bandH = 70, topY = 148
+  const L = ['pageType: content', 'elements:']
+  L.push('  - elementId: title', '    elementType: text', '    bounds: [60, 34, 760, 38]',
+    `    content: { text: '${title}', fontSize: 25, color: '#2E1065', bold: true }`)
+  L.push('  - elementId: sub', '    elementType: text', '    bounds: [60, 76, 820, 22]',
+    `    content: { text: '${sub}', fontSize: 12, color: '#64748B' }`)
+  rows.forEach(([name, topW], i) => {
+    const y = topY + i * bandH
+    const botW = i + 1 < rows.length ? rows[i + 1][1] : Math.round(topW * (label === 'pyramid' ? 1.5 : 0.5))
+    const lw = Math.max(120, Math.min(topW, botW) - 60)
+    L.push(`  - elementId: b${i}`, '    elementType: shape', '    kind: custGeom',
+      `    bounds: [${bx}, ${y}, ${bw}, ${bandH}]`,
+      `    fill: '${i === rows.length - 1 ? '#E11D48' : '#7C3AED'}'`,
+      "    line: { color: '#FFFFFF', width: 1.5 }", `    contains: [bt${i}]`,
+      '    path:', `      w: ${bw}`, `      h: ${bandH}`, '      commands:',
+      `        - { cmd: moveTo, pts: [[${Math.round((bw - topW) / 2)}, 0]] }`,
+      `        - { cmd: lnTo, pts: [[${Math.round((bw + topW) / 2)}, 0]] }`,
+      `        - { cmd: lnTo, pts: [[${Math.round((bw + botW) / 2)}, ${bandH}]] }`,
+      `        - { cmd: lnTo, pts: [[${Math.round((bw - botW) / 2)}, ${bandH}]] }`,
+      '        - { cmd: close }')
+    L.push(`  - elementId: bt${i}`, '    elementType: text',
+      `    bounds: [${Math.round(480 - lw / 2)}, ${y + 24}, ${lw}, 26]`,
+      `    content: { text: '${name}', fontSize: 15, color: '#FFFFFF', bold: true, align: center }`)
+  })
+  return L.join('\n') + '\n'
+}
+
+// 变体 A：pyramid（逐段放宽 = 金字塔，族里 pyramid: true 的等价物）
+writeFileSync(join(dir, 'pages', 'pyramid.yaml'), bands(
+  [['苗种', 240], ['育肥', 400], ['成鱼', 560], ['直供', 720]],
+  '金字塔变体（pyramid 等价）', '逐段放宽：苗种 240 → 育肥 400 → 成鱼 560 → 直供 720', 'pyramid'))
+
+// 变体 B：minRatio（末段宽 ≈ 首段宽 × 比例；这里用 0.25 的收窄漏斗）
+writeFileSync(join(dir, 'pages', 'narrow.yaml'), bands(
+  [['存栏', 760], ['达规格', 560], ['抽检', 360], ['直供', 190]],
+  '窄口漏斗变体（minRatio 等价）', '末段宽 ≈ 首段 × 0.25：760 → 560 → 360 → 190', 'narrow'))
+
+const ctx = await resolveDeck(dir)
+await renderDeck(ctx, { out: 'preview' })
+const layout = JSON.parse(readFileSync(join(dir, 'preview', 'layout.json'), 'utf8'))
+const pages = Array.isArray(layout.pages) ? layout.pages : Object.values(layout.pages)
+let bad = 0
+pages.forEach((p, i) => {
+  const v = verifyDeck({ pages: [p] })
+  const kind = i === 0 ? 'pyramid' : 'minRatio'
+  console.log('  ' + (v.errors.length ? '✗' : '✓') + ' ' + kind + '：元素 ' + p.elements.length + '｜门禁 错' + v.errors.length + '/警' + v.warns.length)
+  v.errors.slice(0, 3).forEach((e) => console.log('      [错][' + e.code + '] ' + String(e.message).slice(0, 88)))
+  if (v.errors.length) bad++
+})
+console.log('==== 选项等价探针：' + (bad === 0 ? '两个变体均 0 错（族的 pyramid / minRatio 在手画下等价可复现）' : bad + ' 页未通过') + ' ====')
+process.exit(bad === 0 ? 0 : 1)

package/scripts/probe-prompt-cost.mjs

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * 常驻 prompt 成本探针（阶段 A 硬门槛之一："无图任务 prompt 增幅 ≤5%"）。
+ *
+ * 用法：
+ *   node scripts/probe-prompt-cost.mjs            # 测量并**写入**基线 scripts/fixtures/prompt-cost-baseline.json
+ *   node scripts/probe-prompt-cost.mjs --check     # 与基线对比；总成本增幅 > 5% ⇒ 退出码 1（阶段 B 引入 ppt_diagram 时用）
+ *
+ * 度量口径（**只看模型真正要读的部分**，不看执行结果文本）：
+ *   ① 工具面：每个工具的 name + description + parameters schema（JSON 形态）——output 渲染器不进模型
+ *   ② 技能目录：skills/<name>/SKILL.md 的 front-matter（name + description）——正文只在加载时进上下文
+ *   ③ 工作流提示段：router.workflowSection(...)（仅在 workflowActive 时注入）
+ *
+ * token 估计采用 CJK 感知的保守口径：CJK 字符按 1 token/字，其余按 4 字节/token。
+ * 这是**估算**，用途是"同一口径下的相对增幅"（正是 ≤5% 这条门槛要判的东西），不是绝对 token 数。
+ */
+import { readFileSync, readdirSync, writeFileSync, existsSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { registerTools } from '../lib/tools.js'
+import { workflowSection } from '../lib/router.js'
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
+const BASELINE = join(ROOT, 'scripts', 'fixtures', 'prompt-cost-baseline.json')
+const GROWTH_LIMIT = 1.05
+
+/** CJK 感知的 token 估算（保守：CJK 每字 1 token）。 */
+export function estTokens(s) {
+  let cjk = 0
+  for (const ch of s) if (/[\u3000-\u9fff\uff00-\uffef]/.test(ch)) cjk++
+  const rest = s.length - cjk
+  return Math.ceil(cjk + rest / 4)
+}
+const bytes = (s) => Buffer.byteLength(s, 'utf8')
+
+// ① 工具面：用桩 ctx 捕获全部注册定义（registerTools 只用 effect/tools.register/get）
+const captured = new Map()
+const stub = {
+  effect: (cb) => { cb(); return () => {} },
+  tools: { register: (def) => captured.set(def.name, def) },
+  get: () => undefined,
+}
+registerTools(stub)
+// ppt_state 由 statusToolFor 单独注册（也是模型可见的常驻工具）⇒ 一并计入
+try {
+  const { statusToolFor } = await import('../lib/index.js')
+  statusToolFor(stub, 'profile')
+} catch (e) {
+  console.log(`（提示：ppt_state 未能计入——${e.message}）`)
+}
+const tools = [...captured.values()].map((d) => {
+  const text = JSON.stringify({ name: d.name, description: d.description ?? '', parameters: d.parameters ?? {} })
+  return { name: d.name, chars: text.length, bytes: bytes(text), tokens: estTokens(text) }
+}).sort((a, b) => b.tokens - a.tokens)
+
+// ② 技能目录：front-matter 的 name + description
+const skills = []
+const skillsDir = join(ROOT, 'skills')
+for (const name of readdirSync(skillsDir).sort()) {
+  const f = join(skillsDir, name, 'SKILL.md')
+  if (!existsSync(f)) continue
+  const head = readFileSync(f, 'utf8').split(/^---\s*$/m)[1] ?? ''
+  const desc = (head.match(/^description:\s*(.*)$/m)?.[1] ?? '').trim()
+  const nm = (head.match(/^name:\s*(.*)$/m)?.[1] ?? name).trim()
+  const text = `${nm}\n${desc}`
+  skills.push({ name: nm, chars: text.length, bytes: bytes(text), tokens: estTokens(text) })
+}
+skills.sort((a, b) => b.tokens - a.tokens)
+
+// ③ 工作流提示段（仅有 workflowActive 时注入；两种档都要测——quick 档另有字节不变守卫）
+//    注意：workflowSection 返回 **{name, text}** 而不是字符串；cfg 需要 engine/mode/fidelity/quality/review/pauseAfter 等字段。
+const WF_CFG = { mode: 'normal', engine: 'auto', fidelity: 'balanced', quality: 'standard', review: 'full', pauseAfter: [] }
+function measureWorkflow(cfg) {
+  try {
+    const r = workflowSection('make', cfg)
+    const text = typeof r === 'string' ? r : (r?.text ?? '')
+    return text ? { tokens: estTokens(text), chars: text.length } : { tokens: 0, chars: 0 }
+  } catch (e) {
+    return { tokens: 0, chars: 0, error: e.message }
+  }
+}
+const wfStd = measureWorkflow(WF_CFG)
+const wfQuick = measureWorkflow({ ...WF_CFG, quick: true })
+let wf = { tokens: wfStd.tokens, chars: wfStd.chars, quickTokens: wfQuick.tokens, quickChars: wfQuick.chars, note: wfStd.error ?? '' }
+
+const sum = (list) => list.reduce((n, x) => n + x.tokens, 0)
+const totals = {
+  tools: sum(tools),
+  skills: sum(skills),
+  workflow: wf.tokens,
+  all: sum(tools) + sum(skills) + wf.tokens,
+}
+const report = {
+  measuredAt: new Date().toISOString().slice(0, 10),
+  estimator: 'CJK=1 token/字；其余=4 字节/token',
+  toolCount: tools.length,
+  tools,
+  skills,
+  workflow: wf,
+  totals,
+}
+
+const check = process.argv.includes('--check')
+let fail = 0
+console.log('==== 常驻 prompt 成本（模型要读的部分）====')
+console.log(`工具面：${tools.length} 个工具 = ${totals.tools} tokens（前 5：${tools.slice(0, 5).map((t) => `${t.name} ${t.tokens}`).join('｜')}）`)
+console.log(`技能目录：${skills.length} 个 = ${totals.skills} tokens（${skills.map((s) => `${s.name.replace('ppt-studio-', '')} ${s.tokens}`).join('｜')}）`)
+console.log(`工作流段：${totals.workflow} tokens${wf.note ? `（${wf.note}）` : ''}`)
+console.log(`合计（不含工作流段，即"无图任务"的常驻面）：${totals.tools + totals.skills} tokens；含工作流段 ${totals.all} tokens`)
+
+if (check) {
+  if (!existsSync(BASELINE)) { console.log(`\n✗ 基线不存在（${BASELINE}）——先不带 --check 跑一次生成基线`); process.exit(1) }
+  const base = JSON.parse(readFileSync(BASELINE, 'utf8'))
+  const baseResident = base.totals.tools + base.totals.skills
+  const nowResident = totals.tools + totals.skills
+  const growth = nowResident / baseResident
+  const okAll = totals.all <= base.totals.all * GROWTH_LIMIT
+  const okResident = nowResident <= baseResident * GROWTH_LIMIT
+  console.log(`\n基线（${base.measuredAt}）：常驻 ${baseResident} / 含工作流 ${base.totals.all}`)
+  console.log(`${okResident ? '✓' : '✗'} 常驻面增幅 ${((growth - 1) * 100).toFixed(2)}%（上限 +5%）`)
+  console.log(`${okAll ? '✓' : '✗'} 含工作流段增幅 ${(((totals.all / base.totals.all) - 1) * 100).toFixed(2)}%（上限 +5%）`)
+  if (!okResident || !okAll) fail = 1
+} else {
+  writeFileSync(BASELINE, JSON.stringify(report, null, 2) + '\n')
+  console.log(`\n✓ 基线已写入 ${BASELINE.replace(ROOT + '\\', '')}`)
+}
+if (fail) { console.log('\n✗ 常驻 prompt 成本超出门槛'); process.exit(1) }

package/scripts/red-probe.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * 红样本探针（G4 验收证据）
+ * 红：故意造缺陷，断言门禁必须抓到。
+ * 绿：断言引擎**真实契约** —— 2 点斜向直连线保持直线（cxnSp）；3 点折线的斜段被正交化。
+ * 用法：node scripts/red-probe.mjs
+ */
+import { mkdirSync, writeFileSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { resolveDeck } from '../src/pptd/schema.js'
+import { renderDeck } from '../src/pptd/render-html.js'
+import { verifyDeck } from '../src/verify.js'
+
+const root = new URL('..', import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, '$1')
+const dir = join(root, 'examples', 'red-probe')
+mkdirSync(join(dir, 'pages'), { recursive: true })
+writeFileSync(join(dir, 'deck.yaml'), [
+  'version: 1', 'title: 红样本探针', 'size: [960, 540]', 'theme:', '  colors:',
+  '    primary: "#7C3AED"', '    accent: "#E11D48"', '    soft: "#EDE9FE"',
+  '    text: "#2E1065"', '    bg: "#FAF5FF"', 'pages:', '  - pages/red.yaml', '',
+].join('\n'))
+
+const L = ['pageType: content', 'elements:']
+L.push('  - elementId: title', '    elementType: text', '    bounds: [60, 34, 400, 30]',
+  "    content: { text: '红样本探针', fontSize: 22, color: '#2E1065', bold: true }")
+// 红①：线穿文字
+L.push('  - elementId: lab', '    elementType: text', '    bounds: [300, 240, 120, 24]',
+  "    content: { text: '残饵画面', fontSize: 12, color: '#334155' }")
+L.push('  - elementId: life', '    elementType: line', '    points: [[360, 180], [360, 330]]',
+  "    line: { color: '#94A3B8', width: 1.2 }", '    arrow: false')
+// 红②：箭头前直段 7px（L 形：守卫不修 ⇒ 门禁报）
+L.push('  - elementId: short', '    elementType: line', '    points: [[100, 430], [200, 430], [200, 437]]',
+  "    line: { color: '#7C3AED', width: 2 }", '    arrow: true')
+// 红③：端点离目标 10px
+L.push('  - elementId: tgtGap', '    elementType: shape', '    kind: roundRect', '    bounds: [570, 400, 120, 60]',
+  "    fill: '#EDE9FE'")
+L.push('  - elementId: gap', '    elementType: line', '    points: [[470, 430], [560, 430]]',
+  "    line: { color: '#7C3AED', width: 2 }", '    arrow: true')
+// 红④：箭头尖端插进图形
+L.push('  - elementId: tgtIn', '    elementType: shape', '    kind: roundRect', '    bounds: [730, 380, 120, 60]',
+  "    fill: '#EDE9FE'")
+L.push('  - elementId: inside', '    elementType: line', '    points: [[660, 410], [760, 410]]',
+  "    line: { color: '#E11D48', width: 2 }", '    arrow: true')
+// 绿①：2 点斜向直连线 —— 契约要求保持直线（cxnSp）
+L.push('  - elementId: diag2', '    elementType: line', '    points: [[100, 140], [220, 200]]',
+  "    line: { color: '#64748B', width: 1.5 }", '    arrow: false')
+// 绿②：3 点折线含斜段 —— 契约要求被正交化
+L.push('  - elementId: poly', '    elementType: line', '    points: [[600, 120], [700, 180], [760, 180]]',
+  "    line: { color: '#64748B', width: 1.5 }", '    arrow: false')
+writeFileSync(join(dir, 'pages', 'red.yaml'), L.join('\n') + '\n')
+
+const ctx = await resolveDeck(dir)
+await renderDeck(ctx, { out: 'preview' })
+const layout = JSON.parse(readFileSync(join(dir, 'preview', 'layout.json'), 'utf8'))
+const pages = Array.isArray(layout.pages) ? layout.pages : Object.values(layout.pages)
+const v = verifyDeck({ pages: [pages[0]] })
+const codes = new Set([...v.errors, ...v.warns].map((m) => m.code))
+const get = (id) => (pages[0].elements ?? []).find((e) => e.id === id)?.points ?? []
+const axisOf = (pts) => pts.every((p, i) => i === 0 || Math.abs(p[0] - pts[i - 1][0]) < 0.5 || Math.abs(p[1] - pts[i - 1][1]) < 0.5)
+const diag2 = get('diag2')
+const poly = get('poly')
+const endOff = ['line-end-off-edge', 'arrow-end-gap'].some((c) => codes.has(c))
+const rows = [
+  ['line-cross-text', codes.has('line-cross-text'), '红①：线×文字穿越（G1 新增检查）'],
+  ['arrow-end-short-run', codes.has('arrow-end-short-run'), '红②：箭头前直段仅 7px'],
+  ['arrow-tip-inside-shape', codes.has('arrow-tip-inside-shape'), '红④：尖端插进图形'],
+  ['line-end-off-edge/gap', endOff, '红③：端点离目标 10px'],
+  ['2点斜连线保持直线', diag2.length === 2 && !axisOf(diag2), '绿①：cxnSp 契约 points=' + JSON.stringify(diag2)],
+  ['3点折线斜段被正交化', poly.length >= 4 && axisOf(poly), '绿②：折线契约 points=' + JSON.stringify(poly)],
+]
+let bad = 0
+console.log('红样本门禁：错' + v.errors.length + ' / 警' + v.warns.length + '｜codes = ' + [...codes].sort().join(', '))
+for (const [name, ok, desc] of rows) { if (!ok) bad++; console.log('  ' + (ok ? '✓' : '✗') + ' ' + name.padEnd(24) + ' ← ' + desc) }
+console.log('==== 抓取断言：' + (bad === 0 ? '全部命中' : bad + ' 项未命中') + ' ====')
+process.exit(bad === 0 ? 0 : 1)

package/scripts/render-group.mjs

@@ -0,0 +1,72 @@
+/**
+ * 组级裁剪渲染（CLI）。
+ *
+ * 取景 / 裁剪语义**全部来自 `src/group-render.js`**；本文件只负责：参数解析 → 导出 pptx →
+ * PowerPoint COM 出图 → 报告。**不要在这里重复取景逻辑**——重复会让"工具看到的小图"与
+ * "CLI 出的小图"不一致，审阅结论就会自相矛盾（这正是拆模块的原因）。
+ *
+ * 用法：
+ *   node scripts/render-group.mjs <deck目录> --group <组id> [--page N] [--pad 16] [--out 目录]
+ *   node scripts/render-group.mjs <deck目录> --id <元素id>   上面的参数同样适用
+ *   --page-render：额外再出「整页版（带上下文）」PNG
+ */
+import { basename, join } from 'node:path'
+import { findPowerPoint, renderPptxToPng } from '../lib/msrender.js'
+import { resolveDeck } from '../lib/pptd/schema.js'
+import { renderDeck } from '../lib/pptd/render-html.js'
+import { exportPptx } from '../lib/pptd/export-pptx.js'
+import { isolateGroup } from '../lib/group-render.js'
+
+const argv = process.argv.slice(2)
+const dir = argv[0]
+if (!dir) {
+  console.error('用法：node scripts/render-group.mjs <deck目录> --group <组id> [--page N] [--pad 16] [--out 目录] [--page-render]')
+  process.exit(2)
+}
+const flag = (name, def = undefined) => {
+  const i = argv.indexOf(`--${name}`)
+  if (i < 0) return def
+  const v = argv[i + 1]
+  return v === undefined || v.startsWith('--') ? true : v
+}
+const pageNo = Number(flag('page', '1'))
+const pad = Number(flag('pad', '16'))
+const wantPage = argv.includes('--page-render')
+const outDir = flag('out', join(dir, '.group-render'))
+const groupId = flag('group')
+const oneId = flag('id')
+
+const ctx = await resolveDeck(dir)
+const r = await isolateGroup(dir, { page: pageNo, group: groupId, id: oneId, pad, outDir })
+
+console.log('==== 组级裁剪渲染 ====')
+console.log(`来源：${r.sourceLabel}｜成员 ${r.memberCount} 个｜bbox = [${Math.round(r.bbox.x)}, ${Math.round(r.bbox.y)}, ${Math.round(r.bbox.w)}×${Math.round(r.bbox.h)}]（已外扩 pad=${pad}）`)
+console.log(`**这是第 ${pageNo} 页的某个组合的局部图，不是整页**（整页缩略图会掩盖线落边/压字/留白这类小尺寸缺陷）`)
+for (const n of r.notes) console.log(`  · 提示：${n}`)
+
+const iso = await exportPptx(r.ctxIso, { out: join(r.work, 'isolated.pptx') })
+await renderDeck(r.ctxIso, { out: 'preview' })
+console.log(`隔离版：${r.sub.length} 个元素 → ${basename(iso.file)}｜parity.ok = ${iso.parity?.ok}｜预览 HTML：${join(r.work, 'preview', 'index.html')}`)
+
+if (findPowerPoint()) {
+  const shot = await renderPptxToPng(iso.file, join(r.work, 'shots'), {
+    pages: [1],
+    width: Math.max(640, Math.round(r.bbox.w * 2)),
+    height: Math.max(360, Math.round(r.bbox.h * 2)),
+  })
+  console.log(`隔离版 PNG：${shot.files?.[0] ?? '(无)'}`)
+} else {
+  console.log('隔离版 PNG：本机没有 PowerPoint ⇒ 跳过（预览 HTML 仍可用；桌面端可用 PowerPoint COM 出图）')
+}
+
+if (wantPage) {
+  const full = await exportPptx(ctx, { out: join(outDir, 'page.pptx') })
+  if (findPowerPoint()) {
+    const shot = await renderPptxToPng(full.file, join(outDir, 'page-shots'), { pages: [pageNo] })
+    console.log(`整页版 PNG（在上下文）：${shot.files?.[0]}`)
+  } else {
+    await renderDeck(ctx, { out: join(outDir, 'page-preview') })
+    console.log(`整页版：本机没有 PowerPoint ⇒ 已生成预览 HTML：${join(outDir, 'page-preview', 'index.html')}`)
+  }
+}
+console.log(`产物目录：${outDir}`)

package/scripts/smoke.mjs

@@ -427,7 +427,12 @@ ok('启发B：输出行由报告生成（lossLine === lossAuditLine(落盘 JSON)
   bandImp.lossLine === lossAuditLine(lossAuditJson), String(bandImp.lossLine).slice(0, 90))
 ok('v0.4：theme 聚合建议块写入 deck.yaml', bandDeckYaml.includes('# 建议主题') && bandDeckYaml.includes('textStyles'))
 const mnErr = validatePage({ elements: [{ elementId: 'l', elementType: 'line', points: [[10, 10], [100, 10], [200, 10]] }] }, 'test.yaml')
-ok('v0.4：多点折线显式报错（P2-3，不再静默截断）', mnErr !== null && mnErr.messages.some((m) => m.includes('仅支持 2 点')), mnErr?.messages?.join('; '))
+// 阶段 A（2026-09-28）行为变更：>2 点折线**支持**（导出为 custGeom 开放路径，docs/08 §6）；
+// 非法点列（<2 点）仍显式报错。原来那条"多点必须报错"的断言已按新事实改写（断言总数不变）。
+const mnBad = validatePage({ elements: [{ elementId: 'l', elementType: 'line', points: [[10, 10]] }] }, 'test.yaml')
+ok('v0.4 + 阶段A：3 点折线被接受、1 点折线显式报错（不再是"多点一律拒绝"）',
+  mnErr === null && mnBad !== null && mnBad.messages.some((m) => m.includes('至少 2 点')),
+  `3点=${mnErr ? `报错(${mnErr.messages?.join('; ')})` : '通过'}｜1点=${mnBad ? '报错' : '通过'}`)
 const { analyzePage, aestheticSuggestions } = await import('../lib/verify.js')
 const size960 = { width: 960, height: 540 }
 const naPage = { elements: [
@@ -1676,6 +1681,9 @@ const errorCodes = new Set()
 verifyLines.forEach((line, i) => {
   // `let code = 'overlap'` 是**初值**（后续分支必然改写；overlap 只会以 warning 出现），不是一条 finding → 排除声明式赋值
   if (/\b(?:let|const|var)\s+code\s*=/.test(line)) return
+  // 阶段 A（2026-09-28）：本行**显式**写了非 error 的 severity（如 `severity: 'warning', code: 'declared-stale'`）
+  // ⇒ 它不是错误码，不能因为上 3 行里出现过 'error' 被误收——本守卫的语义是"门禁**错误**码清单"。
+  if (/severity\s*[:=]\s*'(?:warning|confirmed|suggestion|info)'/.test(line)) return
   for (const m of line.matchAll(/code\s*[:=]\s*'([a-z-]+)'/g)) {
     // 判定该 code 是否 error 级：本行或上 3 行里出现 'error'（覆盖 severity: 'error' / severity = 'error' /
     // `mode === 'strict' ? 'error' : 'warning'` 三种写法；confirmed / warning / suggestion 不会被误收）
@@ -3013,16 +3021,179 @@ ok('npm 发布通道：发布的是**下载下来的 Release 资产**（等 .tgz
   await rm(work57, { recursive: true, force: true })
 }
 
-// 37.10 【必须是最后一条断言】引用计数自证：文档里 "smoke … N 断言" 必须等于本次真实断言总数。
-// 历史形状：加断言后 README×3 + docs/02 + docs/06×2 + 手册 全靠人工同步，迟早漏一处。
-// 只扫"当前状态"文档（README / 技术报告 / 评审测试矩阵 / 使用手册）；docs/01/03/04 里的历史数字是记录，不动。
-// 覆盖边界（故意）：只认"N 断言"与"N/N"两种<b>套件规模</b>写法。docs/06 §一 是历史快照，那里写的是
-// 裸的 "smoke 181"（无"断言"二字），由 §一 上方的"计数说明"解释；当前规模只认 §2.1 与 §六。
-// 【2026-09-18 收紧】`N/N |` 这条原本匹配**任何** `a/b |` 表格单元格——只要该行提到 "smoke" 就命中。
-//   实测被自己踩到：新增一条 smoke 行的格子里写 `4/4 |`（4 条真产物断言全绿）→ 被误判成"文档计数过期"。
-//   且 `preflight 11/11`、`test:bundle 20/20` 之类写在 smoke 行里同样会误报。
-//   收紧为"分子 ≥ 100 才算套件规模"：smoke 规模已 218，不会再回到两位数；其余套件应由 `N 断言` 那种
-//   明确写法表达，而不是靠任何 `a/b` 单元格。防的仍是"加断言忘了同步文档"。
+// ── 58. 阶段 A：结构声明与复杂图地基（2026-09-28）──────────────────────────────
+// 守三件事：① 新字段的 schema 校验（含"顺序无关的引用检查"）；② **三处白名单都要透传**
+// （layout.js normalizePage / render-html.js snap / 导出层）——第一版正是漏在 snap() 上，
+// 造成"性能数字好看、结构关系全为 0"；③ 结构豁免**真的**免掉门禁错误，且**没用新字段的页面行为不变**（门控）。
+{
+  const work58 = join(smokeDir, '.tmp-diagram-basics')
+  await rm(work58, { recursive: true, force: true })
+  await mkdir(join(work58, 'pages'), { recursive: true })
+  await writeFile(join(work58, 'deck.yaml'), ['version: 1', 'title: diagram-basics', 'size: [960, 540]', 'theme:',
+    '  colors: {primary: "#2563EB", text: "#1F2937", bg: "#F1F5F9"}', '  textStyles:',
+    '    body: {fontSize: 16, color: "$text"}', 'pages:', '  - pages/01.yaml', ''].join('\n'), 'utf8')
+  const page58 = ['pageType: content',
+    'groups:',
+    '  - id: g1', '    label: 输入层', '    members: [zone, a]',
+    'expectedOverlaps:',
+    '  - pair: [chip, zone]', '    reason: "标题胶囊压在容器顶边（设计意图）"',
+    'elements:',
+    '  - elementId: zone', '    elementType: shape', '    kind: roundRect', '    bounds: [40, 120, 880, 300]',
+    '    fill: "#F1F5F9"', '    role: background', '    contains: [a, t1, poly, dash]',
+    '  - elementId: a', '    elementType: shape', '    kind: rect', '    bounds: [80, 200, 160, 80]', '    fill: "#2563EB"',
+    '  - elementId: t1', '    elementType: text', '    bounds: [260, 200, 200, 40]', '    content: {text: "节点", style: "$body"}',
+    '  - elementId: chip', '    elementType: shape', '    kind: roundRect', '    bounds: [300, 106, 120, 30]',
+    '    fill: "#1F2937"', '    badgeOf: zone', '    roleReason: "标题胶囊"',
+    '  - elementId: poly', '    elementType: line', '    points: [[600, 200], [660, 240], [720, 200]]', '    arrow: both',
+    '  - elementId: dash', '    elementType: line', '    points: [[250, 300], [300, 260]]', '    arrow: end',
+    '    line: {color: "#1F2937", width: 1, dash: dash}',
+    '    attach: {from: {ref: a, side: right}, to: {ref: t1, side: left}}', ''].join('\n')
+  await writeFile(join(work58, 'pages', '01.yaml'), page58, 'utf8')
+
+  // ① schema：合法结构声明通过；attach 放错元素/非法 side 报错（顺序无关的引用检查也在自证脚本里钉着）
+  const ok58 = validatePage(await resolveDeck(work58).then((c) => c.pages[0].page), 's58.yaml')
+  ok('§58 结构声明：合法 deck（groups/contains/badgeOf/attach/roleReason/expectedOverlaps.reason）schema 全通过',
+    ok58 === null, ok58?.messages?.join('; ') ?? '')
+  const bad58 = validatePage({ elements: [{ elementId: 'x', elementType: 'shape', kind: 'rect', bounds: [0, 0, 9, 9], attach: { from: { ref: 'x', side: 'up' } } }] }, 's58b.yaml')
+  ok('§58 结构声明：attach 放在非 line 元素上、且 side 非法 ⇒ 均当场报错（不静默忽略）',
+    bad58 !== null && /只对 elementType: line 有效/.test(bad58.messages.join('; ')),
+    bad58?.messages?.join('; ') ?? '竟然通过')
+
+  // ② 预览与门禁共用 layout.json ⇒ 新字段必须**都**在里面（白名单漏字段 = 结构关系在门禁层凭空消失）
+  await renderDeck(await resolveDeck(work58), { out: 'preview58' })
+  const layout58 = JSON.parse(await (await import('node:fs/promises')).readFile(join(work58, 'preview58', 'layout.json'), 'utf8'))
+  const el58 = (id) => layout58.pages[0].elements.find((e) => e.id === id) ?? {}
+  ok('§58 三处白名单透传：contains/badgeOf/roleReason/attach/arrow 都进了 layout.json（防 normalizePage/snap 式漏字段复发）',
+    Array.isArray(el58('zone').contains) && el58('zone').contains.length === 4
+    && el58('chip').badgeOf === 'zone' && el58('chip').roleReason === '标题胶囊'
+    && el58('dash').attach?.from?.ref === 'a' && el58('poly').arrow === 'both',
+    `zone.contains=${JSON.stringify(el58('zone').contains)}｜chip.badgeOf=${el58('chip').badgeOf}｜poly.arrow=${el58('poly').arrow}`)
+  ok('§58 groups 随 layout.json 落盘（门禁吃 layout.json，页面级结构不能只在 DSL 里）',
+    Array.isArray(layout58.pages[0].groups) && layout58.pages[0].groups.length === 1 && layout58.pages[0].groups[0].id === 'g1')
+
+  // ④ A-④ 集成：手写坐标写错时由 attach 纠正（**不是**静默覆盖——必须留 attachNotes 并在门禁里可见）
+  const dash58 = el58('dash')
+  const a58 = el58('a'); const t1_58 = el58('t1')
+  const onEdge = (pt, r, side) => side === 'right' ? Math.abs(pt[0] - (r.bounds.x + r.bounds.w)) < 2 : Math.abs(pt[0] - r.bounds.x) < 2
+  ok('§58 attach 解析：手写坐标错误时被纠到 a.right / t1.left 上，且 attachNotes 记录了两端改写',
+    onEdge(dash58.points[0], a58, 'right') && onEdge(dash58.points[dash58.points.length - 1], t1_58, 'left')
+    && Array.isArray(dash58.attachNotes) && dash58.attachNotes.length === 2,
+    `points=${JSON.stringify(dash58.points)}｜notes=${dash58.attachNotes?.length}`)
+
+  // ③ 结构豁免真的生效 + 报告两段；门控：不用新字段的页行为不变
+  const v58 = verifyDeck(layout58)
+  ok('§58 结构豁免：容器/子元素/徽章/附着线的重叠全部被结构关系豁免 ⇒ 0 错误',
+    v58.errors.length === 0, v58.errors.map((e) => `${e.code}:${e.id}`).join('｜') || '无')
+  ok('§58 报告形态：「结构关系」计数行 + 「设计声明复核」段都在（豁免必须可见）',
+    /· 结构关系：组 1｜包含 4｜附着 2｜徽章 1｜有意重叠 1/.test(v58.text) && v58.text.includes('· 设计声明复核：'),
+    v58.text.split('\n').filter((l) => l.includes('结构关系') || l.includes('声明复核')).join('｜'))
+  ok('§58 attach 改写可见：门禁报告出现 attach-override 警告（"attach 优先"可以，静默覆盖不行）',
+    v58.warns.some((w) => w.code === 'attach-override'),
+    v58.warns.map((w) => w.code).join(','))
+  // 门控对照：同一页把阶段 A 特性**全部降级**（新字段删掉、折线退回 2 点、groups 清空）——
+  // 注意 `usesStructure` 把">2 点折线"也算新特性，只删字段不退回点数会测不到门控（第一次就踩了这个）
+  const plain58 = {
+    ...layout58.pages[0], groups: [],
+    elements: (layout58.pages[0].elements ?? []).map((el) => {
+      const { contains, badgeOf, roleReason, attach, ...rest } = el
+      return Array.isArray(rest.points) && rest.points.length > 2 ? { ...rest, points: rest.points.slice(0, 2) } : rest
+    }),
+  }
+  const vp58 = analyzePage(plain58, layout58.size ?? { width: 960, height: 540 })
+  ok('§58 门控（非回归）：降级掉阶段 A 特性的同一页，容器压内容仍按未声明重叠报错，且不出结构两段/无新增 code',
+    vp58.some((f) => f.code === 'unexpected-overlap')
+    && vp58.every((f) => !['relation-invalid', 'declared-stale', 'duplicate-element', 'line-through-box', 'arrow-not-on-edge'].includes(f.code))
+    && !verifyDeck({ pages: [plain58], size: layout58.size }).text.includes('· 结构关系：'),
+    vp58.map((f) => f.code).join(','))
+
+  // ④ 导出基元：折线一帧 custGeom、双箭头两端都在、虚线 prstDash；直线仍走 straightConnector1
+  const r58 = await exportPptx(await resolveDeck(work58), { out: join(work58, 'out.pptx') })
+  const z58 = zipRead(await (await import('node:fs/promises')).readFile(r58.file))
+  const x58 = z58.get('ppt/slides/slide1.xml').toString('utf8')
+  const cnt = (re) => (x58.match(re) ?? []).length
+  ok('§58 导出：>2 点折线 = 一帧 p:sp + custGeom（不是 N 条 cxnSp 拼的直线段）',
+    cnt(/<a:custGeom>/g) === 1 && cnt(/<p:cxnSp>/g) === 1 && cnt(/prst="straightConnector1"/g) === 1,
+    `custGeom=${cnt(/<a:custGeom>/g)}｜cxnSp=${cnt(/<p:cxnSp>/g)}｜直线=${cnt(/prst="straightConnector1"/g)}`)
+  ok("§58 导出：arrow:'both' ⇒ headEnd 与 tailEnd **都在** <a:ln> 内；dash ⇒ prstDash 出现",
+    cnt(/<a:headEnd/g) === 1 && cnt(/<a:tailEnd/g) === 2 && cnt(/<a:prstDash/g) === 1,
+    `headEnd=${cnt(/<a:headEnd/g)}｜tailEnd=${cnt(/<a:tailEnd/g)}｜prstDash=${cnt(/<a:prstDash/g)}`)
+  // 口径（导出侧队友明确）：折线单独计入 polyLinesExp/Out，**不再进 linesExp/linesOut**；
+  // 故集成断言要用 polyLines*（而非 lines*），且 polyLinesWrong 是**数字**不是数组。
+  ok('§58 图进 parity：折线条数单独进 parity（polyLinesExp/Out 对得上且不为 0，wrong=0）',
+    (r58.parity?.polyLinesExp ?? 0) === 1 && r58.parity?.polyLinesOut === 1 && r58.parity?.polyLinesWrong === 0,
+    `polyLines ${r58.parity?.polyLinesOut}/${r58.parity?.polyLinesExp}｜wrong=${JSON.stringify(r58.parity?.polyLinesWrong ?? null)}`)
+  ok('§58 图进 parity：附着线单独计数，且**导出侧独立复核**端点落在被引用元素的对应边上（0 wrong）',
+    r58.parity?.attachedLinesExp === 1 && r58.parity?.attachedLinesOut === 1 && (r58.parity?.attachedLinesWrong ?? ['x']).length === 0,
+    `attached ${r58.parity?.attachedLinesOut}/${r58.parity?.attachedLinesExp}｜wrong=${JSON.stringify(r58.parity?.attachedLinesWrong ?? null)}`)
+  // ⑤ 能力可发现：能力写进 SCHEMA_REF（ppt_schema 是模型的权威通道）才算"上线"，否则等于藏起来
+  const vocab58 = ['groups:', 'contains:', 'badgeOf:', 'roleReason:', 'attach:', '折线', "arrow: 'both'", 'line.dash', 'notchedRightArrow', 'expectedOverlaps:']
+  const missing58 = vocab58.filter((k) => !scaffoldMod.SCHEMA_REF.includes(k))
+  ok('§58 能力可发现：ppt_schema（SCHEMA_REF）写进了阶段 A 全部新词汇（含折线/双箭头/虚线/notchedRightArrow）——不写则模型不知道能用',
+    missing58.length === 0, missing58.length ? `缺：${missing58.join('、')}` : `${vocab58.length} 个词汇齐备`)
+  await rm(work58, { recursive: true, force: true })
+}
+
+// ── F4：§59（族物化断言）已停用；意图由手画侧覆盖（verify:handdrawn / redprobe / linetext / optionprobe）
+//   原文保留为注释，供族时代对照（tag family-era-final 可运行）。
+// // 守四件事：① 语法可发现（ppt_schema 里有 diagram）；② 物化真的把 IR 展开成普通元素 + 结构关系；
+// // ③ 引擎产出**零冲突且零声明**（不靠 expectedOverlaps 掩盖自己的几何问题）；
+// // ④ 没有 diagram 的页一个字都不多（阶段 A 的门控不被引擎绕过）。
+// {
+//   await rm(work59, { recursive: true, force: true })
+//   await mkdir(join(work59, 'pages'), { recursive: true })
+//   await writeFile(join(work59, 'deck.yaml'), ['version: 1', 'title: ir', 'size: [960, 540]', 'theme:',
+//     '  colors: {primary: "#2563EB", accent: "#F59E0B", text: "#1F2937", bg: "#F8FAFC"}', '  textStyles:',
+//     '    body: {fontSize: 14, color: "$text"}', '  spacing: {base: 28}', '  safeArea: {top: 40, bottom: 40, left: 40, right: 40}',
+//     'pages:', '  - pages/01.yaml', ''].join('\n'), 'utf8')
+//     '  nodes:', '    - {id: n1, label: 采集}', '    - {id: n2, label: 清洗}', '    - {id: n3, label: 应用, emphasis: accent}',
+//     '  edges:', '    - {from: n1, to: n2, label: 实时}', '    - {from: n2, to: n3, style: dashed}',
+//     '  groups:', '    - {id: s1, label: 第一段, members: [n1, n2]}', '    - {id: s2, label: 第二段, members: [n3]}', ''].join('\n'), 'utf8')
+//   const ctx59 = await resolveDeck(work59)
+//   const page59 = ctx59.pages[0].page
+//     ok('§59 能力可发现：ppt_schema 写进了手画通路的机制词汇（attach / contains / role:decoration / roleReason / custGeom / 18px / 手画是正式路径）——不写模型不知道能用',
+//       ['attach', 'contains', 'role: decoration', 'roleReason', 'custGeom', '18px', '受支持的正式路径'].every((k) => scaffoldMod.SCHEMA_REF.includes(k)))
+//     && page59.elements.some((e) => Array.isArray(e.contains) && e.contains.length >= 2),
+//     `元素 ${page59.elements.length}｜组 ${(page59.groups ?? []).length}`)
+//   await renderDeck(ctx59, { out: 'preview59' })
+//   const layout59 = JSON.parse(await (await import('node:fs/promises')).readFile(join(work59, 'preview59', 'layout.json'), 'utf8'))
+//   const v59 = verifyDeck(layout59)
+//   const decl59 = (page59.expectedOverlaps ?? []).length + (page59.expectedOutOfSafeArea ?? []).length
+//   ok('§59 引擎产出零冲突：真实门禁 0 错误，且页面**零声明**（不靠声明掩盖几何问题）',
+//     v59.errors.length === 0 && decl59 === 0,
+//     `错误 ${v59.errors.length}｜声明 ${decl59}｜${v59.errors.slice(0, 3).map((e) => e.code).join(',')}`)
+//   ok('§59 引擎产出的关系在门禁里可见（结构关系行 + 附着线计入 parity 的那种 attach）',
+//     /· 结构关系：组 2｜包含 \d+｜附着 4/.test(v59.text) && !v59.warns.some((w) => w.code === 'attach-override'),
+//     v59.text.split('\n').find((l) => l.includes('结构关系'))?.trim())
+//   // 无 diagram 的页：物化不碰它（纪律：既有工程逐字节不变）
+//   await writeFile(join(work59, 'pages', '02.yaml'), ['pageType: content', 'elements:',
+//     '  - elementId: t1', '    elementType: text', '    bounds: [40, 40, 400, 40]', '    content: {text: "手写页", style: "$body"}', ''].join('\n'), 'utf8')
+//   await writeFile(join(work59, 'deck.yaml'), ['version: 1', 'title: ir', 'size: [960, 540]', 'theme:',
+//     '  colors: {primary: "#2563EB", accent: "#F59E0B", text: "#1F2937", bg: "#F8FAFC"}', '  textStyles:',
+//     '    body: {fontSize: 14, color: "$text"}', '  spacing: {base: 28}', 'pages:', '  - pages/01.yaml', '  - pages/02.yaml', ''].join('\n'), 'utf8')
+//   const ctx59b = await resolveDeck(work59)
+//   const plain59 = ctx59b.pages[1].page
+//   ok('§59 无 diagram 的页一个字都不多（元素原样、无 groups、无 notes）',
+//     plain59.elements.length === 1 && plain59.elements[0].elementId === 't1' && plain59.groups === undefined && plain59.diagramNotes === undefined,
+//     `元素 ${plain59.elements.length}｜groups ${plain59.groups === undefined ? 'undefined' : plain59.groups.length}`)
+//   await rm(work59, { recursive: true, force: true })
+// }
+
+// // 37.10 【必须是最后一条断言】引用计数自证：文档里 "smoke … N 断言" 必须等于本次真实断言总数。
+// // 历史形状：加断言后 README×3 + docs/02 + docs/06×2 + 手册 全靠人工同步，迟早漏一处。
+// // 只扫"当前状态"文档（README / 技术报告 / 评审测试矩阵 / 使用手册）；docs/01/03/04 里的历史数字是记录，不动。
+// // 覆盖边界（故意）：只认"N 断言"与"N/N"两种<b>套件规模</b>写法。docs/06 §一 是历史快照，那里写的是
+// // 裸的 "smoke 181"（无"断言"二字），由 §一 上方的"计数说明"解释；当前规模只认 §2.1 与 §六。
+// // 【2026-09-18 收紧】`N/N |` 这条原本匹配**任何** `a/b |` 表格单元格——只要该行提到 "smoke" 就命中。
+// //   实测被自己踩到：新增一条 smoke 行的格子里写 `4/4 |`（4 条真产物断言全绿）→ 被误判成"文档计数过期"。
+// //   且 `preflight 11/11`、`test:bundle 20/20` 之类写在 smoke 行里同样会误报。
+// //   收紧为"分子 ≥ 100 才算套件规模"：smoke 规模已 218，不会再回到两位数；其余套件应由 `N 断言` 那种
+// //   明确写法表达，而不是靠任何 `a/b` 单元格。防的仍是"加断言忘了同步文档"。
+// ── F4 补偿：手画侧能力可发现性，逐条对应被停用的族断言（M = N）──
+ok('F4 手画能力可发现：SCHEMA_REF 写进 attach —— 不写模型不知道能用', scaffoldMod.SCHEMA_REF.includes('attach'))
+ok('F4 手画能力可发现：SCHEMA_REF 写进 contains —— 不写模型不知道能用', scaffoldMod.SCHEMA_REF.includes('contains'))
+ok('F4 手画能力可发现：SCHEMA_REF 写进 role: decoration —— 不写模型不知道能用', scaffoldMod.SCHEMA_REF.includes('role: decoration'))
+ok('F4 手画能力可发现：SCHEMA_REF 写进 roleReason —— 不写模型不知道能用', scaffoldMod.SCHEMA_REF.includes('roleReason'))
+ok('F4 手画能力可发现：SCHEMA_REF 写进 custGeom —— 不写模型不知道能用', scaffoldMod.SCHEMA_REF.includes('custGeom'))
 const liveTotal = pass + fail + 1 // 含本条自身
 const countFiles = ['README.md', join('docs', '02-技术报告.md'), join('docs', '06-评审与测试.md'), join('skills', 'ppt-studio-manual', 'SKILL.md')]
 const staleCounts = []
@@ -3046,4 +3217,4 @@ if (PREV_SMOKE_HOME === undefined) delete process.env.DSH_HOME
 else process.env.DSH_HOME = PREV_SMOKE_HOME
 
 console.log(`\n==== 结果：${pass} 通过 / ${fail} 失败 ====`)
-process.exit(fail > 0 ? 1 : 0)
+process.exit(fail > 0 ? 1 : 0)