dsh-ppt-studio 1.1.0

package/lib/xmljs.js

@@ -0,0 +1,112 @@
+/**
+ * 极简 XML 解析（pptx 读取用）：去命名空间的标签树。
+ * 仅支持我们 OOXML 子集所需：元素/属性/文本/子节点，忽略注释/CDATA 内容按文本。
+ */
+
+export function parseXml(xml) {
+  let i = 0
+  const root = { tag: '#root', attrs: {}, children: [], text: '' }
+  const stack = [root]
+  while (i < xml.length) {
+    const lt = xml.indexOf('<', i)
+    if (lt < 0) break
+    if (xml.startsWith('<?', lt) || xml.startsWith('<!--', lt) || xml.startsWith('<!', lt)) {
+      const end = xml.indexOf('>', lt)
+      i = end < 0 ? xml.length : end + 1
+      continue
+    }
+    // text
+    if (lt > i) appendText(stack[stack.length - 1], xml.slice(i, lt))
+    if (xml.startsWith('</', lt)) {
+      const end = xml.indexOf('>', lt)
+      stack.pop()
+      i = end < 0 ? xml.length : end + 1
+      continue
+    }
+    const close = xml.indexOf('>', lt)
+    const tagText = xml.slice(lt + 1, close).trim()
+    const selfClose = tagText.endsWith('/')
+    const body = selfClose ? tagText.slice(0, -1) : tagText
+    const spAt = body.search(/\s/)
+    const name = spAt < 0 ? body : body.slice(0, spAt)
+    // attrs：支持带空格/引号的值（如 typeface="Microsoft YaHei"）——按 = 匹配，不按空格拆
+    const attrs = {}
+    const attrRe = /([^\s=]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s]+))/g
+    let mm
+    let guard2 = 0
+    while ((mm = attrRe.exec(body)) !== null && guard2++ < 200) {
+      attrs[mm[1]] = mm[2] ?? mm[3] ?? mm[4]
+    }
+    const node = { tag: local(name), attrs, children: [], text: '' }
+    stack[stack.length - 1].children.push(node)
+    if (!selfClose) stack.push(node)
+    i = close + 1
+  }
+  return root
+}
+
+// 实体解码（2026-09-14 修）：此前只做转义（导出侧）、没有解码（导入侧），
+// 于是导入含 & < > 的文本会拿到字面 "&amp;"/"&lt;"（"R&D" → "R&amp;D"）。
+// 只在**文本节点**解码：属性值保持原样，避免 splice/surgical 的结构性属性往返被改写。
+const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" }
+export function decodeEntities(s) {
+  return String(s).replace(/&(#[0-9]+|#x[0-9a-fA-F]+|[a-zA-Z]+);/g, (m, body) => {
+    if (body[0] === '#') {
+      const hex = body[1] === 'x' || body[1] === 'X'
+      const code = hex ? parseInt(body.slice(2), 16) : parseInt(body.slice(1), 10)
+      if (!Number.isFinite(code) || code <= 0 || code > 0x10ffff || (code >= 0xd800 && code <= 0xdfff)) return m
+      return String.fromCodePoint(code)
+    }
+    return ENTITIES[body] ?? m
+  })
+}
+
+function appendText(node, s) {
+  if (s) node.text += decodeEntities(s)
+}
+
+function unquote(v) {
+  const s = v.trim()
+  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) return s.slice(1, -1)
+  return s
+}
+
+function local(name) {
+  const idx = name.indexOf(':')
+  return idx >= 0 ? name.slice(idx + 1) : name
+}
+
+export function children(node, tag) {
+  return tag ? node.children.filter((c) => c.tag === tag) : node.children
+}
+
+export function first(node, tag) {
+  return node.children.find((c) => c.tag === tag)
+}
+
+export function textOf(node) {
+  let out = node.text ?? ''
+  for (const c of node.children) {
+    if (c.tag === 't') out += c.text ?? ''
+  }
+  return out
+}
+
+export function allText(node) {
+  let out = ''
+  const walk = (n) => {
+    if (n.tag === 't') out += n.text ?? ''
+    for (const c of n.children) walk(c)
+  }
+  walk(node)
+  return out
+}
+
+export function firstByPath(node, path) {
+  let cur = node
+  for (const tag of path.split('/')) {
+    cur = first(cur, tag)
+    if (!cur) return undefined
+  }
+  return cur
+}

package/lib/zips.js

@@ -0,0 +1,117 @@
+/**
+ * 极简 ZIP（OOXML）读写：store/deflate 双向，基于 Node 内置 zlib。
+ * 写入用 deflate（PowerPoint 可读）；读取同时支持 store 与 deflate。
+ */
+
+import zlib from 'node:zlib'
+
+// ── CRC32 ────────────────────────────────────────────────────────────────
+const CRC_TABLE = (() => {
+  const t = new Uint32Array(256)
+  for (let n = 0; n < 256; n++) {
+    let c = n
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1
+    t[n] = c >>> 0
+  }
+  return t
+})()
+export function crc32(buf) {
+  let c = 0xffffffff
+  for (let i = 0; i < buf.length; i++) c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8)
+  return (c ^ 0xffffffff) >>> 0
+}
+
+function u16(v) { return Buffer.from([v & 0xff, (v >>> 8) & 0xff]) }
+function u32(v) { return Buffer.from([v & 0xff, (v >>> 8) & 0xff, (v >>> 16) & 0xff, (v >>> 24) & 0xff]) }
+
+/**
+ * 写入 ZIP：entries = { name: Buffer|string }
+ */
+export function zipWrite(entries) {
+  const locals = []
+  const centrals = []
+  let offset = 0
+  for (const [name, content] of Object.entries(entries)) {
+    const data = Buffer.isBuffer(content) ? content : Buffer.from(String(content), 'utf8')
+    const nameBuf = Buffer.from(name, 'utf8')
+    const comp = zlib.deflateRawSync(data)
+    const crc = crc32(data)
+    const local = Buffer.concat([
+      u32(0x04034b50), u16(20), u16(0x0800), u16(8), u16(0), u16(0),
+      u32(crc), u32(comp.length), u32(data.length), u16(nameBuf.length), u16(0),
+      nameBuf, comp,
+    ])
+    locals.push(local)
+    centrals.push(Buffer.concat([
+      u32(0x02014b50), u16(20), u16(20), u16(0x0800), u16(8), u16(0), u16(0),
+      u32(crc), u32(comp.length), u32(data.length), u16(nameBuf.length), u16(0), u16(0), u16(0), u16(0),
+      u32(0), u32(offset), nameBuf,
+    ]))
+    offset += local.length
+  }
+  const central = Buffer.concat(centrals)
+  const eocd = Buffer.concat([
+    u32(0x06054b50), u16(0), u16(0), u16(Object.keys(entries).length), u16(Object.keys(entries).length),
+    u32(central.length), u32(offset), u16(0),
+  ])
+  return Buffer.concat([...locals, central, eocd])
+}
+
+/** 读取 ZIP（支持 store/deflate；仅处理我们关心的条目）。返回 Map<name, Buffer> */
+export function zipRead(buf) {
+  const out = new Map()
+  const eocd = findEocd(buf)
+  if (eocd < 0) throw new Error('not a zip file (no EOCD)')
+  const count = buf.readUInt16LE(eocd + 10)
+  let p = buf.readUInt32LE(eocd + 16) // central dir offset
+  for (let i = 0; i < count; i++) {
+    if (buf.readUInt32LE(p) !== 0x02014b50) break
+    const compMethod = buf.readUInt16LE(p + 10)
+    const compSize = buf.readUInt32LE(p + 20)
+    const nameLen = buf.readUInt16LE(p + 28)
+    const extraLen = buf.readUInt16LE(p + 30)
+    const commentLen = buf.readUInt16LE(p + 32)
+    const localOff = buf.readUInt32LE(p + 42)
+    const name = buf.subarray(p + 46, p + 46 + nameLen).toString('utf8')
+    p += 46 + nameLen + extraLen + commentLen
+    const lnameLen = buf.readUInt16LE(localOff + 26)
+    const lextraLen = buf.readUInt16LE(localOff + 28)
+    const dataStart = localOff + 30 + lnameLen + lextraLen
+    const data = buf.subarray(dataStart, dataStart + compSize)
+    out.set(name, compMethod === 0 ? data : zlib.inflateRawSync(data))
+  }
+  return out
+}
+
+function findEocd(buf) {
+  for (let i = buf.length - 22; i >= 0; i--) {
+    if (buf.readUInt32LE(i) === 0x06054b50) return i
+  }
+  return -1
+}
+
+/** OOXML part 解码：兼容 UTF-16（WPS 常见）与 UTF-8 带/不带 BOM。 */
+export function decodeXml(buf) {
+  if (buf.length >= 3 && buf[0] === 0xef && buf[1] === 0xbb && buf[2] === 0xbf) return buf.toString('utf8').slice(1)
+  if (buf.length >= 2 && buf[0] === 0xff && buf[1] === 0xfe) return buf.toString('utf16le')
+  if (buf.length >= 2 && buf[0] === 0xfe && buf[1] === 0xff) {
+    const s = buf.toString('utf16le').slice(1).split('')
+    const swapped = []
+    for (let i = 0; i + 1 < s.length; i += 2) {
+      swapped.push(s[i + 1])
+      swapped.push(s[i])
+    }
+    return swapped.join('')
+  }
+  return buf.toString('utf8')
+}
+
+/** OOXML 命名空间常量（用于 pptx 生成/解析） */
+export const NS = {
+  o: 'http://schemas.openxmlformats.org/officeDocument/2006/relationships',
+  r: 'http://schemas.openxmlformats.org/officeDocument/2006/relationships',
+  a: 'http://schemas.openxmlformats.org/drawingml/2006/main',
+  p: 'http://schemas.openxmlformats.org/presentationml/2006/main',
+  ct: 'http://schemas.openxmlformats.org/package/2006/content-types',
+  rel: 'http://schemas.openxmlformats.org/package/2006/relationships',
+}

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "dsh-ppt-studio",
+  "version": "1.1.0",
+  "description": "在 DeepSeek Harness 里做 PPT：说需求 → 逐页制作 → 导出可编辑的 .pptx。含布局检查、Office 真渲染复核，以及可扩展的本地模板库",
+  "//publish": "2026-09-18 定：发 npm，**无 scope** 包名 `dsh-ppt-studio`。**状态（2026-09-26）：尚未发布** —— `npm login` 已通（`npm whoami` = `zbsph`）、包名未被占用（`npm view` 404）、构件已备好（发版那个 tgz，sha 与 Release 资产一致），但首次 `npm publish` 返回 **E403**：账号开了 2FA，普通登录凭据不能写入，需 `--otp=<6 位码>` 或勾了 Bypass 2FA 的 granular token。发布纪律：**用发版时那个 tgz**（`npm publish \"<.sync-state.json 里 localTgz 指向的文件>\"`），保证 registry 字节与 GitHub Release 资产**逐字节相同**；**别在 main 前进后跑裸 `npm publish`**（会按当前工作区重新打包）。成功后才做：核对 `npm view dsh-ppt-studio version dist.integrity`，并在隔离 DSH_HOME 里 `dsh plugin add dsh-ppt-studio` 真装一遍。见 docs/06 与 docs/03 的 1.1.0 条目。",
+  "repository": { "type": "git", "url": "git+https://github.com/zbsph/dsh-ppt-studio.git" },
+  "homepage": "https://github.com/zbsph/dsh-ppt-studio#readme",
+  "bugs": { "url": "https://github.com/zbsph/dsh-ppt-studio/issues" },
+  "keywords": ["dsh", "ppt", "pptx", "powerpoint", "slides", "deck", "presentation", "cordis", "plugin", "deepseek-harness"],
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "main": "./lib/index.js",
+  "//lib": "lib/ 是**提交**的构建产物（src 的纯拷贝）：商店（创意工坊）对无 npm 包的条目生成的命令是 `dsh plugin add <repo URL>`，git 安装只拿得到已提交内容，lib 不入库则插件挂不上。守卫：npm run check:lib + smoke 断言。",
+  "//dsh": "profile bundle 声明（2026-09-14）：让 `dsh plugin --profile <p> add <本包>` 装完即挂载——launcher 在 profile 里跑完 pnpm 后核对 dsh.profile.bundles，声明了 dsh.bundle 的依赖自动入栈。dsh.engines.dsh（2026-09-24，DSH 0.1.7 新增字段）：本包从 1.0.7 起只支持 DSH >= 0.1.7-rc.1——不是挑剔版本，而是 0.1.7 把「预设 = 磁盘目录」换成了「预设 = 向 agentPresets 注册表声明」（旧版扫 <dshHome>/.agent-presets/；0.1.7 上游原文：the harness discovers no preset on disk），适配后的交付方式在 0.1.6 及以前没有任何效果。写上范围，让旧宿主上的用户拿到明确信号，而不是「装上却永远看不到那个预设」。",
+  "dsh": {
+    "engines": {
+      "dsh": ">=0.1.7-rc.1"
+    },
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "exports": {
+    ".": {
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "vendor",
+    "templates",
+    "docs",
+    "skills",
+    "scripts",
+    "agent-presets",
+    "cordis.patch.yml",
+    "examples/smoke",
+    "examples/fx",
+    "README.md"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "yaml": "^2.8.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.2 <5",
+    "@deepseek-ai/dsh-skill": ">=0.1.5-rc.2 <2",
+    "@deepseek-ai/dsh-tools": ">=0.1.5-rc.2 <2"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-skill": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "bash scripts/build.sh",
+    "build:node": "node scripts/build.mjs",
+    "sync": "node scripts/release-sync.mjs",
+    "test": "node scripts/build.mjs && node scripts/check-tracked-lf.mjs && node scripts/smoke.mjs && node scripts/check-preset.mjs",
+    "check:eol": "node scripts/check-tracked-lf.mjs",
+    "fresh": "node scripts/verify-fresh-install.mjs",
+    "test:real": "node scripts/regression-real.mjs",
+    "test:preflight": "node scripts/preflight-1.0.mjs",
+    "test:preset": "node scripts/check-preset.mjs",
+    "test:e2e": "node scripts/e2e-1.0.mjs",
+    "test:bundle": "node scripts/verify-bundle-install.mjs",
+    "check:lib": "node scripts/check-lib-freshness.mjs",
+    "audit:facts": "node scripts/audit-manual-facts.mjs",
+    "probe:effect": "node scripts/probe-effect-semantics.mjs",
+    "probe:reparse": "node scripts/probe-reparse-safety.mjs",
+    "probe:asset": "node scripts/probe-asset-freshness.mjs",
+    "eval:skills": "node scripts/eval-skills-score.mjs"
+  }
+}

package/scripts/audit-manual-facts.mjs

@@ -0,0 +1,294 @@
+/**
+ * 手册事实审计（evidence report）——「我改对了没有」的可复跑证据。
+ *
+ * 与 smoke 的分工：
+ *   - smoke §37/§38（13 条）= **回归闸门**：谁改坏了当场红、必须修。
+ *   - 本脚本 = **证据报告**：把每一条"手册 vs 源码"的事实逐条验一遍，打印 ✓/✗ + 源码锚点，
+ *     供人工复核与交接（`npm run audit:facts`）。不进门禁，失败退出码非 0 便于 CI/人工使用。
+ *
+ * 覆盖三类：
+ *   ① 结构性事实（名字/集合/形状/阈值）——可机器判定；
+ *   ② 运行时语义（某个写法到底会不会报错）——用真实引擎跑小夹具；
+ *   ③ 文档自证（各处引用计数、纪律文档里的条数）——防"文档说自己有 13 条其实只有 9 条"。
+ */
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { readFileSync, existsSync } from 'node:fs'
+import { rm, mkdir, writeFile, readFile } from 'node:fs/promises'
+import { listBundledSkills } from '../lib/skill.js'
+import { SCHEMA_REF } from '../lib/scaffold.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 { verifyDeck } from '../lib/verify.js'
+import { chartSvg } from '../lib/pptd/svgCharts.js'
+import { zipRead, decodeXml } from '../lib/zips.js'
+import { readFileSync as rfs } from 'node:fs'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+const read = (rel) => readFileSync(join(root, rel), 'utf8')
+const src = {
+  verify: read(join('src', 'verify.js')),
+  schema: read(join('src', 'pptd', 'schema.js')),
+  svgCharts: read(join('src', 'pptd', 'svgCharts.js')),
+  exportPptx: read(join('src', 'pptd', 'export-pptx.js')),
+  renderHtml: read(join('src', 'pptd', 'render-html.js')),
+  tools: read(join('src', 'tools.js')),
+  index: read(join('src', 'index.js')),
+  commands: read(join('src', 'commands.js')),
+  router: read(join('src', 'router.js')),
+  crosscheck: read(join('src', 'crosscheck.js')),
+  scaffold: read(join('src', 'scaffold.js')),
+}
+const skills = listBundledSkills().map((b) => ({ name: b.parsed.name, text: b.parsed.content, desc: b.parsed.description, when: b.parsed.whenToUse ?? '' }))
+const bySkill = Object.fromEntries(skills.map((s) => [s.name, s.text]))
+const all = skills.map((s) => s.text).join('\n')
+const manual = bySkill['ppt-studio-manual'] ?? ''
+
+let pass = 0
+let fail = 0
+const rows = []
+const check = (claim, ok, evidence) => {
+  rows.push(`${ok ? '✓' : '✗'} ${claim}\n      ↳ ${evidence}`)
+  ok ? pass++ : fail++
+}
+
+// ── ① 结构性事实 ────────────────────────────────────────────────────────────
+const registered = new Set()
+for (const f of ['tools.js', 'index.js']) for (const m of read(join('src', f)).matchAll(/name: '(ppt_[a-z_]+)'/g)) registered.add(m[1])
+const mentioned = new Set([...all.matchAll(/\b(ppt_[a-z_]+)\b/g)].map((m) => m[1]))
+const ghosts = [...mentioned].filter((t) => !registered.has(t))
+check('手册提到的 ppt_* 全部是已注册工具', ghosts.length === 0, ghosts.length ? `不存在：${ghosts.join('、')}` : `${mentioned.size} 个名字命中注册表（共 ${registered.size} 个工具）`)
+
+const vLines = src.verify.split(/\r?\n/)
+const codes = new Map()
+vLines.forEach((line, i) => {
+  if (/\b(?:let|const|var)\s+code\s*=/.test(line)) return
+  for (const m of line.matchAll(/code\s*[:=]\s*'([a-z-]+)'/g)) {
+    const w = vLines.slice(Math.max(0, i - 3), i + 1).join('\n')
+    codes.set(m[1], /'error'/.test(w) ? 'error' : 'warn|suggest')
+  }
+})
+const errCodes = [...codes].filter(([, s]) => s === 'error').map(([c]) => c).sort()
+const noDoc = errCodes.filter((c) => !manual.includes(c))
+check('verify 的每个门禁错误码都写进了使用手册 §4', noDoc.length === 0, noDoc.length ? `缺：${noDoc.join('、')}` : `错误码 ${errCodes.join('/')}`)
+const gateLine = manual.split('\n').find((l) => l.includes('ERROR 必须清零')) ?? ''
+const gateNames = [...gateLine.matchAll(/`([a-z][a-z-]*)`/g)].map((m) => m[1])
+const ghostGate = gateNames.filter((t) => !errCodes.includes(t))
+check('手册门禁清单里的 code 名都是真实错误码（防写出源码里没有的名字）', ghostGate.length === 0 && gateNames.length > 0, ghostGate.length ? `幽灵 code：${ghostGate.join('、')}` : `清单 = ${gateNames.join('/')}`)
+
+for (const c of ['density', 'hotspot', 'near-align']) {
+  const line = vLines.find((l) => l.includes(`code: '${c}'`)) ?? ''
+  check(`${c} 在源码里是 warning（手册不得归到 [·] 建议）`, /severity: 'warning'/.test(line), `verify.js: ${line.trim().slice(0, 90)}`)
+}
+const conformanceMode = src.verify.match(/severity: mode === 'strict' \? 'error' : 'warning',\s*\n?\s*code: 'theme-conformance'/)
+check('theme-conformance：strict=error / suggest=warning / off=跳过（手册如此描述）', !!conformanceMode, 'verify.js themeConformance(): severity 随 mode 切换；无 colors 自动跳过')
+
+const lineValidator = src.schema.match(/仅支持 2 点 \[\[x1,y1\],\[x2,y2\]\]/)
+check('line 只支持两点（手册已写明，拆成多条 line）', !!lineValidator, `schema.js validateLine: ${(lineValidator?.[0] ?? '未找到').slice(0, 60)}`)
+
+const tableKeys = src.schema.match(/table: \['cols', 'rows', 'header'\]/)
+check('table 只有 cols/rows/header（手册"没有逐列对齐字段"成立）', !!tableKeys, `schema.js ELEMENT_KEYS: ${tableKeys?.[0] ?? '未找到'}`)
+
+const chartKeys = src.schema.match(/chart: \['chart'\]/)
+const chartNoLabels = !/legend|dataLabels|labels\s*:/.test(src.schema.match(/function validateChart[\s\S]*?\n\}/)?.[0] ?? '')
+check('chart 没有分类名/数值/图例字段（手册"标签要自己补"成立）', !!chartKeys && chartNoLabels, `schema.js ELEMENT_KEYS.chart=${chartKeys?.[0] ?? '?'}；validateChart 只校验 type/data.cols/data.rows/series`)
+
+const trunc = Number((src.svgCharts.match(/c\.length\s*>\s*(\d+)/) ?? [])[1])
+const claimedTrunc = [...all.matchAll(/超过\s*(\d+)\s*字截断/g)].map((m) => Number(m[1]))
+check('预览图表分类名截断阈值 = 手册所写', trunc > 0 && claimedTrunc.every((n) => n === trunc), `svgCharts.js: c.length > ${trunc}；手册声称 ${claimedTrunc.join(',') || '未写'}`)
+
+const realCmds = new Set([...src.commands.matchAll(/cmd === '([a-z-]+)'/g)].map((m) => m[1]))
+const mentionedCmds = new Set([...all.matchAll(/\/ppt\s+([a-z-]+)/g)].map((m) => m[1]))
+const ghostCmds = [...mentionedCmds].filter((c) => !realCmds.has(c))
+check('/ppt 子命令真实存在', ghostCmds.length === 0, ghostCmds.length ? `不存在：${ghostCmds.join('、')}` : `手册用到 ${[...mentionedCmds].join('/')}；命令面共 ${realCmds.size} 个`)
+
+const floorM = src.exportPptx.match(/Math\.max\((\d+),\s*Math\.round\(origSize \*\s*([\d.]+)\)\)/)
+const floorPt = Number(floorM?.[1])
+const floorPct = Math.round(Number(floorM?.[2]) * 100)
+check('缩字下限常量 = 手册所写 max(6pt, 60%)', new RegExp(`max\\(${floorPt}pt, ${floorPct}% 原字号\\)`).test(manual), `export-pptx.js: Math.max(${floorPt}, Math.round(origSize * ${floorM?.[2]}))`)
+
+check('缺省页面尺寸 960×540 / 1px=1pt（手册所写）', /size \?\? \{ width: 960, height: 540 \}/.test(src.verify) && /960x540/.test(src.schema), 'verify.js verifyDeck(): size ?? {width:960,height:540}；schema.js 顶部注释')
+
+// ── ② 运行时语义（真引擎小夹具）─────────────────────────────────────────────
+const tmp = join(root, 'examples', 'smoke', '.tmp-audit-facts')
+await rm(tmp, { recursive: true, force: true })
+await mkdir(join(tmp, 'pages'), { recursive: true })
+const deckYaml = (pages) => ['version: 1', 'title: "审计夹具"', 'size: [960, 540]', 'theme:',
+  '  colors: {ink: "#111111", brand: "#2563EB"}',
+  '  textStyles:', '    body: {fontSize: 14, color: "$ink"}', 'pages:', ...pages.map((p) => `  - pages/${p}.yaml`), ''].join('\n')
+const page = (els, pageExtra = []) => ['pageType: content', ...pageExtra, 'elements:', ...els, ''].join('\n')
+const box = 'bounds: [40, 40, 300, 80]'
+
+// 夹具 A：文字压图表（含/不含 role 与声明）
+const chartEl = (role, extra = []) => ['  - elementId: chart', '    elementType: chart', `    ${box}`, ...(role ? [`    role: ${role}`] : []),
+  '    chart:', '      type: bar', '      data:', '        cols: [分类, 值]', '        rows: [[A, 1], [B, 2]]', ...extra]
+const labelEl = ['  - elementId: label', '    elementType: text', '    bounds: [60, 60, 200, 40]', '    content: {text: "压在图上的标签", style: "$body"}']
+// 不压图表的第二个元素：单元素页不会产生美学建议（els.length < 2 直接 return），且压图会造出 content-collision
+const sideEl = ['  - elementId: side', '    elementType: text', '    bounds: [60, 320, 600, 40]', '    content: {text: "图旁的说明", style: "$body"}']
+const writeDeck = async (dir, els, pageExtra = []) => {
+  await mkdir(join(dir, 'pages'), { recursive: true })
+  await writeFile(join(dir, 'deck.yaml'), deckYaml(['01']), 'utf8')
+  await writeFile(join(dir, 'pages', '01.yaml'), page(els, pageExtra), 'utf8')
+}
+const verifyDir = async (dir) => {
+  const ctx = await resolveDeck(dir)
+  const r = await renderDeck(ctx, {})
+  const v = verifyDeck(r.layout)
+  return { ctx, r, v, errors: v.text.split('\n').filter((l) => l.includes('[✗]')).length }
+}
+
+const dirA = join(tmp, 'a-plain')
+await writeDeck(dirA, [...labelEl, ...chartEl(null)])
+const ra = await verifyDir(dirA)
+check('运行时：无 role 的 chart 被 text 压住 → content-collision（内容互压）', /content-collision/.test(ra.v.text), `errors=${ra.errors}；${(ra.v.text.match(/content-collision[^\n]*/) ?? [''])[0].slice(0, 100)}`)
+
+const dirB = join(tmp, 'b-declared-plain')
+await writeDeck(dirB, [...labelEl, ...chartEl(null)], ['expectedOverlaps:', '  - pair: [chart, label]'])
+const rb = await verifyDir(dirB)
+check('运行时：无 role 时"声明也不管用"（仍报 content-collision）——手册"不可声明豁免"成立', /content-collision/.test(rb.v.text) && rb.errors > 0, `errors=${rb.errors}`)
+
+const dirC = join(tmp, 'c-background')
+await writeDeck(dirC, [...labelEl, ...chartEl('background')], ['expectedOverlaps:', '  - pair: [chart, label]'])
+const rc = await verifyDir(dirC)
+check('运行时：chart role:background + 声明 → 0 错误（"图当衬底"路径成立）', rc.errors === 0 && /预期重叠/.test(rc.v.text), `errors=${rc.errors}；${(rc.v.text.match(/预期重叠[^\n]*/) ?? [''])[0].slice(0, 60)}`)
+
+const dirD = join(tmp, 'd-decoration')
+await writeDeck(dirD, [...labelEl, ...chartEl('decoration')])
+const rd = await verifyDir(dirD)
+check('运行时：chart role:decoration → 不再报重叠（"纯装饰"路径成立，无需声明）', rd.errors === 0 && !/content-collision/.test(rd.v.text), `errors=${rd.errors}`)
+
+const dirE = join(tmp, 'e-dec-outside')
+await mkdir(join(dirE, 'pages'), { recursive: true })
+await writeFile(join(dirE, 'deck.yaml'), ['version: 1', 'title: "出界夹具"', 'size: [960, 540]', 'theme:', '  colors: {ink: "#111111"}', '  safeArea: {top: 20, bottom: 20, left: 0, right: 0}', 'pages:', '  - pages/01.yaml', ''].join('\n'), 'utf8')
+await writeFile(join(dirE, 'pages', '01.yaml'), page(['  - elementId: deco', '    elementType: shape', '    kind: rect', '    role: decoration', '    bounds: [40, 4, 120, 12]', '    fill: "#111111"']), 'utf8')
+const re = await verifyDir(dirE)
+check('运行时：decoration 不豁免出界（仍报 out-of-safe-area）——手册与 C3 口径一致', /out-of-safe-area/.test(re.v.text), `errors=${re.errors}；${(re.v.text.match(/out-of-safe-area[^\n]*/) ?? [''])[0].slice(0, 90)}`)
+
+const dirF = join(tmp, 'f-bad-chart')
+await writeDeck(dirF, ['  - elementId: c', '    elementType: chart', `    ${box}`, '    chart:', '      type: bad', '      data: [{label: A, value: 1}]'])
+let badChart = null
+try { await resolveDeck(dirF) } catch (e) { badChart = e }
+check('运行时：chart 写成 data:[{label,value}] / type:bad → schema 直接拒绝', !!badChart && /chart\.type|data\.cols/.test(badChart.messages?.join(';') ?? ''), (badChart?.messages ?? []).join('; ').slice(0, 140) || '竟然通过了')
+
+const dirG = join(tmp, 'g-3pts-line')
+await writeDeck(dirG, ['  - elementId: poly', '    elementType: line', '    points: [[10, 10], [50, 30], [90, 10]]'])
+let badLine = null
+try { await resolveDeck(dirG) } catch (e) { badLine = e }
+check('运行时：三点折线被拒（手册"每条只有两点"成立）', !!badLine && /2 点/.test(badLine.messages?.join(';') ?? ''), (badLine?.messages ?? []).join('; ').slice(0, 120) || '竟然通过了')
+
+const dirH = join(tmp, 'h-notes')
+await mkdir(join(dirH, 'pages'), { recursive: true })
+await writeFile(join(dirH, 'deck.yaml'), deckYaml(['01']), 'utf8')
+await writeFile(join(dirH, 'pages', '01.yaml'), ['pageType: content', 'notes: "这段讲稿应被写进 pptx 备注页"', 'elements:', ...labelEl, ''].join('\n'), 'utf8')
+const rh = await verifyDir(dirH)
+const expH = await exportPptx(rh.ctx, { out: 'out-notes.pptx', engine: 'pptd' })
+const zipH = zipRead(await readFile(expH.file))
+const hasNotesPart = [...zipH.keys()].some((k) => /^ppt\/notesSlides\/notesSlide\d+\.xml$/.test(k))
+check('运行时：页面 notes 真的写进 pptx（备注页部件存在）', hasNotesPart, hasNotesPart ? '包内有 notesSlide 部件' : '包内没有 notesSlide')
+const notesParityOk = expH.parity?.notesExp === 1 && expH.parity?.notesOut === 1 && expH.parity?.ok === true
+check('运行时：导出 parity 自证备注（notesExp/notesOut 且 ok）', notesParityOk, `parity = ${JSON.stringify(expH.parity ?? {})}`)
+const notesRelsH = decodeXml(zipH.get('ppt/notesSlides/_rels/notesSlide1.xml.rels') ?? Buffer.from(''))
+check('运行时：notesSlide 自带 rels（→ notesMaster + 回指幻灯）——缺它真 PowerPoint 报"文件损坏"',
+  /notesMaster/.test(notesRelsH) && /Type="[^"]*\/slide"/.test(notesRelsH),
+  `rels: ${notesRelsH.slice(0, 120) || '(缺失)'}`)
+check('运行时：presentation.xml 不含 notesMasterIdLst（实测该元素会让 PowerPoint 拒开）',
+  !/notesMasterIdLst/.test(decodeXml(zipH.get('ppt/presentation.xml'))), 'presentation.xml 中无 notesMasterIdLst')
+const xmljsMod = await import('../lib/xmljs.js')
+check('实体解码：&lt;/&amp;/数字实体能解回字符（导入侧此前不解码）',
+  xmljsMod.parseXml('<a:t>R&amp;D &lt;x&gt; &#65;</a:t>').children[0].text === 'R&D <x> A',
+  `解码结果=${JSON.stringify(xmljsMod.parseXml('<a:t>R&amp;D &lt;x&gt; &#65;</a:t>').children[0].text)}`)
+
+const dirI = join(tmp, 'i-chartref')
+await writeDeck(dirI, ['  - elementId: c', '    elementType: chart', `    ${box}`, '    chart:', '      type: bar', '      colors: ["$brand"]', '      data:', '        cols: [分类, 值]', '        rows: [[A, 1], [B, 2]]', ...sideEl])
+const ri = await verifyDir(dirI)
+// 必须走真实渲染产物：normalizePage() 会在 layout.js 里 resolveColor，直接调 chartSvg(原始 yaml) 会绕过它。
+// （layout.json 快照只记 chartType、不记 colors，所以三层里可查的是"预览 HTML"与"导出 XML"两层。）
+const htmlI = readFileSync(join(ri.r.outDir, ri.r.htmlFiles[0]), 'utf8')
+const expI = await exportPptx(ri.ctx, { out: 'out-ref.pptx', engine: 'pptd' })
+const xmlI = zipRead(await readFile(expI.file)).get('ppt/slides/slide1.xml').toString('utf8')
+check('运行时：chart colors 用 $themeRef（$brand）在预览与成品两层都被解析为 hex',
+  !htmlI.includes('$brand') && !/val="\$brand"/.test(xmlI),
+  `预览 HTML ${htmlI.includes('$brand') ? '出现字面 $brand ✗' : '已解析 ✓'}；导出 XML ${/val="\$brand"/.test(xmlI) ? '仍是 $brand ✗' : '已解析 ✓'}`)
+
+const themeChartColors = /aesthetic-theme[^\n]*颜色/.test(ri.v.text)
+check('运行时：chart 显式用主题内颜色（$ref=$brand）→ 不出配色建议（不打扰）', !themeChartColors, themeChartColors ? (ri.v.text.match(/[^\n]*aesthetic-theme[^\n]*/) ?? [''])[0].slice(0, 110) : '无配色建议（$brand ∈ theme.colors）')
+
+const dirI2 = join(tmp, 'i2-chart-offtheme')
+await writeDeck(dirI2, ['  - elementId: c', '    elementType: chart', `    ${box}`, '    chart:', '      type: bar', '      colors: ["#FF00FF"]', '      data:', '        cols: [分类, 值]', '        rows: [[A, 1], [B, 2]]', ...sideEl])
+const ri2 = await verifyDir(dirI2)
+const offThemeSuggested = /aesthetic-theme[^\n]*#FF00FF/.test(ri2.v.text)
+check('运行时：chart 显式写主题外颜色 → [·] 建议且**不新增错误**（图表配色刻意保持建议级）',
+  offThemeSuggested && ri2.errors === 0,
+  `建议${offThemeSuggested ? '命中' : '未命中'}；errors=${ri2.errors}`)
+
+// ── ③ 文档自证 ──────────────────────────────────────────────────────────────
+const smokeSrc = read(join('scripts', 'smoke.mjs'))
+const guardNames = [...smokeSrc.matchAll(/ok\('(手册 vs 源码|SCHEMA_REF 自洽|文档计数自证)[^']*'/g)].map((m) => m[0])
+const docClaim = Number((read(join('docs', '05-迭代流程.md')).match(/已落成 \*\*(\d+) 条机器断言\*\*/) ?? [])[1])
+check('docs/05 §0c 声称的断言条数 = smoke 里实际新增的手册事实断言条数', docClaim === guardNames.length, `docs 声称 ${docClaim} 条；smoke 实际 ${guardNames.length} 条`)
+
+const refLines = SCHEMA_REF.split('\n')
+const refBad = refLines.find((l) => /decoration/.test(l) && /豁免/.test(l) && /出界/.test(l) && !/不豁免出界/.test(l))
+check('SCHEMA_REF 自洽：不声称 decoration 豁免出界', refBad === undefined && refLines.some((l) => /不豁免出界/.test(l)), refBad ? `仍写着：${refBad.trim().slice(0, 70)}` : '两处口径一致：只豁免重叠、不豁免出界')
+
+const crossPageClaims = /跨页一致性没有断言|这些没有工具断言|工具基本不管/.test(bySkill['ppt-studio-craft'] ?? '')
+check('craft 已写明"跨页一致性没有工具断言"（源码确实无跨页/字体家族检查）', crossPageClaims && !/fontFamily/.test(src.verify), `verify.js 中 fontFamily 出现 ${(src.verify.match(/fontFamily/g) ?? []).length} 次`)
+
+// 2026-09-18 改判：表格有了自己的溢出断言（table-overflow），图表仍然没有。
+// 这条审计的价值正在于此——加门禁时它当场抓出"手册还在说表格没有溢出断言"。
+const tableOverflowClaim = /table-overflow/.test(bySkill['ppt-studio-data'] ?? '') && /不检查图表/.test(bySkill['ppt-studio-data'] ?? '')
+const overflowTextAndTable = /el\.kind === 'text' \|\| el\.kind === 'table'/.test(src.verify)
+  && /code: 'table-overflow'/.test(src.verify)
+  && !/code: '(chart|image)-overflow'/.test(src.verify)
+check('data 已写明"表格有溢出断言（table-overflow）、图表没有"（与源码一致）',
+  tableOverflowClaim && overflowTextAndTable, `verify.js: 溢出断言覆盖 text+table；chart 仍无`)
+
+// 2026-09-18 重写：crosscheck 从"机器判定（跨页数字分组 + grounded/unmapped 伪状态）"改为
+// "材料包 + 审阅协议（工具不判定）"。这条审计的价值仍在于**手册与源码不许各说各话**：
+// 源码里不得残留状态机/分组，data 手册必须同步成"材料包"口径且不得再提 grounded/unmapped。
+const packRewrite = /审阅材料包/.test(src.crosscheck)
+  && /无法核实/.test(src.crosscheck) && /无来源支撑/.test(src.crosscheck)
+  && /不要使用子代理/.test(src.crosscheck)
+const noVerdictLogic = !/status: [^\n]*'grounded'/.test(src.crosscheck)
+  && !/numMap/.test(src.crosscheck) && !/groups: groups/.test(src.crosscheck)
+const dataSkillSynced = /ppt_crosscheck/.test(bySkill['ppt-studio-data'] ?? '')
+  && /材料包/.test(bySkill['ppt-studio-data'] ?? '')
+  && !/grounded|unmapped/.test(bySkill['ppt-studio-data'] ?? '')
+check('data 对 crosscheck 的口径与源码一致（材料包+审阅协议；无 grounded/unmapped 伪状态、无数字分组）',
+  packRewrite && noVerdictLogic && dataSkillSynced,
+  `crosscheck.js：材料包=${packRewrite}｜无状态机=${noVerdictLogic}｜data 手册已同步=${dataSkillSynced}`)
+
+const chartIssueScope = /allZero/.test(src.svgCharts) && !/fabricat/.test(src.svgCharts)
+const chartIssueHonest = /没有任何工具会拦/.test(bySkill['ppt-studio-data'] ?? '')
+check('data 对 chartIssue 的能力描述准确（只拦空数据/全零）', chartIssueScope && chartIssueHonest, 'svgCharts.js chartIssue(): rows 为空 / 全零或非有限值 → 其余不拦')
+
+const notesHonest = /备注页/.test(bySkill['ppt-studio-copy'] ?? '') && /(导出|写进|随导出)/.test(bySkill['ppt-studio-copy'] ?? '')
+check('copy §7 与导出器一致：讲稿会写进 pptx 备注页（双向断言，手册说反了会红）',
+  notesHonest && /notesSlides\//.test(src.exportPptx), `export-pptx.js 备注部件 ${(src.exportPptx.match(/notesSlides\//g) ?? []).length} 处；手册${notesHonest ? '说会导出' : '未说会导出'}`)
+
+const presetDrift = existsSync(join(root, 'agent-presets', 'ppt', 'agent.cordis.yml'))
+check('预设副本仍在（check-preset.mjs 负责逐行比对）', presetDrift, 'agent-presets/ppt/agent.cordis.yml 存在，`npm run test:preset` 比对随包 standard')
+
+// 触发纪律（2026-09-15 用户反馈）：答疑手册曾被"开工时"加载——因为它的 description/whenToUse
+// 把"如何开始 / 模型不确定某一 DSL 写法"写成了触发条件（对正在做 PPT 的人是恒真条件）。
+// 事实判定：答疑触发面只认"用户提问"，制作三本不把读者引向答疑手册，工作流提示段显式分行。
+const manParsed = skills.find((s) => s.name === 'ppt-studio-manual') ?? { desc: '', when: '' }
+const qaDesc = /用户问|提问/.test(manParsed.desc)
+const qaWhen = /提问|用户问/.test(manParsed.when)
+const negated = /不要加载/.test(manParsed.desc) && /不要加载/.test(manParsed.when)
+const selfTrigger = /模型不确定/.test(manParsed.desc + manParsed.when) || /不确定某一/.test(manParsed.desc + manParsed.when)
+check('答疑手册触发纪律：只由"用户提问"触发（description/whenToUse 双处声明 + "制作中不要加载"否定句）',
+  qaDesc && qaWhen && negated && !selfTrigger,
+  `提问触发=${qaDesc}/${qaWhen}｜否定句=${negated}｜恒真自触发措辞残留=${selfTrigger}`)
+
+const crossPtr = ['ppt-studio-craft', 'ppt-studio-data', 'ppt-studio-copy'].filter((n) => (bySkill[n] ?? '').includes('ppt-studio-manual'))
+const wfSplit = /答疑手册/.test(src.router) && /不要加载/.test(src.router)
+check('答疑手册分层落地：工作流提示段显式分行（答疑手册 vs 制作手册），制作三本正文零指向答疑手册',
+  wfSplit && crossPtr.length === 0, `工作流含分行=${wfSplit}；三本指向=${crossPtr.join('、') || '无'}`)
+
+await rm(tmp, { recursive: true, force: true })
+
+console.log(rows.join('\n'))
+console.log(`\n==== 手册事实审计：${pass} 通过 / ${fail} 失败（共 ${pass + fail} 条，逐条附源码锚点）====`)
+process.exit(fail > 0 ? 1 : 0)