@capyclaw/ppt-workbench 0.0.0-stage → 2.4.1

package/server/store/doc.mjs

@@ -0,0 +1,52 @@
+/** PPT 兼容层：标准会话信封 + PPT 的 deck 初始文档与标题同步。 */
+import {
+  applyAck as baseAck,
+  applyPush as basePush,
+  applyServer as baseServer,
+  applyShotRequest as baseShotRequest,
+  applyShotResult as baseShotResult,
+  applyState as baseState,
+  applyUi as baseUi,
+  createSessionState,
+  pendingOf,
+} from '@capyclaw/document-workbench/session'
+
+export const EMPTY_DECK = () => ({ title: '', slides: [] })
+
+export const EMPTY_DOC = () => createSessionState({ title: '' })
+
+export function applyPush(doc, cmds, title, now) {
+  return basePush(doc, cmds, title, now)
+}
+
+export function applyServer(doc, seq, applied, error, now) {
+  return baseServer(doc, seq, applied, error, {
+    now,
+    stateCompact: true,
+    onApplied: (next) => {
+      if (next.title && next.deck) next.deck.title = next.title
+    },
+  })
+}
+
+export function applyAck(doc, seq, applied, error, now) {
+  return baseAck(doc, seq, applied, error, now)
+}
+
+export function applyState(doc, deck, seq, now) {
+  return baseState(doc, deck, seq, { now, documentKey: 'deck' })
+}
+
+export function applyUi(doc, cmds, now) {
+  return baseUi(doc, cmds, now)
+}
+
+export function applyShotRequest(doc, now) {
+  return baseShotRequest(doc, now)
+}
+
+export function applyShotResult(doc, req, data, now) {
+  return baseShotResult(doc, req, data, now)
+}
+
+export { pendingOf }

package/server/store/index.mjs

@@ -0,0 +1,34 @@
+/**
+ * PPT 桥存储 facade：通用版本化会话来自 @capyclaw/document-workbench，
+ * 本文件只保留 deck 的初始文档、summary 与标题同步。
+ */
+import { DocumentSession, OWNER_TTL } from '@capyclaw/document-workbench/session'
+import { FileBridgeBackend } from './backends/file-backend.mjs'
+import { EMPTY_DOC } from './doc.mjs'
+
+export * from './sanitize.mjs'
+export { OWNER_TTL, FileBridgeBackend }
+
+export class BridgeStore extends DocumentSession {
+  constructor(fileOrOptions) {
+    let backend
+    if (typeof fileOrOptions === 'string') backend = new FileBridgeBackend(fileOrOptions)
+    else if (fileOrOptions && fileOrOptions.backend) backend = fileOrOptions.backend
+    else throw new Error('BridgeStore 需要 file 路径或 backend')
+
+    super({
+      backend,
+      initialDoc: EMPTY_DOC(),
+      documentKey: 'deck',
+      stateCompact: true,
+      summary: (doc) => ({
+        title: doc.deck && doc.deck.title ? doc.deck.title : '未命名',
+        slides: doc.deck && Array.isArray(doc.deck.slides) ? doc.deck.slides.length : 0,
+      }),
+      checkpointDocument: () => ({ title: '未命名', slides: [] }),
+      onApplied: (doc) => {
+        if (doc.title && doc.deck) doc.deck.title = doc.title
+      },
+    })
+  }
+}

package/server/store/journal.mjs

@@ -0,0 +1,9 @@
+/** journal：把事件写入 backend（失败不影响主流程）。 */
+
+export function appendJournal(backend, event) {
+  backend.appendJournal(event)
+}
+
+export function journalTail(backend, limit = 8) {
+  return backend.journalTail(limit)
+}

package/server/store/lease.mjs

@@ -0,0 +1,2 @@
+/** 兼容层：deck owner 租约的通用实现位于 @capyclaw/document-workbench/session。 */
+export { OWNER_TTL, claimOwner, ownerStatus, releaseOwner } from '@capyclaw/document-workbench/session'

package/server/store/sanitize.mjs

@@ -0,0 +1,32 @@
+/** 桥协议白名单：通用信封来自 @capyclaw/document-workbench，PPT 只需声明 deck 字段与上限。 */
+import { createSessionSanitizers } from '@capyclaw/document-workbench/session'
+
+export const MAX_CMDS = 100               // 单队指令条数上限
+export const MAX_TOTAL = 8 * 1024 * 1024  // 单队总量上限（字节）
+export const MAX_SHOT = 4 * 1024 * 1024   // 截图 dataURL 上限
+
+const sanitizers = createSessionSanitizers({
+  documentKey: 'deck',
+  maxCmds: MAX_CMDS,
+  maxTotal: MAX_TOTAL,
+  maxShot: MAX_SHOT,
+  maxTitle: 120,
+  maxError: 2000,
+  maxId: 64,
+})
+
+const {
+  sanitizeAck,
+  sanitizeClaim,
+  sanitizePush,
+  sanitizeShotResult,
+  sanitizeState: baseSanitizeState,
+} = sanitizers
+
+export { sanitizeAck, sanitizeClaim, sanitizePush, sanitizeShotResult }
+
+/** 兼容旧 API：返回 { deck, seq }；通用 bridge 会把它归一化为 value。 */
+export function sanitizeState(body) {
+  const data = baseSanitizeState(body)
+  return data ? { deck: data.value, seq: data.seq } : null
+}

package/server/store.mjs

@@ -0,0 +1,2 @@
+/** 兼容入口：桥存储已拆到 server/store/*。 */
+export * from './store/index.mjs'

package/server/tools/capabilities/apply.mjs

@@ -0,0 +1,33 @@
+/** 底层指令逃生口：一次提交任意 op 数组。 */
+import { okText } from '../domains/tooling.mjs'
+import { defineCapability, defineTool } from '../kernel/define.mjs'
+
+export const applyCapability = defineCapability({
+  id: 'apply',
+  title: '底层指令',
+  tags: ['advanced'],
+  requires: ['deck'],
+  features: ['deck.write'],
+  tools: [
+    defineTool({
+      name: 'ppt_apply',
+      description: '通用逃生口：一次提交任意底层指令数组（load / update-slide / add-element / set-background / theme / …），复杂组合动作用。',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          ops: { type: 'array', maxItems: 100, items: { type: 'object' }, description: '底层 op 数组（≤100）' },
+          title: { type: 'string', maxLength: 120, description: 'deck 标题（可选）' },
+        },
+        additionalProperties: false,
+      },
+      kind: 'write',
+      since: '1.0.0',
+      handler: async ({ ops, title }, ctx) => {
+        const list = Array.isArray(ops) ? ops : []
+        if (!list.length && !title) throw new Error('ops 为空且未提供 title：请提供操作或标题')
+        const r = await ctx.deck.write(list, title)
+        return okText(r, list.length ? `已应用 ${list.length} 条指令` : '已更新标题')
+      },
+    }),
+  ],
+})

package/server/tools/capabilities/audit.mjs

@@ -0,0 +1,24 @@
+/** 确定性 deck 审计能力。 */
+import { auditDeck } from '../../../core/audit.js'
+import { defineCapability, defineTool } from '../kernel/define.mjs'
+
+export const auditCapability = defineCapability({
+  id: 'audit',
+  title: '确定性审计',
+  tags: ['read', 'quality'],
+  requires: ['deck'],
+  features: ['deck.audit'],
+  tools: [
+    defineTool({
+      name: 'ppt_audit',
+      description: '确定性审计当前 deck：文字越界/溢出/重叠、同文案重复、文字隐形/被遮挡、有效背景对比度、重复版式、配色漂移、重复图片、页面密度。返回 pass/blocking；交付前或截图前调用，pass=false 不得说审计通过。',
+      inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+      kind: 'read',
+      since: '2.1.0',
+      handler: async (args, ctx) => {
+        const doc = await ctx.deck.read()
+        return { text: JSON.stringify(auditDeck(doc.deck), null, 2) }
+      },
+    }),
+  ],
+})

package/server/tools/capabilities/chart.mjs

@@ -0,0 +1,83 @@
+/** 图表能力：把数据直接变成 PPTist 原生图表（echarts 渲染，不再手绘形状拼图）。 */
+import { CHART_TYPES } from '../../../core/chart.js'
+import { clamp, okText } from '../domains/tooling.mjs'
+import { defineCapability, defineTool } from '../kernel/define.mjs'
+
+const chartDataDesc =
+  '数据，支持多种格式：{labels:[...], series:[[...]]} / {labels:[...], values:[...]} 单系列 / ' +
+  '{headers:[...], rows:[[...]]} 表格式（首列类目，其余列系列） / {items:[[name,value]...]} 饼图式'
+
+export const chartCapability = defineCapability({
+  id: 'chart',
+  title: '图表',
+  tags: ['write', 'data'],
+  requires: ['deck'],
+  features: ['deck.chart'],
+  tools: [
+    defineTool({
+      name: 'ppt_chart',
+      description:
+        '插入或更新图表（PPTist 原生 echarts 图表）。给定数据即可生成柱/条/折线/面积/饼/环/雷达/散点图，' +
+        '支持多种数据格式（labels+series、表格 rows、键值对 items）。带 element_id 时为更新已有图表。',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          slide: { type: 'integer', description: '0 起页号，默认 0' },
+          chart_type: { type: 'string', enum: CHART_TYPES, description: '图表类型，新增必填' },
+          data: { type: 'object', description: chartDataDesc },
+          element_id: { type: 'string', description: '更新模式：要更新的图表元素 id' },
+          options: {
+            type: 'object',
+            description: '渲染选项 {lineSmooth?:折线平滑, stack?:堆叠}',
+            properties: {
+              lineSmooth: { type: 'boolean' },
+              stack: { type: 'boolean' },
+            },
+            additionalProperties: false,
+          },
+          colors: { type: 'array', items: { type: 'string' }, description: '系列配色（缺省用幻灯片主题色）' },
+          text_color: { type: 'string', description: '图表文字颜色' },
+          left: { type: 'number' },
+          top: { type: 'number' },
+          width: { type: 'number' },
+          height: { type: 'number' },
+        },
+        required: ['slide'],
+        additionalProperties: false,
+      },
+      kind: 'write',
+      since: '2.2.0',
+      handler: async (args, ctx) => {
+        const i = clamp(Number(args.slide) | 0, 0, 999)
+        const p = args || {}
+        if (p.element_id) {
+          const props = {}
+          if (p.chart_type) props.chartType = p.chart_type
+          if (p.data != null) props.data = p.data
+          if (p.options != null) props.options = p.options
+          if (Array.isArray(p.colors)) props.colors = p.colors
+          if (p.text_color) props.textColor = p.text_color
+          for (const k of ['left', 'top', 'width', 'height']) {
+            if (p[k] != null) props[k] = p[k]
+          }
+          const r = await ctx.deck.write([{ op: 'update-chart', slide: i, elementId: String(p.element_id), props }])
+          return okText(r, `已更新图表 ${p.element_id}`)
+        }
+        if (!p.chart_type) throw new Error('新增图表需要 chart_type（' + CHART_TYPES.join('/') + '）')
+        if (p.data == null) throw new Error('新增图表需要 data（' + chartDataDesc + '）')
+        const element = {
+          chartType: p.chart_type,
+          data: p.data,
+          ...(p.options != null ? { options: p.options } : {}),
+          ...(Array.isArray(p.colors) ? { colors: p.colors } : {}),
+          ...(p.text_color ? { textColor: p.text_color } : {}),
+        }
+        for (const k of ['left', 'top', 'width', 'height']) {
+          if (p[k] != null) element[k] = p[k]
+        }
+        const r = await ctx.deck.write([{ op: 'add-chart', slide: i, element }])
+        return okText(r, `已在第 ${i} 页插入 ${p.chart_type} 图表`)
+      },
+    }),
+  ],
+})

package/server/tools/capabilities/compose.mjs

@@ -0,0 +1,97 @@
+/** 成稿编排能力：内置版式成稿（组合 core 引擎与 deck 端口）。 */
+import { buildDeck, buildSlide, PRESETS } from '../../../core/deck-layout.js'
+import { okText } from '../domains/tooling.mjs'
+import { defineCapability, defineTool } from '../kernel/define.mjs'
+
+export const composeCapability = defineCapability({
+  id: 'compose',
+  title: '成稿编排',
+  tags: ['recipe', 'layout'],
+  requires: ['deck'],
+  features: ['deck.compose'],
+  tools: [
+    defineTool({
+      name: 'ppt_deck',
+      description: '从大纲一次成稿：按版式（cover/section/bullets/two/stat/quote/end）+ 设计预设（clean/business/warm/tech）生成整套专业排版 deck，替换当前内容。默认简洁成稿首选（preset: clean）。',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          title: { type: 'string', maxLength: 40 },
+          preset: { type: 'string', enum: ['clean', 'business', 'warm', 'tech'] },
+          slides: {
+            type: 'array',
+            maxItems: 30,
+            items: {
+              type: 'object',
+              properties: {
+                layout: { type: 'string', enum: ['cover', 'section', 'bullets', 'two', 'stat', 'quote', 'end'] },
+                title: { type: 'string', maxLength: 40 },
+                subtitle: { type: 'string', maxLength: 80 },
+                kicker: { type: 'string', maxLength: 40 },
+                index: { type: 'integer' },
+                bullets: { type: 'array', maxItems: 8 },
+                left: { type: 'object' }, right: { type: 'object' },
+                stats: { type: 'array', maxItems: 4 },
+                quote: { type: 'string', maxLength: 300 }, author: { type: 'string', maxLength: 60 },
+                note: { type: 'string', maxLength: 300 }, foot: { type: 'string', maxLength: 100 },
+              },
+              required: ['layout'],
+            },
+          },
+        },
+        required: ['slides'],
+        additionalProperties: false,
+      },
+      kind: 'write',
+      since: '1.0.0',
+      handler: async ({ title, preset, slides }, ctx) => {
+        const deck = buildDeck({ title, preset, slides })
+        const r = await ctx.deck.write([{ op: 'load', deck }])
+        return okText(r, `已生成 ${deck.slides.length} 页「${deck.title}」（预设 ${preset || 'clean'}）`)
+      },
+    }),
+    defineTool({
+      name: 'ppt_page',
+      description: '逐页成稿：一次只追加/替换当前一页（同一套 clean 版式），适合长 deck 分批落盘；首屏用 replace:true，后续逐页追加。',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          layout: { type: 'string', enum: ['cover', 'section', 'bullets', 'two', 'stat', 'quote', 'end'] },
+          preset: { type: 'string', enum: ['clean', 'business', 'warm', 'tech'] },
+          deck_title: { type: 'string', maxLength: 40 },
+          position: { type: 'integer', description: '插入位置（0 起，缺省末尾）' },
+          replace: { type: 'boolean', description: 'true 时用这一页替换整个 deck（首屏用）' },
+          title: { type: 'string', maxLength: 40 },
+          subtitle: { type: 'string', maxLength: 80 },
+          kicker: { type: 'string', maxLength: 40 },
+          section_index: { type: 'integer', description: 'section 版式的章节序号' },
+          bullets: { type: 'array', maxItems: 8 },
+          left: { type: 'object' }, right: { type: 'object' },
+          stats: { type: 'array', maxItems: 4 },
+          quote: { type: 'string', maxLength: 300 }, author: { type: 'string', maxLength: 60 },
+          note: { type: 'string', maxLength: 300 }, foot: { type: 'string', maxLength: 100 },
+        },
+        required: ['layout'],
+        additionalProperties: false,
+      },
+      kind: 'write',
+      since: '2.3.0',
+      handler: async ({ layout, preset, deck_title, position, replace, section_index, ...page }, ctx) => {
+        const spec = { layout, ...page }
+        if (section_index != null) spec.index = section_index
+        const presetName = PRESETS[preset] ? preset : 'clean'
+        const P = PRESETS[presetName]
+        const slide = buildSlide(P, spec, 0)
+        const theme = { themeColors: [P.accent, P.accent2, P.fg], fontColor: P.fg, backgroundColor: P.bg }
+        if (replace) {
+          const r = await ctx.deck.write([{ op: 'load', deck: { title: deck_title || page.title || '演示文稿', slides: [slide], theme } }])
+          return okText(r, `已用 1 页替换 deck「${deck_title || page.title || '演示文稿'}」`)
+        }
+        const cmd = { op: 'add-slide', slide }
+        if (position != null) cmd.index = Number(position) | 0
+        const r = await ctx.deck.write([cmd])
+        return okText(r, `已追加 1 页「${page.title || layout}」`)
+      },
+    }),
+  ],
+})

package/server/tools/capabilities/contract.mjs

@@ -0,0 +1,34 @@
+/** 契约探测能力：版本、工具清单、能力清单与运行时状态。 */
+import { defineCapability, defineTool } from '../kernel/define.mjs'
+
+export const contractCapability = defineCapability({
+  id: 'contract',
+  title: '契约探测',
+  tags: ['meta'],
+  requires: ['status', 'contract'],
+  features: ['deck.contract'],
+  tools: [
+    defineTool({
+      name: 'ppt_capabilities',
+      description: '返回工作台契约版本、工具清单、能力清单、能力标签与编辑器地址。skill 加载后先调用一次；工具缺失或 major 版本不一致时停止并提示升级。',
+      inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+      kind: 'read',
+      since: '2.0.0',
+      handler: async (args, ctx) => {
+        let editorUrl = ''
+        try { editorUrl = new URL(ctx.status.baseUrl).origin + '/' } catch { /* 保持空字符串 */ }
+        let runtime = { editorConnected: false, hasDeck: false, slides: 0, seq: 0 }
+        try {
+          const status = await ctx.status.get()
+          runtime = {
+            editorConnected: !!status.owner,
+            hasDeck: !!status.has_deck,
+            slides: Number(status.slides || 0),
+            seq: Number(status.seq || 0),
+          }
+        } catch { /* relay 不可用时仍返回静态契约 */ }
+        return { text: JSON.stringify(ctx.contract.report(editorUrl, runtime), null, 2) }
+      },
+    }),
+  ],
+})

package/server/tools/capabilities/deck.mjs

@@ -0,0 +1,27 @@
+/** 读 deck 能力。 */
+import { defineCapability, defineTool } from '../kernel/define.mjs'
+
+export const deckCapability = defineCapability({
+  id: 'deck',
+  title: '读取演示文稿',
+  tags: ['read'],
+  requires: ['deck'],
+  features: ['deck.read'],
+  tools: [
+    defineTool({
+      name: 'ppt_get_deck',
+      description: '读当前演示文稿：标题、每页背景/元素。需要精确定位（页号/元素 id）时调用；改背景/加页/改首个文本不要先读。',
+      inputSchema: {
+        type: 'object',
+        properties: { detailed: { type: 'boolean', description: '元素几何/颜色等细节（缺省只给摘要）' } },
+        additionalProperties: false,
+      },
+      kind: 'read',
+      since: '1.0.0',
+      handler: async ({ detailed }, ctx) => {
+        const doc = await ctx.deck.read()
+        return { text: ctx.deck.summarize(doc.deck, !!detailed) }
+      },
+    }),
+  ],
+})

package/server/tools/capabilities/element.mjs

@@ -0,0 +1,67 @@
+/** 元素能力：加/改/删元素；图片插入委托给 media.insertImage。 */
+import { resolveColor } from '../domains/color.mjs'
+import { clamp, okText } from '../domains/tooling.mjs'
+import { defineCapability, defineTool } from '../kernel/define.mjs'
+
+export const elementCapability = defineCapability({
+  id: 'element',
+  title: '元素编辑',
+  tags: ['write', 'layout'],
+  requires: ['deck', 'media'],
+  dependsOn: ['image'],
+  features: ['deck.write'],
+  tools: [
+    defineTool({
+      name: 'ppt_element',
+      description: '元素级编辑：add 加文本/形状/图片，update 改位置/尺寸/旋转/填充/文字样式，remove 删除。插入图片走 ppt_image 的同一实现。',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          action: { type: 'string', enum: ['add', 'update', 'remove'] },
+          slide: { type: 'integer', description: '0 起页号' },
+          element_id: { type: 'string' },
+          element: {
+            type: 'object',
+            description: "add 用：{type:'text'|'shape'|'image', text?/content?, src?(image), fill?, left?, top?, width?, height?, fontSize?, color?}",
+          },
+          props: {
+            type: 'object',
+            description: 'update 用：{left?,top?,width?,height?,rotate?,opacity?,fill?,src?,text?,fontSize?,color?,bold?,align?}',
+          },
+        },
+        required: ['action', 'slide'],
+        additionalProperties: false,
+      },
+      kind: 'write',
+      since: '1.0.0',
+      handler: async ({ action, slide, element_id, element, props }, ctx) => {
+        const i = clamp(Number(slide) | 0, 0, 999)
+        if (action === 'add') {
+          const el = element || {}
+          if (el.type === 'image') {
+            if (!ctx.media) throw new Error('插入图片需要启用 image 能力')
+            return ctx.media.insertImage({ slide: i, ...el })
+          }
+          const r = await ctx.deck.write([{ op: 'add-element', slide: i, element: el }])
+          return okText(r, `已在第 ${i} 页加元素`)
+        }
+        if (!element_id) throw new Error('update/remove 需要 element_id')
+        if (action === 'remove') {
+          const r = await ctx.deck.write([{ op: 'remove-element', slide: i, elementId: String(element_id) }])
+          return okText(r, `已删除元素 ${element_id}`)
+        }
+        if (action === 'update') {
+          const cleaned = {}
+          const p = props || {}
+          ;['left', 'top', 'width', 'height', 'rotate', 'opacity', 'fill', 'src', 'text', 'html', 'fontSize', 'color', 'bold', 'align', 'defaultColor'].forEach(k => {
+            if (p[k] != null) cleaned[k] = p[k]
+          })
+          if (cleaned.color) cleaned.color = resolveColor(cleaned.color)
+          const r = await ctx.deck.write([{ op: 'set-element', slide: i, elementId: String(element_id), props: cleaned }])
+          return okText(r, `已更新元素 ${element_id}`)
+        }
+        throw new Error('未知 action: ' + action)
+      },
+    }),
+  ],
+})

package/server/tools/capabilities/export.mjs

@@ -0,0 +1,95 @@
+/** PPTX 导出：把当前 deck 渲染成本机 .pptx 文件。 */
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { defineCapability, defineTool } from '../kernel/define.mjs'
+import { renderDeckToPptx, safeFileName } from '../domains/pptx-export.mjs'
+
+function outputPath({ filePath, fileName, title }) {
+  const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\..+$/, '')
+  const base = safeFileName(fileName || title || 'presentation')
+  const defaultName = `${base}${stamp ? '-' + stamp : ''}.pptx`
+  if (!filePath) return path.join(os.tmpdir(), 'ppt-exports', defaultName)
+
+  const resolved = path.resolve(String(filePath))
+  if (/\.pptx$/i.test(resolved)) return resolved
+  return path.join(resolved, defaultName)
+}
+
+export const exportCapability = defineCapability({
+  id: 'export',
+  title: '导出 PPTX',
+  tags: ['write', 'file'],
+  requires: ['deck', 'status'],
+  features: ['deck.export'],
+  tools: [
+    defineTool({
+      name: 'ppt_export_pptx',
+      description: '把当前 deck 导出为本机 .pptx 文件（pptxgenjs）。支持文字/形状/图片/线条/表格/图表/背景/备注；自定义 SVG 路径用矩形近似，LaTeX/音视频跳过。返回文件绝对路径与降级项。',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          path: { type: 'string', description: '输出 .pptx 路径，或已存在的目录；缺省写到系统临时目录 ppt-exports/' },
+          file_name: { type: 'string', maxLength: 160, description: '文件名（可省略 .pptx）；path 为目录/缺省时使用' },
+          slide_indices: {
+            type: 'array',
+            items: { type: 'integer', minimum: 0 },
+            maxItems: 200,
+            description: '只导出指定页（0 基）；缺省导出全部',
+          },
+          include_notes: { type: 'boolean', description: '是否写入演讲者备注（默认 true）' },
+          overwrite: { type: 'boolean', description: '目标已存在时是否覆盖；保存回原文件必须显式 true' },
+          backup: { type: 'boolean', description: '覆盖前是否备份为 <name>.bak-<时间>.pptx（默认 true）' },
+        },
+        additionalProperties: false,
+      },
+      kind: 'write',
+      since: '2.4.0',
+      handler: async ({ path: filePath, file_name, slide_indices, include_notes, overwrite, backup }, ctx) => {
+        const doc = await ctx.deck.read()
+        const deck = doc && doc.deck
+        if (!deck || !Array.isArray(deck.slides) || !deck.slides.length) {
+          throw new Error('当前 deck 没有幻灯片，无法导出 PPTX')
+        }
+
+        let exportDeck = deck
+        if (Array.isArray(slide_indices) && slide_indices.length) {
+          const indices = [...new Set(slide_indices.map((value) => Number(value)))]
+          const bad = indices.find((index) => !Number.isInteger(index) || index < 0 || index >= deck.slides.length)
+          if (bad !== undefined) throw new Error(`页号越界：${bad}（共 ${deck.slides.length} 页）`)
+          exportDeck = { ...deck, slides: indices.map((index) => deck.slides[index]) }
+        }
+
+        const target = outputPath({ filePath, fileName: file_name, title: deck.title })
+        if (fs.existsSync(target) && overwrite !== true) {
+          throw new Error('目标文件已存在：保存回原文件请显式传 overwrite:true；否则请换 path 或 file_name 另存')
+        }
+        const { buffer, stats } = await renderDeckToPptx(exportDeck, {
+          assetBase: ctx.status.baseUrl,
+          includeNotes: include_notes !== false,
+        })
+        fs.mkdirSync(path.dirname(target), { recursive: true })
+        let backupPath = ''
+        if (fs.existsSync(target) && backup !== false) {
+          const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\..+$/, '')
+          backupPath = target.replace(/\.pptx$/i, `.bak-${stamp}.pptx`)
+          fs.copyFileSync(target, backupPath)
+        }
+        fs.writeFileSync(target, buffer)
+
+        return {
+          text: JSON.stringify({
+            ok: true,
+            path: target,
+            backup: backupPath,
+            bytes: buffer.length,
+            title: deck.title || '',
+            slides: exportDeck.slides.length,
+            stats,
+            note: '导出完成。若 stats.skipped/approximated 非 0，说明有元素被跳过或近似，详见 stats.warnings。',
+          }, null, 2),
+        }
+      },
+    }),
+  ],
+})