@capyclaw/ppt-workbench 0.0.0-stage → 2.4.1

package/server/tools/capabilities/formula.mjs

@@ -0,0 +1,72 @@
+/** 公式能力：TeX 数学公式 → PPTist 原生 latex 元素（hfmath stroke 渲染，与编辑器描边渲染同款）。 */
+import { renderFormula } from '../../../core/formula.js'
+import { clamp, okText } from '../domains/tooling.mjs'
+import { defineCapability, defineTool } from '../kernel/define.mjs'
+
+export const formulaCapability = defineCapability({
+  id: 'formula',
+  title: '数学公式',
+  tags: ['write', 'content'],
+  requires: ['deck'],
+  features: ['deck.formula'],
+  tools: [
+    defineTool({
+      name: 'ppt_formula',
+      description:
+        '插入或更新数学公式（TeX 语法，PPTist 原生 latex 元素，手写风描边渲染）。' +
+        '支持分式 \\frac{}{}、上下标 ^ _、根号 \\sqrt、求和积分 \\sum \\int、希腊字母、矩阵等；' +
+        '渲染由内置 hfmath 引擎完成。带 element_id 时为更新（重新渲染并替换）。',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          slide: { type: 'integer', description: '0 起页号，默认 0' },
+          latex: { type: 'string', description: 'TeX 公式，如 E=mc^2 / \\frac{a}{b} / \\int_0^1 x^2 dx' },
+          element_id: { type: 'string', description: '更新模式：要更新的公式元素 id' },
+          color: { type: 'string', description: '笔画颜色，默认 #333333' },
+          stroke_width: { type: 'number', description: '笔画宽度，默认 2' },
+          left: { type: 'number' },
+          top: { type: 'number' },
+          width: { type: 'number', description: '默认按渲染原始尺寸' },
+          height: { type: 'number', description: '默认按渲染原始尺寸（fixedRatio 锁比例）' },
+        },
+        required: ['slide', 'latex'],
+        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) {
+          /* 更新：重新渲染新公式，替换 path/viewBox/latex（几何/颜色按参数顺带改）。 */
+          const rendered = renderFormula(p.latex)
+          const props = {
+            latex: p.latex,
+            path: rendered.path,
+            viewBox: rendered.viewBox,
+          }
+          if (p.width != null) props.width = p.width
+          if (p.height != null) props.height = p.height
+          if (p.color) props.color = p.color
+          if (p.stroke_width != null) props.strokeWidth = p.stroke_width
+          for (const k of ['left', 'top']) {
+            if (p[k] != null) props[k] = p[k]
+          }
+          const r = await ctx.deck.write([{ op: 'set-element', slide: i, elementId: String(p.element_id), props }])
+          return okText(r, `已更新公式 ${p.element_id}`)
+        }
+        const element = {
+          type: 'latex',
+          latex: p.latex,
+          ...(p.color ? { color: p.color } : {}),
+          ...(p.stroke_width != null ? { strokeWidth: p.stroke_width } : {}),
+        }
+        for (const k of ['left', 'top', 'width', 'height']) {
+          if (p[k] != null) element[k] = p[k]
+        }
+        const r = await ctx.deck.write([{ op: 'add-element', slide: i, element }])
+        return okText(r, `已在第 ${i} 页插入公式`)
+      },
+    }),
+  ],
+})

package/server/tools/capabilities/history.mjs

@@ -0,0 +1,29 @@
+/** 撤销/重做能力。 */
+import { okText } from '../domains/tooling.mjs'
+import { defineCapability, defineTool } from '../kernel/define.mjs'
+
+export const historyCapability = defineCapability({
+  id: 'history',
+  title: '撤销重做',
+  tags: ['control'],
+  requires: ['deck'],
+  features: ['deck.undo'],
+  tools: [
+    defineTool({
+      name: 'ppt_history',
+      description: '撤销/重做。',
+      inputSchema: {
+        type: 'object',
+        properties: { action: { type: 'string', enum: ['undo', 'redo'] } },
+        required: ['action'],
+        additionalProperties: false,
+      },
+      kind: 'control',
+      since: '1.0.0',
+      handler: async ({ action }, ctx) => {
+        const r = await ctx.deck.write([{ op: String(action) }])
+        return okText(r, action === 'undo' ? '已撤销' : '已重做')
+      },
+    }),
+  ],
+})

package/server/tools/capabilities/image.mjs

@@ -0,0 +1,152 @@
+/** 图片能力：图片先进入对象仓库，deck 只保存 /assets/<sha256> 引用。 */
+import fs from 'node:fs'
+import { imageMime, imageSize, resolveAttachmentFile } from '../domains/image.mjs'
+import { IMAGE_MAX_BYTES, describeImageFailure, downloadImage } from '../domains/remote-image.mjs'
+import { clamp, okText } from '../domains/tooling.mjs'
+import { defineCapability, defineTool } from '../kernel/define.mjs'
+
+const MAX_MB = Math.round(IMAGE_MAX_BYTES / 1024 / 1024)
+const TOO_LARGE_HINT = `图片过大（>${MAX_MB}MB），请先压缩后再插入`
+
+function readLocalImage(file) {
+  const stat = fs.statSync(file)
+  if (!stat.isFile()) throw new Error('图片路径不是文件：' + file)
+  if (stat.size > IMAGE_MAX_BYTES) throw new Error(TOO_LARGE_HINT)
+  return fs.readFileSync(file)
+}
+
+async function insertImage(ctx, spec) {
+  const { slide, attachment_id, attachmentId, path: filePath, src, left, top, width, height } = spec || {}
+  const i = clamp(Number(slide == null ? 0 : slide) | 0, 0, 999)
+  const aid = attachment_id || attachmentId
+  let buf = null
+  let assetUrl = ''
+  let dataUrl = ''
+  let natW = 0, natH = 0
+  if (aid) {
+    const p = resolveAttachmentFile(aid)
+    buf = readLocalImage(p)
+  } else if (filePath) {
+    if (!fs.existsSync(String(filePath))) throw new Error('图片文件不存在：' + filePath)
+    buf = readLocalImage(String(filePath))
+  } else if (src) {
+    const s = String(src)
+    if (/^https?:/i.test(s)) {
+      if (/\/assets\/[a-f0-9]{64}$/i.test(s)) {
+        assetUrl = s
+      } else {
+        /* 远程图不能直接把 URL 丢给编辑器：先下载并验证是图片，再进入对象仓库。 */
+        try {
+          const fetched = await downloadImage(s)
+          buf = fetched.buf
+        } catch (error) {
+          throw new Error(describeImageFailure(error, s))
+        }
+      }
+    } else if (/^data:image\//i.test(s)) {
+      const comma = s.indexOf(',')
+      if (comma < 0) throw new Error('data URL 不合法')
+      /* 先按 base64 长度粗判，避免解码超大字符串造成瞬时内存峰值。 */
+      if (s.length > Math.ceil(IMAGE_MAX_BYTES * 4 / 3) + 128) throw new Error(TOO_LARGE_HINT)
+      buf = Buffer.from(s.slice(comma + 1), 'base64')
+      if (buf.length > IMAGE_MAX_BYTES) throw new Error(TOO_LARGE_HINT)
+    } else if (/^\/assets\/[a-f0-9]{64}$/i.test(s)) {
+      assetUrl = s
+    } else if (fs.existsSync(s)) {
+      buf = readLocalImage(s)
+    } else {
+      throw new Error('src 既不是 http(s)/data URL，也不是存在的文件：' + s.slice(0, 120))
+    }
+  } else {
+    throw new Error('ppt_image 需要 attachment_id / path / src 之一')
+  }
+  if (buf) {
+    if (buf.length > IMAGE_MAX_BYTES) throw new Error(TOO_LARGE_HINT)
+    const mime = imageMime(buf)
+    if (!mime) throw new Error('不支持的图片格式（仅 PNG/JPEG/GIF/WebP）')
+    if (process.env.PPT_ASSET_STORE === '1') {
+      const asset = await ctx.assets.put(buf, mime)
+      assetUrl = asset.url
+    } else {
+      dataUrl = `data:${mime};base64,${buf.toString('base64')}`
+    }
+    const sz = imageSize(buf)
+    if (sz) { natW = sz[0]; natH = sz[1] }
+  }
+  if (!assetUrl && !dataUrl) throw new Error('图片未能写入对象仓库')
+  const SW = 1000, SH = 562.5
+  let w = width != null ? Number(width) : null
+  let h = height != null ? Number(height) : null
+  if ((w == null || h == null) && natW && natH) {
+    if (w == null && h == null) {
+      const scale = Math.min(SW / natW, SH / natH)
+      w = natW * scale; h = natH * scale
+    } else if (w == null) {
+      w = h * natW / natH
+    } else {
+      h = w * natH / natW
+    }
+  }
+  if (w == null) w = SW
+  if (h == null) h = SH
+  const l = left != null ? Number(left) : Math.round((SW - w) / 2)
+  const t = top != null ? Number(top) : Math.round((SH - h) / 2)
+  const element = {
+    type: 'image', src: assetUrl || dataUrl,
+    left: l, top: t, width: Math.round(w), height: Math.round(h),
+  }
+  const beforeDoc = await ctx.deck.read()
+  const beforeSlide = ((beforeDoc.deck && beforeDoc.deck.slides) || [])[i] || {}
+  const beforeIds = new Set((beforeSlide.elements || []).filter(e => e.type === 'image').map(e => e.id))
+  const r = await ctx.deck.write([{ op: 'add-element', slide: i, element }])
+  if (!r.ok) return okText(r, '图片插入失败')
+  const afterDoc = await ctx.deck.read()
+  const afterSlide = ((afterDoc.deck && afterDoc.deck.slides) || [])[i] || {}
+  const newImg = (afterSlide.elements || []).find(e => e.type === 'image' && !beforeIds.has(e.id))
+  if (!newImg) {
+    throw new Error('图片未真正插入：deck 中目标页没有新增 image 元素。最常见原因是编辑器还是旧 bundle（不支持 image），请按 F5 刷新桌面后重试；不要重复插入。')
+  }
+  const imgSrc = String(newImg.src || '')
+  if (!/^\/assets\/[a-f0-9]{64}$/i.test(imgSrc) && !/^data:image\//i.test(imgSrc) && !/^https?:/i.test(imgSrc)) {
+    throw new Error('图片元素已创建但 src 无效，请重试或刷新编辑器。')
+  }
+  const nat = natW && natH ? `${natW}×${natH}` : '图片'
+  if (assetUrl) {
+    const assetId = assetUrl.split('/').pop()
+    return { text: `已存入对象仓库并插入：第 ${i} 页新增图片 id=${newImg.id}（${nat} → ${Math.round(newImg.width)}×${Math.round(newImg.height)}，asset=${assetId}）` }
+  }
+  return { text: `已插入并校验：第 ${i} 页新增图片 id=${newImg.id}（${nat} → ${Math.round(newImg.width)}×${Math.round(newImg.height)}）` }
+}
+
+export const imageCapability = defineCapability({
+  id: 'image',
+  title: '图片',
+  tags: ['write', 'media'],
+  requires: ['deck', 'assets'],
+  provides: { media: { insertImage } },
+  features: ['deck.image'],
+  tools: [
+    defineTool({
+      name: 'ppt_image',
+      description: '插入图片（一次完成，图片先写入对象仓库，deck 只存 /assets/<sha256> 引用）：attachment_id 取聊天图片附件的 sha256 id；也支持 path/src。src 走远程下载时带浏览器头、25s 超时、自动重试一次，上限 6MB。失败会返回 [错误码]：HOST_BLOCKED / HTTP_403 / TIMEOUT / TOO_LARGE 等——永久性失败不要重试同一链接或域名，改换来源或先用本地 path 下载。不要用 shell 找图，不要截图验证。',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          slide: { type: 'integer', description: '0 起页号，缺省 0（封面）' },
+          attachment_id: { type: 'string', description: '聊天图片附件的 attachmentId（sha256:…）' },
+          attachmentId: { type: 'string', description: 'attachment_id 的兼容别名' },
+          path: { type: 'string', description: '本机图片路径（兼容旧用法）' },
+          src: { type: 'string', description: 'http(s) 或 data URL' },
+          left: { type: 'number' },
+          top: { type: 'number' },
+          width: { type: 'number' },
+          height: { type: 'number' },
+        },
+        additionalProperties: false,
+      },
+      kind: 'write',
+      since: '1.0.0',
+      handler: (args, ctx) => insertImage(ctx, args),
+    }),
+  ],
+})

package/server/tools/capabilities/imagesearch.mjs

@@ -0,0 +1,152 @@
+/** 图片检索能力：搜索 + 预检，返回确认可下载的候选直链；下载/入库/插图由 ppt_image 负责。 */
+import { IMAGE_UA, probeImage } from '../domains/remote-image.mjs'
+import { defineCapability, defineTool } from '../kernel/define.mjs'
+
+const BING = 'https://cn.bing.com/images/async'
+const UA = IMAGE_UA
+const MIN_WIDTH = 480
+const CACHE_TTL_MS = 10 * 60 * 1000
+/* 全局预算：一个 read 工具不该拖到十几秒。
+ * 2026-11-02 实测 Bing 图片搜索常态 0.2~0.5s，偶发 7s+ 抖动，
+ * 所以搜索单独给 8s（沿用原值，不因预检而收紧），预检在剩余预算里跑，
+ * 整轮 12s 封顶。预算耗尽就返回已拿到的结果，不再补测。 */
+const TOTAL_BUDGET_MS = 12000
+const SEARCH_TIMEOUT_MS = 8000
+const PROBE_CONCURRENCY = 9
+const PROBE_TIMEOUT_MS = 3000
+const PROBE_MAX_RATIO = 2
+const cache = new Map()
+
+const decode = (value) => String(value || '')
+  .replace(/"/g, '"')
+  .replace(/&/g, '&')
+  .replace(/'/g, "'")
+  .replace(/&lt;/g, '<')
+  .replace(/&gt;/g, '>')
+
+/** 从 Bing 图片搜索 HTML 中提取 murl/purl/t 宽高。 */
+export function parseBingImages(html, limit = 12) {
+  const out = []
+  const seen = new Set()
+  for (const match of String(html || '').matchAll(/m="(\{&quot;[\s\S]*?)"/g)) {
+    let meta
+    try { meta = JSON.parse(decode(match[1])) } catch { continue }
+    const url = String(meta.murl || '')
+    if (!/^https?:\/\//i.test(url) || seen.has(url)) continue
+    seen.add(url)
+    out.push({
+      title: String(meta.t || '').replace(/\s+/g, ' ').trim().slice(0, 80),
+      page: String(meta.purl || ''),
+      url,
+      width: Number(meta.w) || 0,
+      height: Number(meta.h) || 0,
+    })
+    if (out.length >= limit) break
+  }
+  return out
+}
+
+async function searchBing(query, count, deadline) {
+  const url = `${BING}?q=${encodeURIComponent(query)}&first=1&count=${Math.max(count * 3, 24)}&mkt=zh-CN&qft=+filterui:photo-photo`
+  const budget = Math.min(SEARCH_TIMEOUT_MS, Math.max(1000, deadline - Date.now()))
+  const res = await fetch(url, {
+    signal: AbortSignal.timeout(budget),
+    headers: { 'user-agent': UA, 'accept-language': 'zh-CN,zh;q=0.9,en;q=0.8' },
+  })
+  if (!res.ok) throw new Error(`图片搜索 HTTP ${res.status}`)
+  return parseBingImages(await res.text(), count)
+}
+
+/**
+ * 并发预检，凑够 want 条就停。
+ * 只淘汰"确定的坏链"（403/404/不是图片/超大）；预检超时或网络抖动归入
+ * unverified——下载阶段预算长得多，不能因为探测慢就丢掉可能的好图。
+ * 返回顺序：验证通过的在前，未验证的兜底在后。
+ */
+async function filterDownloadable(items, want, deadline) {
+  const verified = []
+  const unverified = []
+  const rejected = []
+  const pool = items.slice(0, Math.min(items.length, want * PROBE_MAX_RATIO))
+  let cursor = 0
+  const worker = async () => {
+    while (cursor < pool.length && verified.length < want && Date.now() < deadline) {
+      const item = pool[cursor++]
+      const probe = await probeImage(item.url, { timeoutMs: PROBE_TIMEOUT_MS, deadline })
+      if (probe.ok) verified.push(item)
+      else if (probe.permanent) rejected.push({ url: item.url, code: probe.code, permanent: true })
+      else unverified.push(item)
+    }
+  }
+  const lanes = Math.min(PROBE_CONCURRENCY, pool.length)
+  await Promise.all(Array.from({ length: lanes }, worker))
+  return {
+    candidates: [...verified, ...unverified].slice(0, want),
+    verifiedCount: Math.min(verified.length, want),
+    verified: new Set(verified),
+    rejected,
+  }
+}
+
+export const imagesearchCapability = defineCapability({
+  id: 'imagesearch',
+  title: '图片检索',
+  tags: ['read'],
+  features: ['media.search'],
+  tools: [
+    defineTool({
+      name: 'ppt_images',
+      description: '图片搜索：返回已预检可下载的候选直链（不下载正文，整轮 12s 内）。选中后直接用 ppt_image { src: url, slide } 插入；返回的候选基本不会 403/超限，若仍失败说明网络波动，换下一个候选即可。',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          query: { type: 'string', maxLength: 120, description: '中文或英文图片搜索词' },
+          count: { type: 'integer', minimum: 1, maximum: 12, description: '需要的候选数量，缺省 6' },
+          min_width: { type: 'integer', description: '最小宽度像素，缺省 480' },
+        },
+        required: ['query'],
+        additionalProperties: false,
+      },
+      kind: 'read',
+      since: '2.3.0',
+      handler: async ({ query, count, min_width }) => {
+        const want = Math.min(12, Math.max(1, Number(count) || 6))
+        const floor = Math.max(0, Number(min_width) || MIN_WIDTH)
+        const cacheKey = `${query}|${want}|${floor}`
+        const hit = cache.get(cacheKey)
+        if (hit && Date.now() - hit.at < CACHE_TTL_MS) return { text: hit.text }
+
+        const deadline = Date.now() + TOTAL_BUDGET_MS
+        const found = (await searchBing(query, want * 3, deadline)).filter((item) => !item.width || item.width >= floor)
+        if (!found.length) throw new Error(`没有找到图片（${query}）`)
+        const { candidates, verifiedCount, verified, rejected } = await filterDownloadable(found, want, deadline)
+        if (!candidates.length) {
+          const codes = [...new Set(rejected.map((r) => r.code))].slice(0, 3).join('/') || '未知'
+          throw new Error(`搜到 ${found.length} 条但全部不可下载（${codes}）：请换搜索词，或改用本地图片路径`)
+        }
+        const results = candidates.map((item) => {
+          const entry = {
+            title: item.title,
+            page: item.page,
+            url: item.url,
+            width: item.width,
+            height: item.height,
+          }
+          if (!verified.has(item)) entry.verified = false
+          return entry
+        })
+        const text = JSON.stringify({
+          query,
+          count: results.length,
+          verified: verifiedCount,
+          images: results,
+          note: verifiedCount === results.length
+            ? '候选均已预检可下载；直接用 ppt_image { src: url, slide } 插入，不要换 URL 试探'
+            : '前 ' + verifiedCount + ' 条已预检可下载，优先用它们；verified:false 的仅预检超时，下载可能较慢。直接用 ppt_image { src: url, slide } 插入。',
+        }, null, 2)
+        cache.set(cacheKey, { at: Date.now(), text })
+        return { text }
+      },
+    }),
+  ],
+})

package/server/tools/capabilities/import.mjs

@@ -0,0 +1,180 @@
+/** PPTX 导入：把本机文件交给编辑器内置的 PPTist 导入器，返回导入摘要。 */
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import { defineCapability, defineTool } from '../kernel/define.mjs'
+
+const MAX_BYTES = 128 * 1024 * 1024
+const DEFAULT_WAIT_MS = 180_000
+const MAX_WAIT_MS = 300_000
+const RESULT_URL = '/api/desktop/works/ppt-bridge/import-result'
+const PPTX_EXT = /\.pptx$/i
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+function readBytes({ filePath, data }) {
+  if (filePath && data) throw new Error('path 与 data 只能二选一')
+  if (!filePath && !data) throw new Error('请提供 path（本机 .pptx 路径）或 data（base64）')
+
+  if (filePath) {
+    const abs = path.resolve(String(filePath))
+    let stat
+    try {
+      stat = fs.statSync(abs)
+    } catch {
+      throw new Error(`找不到文件：${abs}`)
+    }
+    if (!stat.isFile()) throw new Error(`不是文件：${abs}`)
+    if (!PPTX_EXT.test(abs)) throw new Error('只支持 .pptx（OOXML）文件；.ppt 请先用 PowerPoint 另存为 .pptx')
+    if (stat.size > MAX_BYTES) throw new Error(`文件过大：${Math.round(stat.size / 1024 / 1024)}MB（上限 ${MAX_BYTES / 1024 / 1024}MB）`)
+    return { bytes: fs.readFileSync(abs), name: path.basename(abs), path: abs }
+  }
+
+  const bytes = Buffer.from(String(data), 'base64')
+  if (!bytes.length) throw new Error('data 不是有效的 base64 内容')
+  if (bytes.length > MAX_BYTES) throw new Error(`文件过大：${Math.round(bytes.length / 1024 / 1024)}MB（上限 ${MAX_BYTES / 1024 / 1024}MB）`)
+  return { bytes, name: 'import.pptx', path: '' }
+}
+
+function assertPptx(bytes) {
+  if (bytes.length < 4 || bytes[0] !== 0x50 || bytes[1] !== 0x4b) {
+    throw new Error('不是有效的 PPTX 文件（缺少 ZIP/OOXML 头）')
+  }
+}
+
+function compactDeck(deck) {
+  const slides = Array.isArray(deck?.slides) ? deck.slides : []
+  return {
+    title: deck?.title || '',
+    slides: slides.length,
+    elements: slides.reduce((sum, slide) => sum + (Array.isArray(slide.elements) ? slide.elements.length : 0), 0),
+    perSlide: slides.map((slide, index) => ({
+      index,
+      elements: Array.isArray(slide.elements) ? slide.elements.length : 0,
+      types: Array.from(new Set((slide.elements || []).map((el) => el.type).filter(Boolean))),
+    })),
+  }
+}
+
+async function waitForMirror(ctx, summary, timeoutMs = 8000) {
+  const wantSlides = Number(summary?.import?.final ?? summary?.slideCount ?? 0)
+  const wantTitle = String(summary?.title || '')
+  const deadline = Date.now() + timeoutMs
+  let doc = await ctx.deck.read()
+  while (Date.now() < deadline) {
+    const deck = doc?.deck || {}
+    const slides = Array.isArray(deck.slides) ? deck.slides.length : 0
+    const titleOk = !wantTitle || String(deck.title || '') === wantTitle
+    if ((!wantSlides || slides === wantSlides) && titleOk) return { doc, synced: true }
+    await sleep(150)
+    doc = await ctx.deck.read()
+  }
+  return { doc, synced: false }
+}
+
+export const importCapability = defineCapability({
+  id: 'import',
+  title: '导入 PPTX',
+  tags: ['write', 'file'],
+  requires: ['deck', 'editor', 'importer'],
+  features: ['deck.import'],
+  tools: [
+    defineTool({
+      name: 'ppt_import_pptx',
+      description: '打开本机 .pptx：上传给右侧 PPTist 编辑器，用其原生导入器转换成可编辑 deck。导入后返回标题/页数/每页元素摘要；动画、母版、SmartArt、复杂图表等可能丢失。',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          path: { type: 'string', description: '本机 .pptx 文件路径（绝对路径，或相对 MCP 进程 cwd）' },
+          data: { type: 'string', description: '可选：PPTX 的 base64 内容（无法访问 path 时使用）' },
+          name: { type: 'string', maxLength: 200, description: '显示文件名；缺省取 path 的 basename' },
+          mode: {
+            type: 'string',
+            enum: ['replace', 'append'],
+            description: 'replace（默认）用导入内容替换当前 deck；append 追加到现有页之后',
+          },
+          wait_ms: {
+            type: 'integer',
+            minimum: 1000,
+            maximum: MAX_WAIT_MS,
+            description: '等待编辑器完成导入的毫秒数（默认 180000）',
+          },
+        },
+        additionalProperties: false,
+      },
+      kind: 'write',
+      since: '2.4.0',
+      handler: async ({ path: filePath, data, name, mode, wait_ms }, ctx) => {
+        const input = readBytes({ filePath, data })
+        assertPptx(input.bytes)
+        const displayName = String(name || input.name || 'import.pptx')
+        const importMode = mode === 'append' ? 'append' : 'replace'
+        const waitMs = Math.max(1000, Math.min(Number(wait_ms) || DEFAULT_WAIT_MS, MAX_WAIT_MS))
+
+        /* 导入必须在编辑器页面里执行（复用 PPTist 的 DOM/字体/图片上下文）。 */
+        await ctx.editor.require(4000)
+
+        const uploaded = await ctx.importer.upload(input.bytes, displayName, input.path || '')
+        if (!uploaded || !uploaded.url) throw new Error('上传 PPTX 失败：桥没有返回临时文件地址')
+
+        const req = `imp_${Date.now().toString(36)}_${crypto.randomBytes(4).toString('hex')}`
+        const pushed = await ctx.deck.write([
+          /* 先压服务端历史快照：导入是编辑器级操作，不走 op 内核；
+           * 没有这一步 ppt_history undo 回不到导入前。 */
+          { op: 'snapshot' },
+          {
+            op: 'import-pptx',
+            req,
+            id: uploaded.id,
+            url: uploaded.url,
+            name: displayName,
+            mode: importMode,
+            resultUrl: RESULT_URL,
+          },
+        ])
+        if (!pushed.ok) throw new Error('导入指令投递失败：' + (pushed.error || '编辑器未接受指令'))
+
+        const deadline = Date.now() + waitMs
+        let result = null
+        while (Date.now() < deadline) {
+          try {
+            const current = await ctx.importer.result(req)
+            if (current && current.done) { result = current; break }
+          } catch { /* relay 瞬断：继续轮询直到超时 */ }
+          await sleep(200)
+        }
+        if (!result) {
+          throw new Error(
+            `等待编辑器导入超时（${Math.round(waitMs / 1000)}s）：请确认右侧编辑器页面已打开并刷新到最新版本`,
+          )
+        }
+        if (!result.ok) throw new Error('PPTX 导入失败：' + (result.error || '编辑器未返回错误详情'))
+
+        const { doc, synced } = await waitForMirror(ctx, result.summary)
+        const deck = compactDeck(doc?.deck)
+        const summary = result.summary && typeof result.summary === 'object' ? result.summary : {}
+        const warnings = []
+        if (!synced) warnings.push('deck 镜像尚未追上导入结果；稍后调用 ppt_get_deck 复查')
+        if (summary.mounted === false) warnings.push('编辑器返回 mounted=false，导入结果可能不完整')
+        const expectedFinal = Number(summary.import?.final ?? summary.slideCount ?? 0)
+        if (expectedFinal && deck.perSlide.length !== expectedFinal) {
+          warnings.push('导入摘要与 deck 页数不一致；请用 ppt_get_deck 复查')
+        }
+
+        return {
+          text: JSON.stringify({
+            ok: true,
+            source: { name: displayName, path: input.path || '', bytes: input.bytes.length, mode: importMode },
+            title: deck.title || summary.title || '',
+            slideCount: deck.slides,
+            elementCount: deck.elements,
+            deck: { title: deck.title, slides: deck.slides, elements: deck.elements, perSlide: deck.perSlide },
+            imported: summary,
+            warnings,
+            note: 'PPTX 已转换为 PPTist 编辑模型；动画/母版/SmartArt/复杂图表等可能丢失。建议随后调用 ppt_get_deck 或 ppt_audit 检查。',
+          }, null, 2),
+        }
+      },
+    }),
+  ],
+})

package/server/tools/capabilities/index.mjs

@@ -0,0 +1,58 @@
+/**
+ * 能力清单：唯一扩展点。
+ *
+ * 新增能力：新建 capabilities/<id>.mjs，导出 defineCapability(...)，
+ * 然后在这里加一行 import 和数组项即可。contract / instructions / 测试
+ * 全部由 registry 自动派生。
+ */
+import { contractCapability } from './contract.mjs'
+import { deckCapability } from './deck.mjs'
+import { auditCapability } from './audit.mjs'
+import { taskCapability } from './task.mjs'
+import { textCapability } from './text.mjs'
+import { styleCapability } from './style.mjs'
+import { elementCapability } from './element.mjs'
+import { slideCapability } from './slide.mjs'
+import { applyCapability } from './apply.mjs'
+import { composeCapability } from './compose.mjs'
+import { recolorCapability } from './recolor.mjs'
+import { imageCapability } from './image.mjs'
+import { imagesearchCapability } from './imagesearch.mjs'
+import { screenshotCapability } from './screenshot.mjs'
+import { presentCapability } from './present.mjs'
+import { historyCapability } from './history.mjs'
+import { chartCapability } from './chart.mjs'
+import { tableCapability } from './table.mjs'
+import { notesCapability } from './notes.mjs'
+import { shapeCapability } from './shape.mjs'
+import { lineCapability } from './line.mjs'
+import { formulaCapability } from './formula.mjs'
+import { importCapability } from './import.mjs'
+import { exportCapability } from './export.mjs'
+
+export const CAPABILITIES = [
+  contractCapability,
+  deckCapability,
+  auditCapability,
+  taskCapability,
+  textCapability,
+  styleCapability,
+  elementCapability,
+  slideCapability,
+  applyCapability,
+  composeCapability,
+  recolorCapability,
+  imageCapability,
+  imagesearchCapability,
+  screenshotCapability,
+  presentCapability,
+  historyCapability,
+  chartCapability,
+  tableCapability,
+  notesCapability,
+  shapeCapability,
+  lineCapability,
+  formulaCapability,
+  importCapability,
+  exportCapability,
+]