@capyclaw/ppt-workbench 0.0.0-stage → 2.4.0

package/server/mcp/instructions.mjs

@@ -0,0 +1,40 @@
+/**
+ * server instructions：agent 拿到的「怎么用这套工具」说明书（≤32KB 硬限）。
+ * 排版由 dsh-tool-host 的 buildInstructions 统一生成，本文件只放 PPT 文案。
+ */
+import { buildInstructions } from '../shared/tool-host.mjs'
+import { CONTRACT_VERSION } from '../contract.mjs'
+
+export function serverInstructions(editorUrl, { tools = [], capabilities = [] } = {}) {
+  const major = String(CONTRACT_VERSION).split('.')[0]
+  const caps = capabilities.length
+    ? capabilities
+    : [{ title: '工具', description: '', tools: tools.map((tool) => tool.name) }]
+
+  return buildInstructions({
+    title: 'PPTist 工作台',
+    intro: '你负责通过 `mcp__ppt__*` 工具编辑右侧实时 PPTist 编辑器。',
+    startup: [
+      `首次操作前调用 \`ppt_capabilities\`，确认 \`contractVersion\` 为 ${major}.x；工具缺失或 major 不一致时停止，提示用户安装/升级 \`dsh-ppt-suite\`。`,
+      '若本会话提供对应 skill，先加载：`pptmaster-narrative`、`pptmaster-design`、`pptist-api`、`pptist-authoring`、`pptist-editing`、`pptist-visual-check`、`pptist-research`；没有 skill 时按本页规则执行。',
+    ],
+    capabilities: caps,
+    rules: [
+      '用户说“背景/页面/幻灯片/标题”指右侧编辑器，不是网页或文件。',
+      '新建 deck 默认用 `ppt_deck` + `preset:"clean"` 出简洁稿，不叠装饰形状。',
+      '改现有 deck 只执行用户点名的修改；不主动审美、审计、截图，不扩大范围。',
+      '改整体背景/配色只用 `ppt_recolor` 一次完成；禁止逐页 `ppt_element` 改色。',
+      '改文字/加页/改背景不要先读整个 deck；只有定位具体元素时才 `ppt_get_deck({detailed:true})`，一次即可。',
+      '图片用 `ppt_image`（attachment_id/path/src），不要用 shell 找图，不要用 `ppt_element` 传本机路径。',
+      '单次工具参数不要过大：`ppt_deck` 一次不超过约 20 页；超过时先成稿骨架，再用 `ppt_fill` / `ppt_text` 分批补充，避免 tool input JSON 解析失败。',
+      '不主动截图；用户要求看效果或确实不确定版面时才 `ppt_screenshot`。',
+      '工具返回已含回执；改完一句话回复，不要重复验证。',
+      '长任务每阶段用 `ppt_task` checkpoint；新会话先 status，必要时 restore。',
+      `编辑器未连接时，提示用户打开 ${editorUrl}（页面加载后自动连接），不要循环重试。`,
+    ],
+    output: [
+      '交付时说明页数、每章要点、是否已截图确认。',
+      '不贴 JSON、不列工具调用日志。',
+    ],
+  })
+}

package/server/mcp-http.mjs

@@ -0,0 +1,3 @@
+/** 兼容入口：MCP HTTP 协议壳与 instructions 已拆到 server/mcp/*。 */
+export { createMcpHandler } from './mcp/handler.mjs'
+export { serverInstructions } from './mcp/instructions.mjs'

package/server/ppt-shim.mjs

@@ -0,0 +1,156 @@
+/**
+ * ppt-shim.mjs — 服务端 PptApp 数据执行器（纯 JSON，无 DOM）。
+ *
+ * 架构定位（2026-10-30 解耦批）：
+ *   deck 数据的权威保存在 relay 进程（store.doc.deck）。
+ *   MCP 工具的 ops 在服务端由本 shim 直接执行——**不依赖任何编辑器页面在线**。
+ *   编辑器页面（无论侧边栏还是独立标签）只是视图：watch 到指令版本变化后
+ *   镜像 load 最新 deck；用户手动编辑通过 pushState 镜像回服务端。
+ *
+ * 实现 core/ops.js 定义的 P 接口子集（数据类）：
+ *   isMounted / getSlides / updateSlide / load / setTitle / setTheme / getTheme
+ *   addSlide / removeSlide / moveSlide / duplicateSlide / selectSlide
+ *   snapshot / undo / redo / present / exitPresent
+ * undo/redo 在服务端维护 50 步 deck 历史；present/select 仍是页面概念。
+ */
+
+const emptyDeck = () => ({
+  title: '未命名演示文稿',
+  slides: [],
+  theme: {
+    themeColors: ['#2f6feb', '#f0a030', '#1f2d3d'],
+    fontColor: '#1f2d3d',
+    fontName: '',
+    backgroundColor: '#ffffff',
+  },
+  viewportSize: 1000,
+  viewportRatio: 0.5625,
+})
+
+let dupCounter = 0
+
+export function createJsonPptApp(store) {
+  const deckOf = () => {
+    if (!store.doc.deck || !Array.isArray(store.doc.deck.slides)) {
+      store.doc.deck = emptyDeck()
+    }
+    return store.doc.deck
+  }
+
+  const past = []
+  const future = []
+  const cloneDeck = () => JSON.parse(JSON.stringify(deckOf()))
+  const remember = () => {
+    past.push(cloneDeck())
+    if (past.length > 50) past.shift()
+    future.length = 0
+  }
+  const restore = (deck) => {
+    store.doc.deck = deck
+    store.doc.updated = Date.now() / 1000
+  }
+
+  const P = {
+    isMounted() { return true },
+
+    getSlides() { return deckOf().slides },
+
+    /** PPTist updateSlide(index, slide) → bool */
+    updateSlide(i, slide) {
+      const slides = deckOf().slides
+      const k = Number(i) | 0
+      if (k < 0 || k >= slides.length) return false
+      slides[k] = slide
+      return true
+    },
+
+    /** 替换 title + slides + 画布设定（checkpoint 恢复必须连 theme 一起还原）。 */
+    load(deck) {
+      const d = deckOf()
+      if (deck && Array.isArray(deck.slides)) d.slides = JSON.parse(JSON.stringify(deck.slides))
+      if (deck && deck.title != null) d.title = String(deck.title)
+      for (const key of ['theme', 'viewportSize', 'viewportRatio']) {
+        if (deck && deck[key] != null) d[key] = JSON.parse(JSON.stringify(deck[key]))
+      }
+      return true
+    },
+
+    setTitle(t) { deckOf().title = String(t || '') },
+
+    getTheme() { return deckOf().theme || {} },
+
+    setTheme(t) {
+      const d = deckOf()
+      d.theme = { ...(d.theme || {}), ...(t || {}) }
+    },
+
+    addSlide(slide, index) {
+      const d = deckOf()
+      const s = (slide && (slide.elements || slide.background || slide.id))
+        ? JSON.parse(JSON.stringify(slide))
+        : { id: 'slide_' + Date.now() + '_' + Math.floor(Math.random() * 1e3), elements: [] }
+      if (!Array.isArray(s.elements)) s.elements = []
+      if (index != null) {
+        const k = Math.min(Math.max(Number(index) | 0, 0), d.slides.length)
+        d.slides.splice(k, 0, s)
+      } else {
+        d.slides.push(s)
+      }
+      return true
+    },
+
+    removeSlide(i) {
+      const slides = deckOf().slides
+      const k = Number(i) | 0
+      if (k < 0 || k >= slides.length) return false
+      slides.splice(k, 1)
+      return true
+    },
+
+    moveSlide(from, to) {
+      const slides = deckOf().slides
+      const a = Number(from) | 0
+      const b = Number(to) | 0
+      if (a < 0 || a >= slides.length || b < 0 || b > slides.length) return false
+      const [m] = slides.splice(a, 1)
+      slides.splice(b > a ? b - 1 : b, 0, m)
+      return true
+    },
+
+    duplicateSlide(i) {
+      const slides = deckOf().slides
+      const k = Number(i) | 0
+      if (k < 0 || k >= slides.length) return false
+      dupCounter += 1
+      const copy = JSON.parse(JSON.stringify(slides[k]))
+      copy.id = (copy.id || 'slide') + '_d' + dupCounter
+      ;(copy.elements || []).forEach(e => { e.id = (e.id || 'el') + '_d' + dupCounter })
+      slides.splice(k + 1, 0, copy)
+      return true
+    },
+
+    /** 每个会改 deck 的 op 执行前调用。 */
+    snapshot: remember,
+
+    undo() {
+      if (!past.length) return false
+      future.push(cloneDeck())
+      restore(past.pop())
+      return true
+    },
+
+    redo() {
+      if (!future.length) return false
+      past.push(cloneDeck())
+      restore(future.pop())
+      return true
+    },
+
+    /* 页面概念：服务端 no-op */
+    selectSlide() { return true },
+    present() { return true },
+    exitPresent() { return true },
+  }
+
+  return P
+}

package/server/relay.mjs

@@ -0,0 +1,245 @@
+/**
+ * 桥 relay 组合根：
+ *   1) 桥端点（/api/desktop/works/ppt-bridge…）→ routes/bridge.mjs
+ *   2) MCP Streamable HTTP（/mcp）→ mcp/handler.mjs
+ *   3) 编辑器静态页（/、/app.js、/ppt-full-app.js）→ routes/editor.mjs
+ *
+ * 通用宿主（端口/锁/复用/健康/指标/静态/关闭）由 dsh-service-host 提供；
+ * 本文件只保留 PPT 专属装配。
+ *
+ * 也可脱离 dsh 独立运行：node server/relay.mjs [--port 39311] [--dir <hostDir>]
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { BridgeStore } from './store.mjs'
+import { createMcpHandler, serverInstructions } from './mcp-http.mjs'
+import { applyOp } from '../core/ops.js'
+import { createJsonPptApp } from './ppt-shim.mjs'
+import { CONTRACT_VERSION, PACKAGE_VERSION } from './contract.mjs'
+import { BASE_PATH, DEFAULT_PORT } from './constants.mjs'
+import { createAssetRoutes } from './routes/assets.mjs'
+import { createFileAssetStore } from './shared/asset-service.mjs'
+import { createEditorRoutes } from './routes/editor.mjs'
+import { createMcpRoutes } from './routes/mcp.mjs'
+import { createImportRoutes } from './routes/import.mjs'
+import { createBridgeRoutes } from './routes/bridge.mjs'
+import { replayPending } from './runtime/recovery.mjs'
+import { createServiceApp } from './shared/service-host.mjs'
+import { inspectContractSnapshots, describeMismatch } from './contract-snapshots.mjs'
+import { getTuning } from './tuning.mjs'
+import { createRuntimeStoreClient, loadRuntimeContext } from './infra/runtime/context.mjs'
+import { WorkspaceBackend } from './infra/workspace/manager.mjs'
+
+export { DEFAULT_PORT, BASE_PATH }
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+
+export async function startRelay({
+  port = DEFAULT_PORT,
+  hostDir = process.env.PPT_BRIDGE_HOME
+    || path.join(process.env.USERPROFILE || process.env.HOME || '.', '.dsh-ppt-bridge'),
+  packageDir = PKG_ROOT,
+  scanLimit = 50,
+  lockFile,
+  strictPort = false,
+  allowReuse = true,
+  backend = null,
+  assetStore = null,
+  assetService = null,
+  capabilities = null,
+  serviceHost = null,
+  toolHost = null,
+  editorHost = null,
+} = {}) {
+  const editorDir = path.join(packageDir, 'editor')
+  const contractSnapshots = inspectContractSnapshots(packageDir, CONTRACT_VERSION)
+  if (!contractSnapshots.ok) {
+    console.error('[ppt-workbench] 契约快照不一致，工具调用将被拒绝:', describeMismatch(contractSnapshots))
+  }
+  const store = backend ? new BridgeStore({ backend }) : new BridgeStore(path.join(hostDir, 'state.json'))
+  /* 独立运行（无 dsh）也要有对象仓库：图片落 hostDir/assets，
+   * 否则 /assets 上传 404，ppt_images / ppt_image 的入库分支不可用。 */
+  if (!assetStore && !assetService) {
+    try {
+      assetStore = createFileAssetStore({ dir: path.join(hostDir, 'assets') })
+    } catch { /* 对象仓库不可用不影响纯 deck 功能 */ }
+  }
+  if (assetStore) process.env.PPT_ASSET_STORE = '1'
+
+  const createApp = serviceHost?.createApp ? (options) => serviceHost.createApp(options) : createServiceApp
+  const app = createApp({
+    id: 'ppt-workbench',
+    title: 'PPT Workbench',
+    version: PACKAGE_VERSION,
+    contractVersion: CONTRACT_VERSION,
+    health: () => {
+      const doc = store.get()
+      const owner = doc.owner && doc.owner.id && (Date.now() / 1000 - (doc.owner.ts || 0) <= 10)
+      return {
+        bridge: 'ppt-workbench',
+        editor: `http://127.0.0.1:${app.port}/`,
+        editorConnected: !!owner,
+        hasDeck: !!(doc.deck && Array.isArray(doc.deck.slides) && doc.deck.slides.length),
+        slides: doc.deck && Array.isArray(doc.deck.slides) ? doc.deck.slides.length : 0,
+        seq: doc.seq | 0,
+        appliedSeq: doc.applied_seq | 0,
+        stateSeq: doc.state_seq | 0,
+        uiSeq: doc.ui_seq | 0,
+        lastError: doc.error || '',
+        contractsOk: contractSnapshots.ok,
+        contractsChecked: contractSnapshots.checked,
+        injected: {
+          serviceHost: !!serviceHost,
+          toolHost: !!toolHost,
+          editorHost: !!editorHost,
+          assets: !!assetStore,
+        },
+      }
+    },
+    metrics: () => {
+      const doc = store.get()
+      const slides = doc.deck && Array.isArray(doc.deck.slides) ? doc.deck.slides.length : 0
+      const owner = doc.owner && doc.owner.id && (Date.now() / 1000 - (doc.owner.ts || 0) <= 10)
+      return [
+        ['ppt_workbench_slides', slides],
+        ['ppt_workbench_seq', doc.seq | 0],
+        ['ppt_workbench_applied_seq', doc.applied_seq | 0],
+        ['ppt_workbench_state_seq', doc.state_seq | 0],
+        ['ppt_workbench_editor_connected', owner ? 1 : 0],
+        ['ppt_workbench_shot_req', doc.shot_req | 0],
+        ['ppt_workbench_memory_rss_bytes', process.memoryUsage().rss],
+      ]
+    },
+  })
+
+  const jsonP = createJsonPptApp(store)
+  let mcpHandler = null
+  for (const route of createMcpRoutes({ getMcpHandler: () => mcpHandler })) app.use(route)
+  if (assetService?.mount) assetService.mount(app, { store: assetStore, basePath: BASE_PATH })
+  else app.use(createAssetRoutes({ assetStore, basePath: BASE_PATH }))
+  for (const route of createEditorRoutes({ editorDir, editorHost })) app.use(route)
+  /* 必须先于 bridge 路由：bridge 的主端点会把任意 POST 当 JSON 读取，
+   * 原始 pptx 字节不能被它先消费。 */
+  app.use(createImportRoutes({ basePath: BASE_PATH, importDir: path.join(hostDir, 'imports'), store }))
+  for (const route of createBridgeRoutes({ store, jsonP, applyOp })) app.use(route)
+
+  const tuning = getTuning()
+  const info = await app.listen({
+    port,
+    hostDir,
+    scanLimit,
+    lockFile: lockFile || path.join(hostDir, '.relay-instance.lock'),
+    strictPort,
+    allowReuse,
+    discoveryFile: '',
+    requestTimeoutMs: Number(tuning.httpRequestTimeoutMs) || 30000,
+    headersTimeoutMs: Number(tuning.httpHeadersTimeoutMs) || 10000,
+    keepAliveTimeoutMs: Number(tuning.httpKeepAliveTimeoutMs) || 5000,
+  })
+
+  if (info.reused) {
+    return { url: `${info.url}${BASE_PATH}`, editorUrl: `${info.url}/`, port: info.port, reused: true, stop: async () => {} }
+  }
+
+  try {
+    /* bridge-client 在 import 时读 PPT_BRIDGE_URL，必须先设 env 再 import tools。 */
+    process.env.PPT_BRIDGE_URL = `${info.url}${BASE_PATH}`
+
+    /* 崩溃恢复：state.json 里 seq > applied_seq 说明上一批指令未完整落盘。
+     * 用 store 的串行队列占住写锁，恢复完成前的 push 会排队而不是交叉执行。 */
+    await store.enqueue(() => replayPending({ store, jsonP, applyOp }))
+
+    let registry = null
+    try {
+      const tools = await import('./tools.mjs')
+      registry = tools.createRegistry(tools.CAPABILITIES, { enabled: capabilities, toolHost })
+    } catch (e) {
+      console.error('[ppt-workbench] 工具未装载（构建产物缺失，先跑 scripts/build-plugin.mjs）:', e.message)
+    }
+    const TOOLS = registry?.TOOLS || []
+    const TOOL_IMPL = registry?.TOOL_IMPL || {}
+    const CAPABILITIES = registry?.CAPABILITIES || []
+    mcpHandler = createMcpHandler({
+      tools: TOOLS,
+      callTool: (name, args) => {
+        if (!contractSnapshots.ok && name !== 'ppt_capabilities') {
+          throw new Error(
+            `契约快照与运行时 major 不一致，已拒绝 ${name}：${describeMismatch(contractSnapshots)}。` +
+            '请重装/升级 dsh-ppt-suite 后重试。',
+          )
+        }
+        const impl = TOOL_IMPL[name]
+        if (!impl) throw new Error('未知工具: ' + name)
+        return impl(args)
+      },
+      serverInfo: { name: 'ppt-workbench', version: PACKAGE_VERSION },
+      instructions: serverInstructions(`http://127.0.0.1:${info.port}/`, { tools: TOOLS, capabilities: CAPABILITIES }),
+      maxBodyBytes: Number(tuning.bodyLimitBytes) || 10 * 1024 * 1024,
+      maxBatch: Number(tuning.mcpBatchLimit) || 100,
+    })
+
+    writeDiscovery(hostDir, `${info.url}${BASE_PATH}`, info.port)
+    return {
+      url: `${info.url}${BASE_PATH}`,
+      editorUrl: `${info.url}/`,
+      port: info.port,
+      reused: false,
+      stop: async () => {
+        removeDiscovery(hostDir)
+        await info.stop()
+      },
+    }
+  } catch (error) {
+    /* 启动失败不能留下僵尸端口/锁/发现文件。 */
+    try { removeDiscovery(hostDir) } catch { /* 忽略 */ }
+    try { await info.stop() } catch { /* 忽略 */ }
+    throw error
+  }
+}
+
+function writeDiscovery(hostDir, url, port) {
+  try {
+    fs.mkdirSync(hostDir, { recursive: true })
+    fs.writeFileSync(path.join(hostDir, 'bridge.json'), JSON.stringify({
+      bridge: 'ppt-workbench', url, port, pid: process.pid, updated: new Date().toISOString(),
+    }, null, 2))
+  } catch { /* 发现文件写失败不影响服务 */ }
+}
+
+function removeDiscovery(hostDir) {
+  const file = path.join(hostDir, 'bridge.json')
+  try {
+    const data = JSON.parse(fs.readFileSync(file, 'utf8'))
+    if (data.pid === process.pid) fs.rmSync(file, { force: true })
+  } catch { /* 不存在或不是本进程写的 */ }
+}
+
+/* ---- 独立运行入口（无 dsh 也可手动拉起，供调试/演示）---- */
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const arg = (name, dflt) => {
+    const i = process.argv.indexOf(name)
+    return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : dflt
+  }
+  /* 独立服务形态也要接上 runtime 的 workspace：broker 拉起时继承了
+   * DSH_RUNTIME_FILE / DSH_STORE_*，relay 据此使用当前 runtime 的 store，
+   * 而不是退化成全局 ~/.dsh-ppt-bridge 文件库。 */
+  const runtime = loadRuntimeContext()
+  const workId = runtime?.workId || 'main'
+  const client = runtime ? createRuntimeStoreClient(runtime, { workId }) : null
+  const backend = client
+    ? new WorkspaceBackend({
+        client,
+        workId,
+        journalPath: runtime.paths?.logs ? path.join(runtime.paths.logs, 'ppt-journal.jsonl') : null,
+      })
+    : null
+  const relay = await startRelay({
+    port: Number(arg('--port', DEFAULT_PORT)) || DEFAULT_PORT,
+    hostDir: arg('--dir', undefined) || runtime?.paths?.contentState || undefined,
+    backend,
+  })
+  console.log('[ppt-workbench] 桥:', relay.url)
+  console.log('[ppt-workbench] 编辑器:', relay.editorUrl, '(浏览器打开即用)')
+  console.log('[ppt-workbench] MCP 端点:', relay.url.replace(BASE_PATH, '/mcp'))
+}

package/server/routes/assets.mjs

@@ -0,0 +1,2 @@
+/** 对象仓库路由统一来自 dsh-asset-service 公共插件。 */
+export { createAssetRoutes } from '../shared/asset-service.mjs'

package/server/routes/bridge.mjs

@@ -0,0 +1,47 @@
+/**
+ * PPT 桥端点：协议与路由由 dsh-document-workbench 提供，本文件只注入
+ * PPT 的 deck 投影、VIEW_OPS 与 applyOp。
+ */
+import { createDocumentBridge } from 'dsh-document-workbench/bridge'
+import { BASE_PATH, VIEW_OPS } from '../constants.mjs'
+import { getTuning } from '../tuning.mjs'
+import {
+  sanitizeAck, sanitizeClaim, sanitizePush, sanitizeShotResult, sanitizeState,
+} from '../store.mjs'
+
+export function createBridgeRoutes({ store, jsonP, applyOp }) {
+  const tuning = getTuning()
+  return createDocumentBridge({
+    session: store,
+    basePath: BASE_PATH,
+    bridgeName: 'ppt-bridge',
+    documentKey: 'deck',
+    documentPath: '/deck',
+    authority: 'server',
+    apply: (cmd) => applyOp(jsonP, cmd),
+    isViewOp: (cmd) => VIEW_OPS.has(cmd.op),
+    sanitizers: {
+      sanitizeAck,
+      sanitizeClaim,
+      sanitizePush,
+      sanitizeShotResult,
+      sanitizeState,
+    },
+    bodyLimitBytes: Number(tuning.bodyLimitBytes) || 10 * 1024 * 1024,
+    watch: {
+      pollMs: tuning.watchPollMs,
+      timeoutSec: tuning.watchTimeoutSec,
+      maxTimeoutSec: tuning.watchTimeoutMaxSec,
+    },
+    projectStatus: (doc) => ({
+      bridge: 'ppt-workbench',
+      has_deck: !!(doc.deck && Array.isArray(doc.deck.slides) && doc.deck.slides.length),
+      slides: doc.deck && Array.isArray(doc.deck.slides) ? doc.deck.slides.length : 0,
+    }),
+    projectDocument: (doc) => ({
+      deck: doc.deck || {},
+      state_seq: doc.state_seq | 0,
+      applied_seq: doc.applied_seq | 0,
+    }),
+  }).routes
+}

package/server/routes/editor.mjs

@@ -0,0 +1,9 @@
+/** 静态编辑器路由统一来自 dsh-editor-host 公共插件。 */
+import { createEditorHost as createSharedEditorHost } from '../shared/editor-host.mjs'
+import { EDITOR_FILES } from '../constants.mjs'
+
+export function createEditorRoutes({ editorDir, editorHost = null }) {
+  const factory = editorHost?.createEditorHost || createSharedEditorHost
+  const host = factory({ id: 'ppt-editor', dir: editorDir, files: EDITOR_FILES })
+  return [host.staticRoutes]
+}