@twinsearth/w2m-dsh-plugin 2.2.6 → 3.1.0

package/src/decision-center/kernel.mjs

@@ -0,0 +1,165 @@
+/**
+ * W2M-local replacement for the dsh-Fang kernel barrel the decision-center modules import.
+ *
+ * The ported plugin was written against `../kernel/index.mjs`, a barrel that existed to share ids,
+ * a tiny bus, filesystem helpers, the data-directory resolver and the deployment-role gate between
+ * the ten Fang plugins. W2M mounts one plugin, so the same names are supplied here with W2M paths:
+ *
+ *   * `z` is the vendored schemastery the Fang tree carries (MIT, upstream cordis). Keeping it means
+ *     the plugin's `Config` definitions and their descriptions survive the port verbatim;
+ *   * `SERVICE` names the Cordis services this plugin provides and optionally reads. The values are
+ *     W2M-prefixed so a profile that still mounts Fang's decision center cannot collide with this one;
+ *   * `resolveFangLayout` returns only what the ported code reads -- `dataDir` -- anchored in the same
+ *     `$DSH_HOME/xclient` state directory every other W2M component uses;
+ *   * `roleGate` has nothing to gate: the mother/fork deployment matrix is a Fang concept, and a W2M
+ *     profile is always the host, so the gate reports active.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+import { resolveStateDir } from '../util/cli.mjs';
+
+export { default as z } from './vendor/schemastery.mjs';
+
+/** Cordis service keys. Shared by the plugin that provides them and the routes that read them. */
+export const SERVICE = Object.freeze({
+  auditor: 'w2mAuditor',
+  decisionCenter: 'w2mDecisionCenter',
+  restart: 'w2mRestart',
+});
+
+/**
+ * Audit topic names.
+ *
+ * The ported module imports this object but records nothing through it -- tickets carry their own
+ * `audit` array in the store -- so the port keeps the import surface without inventing topics W2M
+ * does not emit.
+ */
+export const AUDIT = Object.freeze({});
+
+/** Deterministic, dependency-free event bus (same contract as the Fang kernel's). */
+export function createBus() {
+  const map = new Map();
+  return {
+    on(topic, fn) {
+      if (typeof fn !== 'function') return () => {};
+      if (!map.has(topic)) map.set(topic, new Set());
+      map.get(topic).add(fn);
+      return () => map.get(topic)?.delete(fn);
+    },
+    off(topic, fn) {
+      map.get(topic)?.delete(fn);
+    },
+    emit(topic, payload) {
+      const set = map.get(topic);
+      if (!set) return 0;
+      let n = 0;
+      for (const fn of [...set]) {
+        try {
+          fn(payload);
+          n += 1;
+        } catch {
+          /* a listener must never break the emitter */
+        }
+      }
+      return n;
+    },
+    listenerCount(topic) {
+      return map.get(topic)?.size ?? 0;
+    },
+    clear(topic) {
+      if (topic === undefined) map.clear();
+      else map.delete(topic);
+    },
+  };
+}
+
+export const bus = createBus();
+
+/** `prefix_<base36 time><random>`: sortable enough to read, unique enough to key a ticket. */
+export function newId(prefix = 'id') {
+  return `${prefix}_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`;
+}
+
+export function newUuid() {
+  return randomUUID();
+}
+
+export function nowMs() {
+  return Date.now();
+}
+
+export function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export function exists(file) {
+  try {
+    fs.lstatSync(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function readJson(file, fallback = null) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+export function writeFileAtomic(file, data) {
+  ensureDir(path.dirname(file));
+  const tmp = `${file}.${process.pid}.${Date.now().toString(36)}.tmp`;
+  fs.writeFileSync(tmp, data);
+  try {
+    fs.renameSync(tmp, file);
+  } catch {
+    // Windows can refuse a rename while a reader holds the file open; retry once, then fall back.
+    try {
+      fs.copyFileSync(tmp, file);
+    } finally {
+      try {
+        fs.rmSync(tmp, { force: true });
+      } catch {
+        /* the temp file is disposable */
+      }
+    }
+  }
+  return file;
+}
+
+export function writeJsonAtomic(file, value, { indent = 2 } = {}) {
+  return writeFileAtomic(file, `${JSON.stringify(value, null, indent)}\n`);
+}
+
+/**
+ * Resolve the data directory the decision store lives in.
+ *
+ * Only `dataDir` is read by the ported code. An explicit `dataRoot` wins (tests and standalone
+ * deployments point it at a throwaway directory); otherwise the store sits under
+ * `$DSH_HOME/xclient/decision-center`, beside every other W2M state file.
+ */
+export function resolveFangLayout(options = {}) {
+  const { dataRoot = '' } = options;
+  const explicit = String(dataRoot ?? '').trim();
+  const dataDir =
+    explicit !== '' ? path.resolve(explicit) : path.join(resolveStateDir(null, ''), 'decision-center');
+  return { dataDir };
+}
+
+/**
+ * Deployment-role gate.
+ *
+ * Fang gates a plugin per mother/fork role. W2M always runs as the host, so the gate reports active
+ * and keeps the call site (and its `logger` diagnostic) unchanged.
+ */
+export function roleGate(pluginKey, { logger = null } = {}) {
+  const reason = `${pluginKey} active in host`;
+  if (logger && typeof logger.info === 'function') logger.info(reason);
+  return { role: 'host', active: true, reason };
+}

package/src/decision-center/lib/ai-secret-store.mjs

@@ -0,0 +1,202 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+//
+// ai-secret-store — AI advisor 的 API Key 持久化：只走 OS 钥匙串 / DPAPI，绝不落明文。
+//
+// 支持的 backend：
+//   * win32  : DPAPI（用户级）——PowerShell 调 ProtectedData.Protect/Unprotect，secret 走 stdin
+//   * linux  : secret-tool（Secret Service / libsecret）——secret 走 stdin
+//   * darwin : 暂未实现（明确返回 unavailable，不假装成功）
+//   * 其它   : unavailable
+//
+// 磁盘上只存：
+//   <dataDir>/decision-ai-secret.json   { version, backend, provider, model, baseUrl, updatedAt }
+//   <dataDir>/decision-ai-secret.enc    backend 加密后的 blob（DPAPI 是 base64 密文；secret-tool 不落盘）
+// 若 backend 不可用 => available=false，调用方必须退回「仅内存」，绝不写明文。
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+import { ensureDir, writeJsonAtomic } from '../kernel.mjs'
+
+export const SECRET_META_FILE = 'decision-ai-secret.json'
+export const SECRET_BLOB_FILE = 'decision-ai-secret.enc'
+export const DEFAULT_SERVICE = 'w2m-decision-ai'
+
+const PS_PROTECT = [
+  'Add-Type -AssemblyName System.Security',
+  '$b64=[Console]::In.ReadToEnd()',
+  '$bytes=[Convert]::FromBase64String($b64)',
+  '$enc=[System.Security.Cryptography.ProtectedData]::Protect($bytes,$null,[System.Security.Cryptography.DataProtectionScope]::CurrentUser)',
+  '[Console]::Out.Write([Convert]::ToBase64String($enc))',
+].join('; ')
+
+const PS_UNPROTECT = [
+  'Add-Type -AssemblyName System.Security',
+  '$b64=[Console]::In.ReadToEnd()',
+  '$bytes=[Convert]::FromBase64String($b64)',
+  '$raw=[System.Security.Cryptography.ProtectedData]::Unprotect($bytes,$null,[System.Security.Cryptography.DataProtectionScope]::CurrentUser)',
+  '[Console]::Out.Write([Convert]::ToBase64String($raw))',
+].join('; ')
+
+/** 默认 runner：同步执行，stdin 传 secret，stdout 回结果；不把 secret 放进 argv。 */
+export function defaultRunner(command, args, input = '') {
+  const result = spawnSync(command, args, { input, encoding: 'utf8', windowsHide: true, timeout: 15000 })
+  return {
+    ok: result.status === 0,
+    status: result.status ?? -1,
+    stdout: String(result.stdout ?? '').trim(),
+    stderr: String(result.stderr ?? '').trim(),
+    error: result.error ? String(result.error?.message ?? result.error) : '',
+  }
+}
+
+export function detectSecretBackend({ platform = process.platform, runner = defaultRunner } = {}) {
+  if (platform === 'win32') {
+    const probe = runner('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', 'Add-Type -AssemblyName System.Security; "ok"'])
+    return probe.ok ? { backend: 'dpapi', available: true } : { backend: 'unavailable', available: false, reason: 'dpapi-probe-failed' }
+  }
+  if (platform === 'linux') {
+    const probe = runner('secret-tool', ['--version'])
+    return probe.ok ? { backend: 'secret-service', available: true } : { backend: 'unavailable', available: false, reason: 'secret-tool-missing' }
+  }
+  return { backend: 'unavailable', available: false, reason: platform === 'darwin' ? 'keychain-not-implemented' : 'platform-unsupported' }
+}
+
+/**
+ * @param {{dataDir:string, platform?:string, runner?:Function, service?:string, logger?:object}} options
+ */
+export function createAiSecretStore(options = {}) {
+  const dataDir = String(options.dataDir ?? '')
+  if (!dataDir) throw new Error('createAiSecretStore: dataDir required')
+  const platform = options.platform ?? process.platform
+  const runner = typeof options.runner === 'function' ? options.runner : defaultRunner
+  const service = String(options.service ?? DEFAULT_SERVICE)
+  const log = (level, message) => { try { options.logger?.[level]?.(`[ai-secret-store] ${message}`) } catch { /* ignore */ } }
+  const metaFile = path.join(dataDir, SECRET_META_FILE)
+  const blobFile = path.join(dataDir, SECRET_BLOB_FILE)
+  // 懒探测：只有真正需要持久化/读取能力时才执行后端探测（测试/未配置 AI 时零开销）。
+  let detection = null
+  const ensureBackend = () => {
+    if (detection === null) detection = detectSecretBackend({ platform, runner })
+    return detection
+  }
+
+  const readJson = (file) => {
+    try { return JSON.parse(fs.readFileSync(file, 'utf8')) } catch { return null }
+  }
+  const removeIfExists = (file) => { try { if (fs.existsSync(file)) fs.unlinkSync(file) } catch { /* ignore */ } }
+
+  function encrypt(secretJson) {
+    const detection = ensureBackend()
+    const plain = Buffer.from(secretJson, 'utf8').toString('base64')
+    if (detection.backend === 'dpapi') {
+      const out = runner('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', PS_PROTECT], plain)
+      if (!out.ok || !out.stdout) return { ok: false, reason: 'dpapi-protect-failed', detail: out.stderr || out.error }
+      return { ok: true, payload: out.stdout }
+    }
+    if (detection.backend === 'secret-service') {
+      const out = runner('secret-tool', ['store', '--label', 'dsh-fang decision AI key', 'service', service, 'slot', 'api-key'], secretJson)
+      if (!out.ok) return { ok: false, reason: 'secret-tool-store-failed', detail: out.stderr || out.error }
+      return { ok: true, payload: '' }
+    }
+    return { ok: false, reason: 'secret-backend-unavailable' }
+  }
+
+  function decrypt(payload) {
+    const detection = ensureBackend()
+    if (detection.backend === 'dpapi') {
+      const out = runner('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', PS_UNPROTECT], String(payload ?? ''))
+      if (!out.ok || !out.stdout) return { ok: false, reason: 'dpapi-unprotect-failed', detail: out.stderr || out.error }
+      try { return { ok: true, secretJson: Buffer.from(out.stdout, 'base64').toString('utf8') } } catch { return { ok: false, reason: 'dpapi-decode-failed' } }
+    }
+    if (detection.backend === 'secret-service') {
+      const out = runner('secret-tool', ['lookup', 'service', service, 'slot', 'api-key'])
+      if (!out.ok || !out.stdout) return { ok: false, reason: 'secret-tool-lookup-failed', detail: out.stderr || out.error }
+      return { ok: true, secretJson: out.stdout }
+    }
+    return { ok: false, reason: 'secret-backend-unavailable' }
+  }
+
+  return {
+    get backend() { return ensureBackend().backend },
+    get available() { return ensureBackend().available === true },
+    get reason() { return ensureBackend().reason ?? null },
+    service,
+    capabilities() {
+      const detection = ensureBackend()
+      return { backend: detection.backend, available: detection.available === true, reason: detection.reason ?? null, encryptedAtRest: detection.backend === 'dpapi' ? 'dpapi-user' : detection.backend === 'secret-service' ? 'os-secret-service' : 'none' }
+    },
+    /** 保存 { provider, model, baseUrl, apiKey }；失败返回 ok:false，调用方保持仅内存。 */
+    save(config = {}) {
+      const detection = ensureBackend()
+      if (!detection.available) return { ok: false, reason: detection.reason ?? 'secret-backend-unavailable' }
+      const apiKey = String(config.apiKey ?? '').trim()
+      if (!apiKey) return { ok: false, reason: 'api-key-required' }
+      const meta = {
+        version: 1,
+        backend: detection.backend,
+        provider: String(config.provider ?? '').slice(0, 40),
+        model: String(config.model ?? '').slice(0, 120),
+        baseUrl: String(config.baseUrl ?? '').slice(0, 500),
+        updatedAt: Date.now(),
+      }
+      const encrypted = encrypt(JSON.stringify({
+        apiKey,
+        ...(Array.isArray(config.profiles) ? { profiles: config.profiles } : {}),
+        ...(config.routes && typeof config.routes === 'object' ? { routes: config.routes } : {}),
+        ...(config.modelByLevel && typeof config.modelByLevel === 'object' ? { modelByLevel: config.modelByLevel } : {}),
+      }))
+      if (!encrypted.ok) return encrypted
+      try {
+        ensureDir(dataDir)
+        if (encrypted.payload) {
+          fs.writeFileSync(blobFile, encrypted.payload, { encoding: 'utf8', mode: 0o600 })
+          try { fs.chmodSync(blobFile, 0o600) } catch { /* windows */ }
+        }
+        writeJsonAtomic(metaFile, meta)
+        return { ok: true, backend: detection.backend, meta }
+      } catch (error) {
+        log('warn', `save failed: ${String(error?.message ?? error)}`)
+        return { ok: false, reason: 'persist-failed', detail: String(error?.message ?? error) }
+      }
+    },
+    /** 读取已持久化配置；不存在/backend 不匹配/解密失败 => null（不抛）。 */
+    load() {
+      // 没有落盘元数据时不要探测 backend（避免无 AI 配置的宿主每次启动都拉起 PowerShell）。
+      if (!fs.existsSync(metaFile)) return null
+      const detection = ensureBackend()
+      if (!detection.available) return null
+      const meta = readJson(metaFile)
+      if (!meta || meta.backend !== detection.backend) return null
+      let payload = ''
+      try { payload = fs.existsSync(blobFile) ? fs.readFileSync(blobFile, 'utf8') : '' } catch { payload = '' }
+      if (detection.backend === 'dpapi' && !payload) return null
+      const decrypted = decrypt(payload)
+      if (!decrypted.ok) { log('warn', `load failed: ${decrypted.reason}`); return null }
+      let secret = null
+      try { secret = JSON.parse(decrypted.secretJson) } catch { return null }
+      const apiKey = String(secret?.apiKey ?? '').trim()
+      if (!apiKey) return null
+      return {
+        provider: String(meta.provider ?? 'custom'),
+        model: String(meta.model ?? ''),
+        baseUrl: String(meta.baseUrl ?? ''),
+        apiKey,
+        ...(Array.isArray(secret.profiles) ? { profiles: secret.profiles } : {}),
+        ...(secret.routes && typeof secret.routes === 'object' ? { routes: secret.routes } : {}),
+        ...(secret.modelByLevel && typeof secret.modelByLevel === 'object' ? { modelByLevel: secret.modelByLevel } : {}),
+        source: `os:${detection.backend}`,
+        backend: detection.backend,
+      }
+    },
+    clear() {
+      removeIfExists(metaFile)
+      removeIfExists(blobFile)
+      if (ensureBackend().backend === 'secret-service') {
+        try { runner('secret-tool', ['clear', 'service', service, 'slot', 'api-key']) } catch { /* ignore */ }
+      }
+      return { ok: true }
+    },
+  }
+}

package/src/decision-center/lib/decision-outbox.mjs

@@ -0,0 +1,129 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+//
+// decision-outbox — fork 侧的「向母体提交 decision」耐久 outbox（P4 地基）。
+//
+// 方向：fork → mother 走 HTTP ingest，不走 adapter（adapter 是 mother → fork 控制通道）。
+// 母体地址/token 从 DSH_FANG_MOTHER 指向的母体 dataDir 读取：
+//   <motherDataDir>/endpoint.json  { url }
+//   <motherDataDir>/fang-auth.json { token }（0600）
+//
+// 现状：库本身可用，但还没有接进 fork 的 Agent tool / umbrella ASK；未接 = 不算接线。
+import fs from 'node:fs'
+import path from 'node:path'
+import { randomUUID } from 'node:crypto'
+
+import { ensureDir, readJson, writeJsonAtomic } from '../kernel.mjs'
+
+export const OUTBOX_DIRNAME = 'decision-outbox'
+
+export function resolveMotherTarget(motherDataDir) {
+  const dir = String(motherDataDir ?? '').trim()
+  if (!dir) return { ok: false, reason: 'mother-data-dir-required' }
+  const endpoint = readJson(path.join(dir, 'endpoint.json'), null)
+  const auth = readJson(path.join(dir, 'fang-auth.json'), null)
+  const url = String(endpoint?.url ?? '').replace(/\/+$/, '')
+  const token = String(auth?.token ?? '')
+  if (!url || !token) return { ok: false, reason: 'mother-endpoint-unavailable', url, hasToken: Boolean(token) }
+  return { ok: true, url, token }
+}
+
+/**
+ * @param {{dataDir:string, fetchImpl?:Function, logger?:object, now?:()=>number}} options
+ */
+export function createDecisionOutbox(options = {}) {
+  const dataDir = String(options.dataDir ?? '')
+  if (!dataDir) throw new Error('createDecisionOutbox: dataDir required')
+  const dir = path.join(dataDir, OUTBOX_DIRNAME)
+  const fetchImpl = typeof options.fetchImpl === 'function' ? options.fetchImpl : globalThis.fetch
+  const now = typeof options.now === 'function' ? options.now : () => Date.now()
+  const log = (level, message) => { try { options.logger?.[level]?.(`[decision-outbox] ${message}`) } catch { /* ignore */ } }
+  const fileOf = (id) => path.join(dir, `${id}.json`)
+  const listIds = () => {
+    try { return fs.readdirSync(dir).filter((name) => name.endsWith('.json')).map((name) => name.slice(0, -5)).sort() } catch { return [] }
+  }
+
+  function enqueue(payload) {
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload)) throw new TypeError('enqueue: payload object required')
+    ensureDir(dir)
+    const id = `out-${now()}-${randomUUID()}`
+    const record = { id, payload, createdAt: now(), attempts: 0, nextAt: 0 }
+    writeJsonAtomic(fileOf(id), record)
+    return record
+  }
+
+  async function post(target, payload) {
+    const response = await fetchImpl(`${target.url}/fang/api/decisions/ingest`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'x-fang-auth': target.token },
+      body: JSON.stringify(payload),
+    })
+    const text = await response.text().catch(() => '')
+    let body = null
+    try { body = JSON.parse(text) } catch { body = null }
+    return { ok: response.ok, status: response.status, body }
+  }
+
+  /** 先直连母体；失败（含母体不可达）就落 outbox，返回 queued:true。 */
+  async function submit(payload, { motherDataDir } = {}) {
+    const target = resolveMotherTarget(motherDataDir)
+    if (!target.ok) {
+      const record = enqueue(payload)
+      return { ok: true, queued: true, outboxId: record.id, ticket: null, reason: target.reason }
+    }
+    try {
+      const result = await post(target, payload)
+      if (result.ok) return { ok: true, queued: false, status: result.status, ticket: result.body?.ticket ?? null }
+      const record = enqueue(payload)
+      record.lastStatus = result.status
+      writeJsonAtomic(fileOf(record.id), record)
+      return { ok: true, queued: true, outboxId: record.id, ticket: null, reason: `http-${result.status}` }
+    } catch (error) {
+      const record = enqueue(payload)
+      log('warn', `submit queued: ${String(error?.message ?? error)}`)
+      return { ok: true, queued: true, outboxId: record.id, ticket: null, reason: 'network-error' }
+    }
+  }
+
+  /** 重放 outbox；成功即删文件，失败保留并写退避 nextAt。 */
+  async function flush({ motherDataDir, limit = 50 } = {}) {
+    const target = resolveMotherTarget(motherDataDir)
+    const ids = listIds()
+    if (!target.ok) return { ok: false, reason: target.reason, sent: 0, failed: 0, remaining: ids.length }
+    let sent = 0
+    let failed = 0
+    for (const id of ids.slice(0, Math.max(0, limit))) {
+      const record = readJson(fileOf(id), null)
+      if (!record?.payload) { try { fs.unlinkSync(fileOf(id)) } catch { /* ignore */ } continue }
+      try {
+        const result = await post(target, record.payload)
+        if (result.ok) {
+          try { fs.unlinkSync(fileOf(id)) } catch { /* ignore */ }
+          sent += 1
+        } else {
+          record.attempts = (Number(record.attempts) || 0) + 1
+          record.nextAt = now() + Math.min(60_000, 2 ** record.attempts * 1000)
+          record.lastStatus = result.status
+          writeJsonAtomic(fileOf(id), record)
+          failed += 1
+        }
+      } catch (error) {
+        record.attempts = (Number(record.attempts) || 0) + 1
+        record.nextAt = now() + Math.min(60_000, 2 ** record.attempts * 1000)
+        record.lastError = String(error?.message ?? error).slice(0, 300)
+        writeJsonAtomic(fileOf(id), record)
+        failed += 1
+      }
+    }
+    return { ok: true, sent, failed, remaining: listIds().length }
+  }
+
+  return {
+    dir,
+    enqueue,
+    submit,
+    flush,
+    pending: () => listIds().length,
+    list: () => listIds().map((id) => readJson(fileOf(id), null)).filter(Boolean),
+  }
+}

package/src/decision-center/lib/producer-contract.mjs

@@ -0,0 +1,162 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+//
+// producer-contract — 业务生产者 → 决策中心的统一调用契约（v1）。
+//
+// 这五个系统本体不在本仓：本模块只定义「它们该怎么调用」，并提供：
+//   * normalizeProducerPayload(input)  字段校验 + 默认值 + 稳定 dedupeKey
+//   * createProducerSubmitter({submit}) 统一提交封装（返回统一 envelope）
+//   * producerCatalog()                机器可读契约目录（UI/外部系统可发现）
+import { nowMs } from '../kernel.mjs'
+
+export const PRODUCER_CONTRACT_VERSION = 1
+export const PRODUCER_LEVELS = Object.freeze(['red', 'yellow', 'blue', 'green'])
+export const PRODUCER_NAMES = Object.freeze(['HarnessMM', 'PluginUpdater', 'SuperAgent', 'PJM', 'Worker'])
+
+export const PRODUCER_CONTRACTS = Object.freeze({
+  HarnessMM: Object.freeze({
+    kinds: ['harnessmm-suggestion'],
+    defaultLevel: 'blue',
+    sourceRole: 'worker',
+    required: ['title'],
+    defaultActions: [
+      { id: 'accept', label: '采纳', type: 'default' },
+      { id: 'ignore', label: '忽略', type: 'default' },
+    ],
+  }),
+  PluginUpdater: Object.freeze({
+    kinds: ['plugin-updater-backup'],
+    defaultLevel: 'green',
+    sourceRole: 'worker',
+    required: ['title'],
+    defaultActions: [],
+  }),
+  SuperAgent: Object.freeze({
+    kinds: ['superagent-completion'],
+    defaultLevel: 'green',
+    sourceRole: 'worker',
+    required: ['title'],
+    defaultActions: [],
+  }),
+  PJM: Object.freeze({
+    kinds: ['pjm-timeout', 'pjm-fatal'],
+    defaultLevel: 'yellow',
+    sourceRole: 'pjm',
+    required: ['title'],
+    defaultActions: [
+      { id: 'retry', label: '重试', type: 'primary' },
+      { id: 'abandon', label: '放弃', type: 'default' },
+    ],
+  }),
+  Worker: Object.freeze({
+    kinds: ['worker-deviation'],
+    defaultLevel: 'yellow',
+    sourceRole: 'worker',
+    required: ['title'],
+    defaultActions: [
+      { id: 'review', label: '查看', type: 'primary' },
+      { id: 'ignore', label: '忽略', type: 'default' },
+    ],
+  }),
+})
+
+const fail = (code, extra = {}) => ({ ok: false, code, ...extra })
+
+/** 稳定默认 dedupeKey：调用方显式传优先，否则用常见业务 id 派生。 */
+function deriveDedupeKey(producer, kind, raw) {
+  if (raw.dedupeKey !== undefined && raw.dedupeKey !== null && String(raw.dedupeKey).trim()) return String(raw.dedupeKey).trim().slice(0, 200)
+  const ref = raw.id ?? raw.backupId ?? raw.suggestionId ?? raw.taskId ?? raw.projectId ?? raw.workerId
+  if (ref === undefined || ref === null || String(ref).trim() === '') return undefined
+  return `${producer}:${kind}:${String(ref).trim()}`.slice(0, 200)
+}
+
+/**
+ * 校验并补全统一 payload。成功返回 { ok:true, payload }；失败返回 { ok:false, code, errors }。
+ * 不写盘、不提交。
+ */
+export function normalizeProducerPayload(input = {}) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return fail('invalid-payload')
+  const producer = String(input.producer ?? '').trim()
+  const contract = PRODUCER_CONTRACTS[producer]
+  if (!contract) return fail('unknown-producer', { allowedProducers: [...PRODUCER_NAMES] })
+  const kind = String(input.kind ?? contract.kinds[0]).trim()
+  if (!contract.kinds.includes(kind)) {
+    return fail('unknown-kind', { producer, allowedKinds: [...contract.kinds] })
+  }
+  const level = input.level === undefined || input.level === null ? contract.defaultLevel : String(input.level).trim().toLowerCase()
+  if (!PRODUCER_LEVELS.includes(level)) return fail('bad-level', { allowedLevels: [...PRODUCER_LEVELS] })
+  const title = String(input.title ?? '').trim()
+  if (!title) return fail('title-required')
+  const actions = Array.isArray(input.actions) ? input.actions.slice(0, 12)
+    : (Array.isArray(contract.defaultActions) && contract.defaultActions.length > 0 ? contract.defaultActions.map((item) => ({ ...item })) : undefined)
+  const options = Array.isArray(input.options) ? input.options.slice(0, 12) : undefined
+  if (level !== 'green' && !(actions?.length) && !(options?.length)) {
+    return fail('options-or-actions-required', { level })
+  }
+  const timeoutMinutes = Number.isFinite(Number(input.timeoutMinutes))
+    ? Math.max(0, Number(input.timeoutMinutes))
+    : kind === 'pjm-timeout' ? 5 : undefined
+  const payload = {
+    producer,
+    kind,
+    level,
+    title: title.slice(0, 500),
+    context: String(input.context ?? input.description ?? `${producer}/${kind}`).slice(0, 12000),
+    ...(actions ? { actions } : {}),
+    ...(options ? { options } : {}),
+    ...(timeoutMinutes === undefined ? {} : { timeoutMinutes }),
+    ...(deriveDedupeKey(producer, kind, input) ? { dedupeKey: deriveDedupeKey(producer, kind, input) } : {}),
+    sourceRole: String(input.sourceRole ?? contract.sourceRole),
+    ...(input.sessionId ? { sessionId: String(input.sessionId).slice(0, 200) } : {}),
+    ...(input.metadata && typeof input.metadata === 'object' ? { metadata: input.metadata } : {}),
+    producerContractVersion: PRODUCER_CONTRACT_VERSION,
+    at: nowMs(),
+  }
+  return { ok: true, payload }
+}
+
+/** 统一提交封装：返回固定 envelope，外部系统不需要理解 decision-center 内部形状。 */
+export function createProducerSubmitter({ submit } = {}) {
+  if (typeof submit !== 'function') throw new TypeError('createProducerSubmitter: submit required')
+  return async function submitProducerEvent(input = {}) {
+    const normalized = normalizeProducerPayload(input)
+    if (!normalized.ok) {
+      return { ok: false, code: normalized.code, errors: normalized.errors ?? null, ...normalized }
+    }
+    let out = null
+    try {
+      out = await submit(normalized.payload)
+    } catch (error) {
+      return { ok: false, code: 'submit-failed', error: String(error?.message ?? error).slice(0, 500) }
+    }
+    return {
+      ok: out?.ok !== false,
+      producer: normalized.payload.producer,
+      kind: normalized.payload.kind,
+      level: normalized.payload.level,
+      ticketId: out?.ticket?.id ?? null,
+      deduped: out?.deduped === true,
+      queued: out?.queued === true,
+      outboxId: out?.outboxId ?? null,
+      reason: out?.reason ?? null,
+    }
+  }
+}
+
+export function producerCatalog() {
+  return {
+    ok: true,
+    version: PRODUCER_CONTRACT_VERSION,
+    producers: PRODUCER_NAMES.map((producer) => {
+      const contract = PRODUCER_CONTRACTS[producer]
+      return {
+        producer,
+        kinds: [...contract.kinds],
+        defaultLevel: contract.defaultLevel,
+        sourceRole: contract.sourceRole,
+        required: [...contract.required],
+        payload: ['producer', 'kind', 'level?', 'title', 'context', 'actions|options', 'timeoutMinutes?', 'dedupeKey?', 'sourceRole?', 'sessionId?'],
+      }
+    }),
+  }
+}