@cloud411716/fancy-webnovel 1.0.46 → 3.0.0

package/lib/infra.js

@@ -0,0 +1,594 @@
+/**
+ * infra.js — DSH Plugin Core Infrastructure
+ *
+ * Provides:
+ *   notify(session, kind, text)       — return success/error result for TUI toast + Web left-panel
+ *   llmFollowup(invocation, prompt)   — hand a prompt to the LLM as a user message
+ *   broadcastResult(invocation, name, result) — 显式把命令结果播报给 LLM（默认不调用）
+ *   askUserQuestion(ctx, invocation, questions) — ask the human, with DSH's error taxonomy mapped
+ *   spawnScript(cmd, args, opts)     — spawn child process, parse stdout JSON, retain stderr
+ *
+ * All fancy-* plugins import from this file.
+ *
+ * ── 铁律一：插件不碰会话 ──────────────────────────────────────────
+ *
+ * **插件自己不往会话里写任何事件**，也不为了"点亮对话视图"去唤醒 agent。
+ *
+ * 通知类消息（初始化成功、参数不正确、校验失败……）全部是**本地行为**：
+ * notify() → command/done → TUI toast + Web 左侧命令面板
+ * （dsh-commands 的 settle → channel.notify）。
+ * **一条通知都不进模型请求。**
+ *
+ * 用户原话（2026-10-26）：
+ *   「我希望fancy-webnovel的通知类消息，例如初始化成功,参数不正确等通知
+ *     都是"本地"的行为,不触发LLM,而不是像现在这样即便发送个空字符串都会触发llm」
+ *
+ * 这条铁律不是保守，是**有硬约束支撑的**：
+ *
+ *   · 插件自己 session.append 会抢走 transcript 的第一条（surface 头），
+ *     于是 agent 之后提交系统提示词时抛
+ *     "system/message requires a protected first surface head"
+ *     → **会话读不回来**（dsh-session-format-v2-to-v3/lib/index.js:432）；
+ *   · 而第一条必须是系统提示词（见下面"铁律二"），
+ *     插件写进去的东西会逼着系统提示词降级成 user 轮；
+ *   · 插件伪造 agent 的回合也不行：回合号必须严格递增，插件占掉 lastTurn+1
+ *     就会让 agent 下一回合的 turn/start 被判 "does not open expected turn"
+ *     （agent 在 session/create 时就构造，计数器已固化）。
+ *
+ * 详见 tests/cases/conversation-view.test.js。
+ *
+ * ── 铁律二：插件要跟模型说话，只有一条路 ────────────────────────────
+ *
+ * llmFollowup() → agent.followup()。由 agent loop 提交时，系统提示词排在前面、
+ * 插件的提示词排在后面（dsh-agent-loop:1024-1028）。
+ *
+ * ## 这里有一条不能破的顺序依赖
+ *
+ * **系统提示词必须是 transcript 的第一条消息。**
+ *
+ * pi-ai 的 splitSystemPrompt（dsh-llm-pi-ai/lib/index.js:1210-1214）
+ * **只认第一条**：首条不是 system 就不提取，真正的系统提示词会掉进
+ * `role === "system"` 分支（:1242-1248）被**转成一条 user 消息** ——
+ * 这就是"系统提示词从 system 轮降级成 user 轮"。
+ *
+ * 插件自己 session.append 会破坏它（插件的消息抢走第一条），
+ * 所以必须走 agent.followup：agent loop 先提交 system/message
+ * （dsh-agent-loop/lib/index.js:1024-1026），再提交插件的 user/message
+ * （:1028），顺序由 agent 保证。
+ *
+ * ⚠️ 改动投递顺序前先看这段：一旦系统提示词不再排第一，模型会在
+ * "降级后的提示词"下运行，而且**没有任何报错**。
+ *
+ * 不要自己 session.append('user/message', ...) 往请求里塞东西 —— 插件写进
+ * 会话的每一条消息都会进入下一次模型请求，而且会破坏 DSH「surface 头 =
+ * 系统提示词」的不变量（会话读不回来）。
+ *
+ * ## llmFollowup 的唯一判空规则
+ *
+ * 正文必须 **trim 后长度 > 0**。这条规则覆盖了所有会判空的路径：
+ * pi-ai 的 userContent 按 length 判（dsh-llm-pi-ai/lib/index.js:1144），
+ * DSH host 入口的 hasPromptContent 按 trim 判
+ * （dsh-api-session-controller/lib/index.js:548）。
+ * trim 后长度 > 0 的正文两条路都过 → **content 不可能被判成空**，
+ * provider 也就不会 400（"message content cannot be empty"）。
+ *
+ * 没有特例口子。空正文、纯空白正文一律拒绝投递 —— 空 content 到线就是
+ * provider 400（实测 2026-10-26，agnes-2.5-flash）。
+ *
+ * 命令结果本身不走模型：左侧命令面板已经是完整结果，没必要再让模型转述
+ * 一遍 —— 实测 2026-10-25：模型收到"命令失败"播报后自己去跑 which / ls /
+ * npm list 排查插件，既烧额度又不可控。
+ *
+ * 确实需要把结果交给模型时，显式调用 broadcastResult(invocation, 插件名, result)。
+ */
+
+import { spawn } from 'child_process';
+import { randomUUID } from 'crypto';
+import { join, resolve } from 'path';
+
+// --------------------------------------------------------------------------
+// ANSI escape cleanup
+// --------------------------------------------------------------------------
+
+/**
+ * Strip ANSI escape sequences from a string (defensive, prevents TTY leak).
+ * Handles CSI (e.g. \x1b[31m), OSC (e.g. \x1b]...\x07) and charset selection.
+ */
+export function stripAnsi(str) {
+  return String(str)
+    .replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, '')    // CSI: \x1b[...<final>
+    .replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, '') // OSC: \x1b]...\x07 or \x1b\\
+    .replace(/\x1b[()][AB012]/g, '')              // Charset selection
+    .replace(/\x1b[=>NOMc78]/g, '');             // Single-char controls
+}
+
+// --------------------------------------------------------------------------
+// notify — return error result propagated through dsh-commands settleThrown()
+// --------------------------------------------------------------------------
+
+/**
+ * @param {object} _session - DSH Session object (kept for API compatibility; unused)
+ * @param {'error'|'success'} kind
+ * @param {string} text
+ * @returns {{ kind: 'error'|'success', text: string }} Result propagated through
+ *   dsh-commands settleThrown() → command/done → channel.notify() (TUI toast)
+ *   and command/done (Web left-panel with real commandId prefix)
+ */
+export function notify(_session, kind, text) {
+  return { kind, text: stripAnsi(text) };
+}
+
+// ---------------------------------------------------------------------------
+// askUserQuestion — 向用户提问，统一处理 DSH 的错误码
+// ---------------------------------------------------------------------------
+
+/**
+ * DSH 的 UserQuestionError 码全集（权威来源：@deepseek-ai/dsh-user-questions
+ * 的 README 与 lib/types/index.js）：
+ *   EMPTY_QUESTIONS / BAD_INTENT / NO_PROVIDER / ASK_ABORTED /
+ *   CALLER_NOT_LIVE / DELEGATED_CALLER
+ *
+ * 此前各插件自己写 try/catch，只认其中 3 个码，其余落到 `throw err`
+ * 重新抛出 —— 命令会带着未捕获异常结束，用户看到的是原始错误而不是
+ * 可读提示。CALLER_NOT_LIVE（会话已被 dispose）与 DELEGATED_CALLER
+ * （在子代理里运行）都是实际会遇到的场景。
+ */
+export function classifyUserQuestionError(err) {
+  const code = err && typeof err.code === 'string' ? err.code : '';
+  const message = err && err.message ? err.message : String(err || '未知错误');
+  if (code === 'ASK_ABORTED' || code === 'ASK_CANCELLED') {
+    return { type: 'cancelled', message: null };
+  }
+  if (code === 'NO_PROVIDER') {
+    return { type: 'no_provider', message: null };
+  }
+  if (code === 'CALLER_NOT_LIVE' || code === 'DELEGATED_CALLER' || code === 'ASK_MISSING_AGENT') {
+    return {
+      type: 'ask_failed',
+      message: '当前会话已不处于可交互状态（可能已被关闭，或该命令运行在子代理里）。' +
+        '请回到主会话重新执行本命令。'
+    };
+  }
+  if (code === 'EMPTY_QUESTIONS' || code === 'BAD_INTENT') {
+    return { type: 'ask_failed', message: '提问内容不被 DSH 接受（' + code + '）：' + message };
+  }
+  return { type: 'ask_failed', message: message };
+}
+
+/**
+ * 找出提问内容里**不能安全 JSON 化**的值。
+ *
+ * DSH 的 api gateway 在远程（web UI 连远端 host）模式下会校验提问请求
+ * 必须是"lossless JSON"：属性值不允许是 undefined —— JSON.stringify 会
+ * 悄悄丢掉 undefined，但网关按**属性存在性**判定，所以
+ * `{ label: '番茄', description: undefined }` 会被整个请求被拒：
+ *   "api gateway: Remote event request is not lossless JSON data"
+ *
+ * 这个错误看不出是哪个字段的问题，只能靠猜。这里在本地先扫一遍，
+ * 把位置定位到具体路径，让错误信息直接可执行。
+ *
+ * 只检查"一定会出问题"的值（undefined / function / symbol / bigint /
+ * NaN / Infinity），不做原型等更严格的判定 —— 避免误报。
+ */
+function findNonJsonValues(value, path = '', out = [], seen = new Set()) {
+  if (value === null) return out;
+  const t = typeof value;
+  if (t === 'string' || t === 'boolean') return out;
+  if (t === 'number') {
+    if (!Number.isFinite(value)) out.push(`${path} = ${value}`);
+    return out;
+  }
+  if (t === 'undefined' || t === 'function' || t === 'symbol' || t === 'bigint') {
+    out.push(`${path} = ${t}`);
+    return out;
+  }
+  if (t !== 'object') return out;
+  if (seen.has(value)) return out;   // 循环引用不重复报
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      for (let i = 0; i < value.length; i++) {
+        findNonJsonValues(value[i], `${path}[${i}]`, out, seen);
+      }
+      return out;
+    }
+    for (const key of Object.keys(value)) {
+      findNonJsonValues(value[key], `${path}.${key}`, out, seen);
+    }
+    return out;
+  } finally {
+    seen.delete(value);
+  }
+}
+
+/**
+ * 问用户一个问题，**永不抛异常**。
+ *
+ * @returns {Promise<{ok: boolean, answer: object|null, failure: {type: string, message: string|null}|null}>}
+ *          failure.type 可直接作为插件 notify 的 type：
+ *          'cancelled' / 'no_provider' / 'ask_failed'
+ */
+export async function askUserQuestion(ctx, invocation, questions) {
+  // 送进 DSH 之前先本地预检：远程模式下这类问题会让网关直接拒掉整个请求，
+  // 而且报出来的错误完全指不到字段（"Remote event request is not lossless
+  // JSON data"）。本地拦住才能给出可执行的提示。
+  const bad = findNonJsonValues(questions, 'questions');
+  if (bad.length) {
+    return {
+      ok: false,
+      answer: null,
+      failure: {
+        type: 'ask_failed',
+        message: '提问内容含有无法 JSON 化的值，DSH 会拒收整个请求：' + bad.join('、') +
+          '。可选字段请直接省略该键，不要传 undefined。',
+      },
+    };
+  }
+  try {
+    const answer = await ctx.userQuestions.ask({
+      questions,
+      agent: invocation.agent,
+      signal: invocation.signal,
+    });
+    return { ok: true, answer, failure: null };
+  } catch (err) {
+    return { ok: false, answer: null, failure: classifyUserQuestionError(err) };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// llmFollowup — 发送消息给 LLM，让 LLM 在同一 session 继续处理
+// ---------------------------------------------------------------------------
+
+/**
+ * 构造一条 DSH 的 UserMessage。
+ *
+ * 单独导出（而不是把字面量埋在 llmFollowup 里）：用例要断言的是**消息对象的
+ * 字段**，直接调用真函数比对，比去源码里刮字符串可靠得多 —— 源码刮取会
+ * 被任何一次重构打断，而且只能看到"写没写"，看不到"对不对"。
+ *
+ * @param {string} text - 提示词正文（调用方保证非空字符串；正文还必须
+ *   trim 不掉 —— 见 llmFollowup 的"唯一判空规则"）
+ * @returns {{id: string, role: string, content: Array, source: object}}
+ */
+export function buildUserMessage(text) {
+  return {
+    // DSH 的 Message.id 契约是"跨所有表示边界保持的稳定身份"。
+    // 此前用 Date.now()，同一毫秒内两次投递会产生相同 id；当前各次投递
+    // 间隔远超 1ms 所以没暴露，但并发投递就会撞 id。
+    id: 'llm-followup-' + randomUUID(),
+    role: 'user',
+    content: [{ type: 'text', text }],
+    source: { kind: 'user' },
+  };
+}
+
+/**
+ * 给 LLM 投递一条 user 消息。
+ *
+ * ## 唯一判空规则（没有特例）
+ *
+ * 正文必须 **trim 后长度 > 0**。
+ *
+ * 这条规则覆盖了所有会判空的路径：
+ *   · **按 length 判**：pi-ai 适配器丢掉空文本块
+ *     （dsh-llm-pi-ai/lib/index.js:1144 `if (block.text.length > 0)`），
+ *     消息内容变成空数组 → provider 400 "message content cannot be empty"。
+ *   · **按 trim 判**：DSH 自己的 host 入口
+ *     （dsh-api-session-controller/lib/index.js:548
+ *     `part.text.trim().length > 0`）—— 纯空白正文在那条路上直接被拒。
+ *
+ * trim 后长度 > 0 的正文，两条路都过 → **content 不可能被判成空**。
+ * 普通空格只过得了第一条（实测：走 session/prompt 被拒，accepted=None）。
+ *
+ * **没有特例口子。** 曾经为了"点亮对话视图"开过一个 allowEmptyBody 开关
+ * （允许投递零长度正文），2026-10-26 连同整个点亮机制一起删掉了 ——
+ * 通知类消息必须是纯本地行为，不该为了点亮视图去唤醒模型。
+ *
+ * @param {object} invocation - DSH 命令调用对象
+ * @param {string|object|null|undefined} content - 提示词正文
+ * @returns {{ok: boolean, error: string|null}}
+ */
+/**
+ * 给所有插件提示词追加统一的临时文件规则。
+ *
+ * 绝对路径来自会话 cwd（工作区目录），不依赖宿主进程的 process.cwd()。
+ */
+export function tempDirInstruction(invocation) {
+  const cwd = invocation && invocation.agent && invocation.agent.session
+    && invocation.agent.session.header
+    && invocation.agent.session.header.cwd;
+  if (typeof cwd !== 'string' || !cwd.trim()) return '';
+  const tempDir = join(resolve(cwd), '.tmp');
+  return [
+    '',
+    '【临时文件规则】',
+    '如果需要创建临时文件，必须创建在以下绝对路径目录中：',
+    tempDir,
+    '创建目录可用：mkdir -p ' + tempDir,
+    '不要把临时文件直接放在工作区目录、/tmp 或其他位置。',
+    '临时文件创建后不允许删除（任务结束也不要清理）；需要重写时直接覆盖同一个文件。',
+  ].join('\n');
+}
+
+export function llmFollowup(invocation, content, options) {
+  let prompt;
+  try {
+    if (typeof content === 'string') prompt = content;
+    else if (content === null || content === undefined) prompt = '';
+    else prompt = JSON.stringify(content);
+  } catch (e) {
+    const reason = '提示词无法序列化：' + (e && e.message ? e.message : String(e));
+    console.error('[llmFollowup]', reason);
+    return { ok: false, error: reason };
+  }
+  if (typeof prompt !== 'string' || prompt.length === 0) {
+    const reason = '提示词为空字符串，拒绝投递（空消息会被 provider 拒收：message content cannot be empty）';
+    console.error('[llmFollowup]', reason);
+    return { ok: false, error: reason };
+  }
+  if (prompt.trim().length === 0) {
+    const reason = '提示词为空，拒绝投递（空消息会被 provider 拒收：message content cannot be empty）';
+    console.error('[llmFollowup]', reason);
+    return { ok: false, error: reason };
+  }
+  try {
+    const appendTempRule = !options || options.appendTempRule !== false;
+    const finalPrompt = appendTempRule ? prompt + tempDirInstruction(invocation) : prompt;
+    const message = buildUserMessage(finalPrompt);
+    const agent = invocation.agent;
+    // DSH 对两者的语义区分得很明确：
+    //   followup() — "排一个普通的后续 turn 并唤醒驱动器，
+    //                该项成为它自己 turn 的唯一普通消息"（正是这里要的）
+    //   send()    — "路由到 inbox 边界，wakeup 只是'可能唤醒'"
+    // 优先用语义更准的 followup；旧运行时没有该方法时退回 send。
+    if (agent && typeof agent.followup === 'function') {
+      agent.followup(message);
+    } else {
+      agent.send(message, 'next-turn', true);
+    }
+    // 记账：本次命令已经派过模型消息。
+    // broadcastResult 据此判断"要不要播报"——派过活就不播，
+    // 那条真实提示词本身就把对话视图激活了。
+    markDispatched(invocation);
+    // 注意：这里的 ok 只代表"消息已入队"，不代表模型已处理。
+    // DSH 的 send/followup 都返回 void，真正的模型调用在后续 agent loop 里
+    // 异步发生（其 whenIdle 文档亦明确："does not identify the settlement
+    // of any particular message"）。
+    return { ok: true, error: null };
+  } catch (e) {
+    // 记录并把失败结果返回给调用方：此前这里只 console.error，
+    // 导致调用方的 try/catch 永远捕获不到失败，会把"投递失败"当成"阶段已开始"。
+    console.error('[llmFollowup error]', e);
+    return { ok: false, error: e && e.message ? e.message : String(e) };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 命令结果播报 —— 显式调用才会给 LLM 发消息
+// ---------------------------------------------------------------------------
+
+/**
+ * 本次命令已经派过模型消息的记账。
+ *
+ * invocation 是 DSH 冻结的对象（dsh-commands/lib/index.js:369
+ * `Object.freeze({commandId, agent, rawInput, attachments, signal})`），
+ * 挂不上去标记，只能用 WeakSet 记账 —— 也不能用普通 Map：命令结束就没人
+ * 再看这个 invocation，不回收会漏内存。
+ */
+const dispatchedInvocations = new WeakSet();
+
+/** 记账：本次命令已派过模型消息。 */
+export function markDispatched(invocation) {
+  if (invocation && (typeof invocation === 'object' || typeof invocation === 'function')) {
+    dispatchedInvocations.add(invocation);
+  }
+}
+
+/** 本次命令是否派过模型消息。 */
+export function hasDispatched(invocation) {
+  return Boolean(invocation) && dispatchedInvocations.has(invocation);
+}
+
+/** 结果播报正文的最大长度（超了截断；完整内容仍在命令面板里）。 */
+const BROADCAST_MAX = 1500;
+
+/**
+ * 构造"命令结果播报"的文本。
+ *
+ * **默认不会发**：命令结果已经在左侧命令面板里完整呈现（DSH 的 command/done），
+ * 再给 LLM 发一遍是重复劳动，而且实测有害 —— 收到播报的模型会自己去
+ * "帮忙"排查（tt5 实测 2026-10-25：模型收到"命令失败"后跑了 which / ls /
+ * npm list 去查插件，既烧额度又不可控）。
+ *
+ * 所以现在只有插件**显式调用** broadcastResult() 时才会真的发。
+ * 派活的命令（骨架 / 血肉 / 节奏 / 写作 / 去味 / 导入）本来就会发真实提示词，
+ * 那条 user 消息已经激活了对话视图，不需要额外播报。
+ *
+ * 措辞上有两条硬要求：
+ *   ① **永远声明"不是任务指令"**：模型收到结果通报就自己去干活 = 假成功。
+ *      （哪怕命令返回的是 kind='success'，正文也可能写着"未完成"——
+ *      插件的约定是"命令本身正常执行了"，成败在正文里。）
+ *   ② **不替插件宣布成功**：只说"命令已结束"，成败由正文说了算。
+ */
+export function buildBroadcastText(pluginName, result) {
+  const failed = Boolean(result && result.kind === 'error');
+  const raw = result && typeof result.text === 'string' ? result.text.trim() : '';
+  const head = `【${pluginName}】命令${failed ? '失败' : '已结束'}。`;
+  const tail = failed
+    ? '\n\n（命令结果播报：请如实转达失败原因并给出下一步建议；这是结果通报，不是任务指令，'
+      + '不要开始执行任何任务。）'
+    : '\n\n（命令结果播报：请如实转达上面的结果；这是结果通报，不是任务指令，'
+      + '不要开始执行任何任务。用户没有后续指令时不必展开。）';
+  let body = raw;
+  if (body.length > BROADCAST_MAX) {
+    body = body.slice(0, BROADCAST_MAX) + '\n…（已截断，完整内容见命令面板）';
+  }
+  return head + (body ? '\n\n' + body : '') + tail;
+}
+
+/**
+ * 显式把命令结果播报给 LLM（**默认不调用**）。
+ *
+ * 只有插件确实需要"让模型知道这次命令的结果"时才用 ——
+ * 例如插件跑完一个阶段后要把结论交给模型继续处理。
+ * 不需要就别调：左侧命令面板已经完整呈现了结果。
+ *
+ * 已派过活时不播报：那条真实提示词已经把对话视图激活了，
+ * 再补一条只会打断正在跑的阶段。
+ *
+ * @param {object} invocation - DSH 命令调用对象
+ * @param {string} pluginName - 插件名（写进播报，让模型知道是谁的结果）
+ * @param {{kind: string, text?: string}} result - 命令结果（notify 的返回值）
+ * @returns {Promise<{activated: boolean, reason: string, error?: string}>}
+ */
+export async function broadcastResult(invocation, pluginName, result) {
+  if (hasDispatched(invocation)) {
+    return { activated: false, reason: 'already_dispatched' };
+  }
+  const text = buildBroadcastText(pluginName, result);
+  const follow = await llmFollowup(invocation, text, { appendTempRule: false });
+  return follow.ok === true
+    ? { activated: true, reason: 'activated' }
+    : { activated: false, reason: 'dispatch_failed', error: follow.error };
+}
+
+// ---------------------------------------------------------------------------
+// spawnScript — spawn 子进程，stdout 只收集 JSON，stderr 单独收集并保留
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {Object} SpawnResult
+ * @property {boolean} ok
+ * @property {string} [output] - 完整 stdout
+ * @property {string} [error]  - 错误描述（stderr 或 exit code）
+ * @property {string} [stderr] - 原始 stderr（成功时也保留）
+ * @property {number} [code]   - exit code
+ */
+
+/**
+ * 终止子进程及其所在的进程组。
+ *
+ * spawnScript 以 detached:true 起子进程，proc.pid 即新进程组的组长，
+ * process.kill(-pid, sig) 会把整组一起收掉 —— 其中包含 playwright 拉起的
+ * chromium。此前只调 proc.kill() 杀直接子进程，chromium 会变成孤儿进程，
+ * 继续占 CPU/内存并往工作区目录写盘。
+ *
+ * Windows 的 process.kill 不支持负 pid，此处退化为只杀直接子进程
+ * （与改动前行为一致，不劣化）。
+ *
+ * 导出供调用方使用：被 detached 出去的孙进程不在调用方的进程组里，
+ * 调用方自己被 SIGTERM 时必须显式转发，否则孙进程会变成孤儿。
+ */
+export function killProcessTree(proc, signal = 'SIGTERM') {
+  if (proc.pid) {
+    try { process.kill(-proc.pid, signal); } catch (_) { /* 非 POSIX，或进程已退出 */ }
+  }
+  try { proc.kill(signal); } catch (_) {}
+}
+
+/**
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {Object} [opts]
+ * @param {number} [opts.timeout=30000] - 毫秒超时（手动实现，因为 spawn 的 timeout 选项无效）
+ * @param {string} [opts.cwd]
+ * @param {Object} [opts.env]
+ * @param {Function} [opts.onSpawn] - 子进程创建后的回调，参数为 ChildProcess。
+ *   用于让调用方自己接管信号转发（被 detached 出去的孙进程不在调用方进程组内）。
+ * @returns {Promise<SpawnResult>}
+ */
+export function spawnScript(cmd, args, { timeout = 30000, cwd, env, onSpawn } = {}) {
+  return new Promise((resolve) => {
+    let proc;
+    try {
+      // detached:true —— 子进程成为独立进程组的组长，超时时可整组清理。
+      proc = spawn(cmd, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'], detached: true });
+    } catch (spawnErr) {
+      resolve({ ok: false, output: '', error: spawnErr.message, stderr: '' });
+      return;
+    }
+
+    if (typeof onSpawn === 'function') {
+      try { onSpawn(proc); } catch (_) { /* 调用方的钩子异常不应影响主流程 */ }
+    }
+
+    const outParts = [], errParts = [];
+    proc.stdout.on('data', (d) => { outParts.push(d.toString()); });
+    proc.stderr.on('data', (d) => { errParts.push(d.toString()); });
+
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      killProcessTree(proc, 'SIGTERM');
+      // 5s 兜底 SIGKILL（防止 child process 拒收 SIGTERM）
+      const killTimer = setTimeout(() => {
+        killProcessTree(proc, 'SIGKILL');
+      }, 5000);
+      killTimer.unref();
+    }, timeout);
+    timer.unref();
+
+    proc.on('close', (code) => {
+      clearTimeout(timer);
+      const stdout = outParts.join('');
+      const stderr = errParts.join('');
+
+      // 优先尝试解析 stdout 为 JSON
+      try {
+        const parsed = JSON.parse(stdout);
+        // 判定优先级：
+        //   0) 超时 → 一律失败（最高优先级，见下）
+        //   1) explicit ok === true  → 成功
+        //   2) explicit ok === false → 失败
+        //   3) 没有 ok 字段 → 看 written > 0（fanqie/jinjiang/qimao receipt），
+        //      或看顶层 status === 'success'（bootstrap receipt 风格）
+        //
+        // 超时必须排在 parsed.ok 之前：子进程完全可能在挂死之前
+        // 已经往 stdout 写过一条 {"ok":true}（例如先写 receipt 再卡住），
+        // 此时若让 parsed.ok 胜出，超时会被判成"成功"——
+        // 调用方只判 ok 就会拿到假成功。
+        let okFlag;
+        if (timedOut) {
+          okFlag = false;
+        } else if (parsed.ok === true) {
+          okFlag = true;
+        } else if (parsed.ok === false) {
+          okFlag = false;
+        } else {
+          const hasWritten = Number.isInteger(parsed.written) && parsed.written > 0;
+          okFlag = hasWritten || parsed.status === 'success';
+        }
+        resolve({
+          ok: okFlag,
+          output: stdout,
+          // 超时信息优先于子进程自报的错误 —— 超时才是真正的失败原因，
+          // 子进程的错误信息只是它被 SIGTERM 打断时的表象。
+          error: timedOut
+            ? `timeout after ${timeout}ms`
+            : (parsed.error
+                ? (typeof parsed.error === 'object'
+                    ? (parsed.error.message || JSON.stringify(parsed.error))
+                    : String(parsed.error))
+                : undefined),
+          stderr,
+          code,
+        });
+        return;
+      } catch (_) {
+        // stdout 不是 JSON — fallback 到 stderr / exit code
+        resolve({
+          ok: false,
+          output: stdout,
+          error: stderr.trim() || (timedOut ? `timeout after ${timeout}ms` : `exit ${code}`),
+          stderr,
+          code,
+        });
+      }
+    });
+    proc.on('error', (err) => {
+      clearTimeout(timer);
+      resolve({ ok: false, output: '', error: err.message, stderr: errParts.join(''), code: -1 });
+    });
+  });
+}