@capyclaw/ppt-workbench 0.0.0-stage → 2.4.0

package/server/shared/state-service.mjs

@@ -0,0 +1,249 @@
+/**
+ * dsh-state-service —— 插件运行状态标准件。
+ *
+ * 提供：
+ *   - FileStateBackend：原子 JSON 状态 + append-only journal（2MB 轮转）+ 命名 checkpoint
+ *   - PersistentStore：在任意 backend 上的通用状态门面
+ *   - replayPending：崩溃后重放未完成批次
+ *
+ * 与 workspace-service 的分工：
+ *   workspace 管“作品文件”（work manifest / 版本 / 归属）；
+ *   state 管“插件运行状态”（doc / journal / checkpoint / recovery）。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { createServiceApi } from './kit/service/api.mjs'
+
+export class FileStateBackend {
+  /* journalMaxBytes 默认 512KB 由 NSGA-II 进化搜索固化（evolution/，2026-11-01）：
+   * 尾读 p95 4.3→1.9ms、磁盘占用 -33%、追加吞吐 +8%，恢复 0 失败。
+   *
+   * fsyncEvery 默认 16：状态写是「write tmp → rename」的原子替换，进程崩溃时
+   * 页缓存中的数据已对其它进程可见（rename 原子），只有掉电才需要 fsync 保证落盘。
+   * 实测每写一次 fsync 使 157KB 状态从 0.67ms 涨到 1.80ms（+1.13ms），而
+   * document-workbench 每个编辑批次会写 2 次状态——节流到每 16 次写一次 fsync，
+   * 把该链路成本从 ~3.6ms/批降到 ~1.5ms/批；checkpoint 仍强制 fsync（里程碑语义）。
+   * 设为 1 恢复「每次写都 fsync」的旧行为；设为 0 则完全不做 fsync。 */
+  constructor(file, { initialDoc = {}, journalMaxBytes = 512 * 1024, fsyncEvery = 16 } = {}) {
+    if (!file) throw new Error('FileStateBackend 需要 file')
+    this.file = file
+    this.dir = path.dirname(file)
+    this.journalFile = path.join(this.dir, 'journal.jsonl')
+    this.checkpointDir = path.join(this.dir, 'checkpoints')
+    this.initialDoc = initialDoc
+    this.journalMaxBytes = Math.max(64 * 1024, Number(journalMaxBytes) || 512 * 1024)
+    this.fsyncEvery = Math.max(0, Number(fsyncEvery) || 0)
+    this._writeCount = 0
+    /** 最近一次读状态失败的原因；ENOENT 不算错误。 */
+    this.lastStateError = null
+  }
+
+  readState() {
+    let raw
+    try {
+      raw = fs.readFileSync(this.file, 'utf8')
+    } catch (error) {
+      if (error.code === 'ENOENT') return null
+      this.lastStateError = { code: 'STATE_IO', message: error.message }
+      return null
+    }
+    try {
+      const parsed = JSON.parse(raw)
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        return { ...structuredClone(this.initialDoc), ...parsed }
+      }
+      throw new Error('state 根节点不是 object')
+    } catch (error) {
+      /* 坏状态不能静默当成空库：先隔离原文件，避免下一次保存直接覆盖证据。 */
+      this.lastStateError = { code: 'STATE_CORRUPT', message: error.message }
+      const quarantine = `${this.file}.corrupt-${Date.now()}`
+      try { fs.renameSync(this.file, quarantine) } catch { /* 隔离失败也要保持只读语义 */ }
+      console.error(`[state-service] state 损坏，已隔离到 ${quarantine}: ${error.message}`)
+      return null
+    }
+  }
+
+  /** 强制把当前状态文件刷盘（checkpoint/退出等里程碑用；失败不抛）。 */
+  flush() {
+    try {
+      const fd = fs.openSync(this.file, 'r+')
+      try { fs.fsyncSync(fd) } finally { fs.closeSync(fd) }
+    } catch { /* 文件不存在或文件系统不支持 fsync */ }
+  }
+
+  writeState(doc) {
+    fs.mkdirSync(path.dirname(this.file), { recursive: true })
+    const tmp = `${this.file}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`
+    fs.writeFileSync(tmp, JSON.stringify(doc))
+    this._writeCount += 1
+    /* fsyncEvery=0 → 从不周期刷盘；=1 → 每次刷盘（旧行为）；=N → 每 N 次写刷一次。 */
+    const due = this.fsyncEvery > 0 && (this.fsyncEvery === 1 || this._writeCount % this.fsyncEvery === 0)
+    if (due) {
+      try {
+        const fd = fs.openSync(tmp, 'r+')
+        try { fs.fsyncSync(fd) } finally { fs.closeSync(fd) }
+      } catch { /* fsync 在部分文件系统不可用 */ }
+    }
+    fs.renameSync(tmp, this.file)
+  }
+
+  appendJournal(event) {
+    try {
+      fs.mkdirSync(this.dir, { recursive: true })
+      fs.appendFileSync(this.journalFile, JSON.stringify({ ...event, ts: Date.now() / 1000 }) + '\n')
+      if (fs.statSync(this.journalFile).size > this.journalMaxBytes) {
+        const rotated = this.journalFile + '.1'
+        try { fs.rmSync(rotated, { force: true }) } catch { /* 忽略 */ }
+        try { fs.renameSync(this.journalFile, rotated) } catch (error) {
+          console.error('[state-service] journal 轮转失败（继续追加）:', error.message)
+        }
+      }
+    } catch { /* journal 失败不阻塞主状态 */ }
+  }
+
+  journalTail(limit = 8) {
+    const read = (file) => {
+      try {
+        return fs.readFileSync(file, 'utf8').trim().split(/\r?\n/).filter(Boolean)
+      } catch { return [] }
+    }
+    /* 轮转后的 .1 仍是最近历史的一部分，tail 必须跨文件读取。 */
+    const lines = [...read(this.journalFile + '.1'), ...read(this.journalFile)]
+    return lines.slice(-limit).map((line) => {
+      try { return JSON.parse(line) } catch { return { type: 'invalid', raw: line.slice(0, 120) } }
+    })
+  }
+
+  writeCheckpoint(name, payload) {
+    const safe = checkpointName(name)
+    fs.mkdirSync(this.checkpointDir, { recursive: true })
+    const file = path.join(this.checkpointDir, safe + '.json')
+    const tmp = `${file}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`
+    fs.writeFileSync(tmp, JSON.stringify(payload))
+    /* checkpoint 是恢复里程碑：无视 fsyncEvery 节流，强制落盘。 */
+    try {
+      const fd = fs.openSync(tmp, 'r+')
+      try { fs.fsyncSync(fd) } finally { fs.closeSync(fd) }
+    } catch { /* fsync 在部分文件系统不可用 */ }
+    fs.renameSync(tmp, file)
+  }
+
+  listCheckpoints() {
+    try {
+      return fs.readdirSync(this.checkpointDir)
+        .filter((name) => name.endsWith('.json'))
+        .map((name) => {
+          try {
+            const payload = JSON.parse(fs.readFileSync(path.join(this.checkpointDir, name), 'utf8'))
+            return {
+              name: payload.name,
+              seq: payload.seq,
+              appliedSeq: payload.appliedSeq,
+              pending: !!payload.pending,
+              title: payload.title,
+              slides: payload.slides,
+              createdAt: payload.createdAt,
+              meta: payload.meta || {},
+            }
+          } catch { return null }
+        })
+        .filter(Boolean)
+        .sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)))
+    } catch { return [] }
+  }
+
+  readCheckpoint(name) {
+    return JSON.parse(fs.readFileSync(path.join(this.checkpointDir, checkpointName(name) + '.json'), 'utf8'))
+  }
+}
+
+export function checkpointName(name) {
+  const safe = String(name || '')
+  if (!/^[a-zA-Z0-9._-]{1,64}$/.test(safe)) throw new Error('checkpoint 名称必须是 1-64 位字母/数字/._-')
+  return safe
+}
+
+/** 通用状态门面：业务 store 可以继承它，只写领域方法。 */
+export class PersistentStore {
+  constructor({ backend, initialDoc = {} }) {
+    if (!backend) throw new Error('PersistentStore 需要 backend')
+    this.backend = backend
+    this.doc = backend.readState() || { ...structuredClone(initialDoc) }
+  }
+
+  get() { return this.doc }
+
+  save() {
+    this.backend.writeState(this.doc)
+    return this.doc
+  }
+
+  journal(event) {
+    this.backend.appendJournal(event)
+  }
+
+  journalTail(limit = 8) {
+    return this.backend.journalTail(limit)
+  }
+
+  checkpoint(name, payload, meta = {}) {
+    const safe = checkpointName(name)
+    const body = {
+      name: safe,
+      ...payload,
+      meta: meta && typeof meta === 'object' ? meta : {},
+      createdAt: new Date().toISOString(),
+    }
+    this.backend.writeCheckpoint(safe, body)
+    this.journal({ type: 'checkpoint', name: safe })
+    return body
+  }
+
+  listCheckpoints() {
+    return this.backend.listCheckpoints()
+  }
+
+  readCheckpoint(name) {
+    return this.backend.readCheckpoint(name)
+  }
+}
+
+/**
+ * 崩溃恢复：把未完成批次交给 apply 重放，然后回执。
+ * @param {{ store: object, pending: () => any, apply: (cmd:any) => Promise<void>|void }} options
+ */
+export async function replayPending({ store, pending, apply }) {
+  const item = pending()
+  if (!item) return { recovered: 0, seq: 0, error: '' }
+  let recovered = 0
+  let error = ''
+  for (const cmd of item.cmds || []) {
+    try {
+      await apply(cmd)
+      recovered++
+    } catch (e) {
+      error = String((e && e.message) || e)
+      break
+    }
+  }
+  store.applyServer(item.seq, recovered, error)
+  return { seq: item.seq, recovered, error }
+}
+
+export function createFileBackend(file, options = {}) {
+  return new FileStateBackend(file, options)
+}
+
+export function createStateHost(config = {}) {
+  return {
+    api: createServiceApi('state', '1.0.0', ['file-backend', 'journal', 'checkpoint', 'recovery']),
+    version: '0.1.0',
+    FileStateBackend,
+    PersistentStore,
+    createFileBackend,
+    createStore({ backend, initialDoc = config.initialDoc || {} }) {
+      return new PersistentStore({ backend, initialDoc })
+    },
+    replayPending,
+  }
+}

package/server/shared/tool-host.mjs

@@ -0,0 +1,341 @@
+/**
+ * dsh-tool-host —— 工具面标准件。
+ *
+ * 把“能力声明 → 注册表 → 工具 schema/实现 → 契约报告 → MCP 协议壳”收成一套：
+ *   defineTool / defineCapability / createRegistry / createMcpHandler /
+ *   createCapabilityReport / buildInstructions
+ *
+ * 功能插件只写业务能力，不再复制 kernel/registry/dispatch/validate/contract。
+ */
+import { createMcpHandler as createKitMcpHandler } from './kit/service/mcp-http.mjs'
+import { validateToolArguments } from './kit/tools/validate.mjs'
+import { createServiceApi } from './kit/service/api.mjs'
+
+const KINDS = new Set(['read', 'write', 'control'])
+
+export function defineTool({
+  name,
+  description = '',
+  inputSchema = { type: 'object', properties: {}, additionalProperties: false },
+  kind = 'write',
+  since = '1.0.0',
+  handler,
+} = {}) {
+  if (!name || typeof name !== 'string') throw new Error('defineTool 需要 name')
+  if (typeof handler !== 'function') throw new Error(`工具 ${name} 需要 handler`)
+  if (!KINDS.has(kind)) throw new Error(`工具 ${name} 的 kind 非法: ${kind}`)
+  return Object.freeze({ name, description, inputSchema, kind, since, handler })
+}
+
+export function defineCapability({
+  id,
+  title,
+  description = '',
+  tags = [],
+  requires = [],
+  dependsOn = [],
+  provides = {},
+  features = [],
+  tools = [],
+} = {}) {
+  if (!id || typeof id !== 'string') throw new Error('defineCapability 需要 id')
+  if (!Array.isArray(tools) || !tools.length) throw new Error(`能力 ${id} 至少需要一个工具`)
+  return Object.freeze({
+    id,
+    title: title || id,
+    description,
+    tags: Object.freeze([...tags]),
+    requires: Object.freeze([...requires]),
+    dependsOn: Object.freeze([...dependsOn]),
+    provides: Object.freeze({ ...provides }),
+    features: Object.freeze([...features]),
+    tools: Object.freeze([...tools]),
+  })
+}
+
+function validateCapabilities(capabilities) {
+  const ids = new Set()
+  const toolNames = new Set()
+  for (const cap of capabilities) {
+    if (ids.has(cap.id)) throw new Error(`重复的 capability id: ${cap.id}`)
+    ids.add(cap.id)
+    for (const tool of cap.tools) {
+      if (toolNames.has(tool.name)) throw new Error(`重复的工具名: ${tool.name}`)
+      toolNames.add(tool.name)
+    }
+  }
+  for (const cap of capabilities) {
+    for (const dep of cap.dependsOn) {
+      if (!ids.has(dep)) throw new Error(`能力 ${cap.id} 依赖不存在的能力: ${dep}`)
+    }
+  }
+}
+
+function selectCapabilities(capabilities, enabled) {
+  if (!enabled || !enabled.length) return capabilities
+  const byId = new Map(capabilities.map((cap) => [cap.id, cap]))
+  for (const id of enabled) {
+    if (!byId.has(id)) throw new Error(`enabled 里有未知能力: ${id}`)
+  }
+  const ids = new Set(enabled)
+  let changed = true
+  while (changed) {
+    changed = false
+    for (const cap of capabilities) {
+      if (!ids.has(cap.id)) continue
+      for (const dep of cap.dependsOn) {
+        if (!ids.has(dep)) { ids.add(dep); changed = true }
+      }
+    }
+  }
+  return capabilities.filter((cap) => ids.has(cap.id))
+}
+
+/**
+ * @param {Array} capabilities
+ * @param {{ enabled?: string[], ports?: object, report?: Function, reserved?: string[] }} options
+ */
+export function createRegistry(capabilities, { enabled = null, ports = null, report = null, reserved = [] } = {}) {
+  validateCapabilities(capabilities)
+  const selected = selectCapabilities(capabilities, enabled)
+
+  const kernelPorts = { ...(ports || {}) }
+  const reservedNames = new Set([...(reserved || []), 'contract'])
+  const providers = new Map()
+  for (const cap of selected) {
+    for (const [ns, api] of Object.entries(cap.provides || {})) {
+      if (reservedNames.has(ns)) throw new Error(`能力 ${cap.id} 不能覆盖内核端口: ${ns}`)
+      if (providers.has(ns)) throw new Error(`服务命名空间重复: ${ns}（${providers.get(ns).cap.id} / ${cap.id}）`)
+      providers.set(ns, { cap, api })
+    }
+  }
+
+  const available = new Set([...Object.keys(kernelPorts), ...reservedNames, ...providers.keys()])
+  for (const cap of selected) {
+    for (const req of cap.requires) {
+      if (!available.has(req)) throw new Error(`能力 ${cap.id} 需要未提供的端口/服务: ${req}`)
+    }
+  }
+
+  const ctx = { ...kernelPorts }
+  for (const [ns, { api }] of providers) {
+    ctx[ns] = {}
+    for (const [method, fn] of Object.entries(api)) {
+      if (typeof fn !== 'function') throw new Error(`服务 ${ns}.${method} 必须是函数`)
+      ctx[ns][method] = (...args) => fn(ctx, ...args)
+    }
+  }
+
+  const TOOLS = []
+  const TOOL_IMPL = {}
+  const TOOL_META = {}
+  const FEATURES = []
+  const CAPABILITIES = []
+
+  for (const cap of selected) {
+    for (const feature of cap.features) {
+      if (!FEATURES.includes(feature)) FEATURES.push(feature)
+    }
+    CAPABILITIES.push({
+      id: cap.id,
+      title: cap.title,
+      description: cap.description,
+      tags: [...cap.tags],
+      tools: cap.tools.map((tool) => tool.name),
+    })
+    for (const tool of cap.tools) {
+      TOOLS.push({ name: tool.name, description: tool.description, inputSchema: tool.inputSchema })
+      TOOL_META[tool.name] = { kind: tool.kind, since: tool.since, capability: cap.id }
+      TOOL_IMPL[tool.name] = (args) => tool.handler(args || {}, ctx)
+    }
+  }
+
+  const reportFn = report || createCapabilityReport
+  ctx.contract = {
+    report: (editorUrl = '', runtime = {}) => reportFn({
+      tools: TOOLS,
+      toolMeta: TOOL_META,
+      features: FEATURES,
+      capabilities: CAPABILITIES,
+      editorUrl,
+      runtime,
+    }),
+  }
+
+  return { TOOLS, TOOL_IMPL, TOOL_META, FEATURES, CAPABILITIES, ctx }
+}
+
+/** 与 MCP 工具面解耦：调用前统一校验。 */
+export function createToolDispatcher({ tools, callTool }) {
+  const toolMap = new Map((tools || []).map((tool) => [tool.name, tool]))
+  return {
+    listTools() {
+      return { tools }
+    },
+    async callTool(name, args = {}) {
+      const tool = toolMap.get(name)
+      if (!tool) {
+        return { content: [{ type: 'text', text: `未知工具: ${String(name)}` }], isError: true }
+      }
+      const check = validateToolArguments(tool, args)
+      if (!check.ok) {
+        return { content: [{ type: 'text', text: '参数不合法：' + check.errors.join('；') }], isError: true }
+      }
+      const out = await callTool(name, args)
+      if (out && out.content) return out
+      return { content: [{ type: 'text', text: out?.text || 'ok' }] }
+    },
+  }
+}
+
+/**
+ * MCP Streamable HTTP 处理器。registry 可直接传 createRegistry 的返回值。
+ * 兼容两种调用：
+ *   { registry } 或 { tools, toolImpl }
+ *   { tools, callTool }（旧 relay 形态）
+ * @param {{ registry?: object, tools?: Array, toolImpl?: object, callTool?: Function, serverInfo?: object, instructions?: string }} options
+ */
+export function createMcpHandler({ registry, tools, toolImpl, callTool, serverInfo, instructions } = {}) {
+  const list = tools || registry?.TOOLS || []
+  const impl = toolImpl || registry?.TOOL_IMPL || null
+  if (!Array.isArray(list) || !list.length) throw new Error('createMcpHandler: 没有工具可暴露')
+  if (!impl && typeof callTool !== 'function') throw new Error('createMcpHandler: 需要 toolImpl 或 callTool')
+  return createKitMcpHandler({
+    tools: list,
+    callTool: (name, args, context) => {
+      if (typeof callTool === 'function' && !impl) return callTool(name, args, context)
+      const fn = impl[name]
+      if (!fn) throw new Error(`未知工具: ${name}`)
+      return fn(args, context)
+    },
+    serverInfo: serverInfo || { name: 'dsh-tool-host', version: '0.1.0' },
+    instructions,
+  })
+}
+
+export function createCapabilityReport({
+  tools = [],
+  toolMeta = {},
+  features = [],
+  capabilities = [],
+  contractVersion = '1.0.0',
+  packageVersion = '0.0.0',
+  editorUrl = '',
+  runtime = {},
+} = {}) {
+  return {
+    contractVersion,
+    packageVersion,
+    editorUrl,
+    ...runtime,
+    toolCount: tools.length,
+    tools: tools.map((tool) => ({
+      name: tool.name,
+      kind: toolMeta[tool.name]?.kind ?? 'write',
+      since: toolMeta[tool.name]?.since ?? '1.0.0',
+      capability: toolMeta[tool.name]?.capability ?? '',
+    })),
+    features,
+    capabilities: capabilities.map((cap) => ({
+      id: cap.id,
+      title: cap.title,
+      description: cap.description || '',
+      tags: cap.tags || [],
+      tools: cap.tools || [],
+    })),
+  }
+}
+
+/**
+ * 生成 MCP server instructions（≤32KB）。业务只提供数据，不再手写排版。
+ */
+export function buildInstructions({
+  title = '',
+  intro = '',
+  startup = [],
+  capabilities = [],
+  tools = [],
+  rules = [],
+  output = [],
+} = {}) {
+  const rows = capabilities.length
+    ? capabilities.map((cap) => `| ${cap.title} | ${cap.tools.map((name) => `\`${name}\``).join(', ')} | ${cap.description || ''} |`)
+    : [{
+      title: '工具',
+      tools: tools.map((tool) => tool.name),
+      description: '',
+    }].map((cap) => `| ${cap.title} | ${cap.tools.map((name) => `\`${name}\``).join(', ')} | |`)
+
+  const lines = []
+  if (title) lines.push(`# ${title}`, '')
+  if (intro) lines.push(intro, '')
+  if (startup.length) {
+    lines.push('## 启动检查')
+    startup.forEach((line, index) => lines.push(`${index + 1}. ${line}`))
+    lines.push('')
+  }
+  lines.push('## 能力面', '| 能力 | 工具 | 用途 |', '|---|---|---|', ...rows, '')
+  if (rules.length) {
+    lines.push('## 硬规则')
+    rules.forEach((line) => lines.push(`- ${line}`))
+    lines.push('')
+  }
+  if (output.length) {
+    lines.push('## 输出')
+    output.forEach((line) => lines.push(`- ${line}`))
+  }
+  return lines.join('\n')
+}
+
+/**
+ * 把能力注册表直接注册到 DSH 的 ctx.tools（同进程原生工具面）。
+ * 注册后不再需要单独的 loopback /mcp 端口和 @deepseek-ai/dsh-mcp-client row。
+ * @param {object} ctx DSH cordis context
+ * @param {object} registry createRegistry() 的返回值
+ * @param {{ namespace?: string }} options
+ * @returns {() => void} 反注册全部工具
+ */
+export function registerWithDsh(ctx, registry, { namespace = '' } = {}) {
+  if (!ctx?.tools?.register) throw new Error('registerWithDsh: 当前 DSH 没有 ctx.tools.register')
+  const disposers = []
+  for (const tool of registry?.TOOLS || []) {
+    const impl = registry.TOOL_IMPL?.[tool.name]
+    if (typeof impl !== 'function') throw new Error(`registerWithDsh: 工具缺少实现 ${tool.name}`)
+    const name = namespace ? `${namespace}_${tool.name}` : tool.name
+    disposers.push(ctx.tools.register({
+      name,
+      description: tool.description || '',
+      parameters: tool.inputSchema || { type: 'object', properties: {}, additionalProperties: false },
+      output: {
+        schema: { type: 'object', additionalProperties: true },
+        render: (args, value) => (value && Array.isArray(value.content)
+          ? value.content
+          : [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value) }]),
+      },
+      execute: (args) => impl(args),
+    }))
+  }
+  return () => {
+    for (const dispose of disposers) {
+      try { dispose() } catch { /* 忽略重复释放 */ }
+    }
+  }
+}
+
+export function createToolHost(config = {}) {
+  return {
+    api: createServiceApi('toolHost', '1.0.0', ['dsl', 'registry', 'validate', 'contract', 'mcp', 'instructions', 'native-tools']),
+    version: '0.1.0',
+    defineTool,
+    defineCapability,
+    createRegistry: (capabilities, options = {}) => createRegistry(capabilities, { ...config, ...options }),
+    createMcpHandler,
+    createToolDispatcher,
+    createCapabilityReport,
+    buildInstructions,
+    registerWithDsh,
+    validateToolArguments,
+  }
+}
+
+export { validateToolArguments }

package/server/shared/tuning.mjs

@@ -0,0 +1,63 @@
+/**
+ * dsh-service-host 运行时调优层。
+ *
+ * 默认值与进化搜索（evolution/ NSGA-II）的 founder 基线保持一致；
+ * 生产环境可用 DSH_TUNING_JSON 覆盖（按包名分组），测试/评估用 setTuning 注入。
+ */
+
+const DEFAULTS = {
+  /* 端口被占时向后顺延扫描的次数上限（非 strictPort） */
+  portScanLimit: 50,
+  /* 复用既有实例的 /healthz 探测超时
+   * 200ms 由进化搜索固化（evolution/，2026-11-01）：黑洞端口启动阻塞 425→227ms；
+   * 健康实例 RTT 1-3ms，仍有 60 倍以上余量。 */
+  reuseProbeTimeoutMs: 200,
+  /* 单实例锁：空/坏锁视为残留前的宽限 */
+  lockFreshGraceMs: 2000,
+  /* 优雅关闭：先等 N ms 再断开全部连接 */
+  closeGraceMs: 50,
+  /* 优雅关闭：强制完成的兜底时限 */
+  closeForceMs: 1000,
+}
+
+let overrides = {}
+let envLoaded = false
+
+function loadEnv() {
+  if (envLoaded) return
+  envLoaded = true
+  try {
+    const raw = process.env.DSH_TUNING_JSON
+    if (!raw) return
+    const parsed = JSON.parse(raw)
+    if (!parsed || typeof parsed !== 'object') return
+    const own = parsed['dsh-service-host'] && typeof parsed['dsh-service-host'] === 'object'
+      ? parsed['dsh-service-host']
+      : parsed
+    for (const key of Object.keys(DEFAULTS)) {
+      if (own[key] !== undefined) overrides[key] = own[key]
+    }
+  } catch { /* 非法 JSON 静默忽略：调优失败不能阻塞启动 */ }
+}
+
+/** 当前生效参数（默认值 + env + setTuning 覆盖）。 */
+export function tuning() {
+  loadEnv()
+  return { ...DEFAULTS, ...overrides }
+}
+
+/** 测试/评估注入。只接受已知键，避免拼写错误静默生效。 */
+export function setTuning(patch = {}) {
+  loadEnv()
+  for (const [key, value] of Object.entries(patch)) {
+    if (key in DEFAULTS) overrides[key] = value
+  }
+}
+
+/** 恢复到默认值 + env 覆盖。 */
+export function resetTuning() {
+  overrides = {}
+  envLoaded = false
+}
+
+export const TUNING_DEFAULTS = { ...DEFAULTS }

package/server/single-instance.mjs

@@ -0,0 +1,2 @@
+/** 兼容入口：单实例锁实现统一来自 dsh-plugin-kit 的构建快照。 */
+export * from './infra/single-instance.mjs'

package/server/store/backends/file-backend.mjs

@@ -0,0 +1,13 @@
+/** 文件后端：通用实现来自 dsh-state-service；保留 PPT 的初始文档。 */
+import { FileStateBackend } from '../../shared/state-service.mjs'
+import { getTuning } from '../../tuning.mjs'
+import { EMPTY_DOC } from '../doc.mjs'
+
+export class FileBridgeBackend extends FileStateBackend {
+  constructor(file) {
+    super(file, {
+      initialDoc: EMPTY_DOC(),
+      journalMaxBytes: getTuning().journalMaxBytes,
+    })
+  }
+}

package/server/store/checkpoints.mjs

@@ -0,0 +1,28 @@
+/** 兼容层：checkpoint 名称与载荷沿用 PPT 字段，底层由 DocumentSession 写入。 */
+export { checkpointName } from 'dsh-document-workbench/session'
+
+export function buildCheckpoint(doc, name, meta = {}) {
+  const pending = (doc.seq | 0) > (doc.applied_seq | 0)
+  const deck = doc.deck || { title: '未命名', slides: [] }
+  return {
+    name,
+    seq: doc.seq | 0,
+    appliedSeq: doc.applied_seq | 0,
+    pending,
+    title: doc.title || deck.title || '未命名',
+    slides: Array.isArray(deck.slides) ? deck.slides.length : 0,
+    deck,
+    meta: meta && typeof meta === 'object' ? meta : {},
+    createdAt: new Date().toISOString(),
+  }
+}
+
+export function listCheckpoints(backend) {
+  return backend.listCheckpoints()
+}
+
+export function readCheckpoint(backend, name) {
+  const payload = backend.readCheckpoint(name)
+  if (!payload || !payload.deck) throw new Error('checkpoint 内容损坏: ' + name)
+  return payload
+}