@capyclaw/ppt-workbench 0.0.0-stage → 2.4.0

package/server/tools/capabilities/line.mjs

@@ -0,0 +1,58 @@
+/** 线条能力：直线/虚线/折线连接（含端点箭头），坐标用画布绝对值，方向免算。 */
+import { clamp, okText } from '../domains/tooling.mjs'
+import { defineCapability, defineTool } from '../kernel/define.mjs'
+
+const POINT_STYLES = ['none', 'arrow', 'triangle', 'dot', 'square']
+
+const pointOf = (v) => (v && v !== 'none' ? String(v) : '')
+
+export const lineCapability = defineCapability({
+  id: 'line',
+  title: '线条',
+  tags: ['write', 'layout'],
+  requires: ['deck'],
+  features: ['deck.line'],
+  tools: [
+    defineTool({
+      name: 'ppt_line',
+      description:
+        '画一条线（直线 / 虚线 / 折线）。给起点终点画布坐标即可，包围盒自动计算；' +
+        '端点箭头可选 arrow / triangle / dot / square；broken 给拐点画布坐标可画折线。',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          slide: { type: 'integer', description: '0 起页号，默认 0' },
+          x1: { type: 'number', description: '起点 x（画布坐标）' },
+          y1: { type: 'number', description: '起点 y' },
+          x2: { type: 'number', description: '终点 x' },
+          y2: { type: 'number', description: '终点 y' },
+          color: { type: 'string', description: '线色，默认 #5b9bd5' },
+          style: { type: 'string', enum: ['solid', 'dashed'], description: '默认 solid' },
+          width: { type: 'number', description: '线宽，默认 2' },
+          start_point: { type: 'string', enum: POINT_STYLES, description: '起点箭头，默认 none' },
+          end_point: { type: 'string', enum: POINT_STYLES, description: '终点箭头，默认 none' },
+          broken: { type: 'array', items: { type: 'number' }, description: '折线拐点 [x, y]（画布坐标，产生 ┳ 型连接）' },
+        },
+        required: ['slide', 'x1', 'y1', 'x2', 'y2'],
+        additionalProperties: false,
+      },
+      kind: 'write',
+      since: '2.2.0',
+      handler: async (args, ctx) => {
+        const i = clamp(Number(args.slide) | 0, 0, 999)
+        const p = args || {}
+        const element = {
+          type: 'line',
+          x1: p.x1, y1: p.y1, x2: p.x2, y2: p.y2,
+          color: p.color || '#5b9bd5',
+          style: p.style || 'solid',
+          width: p.width != null ? p.width : 2,
+          points: [pointOf(p.start_point), pointOf(p.end_point)],
+          ...(Array.isArray(p.broken) && p.broken.length === 2 ? { broken: p.broken } : {}),
+        }
+        const r = await ctx.deck.write([{ op: 'add-element', slide: i, element }])
+        return okText(r, `已在第 ${i} 页画线`)
+      },
+    }),
+  ],
+})

package/server/tools/capabilities/notes.mjs

@@ -0,0 +1,33 @@
+/** 备注能力：演讲者备注（编辑器备注面板直接显示）。 */
+import { clamp, okText } from '../domains/tooling.mjs'
+import { defineCapability, defineTool } from '../kernel/define.mjs'
+
+export const notesCapability = defineCapability({
+  id: 'notes',
+  title: '演讲备注',
+  tags: ['write', 'content'],
+  requires: ['deck'],
+  features: ['deck.notes'],
+  tools: [
+    defineTool({
+      name: 'ppt_notes',
+      description: '设置指定页的演讲者备注（显示在编辑器备注面板，导出 PPTX 一并保留）。传空字符串清空。',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          slide: { type: 'integer', description: '0 起页号' },
+          notes: { type: 'string', maxLength: 2000, description: '备注内容；空字符串清空' },
+        },
+        required: ['slide', 'notes'],
+        additionalProperties: false,
+      },
+      kind: 'write',
+      since: '2.2.0',
+      handler: async ({ slide, notes }, ctx) => {
+        const i = clamp(Number(slide) | 0, 0, 999)
+        const r = await ctx.deck.write([{ op: 'set-notes', slide: i, notes: String(notes || '') }])
+        return okText(r, notes ? `已设置第 ${i} 页备注` : `已清空第 ${i} 页备注`)
+      },
+    }),
+  ],
+})

package/server/tools/capabilities/present.mjs

@@ -0,0 +1,34 @@
+/** 放映控制能力。 */
+import { clamp, okText } from '../domains/tooling.mjs'
+import { defineCapability, defineTool } from '../kernel/define.mjs'
+
+export const presentCapability = defineCapability({
+  id: 'present',
+  title: '放映',
+  tags: ['control'],
+  requires: ['deck'],
+  features: ['deck.present'],
+  tools: [
+    defineTool({
+      name: 'ppt_present',
+      description: '放映控制：start（可指定起始页）/ exit。',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          action: { type: 'string', enum: ['start', 'exit'] },
+          slide: { type: 'integer', description: 'start 的起始页（0 起）' },
+        },
+        required: ['action'],
+        additionalProperties: false,
+      },
+      kind: 'control',
+      since: '1.0.0',
+      handler: async ({ action, slide }, ctx) => {
+        const r = action === 'exit'
+          ? await ctx.deck.write([{ op: 'exit-present' }])
+          : await ctx.deck.write([{ op: 'present', index: slide != null ? clamp(Number(slide) | 0, 0, 999) : undefined }])
+        return okText(r, action === 'exit' ? '已退出放映' : '已开始放映')
+      },
+    }),
+  ],
+})

package/server/tools/capabilities/recolor.mjs

@@ -0,0 +1,60 @@
+/** 整体换色能力：新编辑器单条 recolor，旧编辑器回退为批量队列。 */
+import { resolveColor } from '../domains/color.mjs'
+import { expandRecolorOps, resolveForeground } from '../domains/recolor.mjs'
+import { normalizeSlides, okText } from '../domains/tooling.mjs'
+import { defineCapability, defineTool } from '../kernel/define.mjs'
+
+export const recolorCapability = defineCapability({
+  id: 'recolor',
+  title: '整体换色',
+  tags: ['recipe', 'style'],
+  requires: ['deck'],
+  features: ['deck.recolor'],
+  tools: [
+    defineTool({
+      name: 'ppt_recolor',
+      description: '一键整体换色（一次调用完成）：背景 + 全部文字对比色 + 装饰形状（线条/圆点/色条）统一色。改整体背景/配色时优先用它，禁止逐页 ppt_element 改色。',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          background: { type: 'string', description: '新背景色（CSS 颜色或中文色名）' },
+          text: { type: 'string', description: '文字颜色；缺省按背景自动对比（浅底深字/深底白字）' },
+          shapes: { type: 'string', description: '装饰形状填充色；缺省跟随文字色（传 null 表示不改装饰）' },
+          slides: { type: 'array', items: { type: 'integer' }, description: '只改这些页；缺省全部' },
+        },
+        required: ['background'],
+        additionalProperties: false,
+      },
+      kind: 'write',
+      since: '1.0.0',
+      handler: async ({ background, text, shapes, slides }, ctx) => {
+        const bg = resolveColor(background)
+        const textColor = text ? resolveColor(text) : ''
+        const shapeColor = shapes === undefined ? undefined : (shapes === null ? null : resolveColor(shapes))
+        const targets = normalizeSlides(slides)
+
+        // 1) 新编辑器：单条 recolor 指令（背景+文字+装饰一次完成）
+        const cmd = { op: 'recolor', background: bg }
+        if (textColor) cmd.text = textColor
+        if (shapeColor !== undefined) cmd.shapes = shapeColor
+        if (targets) cmd.indices = targets
+        const r = await ctx.deck.write([cmd])
+        if (r.ok) return okText(r, '整体配色已更新')
+        if (!/未知指令/.test(String(r.error || ''))) return okText(r, '整体配色失败')
+
+        // 2) 旧编辑器兼容：展开为 set-background + set-element 批量队列
+        const fg = resolveForeground(bg, textColor)
+        const sf = shapeColor === undefined ? fg : shapeColor
+        const doc = await ctx.deck.read()
+        const ops = expandRecolorOps(doc.deck, { bg, fg, sf, targets })
+        let applied = 0
+        for (let i = 0; i < ops.length; i += 90) {
+          const rr = await ctx.deck.write(ops.slice(i, i + 90))
+          if (!rr.ok) return okText(rr, '整体配色失败（兼容模式）')
+          applied += rr.applied
+        }
+        return { text: `整体配色已更新（兼容模式，${applied} 条）` }
+      },
+    }),
+  ],
+})

package/server/tools/capabilities/screenshot.mjs

@@ -0,0 +1,86 @@
+/** 实时画面能力：唯一依赖编辑器页面在线的能力。 */
+import { sleep } from '../domains/tooling.mjs'
+import { defineCapability, defineTool } from '../kernel/define.mjs'
+
+let screenshotChain = Promise.resolve()
+
+/* 每次尝试等编辑器回图的时长：两次合计 ~18s + settle 3s ≈ 21s 封顶。
+   曾经 45s×2 ≈ 94s——客户端（60s 超时）早已断连，响应写回已销毁 socket
+   曾引发进程崩溃（HTTP 层已加断连防护，这里同时改为快速失败）。 */
+export const SHOT_WAIT_DEADLINES_MS = [12000, 6000]
+
+async function captureScreenshot(ctx, { deadlines = SHOT_WAIT_DEADLINES_MS } = {}) {
+  /* 截图必须在页面内渲染——这是唯一真正依赖面板在线的操作 */
+  await ctx.editor.require()
+  /* 空 deck 直接拒绝：曾经空 deck 让编辑器渲染空图被 sanitize 拒收，
+     页面又已标记 lastShotReq 不再重试 → 服务端 shot_req 永久悬挂。 */
+  const deckStatus = await ctx.status.get()
+  if (deckStatus.has_deck === false || Number(deckStatus.slides || 0) === 0) {
+    throw new Error('当前演示文稿为空（0 页），没有可截取的画面。请先用 ppt_deck / ppt_slide 添加页面。')
+  }
+  /* 先等编辑器应用完所有已排队指令，避免截到旧状态 */
+  const settleDeadline = Date.now() + 3000
+  while (Date.now() < settleDeadline) {
+    const st = await ctx.status.get()
+    if (Number(st.applied_seq || 0) >= Number(st.seq || 0)) break
+    await sleep(120)
+  }
+  let lastError = ''
+  for (const waitMs of deadlines) {
+    const reqDoc = await ctx.editor.requestShot()
+    const req = reqDoc.shot_req
+    const deadline = Date.now() + waitMs
+    let pending = true
+    while (Date.now() < deadline) {
+      const st = await ctx.status.get()
+      if (st.shot && st.shot.req === req) {
+        const shot = await ctx.editor.getShot()
+        if (shot.data) {
+          const base64 = shot.data.slice(shot.data.indexOf(',') + 1)
+          return {
+            content: [
+              { type: 'text', text: `以下是右侧编辑器的实时画面（全部页拼图，帧 ${req}）：` },
+              { type: 'image', data: base64, mimeType: 'image/jpeg' },
+            ],
+          }
+        }
+        lastError = '编辑器渲染失败'
+        pending = false
+        break
+      }
+      await sleep(150)
+    }
+    if (pending) lastError = '等待编辑器渲染超时'
+    await sleep(600)
+  }
+  throw new Error(`截图失败（${lastError}）：编辑器面板未打开、在后台被浏览器节流，或页面已关闭。请把编辑器标签页切到前台再重试。`)
+}
+
+export const screenshotCapability = defineCapability({
+  id: 'screenshot',
+  title: '实时画面',
+  tags: ['read', 'visual'],
+  requires: ['editor', 'status'],
+  features: ['deck.screenshot'],
+  tools: [
+    defineTool({
+      name: 'ppt_screenshot',
+      description: '取右侧编辑器实时画面（全部页拼图）。确认视觉效果时调用。',
+      inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+      kind: 'read',
+      since: '1.0.0',
+      handler: async (args, ctx) => {
+        /* 并发截图串行化：多个工具调用不能互相 reset shot_req。 */
+        const previous = screenshotChain
+        let release
+        screenshotChain = new Promise((resolve) => { release = resolve })
+        await previous
+        try {
+          return await captureScreenshot(ctx)
+        } finally {
+          release()
+        }
+      },
+    }),
+  ],
+})

package/server/tools/capabilities/shape.mjs

@@ -0,0 +1,64 @@
+/** 形状能力：内置形状库一键插入（矩形/圆/三角/星形/箭头/气泡…），也接受自定义 path。 */
+import { SHAPE_KEYS, getShape } from '../../../core/shape-library.js'
+import { clamp, okText } from '../domains/tooling.mjs'
+import { defineCapability, defineTool } from '../kernel/define.mjs'
+
+export const shapeCapability = defineCapability({
+  id: 'shape',
+  title: '形状库',
+  tags: ['write', 'layout'],
+  requires: ['deck'],
+  features: ['deck.shape'],
+  tools: [
+    defineTool({
+      name: 'ppt_shape',
+      description:
+        '插入形状。shape 从内置库选（' + SHAPE_KEYS.join(' / ') + '），' +
+        '也可传自定义 SVG path + viewBox。装饰、流程节点、强调块都走这里。',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          slide: { type: 'integer', description: '0 起页号，默认 0' },
+          shape: { type: 'string', description: '内置形状 key，如 circle / arrow-right / star-5 / round-rect' },
+          path: { type: 'string', description: '自定义 SVG path（与 shape 二选一，优先生效）' },
+          viewBox: { type: 'array', items: { type: 'number' }, description: '自定义 path 的 viewBox [w, h]，默认 [200, 200]' },
+          fill: { type: 'string', description: '填充色，默认 #5b9bd5' },
+          left: { type: 'number' },
+          top: { type: 'number' },
+          width: { type: 'number', description: '默认 200' },
+          height: { type: 'number', description: '默认 200' },
+          rotate: { 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 || {}
+        let path = p.path
+        let viewBox = Array.isArray(p.viewBox) && p.viewBox.length === 2 ? p.viewBox : [200, 200]
+        if (!path) {
+          if (!p.shape) throw new Error('需要 shape（内置形状 key）或 path（自定义 SVG）')
+          const s = getShape(p.shape)
+          path = s.path
+          viewBox = s.viewBox
+        }
+        const element = {
+          type: 'shape',
+          path,
+          viewBox,
+          fill: p.fill || '#5b9bd5',
+          left: p.left != null ? p.left : 60,
+          top: p.top != null ? p.top : 120,
+          width: p.width != null ? p.width : 200,
+          height: p.height != null ? p.height : 200,
+          ...(p.rotate != null ? { rotate: p.rotate } : {}),
+        }
+        const r = await ctx.deck.write([{ op: 'add-element', slide: i, element }])
+        return okText(r, `已在第 ${i} 页插入形状${p.shape ? ' ' + p.shape : ''}`)
+      },
+    }),
+  ],
+})

package/server/tools/capabilities/slide.mjs

@@ -0,0 +1,81 @@
+/** 页面管理能力。 */
+import { simpleSlide } from '../domains/slide.mjs'
+import { okText } from '../domains/tooling.mjs'
+import { defineCapability, defineTool } from '../kernel/define.mjs'
+
+export const slideCapability = defineCapability({
+  id: 'slide',
+  title: '页面管理',
+  tags: ['write', 'structure'],
+  requires: ['deck'],
+  features: ['deck.write'],
+  tools: [
+    defineTool({
+      name: 'ppt_slide',
+      description: '页管理：add（标题+要点）/remove/move/duplicate/select。',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          action: { type: 'string', enum: ['add', 'remove', 'move', 'duplicate', 'select'] },
+          index: { type: 'integer', description: '目标页号（0 起）；add 时为插入位置，缺省末尾' },
+          to: { type: 'integer', description: 'move 的目标位置' },
+          title: { type: 'string', maxLength: 40, description: 'add 的标题' },
+          bullets: { type: 'array', maxItems: 8, items: { type: 'string', maxLength: 80 } },
+          background: { type: 'string' },
+        },
+        required: ['action'],
+        additionalProperties: false,
+      },
+      kind: 'write',
+      since: '1.0.0',
+      handler: async ({ action, index, to, title, bullets, background }, ctx) => {
+        const slideCount = async () => {
+          const doc = await ctx.deck.read()
+          return doc.deck && Array.isArray(doc.deck.slides) ? doc.deck.slides.length : 0
+        }
+        const requirePage = (value, label = 'index') => {
+          const n = Number(value)
+          if (!Number.isInteger(n) || n < 0) throw new Error(`ppt_slide ${action} 需要 ${label}（0 起整数）`)
+          return n
+        }
+        if (action === 'add') {
+          const count = await slideCount()
+          let at = index != null ? Math.min(requirePage(index), count) : count
+          const r = await ctx.deck.write([{ op: 'add-slide', slide: simpleSlide(title || '新一页', bullets, background), index: at }])
+          return okText(r, `已加一页「${title || '新一页'}」`)
+        }
+        if (action === 'remove') {
+          const count = await slideCount()
+          const i = requirePage(index)
+          if (i >= count) throw new Error(`页号越界：${i}（共 ${count} 页）`)
+          const r = await ctx.deck.write([{ op: 'remove-slide', id: i }])
+          return okText(r, `已删除第 ${i} 页`)
+        }
+        if (action === 'move') {
+          const count = await slideCount()
+          const from = requirePage(index)
+          const target = requirePage(to, 'to')
+          if (from >= count) throw new Error(`页号越界：${from}（共 ${count} 页）`)
+          if (target >= count) throw new Error(`目标页号越界：${target}（共 ${count} 页）`)
+          const r = await ctx.deck.write([{ op: 'move-slide', from, to: target }])
+          return okText(r, `已移动第 ${from} 页到 ${target}`)
+        }
+        if (action === 'duplicate') {
+          const count = await slideCount()
+          const i = requirePage(index)
+          if (i >= count) throw new Error(`页号越界：${i}（共 ${count} 页）`)
+          const r = await ctx.deck.write([{ op: 'duplicate-slide', id: i }])
+          return okText(r, `已复制第 ${i} 页`)
+        }
+        if (action === 'select') {
+          const count = await slideCount()
+          const i = requirePage(index)
+          if (i >= count) throw new Error(`页号越界：${i}（共 ${count} 页）`)
+          const r = await ctx.deck.write([{ op: 'select', id: i }])
+          return okText(r, `已选中第 ${i} 页`)
+        }
+        throw new Error('未知 action: ' + action)
+      },
+    }),
+  ],
+})

package/server/tools/capabilities/style.mjs

@@ -0,0 +1,48 @@
+/** 样式能力：背景色、文字颜色、字体名、主题色。 */
+import { resolveColor } from '../domains/color.mjs'
+import { clamp, normalizeSlides, okText } from '../domains/tooling.mjs'
+import { defineCapability, defineTool } from '../kernel/define.mjs'
+
+export const styleCapability = defineCapability({
+  id: 'style',
+  title: '主题与背景',
+  tags: ['write', 'style'],
+  requires: ['deck'],
+  features: ['deck.write'],
+  tools: [
+    defineTool({
+      name: 'ppt_style',
+      description: '整体样式：背景色（可指定页），文字颜色，字体名，主题色数组。浅底会自动配深字、深底配白字。',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          background: { type: 'string', description: '背景色（CSS 或中文色名）' },
+          slides: { type: 'array', items: { type: 'integer' }, description: '只改这些页的背景；缺省全部' },
+          contrast: { type: 'boolean', description: '自动对比度，缺省 true' },
+          text_color: { type: 'string', description: '全局正文颜色' },
+          font_name: { type: 'string' },
+          theme_colors: { type: 'array', items: { type: 'string' }, description: '主题色数组' },
+        },
+        additionalProperties: false,
+      },
+      kind: 'write',
+      since: '1.0.0',
+      handler: async ({ background, slides, contrast, text_color, font_name, theme_colors }, ctx) => {
+        const ops = []
+        if (background) {
+          const cmd = { op: 'set-background', color: resolveColor(background), contrast: contrast !== false }
+          const targets = normalizeSlides(slides)
+          if (targets) cmd.indices = targets
+          ops.push(cmd)
+        }
+        const theme = {}
+        if (text_color) theme.fontColor = resolveColor(text_color)
+        if (font_name) theme.fontName = String(font_name)
+        if (Array.isArray(theme_colors) && theme_colors.length) theme.themeColors = theme_colors.map(resolveColor)
+        if (Object.keys(theme).length) ops.push({ op: 'theme', theme })
+        const r = await ctx.deck.write(ops)
+        return okText(r, '样式已更新')
+      },
+    }),
+  ],
+})

package/server/tools/capabilities/table.mjs

@@ -0,0 +1,127 @@
+/** 表格能力：把二维数据直接变成 PPTist 原生表格，支持表头样式与单元格精修。 */
+import { clamp, okText } from '../domains/tooling.mjs'
+import { defineCapability, defineTool } from '../kernel/define.mjs'
+
+export const tableCapability = defineCapability({
+  id: 'table',
+  title: '表格',
+  tags: ['write', 'data'],
+  requires: ['deck'],
+  features: ['deck.table'],
+  tools: [
+    defineTool({
+      name: 'ppt_table',
+      description:
+        '插入或整体更新表格（PPTist 原生表格）。rows 为二维数组，字符串/数字直接作单元格；' +
+        'header: true 时首行渲染为加粗底色表头。带 element_id 时整体替换该表格数据。',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          slide: { type: 'integer', description: '0 起页号，默认 0' },
+          rows: {
+            type: 'array',
+            description: '二维数组，如 [["区域","目标"],["华东",70],["华南",66]]；单元格也可用对象 {text, bold, color, backcolor, align, fontsize}',
+            items: { type: 'array' },
+          },
+          header: { type: 'boolean', description: '首行作为表头（加粗 + 主题色浅底）' },
+          theme_color: { type: 'string', description: '表格主题色（表头底色由此淡化生成），默认 #5b9bd5' },
+          element_id: { type: 'string', description: '更新模式：整体替换该表格的数据/列宽' },
+          col_widths: { type: 'array', items: { type: 'number' }, description: '列宽比例或像素（自动归一）' },
+          cell_min_height: { type: 'number', description: '单元格最小高度，默认 36' },
+          left: { type: 'number' },
+          top: { type: 'number' },
+          width: { type: 'number' },
+          height: { type: 'number' },
+        },
+        required: ['slide', 'rows'],
+        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.rows != null) {
+            // 整体替换：重建 data，保留原主题色
+            const element = { rows: p.rows, header: Boolean(p.header), themeColor: p.theme_color }
+            const r0 = await ctx.deck.write([{ op: 'remove-element', slide: i, elementId: String(p.element_id) }])
+            if (!r0.ok) return { text: `替换失败：${r0.error}` }
+            const r = await ctx.deck.write([{ op: 'add-table', slide: i, element }])
+            return okText(r, `已重建表格 ${p.element_id}`)
+          }
+          if (p.theme_color) props.themeColor = p.theme_color
+          if (p.header != null) props.rowHeader = Boolean(p.header)
+          if (Array.isArray(p.col_widths)) props.colWidths = p.col_widths
+          for (const k of ['left', 'top', 'width', 'height']) {
+            if (p[k] != null) props[k] = p[k]
+          }
+          const r = await ctx.deck.write([{ op: 'update-table', slide: i, elementId: String(p.element_id), props }])
+          return okText(r, `已更新表格 ${p.element_id}`)
+        }
+        const element = {
+          rows: p.rows,
+          header: Boolean(p.header),
+          ...(p.theme_color ? { themeColor: p.theme_color } : {}),
+          ...(Array.isArray(p.col_widths) ? { colWidths: p.col_widths } : {}),
+          ...(p.cell_min_height != null ? { cellMinHeight: p.cell_min_height } : {}),
+        }
+        for (const k of ['left', 'top', 'width', 'height']) {
+          if (p[k] != null) element[k] = p[k]
+        }
+        const r = await ctx.deck.write([{ op: 'add-table', slide: i, element }])
+        return okText(r, `已在第 ${i} 页插入表格（${p.rows.length} 行）`)
+      },
+    }),
+
+    defineTool({
+      name: 'ppt_table_cells',
+      description:
+        '精修已有表格的单元格：改文字 / 加粗 / 颜色 / 底色 / 对齐 / 字号，也可换表格主题色。' +
+        '行号列号从 0 起，元素 id 可用 ppt_get_deck 查询。',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          slide: { type: 'integer', description: '0 起页号，默认 0' },
+          element_id: { type: 'string', description: '表格元素 id' },
+          cells: {
+            type: 'array',
+            description: '单元格补丁列表',
+            items: {
+              type: 'object',
+              properties: {
+                row: { type: 'integer', description: '0 起行号' },
+                col: { type: 'integer', description: '0 起列号' },
+                text: { type: 'string' },
+                bold: { type: 'boolean' },
+                color: { type: 'string', description: '文字颜色' },
+                backcolor: { type: 'string', description: '单元格底色' },
+                align: { type: 'string', enum: ['left', 'center', 'right'] },
+                fontsize: { type: 'number' },
+              },
+              required: ['row', 'col'],
+              additionalProperties: false,
+            },
+          },
+          theme_color: { type: 'string', description: '顺带更换表格主题色' },
+        },
+        required: ['slide', 'element_id', 'cells'],
+        additionalProperties: false,
+      },
+      kind: 'write',
+      since: '2.2.0',
+      handler: async ({ slide, element_id, cells, theme_color }, ctx) => {
+        const i = clamp(Number(slide) | 0, 0, 999)
+        const r = await ctx.deck.write([{
+          op: 'set-table-cells',
+          slide: i,
+          elementId: String(element_id),
+          cells,
+          ...(theme_color ? { themeColor: theme_color } : {}),
+        }])
+        return okText(r, `已更新表格 ${element_id} 的 ${Array.isArray(cells) ? cells.length : 0} 个单元格`)
+      },
+    }),
+  ],
+})

package/server/tools/capabilities/task.mjs

@@ -0,0 +1,52 @@
+/** 任务恢复能力：status / list / checkpoint / restore。 */
+import { okText } from '../domains/tooling.mjs'
+import { defineCapability, defineTool } from '../kernel/define.mjs'
+
+export const taskCapability = defineCapability({
+  id: 'task',
+  title: '任务恢复',
+  tags: ['state'],
+  requires: ['deck', 'task'],
+  features: ['deck.task'],
+  tools: [
+    defineTool({
+      name: 'ppt_task',
+      description: '任务恢复：status 查当前进度/待处理批次/最近 checkpoint；list 列 checkpoint；checkpoint 保存命名快照；restore 恢复快照。长任务每阶段保存一次。',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          action: { type: 'string', enum: ['status', 'list', 'checkpoint', 'restore'] },
+          name: { type: 'string', maxLength: 64, description: 'checkpoint 名称（字母/数字/._-）' },
+          meta: { type: 'object', description: 'checkpoint 附带的 goal/plan/next 等元数据' },
+        },
+        required: ['action'],
+        additionalProperties: false,
+      },
+      kind: 'read',
+      since: '2.2.0',
+      handler: async ({ action, name, meta }, ctx) => {
+        if (action === 'status') {
+          const status = await ctx.task.status()
+          return { text: JSON.stringify(status, null, 2) }
+        }
+        if (action === 'list') {
+          const data = await ctx.task.list()
+          return { text: JSON.stringify(data, null, 2) }
+        }
+        if (action === 'checkpoint') {
+          if (!name) throw new Error('checkpoint 需要 name')
+          const saved = await ctx.task.checkpoint(name, meta || {})
+          return { text: `已保存 checkpoint ${saved.name}（seq ${saved.seq}，${saved.slides} 页）` }
+        }
+        if (action === 'restore') {
+          if (!name) throw new Error('restore 需要 name')
+          const saved = await ctx.task.read(name)
+          if (!saved || !saved.deck) throw new Error('checkpoint 不存在或内容损坏: ' + name)
+          const result = await ctx.deck.write([{ op: 'load', deck: saved.deck }])
+          return okText(result, `已恢复 checkpoint ${name}（${saved.slides} 页）`)
+        }
+        throw new Error('未知 action: ' + action)
+      },
+    }),
+  ],
+})