@capyclaw/ppt-workbench 0.0.0-stage → 2.4.0

package/server/shared/kit/tools/validate.mjs

@@ -0,0 +1,115 @@
+/**
+ * 轻量 JSON Schema 参数校验（覆盖本工具面用到的子集）。
+ * MCP server 不会替我们执行 inputSchema，必须在调用实现前自己挡住坏参数。
+ *
+ * 编译缓存：schema 对象通常随工具定义长期存在，按 schema 对象（WeakMap）编译成
+ * 闭包树，重复调用不再逐层遍历 schema/创建临时数组。语义与解释执行逐行等价
+ * （anyOf / type / enum / maxLength / array / object 的顺序与错误文案不变）。
+ * 基准：50 元素数组参数校验从 ~0.029ms 降到 ~0.01ms（evolution/hotpath-bench.mjs H11）。
+ */
+
+const TYPE_CHECKS = {
+  string: (v) => typeof v === 'string',
+  number: (v) => typeof v === 'number' && Number.isFinite(v),
+  integer: (v) => typeof v === 'number' && Number.isInteger(v),
+  boolean: (v) => typeof v === 'boolean',
+  array: (v) => Array.isArray(v),
+  object: (v) => v !== null && typeof v === 'object' && !Array.isArray(v),
+  null: (v) => v === null,
+}
+
+/** schema 对象 → 编译后的校验闭包。 */
+const compiledCache = new WeakMap()
+
+/**
+ * 把 schema 编译成 `(value, path, errors) => void` 闭包树。
+ * 纯结构性编译，不依赖运行时数据；同一 schema 对象只编译一次。
+ */
+function compileSchema(schema) {
+  if (!schema || typeof schema !== 'object') return () => {}
+
+  /* anyOf：与解释版一致——任一支路无错误即通过，且通过后不再执行其余规则。 */
+  if (schema.anyOf) {
+    const branches = schema.anyOf.map(compileSchema)
+    return (value, path, errors) => {
+      const matched = branches.some((branch) => {
+        const local = []
+        branch(value, path, local)
+        return local.length === 0
+      })
+      if (!matched) errors.push(`${path} 不符合 anyOf`)
+    }
+  }
+
+  const typeCheck = schema.type ? TYPE_CHECKS[schema.type] : null
+  const enumValues = schema.enum ? schema.enum : null
+  const maxLength = schema.maxLength != null ? schema.maxLength : null
+  const maxItems = schema.type === 'array' && schema.maxItems != null ? schema.maxItems : null
+  const validateItem = schema.type === 'array' && schema.items ? compileSchema(schema.items) : null
+  const properties = schema.type === 'object' ? (schema.properties || {}) : null
+  const propValidators = properties
+    ? Object.entries(properties).map(([key, child]) => [key, compileSchema(child)])
+    : null
+  const required = properties && Array.isArray(schema.required) ? schema.required : null
+  const noAdditional = properties && schema.additionalProperties === false
+
+  return (value, path, errors) => {
+    /* 类型不符：解释版立即返回，不再做深层校验（保持该短路语义）。 */
+    if (typeCheck && !typeCheck(value)) {
+      errors.push(`${path} 应为 ${schema.type}`)
+      return
+    }
+    if (enumValues && !enumValues.includes(value)) {
+      errors.push(`${path} 必须是 ${enumValues.join(' / ')}`)
+    }
+    if (maxLength != null && typeof value === 'string' && value.length > maxLength) {
+      errors.push(`${path} 超过最大长度 ${maxLength}`)
+    }
+    if (maxItems != null && Array.isArray(value) && value.length > maxItems) {
+      errors.push(`${path} 最多 ${maxItems} 项`)
+    }
+    if (validateItem && Array.isArray(value)) {
+      value.forEach((item, i) => validateItem(item, `${path}[${i}]`, errors))
+    }
+    if (properties && value !== null && typeof value === 'object' && !Array.isArray(value)) {
+      if (required) {
+        for (const key of required) {
+          if (value[key] === undefined || value[key] === null) errors.push(`${path}.${key} 必填`)
+        }
+      }
+      if (noAdditional) {
+        for (const key of Object.keys(value)) {
+          if (!properties[key]) errors.push(`${path}.${key} 不是允许的参数`)
+        }
+      }
+      for (const [key, validateChild] of propValidators) {
+        if (value[key] === undefined) continue
+        validateChild(value[key], `${path}.${key}`, errors)
+      }
+    }
+  }
+}
+
+/** 取（或编译）schema 的校验闭包。 */
+function validatorOf(schema) {
+  if (!schema || typeof schema !== 'object') return compileSchema(schema)
+  const cached = compiledCache.get(schema)
+  if (cached) return cached
+  const compiled = compileSchema(schema)
+  compiledCache.set(schema, compiled)
+  return compiled
+}
+
+/**
+ * @returns {{ok: boolean, errors: string[]}}
+ */
+export function validateToolArguments(tool, args) {
+  const errors = []
+  if (!tool || !tool.inputSchema) {
+    if (args != null && (typeof args !== 'object' || Array.isArray(args))) errors.push('arguments 必须是 object')
+    return { ok: errors.length === 0, errors }
+  }
+  if (args == null) args = {}
+  validatorOf(tool.inputSchema)(args, 'arguments', errors)
+  return { ok: errors.length === 0, errors }
+}

package/server/shared/kit/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/shared/kit/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 }
+}