@capyclaw/ppt-workbench 0.0.0-stage → 2.4.1

package/lib/host.mjs

@@ -0,0 +1,98 @@
+/**
+ * 【已退役 2026-11-01 服务解耦标准】本文件不再作为 cordis 入口使用。
+ *
+ * 旧设计：本模块被 insert 进 dsh 进程，在 apply 里进程内拉起桥 relay——
+ * 违反「服务彼此独立、跨端口拉起交给中间件」原则，已废弃。
+ *
+ * 新形态：relay 是独立端口服务（server/relay.mjs 即 standalone 入口，
+ * dsh-service-host 骨架：/healthz 带 pid、单实例锁、优雅关闭），由
+ * dsh-service-broker 按清单以独立进程拉起（服务规格见包根
+ * cordis.patch.yml 注释）。本文件仅为过渡期兼容保留，勿再 insert。
+ */
+/**
+ * dsh-ppt-workbench 宿主插件（cordis 入口，loader 经包名加载本模块）。
+ *
+ * apply 里进程内拉起桥 relay（桥端点 + /mcp + 编辑器静态页），返回
+ * disposer——插件停用时关闭 relay（官方 remote-access 等同款生命周期）。
+ * 零 @deepseek-ai 依赖：只用 node 内置模块，最小化跨版本耦合。
+ */
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { runtimeContextFromConfig, createRuntimeStoreClient } from '../server/infra/runtime/context.mjs'
+import { WorkspaceBackend } from '../server/infra/workspace/manager.mjs'
+import { createWorkspaceAssetStore } from '../server/shared/asset-service.mjs'
+import { assertServiceApi } from '../server/shared/kit/service/api.mjs'
+
+export const name = 'ppt-workbench-host'
+
+function safeGet(ctx, serviceName) {
+  try { return ctx?.get ? ctx.get(serviceName) : null } catch { return null }
+}
+
+function requireApi(service, name) {
+  if (service) assertServiceApi(service, { name, major: 1 })
+  return service
+}
+
+export async function apply(ctx, config) {
+  const packageDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+  const { startRelay, DEFAULT_PORT } = await import('../server/relay.mjs')
+  const runtime = runtimeContextFromConfig(config || {})
+  const workId = (config && config.workId) || runtime?.workId || 'main'
+  /* 如果同进程挂载了 workspace-service，优先使用它提供的 scoped client；
+   * 没有时保留 runtime context fallback，保证独立运行。 */
+  const workspaceService = safeGet(ctx, 'workspace')
+  const storeClient = workspaceService?.getWork
+    ? workspaceService.getWork(workId)
+    : (runtime ? createRuntimeStoreClient(runtime, { workId }) : null)
+  const journalPath = runtime ? path.join(runtime.paths.logs, 'ppt-journal.jsonl') : null
+  const backend = storeClient ? new WorkspaceBackend({ client: storeClient, workId, journalPath }) : null
+  const hostDir = (config && config.hostDir)
+    || runtime?.paths?.contentState
+    || process.env.PPT_BRIDGE_HOME
+    || path.join(os.homedir(), '.dsh-ppt-bridge')
+  /* 公共插件 API 契约：存在则校验 major，避免静默不兼容。 */
+  const serviceHost = requireApi(safeGet(ctx, 'serviceHost'), 'serviceHost')
+  const toolHost = requireApi(safeGet(ctx, 'toolHost'), 'toolHost')
+  const editorHost = requireApi(safeGet(ctx, 'editorHost'), 'editorHost')
+  /* 图片等二进制资源只进对象仓库；deck 里只保存 /assets/<sha256> 引用。 */
+  const assetService = requireApi(safeGet(ctx, 'assets'), 'assets')
+  const assetStore = storeClient
+    ? (assetService?.createStore
+        ? assetService.createStore({ storeClient, workId })
+        : createWorkspaceAssetStore({ storeClient, workId }))
+    : (assetService?.createFileStore
+        ? assetService.createFileStore({ dir: path.join(hostDir, 'assets') })
+        : null)
+  const port = (config && Number(config.port))
+    || runtime?.ports?.content
+    || DEFAULT_PORT
+  const relay = await startRelay({
+    packageDir,
+    port,
+    hostDir,
+    strictPort: config?.strictPort != null ? !!config.strictPort : !!runtime,
+    allowReuse: config?.allowReuse != null ? !!config.allowReuse : !runtime,
+    lockFile: (config && config.lockFile) || path.join(hostDir, '.relay-instance.lock'),
+    backend,
+    assetStore,
+    assetService,
+    workId,
+    capabilities: config?.capabilities || null,
+    serviceHost,
+    toolHost,
+    editorHost,
+  })
+  const line = relay.reused
+    ? `[ppt-workbench] 复用已运行的桥: ${relay.url}`
+    : `[ppt-workbench] 桥已就绪: ${relay.url}`
+  console.log(line)
+  console.log(`[ppt-workbench] 编辑器: ${relay.editorUrl} （浏览器打开即用）`)
+  if (runtime) console.log(`[ppt-workbench] runtime=${runtime.runtimeId} work=${workId} namespace=${runtime.store?.namespace || ''}`)
+  if (relay.reused) console.log('[ppt-workbench] 注意：实际端口可能不是配置端口，/mcp 以当前 runtime 的 profile 注入为准')
+  return async () => {
+    await relay.stop()
+    console.log('[ppt-workbench] 桥已停止')
+  }
+}

package/package.json

@@ -1,6 +1,53 @@
-{
-  "name": "@capyclaw/ppt-workbench",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@capyclaw/ppt-workbench",
+  "version": "2.4.1",
+  "description": "PPT 工作台运行时：27 个 ppt_* MCP 工具（导入/导出 PPTX + 图表/表格/公式/形状/线条/备注 + 契约探测）+ 本机实时 PPTist 编辑器。",
+  "type": "module",
+  "main": "./lib/host.mjs",
+  "exports": {
+    ".": "./lib/host.mjs",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "capabilities": {
+      "source": "server/tools/capabilities",
+      "manifest": "capabilities.json"
+    }
+  },
+  "meta": {
+    "title": "PPT 工作台运行时",
+    "description": "AI 生成/编辑 PPT：27 个 ppt_* 工具 + 浏览器实时编辑器（http://127.0.0.1:39311/）"
+  },
+  "files": [
+    "lib/",
+    "server/",
+    "core/",
+    "!server/.relay-instance.lock",
+    "editor/",
+    "contract/",
+    "cordis.patch.yml",
+    "README.md",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "license": "AGPL-3.0-or-later",
+  "dependencies": {
+    "pptxgenjs": "^3.12.0",
+    "@capyclaw/document-workbench": "^0.1.0"
+  },
+  "author": {
+    "name": "CapyClaw",
+    "url": "https://github.com/capyclaw",
+    "email": "support@capyclaw.dev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/capyclaw/dsh-plugins"
+  },
+  "bugs": {
+    "url": "https://github.com/capyclaw/dsh-plugins/issues"
+  },
+  "homepage": "https://github.com/capyclaw/dsh-plugins"
+}

package/server/audit.mjs

@@ -0,0 +1,2 @@
+/** 兼容入口：deck 审计已移入 core/audit.js（纯 deck 域）。 */
+export * from '../core/audit.js'

package/server/bridge-client.mjs

@@ -0,0 +1,174 @@
+/** 桥 HTTP 客户端（MCP 侧）：keep-alive 连接复用 + 指令推送/回执 + deck 摘要。 */
+import nodeHttp from 'node:http'
+import { textHolder, htmlOf } from '../core/text.js'
+import { getTuning } from './tuning.mjs'
+
+export const BASE = (process.env.PPT_BRIDGE_URL || 'http://127.0.0.1:3311/api/desktop/works/ppt-bridge').replace(/\/+$/, '')
+
+const MAX_RESPONSE_BYTES = 16 * 1024 * 1024
+
+/* keep-alive 连接池：同 host 复用 TCP，省去每次 handshake；
+ * server 关闭时 agent 自动重连，不会积压僵尸连接。 */
+const keepAliveAgent = new nodeHttp.Agent({ keepAlive: true, maxSockets: 8 })
+
+export const getDeck = () => http('GET', BASE)
+export const get = (path) => http('GET', BASE + path)
+export const post = (path, body, options) => http('POST', BASE + path, body, options)
+
+/** 轻量读取（2026-10-22）：轮询只取状态，不拉 deck / 截图 base64。
+ *  旧实现每次 push 回执轮询都拉完整文档（含上一张截图 2-4MB），
+ *  一次工具调用最多轮询 120 次 ≈ 数百 MB 本地传输 + JSON 解析。 */
+export const getStatus = () => http('GET', BASE + '/status', undefined, { timeoutMs: 5000 })
+export const getDeckOnly = async () => {
+  let d = await http('GET', BASE + '/deck', undefined, { timeoutMs: 15000 })
+  /* 新编辑器先回执后镜像：等镜像追上本次指令（旧编辑器 state_seq=0，直接返回） */
+  const deadline = Date.now() + 2000
+  while (d.state_seq > 0 && d.state_seq < (d.applied_seq || 0) && Date.now() < deadline) {
+    await sleep(getTuning().statusPollMs || 100)
+    d = await http('GET', BASE + '/deck', undefined, { timeoutMs: 15000 })
+  }
+  return d
+}
+export const getShot = () => http('GET', BASE + '/shot', undefined, { timeoutMs: 30000 })
+
+/** 把图片写入 relay 的对象仓库，返回 /assets/<sha256> 引用。 */
+export const putAsset = (bytes, contentType = 'application/octet-stream') =>
+  post('/assets', { data: Buffer.from(bytes).toString('base64'), contentType }, { timeoutMs: 30000 })
+
+/** 上传待导入的 PPTX（原始字节，不走 base64），返回临时下载地址。 */
+export const uploadImport = (bytes, name = 'import.pptx', sourcePath = '') =>
+  http('POST', BASE + '/import-file', undefined, {
+    body: Buffer.from(bytes),
+    headers: {
+      'content-type': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+      'x-file-name': encodeURIComponent(String(name || 'import.pptx')),
+      ...(sourcePath ? { 'x-source-path': encodeURIComponent(String(sourcePath)) } : {}),
+    },
+    timeoutMs: 120000,
+  })
+
+/** 读取编辑器回传的导入结果；done=false 表示仍在处理。 */
+export const getImportResult = (req) => get('/import-result?req=' + encodeURIComponent(String(req || '')))
+
+/** 本机回环请求：每条独立连接（agent:false）。
+ *  2026-10-21 实测坑：fetch 连接池会在网关重启后复用僵尸 keep-alive
+ *  连接，服务端把它当坏请求回 501。
+ *  2026-10-31：补 connect/response 超时与响应体上限；桥挂起时不再永久卡住工具。 */
+function http(method, url, body, options = {}) {
+  return new Promise((resolve, reject) => {
+    const u = new URL(url)
+    const raw = Buffer.isBuffer(options.body) ? options.body : null
+    const payload = raw || (body ? Buffer.from(JSON.stringify(body)) : null)
+    const headers = { ...(options.headers || {}) }
+    if (payload) {
+      if (!raw && !headers['content-type']) headers['content-type'] = 'application/json'
+      headers['content-length'] = payload.length
+    }
+    const timeoutMs = Math.max(1000, Number(options.timeoutMs) || Number(getTuning().httpRequestTimeoutMs) || 15000)
+    let settled = false
+    const finish = (fn, value) => {
+      if (settled) return
+      settled = true
+      fn(value)
+    }
+    const req = nodeHttp.request({
+      hostname: u.hostname, port: u.port || 80,
+      path: u.pathname + u.search, method, headers, agent: keepAliveAgent,
+    }, (res) => {
+      let data = ''
+      let size = 0
+      res.setEncoding('utf8')
+      res.on('data', (chunk) => {
+        size += Buffer.byteLength(chunk)
+        if (size > MAX_RESPONSE_BYTES) {
+          req.destroy(new Error(`bridge 响应超过 ${Math.round(MAX_RESPONSE_BYTES / 1024 / 1024)}MB 上限`))
+          return
+        }
+        data += chunk
+      })
+      res.on('error', (error) => finish(reject, error))
+      res.on('end', () => {
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+          return finish(reject, new Error(`bridge ${method} ${url} -> HTTP ${res.statusCode} ${data.slice(0, 160)}`))
+        }
+        try { finish(resolve, JSON.parse(data)) }
+        catch { finish(reject, new Error('bridge 返回非 JSON: ' + data.slice(0, 160))) }
+      })
+    })
+    req.setTimeout(timeoutMs, () => {
+      req.destroy(new Error(`bridge ${method} ${url} 超时（${timeoutMs}ms）`))
+    })
+    req.on('error', (error) => finish(reject, error))
+    if (payload) req.write(payload)
+    req.end()
+  })
+}
+
+export const sleep = (ms) => new Promise(r => setTimeout(r, ms))
+export const clamp = (n, lo, hi) => Math.min(hi, Math.max(lo, n))
+
+/** 编辑器连接必须活跃（lease 有效）才允许推送。
+ *  2026-10-22：此前无窗口/租约过期时仍盲等 12~30s，实测造成 20 次
+ *  25~40s 的工具超时。现在最多等 graceMs 让新窗口完成 claim，随后立即失败。
+ *  2026-10-30：错误信息只说"下一步做什么"，不暴露内部租约概念。 */
+export async function requireEditor(graceMs = 4000) {
+  const deadline = Date.now() + graceMs
+  let st = await getStatus()
+  while (true) {
+    if (st.owner && Number(st.owner.age || 0) <= 10) return st
+    if (Date.now() >= deadline) {
+      throw new Error('PPT 编辑器窗口尚未连接：请打开右侧「浏览器」面板访问 http://127.0.0.1:39311 ，页面加载完成后会自动连接，无需其他操作')
+    }
+    await sleep(getTuning().statusPollMs || 200)
+    st = await getStatus()
+  }
+}
+
+export async function push(cmds, title) {
+  if (!Array.isArray(cmds)) throw new Error('没有可执行的指令')
+  if (!cmds.length && !title) throw new Error('没有可执行的指令')
+  /* 解耦批：写操作在服务端执行，不依赖编辑器页面在线 */
+  const doc = await post('', { cmds, title: title || '' }, { timeoutMs: 30000 })
+  const seq = doc.seq
+  const tuning = getTuning()
+  /* 批次越大，服务端执行时间越长；固定 12s 会把合法的 100 条批次误判为超时。 */
+  const baseDeadline = Number(tuning.pushBaseDeadlineMs) || 12000
+  const perOp = Number(tuning.pushPerOpMs) || 0
+  const deadline = Date.now() + Math.min(baseDeadline + cmds.length * perOp, 110000)
+  while (Date.now() < deadline) {
+    const cur = await getStatus()
+    if (cur.applied_seq >= seq) {
+      return { seq, applied: cur.applied, error: cur.error || '', ok: !cur.error }
+    }
+    await sleep(tuning.statusPollMs || 100)
+  }
+  return { seq, applied: 0, error: '等待编辑器应用超时（右侧面板是否已打开？）', ok: false }
+}
+
+export const okText = (r, msg) => ({
+  text: r.ok ? `${msg}（seq ${r.seq}，${r.applied} 条）` : `应用失败：${r.error}`,
+})
+
+/** 紧凑 deck 摘要；detailed 时附元素几何/颜色。 */
+export function summarize(deck, detailed) {
+  if (!deck || !Array.isArray(deck.slides)) return '（桥上没有 deck：右侧编辑器未就绪）'
+  const lines = [`标题：${deck.title || '未命名'}`, `共 ${deck.slides.length} 页`]
+  deck.slides.forEach((s, i) => {
+    const bg = s.background ? (s.background.type === 'solid' ? s.background.color : s.background.type) : '默认'
+    lines.push(`[${i}] id=${s.id || '-'} 背景=${bg}`)
+    ;(s.elements || []).forEach(e => {
+      const holder = textHolder(e)
+      if (holder) {
+        const t = String(htmlOf(e) || '').replace(/<[^>]+>/g, '').replace(/\s+/g, ' ').trim()
+        const geom = detailed ? ` (${Math.round(e.left)},${Math.round(e.top)} ${Math.round(e.width)}x${Math.round(e.height)}${e.color ? ' ' + e.color : ''})` : ''
+        const label = e.type === 'text' ? '文本' : '形状文本'
+        const fill = detailed && e.type === 'shape' ? ` fill=${e.fill || ''}` : ''
+        lines.push(`  - ${label}#${e.id}${geom}${fill}：${t.slice(0, 80)}`)
+      } else {
+        const geom = detailed ? ` (${Math.round(e.left)},${Math.round(e.top)} ${Math.round(e.width)}x${Math.round(e.height)}) fill=${e.fill || ''}` : ''
+        lines.push(`  - ${e.type}#${e.id}${geom}`)
+      }
+    })
+  })
+  return lines.join('\n')
+}

package/server/constants.mjs

@@ -0,0 +1,20 @@
+/** 桥的稳定常量（relay/routes/tests 共用，避免循环 import）。 */
+import { VIEW_OP_NAMES } from '../core/ops.js'
+
+export const DEFAULT_PORT = 39311
+export const BASE_PATH = '/api/desktop/works/ppt-bridge'
+
+export const EDITOR_FILES = {
+  '/': ['index.html', 'text/html; charset=utf-8'],
+  '/index.html': ['index.html', 'text/html; charset=utf-8'],
+  /* “打开方式”启动器专用入口：版本化 URL 绕过浏览器对旧 app.js 的强缓存。
+   * 升级编辑器构建时同时改 app-v* 文件名与 index.html 里的 script src。 */
+  '/open.html': ['index.html', 'text/html; charset=utf-8'],
+  '/app.js': ['app.js', 'text/javascript; charset=utf-8'],
+  '/app-v20261103.js': ['app.js', 'text/javascript; charset=utf-8'],
+  '/heartbeat-worker.js': ['heartbeat-worker.js', 'text/javascript; charset=utf-8'],
+  '/ppt-full-app.js': ['ppt-full-app.js', 'text/javascript; charset=utf-8'],
+}
+
+/** 页面级命令：不改 deck，只交给编辑器执行。由 op registry 的 view 元数据派生。 */
+export const VIEW_OPS = new Set(VIEW_OP_NAMES)

package/server/contract-snapshots.mjs

@@ -0,0 +1,62 @@
+/**
+ * 契约快照校验：workbench 与同目录 skill 包的 contract/ppt-contract.json
+ * major 不一致时，MCP 工具调用被拒绝（ppt_capabilities 除外，便于诊断）。
+ *
+ * 开发态（plugin/）和发布态（components/）里 skill 包都是 workbench 的兄弟目录，
+ * 因此无需配置文件；只装 workbench 时 checked=0，不拦截。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+
+const SKILL_PREFIX = 'dsh-ppt-skill-'
+
+function majorOf(version) {
+  return String(version || '').split('.')[0]
+}
+
+export function inspectContractSnapshots(packageDir, contractVersion, { prefix = SKILL_PREFIX } = {}) {
+  const expectedMajor = majorOf(contractVersion)
+  const report = { expected: contractVersion || '', checked: 0, ok: true, mismatched: [] }
+  const parent = path.dirname(packageDir)
+
+  let entries
+  try {
+    entries = fs.readdirSync(parent, { withFileTypes: true })
+  } catch {
+    return report
+  }
+
+  for (const entry of entries) {
+    if (!entry.name.startsWith(prefix)) continue
+    const dir = path.join(parent, entry.name)
+    try {
+      /* junction/软链接也要跟随；Dirent.isDirectory() 对链接为 false。 */
+      if (!fs.statSync(dir).isDirectory()) continue
+    } catch {
+      continue
+    }
+
+    report.checked++
+    const file = path.join(dir, 'contract', 'ppt-contract.json')
+    let snapshot = null
+    try {
+      snapshot = JSON.parse(fs.readFileSync(file, 'utf8'))
+    } catch {
+      report.mismatched.push({ package: entry.name, expected: contractVersion, actual: null })
+      continue
+    }
+    const actualMajor = majorOf(snapshot.contractVersion)
+    if (actualMajor !== expectedMajor) {
+      report.mismatched.push({ package: entry.name, expected: contractVersion, actual: snapshot.contractVersion || null })
+    }
+  }
+
+  report.ok = report.mismatched.length === 0
+  return report
+}
+
+export function describeMismatch(report) {
+  return report.mismatched
+    .map((item) => `${item.package}(snapshot=${item.actual || 'missing'}, runtime=${item.expected})`)
+    .join('；')
+}

package/server/contract.mjs

@@ -0,0 +1,24 @@
+/**
+ * MCP 工具契约的唯一真源（版本 + 报告格式）。
+ *
+ * 工具/能力清单由 capabilities → registry 派生；报告结构来自 dsh-tool-host。
+ * 新增能力只改 capabilities/index.mjs。
+ */
+import { createCapabilityReport } from './shared/tool-host.mjs'
+
+/** 工具契约版本：工具名、参数、返回结构发生不兼容变化时升 major。 */
+export const CONTRACT_VERSION = '2.4.0'
+
+/** 工作台包版本。 */
+export const PACKAGE_VERSION = '2.4.0'
+
+/** 生成模型可读的能力报告。 */
+export function capabilityReport(args, editorUrl = '', runtime = {}) {
+  return createCapabilityReport({
+    ...args,
+    contractVersion: CONTRACT_VERSION,
+    packageVersion: PACKAGE_VERSION,
+    editorUrl,
+    runtime,
+  })
+}

package/server/deck-layout.mjs

@@ -0,0 +1,2 @@
+/** 兼容入口：排版引擎已移入 core/deck-layout.js（纯 deck 域）。 */
+export * from '../core/deck-layout.js'

package/server/http-utils.mjs

@@ -0,0 +1,2 @@
+/** 兼容入口：HTTP 传输实现统一来自 @capyclaw/plugin-kit 的构建快照。 */
+export * from './infra/http.mjs'

package/server/infra/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))
+  })
+}