@twinsearth/fang-dsh-plugin 0.0.0-stage → 3.3.4

package/src/lib/decision-events.mjs

@@ -0,0 +1,129 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+//
+// decision-events — 决策中心 bus 事件 → 一条 HTTP SSE 流。
+//
+// 只负责「把事件写进一个已鉴权的响应」：路由层负责 auth/Host/Origin，本模块不碰 token。
+// 事件：ready（初始 rev/计数）、ticket（created/updated）、ping（心跳）。
+// 客户端断开/出错即退订，绝不把 bus listener 泄漏到下一个请求。
+export const DECISION_EVENT_TOPICS = Object.freeze([
+  'fang/decision-created',
+  'fang/decision-updated',
+])
+
+/**
+ * @param {object} input
+ * @param {any} input.req
+ * @param {any} input.res 已通过路由鉴权的 Node 响应
+ * @param {{on:Function,off?:Function}} input.bus kernel bus
+ * @param {{list?:Function}} [input.center] 决策中心服务（只读 list 用于 ready）
+ * @param {number} [input.heartbeatMs]
+ * @param {Function} [input.now]
+ * @returns {{close:Function, send:Function, headers:object, closed:boolean}}
+ */
+export function openDecisionEventStream({
+  req,
+  res,
+  bus,
+  center = null,
+  heartbeatMs = 15000,
+  now = () => Date.now(),
+} = {}) {
+  if (!req || !res || !bus || typeof bus.on !== 'function') {
+    throw new Error('openDecisionEventStream: req/res/bus required')
+  }
+  const headers = {
+    'content-type': 'text/event-stream; charset=utf-8',
+    'cache-control': 'no-store, no-cache, must-revalidate',
+    connection: 'keep-alive',
+    'x-accel-buffering': 'no',
+  }
+  res.writeHead(200, headers)
+  try { res.flushHeaders?.() } catch { /* fake/undici responses may not support it */ }
+
+  let closed = false
+  const cleanups = []
+  const send = (event, data) => {
+    if (closed) return false
+    try {
+      res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`)
+      return true
+    } catch {
+      close()
+      return false
+    }
+  }
+  const close = () => {
+    if (closed) return
+    closed = true
+    for (const off of cleanups.reverse()) {
+      try { if (typeof off === 'function') off() } catch { /* ignore */ }
+    }
+    cleanups.length = 0
+    try { res.end() } catch { /* ignore */ }
+  }
+
+  // ready：客户端据此判断「这确实是新流的首帧」，而不是把旧缓存当实时。
+  let initial = null
+  try { initial = typeof center?.list === 'function' ? center.list({ includeArchived: false }) : null } catch { initial = null }
+  send('ready', {
+    at: now(),
+    rev: Number(initial?.rev) || 0,
+    counts: initial?.counts ?? null,
+  })
+
+  for (const topic of DECISION_EVENT_TOPICS) {
+    const handler = (ticket) => {
+      send('ticket', {
+        at: now(),
+        type: topic.endsWith('-created') ? 'created' : 'updated',
+        // 紧凑提示字段（客户端也可只按 rev 拉增量），ticket 一并带上避免多一跳。
+        rev: Number(ticket?.rev) || 0,
+        ids: ticket?.id ? [String(ticket.id)] : [],
+        ticket,
+      })
+    }
+    const off = bus.on(topic, handler)
+    cleanups.push(() => { try { if (typeof off === 'function') off(); else bus.off?.(topic, handler) } catch { /* ignore */ } })
+  }
+
+  const heartbeat = setInterval(() => {
+    if (!send('ping', { at: now() })) return
+  }, Math.max(10, Number(heartbeatMs) || 15000))
+  heartbeat.unref?.()
+  cleanups.push(() => clearInterval(heartbeat))
+
+  for (const [target, event] of [[req, 'close'], [req, 'aborted'], [res, 'close'], [res, 'error']]) {
+    if (target && typeof target.on === 'function') {
+      const fn = () => close()
+      try { target.on(event, fn) } catch { /* ignore */ }
+      cleanups.push(() => { try { target.removeListener?.(event, fn) } catch { /* ignore */ } })
+    }
+  }
+
+  return { close, send, headers, get closed() { return closed } }
+}
+
+/** 紧凑的 SSE 帧解析（客户端/测试共用；不依赖 EventSource）。 */
+export function parseSseFrames(buffer = '') {
+  const frames = []
+  let rest = String(buffer)
+  for (;;) {
+    const index = rest.indexOf('\n\n')
+    if (index < 0) break
+    const raw = rest.slice(0, index)
+    rest = rest.slice(index + 2)
+    let event = 'message'
+    const dataLines = []
+    for (const line of raw.split('\n')) {
+      if (line.startsWith('event:')) event = line.slice(6).trim()
+      else if (line.startsWith('data:')) dataLines.push(line.slice(5).trimStart())
+    }
+    let data = null
+    if (dataLines.length) {
+      try { data = JSON.parse(dataLines.join('\n')) } catch { data = null }
+    }
+    frames.push({ event, data })
+  }
+  return { frames, rest }
+}

package/src/lib/decision-ingest-client.mjs

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+//
+// decision-ingest-client — 给独立进程（PJM/Worker/HarnessMM/PluginUpdater/SuperAgent）
+// 用的 fork 侧 ingest 客户端：
+//   * 从母体 dataDir 发现 endpoint + token（DSH_FANG_MOTHER 或显式路径）
+//   * 直连 POST /fang/api/decisions/ingest
+//   * 失败时落本地 outbox，可 flush 重放（耐久，不丢 ticket）
+// 注意：客户端存在 ≠ 业务已接；外部进程仍需在事件处调用 .submit()。
+import process from 'node:process'
+
+import { createDecisionOutbox, resolveMotherTarget } from './decision-outbox.mjs'
+
+export function createForkIngestClient({
+  dataDir,
+  motherDataDir = process.env.DSH_FANG_MOTHER,
+  fetchImpl,
+  logger,
+} = {}) {
+  const dir = String(dataDir ?? '').trim()
+  if (!dir) throw new TypeError('createForkIngestClient: dataDir required (outbox directory)')
+  const outbox = createDecisionOutbox({ dataDir: dir, fetchImpl, logger })
+  const target = () => resolveMotherTarget(motherDataDir)
+  return {
+    target,
+    motherDataDir: String(motherDataDir ?? ''),
+    /** 直连母体；失败自动落 outbox，返回 {ok, queued, ticket, outboxId?}。 */
+    submit(payload) {
+      return outbox.submit(payload, { motherDataDir })
+    },
+    flush() {
+      return outbox.flush({ motherDataDir })
+    },
+    pending() {
+      return outbox.pending()
+    },
+    list() {
+      return outbox.list()
+    },
+  }
+}

package/src/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/index.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/lib/decision-policy.mjs

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+//
+// v3.2.0 四色决策状态机（唯一事实来源）。
+// `expiresAt` 是归档期限；`waitDeadlineAt` 只是 Agent 的流程等待窗口，二者不可混用。
+export const DECISION_LEVEL_POLICY = Object.freeze({
+  red: Object.freeze({ waitMode: 'human', graceMs: null, afterWait: 'keep-waiting', label: '必须人工选择', priority: 'P0', risk: 'high' }),
+  yellow: Object.freeze({ waitMode: 'grace-defer', graceMs: 3 * 60_000, afterWait: 'defer', label: '3 分钟后继续，可补选', priority: 'P1', risk: 'medium' }),
+  blue: Object.freeze({ waitMode: 'grace-recommended', graceMs: 60_000, afterWait: 'recommended', label: '1 分钟后按推荐执行', priority: 'P2', risk: 'low' }),
+  green: Object.freeze({ waitMode: 'immediate', graceMs: 0, afterWait: 'recommended', label: '自动执行并留底', priority: 'P3', risk: 'info' }),
+})
+
+export const DECISION_PRIORITIES = Object.freeze(['P0', 'P1', 'P2', 'P3'])
+export const DECISION_RISKS = Object.freeze(['high', 'medium', 'low', 'info'])
+
+/** 调用方可以覆盖默认优先级/风险（例如低等级但高风险的安全票）。 */
+export function normalizeDecisionPriority(value, level) {
+  const raw = String(value ?? '').trim().toUpperCase()
+  if (DECISION_PRIORITIES.includes(raw)) return raw
+  return decisionPolicy(level).priority
+}
+
+export function normalizeDecisionRisk(value, level) {
+  const raw = String(value ?? '').trim().toLowerCase()
+  const alias = { critical: 'high', high: 'high', medium: 'medium', med: 'medium', low: 'low', info: 'info', none: 'info' }
+  const mapped = alias[raw]
+  if (mapped) return mapped
+  return decisionPolicy(level).risk
+}
+
+export function decisionPolicy(level) {
+  return DECISION_LEVEL_POLICY[level] ?? DECISION_LEVEL_POLICY.yellow
+}
+
+export function decisionWaitMs(level, timeoutMinutes) {
+  const policy = decisionPolicy(level)
+  if (policy.graceMs === null) return null
+  // timeoutMinutes 对黄/蓝表示等待窗口；未显式指定时使用该等级的默认值。
+  const override = Number(timeoutMinutes)
+  if (Number.isFinite(override) && override > 0) return Math.max(1, Math.round(override * 60_000))
+  return policy.graceMs
+}
+
+/** 推荐项优先；低风险票没有推荐标记时确定性地取第一项，保证流程能继续。 */
+export function recommendedDecisionOption(options) {
+  const list = Array.isArray(options) ? options : []
+  return list.find((option) => option?.isRecommended === true) ?? list[0] ?? null
+}
+
+export function isDeferredDecision(ticket) {
+  return ticket?.status === 'pending' && ticket?.level === 'yellow' && Number(ticket?.deferredAt) > 0
+}

package/src/lib/default-essence.mjs

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// 新用户默认“元宝”：安装不激活 / 安装并激活 两组插件，以及本机插件配置复制选项。
+export const DEFAULT_ESSENCE_NAME = '默认元宝'
+
+export const DEFAULT_ESSENCE_PRESET = Object.freeze({
+  version: 1,
+  groups: Object.freeze([
+    {
+      key: 'installed-inactive',
+      title: '安装不激活',
+      enabled: false,
+      specs: Object.freeze([
+        '@twinsearth/dsh-2xray',
+        '@michengai/dsh-agency-agents',
+        'dsh-better-sidebar',
+        'dsh-context',
+        '@liustack/modlens',
+        '@liustack/modsearch',
+      ]),
+    },
+    {
+      key: 'installed-active',
+      title: '安装并激活',
+      enabled: true,
+      specs: Object.freeze([
+        'dshmarket',
+        '@twinsearth/dsh-im2a-plugin',
+        '@openviking/dsh-memory-plugin',
+        '@twinsearth/w2m-dsh-plugin',
+      ]),
+    },
+  ]),
+})
+
+/** 从 pluginManager.listPlugins() 的结果里判断某个包是否已安装（模糊匹配包名末尾）。 */
+export function matchInstalled(entries, spec) {
+  const wanted = String(spec ?? '').toLowerCase()
+  const bare = wanted.includes('/') ? wanted.split('/').pop() : wanted
+  for (const entry of entries ?? []) {
+    const name = String(entry?.name ?? entry?.id ?? '').toLowerCase()
+    if (!name) continue
+    if (name === wanted || name.endsWith('/' + bare) || name.includes(bare)) return entry
+  }
+  return null
+}
+
+export function planDefaultEssence(entries) {
+  return {
+    name: DEFAULT_ESSENCE_NAME,
+    version: DEFAULT_ESSENCE_PRESET.version,
+    groups: DEFAULT_ESSENCE_PRESET.groups.map((group) => ({
+      key: group.key,
+      title: group.title,
+      enabled: group.enabled,
+      plugins: group.specs.map((spec) => {
+        const hit = matchInstalled(entries, spec)
+        return { spec, installed: Boolean(hit), pluginId: hit?.id ?? null }
+      }),
+    })),
+  }
+}

package/src/lib/desktop-launch.mjs

@@ -0,0 +1,138 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+//
+// desktop-launch — 把 DSH Desktop 启动挂到 restart-supervisor 下的「真实入口」适配器。
+//
+// 它不修改 DSH Desktop 安装目录，也不自动启动；只负责构造：
+//   node tools/restart-supervisor.mjs [--execute] --data-root <dir> -- <desktop-exe> <args...>
+// 由 supervisor 决定：退出码 75 + 已武装清单 + pid 匹配才重启；默认 dry-run。
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import {
+  applyDisabledRows,
+  checkBundleRows,
+  findFangPackageDir,
+  readBundleRows,
+  readPackageName,
+} from './boot-guard.mjs'
+
+const isExecutableFile = (file) => {
+  try { return fs.statSync(file).isFile() } catch { return false }
+}
+
+/** 从 env/DSH 参数推断本机 desktop profile（用于无 --profile-dir 时自动自检）。 */
+export function detectDesktopProfileDir({ env = process.env, args = [] } = {}) {
+  const hasPackage = (dir) => {
+    try { return isExecutableFile(path.join(String(dir), 'package.json')) } catch { return false }
+  }
+  const explicit = String(env?.DSH_PROFILE_DIR ?? '').trim()
+  if (explicit && hasPackage(explicit)) return path.resolve(explicit)
+  let profile = String(env?.DSH_PROFILE ?? '').trim()
+  if (!profile) {
+    const index = Array.isArray(args) ? args.findIndex((value) => value === '--profile' || value === '-p') : -1
+    if (index >= 0 && args[index + 1]) profile = String(args[index + 1])
+    else {
+      const inline = Array.isArray(args) ? args.find((value) => value.startsWith('--profile=')) : null
+      if (inline) profile = inline.slice('--profile='.length)
+    }
+  }
+  if (!profile) profile = 'desktop'
+  const home = String(env?.DSH_HOME ?? '').trim() || path.join(String(env?.USERPROFILE ?? env?.HOME ?? '').trim() || '.', '.dsh')
+  if (!home) return ''
+  const candidate = path.join(path.resolve(home), 'profiles', profile)
+  return hasPackage(candidate) ? candidate : ''
+}
+
+const pidAlive = (pid) => {
+  const value = Number(pid)
+  if (!Number.isInteger(value) || value <= 0) return false
+  try { process.kill(value, 0); return true } catch (error) { return error?.code === 'EPERM' }
+}
+
+/** 读取 restart-guard 写的 boot-state；上一进程 booting/crashed 且 pid 已死 = 启动期崩溃。 */
+export function readUncleanBoot(dataRoot) {
+  const root = String(dataRoot ?? '').trim()
+  if (!root) return null
+  try {
+    const file = path.join(path.resolve(root), 'restart', 'boot-state.json')
+    const raw = JSON.parse(fs.readFileSync(file, 'utf8'))
+    if (!raw || (raw.state !== 'booting' && raw.state !== 'crashed')) return null
+    if (Number(raw.pid) === process.pid) return null
+    if (pidAlive(raw.pid)) return null
+    return { state: String(raw.state), pid: Number(raw.pid) || null, at: Number(raw.at) || 0, error: raw.error ?? null }
+  } catch { return null }
+}
+
+/**
+ * 启动前跑 boot-guard：失败时可按“安全模式”禁用全部 fang 行。
+ * 默认不写 profile；调用方显式 safeModeOnFailure=true 才会改（会先备份）。
+ * dataRoot 给出时，若上次 boot-state 为 booting/crashed（启动期崩溃），同样走安全模式熔断。
+ */
+export function runBootGuard(profileDir, { dataRoot = '', safeModeOnFailure = false, timeoutMs = 8000 } = {}) {
+  const dir = String(profileDir ?? '').trim()
+  if (!dir) return { ok: true, skipped: 'no-profile-dir' }
+  const resolved = path.resolve(dir)
+  if (!isExecutableFile(path.join(resolved, 'package.json'))) return { ok: false, error: 'profile-package-missing', profileDir: resolved }
+  const pkgDir = findFangPackageDir(resolved)
+  if (!pkgDir) return { ok: true, skipped: 'fang-package-not-found', profileDir: resolved }
+  const parsed = readBundleRows(pkgDir)
+  if (!parsed.ok) return { ok: false, error: 'bundle-patch-invalid', detail: parsed.error, profileDir: resolved }
+  const uncleanBoot = readUncleanBoot(dataRoot)
+  const disableAllForSafeMode = (reason, findings) => {
+    const applied = applyDisabledRows(resolved, parsed.rows.map((row) => row.id))
+    if (!applied.ok) return { ok: false, error: 'safe-mode-apply-failed', detail: applied.error, findings, profileDir: resolved, reason }
+    return { ok: true, safeModeApplied: true, reason, applied, findings, checked: findings.length, profileDir: resolved, packageDir: pkgDir }
+  }
+  if (uncleanBoot) {
+    if (!safeModeOnFailure) return { ok: false, error: 'unclean-boot', uncleanBoot, profileDir: resolved, packageDir: pkgDir }
+    return disableAllForSafeMode('unclean-boot', [{ code: 'unclean-boot', level: 'block', detail: JSON.stringify(uncleanBoot) }])
+  }
+  const checked = checkBundleRows(parsed.rows, { profileDir: resolved, ownPackage: readPackageName(pkgDir), timeoutMs })
+  if (checked.ok) return { ok: true, checked: checked.checked, findings: checked.findings, profileDir: resolved, packageDir: pkgDir }
+  const blocked = checked.findings.filter((finding) => finding.level === 'block')
+  if (!safeModeOnFailure) {
+    return { ok: false, error: 'boot-guard-blocked', findings: checked.findings, blocked, profileDir: resolved, packageDir: pkgDir }
+  }
+  return disableAllForSafeMode('boot-guard-blocked', checked.findings)
+}
+
+/**
+ * @param {{exe?:string, dataRoot?:string, profileDir?:string, args?:string[], execute?:boolean, nodePath?:string, supervisorPath?:string}} input
+ * @returns {{ok:true, argv:string[], dryRun:boolean, exe:string, dataRoot:string, profileDir:string} | {ok:false, error:string}}
+ */
+export function resolveDesktopLaunch(input = {}) {
+  const exe = String(input.exe ?? '').trim()
+  if (!exe) return { ok: false, error: 'desktop-exe-required' }
+  const resolvedExe = path.resolve(exe)
+  if (!isExecutableFile(resolvedExe)) return { ok: false, error: 'desktop-exe-missing' }
+  const dataRoot = String(input.dataRoot ?? '').trim()
+  if (!dataRoot) return { ok: false, error: 'data-root-required' }
+  const resolvedRoot = path.resolve(dataRoot)
+  const profileDir = String(input.profileDir ?? '').trim()
+  if (profileDir) {
+    const resolvedProfile = path.resolve(profileDir)
+    if (!isExecutableFile(path.join(resolvedProfile, 'package.json'))) return { ok: false, error: 'profile-dir-missing' }
+  }
+  const supervisorPath = input.supervisorPath
+    ? path.resolve(String(input.supervisorPath))
+    : path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'tools', 'restart-supervisor.mjs')
+  if (!isExecutableFile(supervisorPath)) return { ok: false, error: 'supervisor-missing' }
+  const nodePath = String(input.nodePath ?? process.execPath)
+  const execute = input.execute === true
+  const desktopArgs = Array.isArray(input.args) ? input.args.map(String) : []
+  const argv = [
+    nodePath, supervisorPath,
+    ...(execute ? ['--execute'] : []),
+    '--data-root', resolvedRoot,
+    '--', resolvedExe, ...desktopArgs,
+  ]
+  return { ok: true, argv, dryRun: !execute, exe: resolvedExe, dataRoot: resolvedRoot, profileDir: profileDir ? path.resolve(profileDir) : '' }
+}
+
+/** 只用于展示，不做 shell 拼接执行。 */
+export function describeDesktopLaunch(plan) {
+  if (!plan?.ok) return `desktop-launch: ${plan?.error ?? 'invalid'}`
+  return `${plan.dryRun ? '[dry-run] ' : '[execute] '}${plan.argv.map((part) => (/\s/.test(part) ? JSON.stringify(part) : part)).join(' ')}`
+}