dsh-ppt-studio 1.1.0

package/lib/skill.js

@@ -0,0 +1,174 @@
+/**
+ * 内置 skill 包（提问式手册 + 制作能力手册）——DSH 0.1.5 起的"插件内嵌 skill"通道：
+ *   ctx.skills.register(...)（@deepseek-ai/dsh-skill 的运行时注册）
+ *
+ * 为什么走内嵌而不是只写文件：
+ *  - 注册落在**调用 ctx 所在层**；本插件由 agent preset 的常驻装配挂载 → 落该 preset 层，
+ *    只有 PPT 工作室会话看得见（不污染全局技能目录）；
+ *  - 内容随包（lib/../skills/<name>/SKILL.md），与插件同生共死——升级即新、卸载即净，无副本可过期；
+ *  - 与用户自装同名技能**不冲突**：注册表跨层重名由"就近层优先"裁决，PPT 会话内命中包内嵌这一份，
+ *    用户那份在其它会话照旧可见。
+ *
+ * 设计约束（2026-09-14，用户明确）：
+ *  - 内嵌技能是**纯增益**：不改变任何铁律与门禁语义；技能缺失 / skills 服务缺位时插件完整可用；
+ *  - 每个技能必须自包含且短（描述 ≤500 字且只写触发，正文几千字符量级）——正文是按需加载的成本。
+ *
+ * 兼容策略：install.mjs 仍把同一份 SKILL.md 镜像到 <dshHome>/skills/<name>/（非 PPT 会话也能问到手册）。
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import YAML from 'yaml'
+
+/** 随包技能根目录（包根/skills）。 */
+export const SKILLS_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'skills')
+/** 提问式手册（历史名，保持导出兼容）。 */
+export const MANUAL_NAME = 'ppt-studio-manual'
+export const MANUAL_DIR = join(SKILLS_DIR, MANUAL_NAME)
+export const MANUAL_FILE = join(MANUAL_DIR, 'SKILL.md')
+
+/**
+ * 解析 SKILL.md：YAML frontmatter（name/description/whenToUse/disable-model-invocation/user-invocable/metadata）
+ * + body 作为 content。语义与 @deepseek-ai/dsh-skill-filesystem 的 parseSkillFile 对齐
+ * （content = 去 frontmatter 后 trim 的正文），保证"文件通道"与"内嵌通道"交付同一份内容。
+ * @returns {{name: string, description: string, whenToUse?: string, invocation?: {modelInvocable: boolean, userInvocable: boolean}, metadata?: object, content: string} | null}
+ */
+export function parseManual(raw) {
+  if (typeof raw !== 'string') return null
+  const text = raw.replace(/^\uFEFF/, '')
+  if (!text.startsWith('---')) return null
+  const firstEnd = text.indexOf('\n')
+  if (firstEnd < 0) return null
+  const close = text.indexOf('\n---', firstEnd)
+  if (close < 0) return null
+  const bodyStart = text.indexOf('\n', close + 1)
+  let data
+  try {
+    data = YAML.parse(text.slice(firstEnd + 1, close + 1))
+  } catch {
+    return null
+  }
+  if (!data || typeof data !== 'object' || Array.isArray(data)) return null
+  const name = typeof data.name === 'string' ? data.name : ''
+  const description = typeof data.description === 'string' ? data.description : ''
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(name) || description.length === 0) return null
+  const invocation = invocationOf(data)
+  return {
+    name,
+    description,
+    ...(typeof data.whenToUse === 'string' && data.whenToUse.length > 0 ? { whenToUse: data.whenToUse } : {}),
+    ...(invocation !== undefined ? { invocation } : {}),
+    ...(data.metadata && typeof data.metadata === 'object' && !Array.isArray(data.metadata) ? { metadata: data.metadata } : {}),
+    content: (bodyStart < 0 ? '' : text.slice(bodyStart)).trim(),
+  }
+}
+
+/** frontmatter 调用策略：仅显式给出时才产出（缺省由注册表补 {modelInvocable:true, userInvocable:true}）。 */
+function invocationOf(data) {
+  const model = data['disable-model-invocation']
+  const user = data['user-invocable']
+  if (model === undefined && user === undefined) return undefined
+  if ((model !== undefined && typeof model !== 'boolean') || (user !== undefined && typeof user !== 'boolean')) return undefined
+  return { modelInvocable: model !== true, userInvocable: user !== false }
+}
+
+/**
+ * 扫描随包技能目录，返回全部可注册技能（跳过无 SKILL.md / frontmatter 非法的目录——不阻断装配）。
+ * @returns {{dir: string, file: string, parsed: object}[]}
+ */
+export function listBundledSkills(dir = SKILLS_DIR) {
+  const out = []
+  if (!existsSync(dir)) return out
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue
+    const skillDir = join(dir, entry.name)
+    const file = join(skillDir, 'SKILL.md')
+    if (!existsSync(file)) continue
+    let parsed = null
+    try {
+      parsed = parseManual(readFileSync(file, 'utf8'))
+    } catch {
+      continue
+    }
+    if (parsed === null) continue
+    out.push({ dir: skillDir, file, parsed })
+  }
+  return out.sort((a, b) => a.parsed.name.localeCompare(b.parsed.name))
+}
+
+/**
+ * 本包内嵌技能的注册结果（纯标量自检快照，不持有活对象）。
+ * 由 `ppt_state` 输出——安装后若想确认"技能到底有没有挂上"，问一次 ppt_state 即可。
+ */
+const STATUS = {
+  registered: false,
+  reason: '未尝试',
+  name: MANUAL_NAME,          // 兼容字段：指向提问式手册
+  contentLen: 0,              // 兼容字段：手册正文长度
+  skills: [],                 // [{name, contentLen, registered}]
+}
+
+/** 注册结果快照（副本；调用方只读）。 */
+export function manualSkillStatus() {
+  return { ...STATUS, skills: STATUS.skills.map((s) => ({ ...s })) }
+}
+
+/** 把单个技能注册进当前 ctx（挂本插件 fiber：停用/卸载即自动注销）。 */
+function registerOne(ctx, skills, item) {
+  const { parsed } = item
+  return ctx.effect(() => skills.register({
+    name: parsed.name,
+    description: parsed.description,
+    ...(parsed.whenToUse !== undefined ? { whenToUse: parsed.whenToUse } : {}),
+    ...(parsed.invocation !== undefined ? { invocation: parsed.invocation } : {}),
+    metadata: { ...(parsed.metadata ?? {}), plugin: 'dsh-ppt-studio', delivery: 'embedded' },
+    // 资源基址：技能里的相对引用（references/ 等）可据此定位；同时标明来源是包目录
+    resourceBase: { kind: 'directory', path: item.dir },
+    source: 'runtime',
+    content: parsed.content,
+  }), `ppt-studio: embedded skill (${parsed.name})`)
+}
+
+/**
+ * 注册全部随包内嵌技能。
+ * @returns {{name: string, contentLen: number}[]} 实际注册成功的技能（skills 服务缺失时为空数组）
+ */
+export function registerManualSkill(ctx) {
+  const skills = ctx.get('skills')
+  if (skills === undefined) {
+    STATUS.registered = false
+    STATUS.reason = 'skills 服务缺失（本部署未装配 @deepseek-ai/dsh-skill）'
+    STATUS.skills = []
+    return []
+  }
+  const found = listBundledSkills()
+  if (found.length === 0) {
+    STATUS.registered = false
+    STATUS.reason = `未找到随包技能（${SKILLS_DIR}）`
+    ctx.logger?.warn?.(`ppt-studio: ${STATUS.reason}——内嵌 skill 未注册`)
+    STATUS.skills = []
+    return []
+  }
+  const registered = []
+  for (const item of found) {
+    try {
+      registerOne(ctx, skills, item)
+      registered.push({ name: item.parsed.name, contentLen: item.parsed.content.length, registered: true })
+    } catch (error) {
+      ctx.logger?.warn?.(`ppt-studio: 内嵌 skill ${item.parsed.name} 注册失败：${error?.message ?? error}`)
+      registered.push({ name: item.parsed.name, contentLen: item.parsed.content.length, registered: false })
+    }
+  }
+  const manual = registered.find((s) => s.name === MANUAL_NAME)
+  STATUS.registered = registered.every((s) => s.registered)
+  STATUS.reason = STATUS.registered ? 'ok' : '部分技能注册失败'
+  STATUS.name = MANUAL_NAME
+  STATUS.contentLen = manual?.contentLen ?? 0
+  STATUS.skills = registered
+  return registered.map((s) => ({ name: s.name, contentLen: s.contentLen }))
+}
+
+/** 随包技能名清单（ppt_state 自检用）。 */
+export function bundledSkillNames() {
+  return listBundledSkills().map((s) => s.parsed.name)
+}

package/lib/splice.js

@@ -0,0 +1,219 @@
+/**
+ * A3/A9 修复（反馈二 ★★）：保真交付——"在原件上只换一页、其余页逐字节不动"。
+ *
+ * `spliceIntoSource`：把 deck 的某一页（pptd 导出单页）替换进 source.pptx 的指定页，
+ *   保留源母版/布局（横幅/页脚原样）、保留该页 notes 关系、媒体合并；其余条目逐字节不变（SHA256 自证）。
+ * `sliceSource`：从（已 splice 或任意）source.pptx 修剪出"单页 + 完整母版/布局/主题"的独立文件
+ *   （等价演示的"单页版"：sldIdLst 只留 1 条、其余幻灯/备注/关系/Override 删除）。
+ *
+ * 实现事实：元组手术用自研 zipRead/zipWrite（deflate 重写，Office 可读）+ 正则处理
+ * presentation.xml / rels / [Content_Types].xml —— 与测试会话手工 PowerShell 手术的程序化等价物。
+ */
+import { readFile, writeFile, mkdir, rm } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import crypto from 'node:crypto'
+import { zipRead, zipWrite, decodeXml } from './zips.js'
+import { resolveDeck } from './pptd/schema.js'
+import { exportPptx } from './pptd/export-pptx.js'
+
+const TINY_PNG = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==', 'base64')
+
+function sha256(buf) { return crypto.createHash('sha256').update(buf).digest('hex') }
+
+/** zip 条目逐条目 SHA256 摘要（返回 Map<name, hash>）。 */
+export function zipDigests(buf) {
+  const out = new Map()
+  for (const [name, data] of zipRead(buf)) out.set(name, sha256(data))
+  return out
+}
+
+/** 从 deck 导出第 page 张（1 基）幻灯的 XML + 媒体包。 */
+export async function deckSlideBundle(deckDir, page) {
+  const ctx = await resolveDeck(deckDir)
+  if (page < 1 || page > ctx.pages.length) throw new Error(`deck 页号越界：${page}（共 ${ctx.pages.length} 页）`)
+  const tmp = join(tmpdir(), `dsh-ppt-splice-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`)
+  await mkdir(tmp, { recursive: true })
+  try {
+    const r = await exportPptx(ctx, { out: join(tmp, 'deck.pptx'), engine: 'pptd' })
+    const z = zipRead(await readFile(r.file))
+    const slideXml = z.get(`ppt/slides/slide${page}.xml`)
+    const slideRels = z.get(`ppt/slides/_rels/slide${page}.xml.rels`)
+    if (!slideXml) throw new Error(`导出产物缺少第 ${page} 张 slide XML（导出异常）`)
+    const relText = decodeXml(slideRels ?? '')
+    const media = []
+    for (const m of relText.matchAll(/Id="(rId\d+)"[^>]*Type="[^"]*\/image"[^>]*Target="\.\.\/media\/([^"]+)"/g)) {
+      const name = decodeURIComponent(m[2])
+      let data = z.get('ppt/media/' + name)
+      if (!data) {
+        const dfile = join(deckDir, 'media', name)
+        if (existsSync(dfile)) data = await readFile(dfile)
+      }
+      media.push({ rId: m[1], name, data: data ?? TINY_PNG })
+    }
+    return { slideXml: decodeXml(slideXml), media, count: ctx.pages.length }
+  } finally {
+    await rm(tmp, { recursive: true, force: true }).catch(() => {})
+  }
+}
+
+/** 定位 source.pptx 第 page 页（1 基）的 slide 键（含 'ppt/' 前缀）。 */
+export function locateSourceSlide(z, page) {
+  const pres = decodeXml(z.get('ppt/presentation.xml'))
+  const relsText = decodeXml(z.get('ppt/_rels/presentation.xml.rels'))
+  const rIds = [...pres.matchAll(/<p:sldId\b[^>]*r:id="([^"]+)"/g)].map((m) => m[1])
+  if (page < 1 || page > rIds.length) throw new Error(`source 页号越界：${page}（共 ${rIds.length} 页）`)
+  const rid = rIds[page - 1]
+  const rel = new Map()
+  for (const m of relsText.matchAll(/<Relationship\s+Id="([^"]+)"\s+Type="([^"]+)"\s+Target="([^"]+)"/g)) rel.set(m[1], { type: m[2], target: m[3] })
+  const r = rel.get(rid)
+  const target = (r?.target ?? '').replace(/^(\.\.\/)+/, '').replace(/^ppt\//, '')
+  if (!r || !/^slides\/slide\d+\.xml$/.test(target)) throw new Error(`source 第 ${page} 页关系解析失败（${rid} → ${r?.target ?? '?'}）`)
+  const slideName = target.split('/').pop()
+  const slideRelsKey = `ppt/slides/_rels/${slideName}.rels`
+  const slideRels = z.has(slideRelsKey) ? decodeXml(z.get(slideRelsKey)) : null
+  return { slide: target, slideKey: 'ppt/' + target, slideRelsKey, slideRels, rid, rIds }
+}
+
+function maxRelId(relsXml) {
+  let max = 0
+  for (const m of relsXml.matchAll(/rId(\d+)/g)) max = Math.max(max, Number(m[1]))
+  return max
+}
+
+/**
+ * 把 deck 第 deckPage 页替换进 source.pptx 的第 sourcePage 页。
+ * @returns { out, sourcePages, deckPages, replaced, unchangedCount, changed, mediaAdded, mediaReused, notesKept }
+ */
+export async function spliceIntoSource({ deckDir, source, page, sourcePage = page, out }) {
+  const zbuf = await readFile(source)
+  const z = zipRead(zbuf)
+  const src = locateSourceSlide(z, sourcePage)
+  const bundle = await deckSlideBundle(deckDir, page)
+
+  // 新 XML：媒体 rId 改号（与源幻灯 rels 现有 id 无冲突）
+  if (!src.slideRels) throw new Error(`源幻灯 ${src.slideKey} 无关系文件（异常结构）——无法安全替换，请人工处理`)
+  const base = maxRelId(src.slideRels)
+  let rewritten = bundle.slideXml
+  const mediaRels = []
+  const mediaNames = []
+  bundle.media.forEach((m, i) => {
+    const newId = `rId${base + 1 + i}`
+    rewritten = rewritten.replaceAll(`r:embed="${m.rId}"`, `r:embed="${newId}"`).replaceAll(`r:link="${m.rId}"`, `r:link="${newId}"`)
+    mediaNames.push(m.name)
+    mediaRels.push(`    <Relationship Id="${newId}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/image" Target="../media/${m.name}"/>`)
+  })
+  // 源幻灯 rels 原样保留（布局/备注等）；媒体关系追加尾部
+  const newRels = src.slideRels.replace(/<\/Relationships>\s*$/, mediaRels.join('\n') + '\n</Relationships>')
+
+  // 媒体：同名已存在 → 复用源条目（零改动）；否则新增（数据来自导出包/deck media/占位图）
+  const partsToAdd = []
+  let mediaReused = 0
+  const seenCts = new Set((decodeXml(z.get('[Content_Types].xml') ?? '') ?? '').match(/<Default\s+[^>]*Extension="([^"]+)"/g)?.map((s) => s.match(/Extension="([^"]+)"/)[1].toLowerCase()) ?? [])
+  let newCt = z.has('[Content_Types].xml') ? decodeXml(z.get('[Content_Types].xml')) : '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"></Types>'
+  let ctChanged = false
+  for (const name of mediaNames) {
+    const key = 'ppt/media/' + name
+    if (z.has(key)) { mediaReused++; continue }
+    const hit = bundle.media.find((m) => m.name === name)
+    partsToAdd.push([key, hit?.data ?? TINY_PNG])
+    const ext = (name.split('.').pop() ?? '').toLowerCase()
+    if (ext && !seenCts.has(ext)) {
+      const ct = ext === 'png' ? 'image/png' : (ext === 'jpg' || ext === 'jpeg') ? 'image/jpeg' : ext === 'gif' ? 'image/gif' : ext === 'emf' ? 'image/x-emf' : 'application/octet-stream'
+      newCt = newCt.replace(/<\/Types>\s*$/, `<Default Extension="${ext}" ContentType="${ct}"/>\n</Types>`)
+      seenCts.add(ext)
+      ctChanged = true
+    }
+  }
+
+  // entries 重建：保持源顺序，替换目标 slide/rels，追加新增媒体，必要时更新 Content_Types
+  const relsKey = src.slideRelsKey
+  const entries = {}
+  for (const [name, data] of z) {
+    if (name === src.slideKey) { entries[name] = Buffer.from(rewritten, 'utf8'); continue }
+    if (name === relsKey) { entries[name] = Buffer.from(newRels, 'utf8'); continue }
+    if (ctChanged && name === '[Content_Types].xml') { entries[name] = Buffer.from(newCt, 'utf8'); continue }
+    entries[name] = data
+  }
+  for (const [key, data] of partsToAdd) entries[key] = data
+
+  const outPath = out ?? source.replace(/\.pptx$/i, '-spliced.pptx')
+  await writeFile(outPath, zipWrite(entries))
+
+  // 自证：源条目（除 slide/rels/ContentTypes）与输出逐字节一致
+  const srcDig = zipDigests(zbuf)
+  const outDig = zipDigests(await readFile(outPath))
+  const excluded = new Set([src.slideKey, relsKey, '[Content_Types].xml'])
+  const changedKeys = [...srcDig.keys()].filter((k) => !excluded.has(k) && srcDig.get(k) !== (outDig.get(k) ?? ''))
+  const unchangedCount = [...srcDig.keys()].filter((k) => !excluded.has(k) && srcDig.get(k) === outDig.get(k)).length
+  const notesKept = /notesSlide/.test(src.slideRels ?? '')
+  return {
+    out: outPath, sourcePages: src.rIds.length, deckPages: bundle.count,
+    replaced: { slide: src.slideKey, sourcePage, deckPage: page },
+    unchangedCount,
+    changed: [...changedKeys, ...(ctChanged ? ['[Content_Types].xml' + '（媒体类型新增）'] : []), ...partsToAdd.map(([k]) => k + '（新增）')],
+    mediaAdded: partsToAdd.length,
+    mediaReused,
+    notesKept,
+  }
+}
+
+/**
+ * 单页化：source.pptx（可先 splice）→ "单页 + 完整母版/布局/主题"独立文件。
+ * 等价测试会话手工手术：sldIdLst 只留 1 条、其余幻灯/备注/关系/Override 删除、布局母版全保留。
+ */
+export async function sliceSource({ source, page, out }) {
+  const zbuf = await readFile(source)
+  const z = zipRead(zbuf)
+  const src = locateSourceSlide(z, page)
+  const slideKey = src.slideKey
+  const slideName = src.slide.split('/').pop()
+  const relsKey = `ppt/slides/_rels/${slideName}.rels`
+  let notesKey = null
+  if (z.has(relsKey)) {
+    const rels = decodeXml(z.get(relsKey))
+    const m = rels.match(/Target="\.\.\/notesSlides\/(notesSlide\d+\.xml)"/)
+    if (m) notesKey = 'ppt/notesSlides/' + m[1]
+  }
+  // presentation.xml：sldIdLst 只留目标页（完整捕获标签含 />，否则替换产物缺闭合 → 文档损坏）
+  let pres = decodeXml(z.get('ppt/presentation.xml'))
+  const sldIds = [...pres.matchAll(/<p:sldId\b[^>]*?r:id="([^"]+)"\s*\/?>/g)]
+  pres = pres.replace(/<p:sldIdLst>[\s\S]*?<\/p:sldIdLst>/, () => {
+    const pick = sldIds.find((m) => m[1] === src.rid)
+    return `<p:sldIdLst>${pick?.[0] ?? ''}</p:sldIdLst>`
+  })
+  // presentation.xml.rels：删除非目标页的 slide 关系（layout/master/theme 等保留）
+  let presRels = decodeXml(z.get('ppt/_rels/presentation.xml.rels'))
+  presRels = presRels.replace(/<Relationship\s+Id="(rId\d+)"\s+Type="[^"]*\/slide"\s+Target="[^"]+"\s*\/>/g, (m0, rid) => (rid === src.rid ? m0 : ''))
+  // [Content_Types].xml：删除其他幻灯/备注 Override（保留目标页与其余类型）
+  const slideNo = slideName.match(/slide(\d+)\.xml$/)?.[1] ?? ''
+  const notesNo = notesKey?.match(/notesSlide(\d+)\.xml$/)?.[1] ?? ''
+  let ct = decodeXml(z.get('[Content_Types].xml'))
+  ct = ct.replace(/<Override\s+PartName="\/ppt\/slides\/slide\d+\.xml"\s+ContentType="[^"]*"\s*\/>/g, (m0) => m0.includes(`slide${slideNo}.xml`) ? m0 : '')
+  ct = ct.replace(/<Override\s+PartName="\/ppt\/notesSlides\/notesSlide\d+\.xml"\s+ContentType="[^"]*"\s*\/>/g, (m0) => (notesNo && m0.includes(`notesSlide${notesNo}.xml`)) ? m0 : '')
+
+  const entries = {}
+  for (const [name, data] of z) {
+    if (name === 'ppt/presentation.xml') { entries[name] = Buffer.from(pres, 'utf8'); continue }
+    if (name === 'ppt/_rels/presentation.xml.rels') { entries[name] = Buffer.from(presRels, 'utf8'); continue }
+    if (name === '[Content_Types].xml') { entries[name] = Buffer.from(ct, 'utf8'); continue }
+    if (name.startsWith('ppt/slides/')) {
+      if (name === slideKey || name === relsKey) entries[name] = data
+      continue
+    }
+    if (name.startsWith('ppt/notesSlides/')) {
+      if (notesKey && name === notesKey) entries[name] = data
+      continue
+    }
+    entries[name] = data
+  }
+  const outPath = out ?? source.replace(/\.pptx$/i, '-single.pptx')
+  await writeFile(outPath, zipWrite(entries))
+  return {
+    out: outPath, page,
+    layouts: [...z.keys()].filter((k) => k.startsWith('ppt/slideLayouts/')).length,
+    masters: [...z.keys()].filter((k) => k.startsWith('ppt/slideMasters/')).length,
+    entries: Object.keys(entries).length,
+  }
+}

package/lib/state.js

@@ -0,0 +1,88 @@
+/**
+ * ppt-studio 状态：会话级（路由/档位）+ 项目级（state.json）。
+ * 会话状态持久化到 ~/.dsh/ppt-studio/session-<id>.json，供 resume 恢复。
+ */
+import { readFile, writeFile, mkdir, access } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+
+const ROOT = join(homedir(), '.dsh', 'ppt-studio')
+export const SESSION_DIR = ROOT
+
+export const DEFAULT_SESSION = () => ({
+  routing: 'auto',            // auto | on | off（语义判断开关）
+  mode: 'auto',               // auto | free | mid | strict（协作模式）
+  fidelity: 'auto',           // auto | strict | free
+  review: 'points',           // none | points | every
+  quality: 'standard',        // quick | standard | audit
+  engine: 'auto',             // auto(=pptd 主引擎) | pptd | python-pptx（pptxgenjs 未实现，命令面明确拒绝）
+  quick: false,               // 快速生成模式（低 token 快交付；跳过视觉审阅/素材/定调）
+  template: null,             // 模板 id（内置或用户自建；/ppt template <id> 或 ppt_templates 选择）
+  pauseAfter: [],
+  workflowActive: false,
+  taskType: null,
+  deckDir: null,
+})
+
+const sessionPath = (sessionId) => join(ROOT, `session-${sanitize(sessionId)}.json`)
+
+export async function loadSession(sessionId) {
+  return (await loadSessionDiag(sessionId)).state
+}
+
+/** 会话状态 + **诊断**（2026-09-18 新增）。区分"没有文件"（正常，新会话）与"文件存在却坏了"（异常）。
+ *  两者原来都静默返回默认值，于是状态文件一旦损坏，`quality: 'audit'` 会**无声**变成 `standard`。 */
+export async function loadSessionDiag(sessionId) {
+  const p = sessionPath(sessionId)
+  if (!existsSync(p)) return { state: DEFAULT_SESSION(), error: null }
+  try {
+    return { state: { ...DEFAULT_SESSION(), ...JSON.parse(await readFile(p, 'utf8')) }, error: null }
+  } catch (e) {
+    return { state: DEFAULT_SESSION(), error: `会话状态文件读取/解析失败（${p}）：${String(e?.message ?? e)}` }
+  }
+}
+
+export async function saveSession(sessionId, state) {
+  await mkdir(ROOT, { recursive: true })
+  await writeFile(sessionPath(sessionId), JSON.stringify(state, null, 2))
+}
+
+const DEFAULT_PROJECT = () => ({
+  taskType: null,          // from-scratch | augment | edit | summarize | unknown
+  spec: {},
+  stage: null,             // s0|s1|s2|s3|s4|s5|s6|done
+  pages: {},               // page ref → status
+  pauseAfter: [],
+  reviews: [],
+  engine: null,
+  quality: 'standard',
+})
+
+export async function loadProject(deckDir) {
+  return (await loadProjectDiag(deckDir)).state
+}
+
+/** 项目状态 + **诊断**（2026-09-18 新增）。**为什么要区分**：文件不存在 = 正常（新工程，用默认）；
+ *  文件存在却读不了/解析失败 = 异常。原来两者都静默返回默认值 ⇒ `state.json` 一损坏，
+ *  `quality: 'audit'` 会**无声**降成 `standard`——最严档（禁 autoDeclare + 强制视觉审阅 + 导出回读断言）
+ *  被降级而用户毫不知情。这正是"严格性只升不降"与"诚实边界优于静默降级"两条原则要防的事。 */
+export async function loadProjectDiag(deckDir) {
+  const p = join(deckDir, 'state.json')
+  if (!existsSync(p)) return { state: DEFAULT_PROJECT(), error: null }
+  try {
+    return { state: { ...DEFAULT_PROJECT(), ...JSON.parse(await readFile(p, 'utf8')) }, error: null }
+  } catch (e) {
+    return { state: DEFAULT_PROJECT(), error: `项目状态文件读取/解析失败（${p}）：${String(e?.message ?? e)}` }
+  }
+}
+
+export async function saveProject(deckDir, state) {
+  await mkdir(deckDir, { recursive: true })
+  await writeFile(join(deckDir, 'state.json'), JSON.stringify(state, null, 2))
+}
+
+function sanitize(s) { return String(s).replace(/[^\w-]+/g, '_').slice(0, 64) }
+
+export async function fileExists(p) { return existsSync(p) }
+export { access }