@twinsearth/w2m-dsh-plugin 3.1.0 → 3.2.0

package/src/interop/contract/server.js

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang/dsh-Master contributors — see LICENSE.
+
+import { CAPABILITIES, CONTRACT_VERSION, ERROR_CODES, METHOD_VERSION, METHODS } from './constants.js'
+import { createResponse, normalizeError, validateEnvelope } from './envelope.js'
+import { helloPayload, parseVersion, unsupportedMethodError } from './negotiate.js'
+
+/**
+ * 契约服务端（Fang 侧/任意一侧）：
+ *   * hello() 返回协商信息；
+ *   * invoke(envelope) 校验信封、检查方法版本、调用 handler、返回标准响应。
+ *
+ * 兼容原则：新增方法只需加 handler；删除/改义必须同时保留 method@old 一个 MINOR 周期。
+ */
+export function createContractServer({
+  role = 'mother',
+  instanceId = '',
+  version = CONTRACT_VERSION,
+  capabilities = CAPABILITIES,
+  transports = [],
+  handlers = {},
+  logger = null,
+  startedAt = Date.now(),
+} = {}) {
+  const registry = new Map(Object.entries(handlers))
+  const hello = () => helloPayload({
+    role,
+    instanceId,
+    version,
+    methods: [...new Set([METHODS.HELLO, METHODS.HEALTH, ...registry.keys()])],
+    capabilities,
+    transports,
+    startedAt,
+  })
+  const logs = { invoked: 0, failed: 0, lastError: null }
+
+  const invoke = async (envelope) => {
+    const validated = validateEnvelope(envelope)
+    if (!validated.ok) {
+      return createResponse({ id: envelope?.id, error: { code: ERROR_CODES.INVALID_ENVELOPE, message: validated.errors.join(', ') } })
+    }
+    const method = String(envelope.method)
+    try {
+      if (method === METHODS.HELLO) return createResponse({ id: envelope.id, result: hello() })
+      if (method === METHODS.HEALTH) {
+        return createResponse({ id: envelope.id, result: { ok: true, role, instanceId, version, uptimeMs: Date.now() - startedAt, methods: [...registry.keys()] } })
+      }
+      const handler = registry.get(method)
+      if (!handler) return createResponse({ id: envelope.id, error: unsupportedMethodError(method) })
+      const methodVersion = parseVersion(METHOD_VERSION[method] ?? '1.0')
+      const localVersion = parseVersion(version)
+      if (methodVersion && localVersion && methodVersion.major !== localVersion.major) {
+        return createResponse({ id: envelope.id, error: { code: ERROR_CODES.UNSUPPORTED_VERSION, message: `method ${method} requires contract major ${methodVersion.major}` } })
+      }
+      logs.invoked += 1
+      const result = await handler(envelope.params ?? null, envelope)
+      return createResponse({ id: envelope.id, result: result ?? null, meta: { role, instanceId } })
+    } catch (error) {
+      logs.failed += 1
+      logs.lastError = normalizeError(error, ERROR_CODES.HANDLER_THREW)
+      if (!error?.code) logs.lastError.code = ERROR_CODES.HANDLER_THREW
+      try { logger?.warn?.(`[contract] ${method} failed: ${logs.lastError.code} ${logs.lastError.message}`) } catch { /* ignore */ }
+      return createResponse({ id: envelope?.id, error: logs.lastError })
+    }
+  }
+
+  return {
+    hello,
+    invoke,
+    describe() {
+      return {
+        protocol: 'fang-master', contractVersion: version, role, instanceId,
+        methods: [...registry.keys()], capabilities, transports, stats: { ...logs },
+      }
+    },
+  }
+}

package/src/interop/contract/transports.js

@@ -0,0 +1,319 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang/dsh-Master contributors — see LICENSE.
+
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import {
+  CONTRACT_VERSION,
+  DEFAULT_TRANSPORT_ORDER,
+  ERROR_CODES,
+  LEGACY_SERVICE_KEYS,
+  METHODS,
+  PROTOCOL,
+} from './constants.js'
+import { ContractTransportError, createEnvelope, createResponse, normalizeError, validateEnvelope } from './envelope.js'
+import { helloPayload, negotiate } from './negotiate.js'
+
+function safeGet(ctx, name) {
+  try {
+    if (!ctx || typeof ctx !== 'object') return null
+    if (typeof ctx.get === 'function') return ctx.get(name) ?? null
+    return ctx[name] ?? null
+  } catch { return null }
+}
+
+function sleep(ms) { return new Promise((resolve) => setTimeout(resolve, Math.max(1, ms))) }
+
+function authHeaders(token) {
+  return token ? { authorization: `Bearer ${token}` } : {}
+}
+
+function baseOf(url) { return String(url ?? '').trim().replace(/\/+$/, '') }
+
+/** 统一传输接口：{name, kind, available(), hello(), invoke(method, params, opts)}。 */
+
+export function createLocalTransport({ ctx, serviceName = 'fangContract' } = {}) {
+  const service = () => safeGet(ctx, serviceName)
+  return {
+    name: 'local', kind: 'local', available: () => Boolean(service() && typeof service().invoke === 'function'),
+    async hello() {
+      const s = service()
+      if (!s) throw new ContractTransportError(ERROR_CODES.TRANSPORT_UNAVAILABLE, 'local contract service is absent', { transport: 'local' })
+      return await s.hello()
+    },
+    async invoke(method, params, opts = {}) {
+      const s = service()
+      if (!s || typeof s.invoke !== 'function') throw new ContractTransportError(ERROR_CODES.TRANSPORT_UNAVAILABLE, 'local contract service is absent', { transport: 'local' })
+      const response = await s.invoke(createEnvelope({ method, params, source: 'local', meta: opts.meta, timeoutMs: opts.timeoutMs }))
+      const check = validateEnvelope(response, { response: true })
+      if (!check.ok) throw new ContractTransportError(ERROR_CODES.INVALID_ENVELOPE, check.errors.join(','), { transport: 'local' })
+      return response
+    },
+  }
+}
+
+export function createHttpTransport({ baseUrl = '', token = '', headers: extraHeaders = {}, fetchImpl = fetch, timeoutMs = 15_000, pathPrefix = '/fang/api/contract' } = {}) {
+  const base = baseOf(baseUrl)
+  const prefix = `/${String(pathPrefix).replace(/^\/+|\/+$/g, '')}`
+  const available = () => Boolean(base)
+  const call = async (endpoint, role, fn, callTimeoutMs = timeoutMs) => {
+    if (!available()) throw new ContractTransportError(ERROR_CODES.TRANSPORT_UNAVAILABLE, 'http contract baseUrl is missing', { transport: 'http' })
+    const effectiveTimeout = Math.max(1, Number(callTimeoutMs) || timeoutMs)
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), effectiveTimeout)
+    timer.unref?.()
+    try {
+      const response = await fetchImpl(`${base}${prefix}${endpoint}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', accept: 'application/json', ...authHeaders(token), ...(extraHeaders && typeof extraHeaders === 'object' ? extraHeaders : {}) },
+        body: JSON.stringify(role),
+        signal: controller.signal,
+      })
+      const text = await response.text()
+      if (!response.ok) {
+        throw new ContractTransportError(ERROR_CODES.TRANSPORT_HTTP_ERROR, `HTTP ${response.status}`, { transport: 'http', detail: text.slice(0, 500) })
+      }
+      let parsed = null
+      try { parsed = JSON.parse(text) } catch { throw new ContractTransportError(ERROR_CODES.INVALID_ENVELOPE, 'HTTP response is not JSON', { transport: 'http' }) }
+      return fn(parsed)
+    } catch (error) {
+      if (error instanceof ContractTransportError) throw error
+      if (error?.name === 'AbortError') throw new ContractTransportError(ERROR_CODES.TRANSPORT_TIMEOUT, `HTTP contract timeout (>${timeoutMs}ms)`, { transport: 'http', retryable: true })
+      throw new ContractTransportError(ERROR_CODES.TRANSPORT_HTTP_ERROR, String(error?.message ?? error), { transport: 'http', retryable: true })
+    } finally { clearTimeout(timer) }
+  }
+  return {
+    name: 'http', kind: 'http', available,
+    async hello() {
+      return await call('/hello', { method: METHODS.HELLO }, (parsed) => {
+        // 允许 /hello 直接返回 payload，或返回标准 response envelope。
+        if (parsed && parsed.protocol) return parsed
+        if (parsed && parsed.ok && parsed.result) return parsed.result
+        throw new ContractTransportError(ERROR_CODES.INVALID_ENVELOPE, 'invalid hello payload', { transport: 'http' })
+      })
+    },
+    async invoke(method, params, opts = {}) {
+      const envelope = createEnvelope({ method, params, source: 'http', meta: opts.meta, timeoutMs: opts.timeoutMs })
+      return await call('/invoke', envelope, (parsed) => {
+        const check = validateEnvelope(parsed, { response: true })
+        if (!check.ok) throw new ContractTransportError(ERROR_CODES.INVALID_ENVELOPE, check.errors.join(','), { transport: 'http' })
+        return parsed
+      }, opts.timeoutMs)
+    },
+  }
+}
+
+function atomicWrite(file, text) {
+  const tmp = `${file}.${process.pid}.tmp`
+  return fs.writeFile(tmp, text, 'utf8').then(() => fs.rename(tmp, file))
+}
+
+/** Windows 对端仍持有句柄时 unlink 可能短暂 EPERM；成功响应后做有界重试清理。 */
+async function removeFileWithRetry(file, attempts = 8) {
+  for (let index = 0; index < attempts; index += 1) {
+    try { await fs.unlink(file); return true } catch (error) {
+      if (error?.code === 'ENOENT') return true
+      if (index + 1 < attempts) await sleep(25 * (index + 1))
+    }
+  }
+  return false
+}
+
+/**
+ * 文件 outbox 兜底传输：同一文件系统、无网络/无 HTTP 时使用。
+ * 请求写 requests/<id>.json，对端（startFileContractServer）写 responses/<id>.json。
+ */
+export function createFileTransport({ dir = '', fetchImpl = null, pollMs = 100, timeoutMs = 15_000 } = {}) {
+  const root = String(dir ?? '').trim()
+  const directories = {
+    request: path.join(root, 'requests'),
+    response: path.join(root, 'responses'),
+  }
+  const ensure = async () => {
+    await fs.mkdir(directories.request, { recursive: true })
+    await fs.mkdir(directories.response, { recursive: true })
+  }
+  return {
+    name: 'file', kind: 'file',
+    available: () => Boolean(root),
+    async hello() {
+      if (!root) throw new ContractTransportError(ERROR_CODES.TRANSPORT_UNAVAILABLE, 'file transport dir is missing', { transport: 'file' })
+      return await this.invoke(METHODS.HELLO, null).then((response) => (response.ok ? response.result : Promise.reject(new ContractTransportError(ERROR_CODES.REMOTE_ERROR, response.error?.message ?? 'hello failed', { transport: 'file' }))))
+    },
+    async invoke(method, params, opts = {}) {
+      if (!root) throw new ContractTransportError(ERROR_CODES.TRANSPORT_UNAVAILABLE, 'file transport dir is missing', { transport: 'file' })
+      await ensure()
+      const envelope = createEnvelope({ method, params, source: 'file', meta: opts.meta, timeoutMs: opts.timeoutMs })
+      const requestFile = path.join(directories.request, `${envelope.id}.json`)
+      const responseFile = path.join(directories.response, `${envelope.id}.json`)
+      await atomicWrite(requestFile, JSON.stringify(envelope))
+      const effectiveTimeout = Math.max(1, Number(opts.timeoutMs) || timeoutMs)
+      const deadline = Date.now() + effectiveTimeout
+      while (Date.now() < deadline) {
+        try {
+          const text = await fs.readFile(responseFile, 'utf8')
+          await removeFileWithRetry(responseFile)
+          const parsed = JSON.parse(text)
+          const check = validateEnvelope(parsed, { response: true })
+          if (!check.ok) throw new ContractTransportError(ERROR_CODES.INVALID_ENVELOPE, check.errors.join(','), { transport: 'file' })
+          // 请求文件由调用方负责回收：服务端实现可能只写响应而不删请求，
+          // 成功匹配响应后必须幂等清理，避免 contract-outbox 长期积累。
+          await removeFileWithRetry(requestFile)
+          return parsed
+        } catch (error) {
+          if (error instanceof ContractTransportError) throw error
+        }
+        await sleep(pollMs)
+      }
+      await removeFileWithRetry(requestFile)
+      await removeFileWithRetry(responseFile)
+      throw new ContractTransportError(ERROR_CODES.TRANSPORT_TIMEOUT, `file contract timeout (>${effectiveTimeout}ms)`, { transport: 'file', retryable: true })
+    },
+  }
+}
+
+/**
+ * 文件 fallback 的服务端轮询器：读取 requests/，调用 contractServer.invoke，写 responses/。
+ * @returns {{stop:()=>void, describe:()=>(object)}}
+ */
+export function startFileContractServer({ dir, server, pollMs = 100, maxAgeMs = 60_000, logger = null } = {}) {
+  const root = String(dir ?? '').trim()
+  if (!root) throw new Error('startFileContractServer requires dir')
+  const requestDir = path.join(root, 'requests')
+  const responseDir = path.join(root, 'responses')
+  let stopped = false
+  let timer = null
+  const tick = async () => {
+    if (stopped) return
+    try {
+      await fs.mkdir(requestDir, { recursive: true })
+      await fs.mkdir(responseDir, { recursive: true })
+      const entries = await fs.readdir(requestDir).catch(() => [])
+      for (const name of entries) {
+        if (!name.endsWith('.json')) continue
+        const file = path.join(requestDir, name)
+        try {
+          const stat = await fs.stat(file)
+          if (Date.now() - stat.mtimeMs > maxAgeMs) { await fs.unlink(file).catch(() => {}); continue }
+          const envelope = JSON.parse(await fs.readFile(file, 'utf8'))
+          const response = await server.invoke(envelope)
+          await atomicWrite(path.join(responseDir, `${envelope.id}.json`), JSON.stringify(response))
+          await fs.unlink(file).catch(() => {})
+        } catch (error) {
+          try { logger?.warn?.(`[contract:file] ${name}: ${String(error?.message ?? error)}`) } catch { /* ignore */ }
+          await fs.unlink(file).catch(() => {})
+        }
+      }
+    } catch { /* poll must not die */ }
+    if (!stopped) timer = setTimeout(tick, pollMs)
+  }
+  timer = setTimeout(tick, pollMs)
+  return {
+    stop() { stopped = true; if (timer) clearTimeout(timer); timer = null },
+    describe() { return { transport: 'file', dir: root, pollMs, stopped } },
+  }
+}
+
+/** 旧版 3.1.x 服务键回退：接口包被替换/新端点不存在时仍能工作。 */
+export function createLegacyTransport({ ctx } = {}) {
+  const forker = () => safeGet(ctx, LEGACY_SERVICE_KEYS.forker)
+  const decision = () => safeGet(ctx, LEGACY_SERVICE_KEYS.decisionCenter)
+  const sessions = () => safeGet(ctx, LEGACY_SERVICE_KEYS.sessionCatalog)
+  const orchestrator = () => safeGet(ctx, LEGACY_SERVICE_KEYS.orchestrator)
+  const available = () => Boolean(forker() || decision() || sessions() || orchestrator())
+  return {
+    name: 'legacy', kind: 'legacy', available,
+    async hello() {
+      return {
+        protocol: PROTOCOL, contractVersion: '0.9.0', role: 'mother', instanceId: 'legacy',
+        methods: [METHODS.HEALTH, METHODS.FORK_SPAWN, METHODS.DECISION_CREATE, METHODS.SESSION_LIST],
+        capabilities: ['sync'], transports: ['legacy'],
+      }
+    },
+    async invoke(method, params) {
+      if (method === METHODS.HEALTH) return createResponse({ result: { ok: true, legacy: true } })
+      if (method === METHODS.FORK_SPAWN) {
+        const service = forker()
+        if (!service || typeof service.spawn !== 'function') throw new ContractTransportError(ERROR_CODES.TRANSPORT_UNAVAILABLE, 'legacy fangForker is absent', { transport: 'legacy' })
+        return createResponse({ result: await service.spawn(params ?? {}) })
+      }
+      if (method === METHODS.DECISION_CREATE) {
+        const service = decision()
+        if (!service || typeof service.create !== 'function') throw new ContractTransportError(ERROR_CODES.TRANSPORT_UNAVAILABLE, 'legacy fangDecisionCenter is absent', { transport: 'legacy' })
+        return createResponse({ result: await service.create(params ?? {}) })
+      }
+      if (method === METHODS.SESSION_LIST) {
+        const service = sessions()
+        if (!service || typeof service.list !== 'function') throw new ContractTransportError(ERROR_CODES.TRANSPORT_UNAVAILABLE, 'legacy fangSessionCatalog is absent', { transport: 'legacy' })
+        return createResponse({ result: await service.list(params ?? {}) })
+      }
+      throw new ContractTransportError(ERROR_CODES.UNSUPPORTED_METHOD, `legacy transport cannot serve ${method}`, { transport: 'legacy' })
+    },
+  }
+}
+
+/**
+ * 传输路由器：按 local → http → file → legacy 顺序尝试；
+ * 传输不可用/超时/协议不兼容/未知方法时自动降级；业务错误不降级（避免重复副作用）。
+ */
+export function createTransportRouter({ transports = [], order = DEFAULT_TRANSPORT_ORDER, localHello = null, logger = null } = {}) {
+  const byName = new Map(transports.map((transport) => [transport.name, transport]))
+  const ordered = order.map((name) => byName.get(name)).filter((transport) => transport && (!transport.available || transport.available()))
+  const attempts = []
+  const record = (entry) => { attempts.push({ at: Date.now(), ...entry }); if (attempts.length > 100) attempts.shift() }
+  return {
+    transports: () => ordered.map((transport) => ({ name: transport.name, kind: transport.kind })),
+    attempts: () => [...attempts],
+    describe() {
+      return {
+        order,
+        available: ordered.map((transport) => transport.name),
+        configured: transports.map((transport) => ({ name: transport.name, kind: transport.kind, available: transport.available ? transport.available() : true })),
+      }
+    },
+    async hello() {
+      const local = localHello ?? helloPayload({ role: 'client', instanceId: 'contract-client' })
+      for (const transport of ordered) {
+        try {
+          const remote = await transport.hello()
+          const negotiation = negotiate(local, remote)
+          record({ transport: transport.name, action: 'hello', ok: true, compatible: negotiation.compatible, reason: negotiation.reason ?? null })
+          if (negotiation.compatible) return { ok: true, transport: transport.name, hello: remote, negotiation, fallback: null }
+          // remote-too-old/新：若还有后续传输（如 legacy），继续降级。
+          if (transport.name !== 'legacy') continue
+          return { ok: true, transport: transport.name, hello: remote, negotiation, fallback: 'legacy' }
+        } catch (error) {
+          record({ transport: transport.name, action: 'hello', ok: false, code: error?.code ?? null })
+          try { logger?.warn?.(`[contract] hello via ${transport.name} failed: ${error?.code ?? error?.message ?? error}`) } catch { /* ignore */ }
+        }
+      }
+      return { ok: false, code: ERROR_CODES.ALL_TRANSPORTS_FAILED, error: 'no transport could complete hello', attempts: this.attempts() }
+    },
+    async invoke(method, params, { idempotencyKey = '', timeoutMs = 30_000 } = {}) {
+      const envelopeMeta = idempotencyKey ? { idempotencyKey } : {}
+      const failures = []
+      for (const transport of ordered) {
+        try {
+          const response = await transport.invoke(method, params, { timeoutMs, meta: envelopeMeta })
+          // 有的传输（local）返回 response envelope；统一读取。
+          const ok = response?.ok === true
+          record({ transport: transport.name, action: method, ok, code: response?.error?.code ?? null })
+          if (ok) return { ok: true, transport: transport.name, response }
+          const code = String(response?.error?.code ?? '')
+          const fallbackable = code === ERROR_CODES.UNSUPPORTED_METHOD || code === ERROR_CODES.UNSUPPORTED_VERSION || response?.error?.retryable === true
+          failures.push({ transport: transport.name, code, message: response?.error?.message ?? '' })
+          if (!fallbackable) return { ok: false, transport: transport.name, response, error: response?.error ?? normalizeError(code), attempts: this.attempts() }
+        } catch (error) {
+          const code = error?.code ?? ERROR_CODES.TRANSPORT_UNAVAILABLE
+          failures.push({ transport: transport.name, code, message: String(error?.message ?? error) })
+          record({ transport: transport.name, action: method, ok: false, code })
+          try { logger?.warn?.(`[contract] ${method} via ${transport.name} failed: ${code} ${error?.message ?? ''}`) } catch { /* ignore */ }
+        }
+      }
+      return { ok: false, code: ERROR_CODES.ALL_TRANSPORTS_FAILED, error: 'all contract transports failed', failures, attempts: this.attempts() }
+    },
+  }
+}
+
+export { CONTRACT_VERSION, LEGACY_SERVICE_KEYS, METHODS }

package/src/interop/index.mjs

@@ -0,0 +1,270 @@
+/**
+ * W2M 互联契约层（contract 1.x）：w2m ↔ 瓮城 dsh-Fang ↔ 房主 dsh-Master 的唯一通道。
+ *
+ * 三个项目相互独立、各自发布。这里不 import 任何对方内部代码，只使用已发布的版本化契约 SDK
+ * （逐字节副本见 `src/interop/contract/`，来源与哈希见其 PROVENANCE.md）。
+ *
+ * 三个方向：
+ *   * **w2m 作为服务端**：`createContractServer` 承载 `w2m.*` 方法，经 local 服务与
+ *     `/api/w2m/contract/{hello,invoke,health}` 暴露；同宿主上 fang/master 的 local 传输默认找
+ *     `fangContract` 服务，所以本插件在它缺席时**也**提供该名字（存在则不覆盖，避免和 fang 抢键）。
+ *   * **w2m 作为客户端**：`createW2mContractClient` 直接复用 SDK 的 local → http → file → legacy
+ *     四级降级路由，调用 fang/master 的方法（`fang.*`、`contract.*`）。
+ *   * **file 兜底**：配置 `fileDir` 时挂上 SDK 的 file 契约服务端，HTTP 被挡/重启窗口仍能互通。
+ *
+ * 契约版本与插件版本解耦：`CONTRACT_VERSION`（SDK，1.1.1）管线协议；`W2M_CONTRACT_VERSION`
+ * （1.0.0）管 w2m 方法表的语义版本；插件自身版本是 third thing，各自独立演进。
+ */
+import {
+  CONTRACT_VERSION,
+  METHODS as CONTRACT_METHODS,
+  PROTOCOL,
+  PROTOCOL_VERSION,
+  createContractClient,
+  createContractServer,
+  startFileContractServer,
+} from './contract/index.js';
+
+/** w2m 方法表：只新增，不改既有方法语义；删除/改义必须升 W2M_CONTRACT_VERSION 的 MAJOR。 */
+export const W2M_CONTRACT_VERSION = '1.0.0';
+
+/** Cordis 插件面：契约层没有必需依赖，Connection 服务在 apply 里按需探测。 */
+export const name = 'w2m-contract';
+export const inject = [];
+
+export const W2M_METHODS = Object.freeze({
+  STATUS: 'w2m.status',
+  METHODS: 'w2m.methods',
+  FLEET_SNAPSHOT: 'w2m.fleet.snapshot',
+  DEVICES_LIST: 'w2m.devices.list',
+  TASKS_LIST: 'w2m.tasks.list',
+});
+
+/** 方法 → 契约版本（协商后按公共 minor 裁剪）。 */
+export const W2M_METHOD_VERSION = Object.freeze({
+  [W2M_METHODS.STATUS]: '1.0',
+  [W2M_METHODS.METHODS]: '1.0',
+  [W2M_METHODS.FLEET_SNAPSHOT]: '1.0',
+  [W2M_METHODS.DEVICES_LIST]: '1.0',
+  [W2M_METHODS.TASKS_LIST]: '1.0',
+});
+
+export const W2M_CONTRACT_CAPABILITIES = Object.freeze(['sync', 'async', 'idempotent']);
+
+export const CONTRACT_ROUTE_PREFIX = '/api/w2m/contract';
+export const CONTRACT_LOCAL_SERVICE = 'fangContract';
+export const W2M_CONTRACT_SERVICE = 'w2mContract';
+
+/** 服务缺席时的明确错误码：不伪造数据。 */
+const SERVICE_ABSENT = 'w2m-service-absent';
+
+function errorOf(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+/** 从 Cordis 上下文读一个可选服务（读不到就是 undefined，不猜）。 */
+function serviceOf(ctx, name) {
+  try {
+    return typeof ctx?.get === 'function' ? (ctx.get(name) ?? undefined) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * 组装 w2m 契约服务端。
+ *
+ * @param {{ctx?: object, instanceId?: string, providers?: object, now?: () => number}} options
+ *   providers 可注入 `status` / `fleetSnapshot` / `devices` / `tasks`，缺省时对应方法如实报
+ *   `w2m-service-absent`，而不是返回空数据冒充成功。
+ * @returns {{server: object, handlers: object}} server 即 SDK 契约服务端（hello/invoke/describe）。
+ */
+export function createW2mContractServer(options = {}) {
+  const { ctx = null, instanceId = `w2m-${process.pid}` } = options;
+  // providers 可由调用方注入，也可由宿主在 `w2mContractProviders` 服务里给出；两者都没有就如实报缺席。
+  const configured = options.providers ?? serviceOf(ctx, 'w2mContractProviders') ?? {};
+  const providers = configured !== null && typeof configured === 'object' ? configured : {};
+  const startedAt = Date.now();
+  const handler = (method, providerNames) => async (params) => {
+    for (const name of providerNames) {
+      const provider = providers[name];
+      if (typeof provider === 'function') return provider(params ?? null);
+    }
+    throw errorOf(SERVICE_ABSENT, `${method}: this w2m host exposes no ${providerNames.join('/')} provider`);
+  };
+  const handlers = {
+    [W2M_METHODS.STATUS]: async () => ({
+      ok: true,
+      plugin: 'w2m',
+      contractVersion: W2M_CONTRACT_VERSION,
+      sdkVersion: CONTRACT_VERSION,
+      protocol: PROTOCOL,
+      protocolVersion: PROTOCOL_VERSION,
+      instanceId,
+      methods: [...Object.keys(W2M_METHODS).map((key) => W2M_METHODS[key])],
+      uptimeMs: Date.now() - startedAt,
+    }),
+    [W2M_METHODS.METHODS]: async () => ({
+      ok: true,
+      contractVersion: W2M_CONTRACT_VERSION,
+      methods: Object.keys(W2M_METHODS).map((key) => ({
+        method: W2M_METHODS[key],
+        since: W2M_METHOD_VERSION[W2M_METHODS[key]],
+      })),
+    }),
+    [W2M_METHODS.FLEET_SNAPSHOT]: handler(W2M_METHODS.FLEET_SNAPSHOT, ['fleetSnapshot']),
+    [W2M_METHODS.DEVICES_LIST]: handler(W2M_METHODS.DEVICES_LIST, ['devices', 'fleetSnapshot']),
+    [W2M_METHODS.TASKS_LIST]: handler(W2M_METHODS.TASKS_LIST, ['tasks']),
+  };
+  const server = createContractServer({
+    // 契约 SDK 的角色词表只有 mother/essence/fork（Fang 概念），未知角色会被规整成 fork。
+    // w2m 是“不是母体的对等端”，用 essence 表达；w2m 自己的身份在 instanceId 与 w2m.* 方法里。
+    role: 'essence',
+    instanceId,
+    version: W2M_CONTRACT_VERSION,
+    capabilities: W2M_CONTRACT_CAPABILITIES,
+    transports: ['local', 'http', 'file'],
+    handlers,
+  });
+  return { server, handlers };
+}
+
+/**
+ * 组装 w2m 契约客户端：复用 SDK 的四级传输降级。
+ *
+ * @param {{ctx?: object, config?: object, fetchImpl?: typeof fetch, logger?: object, instanceId?: string}} options
+ * @returns {object} SDK 客户端 + w2m 便捷方法
+ */
+export function createW2mContractClient(options = {}) {
+  const client = createContractClient({
+    ctx: options.ctx ?? null,
+    config: options.config ?? {},
+    fetchImpl: options.fetchImpl ?? fetch,
+    logger: options.logger ?? null,
+    instanceId: options.instanceId ?? `w2m-client-${process.pid}`,
+  });
+  return {
+    ...client,
+    async status(params = {}, invokeOptions = {}) {
+      return client.invoke(W2M_METHODS.STATUS, params, invokeOptions);
+    },
+    async w2mMethods(params = {}, invokeOptions = {}) {
+      return client.invoke(W2M_METHODS.METHODS, params, invokeOptions);
+    },
+    async fleetSnapshot(params = {}, invokeOptions = {}) {
+      return client.invoke(W2M_METHODS.FLEET_SNAPSHOT, params, invokeOptions);
+    },
+    async devices(params = {}, invokeOptions = {}) {
+      return client.invoke(W2M_METHODS.DEVICES_LIST, params, invokeOptions);
+    },
+    async tasks(params = {}, invokeOptions = {}) {
+      return client.invoke(W2M_METHODS.TASKS_LIST, params, invokeOptions);
+    },
+  };
+}
+
+function json(status, body) {
+  return Response.json(body, { status, headers: { 'cache-control': 'no-store' } });
+}
+
+/** 从请求体读 JSON（契约信封）；读不出就是空对象，交给 SDK 报 invalid-envelope。 */
+async function envelopeOf(request) {
+  if (request.method === 'GET') {
+    try {
+      const url = new URL(request.url, 'http://127.0.0.1');
+      const method = url.searchParams.get('method');
+      if (method === null) return null;
+      const paramsRaw = url.searchParams.get('params');
+      return { method, params: paramsRaw === null ? null : JSON.parse(paramsRaw) };
+    } catch {
+      return null;
+    }
+  }
+  try {
+    const value = await request.json();
+    return value !== null && typeof value === 'object' ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 把契约端挂到宿主 Connection fetch 注册表上。
+ *
+ * 路径固定为 `/api/w2m/contract/*`：w2m 不占用 fang 的 `/fang/api/contract/*`，同宿主联通用
+ * local 服务（默认 `fangContract`），跨宿主时对端把 pathPrefix 配成这里。
+ *
+ * @param {object} ctx Cordis 上下文。
+ * @param {{server: object}} deps
+ * @returns {{mounted: boolean, reason: string|null}}
+ */
+export function registerContractRoutes(ctx, deps) {
+  const status = { mounted: false, reason: 'the host has no Connection service' };
+  if (typeof ctx?.inject !== 'function') return status;
+  ctx.inject(['connection'], (webCtx) => {
+    const registry = webCtx?.connection?.fetch;
+    if (registry === undefined || typeof registry.register !== 'function') {
+      status.reason = 'the connection service carries no fetch registry';
+      return;
+    }
+    const register = (path, methods, fetchHandler) => {
+      registry.register({ path, methods, requestBody: 'buffered', fetch: fetchHandler });
+    };
+    register(`${CONTRACT_ROUTE_PREFIX}/hello`, ['GET', 'POST'], async () => json(200, deps.server.hello()));
+    register(`${CONTRACT_ROUTE_PREFIX}/health`, ['GET'], async () =>
+      json(
+        200,
+        await deps.server.invoke({
+          protocol: PROTOCOL,
+          protocolVersion: PROTOCOL_VERSION,
+          id: 'health',
+          method: CONTRACT_METHODS.HEALTH,
+          params: null,
+          meta: {},
+        }),
+      ),
+    );
+    register(`${CONTRACT_ROUTE_PREFIX}/invoke`, ['POST', 'GET'], async (request) => {
+      const envelope = await envelopeOf(request);
+      return json(200, await deps.server.invoke(envelope));
+    });
+    status.mounted = true;
+    status.reason = null;
+  });
+  return status;
+}
+
+/**
+ * 挂载 w2m 契约层：服务端 + 服务 + HTTP 路由（+ 可选 file 兜底）。
+ *
+ * @param {object} ctx Cordis 上下文。
+ * @param {{instanceId?: string, providers?: object, fileDir?: string, localService?: string}} [config]
+ */
+export function apply(ctx, config = {}) {
+  const { server } = createW2mContractServer({
+    ctx,
+    instanceId:
+      typeof config?.instanceId === 'string' && config.instanceId !== '' ? config.instanceId : undefined,
+    providers: config?.providers ?? {},
+  });
+  const service = { ...server };
+  const provide = (name) => {
+    if (typeof ctx?.effect === 'function') ctx.effect(() => ctx.provide(name, service));
+    else if (typeof ctx?.provide === 'function') ctx.provide(name, service);
+  };
+  provide(W2M_CONTRACT_SERVICE);
+  const localServiceName =
+    typeof config?.localService === 'string' && config.localService !== ''
+      ? config.localService
+      : CONTRACT_LOCAL_SERVICE;
+  // 同宿主对端（fang/master 的 local 传输）默认找 `fangContract`：缺席时才补位，存在就让给 fang。
+  if (serviceOf(ctx, localServiceName) === undefined) provide(localServiceName);
+  registerContractRoutes(ctx, { server });
+  if (typeof config?.fileDir === 'string' && config.fileDir !== '') {
+    const fileServer = startFileContractServer({ dir: config.fileDir, server, logger: null });
+    if (typeof ctx?.effect === 'function') ctx.effect(() => () => fileServer?.close?.());
+  }
+  return service;
+}

package/src/plugin/tools.mjs

@@ -296,7 +296,7 @@ const MAX_STAGES = 16;
  * `package.json` during `scripts/pack.mjs` rather than hand-maintained, and `W2M_PLUGIN_VERSION`
  * overrides it at runtime for tests and packagers.
  */
-const PLUGIN_VERSION = '3.1.0';
+const PLUGIN_VERSION = '3.2.0';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;