@capyclaw/ppt-workbench 0.0.0-stage → 2.4.0

package/server/infra/runtime/context.mjs

@@ -0,0 +1,128 @@
+/**
+ * Runtime context：插件启动时读取本次 DSH runtime 的端口、目录、namespace。
+ *
+ * 优先级：
+ *   1. 显式 runtimeFile / config.runtimeFile
+ *   2. DSH_RUNTIME_FILE
+ *   3. DSH_RUNTIME_ID + DSH_STORE_ROOT + DSH_STORE_TOKEN 环境变量
+ *
+ * 插件不应再读全局插件目录或写死端口；所有持久化内容都走
+ * WorkspaceClient，确保只作用于当前 runtime 的 namespace。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { WorkspaceManager, WorkspaceClient } from '../workspace/manager.mjs'
+
+function readJson(file, fallback = null) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')) } catch { return fallback }
+}
+
+export function runtimeFileFromEnv(env = process.env) {
+  return env.DSH_RUNTIME_FILE || ''
+}
+
+export function loadRuntimeContext({ runtimeFile, env = process.env } = {}) {
+  const file = runtimeFile || runtimeFileFromEnv(env)
+  if (file && fs.existsSync(file)) {
+    const runtime = readJson(file, null)
+    if (!runtime) throw new Error(`runtime 文件损坏: ${file}`)
+    return normalizeRuntime(runtime, { runtimeFile: path.resolve(file), env })
+  }
+  if (env.DSH_RUNTIME_ID && env.DSH_STORE_ROOT) {
+    return normalizeRuntime({
+      runtimeId: env.DSH_RUNTIME_ID,
+      storeRoot: env.DSH_STORE_ROOT,
+      ports: {
+        harness: Number(env.DSH_PROXY_PORT) || 0,
+        dsh: Number(env.DSH_UP_PORT) || 0,
+        content: Number(env.DSH_CONTENT_PORT) || 0,
+      },
+      paths: {
+        root: env.DSH_RUNTIME_ROOT || '',
+        dshHome: env.DSH_HOME || '',
+        workspace: env.DSH_WORKSPACE || '',
+        logs: env.DSH_LOG_DIR || '',
+        tmp: env.DSH_TMP_DIR || '',
+        contentState: env.DSH_CONTENT_STATE || '',
+      },
+      store: {
+        root: env.DSH_STORE_ROOT,
+        namespace: env.DSH_STORE_NAMESPACE || env.DSH_RUNTIME_ID,
+        token: env.DSH_STORE_TOKEN || '',
+      },
+      workId: env.DSH_WORK_ID || 'main',
+      profile: env.DSH_PROFILE || '',
+      domain: env.DSH_DOMAIN || '',
+    }, { runtimeFile: null, env })
+  }
+  return null
+}
+
+function normalizeRuntime(runtime, { runtimeFile = null, env = process.env } = {}) {
+  const store = runtime.store || {}
+  const paths = runtime.paths || {}
+  const ports = runtime.ports || {}
+  return {
+    ...runtime,
+    runtimeFile,
+    runtimeId: runtime.runtimeId || env.DSH_RUNTIME_ID || '',
+    storeRoot: runtime.storeRoot || store.root || env.DSH_STORE_ROOT || '',
+    store: {
+      root: store.root || runtime.storeRoot || env.DSH_STORE_ROOT || '',
+      namespace: store.namespace || runtime.runtimeId || env.DSH_RUNTIME_ID || '',
+      token: store.token || env.DSH_STORE_TOKEN || '',
+    },
+    ports: {
+      harness: Number(ports.harness) || Number(env.DSH_PROXY_PORT) || 0,
+      dsh: Number(ports.dsh) || Number(env.DSH_UP_PORT) || 0,
+      content: Number(ports.content) || Number(env.DSH_CONTENT_PORT) || 0,
+      ...ports,
+    },
+    paths: {
+      root: paths.root || '',
+      dshHome: paths.dshHome || env.DSH_HOME || '',
+      workspace: paths.workspace || env.DSH_WORKSPACE || '',
+      logs: paths.logs || env.DSH_LOG_DIR || '',
+      tmp: paths.tmp || env.DSH_TMP_DIR || '',
+      contentState: paths.contentState || env.DSH_CONTENT_STATE || '',
+      ...paths,
+    },
+    workId: runtime.workId || env.DSH_WORK_ID || 'main',
+  }
+}
+
+export function runtimeContextFromConfig(config = {}, options = {}) {
+  if (config && config.runtimeContext && typeof config.runtimeContext === 'object') {
+    return normalizeRuntime(config.runtimeContext, options)
+  }
+  if (config && config.runtimeFile) return loadRuntimeContext({ ...options, runtimeFile: config.runtimeFile })
+  return loadRuntimeContext(options)
+}
+
+export function createRuntimeStoreClient(context, { workId } = {}) {
+  if (!context || !context.store || !context.store.root || !context.store.token) {
+    return null
+  }
+  const store = new WorkspaceManager({ storeRoot: context.store.root })
+  return new WorkspaceClient({
+    manager: store,
+    runtimeId: context.store.namespace || context.runtimeId,
+    token: context.store.token,
+    workId: workId || context.workId || 'main',
+  })
+}
+
+export function runtimePaths(context) {
+  return (context && context.paths) || {}
+}
+
+export function isPathInside(root, target) {
+  if (!root || !target) return false
+  const rel = path.relative(path.resolve(root), path.resolve(target))
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))
+}
+
+export function assertPathInside(root, target, label = 'path') {
+  if (!isPathInside(root, target)) throw new Error(`${label} 越出 runtime 根目录: ${target}`)
+  return path.resolve(target)
+}

package/server/infra/store/blob-store.mjs

@@ -0,0 +1,109 @@
+/**
+ * 纯内容仓库：只负责按 sha256 存取不可变字节。
+ *
+ * 这里刻意不保存 manifest、不关心哪些文件属于同一个作品、不解释文件名。
+ * 文件关系、归属、版本和生命周期全部由 workspace/manager.mjs 的中间层负责。
+ */
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+
+export class BlobStore {
+  constructor({ root }) {
+    if (!root) throw new Error('BlobStore 需要 root')
+    this.root = path.resolve(root)
+    this.objectsRoot = path.join(this.root, 'objects')
+  }
+
+  init() {
+    fs.mkdirSync(this.objectsRoot, { recursive: true })
+    return this
+  }
+
+  blobPath(hash) {
+    if (!/^[a-f0-9]{64}$/.test(String(hash || ''))) throw new Error(`非法对象 hash: ${hash}`)
+    return path.join(this.objectsRoot, hash.slice(0, 2), hash)
+  }
+
+  put(data) {
+    const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data)
+    const hash = crypto.createHash('sha256').update(buffer).digest('hex')
+    const file = this.blobPath(hash)
+    if (!fs.existsSync(file)) {
+      fs.mkdirSync(path.dirname(file), { recursive: true })
+      const tmp = `${file}.tmp-${process.pid}-${crypto.randomBytes(4).toString('hex')}`
+      fs.writeFileSync(tmp, buffer)
+      try {
+        fs.renameSync(tmp, file)
+      } catch (error) {
+        /* 并发写同一 hash 时目标可能已出现；目标有效就复用，绝不删除目标。 */
+        if (fs.existsSync(file)) {
+          try { fs.rmSync(tmp, { force: true }) } catch { /* 忽略 */ }
+          return { hash, size: buffer.length }
+        }
+        try { fs.rmSync(tmp, { force: true }) } catch { /* 忽略 */ }
+        throw error
+      }
+    }
+    return { hash, size: buffer.length }
+  }
+
+  get(hash) {
+    const data = fs.readFileSync(this.blobPath(hash))
+    /* 内容寻址仓库的读取必须复核 sha256：截断/篡改对象不能静默使用。 */
+    const actual = crypto.createHash('sha256').update(data).digest('hex')
+    if (actual !== String(hash)) {
+      throw new Error(`BlobStore 对象校验失败: ${hash} (actual ${actual})`)
+    }
+    return data
+  }
+
+  has(hash) {
+    try { return fs.existsSync(this.blobPath(hash)) } catch { return false }
+  }
+
+  delete(hash) {
+    const file = this.blobPath(hash)
+    if (!fs.existsSync(file)) return false
+    fs.rmSync(file, { force: true })
+    return true
+  }
+
+  list() {
+    const out = []
+    let prefixes = []
+    try {
+      prefixes = fs.readdirSync(this.objectsRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory())
+    } catch {
+      return out
+    }
+    for (const prefix of prefixes) {
+      const dir = path.join(this.objectsRoot, prefix.name)
+      for (const name of fs.readdirSync(dir)) {
+        if (!/^[a-f0-9]{64}$/.test(name)) continue
+        const file = path.join(dir, name)
+        out.push({ hash: name, size: fs.statSync(file).size })
+      }
+    }
+    return out
+  }
+
+  /** 仓库只按中间层给的引用集合做物理清理，不自己判断文件关系。 */
+  gc(referencedHashes, { minAgeMs = 0 } = {}) {
+    const referenced = referencedHashes instanceof Set ? referencedHashes : new Set(referencedHashes || [])
+    const cutoff = Date.now() - Math.max(0, Number(minAgeMs) || 0)
+    let removed = 0
+    let skipped = 0
+    for (const { hash, size } of this.list()) {
+      if (referenced.has(hash)) continue
+      if (minAgeMs > 0) {
+        try {
+          if (fs.statSync(this.blobPath(hash)).mtimeMs > cutoff) { skipped++; continue }
+        } catch { continue }
+      }
+      this.delete(hash)
+      removed++
+    }
+    return { removed, skipped, referenced: referenced.size }
+  }
+}

package/server/infra/tuning.mjs

@@ -0,0 +1,82 @@
+/**
+ * dsh-plugin-kit 运行时调优层。
+ *
+ * 默认值与进化搜索（evolution/ NSGA-II）的 founder 基线保持一致；
+ * 生产环境可用 DSH_TUNING_JSON 覆盖（按包名分组），测试/评估用 setTuning 注入。
+ *
+ * DSH_TUNING_JSON 形如：
+ *   {"dsh-plugin-kit": {"fileLockPollMs": 25, "journalMaxBytes": 2097152}}
+ */
+
+const DEFAULTS = {
+  /* fs-lock：元数据文件锁
+   * pollMs=10 由 NSGA-II 进化搜索固化（evolution/，2026-11-01）：
+   * 24 路竞争延迟 2202→1400ms；10ms 为延迟与轮询 IO 的膝点。 */
+  fileLockSyncTimeoutMs: 10000,
+  fileLockSyncStaleMs: 30000,
+  fileLockAsyncTimeoutMs: 30000,
+  fileLockPollMs: 10,
+  fileLockFreshGraceMs: 2000,
+
+  /* 编辑器租约：wait() 轮询节奏 */
+  leaseWaitPollMs: 200,
+  leaseWaitTimeoutMs: 4000,
+
+  /* JournalStore：journal 轮转阈值与尾读默认行数
+   * 512KB 由进化搜索固化：尾读 p95 4.3→1.9ms、磁盘 -70%、追加吞吐 +8%。 */
+  journalMaxBytes: 512 * 1024,
+  journalTailLimit: 8,
+
+  /* WorkspaceManager catalog 写节流（降低全局 catalog 锁竞争） */
+  catalogThrottleMs: 5000,
+
+  /* WorkspaceClient token 校验缓存 */
+  tokenVerifyCacheMs: 30000,
+
+  /* HTTP 服务三级超时（keepAliveTimeoutMs 必须小于 headersTimeoutMs） */
+  requestTimeoutMs: 30000,
+  headersTimeoutMs: 10000,
+  keepAliveTimeoutMs: 5000,
+}
+
+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-plugin-kit'] && typeof parsed['dsh-plugin-kit'] === 'object'
+      ? parsed['dsh-plugin-kit']
+      : 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/infra/util/fs-lock.mjs

@@ -0,0 +1,132 @@
+/** 同步文件锁：给 registry / workspace manifest 这类元数据用。 */
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import { tuning } from '../tuning.mjs'
+
+const sleepCell = new Int32Array(new SharedArrayBuffer(4))
+
+export function sleepSync(ms) {
+  Atomics.wait(sleepCell, 0, 0, ms)
+}
+
+function pidDead(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false
+  try { process.kill(pid, 0); return false } catch (error) { return error.code === 'ESRCH' }
+}
+
+function newToken() {
+  return crypto.randomBytes(12).toString('hex')
+}
+
+function tryCreate(lockFile, token) {
+  fs.mkdirSync(path.dirname(lockFile), { recursive: true })
+  let fd
+  try {
+    fd = fs.openSync(lockFile, 'wx')
+  } catch (error) {
+    if (error.code === 'EEXIST') return false
+    throw error
+  }
+  try {
+    fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, token, ts: Date.now() }))
+    try { fs.fsyncSync(fd) } catch { /* 部分文件系统不支持 */ }
+  } finally {
+    fs.closeSync(fd)
+  }
+  return true
+}
+
+// Only a complete record whose owner is provably dead can be reclaimed. A
+// record-specific claim serializes competing reclaimers, including across
+// successive lock owners. An abandoned claim is intentionally not reclaimed.
+function reclaimDead(lockFile, staleMs) {
+  let raw, info, stat
+  try {
+    raw = fs.readFileSync(lockFile, 'utf8')
+    info = JSON.parse(raw)
+    stat = fs.statSync(lockFile)
+  } catch { return false }
+  if (!/^[a-f0-9]{24}$/.test(info?.token || '') || !pidDead(info.pid) || Date.now() - stat.mtimeMs <= staleMs) return false
+  const claim = `${lockFile}.reclaim-${crypto.createHash('sha256').update(raw).digest('hex')}`
+  let fd
+  try { fd = fs.openSync(claim, 'wx') } catch { return false }
+  try {
+    try {
+      if (fs.readFileSync(lockFile, 'utf8') !== raw || !pidDead(info.pid)) return false
+      fs.rmSync(lockFile)
+      return true
+    } catch { return false }
+  } finally {
+    fs.closeSync(fd)
+    try { fs.rmSync(claim, { force: true }) } catch { /* 保留未知状态 */ }
+  }
+}
+
+function releaseOwned(lockFile, token) {
+  try {
+    const info = JSON.parse(fs.readFileSync(lockFile, 'utf8'))
+    if (info.token === token) fs.rmSync(lockFile, { force: true })
+  } catch { /* 已被删除或被接管 */ }
+}
+
+function acquireSync(lockFile, { timeoutMs, staleMs }) {
+  const token = newToken()
+  const deadline = Date.now() + timeoutMs
+  const { fileLockPollMs: pollMs } = tuning()
+  while (true) {
+    if (tryCreate(lockFile, token)) return token
+    if (reclaimDead(lockFile, staleMs)) continue
+    if (Date.now() >= deadline) throw new Error(`等待文件锁超时: ${lockFile}`)
+    sleepSync(Math.min(pollMs, Math.max(1, deadline - Date.now())))
+  }
+}
+
+async function acquireAsync(lockFile, { timeoutMs, staleMs }) {
+  const token = newToken()
+  const deadline = Date.now() + timeoutMs
+  const { fileLockPollMs: pollMs } = tuning()
+  while (true) {
+    if (tryCreate(lockFile, token)) return token
+    if (reclaimDead(lockFile, staleMs)) continue
+    if (Date.now() >= deadline) throw new Error(`等待文件锁超时: ${lockFile}`)
+    await new Promise((resolve) => setTimeout(resolve, Math.min(pollMs, Math.max(1, deadline - Date.now()))))
+  }
+}
+
+export function withFileLock(lockFile, fn, opts = {}) {
+  const defaults = tuning()
+  const { timeoutMs = defaults.fileLockSyncTimeoutMs, staleMs = defaults.fileLockSyncStaleMs } = opts
+  const token = acquireSync(lockFile, { timeoutMs, staleMs })
+  try {
+    return fn()
+  } finally {
+    releaseOwned(lockFile, token)
+  }
+}
+
+/** 异步版本：用于分配端口这类需要 await 探测的场景。 */
+export async function withAsyncFileLock(lockFile, fn, opts = {}) {
+  const defaults = tuning()
+  const { timeoutMs = defaults.fileLockAsyncTimeoutMs, staleMs = defaults.fileLockSyncStaleMs } = opts
+  const token = await acquireAsync(lockFile, { timeoutMs, staleMs })
+  try {
+    return await fn()
+  } finally {
+    releaseOwned(lockFile, token)
+  }
+}
+
+export function writeJsonAtomic(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  const tmp = `${file}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`
+  fs.writeFileSync(tmp, JSON.stringify(value, null, 2) + '\n')
+  try { fs.renameSync(tmp, file) } catch {
+    try { fs.rmSync(file, { force: true }) } catch { /* 忽略 */ }
+    fs.renameSync(tmp, file)
+  }
+}
+
+export function readJson(file, fallback = null) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')) } catch { return fallback }
+}