@capyclaw/ppt-workbench 0.0.0-stage → 2.4.0

package/server/shared/editor-host.mjs

@@ -0,0 +1,125 @@
+/**
+ * dsh-editor-host —— 通用浏览器编辑器宿主。
+ *
+ * 功能插件只提供 editor/ 静态目录，不再自己写：
+ *   - 静态文件路由 / content-type / 404
+ *   - “显示即连接”的租约仲裁（后打开者抢占，旧窗口静默待命）
+ *   - claim / release / status / heartbeat 端点
+ *   - 连接状态供 /healthz 使用
+ *
+ * 浏览器端可直接使用 dsh-plugin-kit 的 editor/lease.mjs（无 Node 依赖）。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { createEditorLease } from './kit/editor/lease.mjs'
+import { send, readBody } from './kit/service/http.mjs'
+import { createServiceApi } from './kit/service/api.mjs'
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.woff2': 'font/woff2',
+}
+
+function safeJoin(root, rel) {
+  const target = path.resolve(root, `.${path.sep}${rel}`)
+  const base = path.resolve(root)
+  return target === base || target.startsWith(base + path.sep) ? target : null
+}
+
+function contentType(file) {
+  return MIME[path.extname(file).toLowerCase()] || 'application/octet-stream'
+}
+
+/**
+ * @param {{ id: string, dir: string, basePath?: string, index?: string, files?: Record<string,string|string[]> }} options
+ */
+export function createEditorHost({ id, dir, basePath = '', index = 'index.html', files = null } = {}) {
+  if (!id) throw new Error('createEditorHost: id 必填')
+  const prefix = basePath === '/' ? '' : String(basePath || '').replace(/\/+$/, '')
+  const lease = createEditorLease()
+
+  const staticRoutes = async function editorStatic(req, res, u) {
+    if (req.method !== 'GET' && req.method !== 'HEAD') return false
+    if (prefix && u.pathname !== prefix && !u.pathname.startsWith(prefix + '/')) return false
+    const relRaw = prefix ? u.pathname.slice(prefix.length) : u.pathname
+    const rel = relRaw === '' || relRaw === '/' ? index : decodeURIComponent(relRaw.replace(/^\/+/, ''))
+    let file = null
+    if (files) {
+      const hit = files[relRaw === '' ? '/' : relRaw] || files[relRaw]
+      if (!hit) return false
+      const name = Array.isArray(hit) ? hit[0] : hit
+      file = safeJoin(dir, name)
+    } else {
+      file = safeJoin(dir, rel)
+    }
+    if (!file) return false
+    try {
+      const data = fs.readFileSync(file)
+      res.writeHead(200, {
+        'content-type': contentType(file),
+        'content-length': data.length,
+        'x-content-type-options': 'nosniff',
+        'referrer-policy': 'no-referrer',
+        'cache-control': 'no-cache',
+      })
+      res.end(req.method === 'HEAD' ? undefined : data)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  const leaseRoutes = async function editorLeaseRoutes(req, res, u) {
+    const claimPath = `${prefix}/claim`
+    const releasePath = `${prefix}/release`
+    const statusPath = `${prefix}/status`
+    if (u.pathname === claimPath && req.method === 'POST') {
+      const body = await readBody(req)
+      const result = lease.claim(String(body.id || ''), !!body.force)
+      send(req, res, result.ok ? 200 : 409, result)
+      return true
+    }
+    if (u.pathname === releasePath && req.method === 'POST') {
+      const body = await readBody(req)
+      send(req, res, 200, lease.release(String(body.id || '')))
+      return true
+    }
+    if (u.pathname === statusPath && req.method === 'GET') {
+      send(req, res, 200, { ok: true, connected: lease.isLive(), lease: lease.status() })
+      return true
+    }
+    return false
+  }
+
+  return {
+    id,
+    lease,
+    routes() {
+      return [staticRoutes, leaseRoutes]
+    },
+    staticRoutes,
+    leaseRoutes,
+    status() {
+      return { connected: lease.isLive(), lease: lease.status() }
+    },
+  }
+}
+
+export function createEditorHostService(config = {}) {
+  return {
+    api: createServiceApi('editorHost', '1.0.0', ['static', 'lease', 'heartbeat', 'status']),
+    version: '0.1.0',
+    createEditorHost,
+    createLease: createEditorLease,
+    defaultHost: config.dir ? createEditorHost({ id: config.id || 'editor', ...config }) : null,
+  }
+}

package/server/shared/kit/editor/lease.mjs

@@ -0,0 +1,139 @@
+/**
+ * 「显示即连接」编辑器租约标准模块。
+ *
+ * 活动权（claim）只存在于内部仲裁；不要把它渲染成 UI 状态。
+ * 新打开的窗口强制抢占，旧窗口静默转入待命。
+ */
+import { tuning } from '../tuning.mjs'
+
+const DEFAULT_TTL = 15 // 秒
+const DEFAULT_HEARTBEAT = 3 // 秒（心跳间隔应小于 TTL）
+
+/**
+ * 创建编辑器租约仲裁器。
+ * @param {{ ttl?: number }} [opts]
+ */
+export function createEditorLease(opts = {}) {
+  const ttl = Number(opts.ttl) || DEFAULT_TTL
+  let owner = null // { id, ts }
+
+  return {
+    claim(id, force = false) {
+      const now = Date.now() / 1000
+      if (force || !owner || owner.id === id || now - owner.ts > ttl) {
+        owner = { id, ts: now }
+        return { ok: true, owner: id }
+      }
+      return { ok: false, owner: owner.id }
+    },
+
+    release(id) {
+      if (owner && owner.id === id) owner = null
+      return { ok: true }
+    },
+
+    isLive() {
+      return !!owner && Date.now() / 1000 - owner.ts <= ttl
+    },
+
+    status() {
+      return owner
+        ? { owner: owner.id, age: Math.round((Date.now() / 1000 - owner.ts) * 100) / 100 }
+        : null
+    },
+
+    async wait(o = {}) {
+      const { leaseWaitPollMs: pollMs, leaseWaitTimeoutMs: defaultTimeoutMs } = tuning()
+      const deadline = Date.now() + (o.timeoutMs || defaultTimeoutMs)
+      while (true) {
+        if (this.isLive()) return this.status()
+        if (Date.now() >= deadline) {
+          const hint = o.openHint ? `（打开 ${o.openHint}）` : ''
+          const panel = o.panelHint || '编辑器面板'
+          throw new Error(`${panel}尚未连接${hint}。页面加载后会自动连接，无需其他操作。`)
+        }
+        await new Promise((resolve) => setTimeout(resolve, pollMs))
+      }
+    },
+  }
+}
+
+/**
+ * 编辑器端自动挂接循环。
+ * 首次 claim 强制抢占（后打开者赢），之后静默心跳。
+ * @param {{
+ *   clientId: string,
+ *   claim: (force: boolean) => Promise<boolean>,
+ *   release?: () => void,
+ *   onActive?: () => void,
+ *   onStandby?: () => void,
+ *   retryMs?: number,
+ *   heartbeatMs?: number,
+ *   setInterval?: (cb: () => void) => any,
+ *   clearInterval?: (handle: any) => void
+ * }} o
+ */
+export function startAutoAttach(o) {
+  if (!o || !o.clientId) throw new Error('startAutoAttach: clientId 必填')
+  if (typeof o.claim !== 'function') throw new Error('startAutoAttach: claim 必须是函数')
+
+  const retryMs = o.retryMs || 1000
+  const heartbeatMs = o.heartbeatMs || DEFAULT_HEARTBEAT * 1000
+  const setI = o.setInterval || ((cb) => setInterval(cb, heartbeatMs))
+  const clearI = o.clearInterval || ((handle) => clearInterval(handle))
+
+  let active = false
+  let heartbeat = null
+  let disposed = false
+
+  async function tryClaim(force) {
+    try {
+      return await o.claim(force)
+    } catch {
+      return false
+    }
+  }
+
+  function goActive() {
+    if (active) return
+    active = true
+    try { o.onActive && o.onActive() } catch { /* 用户回调失败不阻塞挂接 */ }
+    heartbeat = setI(async () => {
+      if (disposed) return
+      const ok = await tryClaim(false)
+      if (!ok) goStandby()
+    })
+  }
+
+  function goStandby() {
+    if (!active) return
+    active = false
+    if (heartbeat != null) {
+      clearI(heartbeat)
+      heartbeat = null
+    }
+    try { o.onStandby && o.onStandby() } catch { /* 静默 */ }
+  }
+
+  ;(async () => {
+    let first = true
+    while (!disposed) {
+      const ok = await tryClaim(first)
+      first = false
+      if (ok) {
+        goActive()
+        return
+      }
+      await new Promise((resolve) => setTimeout(resolve, retryMs))
+    }
+  })()
+
+  return {
+    get active() { return active },
+    dispose() {
+      disposed = true
+      goStandby()
+      try { o.release && o.release() } catch { /* 释放失败不阻塞退出 */ }
+    },
+  }
+}

package/server/shared/kit/service/api.mjs

@@ -0,0 +1,45 @@
+/** 公共服务 API 契约：插件之间只通过这份描述判断兼容性。 */
+
+/**
+ * @param {string} name 服务名（ctx.<name>）
+ * @param {string} version API 版本（semver；major 变化 = 不兼容）
+ * @param {string[]} capabilities 能力标签
+ */
+export function createServiceApi(name, version = '1.0.0', capabilities = []) {
+  if (!name) throw new Error('createServiceApi 需要 name')
+  return Object.freeze({
+    name,
+    version,
+    capabilities: Object.freeze([...capabilities]),
+  })
+}
+
+/**
+ * 断言一个已注入的服务对象满足消费者要求。
+ * 缺失服务或 major 不一致时抛出明确错误，避免“看起来能跑”的静默不兼容。
+ * @param {object} service
+ * @param {{ name: string, major?: number|string, version?: string }} expected
+ */
+export function assertServiceApi(service, expected = {}) {
+  const name = expected.name
+  if (!name) throw new Error('assertServiceApi 需要 expected.name')
+  const major = String(expected.major ?? String(expected.version || '1').split('.')[0])
+  if (!service) throw new Error(`缺少公共服务: ctx.${name}`)
+  const api = service.api
+  if (!api || typeof api !== 'object') {
+    throw new Error(`服务 ctx.${name} 没有声明 api 契约；请升级提供方插件`)
+  }
+  if (api.name !== name) {
+    throw new Error(`服务 ctx.${name} 的 api.name=${api.name}，与消费者期望的 ${name} 不一致`)
+  }
+  const gotMajor = String(api.version || '').split('.')[0]
+  if (gotMajor !== major) {
+    throw new Error(`服务 ctx.${name} API major=${gotMajor}，消费者要求 major=${major}（提供方版本 ${api.version}）`)
+  }
+  return api
+}
+
+export function serviceApiSummary(service) {
+  const api = service?.api
+  return api ? { name: api.name, version: api.version, capabilities: [...(api.capabilities || [])] } : null
+}

package/server/shared/kit/service/http.mjs

@@ -0,0 +1,113 @@
+/** 本机插件 HTTP 传输：安全响应头、body 上限、查询解析、loopback 监听。 */
+import http from 'node:http'
+import { tuning } from '../tuning.mjs'
+
+export const SECURITY_HEADERS = {
+  'x-content-type-options': 'nosniff',
+  'referrer-policy': 'no-referrer',
+  'cache-control': 'no-store, no-cache, must-revalidate',
+}
+
+/** 客户端已断开时放弃写入：长请求（截图/长轮询）在 handler 完成前客户端超时
+ * 断连是常态，写已销毁的 socket 会触发无人监听的 'error' 事件打崩进程。 */
+function resDead(res) {
+  return res.destroyed || res.writableEnded
+}
+
+export function send(req, res, code, obj, extraHeaders = {}) {
+  if (resDead(res)) return
+  const body = obj === undefined ? '' : JSON.stringify(obj)
+  try {
+    res.writeHead(code, {
+      'content-type': 'application/json',
+      'content-length': Buffer.byteLength(body),
+      ...SECURITY_HEADERS,
+      ...extraHeaders,
+    })
+    res.end(req.method === 'HEAD' ? undefined : body)
+  } catch { /* socket 已死：响应无人接收，静默放弃 */ }
+}
+
+export function sendText(req, res, code, text, contentType = 'text/plain; charset=utf-8', extraHeaders = {}) {
+  if (resDead(res)) return
+  const body = text === undefined || text === null ? '' : String(text)
+  try {
+    res.writeHead(code, {
+      'content-type': contentType,
+      'content-length': Buffer.byteLength(body),
+      ...SECURITY_HEADERS,
+      ...extraHeaders,
+    })
+    res.end(req.method === 'HEAD' ? undefined : body)
+  } catch { /* socket 已死：响应无人接收，静默放弃 */ }
+}
+
+function bodyError(code, message) {
+  const error = new Error(message)
+  error.code = code
+  return error
+}
+
+export function readBody(req, limit = 10 * 1024 * 1024) {
+  return new Promise((resolve, reject) => {
+    let size = 0
+    const chunks = []
+    let settled = false
+    const fail = (error) => {
+      if (settled) return
+      settled = true
+      reject(error)
+    }
+    req.on('data', (chunk) => {
+      if (settled) return
+      size += chunk.length
+      if (size > limit) {
+        /* 先让路由回 413；立即 destroy 会让客户端只看到 connection reset。 */
+        fail(bodyError('BODY_TOO_LARGE', 'body too large'))
+        req.resume()
+        return
+      }
+      chunks.push(chunk)
+    })
+    req.on('end', () => {
+      if (settled) return
+      settled = true
+      const raw = Buffer.concat(chunks).toString('utf8')
+      if (!raw) return resolve({})
+      try { resolve(JSON.parse(raw)) } catch { reject(bodyError('BAD_JSON', 'bad json')) }
+    })
+    req.on('error', (error) => fail(error))
+    /* 客户端中途断连且未触发 error/aborted 时（如 curl -m 超时），close 兜底，
+       否则 promise 永远 pending，handler 泄漏。 */
+    req.on('close', () => {
+      if (!req.readableEnded) fail(bodyError('CLIENT_ABORTED', 'client aborted'))
+    })
+  })
+}
+
+export function intQ(url, name) {
+  const value = parseInt(url.searchParams.get(name) || '0', 10)
+  return Number.isFinite(value) && value >= 0 ? value : 0
+}
+
+export function listen(port, opts = {}) {
+  const defaults = tuning()
+  const {
+    host = '127.0.0.1',
+    requestTimeoutMs = defaults.requestTimeoutMs,
+    headersTimeoutMs = defaults.headersTimeoutMs,
+    keepAliveTimeoutMs = defaults.keepAliveTimeoutMs,
+    handler,
+  } = opts
+  return new Promise((resolve, reject) => {
+    const server = handler ? http.createServer(handler) : http.createServer()
+    server.requestTimeout = requestTimeoutMs
+    server.headersTimeout = headersTimeoutMs
+    server.keepAliveTimeout = keepAliveTimeoutMs
+    server.on('clientError', (error, socket) => {
+      if (socket.writable) socket.end('HTTP/1.1 400 Bad Request\r\n\r\n')
+    })
+    server.on('error', reject)
+    server.listen(port, host, () => resolve(server))
+  })
+}

package/server/shared/kit/service/mcp-http.mjs

@@ -0,0 +1,142 @@
+/**
+ * 通用 MCP Streamable HTTP 处理器。
+ *
+ * 只实现工具面所需的最小协议：initialize / ping / tools/list / tools/call。
+ * 所有工具调用在进入业务实现前先经过 validateToolArguments。
+ */
+import { readBody, send } from './http.mjs'
+import { validateToolArguments } from '../tools/validate.mjs'
+
+const DEFAULT_PROTOCOL = '2024-11-05'
+
+function rpcError(id, code, message, data) {
+  const error = { code, message }
+  if (data !== undefined) error.data = data
+  return { jsonrpc: '2.0', id: id ?? null, error }
+}
+
+function reply(id, result) {
+  return { jsonrpc: '2.0', id, result }
+}
+
+export function createMcpHandler({
+  tools = [], callTool, serverInfo, instructions,
+  maxBodyBytes = 10 * 1024 * 1024, maxBatch = 100,
+} = {}) {
+  if (!Array.isArray(tools)) throw new Error('createMcpHandler: tools 必须是数组')
+  if (typeof callTool !== 'function') throw new Error('createMcpHandler: callTool 必须是函数')
+
+  const toolMap = new Map(tools.map((tool) => [tool.name, tool]))
+
+  return async function handle(req, res) {
+    /* 长工具调用（如截图）期间客户端可能超时断连；socket 的 'error' 事件
+       无人监听会打崩进程。挂空处理器，配合 send() 的断连防护。 */
+    res.on('error', () => {})
+    if (req.method !== 'POST') {
+      if (res.destroyed) return
+      res.writeHead(405, { allow: 'POST', 'content-type': 'text/plain; charset=utf-8' })
+      return res.end('MCP endpoint: POST only')
+    }
+
+    let msg
+    try {
+      msg = await readBody(req, maxBodyBytes)
+    } catch (error) {
+      if (error?.code === 'BODY_TOO_LARGE') {
+        return send(req, res, 413, rpcError(null, -32600, 'Request body too large'))
+      }
+      return send(req, res, 400, rpcError(null, -32700, 'Parse error'))
+    }
+
+    if (!msg || typeof msg !== 'object') {
+      return send(req, res, 400, rpcError(null, -32600, 'Invalid Request'))
+    }
+
+    const batch = Array.isArray(msg)
+    if (batch && msg.length === 0) {
+      return send(req, res, 400, rpcError(null, -32600, 'Invalid Request'))
+    }
+    if (batch && msg.length > maxBatch) {
+      return send(req, res, 400, rpcError(null, -32600, `Batch too large (max ${maxBatch})`))
+    }
+    const messages = batch ? msg : [msg]
+    const replies = []
+    for (const message of messages) {
+      const result = await handleOne(message, req)
+      if (result !== null) replies.push(result)
+    }
+    if (!replies.length) {
+      if (res.destroyed) return
+      res.writeHead(202, { 'content-length': 0 })
+      return res.end()
+    }
+    return send(req, res, 200, batch ? replies : replies[0])
+  }
+
+  async function handleOne(message, req) {
+    if (!message || typeof message !== 'object' || Array.isArray(message)) {
+      return rpcError(null, -32600, 'Invalid Request')
+    }
+
+    const { id, method, params } = message
+    const isNotification = id === undefined || id === null
+
+    if (typeof method !== 'string' || !method) {
+      return isNotification ? null : rpcError(id, -32600, 'Invalid Request')
+    }
+
+    if (method === 'initialize') {
+      const result = {
+        protocolVersion: String(params?.protocolVersion || DEFAULT_PROTOCOL),
+        capabilities: { tools: { listChanged: false } },
+        serverInfo: serverInfo || { name: 'dsh-plugin', version: '0.0.0' },
+      }
+      if (typeof instructions === 'string' && instructions) result.instructions = instructions
+      return isNotification ? null : reply(id, result)
+    }
+
+    if (method === 'notifications/initialized' || method === 'initialized') return null
+    if (method === 'notifications/cancelled' || method === 'notifications/cancel') return null
+    if (method === 'ping') return isNotification ? null : reply(id, {})
+
+    if (method === 'tools/list') {
+      return isNotification ? null : reply(id, { tools })
+    }
+
+    if (method === 'tools/call') {
+      const name = params?.name
+      const args = params?.arguments && typeof params.arguments === 'object' ? params.arguments : {}
+      const tool = toolMap.get(name)
+      if (!tool) {
+        if (isNotification) return null
+        return reply(id, {
+          content: [{ type: 'text', text: `未知工具: ${String(name)}` }],
+          isError: true,
+        })
+      }
+
+      const check = validateToolArguments(tool, args)
+      if (!check.ok) {
+        if (isNotification) return null
+        return reply(id, {
+          content: [{ type: 'text', text: '参数不合法：' + check.errors.join('；') }],
+          isError: true,
+        })
+      }
+
+      try {
+        const out = await callTool(name, args, { req })
+        if (out && Array.isArray(out.content)) return reply(id, out)
+        return reply(id, { content: [{ type: 'text', text: out?.text || 'ok' }] })
+      } catch (error) {
+        if (isNotification) return null
+        return reply(id, {
+          content: [{ type: 'text', text: '工具失败：' + String((error && error.message) || error) }],
+          isError: true,
+        })
+      }
+    }
+
+    return isNotification ? null : rpcError(id, -32601, `Method not found: ${method}`)
+  }
+}

package/server/shared/kit/service/single-instance.mjs

@@ -0,0 +1,72 @@
+/** 单实例锁：同一时间只允许一个本机插件实例持有锁。 */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const LOCK_FILE = path.join(HERE, '.plugin-instance.lock');
+
+export function acquireLock(lockFile = LOCK_FILE) {
+  try {
+    // 检查锁文件是否存在
+    if (fs.existsSync(lockFile)) {
+      const lockData = JSON.parse(fs.readFileSync(lockFile, 'utf8'));
+      const { pid, timestamp, port } = lockData;
+      
+      // 检查进程是否还活着（Windows）
+      try {
+        process.kill(pid, 0); // 信号 0 只检测不杀
+        const age = Date.now() - timestamp;
+        if (age < 60000) {
+          // 进程活着且锁文件不到 1 分钟
+          console.error(`✗ 另一个插件实例正在运行 (PID ${pid}, 端口 ${port})`);
+          console.error(`如果确认没有运行，删除: ${lockFile}`);
+          return false;
+        }
+      } catch (e) {
+        // 进程已死，清理旧锁
+        console.log(`清理过期锁文件 (PID ${pid} 已不存在)`);
+        fs.unlinkSync(lockFile);
+      }
+    }
+    
+    return true;
+  } catch (e) {
+    console.error('获取锁失败:', e);
+    return false;
+  }
+}
+
+export function writeLock(port, lockFile = LOCK_FILE) {
+  try {
+    // 写入锁文件
+    fs.mkdirSync(path.dirname(lockFile), { recursive: true });
+    fs.writeFileSync(lockFile, JSON.stringify({
+      pid: process.pid,
+      port,
+      timestamp: Date.now(),
+    }));
+    
+    // 进程退出时清理
+    const cleanup = () => {
+      try {
+        if (fs.existsSync(lockFile)) {
+          const data = JSON.parse(fs.readFileSync(lockFile, 'utf8'));
+          if (data.pid === process.pid) {
+            fs.unlinkSync(lockFile);
+          }
+        }
+      } catch (e) { /* 忽略清理失败 */ }
+    };
+    
+    process.on('exit', cleanup);
+    process.on('SIGINT', () => { cleanup(); process.exit(0); });
+    process.on('SIGTERM', () => { cleanup(); process.exit(0); });
+    process.on('uncaughtException', (e) => { console.error('未捕获异常:', e); cleanup(); process.exit(1); });
+    
+    return true;
+  } catch (e) {
+    console.error('写入锁失败:', e);
+    return false;
+  }
+}