dsh-ppt-studio 1.1.0

package/lib/pptxPy.js

@@ -0,0 +1,205 @@
+/**
+ * python-pptx 引擎：把中间层（deck.yaml）映射为 python-pptx 脚本（兜底引擎）。
+ * 覆盖 text / shape / image / table；chart 降级为表格+说明。
+ * 需要 python 环境 + python-pptx（运行前探测，缺失则报错提示）。
+ */
+import { readFile } from 'node:fs/promises'
+import { join, isAbsolute } from 'node:path'
+import { spawnSync } from 'node:child_process'
+import YAML from 'yaml'
+import { normalizePage, measureText } from './pptd/layout.js'
+
+export function genPythonScript(ctx) {
+  const py = []
+  py.push('from pptx import Presentation')
+  py.push('from pptx.util import Emu, Pt')
+  py.push('from pptx.dml.color import RGBColor')
+  py.push('from pptx.enum.shapes import MSO_SHAPE, MSO_CONNECTOR')
+  py.push('from pptx.enum.text import PP_ALIGN, MSO_ANCHOR')
+  py.push('import json, sys')
+  py.push('')
+  // OUT 由 runPythonExport 替换成字面量路径（见文件末尾的 replace）。
+  // 旧实现是 `prs.save(sys.argv[1])` + `print("saved:", sys.argv[1])`，导出时只替换了 save 那一行，
+  // 于是脚本**存完文件后**在 print 处 IndexError（`python -c` 下没有 argv[1]）——文件其实已经写出来了，
+  // 调用方却收到"执行失败"。改成变量后再不会有这个错位。
+  py.push('OUT = sys.argv[1] if len(sys.argv) > 1 else "out.pptx"')
+  py.push('')
+  py.push(`W, H = ${ctx.size.width}, ${ctx.size.height}`)
+  py.push('prs = Presentation()')
+  py.push('prs.slide_width = Emu(W * 12700)')
+  py.push('prs.slide_height = Emu(H * 12700)')
+  py.push('blank = prs.slide_layouts[6]')
+  py.push('')
+  py.push('def rgb(c):')
+  py.push('    if not c: return RGBColor(0, 0, 0)')
+  py.push('    c = c.lstrip("#").upper()')
+  py.push('    return RGBColor(int(c[0:2], 16), int(c[2:4], 16), int(c[4:6], 16))')
+  py.push('')
+  py.push('def fit_font(font, text, box_w, box_h):')
+  py.push('    # 保守估算：CJK 1em / latin 0.55em')
+  py.push('    fs = font.size.pt if font.size else 18')
+  py.push('    lines = max(1, int(box_h // (fs * 1.2)))')
+  py.push('    chars = 0')
+  py.push('    for ch in text:')
+  py.push('        chars += 1 if ord(ch) > 0x2E7F else 0.55')
+  py.push('    need = chars * fs')
+  py.push('    if need > box_w * lines:')
+  py.push('        fs = max(int(fs * box_w * lines / need), int(fs * 0.6))')
+  py.push('        font.size = Pt(fs)')
+  py.push('')
+  py.push('def add_text(slide, b, text, st):')
+  py.push('    box = slide.shapes.add_textbox(Emu(b[0]*12700), Emu(b[1]*12700), Emu(b[2]*12700), Emu(b[3]*12700))')
+  py.push('    tf = box.text_frame')
+  py.push('    tf.word_wrap = True')
+  py.push('    tf.margin_left = tf.margin_right = 0')
+  py.push('    tf.margin_top = tf.margin_bottom = 0')
+  py.push('    fs = st.get("fontSize", 18)')
+  py.push('    for i, line in enumerate(str(text).split("\\n")):')
+  py.push('        p = tf.paragraphs[0] if i == 0 else tf.add_paragraph()')
+  py.push('        run = p.add_run()')
+  py.push('        run.text = line')
+  // 样式必须落在 **run** 上：`paragraph.font` 只写 pPr/defRPr，而 `p.text = …` 会新建 run，
+  // 之前那种"先设 paragraph.font 再 p.text=" 的写法会把字号/颜色/粗体全部丢掉（导出看着有字、样式全无）。
+  py.push('        f = run.font')
+  py.push('        f.size = Pt(fs)')
+  py.push('        if st.get("bold"): f.bold = True')
+  py.push('        f.color.rgb = rgb(st.get("color"))')
+  py.push('        if st.get("fontFamily"): f.name = st["fontFamily"]')
+  py.push('        p.alignment = {"left": PP_ALIGN.LEFT, "center": PP_ALIGN.CENTER, "right": PP_ALIGN.RIGHT}.get(st.get("align"), PP_ALIGN.LEFT)')
+  py.push('        p.line_spacing = st.get("lineHeight", 1.2)')
+  py.push('        fit_font(f, line, b[2], b[3])')
+  py.push('')
+
+  for (const page of ctx.pages) {
+    const els = normalizePage(page, ctx)
+    py.push(`slide = prs.slides.add_slide(blank)`)
+    for (const el of els) {
+      const [x, y, w, h] = [el.bounds.x, el.bounds.y, el.bounds.w, el.bounds.h]
+      switch (el.type) {
+        case 'text': {
+          py.push(`add_text(slide, [${x}, ${y}, ${w}, ${h}], ${JSON.stringify(el.content?.text ?? '')}, ${pyLit({ ...el.style })})`)
+          break
+        }
+        case 'shape': {
+          const map = { rect: 'MSO_SHAPE.RECTANGLE', ellipse: 'MSO_SHAPE.OVAL', triangle: 'MSO_SHAPE.ISOCELES_TRIANGLE' }
+          const mode = map[el.kind] ?? 'MSO_SHAPE.RECTANGLE'
+          py.push(`sh = slide.shapes.add_shape(${mode}, Emu(${x}*12700), Emu(${y}*12700), Emu(${w}*12700), Emu(${h}*12700))`)
+          // 填充/描边必须生成**语句**，不能写成单行条件表达式。原实现写的是
+          //   `sh.line.fill.background() if not {...} else (sh.line.color.rgb = …, sh.line.width = …)`
+          // 一次踩三种雷：① `else (a = b, …)`——赋值是**语句**不是表达式 ⇒ 直接 **SyntaxError**（连编译都过不去）；
+          // ② fill/line 缺省时插值出 JS 的 `undefined` / `null`，Python 里不存在 ⇒ NameError；
+          // ③ `{color, alpha}` 被 JSON.stringify 成 dict 直接喂给 `rgb()` ⇒ AttributeError。
+          // 兜底引擎的全部意义是"pptd 硬失败时还能出片"，它自己语法错就等于没有兜底。
+          const solid = fillColorOf(el.fill)
+          if (solid) {
+            py.push('sh.fill.solid()')
+            py.push(`sh.fill.fore_color.rgb = rgb(${JSON.stringify(solid)})`)
+            if (isApproxFill(el.fill)) py.push('# 注意：alpha / 渐变在兜底引擎里按纯色近似（原生引擎 pptd 保留原样）')
+          } else {
+            py.push('sh.fill.background()')
+          }
+          if (el.line?.color) {
+            py.push(`sh.line.color.rgb = rgb(${JSON.stringify(el.line.color)})`)
+            py.push(`sh.line.width = Pt(${Number(el.line.width) || 1})`)
+          } else {
+            py.push('sh.line.fill.background()')
+          }
+          break
+        }
+        case 'line': {
+          const p1 = el.points[0]
+          const p2 = el.points[1]
+          py.push(`ln = slide.shapes.add_connector(MSO_CONNECTOR.STRAIGHT, Emu(${p1[0]}*12700), Emu(${p1[1]}*12700), Emu(${p2[0]}*12700), Emu(${p2[1]}*12700))`)
+          py.push(`ln.line.color.rgb = rgb(${JSON.stringify(el.line?.color ?? '#000000')}); ln.line.width = Pt(${el.line?.width ?? 1})`)
+          break
+        }
+        case 'image':
+          py.push(`slide.shapes.add_picture(${JSON.stringify(join(ctx.dir, el.src))}, Emu(${x}*12700), Emu(${y}*12700), Emu(${w}*12700), Emu(${h}*12700))`)
+          break
+        case 'table': {
+          py.push(`rows, cols = ${JSON.stringify(el.rows.length + (el.header ? 1 : 0))}, ${Math.max(1, el.cols.length)}`)
+          py.push(`tbl = slide.shapes.add_table(rows, cols, Emu(${x}*12700), Emu(${y}*12700), Emu(${w}*12700), Emu(${h}*12700)).table`)
+          if (el.header) py.push(`for j, v in enumerate(${pyLit(el.cols)}): tbl.cell(0, j).text = str(v)`)
+          py.push(`for i, row in enumerate(${pyLit(el.rows)}):`)
+          py.push(`    for j, v in enumerate(row): tbl.cell(${el.header ? 'i + 1' : 'i'}, j).text = str(v)`)
+          if (el.header) py.push(`for j in range(cols): tbl.cell(0, j).text_frame.paragraphs[0].font.bold = True`)
+          break
+        }
+        case 'chart': {
+          py.push(`# chart 降级：引擎 B 以表格表达（引擎 A 支持矢量拼绘）`)
+          break
+        }
+      }
+    }
+  }
+  py.push('')
+  py.push(`prs.save(OUT)`)
+  py.push(`print("saved:", OUT)`)
+  return py.join('\n')
+}
+
+/** JS 值 → **Python** 字面量。
+ *  为什么不能直接用 JSON.stringify：它产出的是 **JSON**，而 JSON 的 true/false/null 在 Python 里非法。
+ *  真 bug 现场：文本元素的样式字典 `{"wrap":true}` 原样进脚本 ⇒ `NameError: name 'true' is not defined`——
+ *  而文本是最高频的路径，等于兜底引擎对几乎任何 deck 都不可用。 */
+function pyLit(v) {
+  if (v === null || v === undefined) return 'None'
+  if (typeof v === 'boolean') return v ? 'True' : 'False'
+  if (typeof v === 'number') return Number.isFinite(v) ? String(v) : 'None'
+  if (typeof v === 'string') return JSON.stringify(v)
+  if (Array.isArray(v)) return `[${v.map(pyLit).join(', ')}]`
+  if (typeof v === 'object') return `{${Object.entries(v).map(([k, val]) => `${JSON.stringify(k)}: ${pyLit(val)}`).join(', ')}}`
+  return 'None'
+}
+
+/** fill 归一化后的取色：'#hex' | {color,alpha} | {type:'gradient',stops} → '#hex' | null（无填充）。 */
+function fillColorOf(fill) {
+  if (fill == null) return null
+  if (typeof fill === 'string') return /^#/.test(fill) ? fill : null
+  if (Array.isArray(fill.stops)) return fillColorOf(fill.stops[0]?.color ?? null)
+  if (fill.color != null) return fillColorOf(fill.color)
+  return null
+}
+
+/** 兜底引擎会**近似**的填充（alpha / 渐变）——用于在生成脚本里留下诚实标注，而不是悄悄改变观感。 */
+function isApproxFill(fill) {
+  return Boolean(fill && typeof fill === 'object'
+    && (fill.type === 'gradient' || fill.alpha != null || Array.isArray(fill.stops)))
+}
+
+export function findPython() {
+  for (const cmd of ['python', 'py']) {
+    try {
+      const r = spawnSync(cmd, ['-c', 'import pptx; print("ok")'], { encoding: 'utf8', timeout: 15000 })
+      if (r.status === 0 && r.stdout.includes('ok')) return { cmd, has: true }
+      if (r.status === 0 || (r.error === undefined && r.stderr === '')) return { cmd, has: false }
+    } catch { /* try next */ }
+  }
+  return { cmd: null, has: false }
+}
+
+export function runPythonScript(ctx, script) {
+  const py = findPython()
+  if (!py.has) throw new Error('python-pptx 引擎不可用：未检测到带 python-pptx 的 python 环境（pip install python-pptx）——可改用默认 pptd 引擎')
+  return startPython(py.cmd, script)
+}
+
+function startPython(cmd, script) {
+  const r = spawnSync(cmd, ['-c', script], { encoding: 'utf8', timeout: 120000 })
+  if (r.status !== 0) {
+    // A2b 修复（反馈二）：空消息无法定位 → 带 exit code / spawn 错误 / stderr 全文
+    const detail = String(r.error?.code ?? r.error?.message ?? '').trim() || String(r.stderr ?? r.stdout ?? '').trim().slice(0, 1500)
+    throw new Error(`python-pptx 执行失败（exit ${r.status ?? 'unknown'}${r.signal ? `, signal ${r.signal}` : ''}）${detail ? `：${detail}` : '：解释器无任何输出（疑似 WindowsApps 假 python 桩或环境损坏）'}`)
+  }
+  return r.stdout
+}
+
+export async function runPythonExport(ctx, out) {
+  // out：绝对路径原样使用；相对路径相对 deck 目录（与 pptd 引擎同语义，E1）
+  const outPath = isAbsolute(out) ? out : join(ctx.dir, out)
+  // 替换 OUT 那一行（不再替换 save 行——旧写法只换 save，导致 print 仍在读 argv[1]：
+  //   `python -c` 下没有 argv[1] ⇒ **文件已写出却报执行失败**）
+  const script = genPythonScript(ctx).replace(/^OUT = .*$/m, `OUT = ${JSON.stringify(outPath)}`)
+  const result = await runPythonScript(ctx, script)
+  return { file: outPath, engine: 'python-pptx', note: result.trim() }
+}

package/lib/preset-delivery.js

@@ -0,0 +1,195 @@
+/**
+ * 预设交付（2026-09-24 适配 DSH **0.1.7-rc.1**）：从"写预设目录"改为"向 agent-preset 注册表声明"。
+ *
+ * ── 为什么必须改（上游结构性变更，不是可选优化）────────────────────────────────
+ * 0.1.6 及以前：宿主启动时**扫描** `<dshHome>/.agent-presets/<id>/agent.cordis.yml`，
+ *   所以插件只要把文件写进去，预设就会出现在新建会话的选择器里（`dsh-agent-presets` 的 discover 路径）。
+ * 0.1.7：那条发现路径**整个被删掉了**。上游换成两个包——
+ *   `@deepseek-ai/dsh-agent-preset`（一条 YAML 声明）+ `@deepseek-ai/dsh-agent-preset-registry`
+ *   （只有 `register/list/resolve/...`，**没有任何目录扫描**）；随包预设也改为
+ *   `dsh-web-app/presets/*.patch.yml` 里 insert 一行 `@deepseek-ai/dsh-agent-preset`。
+ *   社区插件自己对这条的表述（dsh-client-ui-preset-center README）：
+ *     "Nothing scans that directory: the harness discovers no preset on disk."
+ *   ⇒ 继续写目录 = 预设**永远不会出现**，而且失败是静默的（没有报错、没有日志）。
+ *
+ * ── 现在的做法 ────────────────────────────────────────────────────────────────
+ * 插件激活时把包内 `agent-presets/ppt/` 那份组合**声明**给注册表：
+ *     ctx.inject(['agentPresets'], child => child.agentPresets.register({id,name,description,order,plugins}))
+ * `plugins` = `agent.cordis.yml` 的条目数组（Loader 方言），`name`/`description`/`order` = `preset.yml`。
+ *
+ * 三个必须守住的细节（都有源码依据）：
+ *   ① **`!!js` 必须保真**：`disabled: !!js process.platform === 'win32'` 在 Loader 方言里是
+ *      `{ __jsExpr: "<源码>" }`（`dsh-app-boot` 的 `JsExpr` = `tag:yaml.org,2002:js`，
+ *      `construct: data => ({ __jsExpr: data })`；`cordis-plugin-loader` 用
+ *      `evaluate(ctx, value.__jsExpr)` 求值）。自己读 YAML 时若把它降级成普通字符串，
+ *      `Boolean(<非空字符串>) === true` ⇒ **Windows 上 tool-pwsh 行会被误停用**（没有 shell）。
+ *      本模块用 `yaml` 包注册同名 tag，产出的就是 Loader 认的那个形状。
+ *   ② **相对模块名要变成 file URL**：注册表 mount 时用
+ *      `scope.ctx.extend({ baseUrl: <注册表所在 ctx 的 baseUrl> })`（= harness base，**不是**预设目录），
+ *      所以 `name: ./foo.mjs` 会解析到 harness 里去。社区插件（dsh-liangshen）对同一问题的处理
+ *      就是把相对名展开成 `file://` 绝对 URL。本模块照做（当前组合里没有相对名，属防御）。
+ *   ③ **disposer 归声明者所有**：`register()` 返回注销函数。插件卸载（HMR/停用行）后若不注销，
+ *      再次装配会撞 `Duplicate agent preset: ppt`（`register` 对重复 id 直接 throw）。
+ *      所以整段挂在 `ctx.effect` 上，随插件同生共死。
+ *
+ * ── 安全边界 ────────────────────────────────────────────────────────────────
+ *   · 可被 `config.autoPreset === false` 关闭（保留旧配置键，不破坏既有 profile patch）；
+ *   · 注册表缺失（极简部署 / 低于 0.1.7 的宿主）只告警，**绝不抛**——预设没了也不能让插件挂不上；
+ *   · 组合里出现解析不了的相对名时**拒绝声明**（宁可没有预设，也不声明一条注定 broken 的声明：
+ *     broken 的预设会被 `presetOptions()` 过滤掉，等于白声明还多一条误导日志）。
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { parse } from 'yaml'
+
+/** 预设 id（选择器里的稳定标识；`agent-presets/ppt/` 目录名一致）。 */
+export const PRESET_ID = 'ppt'
+
+/**
+ * Loader 方言里的 `!!js` tag —— 与 `dsh-app-boot` 的 `JsExpr` 同定义（`construct` → `{__jsExpr}`）。
+ * 用我们自己的 `yaml` 包注册（宿主那份在 harness base，profile 里 import 不到）。
+ */
+const JS_TAG = {
+  tag: 'tag:yaml.org,2002:js',
+  resolve: (value) => ({ __jsExpr: value }),
+}
+
+/** 包内自带的预设目录（`lib/` 的上一级 = 包根）。 */
+export function builtinPresetDir() {
+  return join(dirname(fileURLToPath(import.meta.url)), '..', 'agent-presets', PRESET_ID)
+}
+
+/** 最近一次声明的结果（供 ppt_state 与测试观测；进程内单例）。 */
+const STATUS = { id: PRESET_ID, declared: false, via: '', reason: '尚未装配', rows: 0 }
+export function presetDeliveryStatus() {
+  return { ...STATUS }
+}
+
+function loggerOf(ctx) {
+  try { return typeof ctx.logger === 'function' ? ctx.logger('ppt-studio') : ctx.logger } catch { return undefined }
+}
+
+/** 读 Loader 方言的条目数组（`!!js` 保真）。 */
+function readEntryList(file) {
+  const doc = parse(readFileSync(file, 'utf8'), { customTags: [JS_TAG] })
+  if (!Array.isArray(doc)) throw new Error(`${file} 不是 Loader 方言的条目数组`)
+  return doc
+}
+
+/**
+ * 把相对模块名（`./x.mjs` / `../x.mjs`）展开为 `file://` 绝对 URL，递归进 `config` 数组（group 行）。
+ * 解析不到目标文件时抛错（调用方据此拒绝声明）。
+ */
+function absolutizeRows(rows, baseDir) {
+  return rows.map((row) => {
+    const out = { ...row }
+    if (typeof out.name === 'string' && /^\.\.?\//.test(out.name)) {
+      const target = resolve(baseDir, out.name)
+      if (!existsSync(target)) throw new Error(`预设行 ${String(out.id)} 的相对模块名解析不到：${out.name}（在 ${baseDir} 下）`)
+      out.name = pathToFileURL(target).href
+    }
+    if (Array.isArray(out.config)) out.config = absolutizeRows(out.config, baseDir)
+    return out
+  })
+}
+
+/**
+ * 组装交给 `agentPresets.register()` 的声明。
+ * @param {string} [dir] 预设目录（缺省 = 包内自带那份）
+ * @returns {{id: string, name: string, description: string, order: number, plugins: object[]}}
+ */
+export function presetDeclaration(dir = builtinPresetDir()) {
+  const composition = join(dir, 'agent.cordis.yml')
+  if (!existsSync(composition)) throw new Error(`包内预设组合缺失：${composition}`)
+  let meta = {}
+  const metaFile = join(dir, 'preset.yml')
+  if (existsSync(metaFile)) {
+    try { meta = parse(readFileSync(metaFile, 'utf8')) ?? {} } catch { meta = {} }
+  }
+  const plugins = absolutizeRows(readEntryList(composition), dir)
+  return {
+    id: PRESET_ID,
+    name: typeof meta.name === 'string' ? meta.name : 'PPT 工作室',
+    description: typeof meta.description === 'string' ? meta.description : '',
+    order: typeof meta.order === 'number' ? meta.order : 2,
+    plugins,
+  }
+}
+
+function readRegistry(ctx) {
+  try { return ctx.get('agentPresets') } catch { return undefined }
+}
+
+/**
+ * 幂等地把「PPT 工作室」预设声明给 agent-preset 注册表。
+ * @returns {{id: string, declared: boolean, via: string, reason: string, rows: number}} 当前（可能尚未完成的）状态
+ */
+export function declareAgentPreset(ctx, config = {}) {
+  if (config?.autoPreset === false) {
+    STATUS.declared = false
+    STATUS.via = ''
+    STATUS.reason = 'autoPreset=false（配置关闭）'
+    return presetDeliveryStatus()
+  }
+
+  let declaration
+  try {
+    declaration = presetDeclaration()
+  } catch (e) {
+    STATUS.declared = false
+    STATUS.via = ''
+    STATUS.reason = `预设组合不可用（未声明）：${String(e?.message ?? e)}`
+    loggerOf(ctx)?.warn?.(`[ppt-studio] ${STATUS.reason}`)
+    return presetDeliveryStatus()
+  }
+  STATUS.rows = declaration.plugins.length
+  STATUS.reason = '等待 agentPresets 注册表…'
+
+  const warn = (message) => { try { loggerOf(ctx)?.warn?.(`[ppt-studio] ${message}`) } catch { /* 无 logger 时静默 */ } }
+  let release
+  let closed = false
+  let queue = Promise.resolve()
+
+  const declare = (registry) => {
+    queue = queue.then(async () => {
+      if (closed || release !== undefined) return
+      if (registry === undefined) {
+        STATUS.reason = 'agentPresets 服务不可见（本部署未装配预设注册表？）——预设未声明'
+        warn(STATUS.reason)
+        return
+      }
+      try {
+        release = await registry.register(declaration)
+        STATUS.declared = true
+        STATUS.via = 'agentPresets.register'
+        STATUS.reason = `已声明（${declaration.plugins.length} 行）——新建会话的预设选择器里可选「${declaration.name}」`
+        try { loggerOf(ctx)?.info?.(`[ppt-studio] ${STATUS.reason}`) } catch { /* 忽略 */ }
+      } catch (e) {
+        STATUS.declared = false
+        STATUS.via = ''
+        STATUS.reason = `声明失败（不影响插件本身）：${String(e?.message ?? e)}`
+        warn(STATUS.reason)
+      }
+    }).catch((e) => { warn(`预设声明队列异常：${String(e?.message ?? e)}`) })
+  }
+
+  ctx.effect(() => {
+    if (typeof ctx.inject === 'function') {
+      // 注册表可能比本插件行晚激活：`inject` 等它出现再声明，服务消失时子 ctx 一并释放。
+      ctx.inject(['agentPresets'], (child) => { declare(readRegistry(child)) })
+    } else {
+      declare(readRegistry(ctx))
+    }
+    return () => {
+      closed = true
+      const dispose = release
+      release = undefined
+      STATUS.declared = false
+      STATUS.reason = '插件卸载——预设已注销'
+      return dispose === undefined ? queue : Promise.resolve(dispose()).catch(() => {})
+    }
+  }, 'ppt-studio: agent preset declaration')
+
+  return presetDeliveryStatus()
+}

package/lib/preview-server.js

@@ -0,0 +1,164 @@
+/**
+ * PPT 预览服务（需求 A「对话内看 PPT」，v0.6.0）：
+ * host 侧：webServer 注册 `/ppt-preview/` 前缀路由，静态服务于"预览根"。
+ * - 预览根 = ~/.dsh/ppt-studio/preview/<token>/：pages/（render 的 html）+ media/（deck 媒体）。
+ *   render 输出的 html 引用 `../media/`（相对 deck 根）→ 预览根内 pages/../media/ 恰好解析。
+ * - URL 为同源相对路径（/ppt-preview/<token>/pages/deck.html）：GUI 页面本身就在 host 上，
+ *   点击/iframe 均同源，不依赖端口探测。
+ */
+import { mkdir, rm, copyFile, readFile, stat } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { join, dirname, extname, normalize } from 'node:path'
+import { homedir } from 'node:os'
+import { createHash } from 'node:crypto'
+import { resolveDeck } from './pptd/schema.js'
+import { renderDeck } from './pptd/render-html.js'
+
+export const PREVIEW_ROOT = join(homedir(), '.dsh', 'ppt-studio', 'preview')
+const tokens = new Map() // token -> previewRoot
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.svg': 'image/svg+xml',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json',
+}
+
+/**
+ * 构建预览根并分配 token。返回 { token, url, pages, previewRoot }。
+ * render 复用预览管道（preview/*.html + layout.json），再拷贝到隔离预览根。
+ */
+export async function buildPreview(dir) {
+  const ctx = await resolveDeck(dir)
+  const r = await renderDeck(ctx, {})
+  const token = createHash('md5').update(dir).digest('hex').slice(0, 10)
+  const root = join(PREVIEW_ROOT, token)
+  await rm(root, { recursive: true, force: true })
+  await mkdir(join(root, 'pages'), { recursive: true })
+  for (const f of r.htmlFiles) {
+    await copyFile(join(dir, 'preview', f), join(root, 'pages', f))
+  }
+  await copyFile(join(dir, 'preview', 'deck.html'), join(root, 'pages', 'deck.html'))
+  // media（含页面背景图；html 以 ../media/ 引用）
+  if (existsSync(join(dir, 'media'))) {
+    const mediaDir = join(root, 'media')
+    await mkdir(mediaDir, { recursive: true })
+    for (const name of await import('node:fs/promises').then((f) => f.readdir(join(dir, 'media')))) {
+      await copyFile(join(dir, 'media', name), join(mediaDir, name))
+    }
+  }
+  tokens.set(token, root)
+  // 持久化映射（跨进程/重启后链接仍可用）：.meta.json 记录源目录
+  try {
+    const { writeFile } = await import('node:fs/promises')
+    await writeFile(join(root, '.meta.json'), JSON.stringify({ sourceDir: dir, token }))
+  } catch { /* 非致命 */ }
+  return {
+    token,
+    url: `/ppt-preview/${token}/pages/${r.htmlFiles[0]}`,
+    overviewUrl: `/ppt-preview/${token}/pages/deck.html`,
+    pages: r.htmlFiles.length,
+    previewRoot: root,
+  }
+}
+
+/** token → 预览根（内存优先，miss 时从 .meta.json 恢复并回填）。 */
+async function resolveToken(token) {
+  if (tokens.has(token)) return tokens.get(token)
+  const root = join(PREVIEW_ROOT, token)
+  try {
+    const meta = JSON.parse(await readFile(join(root, '.meta.json'), 'utf8'))
+    if (meta?.sourceDir) {
+      tokens.set(token, root)
+      return root
+    }
+  } catch { /* miss */ }
+  return null
+}
+
+/**
+ * 装配双源（注入器 registry 恢复 + agent preset 行挂载）可能同时挂载本插件——
+ * 「duplicate /ppt-preview」崩溃的根因（时序竞态）。路由注册幂等化，**双重防线**：
+ * ① **以 webServer 前缀表为皇帝位**——注册前先查表：已有 /ppt-preview（无论谁注册的、
+ *    refcount 状态如何）→ 跳过注册（只计数）；防任何时序的双注册。
+ * ② refcount 管理（globalThis，跨模块实例共享；双源经 junction/真实路径可能是两个
+ *    ESM 实例，模块级变量不可靠）。
+ * **v0.14.5 补**：卸载器 u() 是异步的（u() 返回 Promise，未 await 会导致"卸载未完成时
+ *   新注册 → duplicate"——v0.14.4 取消路径实测复现）；卸载路径全部 await。
+ */
+const ROUTE_REG = globalThis.__pptRouteReg ?? { count: 0, unreg: null }
+globalThis.__pptRouteReg = ROUTE_REG
+
+/** 卸载决策：count 归零且有卸载器 → await 卸载（失败保留残留，由表判据挡住重复注册）。 */
+async function releaseRouteWhenZero() {
+  if (ROUTE_REG.count === 0 && ROUTE_REG.unreg) {
+    const u = ROUTE_REG.unreg
+    ROUTE_REG.unreg = null
+    try { await u() } catch { /* 幂等；残留由注册前表判据兜底 */ }
+  }
+}
+
+/** 注册预览路由（返回 disposer；无 webServer 环境返回 null）。 */
+export function registerPreviewRoute(ctx) {
+  const ws = ctx.get('webServer')
+  if (!ws) return null
+  const hasRoute = () => (ws.prefixes?.has?.('/ppt-preview') ?? false) === true
+  if (hasRoute() || ROUTE_REG.count > 0) {
+    // 幂等分支：表已注册（任何来源）或本组已发起注册 → 只计数，不重复注册
+    ROUTE_REG.count++
+    // Cordis 语义：`ctx.effect(cb)` 立即执行 cb、用其**返回值**当 disposer。
+    // 这里必须"返回一个函数"——原实现把 `count--` 写在 cb 体里，等于注册当刻就递减，
+    // 于是本文档承诺的"首个注册者真注册、最后卸载者真卸载"实际不成立（路由永不释放）。
+    // 2026-09-14 修正（与 index.js 的装配防重同一处语义错误）。
+    return ctx.effect(() => () => { ROUTE_REG.count--; void releaseRouteWhenZero() }, 'ppt-studio: preview route (ref)')
+  }
+  let cancelled = false
+  const unregPromise = ws.register({
+    kind: 'prefix',
+    path: '/ppt-preview', // prefix 语义：path 不带尾斜杠（实测：带斜杠不命中）
+    async handler(req, res) {
+      try {
+        const u = new URL(req.url ?? '/', 'http://localhost') // 仅作为解析相对路径的基准，不用于输出
+        // token 允许字母/数字/连字符（hex 预览 token 与固定 token 均匹配；v0.14.1 曾因 [a-zA-Z0-9]+ 不含 '-' 导致画廊 404）
+        const m = u.pathname.match(/^\/ppt-preview\/([a-zA-Z0-9-]+)\/(.*)$/)
+        if (!m) return notFound(res)
+        const root = await resolveToken(m[1])
+        const rel = normalize(m[2]).replace(/^([/\\])+/, '')
+        if (!root || rel.includes('..')) return notFound(res)
+        const file = join(root, rel)
+        if (!existsSync(file)) return notFound(res)
+        const st = await stat(file)
+        if (st.isDirectory()) return notFound(res)
+        const buf = await readFile(file)
+        res.writeHead(200, { 'Content-Type': MIME[extname(file).toLowerCase()] ?? 'application/octet-stream', 'Content-Length': buf.length, 'Cache-Control': 'no-store' })
+        res.end(buf)
+      } catch {
+        res.writeHead(500)
+        res.end('preview error')
+      }
+    },
+  }).then(async (u) => {
+    if (cancelled) { try { await u() } catch { /* 幂等 */ } ; return null }
+    ROUTE_REG.unreg = u
+    return u
+  }).catch(() => null)
+  ROUTE_REG.count++
+  // 同上：cb 立即执行、返回值是 disposer —— 清理逻辑必须包在**返回的函数**里。
+  return ctx.effect(() => () => {
+    ROUTE_REG.count--
+    if (cancelled) return
+    if (ROUTE_REG.unreg) { void releaseRouteWhenZero(); return }
+    cancelled = true
+    unregPromise.then(() => releaseRouteWhenZero())
+  }, 'ppt-studio: preview route')
+}
+
+function notFound(res) {
+  res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' })
+  res.end('not found')
+}