@capyclaw/service-broker 0.0.0-stage → 0.2.0

package/lib/host.mjs

@@ -0,0 +1,93 @@
+/**
+ * dsh-service-broker：中间件插件（cordis 入口）。
+ *
+ * 这是 dsh 进程内**唯一**允许存在的插件角色——它不承载任何业务，
+ * 只做三件事：
+ *   1. 按清单（config.manifest 指向 services.json）把各服务作为独立进程拉起；
+ *   2. 向同进程提供 ctx.serviceBroker（list/start/stop/apply 控制面）；
+ *   3. 可选：config.skills.url 指向技能服务时，提供 ctx.skills 瘦客户端
+ *      （数据来自 HTTP，技能内容不再进程内注册）。
+ *
+ * 生命周期：keepAlive 服务（默认）不随插件卸载停止——服务独立于 dsh；
+ * config.stopOnUnload === true 时才随卸载全停。
+ */
+import { ServiceEngine } from './engine.mjs'
+import { createControlServer } from './control.mjs'
+import { createSkillsClient } from './skills-client.mjs'
+import { loadManifest } from './manifest.mjs'
+
+export const name = 'service-broker'
+
+export function apply(ctx, config = {}) {
+  const engine = new ServiceEngine({
+    discoveryPath: config.discoveryPath,
+    logDir: config.logDir,
+    log: (msg) => console.log(`[service-broker] ${msg}`),
+    defaultWaitMs: Number(config.waitMs) || 20000,
+  })
+
+  const api = {
+    api: { name: 'serviceBroker', version: '1.0.0', capabilities: ['apply', 'start', 'stop', 'list', 'doctor'] },
+    engine,
+    discoveryPath: engine.discoveryPath,
+    list: () => engine.list(),
+    start: (spec, options) => engine.apply([{ op: 'up', service: spec }], options),
+    stop: (id) => engine.stop(id),
+    apply: (commands, options) => engine.apply(commands, options),
+    doctor: (id) => engine.doctor(id),
+  }
+  const disposeService = ctx.provide('serviceBroker', api)
+
+  // 技能瘦客户端：ctx.skills 形状与原进程内注册表一致（list/get），
+  // 数据源改为 HTTP 技能服务——技能内容不再进 dsh 进程。
+  let disposeSkills = null
+  if (config.skills?.url) {
+    const client = createSkillsClient(config.skills.url)
+    disposeSkills = ctx.provide('skills', client)
+    console.log(`[service-broker] skills ← ${config.skills.url}`)
+  }
+
+  // 开机清单：有清单就按 up 命令投递给自己（幂等，复用优先）
+  void (async () => {
+    let services = []
+    try { services = loadManifest(config.manifest) } catch (err) {
+      console.warn(`[service-broker] 清单加载失败: ${err.message}`)
+      return
+    }
+    if (!services.length) {
+      console.log('[service-broker] 无开机清单，待命（服务可经控制端点/ctx.serviceBroker 投递）')
+      return
+    }
+    try {
+      const result = await engine.apply(services.map((service) => ({ op: 'up', service })))
+      for (const err of result.errors) console.warn(`[service-broker] ✗ ${err.id}: ${err.error}`)
+      console.log(`[service-broker] 开机清单完成：${result.services.length} 个服务就绪`)
+    } catch (err) {
+      console.warn(`[service-broker] 开机清单投递失败: ${err.message}`)
+    }
+  })()
+
+  // 可选控制端点（embedded 一般不需要；外部投递走 standalone 形态）
+  let controlServer = null
+  if (Number(config.controlPort) > 0) {
+    controlServer = createControlServer(engine, {
+      token: process.env.DSH_BROKER_TOKEN,
+      manifestPath: config.manifest,
+    })
+    controlServer.listen(Number(config.controlPort), '127.0.0.1', () => {
+      console.log(`[service-broker] 控制端点 http://127.0.0.1:${config.controlPort}/control/*`)
+    })
+  }
+
+  engine.startGuard({
+    intervalMs: Number(config.guardIntervalMs) || 5000,
+    maxConsecutive: Number(config.guardMaxConsecutive) || 3,
+  })
+
+  return async () => {
+    if (controlServer) await new Promise((resolve) => controlServer.close(resolve))
+    if (typeof disposeService === 'function') await disposeService()
+    if (typeof disposeSkills === 'function') await disposeSkills()
+    await engine.shutdown({ stopAll: config.stopOnUnload === true })
+  }
+}

package/lib/manifest.mjs

@@ -0,0 +1,40 @@
+/**
+ * 清单加载（host.mjs 与 server.mjs 共用）。
+ *
+ * - manifest 路径为相对路径时，相对 **broker 包目录**解析；
+ * - 清单里的 `${PACKAGE_DIR}` 展开为 **清单文件所在目录**——套件捆绑布局
+ *   下即套件根（services.json 与 node_modules/* 同层），同一份清单在
+ *   dev 树与安装态都能解析出正确绝对路径。
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { validateServiceManifest } from './spec.mjs'
+
+export const PKG_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+
+export function resolveManifestPath(manifestPath) {
+  if (!manifestPath) return path.join(PKG_DIR, 'services.json')
+  return path.isAbsolute(manifestPath) ? manifestPath : path.resolve(PKG_DIR, manifestPath)
+}
+
+export function loadManifest(manifestPath) {
+  const file = resolveManifestPath(manifestPath)
+  if (!existsSync(file)) return []
+  const raw = JSON.parse(readFileSync(file, 'utf8'))
+  const services = Array.isArray(raw) ? raw : raw.services
+  if (!Array.isArray(services)) throw new Error(`manifest 格式非法（缺 services 数组）: ${file}`)
+  const specErrors = validateServiceManifest(services, file)
+  if (specErrors.length) throw new Error(`manifest 服务 spec 非法:\n- ${specErrors.join('\n- ')}`)
+  const base = path.dirname(file)
+  return services.map((service) => expandPackageDir(service, base))
+}
+
+function expandPackageDir(service, base) {
+  const out = { ...service, env: { ...service.env } }
+  if (Array.isArray(out.cmd)) out.cmd = out.cmd.map((a) => String(a).replaceAll('${PACKAGE_DIR}', base))
+  for (const key of ['url', 'cwd', 'logFile']) {
+    if (typeof out[key] === 'string') out[key] = out[key].replaceAll('${PACKAGE_DIR}', base)
+  }
+  return out
+}

package/lib/recovery.mjs

@@ -0,0 +1,206 @@
+// Durable spawn receipts are separate from discovery, which is only observational.
+import fs from 'node:fs'
+import net from 'node:net'
+import path from 'node:path'
+import { spawn, spawnSync } from 'node:child_process'
+
+// Retry only unavailable queries, never substitute a PID or a different marker.
+// A successful but different identity is returned immediately to fail comparisons.
+export function queryWindowsIdentity(script, validate, run = spawnSync) {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    try {
+      const r = run('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], { encoding: 'utf8', windowsHide: true, timeout: 5000 })
+      const value = typeof r.stdout === 'string' ? r.stdout.trim() : ''
+      if (r.status === 0 && validate(value)) return value
+    } catch { /* transient launch failure is not proof */ }
+  }
+  return null
+}
+
+export function marker(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return null
+  try {
+    if (process.platform === 'win32') {
+      const v = queryWindowsIdentity(`$p = Get-Process -Id ${pid} -ErrorAction Stop; $p.StartTime.ToUniversalTime().Ticks.ToString()`, value => /^\d+$/.test(value))
+      return v ? `win:${v}` : null
+    }
+    if (process.platform === 'linux') {
+      const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8')
+      const fields = stat.slice(stat.lastIndexOf(')') + 2).split(' ')
+      const boot = fs.readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim()
+      return fields[19] && boot ? `linux:${boot}:${fields[19]}` : null
+    }
+  } catch {}
+  return null
+}
+/**
+ * 异步版 marker：Windows 上用异步 spawn 调 PowerShell，避免 spawnSync 阻塞事件循环。
+ * 返回格式与 marker() 完全一致，可与同步结果互相比对。
+ *
+ * 动机（2026-11-04 实测）：marker() 在 Windows 单次约 900ms，且 spawnSync 阻塞
+ * 事件循环，导致 broker 并发拉起多个服务时完全串行化。异步版让多个身份查询并行。
+ */
+export async function markerAsync(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return null
+  if (process.platform !== 'win32') return marker(pid)
+  const v = await queryWindowsIdentityAsync(
+    `$p = Get-Process -Id ${pid} -ErrorAction Stop; $p.StartTime.ToUniversalTime().Ticks.ToString()`,
+    (value) => /^\d+$/.test(value),
+  )
+  return v ? `win:${v}` : null
+}
+
+/** 与 queryWindowsIdentity 同语义（最多 3 次重试），但用异步 spawn。 */
+export async function queryWindowsIdentityAsync(script, validate, attemptLimit = 3) {
+  const once = () => new Promise((resolve) => {
+    let child
+    try {
+      child = spawn('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], { windowsHide: true })
+    } catch {
+      resolve(undefined)
+      return
+    }
+    let out = ''
+    let settled = false
+    const finish = (value) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolve(value)
+    }
+    const timer = setTimeout(() => {
+      try { child.kill() } catch { /* 已退出 */ }
+      finish(undefined)
+    }, 5000)
+    child.stdout.setEncoding('utf8')
+    child.stdout.on('data', (d) => { out += d })
+    child.on('error', () => finish(undefined))
+    child.on('close', (code) => {
+      const value = out.trim()
+      finish(code === 0 && validate(value) ? value : undefined)
+    })
+  })
+
+  for (let attempt = 0; attempt < attemptLimit; attempt++) {
+    const v = await once()
+    if (v !== undefined) return v
+  }
+  return null
+}
+
+export function absent(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return false
+  try { process.kill(pid, 0); return false } catch (e) { return e.code === 'ESRCH' }
+}
+export function receiptDir(discovery) { return `${discovery}.ownership` }
+export function receiptPath(discovery, id) {
+  if (typeof id !== 'string' || !/^[a-z0-9][a-z0-9._-]*$/i.test(id)) throw new Error('invalid service id')
+  return path.join(receiptDir(discovery), `${id}.json`)
+}
+export function writeReceipt(discovery, id, value) {
+  const file = receiptPath(discovery, id)
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`
+  fs.writeFileSync(tmp, JSON.stringify(value), { mode: 0o600, flag: 'wx' })
+  fs.renameSync(tmp, file)
+}
+export function removeReceipt(discovery, id) {
+  try { fs.unlinkSync(receiptPath(discovery, id)) } catch (e) { if (e.code !== 'ENOENT') throw e }
+}
+
+export function remainingReceipts(discovery) {
+  try { return fs.readdirSync(receiptDir(discovery)).map(name => `ownership:${name}:unresolved`) }
+  catch (e) { return e.code === 'ENOENT' ? ['ownership:missing'] : ['ownership:unreadable'] }
+}
+
+export function canConnect(port, timeoutMs = 800) {
+  return new Promise((resolve) => {
+    const socket = net.connect({ port, host: '127.0.0.1' })
+    const done = (ok) => { try { socket.destroy() } catch { /* 已销毁 */ } resolve(ok) }
+    socket.setTimeout(timeoutMs)
+    socket.once('connect', () => done(true))
+    socket.once('timeout', () => done(false))
+    socket.once('error', () => done(false))
+  })
+}
+
+function portList(value) {
+  return Object.values(value || {}).filter((port) => Number.isSafeInteger(port) && port > 0)
+}
+
+/**
+ * A dead root alone cannot prove its descendants are gone, so a receipt is
+ * normally kept as evidence. The exception we can verify: the root is absent
+ * and none of the service's declared ports is listening. An orphan that no
+ * longer serves the declared port cannot be the service we were asked to run.
+ * Any listener on those ports keeps the receipt (fail closed).
+ */
+export async function receiptResolvable(receipt, ports) {
+  if (!receipt || !Number.isSafeInteger(receipt.pid) || receipt.pid <= 0) return false
+  if (!absent(receipt.pid)) return false
+  const list = portList(ports ?? receipt.ports)
+  if (!list.length) return false
+  for (const port of list) if (await canConnect(port)) return false
+  return true
+}
+
+// Socket teardown can lag slightly behind process exit; give the OS a short,
+// bounded window before declaring the port still owned by an unknown process.
+export async function waitReceiptResolvable(receipt, ports, timeoutMs = 3000) {
+  const deadline = Date.now() + timeoutMs
+  for (;;) {
+    if (await receiptResolvable(receipt, ports)) return true
+    if (Date.now() >= deadline) return false
+    await new Promise((resolve) => setTimeout(resolve, 200))
+  }
+}
+
+// Caller must serialize against starting a replacement broker and supply the
+// identity captured when it spawned this broker. An absent PID alone is not a receipt.
+export async function recoverServices(discovery, broker) {
+  const unresolved = [], stopped = []
+  if (!broker?.pid || !broker?.marker || !broker?.recoveryMarker || !absent(broker.pid)) return { stopped, unresolved: ['broker:not-confirmed-absent'] }
+  let discovered = {}
+  try { discovered = JSON.parse(fs.readFileSync(discovery, 'utf8'))?.services || {} } catch { /* discovery 缺失时只能依赖收据自身 */ }
+  let entries
+  try { entries = fs.readdirSync(receiptDir(discovery)) } catch (e) {
+    return { stopped, unresolved: [e.code === 'ENOENT' ? 'ownership:missing' : 'ownership:unreadable'] }
+  }
+  for (const name of entries) {
+    if (!name.endsWith('.json')) { unresolved.push(`ownership:${name}:unrecognized`); continue }
+    let r
+    try { r = JSON.parse(fs.readFileSync(path.join(receiptDir(discovery), name), 'utf8')) } catch { unresolved.push(`ownership:${name}:unreadable`); continue }
+    if (!r || `${r.id}.json` !== name || !/^[a-z0-9][a-z0-9._-]*$/i.test(r.id) || r.brokerPid !== broker.pid || r.brokerMarker !== broker.recoveryMarker || r.state !== 'spawned' || !Number.isSafeInteger(r.pid) || r.pid <= 0 || !r.identity) {
+      unresolved.push(`ownership:${name}:unverified`); continue
+    }
+    if (!absent(broker.pid)) { unresolved.push('broker:not-confirmed-absent'); break }
+    if (absent(r.pid)) {
+      // Dead root: only a receipt whose declared ports are all free can be
+      // resolved; any listener may be an unverified descendant.
+      if (await waitReceiptResolvable(r, discovered[r.id]?.ports)) {
+        removeReceipt(discovery, r.id)
+        stopped.push(r.id)
+      } else unresolved.push(`service:${r.id}:already-exited-descendants-unverified`)
+      continue
+    }
+    if (!absent(r.pid)) {
+      if (marker(r.pid) !== r.identity) { unresolved.push(`service:${r.id}:identity-unverified`); continue }
+      if (process.platform === 'win32') {
+        const result = spawnSync('taskkill', ['/PID', String(r.pid), '/F'], { stdio: 'ignore', timeout: 10000, windowsHide: true })
+        if (result.status !== 0 && !absent(r.pid)) { unresolved.push(`service:${r.id}:stop-failed`); continue }
+      } else {
+        try { process.kill(r.pid, 'SIGTERM') } catch (e) { if (e.code !== 'ESRCH') { unresolved.push(`service:${r.id}:stop-failed`); continue } }
+      }
+      for (let i = 0; i < 50 && !absent(r.pid); i++) await new Promise(resolve => setTimeout(resolve, 100))
+      if (!absent(r.pid)) { unresolved.push(`service:${r.id}:still-running`); continue }
+    }
+    // Root exit alone does not prove its descendants exited. It is safe to
+    // resolve once none of the declared ports is still listening; otherwise
+    // keep the receipt as evidence (fail closed).
+    if (await waitReceiptResolvable(r, discovered[r.id]?.ports)) {
+      removeReceipt(discovery, r.id)
+      stopped.push(r.id)
+    } else unresolved.push(`service:${r.id}:descendants-unverified`)
+  }
+  return { stopped, unresolved }
+}

package/lib/skills-client.mjs

@@ -0,0 +1,28 @@
+/**
+ * 技能瘦客户端：把「技能服务」的 HTTP 面适配成原 ctx.skills 的进程内形状。
+ *
+ * 技能内容（SKILL.md 正文）不再通过 ctx.skills.registerProvider 进程内注册，
+ * 而是从独立技能服务拉取——dsh 进程里只剩这一个瘦适配层。
+ * 服务端形状见 bridges/ppt-bridge/dsh-skills-service（GET /skills、GET /skills/:name）。
+ */
+export function createSkillsClient(baseUrl) {
+  const root = String(baseUrl || '').replace(/\/$/, '')
+  return {
+    api: { name: 'skills', version: '1.0.0', kind: 'thin-client' },
+    async list(signal) {
+      const res = await fetch(`${root}/skills`, { signal: signal ?? AbortSignal.timeout(5000) })
+      if (!res.ok) throw new Error(`skills list HTTP ${res.status}`)
+      const body = await res.json()
+      return Array.isArray(body?.skills) ? body.skills : []
+    },
+    async get(candidate, options = {}) {
+      const name = typeof candidate === 'string' ? candidate : candidate?.name
+      if (!name) throw new Error('skills get: 缺 name')
+      const res = await fetch(`${root}/skills/${encodeURIComponent(name)}`, {
+        signal: options.signal ?? AbortSignal.timeout(10000),
+      })
+      if (!res.ok) throw new Error(`未知 skill ${name}（HTTP ${res.status}）`)
+      return res.json()
+    },
+  }
+}

package/lib/spec.mjs

@@ -0,0 +1,78 @@
+/**
+ * 服务 spec 校验：service.schema.json 的代码面。
+ *
+ * stack-services.json（dsh-stack-kit 编译）与 service-manifest.json
+ * （dsh-suite-kit 物化）共用这一份 spec；本模块是装载期与跨包测试
+ * 共同调用的唯一校验器（结构级——语义由 engine/discovery 在运行期裁决）。
+ */
+const ID_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/
+
+function checkPortValue(value, label, errors) {
+  if (value === undefined) return
+  if (value === 'auto') return
+  if (!Number.isInteger(value) || value <= 0 || value > 65535) {
+    errors.push(`${label} 必须是 1-65535 整数或 "auto"`)
+  }
+}
+
+/** 校验单个服务 spec；返回错误数组（空 = 通过）。 */
+export function validateServiceSpec(service, at = 'service') {
+  const errors = []
+  if (!service || typeof service !== 'object' || Array.isArray(service)) {
+    return [`${at} 必须是对象`]
+  }
+  if (typeof service.id !== 'string' || !ID_RE.test(service.id)) {
+    errors.push(`${at}.id 必须是非空的服务标识（字母数字开头，可含 . _ -）`)
+  }
+  if (!Array.isArray(service.cmd) || service.cmd.length === 0 || service.cmd.some((item) => typeof item !== 'string')) {
+    errors.push(`${at}.cmd 必须是非空 string[]（完整命令行）`)
+  }
+  if (service.ports !== undefined) {
+    if (typeof service.ports !== 'object' || service.ports === null || Array.isArray(service.ports)) {
+      errors.push(`${at}.ports 必须是对象（main 或具名端口）`)
+    } else {
+      for (const [name, value] of Object.entries(service.ports)) {
+        checkPortValue(value, `${at}.ports.${name}`, errors)
+      }
+    }
+  }
+  if (service.env !== undefined && (typeof service.env !== 'object' || service.env === null
+    || Array.isArray(service.env) || Object.values(service.env).some((value) => typeof value !== 'string'))) {
+    errors.push(`${at}.env 必须是 string -> string 对象`)
+  }
+  if (service.keepAlive !== undefined && typeof service.keepAlive !== 'boolean') {
+    errors.push(`${at}.keepAlive 必须是 boolean`)
+  }
+  if (service.healthPath !== undefined && typeof service.healthPath !== 'string') {
+    errors.push(`${at}.healthPath 必须是 string`)
+  }
+  if (service.url !== undefined && typeof service.url !== 'string') errors.push(`${at}.url 必须是 string`)
+  if (service.cwd !== undefined && typeof service.cwd !== 'string') errors.push(`${at}.cwd 必须是 string`)
+  if (service.logFile !== undefined && typeof service.logFile !== 'string') errors.push(`${at}.logFile 必须是 string`)
+  if (service.requires !== undefined && (!Array.isArray(service.requires)
+    || service.requires.some((item) => typeof item !== 'string'))) {
+    errors.push(`${at}.requires 必须是 string[]`)
+  }
+  if (service.portFrom !== undefined && !['content', 'urlPort'].includes(service.portFrom)) {
+    errors.push(`${at}.portFrom 只允许 content | urlPort`)
+  }
+  if (service.dirFrom !== undefined && service.dirFrom !== 'contentState') {
+    errors.push(`${at}.dirFrom 只允许 contentState`)
+  }
+  return errors
+}
+
+/** 校验整份清单（services 数组 + 同清单 id 唯一）；返回错误数组（空 = 通过）。 */
+export function validateServiceManifest(services, label = 'manifest') {
+  if (!Array.isArray(services)) return [`${label}: services 必须是数组`]
+  const errors = []
+  const seen = new Set()
+  services.forEach((service, index) => {
+    errors.push(...validateServiceSpec(service, `${label}[${index}]`))
+    if (service && typeof service === 'object' && typeof service.id === 'string') {
+      if (seen.has(service.id)) errors.push(`${label}: 重复的服务 id ${service.id}`)
+      seen.add(service.id)
+    }
+  })
+  return errors
+}

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@capyclaw/service-broker",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "DSH 服务中间件（唯一进程内插件）：按清单/结构化命令把各服务作为独立进程拉起，负责守护、发现（discovery）、控制端点；服务与服务之间不互相带动，跨端口组织一律经过这里。",
+  "type": "module",
+  "main": "./lib/host.mjs",
+  "exports": {
+    ".": "./lib/host.mjs",
+    "./engine": "./lib/engine.mjs",
+    "./manifest": "./lib/manifest.mjs",
+    "./spec": "./lib/spec.mjs",
+    "./schema": "./service.schema.json",
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=18",
+    "dsh": "^0.2.0-rc.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "suite": "./dsh-suite.json",
+    "apiVersion": "1.0.0",
+    "category": "service",
+    "platform": "both"
+  },
+  "meta": {
+    "title": "服务中间件",
+    "description": "按清单把各服务作为独立进程拉起，守护、发现与控制端点；服务之间不互相带动"
+  },
+  "files": [
+    "lib/",
+    "server.mjs",
+    "services.json",
+    "service.schema.json",
+    "cordis.patch.yml",
+    "dsh-suite.json",
+    "README.md"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "test": "node --test test/unit.test.mjs test/e2e.test.mjs test/stability.test.mjs test/adopt-detached.test.mjs"
+  },
+  "dependencies": {
+    "@capyclaw/plugin-kit": "^0.2.0"
+  }
+}

package/server.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/**
+ * dsh-service-broker standalone 入口：中间件以独立端口服务运行。
+ *
+ * 这是桌面/外部场景的主形态：启动清单（作品/后端）不直接拉服务，
+ * 而是把结构化命令 POST 到这里的 /control/apply，由中间件统一执行。
+ *
+ * 用法：
+ *   node server.mjs [--port 39610] [--manifest services.json]
+ *                   [--discovery ~/.dsh/services.json] [--stop-on-exit]
+ *
+ * 环境变量：DSH_BROKER_TOKEN（设置后 /control/* 需带 x-broker-token）。
+ */
+import path from 'node:path'
+import { mkdirSync } from 'node:fs'
+import { receiptDir } from './lib/recovery.mjs'
+import { fileURLToPath } from 'node:url'
+import { ServiceEngine } from './lib/engine.mjs'
+import { createControlServer } from './lib/control.mjs'
+import { loadManifest } from './lib/manifest.mjs'
+
+function arg(name, dflt) {
+  const i = process.argv.indexOf(name)
+  return i >= 0 && process.argv[i + 1] ? process.argv[i + 1] : dflt
+}
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+const port = Number(arg('--port', process.env.DSH_BROKER_PORT || 39610))
+const manifestPath = arg('--manifest', undefined)
+const discoveryPath = arg('--discovery', undefined)
+const stopOnExit = process.argv.includes('--stop-on-exit')
+
+const engine = new ServiceEngine({
+  discoveryPath,
+  log: (msg) => console.log(`${new Date().toISOString().slice(11, 19)} ${msg}`),
+})
+
+// Existence distinguishes a broker with receipt support from a legacy broker.
+mkdirSync(receiptDir(engine.discoveryPath), { recursive: true })
+
+// 开机清单：幂等（复用优先），失败不阻断中间件自身启动
+try {
+  const services = loadManifest(manifestPath)
+  if (services.length) {
+    const result = await engine.apply(services.map((service) => ({ op: 'up', service })))
+    for (const err of result.errors) console.warn(`✗ ${err.id}: ${err.error}`)
+    console.log(`开机清单完成：${result.services.length} 个服务就绪`)
+  } else {
+    console.log('开机清单为空，待命（等待 /control/apply 投递）')
+  }
+} catch (err) {
+  console.warn(`开机清单失败: ${err.message}`)
+}
+
+engine.startGuard()
+const server = createControlServer(engine, { token: process.env.DSH_BROKER_TOKEN, manifestPath })
+server.listen(port, '127.0.0.1', () => {
+  console.log(`dsh-service-broker 就绪: http://127.0.0.1:${port}/control/*`)
+  console.log(`discovery: ${engine.discoveryPath}`)
+})
+
+let exiting = false
+async function shutdown() {
+  if (exiting) return
+  exiting = true
+  console.log('中间件停机…')
+  await new Promise((resolve) => server.close(resolve))
+  await engine.shutdown({ stopAll: stopOnExit })
+  process.exit(0)
+}
+process.on('SIGINT', shutdown)
+process.on('SIGTERM', shutdown)
+process.on('break', shutdown)

package/service.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://dsh.local/schemas/service.schema.json",
+  "title": "DSH Broker 服务清单（唯一服务 spec）",
+  "description": "stack-services.json（dsh-stack-kit 编译）与 service-manifest.json（dsh-suite-kit 物化）是同一 spec 的两个 runtime 工件；本 schema 是二者共同的契约。${PACKAGE_DIR}/${PORT}/${PORT_<NAME>} 占位符由装载/仲裁层展开。",
+  "type": "object",
+  "required": ["services"],
+  "properties": {
+    "services": { "type": "array", "items": { "$ref": "#/$defs/service" } }
+  },
+  "$defs": {
+    "port": {
+      "anyOf": [
+        { "type": "integer", "minimum": 1, "maximum": 65535 },
+        { "type": "string", "enum": ["auto"] }
+      ]
+    },
+    "service": {
+      "type": "object",
+      "required": ["id", "cmd"],
+      "additionalProperties": true,
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$", "description": "服务 id（同清单内唯一）" },
+        "cmd": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "完整命令行（占位符原样保留，broker 展开分配）" },
+        "ports": {
+          "type": "object",
+          "additionalProperties": { "$ref": "#/$defs/port" },
+          "description": "main 为主端口；具名端口映射 PORT_<NAME>"
+        },
+        "url": { "type": "string", "description": "服务入口 URL 模板" },
+        "healthPath": { "type": "string", "description": "健康探测路径（默认 /healthz）" },
+        "keepAlive": { "type": "boolean", "description": "进程死亡后由 broker 原端口复活" },
+        "env": { "type": "object", "additionalProperties": { "type": "string" } },
+        "cwd": { "type": "string" },
+        "requires": { "type": "array", "items": { "type": "string" }, "description": "同清单内依赖的服务 id" },
+        "logFile": { "type": "string" },
+        "portFrom": { "type": "string", "enum": ["content", "urlPort"], "description": "suite 物化期提示：主端口取 runtime content/urlPort（物化后删除）" },
+        "dirFrom": { "type": "string", "enum": ["contentState"], "description": "suite 物化期提示：--dir 参数指向 runtime contentState（物化后删除）" }
+      }
+    }
+  }
+}

package/services.json

@@ -0,0 +1,3 @@
+{
+  "services": []
+}