dsh-ppt-studio 1.1.0

package/scripts/audit-template-fidelity.mjs

@@ -0,0 +1,162 @@
+/**
+ * 模板导入保真审计：源 pptx（XML 逐页）vs 导入模板工程（yaml）同口径对比。
+ * 输出每套的逐页差异表 + 汇总保真率与主要失真类别，落盘 docs/fidelity-report.md。
+ *
+ * 【2026-09-18 状态（1.0.4）】本脚本默认源目录 `桌面/ppt模板库` **已不存在**，它审计的那 4 套模板
+ * 也已从随包发行物移除。保留本脚本是因为它是 docs/fidelity-report.md 里那些结论的**复现工具**——
+ * 要再跑，需自备原始 pptx 并把那 4 套收纳回 `templates/<id>/`（来源见 docs/03 的 1.0.4 记录）。
+ */
+import { join, dirname, basename } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { readFile, writeFile } from 'node:fs/promises'
+import { zipRead, decodeXml } from '../lib/zips.js'
+import { parseXml, children, first, allText } from '../lib/xmljs.js'
+import { resolveDeck } from '../lib/pptd/schema.js'
+import { templateWorkspace } from '../lib/templates.js'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+const SRC = process.argv[2] ?? 'C:/Users/11867/Desktop/ppt模板库'
+const SRC_TO_TPL = {
+  '实用毕业设计论文答辩PPT模板.pptx': '实用毕业设计论文答辩ppt模板',
+  '极简实用部门工作总结PPT模板.pptx': '极简实用部门工作总结ppt模板',
+  '深蓝质感论文答辩PPT模板.pptx': '深蓝质感论文答辩ppt模板',
+  '简约商务.pptx': '简约商务',
+}
+
+const report = []
+report.push('# 模板导入保真审计报告（v0.7.1 对照）\n')
+report.push(`> 生成时间：${new Date().toISOString()}｜源：${SRC}｜导入版：templates/<id>/\n`)
+report.push('## 说明\n- **源计数**：原始 pptx XML（pptx 内部结构，权威）逐页统计；**导入计数**：模板工程 yaml。\n- **保真率** = 导入元素数 / 源形状级元素数（sp/pic/cxnSp/grpSp 内子元素合并为"形状级元素"；grpSp 嵌套子元素计入源侧计数）。\n- 文本保真 = 导入文本字符数 / 源文本字符数（tl 文本 run 汇总；不含表格/图表内文本）。\n')
+
+function slideStats(xmlText) {
+  const root0 = parseXml(xmlText)
+  const sld = first(root0, 'sld') ?? root0
+  const F = (n, t) => (n ? first(n, t) : null)
+  const cSld = F(sld, 'cSld')
+  const spTree = cSld ? F(cSld, 'spTree') : null
+  const st = { sp: 0, pic: 0, cxn: 0, grpChildren: 0, custGeom: 0, grad: 0, ph: 0, cropPic: 0, smartArt: 0, table: 0, chart: 0, textChars: 0, bgImage: false, bgSolid: false }
+  const walk = (node, inGroup) => {
+    for (const c of node?.children ?? []) {
+      if (c.tag === 'sp') {
+        st.sp++
+        const spPr = F(c, 'spPr')
+        if (F(spPr, 'custGeom')) st.custGeom++
+        if (F(spPr, 'gradFill')) st.grad++
+        const nv = F(c, 'nvSpPr') ?? c
+        if (F(nv, 'ph')) st.ph++
+        const tx = F(c, 'txBody')
+        if (tx) st.textChars += allText(tx).replace(/\s/g, '').length
+        if (inGroup) st.grpChildren++
+      } else if (c.tag === 'pic') {
+        st.pic++
+        const blipFill = F(c, 'blipFill')
+        if (F(blipFill, 'srcRect')) st.cropPic++
+        if (inGroup) st.grpChildren++
+      } else if (c.tag === 'cxnSp') {
+        st.cxn++
+        st.grpChildren += inGroup ? 1 : 0
+      } else if (c.tag === 'grpSp') {
+        walk(c, true)
+      } else if (c.tag === 'graphicFrame') {
+        const graphic = F(c, 'graphic')
+        const gd = graphic ? F(graphic, 'graphicData') : null
+        const uri = gd?.attrs?.uri ?? ''
+        if (uri.includes('/table')) st.table++
+        else if (uri.includes('diagram')) st.smartArt++
+        else st.chart++
+      }
+    }
+  }
+  walk(spTree, false)
+  const bgPr = F(F(cSld, 'bg'), 'bgPr')
+  if (bgPr) {
+    if (F(bgPr, 'blipFill')) st.bgImage = true
+    if (F(bgPr, 'solidFill')) st.bgSolid = true
+  }
+  return st
+}
+
+async function importedStats(tplId) {
+  const t = await templateWorkspace(tplId)
+  const ctx = await resolveDeck(t.dir)
+  const st = { sp: 0, pic: 0, cxn: 0, grad: 0, textChars: 0 }
+  let pages = 0
+  let bgCount = 0
+  for (const p of ctx.pages) {
+    pages++
+    if (p.page.background) bgCount++
+    for (const e of p.page.elements ?? []) {
+      if (e.elementType === 'shape') st.sp++
+      else if (e.elementType === 'image') st.pic++
+      else if (e.elementType === 'line') st.cxn++
+      else if (e.elementType === 'text') st.textChars += String(e.content?.text ?? '').replace(/\s/g, '').length
+    }
+  }
+  return { pages, bgCount, ...st, media: t.media.length }
+}
+
+let overallRows = []
+for (const [file, tplId] of Object.entries(SRC_TO_TPL)) {
+  const pptx = join(SRC, file)
+  let buf
+  try { buf = await readFile(pptx) } catch { report.push(`\n## ${file}\n（源文件缺失，跳过）\n`); continue }
+  const zip = zipRead(buf)
+  const entries = [...zip.keys()].filter((k) => /^ppt\/slides\/slide\d+\.xml$/.test(k)).sort((a, b) => Number(a.match(/\d+/)[0]) - Number(b.match(/\d+/)[0]))
+  const per = []
+  const sum = { sp: 0, pic: 0, cxn: 0, grpChildren: 0, custGeom: 0, grad: 0, ph: 0, cropPic: 0, smartArt: 0, table: 0, chart: 0, textChars: 0, bgImage: 0, bgSolid: 0 }
+  for (const e of entries) {
+    const st = slideStats(decodeXml(zip.get(e)))
+    for (const k of Object.keys(sum)) sum[k] += st[k]
+    per.push(st)
+  }
+  const imp = await importedStats(tplId)
+  report.push(`\n## ${file} → 模板「${tplId}」（${per.length} 页源 vs ${imp.pages} 页导入）\n`)
+  report.push('| 类别 | 源（XML） | 导入（yaml） | 备注 |')
+  report.push('|---|---|---|---|')
+  const elSrc = sum.sp + sum.pic + sum.cxn + sum.grpChildren
+  const elImp = imp.sp + imp.pic + imp.cxn
+  const rate = elSrc > 0 ? Math.round((elImp / elSrc) * 100) : 0
+  report.push(`| 形状级元素 | ${elSrc} | ${elImp} | **保真率约 ${rate}%**（组合子元素并入源计数） |`)
+  report.push(`| sp（含矩形/自选） | ${sum.sp} | ${imp.sp} | 自选形状（箭头/圆角等 prst）按 rect 近似 |`)
+  report.push(`| pic（图片） | ${sum.pic} | ${imp.pic} | 裁剪图（crop ×${sum.cropPic}）拉伸处理 |`)
+  report.push(`| cxnSp（连接线） | ${sum.cxn} | ${imp.cxn} | v0.7.1 起解析 |`)
+  report.push(`| 组合 grpSp 子元素 | ${sum.grpChildren} | （并入上） | v0.7.1 起展开 |`)
+  report.push(`| 自定义几何（custGeom） | ${sum.custGeom} | 0 | 自选图形按矩形近似 |`)
+  report.push(`| 渐变填充（gradFill） | ${sum.grad} | 0 | 归一为主色（stops 在 import-styles.json） |`)
+  report.push(`| 占位符（placeholder） | ${sum.ph} | 0 | 占位符元素并入形状近似 |`)
+  report.push(`| SmartArt（diagram） | ${sum.smartArt} | 0 | 降级为文本占位 |`)
+  report.push(`| 表格 / 图表 | ${sum.table} / ${sum.chart} | 保留近似 | chart→占位 |`)
+  report.push(`| 页面背景（图片/纯色） | ${sum.bgImage} 图 / ${sum.bgSolid} 色 | ${imp.bgCount} | 背景提取（满页图≥95% 提升） |`)
+  report.push(`| 文本字符数 | ${sum.textChars} | ${imp.textChars} | **文本保真率约 ${sum.textChars ? Math.round((imp.textChars / sum.textChars) * 100) : 0}%** |`)
+  report.push(`| 媒体文件 | — | ${imp.media} | 组合内图片 v0.7.1 起提取 |`)
+  overallRows.push({ file, rate, textRate: sum.textChars ? Math.round((imp.textChars / sum.textChars) * 100) : 0, elSrc, elImp })
+  // 页级：每页源元素 vs 导入元素（只打印头尾 8 行避免报告过长 → 全量写）
+  const implines = []
+  for (let i = 0; i < per.length; i++) {
+    const s = per[i]
+    const srcN = s.sp + s.pic + s.cxn + s.grpChildren
+    implines.push(`| 第${i + 1}页 | ${srcN} | ${s.pic}图/${s.custGeom}自/${s.grad}渐/${s.smartArt}智/${s.ph}占 | ${s.bgImage ? '背景图' : ''}${s.bgSolid ? '背景色' : ''} |`)
+  }
+  report.push('\n### 页级明细（源侧特征）\n')
+  report.push('| 页 | 元素 | 特征 | 背景 |')
+  report.push('|---|---|---|---|')
+  report.push(...implines)
+}
+
+report.push('\n\n## 汇总\n')
+for (const r of overallRows) {
+  report.push(`- **${r.file}**：元素保真率 ${r.rate}%（${r.elImp}/${r.elSrc}）｜文本保真率 ${r.textRate}%`)
+}
+report.push('\n## 已知导致视觉失真的因素（按影响排序）\n')
+report.push('1. **自选图形 prst → 矩形**（箭头/圆角/图标等 100+ 形状按 rect；custGeom 同理）——影响图标/箭头/装饰形状。')
+report.push('2. **渐变填充归一为末 stop 主色**（gradFill → 单色；stops 记录在 import-styles.json）——影响按钮/胶囊/背景弧带。')
+report.push('3. **特殊字体回退**（PPT 内置字体/手写体缺失 → 浏览器渲染 tofu □□□）——文本内容保留，视觉字形不同。')
+report.push('4. **背景层不完整**：仅识别 slide 级 p:bg 与 ≥95% 满页图；蒙层/前景盖图/背景组图按元素近似。')
+report.push('5. **SmartArt → 文本占位**；图表 → 文本占位（数据在 xml 中，可重建）。')
+report.push('6. **文本块宽度 vs 字体度量差** → 断行位置与源不同（制作时可调框宽）。')
+report.push('7. **裁剪图 srcRect 忽略**（按 fit 拉伸）。')
+
+const outPath = join(root, 'docs', 'fidelity-report.md')
+await writeFile(outPath, report.join('\n'))
+console.log(`审计完成 → ${outPath}`)
+for (const r of overallRows) console.log(`${r.file}: 元素 ${r.rate}% / 文本 ${r.textRate}%`)

package/scripts/bench-m2.mjs

@@ -0,0 +1,48 @@
+/** M2 性能基准：100 页 deck 渲染+实测耗时（D5：先量化再决策）→ docs/02 §6 记录 */
+import { writeFile, mkdir, rm } from 'node:fs/promises'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+const { resolveDeck } = await import('../src/pptd/schema.js')
+const { renderDeck } = await import('../src/pptd/render-html.js')
+const { measureLayout } = await import('../src/measurement.js')
+
+const d = join(homedir(), '.dsh', 'ppt-studio', 'bench-100')
+await rm(d, { recursive: true, force: true })
+await mkdir(join(d, 'pages'), { recursive: true })
+const N = 100
+const refs = []
+for (let i = 1; i <= N; i++) {
+  const name = `p${String(i).padStart(3, '0')}.yaml`
+  refs.push(`  - pages/${name}`)
+  await writeFile(join(d, 'pages', name), [
+    'pageType: content',
+    'elements:',
+    `  - elementId: t${i}`, '    elementType: text', '    bounds: [60, 60, 700, 60]',
+    `    content: {text: "第 ${i} 页：用于性能基准的长文本段落，包含多个中文句子与数字 12345、百分比 45.5%、年份 2026 等常见内容形态，验证真实任务的渲染与测量开销。", fontSize: 22, color: "#1E4E8C"}`,
+    `  - elementId: s${i}`, '    elementType: shape', '    kind: roundRect', '    bounds: [60, 160, 300, 120]', '    fill: "#EAF1F8"',
+    '', ''].join('\n'))
+}
+await writeFile(join(d, 'deck.yaml'), `version: 1
+title: bench-100
+size: [960, 540]
+theme: {colors: {primary: "#1E4E8C", accent: "#EAF1F8"}}
+pages:
+${refs.join('\n')}
+`)
+const t0 = Date.now()
+const ctx = await resolveDeck(d)
+const tRender = Date.now()
+const r = await renderDeck(ctx, {})
+const tMeasure0 = Date.now()
+const m = await measureLayout(d)
+const tEnd = Date.now()
+console.log(JSON.stringify({
+  pages: N,
+  renderMs: tMeasure0 - tRender,
+  measureMs: tEnd - tMeasure0,
+  totalMs: tEnd - t0,
+  perPageMs: Math.round((tEnd - t0) / N * 10) / 10,
+  measuredPages: m.pages,
+  notes: m.notes,
+}, null, 2))
+await rm(d, { recursive: true, force: true })

package/scripts/build-templates.mjs

@@ -0,0 +1,63 @@
+/**
+ * 模板库维护脚本：对每套模板的封面页渲染 + 截图 → templates/<id>/preview.png。
+ * 规则：模板封面 = deck.yaml 的第一页引用（templates 的模板 deck 引 _cover 为主页）。
+ */
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { readdir, rm, mkdir, access } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { spawn } from 'node:child_process'
+import { resolveDeck } from '../lib/pptd/schema.js'
+import { renderDeck } from '../lib/pptd/render-html.js'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+const TPL_DIR = join(root, 'templates')
+const tmp = join(root, 'examples', 'tpl-preview-work')
+
+let pass = 0
+let fail = 0
+const ok = (name, cond, extra = '') => {
+  console.log(`${cond ? '✓' : '✗'} ${name}${extra ? ' — ' + extra : ''}`)
+  cond ? pass++ : fail++
+}
+
+const edge = ['C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe',
+  'C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe',
+  'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+  'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe'].find((p) => existsSync(p))
+
+for (const tpl of (await readdir(TPL_DIR, { withFileTypes: true })).filter((d) => d.isDirectory()).map((d) => d.name)) {
+  const ws = join(tmp, tpl)
+  await rm(ws, { recursive: true, force: true })
+  await mkdir(join(ws, 'pages'), { recursive: true })
+  const { copyFile } = await import('node:fs/promises')
+  await copyFile(join(TPL_DIR, tpl, 'deck.yaml'), join(ws, 'deck.yaml'))
+  try {
+    // 临时引用全部母版页（模板 deck.yaml 只引用 1-2 页）
+    const { templateWorkspace } = await import('../lib/templates.js')
+    const tT = await templateWorkspace(tpl)
+    const refs = tT.meta.pages ?? []
+    const deckTxt = tT.deck.replace(/  - pages\/[^\n]+(?:\n  - pages\/[^\n]+)*/, refs.map((r) => `  - ${r}`).join('\n'))
+    await (await import('node:fs/promises')).writeFile(join(ws, 'deck.yaml'), deckTxt)
+    for (const p of tT.pages) await copyFile(join(TPL_DIR, tpl, p.ref), join(ws, p.ref))
+    const ctx = await resolveDeck(ws)
+    const r = await renderDeck(ctx, {})
+    // 缩略图 = 第一页（封面）
+    const firstHtml = r.htmlFiles[0]
+    const outPng = join(TPL_DIR, tpl, 'preview.png')
+    if (!edge) { ok(`模板 ${tpl}：无浏览器，跳过截图`, true, '仅渲染检查'); continue }
+    const url = 'file:///' + join(ws, 'preview', firstHtml).replace(/\\/g, '/')
+    await new Promise((resolve, reject) => {
+      const child = spawn(edge, ['--headless=new', '--disable-gpu', '--no-first-run', '--hide-scrollbars', `--window-size=${ctx.size.width},${ctx.size.height}`, `--screenshot=${outPng}`, url], { stdio: 'ignore', windowsHide: true })
+      child.on('exit', (code) => code === 0 ? resolve() : reject(new Error(`Edge 退出码 ${code}`)))
+      child.on('error', reject)
+    })
+    ok(`模板 ${tpl}：渲染 + 预览图生成`, existsSync(outPng))
+  } catch (e) {
+    ok(`模板 ${tpl}：渲染/截图`, false, e?.message)
+  }
+}
+
+await rm(tmp, { recursive: true, force: true })
+console.log(`\n==== 模板构建：${pass} 通过 / ${fail} 失败 ====`)
+process.exit(fail > 0 ? 1 : 0)

package/scripts/build.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * Build: copy src/ → lib/（免编译形态：源码即产物，纯 ESM JS）。
+ * 依赖（yaml）从 node_modules 解析，构建时无需 tsc / DSH_CHECKOUT。
+ */
+import { cpSync, mkdirSync, rmSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+rmSync(join(root, 'lib'), { recursive: true, force: true })
+mkdirSync(join(root, 'lib'), { recursive: true })
+cpSync(join(root, 'src'), join(root, 'lib'), { recursive: true })
+console.log('build: src → lib copied')

package/scripts/build.sh

@@ -0,0 +1,7 @@
+#!/bin/bash
+# PPT 工作室构建：免 tsc —— src → lib 复制（见 build.mjs）。
+set -euo pipefail
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT"
+node scripts/build.mjs
+echo "=== Build complete ==="

package/scripts/check-lib-freshness.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * check-lib-freshness —— 守卫「提交的 lib/ 与 src/ 一致」。
+ *
+ * 为什么要这条守卫（2026-09-16）：
+ *   `lib/` 从这一版起**提交进 git**，因为 `dsh plugin --profile web add <本仓库 git URL>`
+ *   只能拿到 git 里已提交的内容，而 package.json 的 exports 指向 ./lib/index.js。
+ *   lib/ 不提交时，git 安装出来的包缺入口文件、插件挂不上（实测：装到的包没有 lib/）。
+ *   代价是"改了 src 忘了 build + commit lib"会静默发出旧代码——本脚本把这条钉死。
+ *
+ * 用法：node scripts/check-lib-freshness.mjs   （smoke 内也有一条同义断言）
+ * 退出码：0 = 逐字节一致；1 = 有缺、有多、或内容不一致（打印前若干条差异）。
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { dirname, join, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+
+/** 递归列出目录下所有文件的相对路径（POSIX 分隔符，便于比较）。 */
+function walk(dir) {
+  const out = []
+  const stack = [dir]
+  while (stack.length) {
+    const cur = stack.pop()
+    for (const entry of readdirSync(cur, { withFileTypes: true })) {
+      const full = join(cur, entry.name)
+      if (entry.isDirectory()) stack.push(full)
+      else if (entry.isFile()) out.push(relative(dir, full).split('\\').join('/'))
+    }
+  }
+  return out.sort()
+}
+
+const libDir = join(root, 'lib')
+const srcDir = join(root, 'src')
+
+let libFiles
+let srcFiles
+try {
+  libFiles = walk(libDir)
+} catch {
+  console.error('check-lib-freshness: lib/ 不存在——先跑 `node scripts/build.mjs`（lib/ 必须提交，见 .gitignore 注释）')
+  process.exit(1)
+}
+try {
+  srcFiles = walk(srcDir)
+} catch {
+  console.error('check-lib-freshness: src/ 不存在')
+  process.exit(1)
+}
+
+const libSet = new Set(libFiles)
+const srcSet = new Set(srcFiles)
+const missing = srcFiles.filter((f) => !libSet.has(f)) // src 有、lib 没有（漏 build）
+const extra = libFiles.filter((f) => !srcSet.has(f))   // lib 有、src 没有（残留/陈旧）
+const changed = srcFiles.filter((f) => libSet.has(f) && !readFileSync(join(srcDir, f)).equals(readFileSync(join(libDir, f))))
+
+const detail = []
+if (missing.length) detail.push(`lib 缺 ${missing.length} 个：${missing.slice(0, 5).join('、')}`)
+if (extra.length) detail.push(`lib 多 ${extra.length} 个：${extra.slice(0, 5).join('、')}`)
+if (changed.length) detail.push(`内容不一致 ${changed.length} 个：${changed.slice(0, 5).join('、')}`)
+
+if (detail.length) {
+  console.error(`check-lib-freshness: ✗ 提交的 lib/ 与 src/ 不一致——请跑 \`node scripts/build.mjs\` 并提交 lib/\n  ${detail.join('\n  ')}`)
+  process.exit(1)
+}
+
+const bytes = libFiles.reduce((sum, f) => sum + statSync(join(libDir, f)).size, 0)
+console.log(`check-lib-freshness: ✓ lib/ 与 src/ 逐字节一致（${libFiles.length} 个文件 / ${(bytes / 1024).toFixed(0)}KB）`)

package/scripts/check-preset.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+/**
+ * check-preset.mjs —— 预设自检（DSH 升级后必跑）
+ *
+ * 背景（2026-09-12 真实故障）：本预设是**随包 standard 预设的全量副本 + 本插件的人格**。
+ * DSH 0.1.5-rc.2 把 `@deepseek-ai/dsh-persona` 的配置从单一 `text` 改成 `prefix`(required)+`suffix`，
+ * 随包 standard 跟着改了，我们的副本没跟着改 → 一切到「PPT 工作室」就报
+ *   failed to apply loader entry persona: invalid config: - $.prefix missing required value
+ * 而单测/契约核对都发现不了——因为坏的是**预设行配置**，不是插件代码。
+ *
+ * 本脚本逐行比对"我们的预设"与"随包 standard 预设"：
+ *   - 两边都有、但 config 不一致 → FAIL（就是本轮这类漂移）
+ *   - 只存在于随包 standard 的行 → WARN（我们可能漏了新版新增行）
+ *   - 只存在于我们的行 → INFO（预期：人格那一行是有意差异）
+ *
+ * ── 2026-09-24 适配 DSH 0.1.7-rc.1：**参照物的位置和格式都变了** ────────────────────
+ *   0.1.6-：`@deepseek-ai/dsh-agent-presets/presets/standard/agent.cordis.yml`
+ *           —— 一份 Loader 方言的**条目数组**（`dsh-agent-presets` 目录发现时代的随包预设）。
+ *   0.1.7+：`@deepseek-ai/dsh-web-app/presets/standard.patch.yml`
+ *           —— 一份 **patch 列表**，里面 `- insert:` 一行 `@deepseek-ai/dsh-agent-preset`，
+ *              预设的行藏在 `config.plugins` 里（`dsh-agent-presets` 复数包已被
+ *              `dsh-agent-preset` + `dsh-agent-preset-registry` 取代，旧路径不存在了）。
+ *   两种都认（老宿主上跑也不瞎），但**认到哪种会在输出里写明**。
+ *
+ * 找不到参照物时**不再静默跳过**：打印醒目 ⚠ 并给出"这条门禁本轮没生效"的结论；
+ * 加 `--require` 时直接 FAIL（发布/干净安装门禁用它——静默跳过正是 2026-09-24 那次
+ * "npm test 250/0 假绿"的成因：整套 DSH 相关检查都在跳过）。
+ *
+ * `--ref <文件>` 可**钉住参照物**（自动识别新旧格式）：本机装了 DSH 时无法制造"找不到参照"的
+ * 场景，测试要靠它；CI 也可用它固定一份参照做回归。
+ *
+ * 用法：node scripts/check-preset.mjs [--preset <文件>] [--ref <文件>] [--verbose] [--require]
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join, dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { execSync } from 'node:child_process'
+import YAML from 'yaml'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+const args = process.argv.slice(2)
+const opt = (k, d) => {
+  const i = args.indexOf(k)
+  return i >= 0 && args[i + 1] ? args[i + 1] : d
+}
+const oursPath = opt('--preset', join(root, 'agent-presets', 'ppt', 'agent.cordis.yml'))
+const verbose = args.includes('--verbose')
+const requireRef = args.includes('--require')
+/** `--ref <文件>`：钉住参照物（自动识别新旧格式）。本机装了 DSH 时无法制造"找不到参照"的场景，测试靠它。 */
+const refPin = opt('--ref', null) === null ? null : resolve(opt('--ref'))
+
+/** 参照物的相对路径（相对 DSH 安装根）：新格式与旧格式各一条。 */
+const REF_MODERN = join('node_modules', '@deepseek-ai', 'dsh-web-app', 'presets', 'standard.patch.yml')
+const REF_LEGACY = join('node_modules', '@deepseek-ai', 'dsh-agent-presets', 'presets', 'standard', 'agent.cordis.yml')
+
+/** DSH 安装根候选：DSH_CHECKOUT → npm 全局 → DSH_HOME/profiles/<profile>/。 */
+function installRoots() {
+  const roots = []
+  if (process.env.DSH_CHECKOUT) roots.push(process.env.DSH_CHECKOUT)
+  try {
+    const globalRoot = execSync('npm root -g', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim()
+    if (globalRoot) roots.push(join(globalRoot, '@deepseek-ai', 'dsh'), globalRoot)
+  } catch { /* npm 不可用则跳过 */ }
+  const dshHome = process.env.DSH_HOME || join(process.env.USERPROFILE || process.env.HOME || '', '.dsh')
+  for (const profile of ['web', 'headless', 'tui']) roots.push(join(dshHome, 'profiles', profile))
+  return roots
+}
+
+/** 定位随包 standard 预设：返回 {path, kind:'modern'|'legacy'} 或 null。 */
+function findShippedStandard() {
+  const roots = installRoots()
+  for (const [rel, kind] of [[REF_MODERN, 'modern'], [REF_LEGACY, 'legacy']]) {
+    for (const base of roots) {
+      const p = join(base, rel)
+      if (existsSync(p)) return { path: p, kind }
+    }
+  }
+  return null
+}
+
+/** 按文档形状自动识别格式：条目数组 ⇒ legacy；patch 列表（含 insert）⇒ modern。 */
+function detectKind(file) {
+  const doc = YAML.parse(readFileSync(file, 'utf8'))
+  if (Array.isArray(doc) && doc.every((r) => r && typeof r === 'object' && typeof r.id === 'string')) return 'legacy'
+  return 'modern'
+}
+
+/** 取 Loader **方言**的条目数组：两种参照格式都归一到这里（`!!js` 只当数据，不比对求值）。 */
+const rowsOf = (file, kind) => {
+  const doc = YAML.parse(readFileSync(file, 'utf8'))
+  if (kind === 'legacy') {
+    if (!Array.isArray(doc)) throw new Error(`${file} 不是 loader 方言的条目数组`)
+    return doc.filter((r) => r && typeof r === 'object' && typeof r.id === 'string')
+  }
+  // modern：patch 列表 → insert 项 → 声明行 → config.plugins
+  const list = Array.isArray(doc) ? doc : [doc]
+  for (const patch of list) {
+    const inserts = Array.isArray(patch?.insert) ? patch.insert : []
+    for (const row of inserts) {
+      const rows = row?.config?.plugins
+      if (Array.isArray(rows)) return rows.filter((r) => r && typeof r === 'object' && typeof r.id === 'string')
+    }
+  }
+  throw new Error(`${file} 里没有找到 \`- insert:\` 的 preset 声明（config.plugins）——上游格式又变了？`)
+}
+const norm = (v) => JSON.stringify(v ?? null)
+
+const ref = refPin !== null
+  ? (existsSync(refPin) ? { path: refPin, kind: detectKind(refPin) } : null)
+  : findShippedStandard()
+if (ref === null && !existsSync(oursPath)) {
+  console.error(`✗ 找不到本预设：${oursPath}`)
+  process.exit(1)
+}
+if (ref === null) {
+  console.log('⚠ 未找到随包 standard 预设 —— **预设漂移门禁本轮没有生效**')
+  if (refPin !== null) console.log(`  你钉的参照物不存在：${refPin}`)
+  else {
+    console.log('  查过这些位置（相对 DSH 安装根）：')
+    for (const base of installRoots()) {
+      console.log(`    · ${join(base, REF_MODERN)}`)
+      console.log(`    · ${join(base, REF_LEGACY)}`)
+    }
+    console.log('  修法：装好 DSH 再跑，或显式给 DSH_CHECKOUT=<DSH 安装根> / --ref <参照文件>。')
+  }
+  process.exit(requireRef ? 1 : 0)
+}
+
+const std = new Map(rowsOf(ref.path, ref.kind).map((r) => [r.id, r]))
+const ours = new Map(rowsOf(oursPath, 'legacy').map((r) => [r.id, r]))
+
+/**
+ * **声明过的有意差异**：本预设故意与随包 standard 不同的行（其余仍必须逐行一致——那才是防无意漂移）。
+ *
+ * 为什么需要这个白名单（2026-09-18 用户提问："我们的预设和标准模式有啥区别？"）：
+ * 本预设原来是 standard 的**逐行副本**，连 persona 都是通用编码人格
+ * ⇒ 它在界面上只是"改了名字的 standard"，没有任何身份。而"人格"正是预设**唯一**还能可靠交付的东西
+ * （工具/技能按预设隔离在这版 DSH 上做不到：切换预设时 agent 已存在 ⇒ `agent/created` 钩子不触发；
+ * 技能注册表在父层读 ⇒ 子层注册看不见。见 docs/03 最新条目）。
+ * 所以：只允许这一行有意不同，且必须在这里写明理由——新增第二处差异会被门禁拦下。
+ */
+const INTENTIONAL = new Map([
+  ['persona', '「PPT 工作室」的人格：把开工状态定成"演示文稿工程"（先定纲再排版、每页一个论点、数字要口径、导出前过门禁）——预设唯一的身份差异'],
+])
+
+console.log(`本预设：${oursPath}`)
+console.log(`参照：  ${ref.path}`)
+console.log(`格式：  ${ref.kind === 'modern' ? '0.1.7+（dsh-web-app patch 的 config.plugins）' : '0.1.6-（dsh-agent-presets 条目数组）'}\n`)
+
+let fail = 0
+let warn = 0
+let intentional = 0
+for (const [id, r] of ours) {
+  const s = std.get(id)
+  if (s === undefined) {
+    console.log(`  · [本预设新增] ${id}（${r.name ?? '—'}）`)
+    continue
+  }
+  if (norm(r.config) !== norm(s.config)) {
+    if (INTENTIONAL.has(id)) {
+      intentional++
+      console.log(`  ◆ [有意差异] ${id}（${r.name ?? '—'}）— ${INTENTIONAL.get(id)}`)
+      if (verbose) {
+        console.log(`      随包 standard: ${norm(s.config)}`)
+        console.log(`      本预设:        ${norm(r.config)}`)
+      }
+      continue
+    }
+    fail++
+    console.log(`  ✗ [配置漂移] ${id}（${r.name ?? '—'}）`)
+    console.log(`      随包 standard: ${norm(s.config)}`)
+    console.log(`      本预设:        ${norm(r.config)}`)
+  } else if (verbose) {
+    console.log(`  ✓ ${id}`)
+  }
+}
+for (const [id, s] of std) {
+  if (!ours.has(id)) {
+    warn++
+    console.log(`  ⚠ [随包含有、本预设缺少] ${id}（${s.name ?? '—'}）——新版新增行？确认是否要补`)
+  }
+}
+
+console.log(`\n==== 预设自检：漂移 ${fail} / 缺行 ${warn} / 有意差异 ${intentional}（参照格式 ${ref.kind}） ====`)
+if (fail > 0) {
+  console.log('修复方式：把漂移行的 config 改成随包 standard 的形状（预设是它的全量副本），再 npm pack 发版；')
+  console.log('若这是**有意**差异，请加进本脚本顶部的 INTENTIONAL 白名单并写明理由（否则它会在下次升级时被当成漂移）。')
+}
+process.exit(fail > 0 ? 1 : 0)

package/scripts/check-tracked-lf.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * 发行字节守卫：所有**跟踪的文本文件必须是 LF**。
+ *
+ * 为什么需要这条（2026-09-18，创意工坊 PR 审核把问题翻出来的那一类）：
+ * 本插件有两条"一条命令安装"的路径，用户拿到的东西必须是**同一份字节**：
+ *   ① 创意工坊卡片那条 `dsh plugin add <仓库 URL>` → pnpm 走 **git 检出**已提交内容；
+ *   ② GitHub Release 的 `.tgz` 资产              → `npm pack` 打包**工作区**内容。
+ * ②永远是 LF（脚本写出来的），而①在 Windows 上会被 `core.autocrlf=true`
+ * （**Git for Windows 的系统级默认值**，用户不需要配置任何东西）转成 CRLF。
+ * CRLF 会让 src/templates.js 里按 `\n` 做的行锚定文本手术**静默失效**——
+ * 物化出来的模板工作区 deck.yaml 引用一个故意没被复制的母版页，resolveDeck 抛
+ * `page file missing: pages/_cover.yaml`，干净克隆里 `npm test` 直接崩。
+ *
+ * 三道防线各管一段，缺一不可：
+ *   · `.gitattributes`（`* text=auto eol=lf`）——把检出字节钉成 LF（正常情况由它解决）；
+ *   · 本脚本——`eol=lf` 被误覆盖（例如有人给某类文件写了 `-text`、或把文本文件当 binary 声明）时当场红；
+ *   · src/templates.js 的 `normalizeText()`——用户**手改过**的 CRLF/BOM 文件也不失效（这道防线管的是用户内容，
+ *     不是发行物，所以不能拿它替代前两道）。
+ *
+ * 判定看**内容里的 `\r\n`**，不看 git 属性：查的是"安装路径真正拿到的字节"。
+ * 二进制按扩展名 + NUL 字节跳过（.pptx/.png/.woff…）。
+ *
+ * 用法：node scripts/check-tracked-lf.mjs      # 有问题 exit 1
+ *       node scripts/check-tracked-lf.mjs --fix # 就地改写成 LF（作者/贡献者在 Windows 上被编辑器改坏时用）
+ */
+import { execFileSync } from 'node:child_process'
+import { readFileSync, writeFileSync } from 'node:fs'
+import { extname, join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+const FIX = process.argv.includes('--fix')
+
+/** 二进制扩展名（不参与换行检查）。 */
+const BINARY = new Set([
+  '.pptx', '.zip', '.tgz', '.gz', '.png', '.jpg', '.jpeg', '.gif', '.webp', '.ico',
+  '.woff', '.woff2', '.ttf', '.otf', '.pdf', '.xlsx', '.docx', '.mp4', '.webp',
+])
+
+let files
+try {
+  files = execFileSync('git', ['ls-files', '-z'], { cwd: root, encoding: 'utf8' })
+    .split('\0')
+    .filter(Boolean)
+} catch (e) {
+  console.log(`⚠ 跳过：拿不到 git 跟踪清单（${String(e?.message ?? e).split('\n')[0].slice(0, 100)}）`)
+  process.exit(0)
+}
+
+const offenders = []
+let checked = 0
+for (const rel of files) {
+  if (BINARY.has(extname(rel).toLowerCase())) continue
+  let buf
+  try {
+    buf = readFileSync(join(root, rel))
+  } catch {
+    continue // 工作区缺失（稀疏检出等）：不是本检查的职责
+  }
+  if (buf.includes(0)) continue // NUL ⇒ 二进制
+  checked++
+  // 只看 CRLF：单独出现的 \r（老 Mac 风格）在本仓库不存在，不必处理
+  if (buf.includes('\r\n')) offenders.push(rel)
+}
+
+if (offenders.length) {
+  if (FIX) {
+    for (const rel of offenders) {
+      const p = join(root, rel)
+      writeFileSync(p, readFileSync(p, 'utf8').replace(/\r\n/g, '\n'))
+    }
+    console.log(`✓ 已把 ${offenders.length} 个文件改写成 LF（工作区字节现在与提交内容一致）`)
+    process.exit(0)
+  }
+  console.error(`✗ 有 ${offenders.length} 个跟踪的文本文件是 CRLF（应为 LF）：`)
+  for (const f of offenders.slice(0, 30)) console.error(`    ${f}`)
+  if (offenders.length > 30) console.error(`    …还有 ${offenders.length - 30} 个`)
+  console.error('  为什么必须修：CRLF 检出会让行锚定文本手术静默失效 ⇒ git 安装（创意工坊那条命令）')
+  console.error('  与 tgz 安装不是同一份字节。修法：node scripts/check-tracked-lf.mjs --fix')
+  console.error('  （脏的只是工作区字节——提交内容一直要求 LF；改完 git status 应仍为干净。）')
+  process.exit(1)
+}
+console.log(`✓ 发行字节：${checked} 个跟踪的文本文件全部是 LF（git 安装 == tgz 安装的前提）`)

package/scripts/dbg-import.mjs

@@ -0,0 +1,13 @@
+import { zipRead } from '../lib/zips.js'
+import { parseXml } from '../lib/xmljs.js'
+import { readFile } from 'node:fs/promises'
+
+const buf = await readFile('examples/smoke/out-smoke.pptx')
+const files = zipRead(buf)
+const xml = files.get('ppt/presentation.xml').toString('utf8')
+console.log('xml head:', xml.slice(0, 200))
+console.log('xml len:', xml.length)
+const pres = parseXml(xml)
+const p = pres.children[0]
+console.log('root child:', p.tag, 'children:', p.children.length, 'text len:', p.text.length)
+if (p.children[0]) console.log('first child:', p.children[0].tag, JSON.stringify(p.children[0].attrs).slice(0, 120))