@xiaobuyu/nodesign 0.0.1

package/server/engine/mcp/tools/helpers/perception-page.js

@@ -0,0 +1,215 @@
+/**
+ * server/engine/mcp/tools/helpers/perception-page.js
+ * 感知工具的**唯一**页面加载口（2026-08-18）
+ *
+ * ## 为什么要有这一层
+ *
+ * 在这之前四个感知工具各自 `page.goto('file://' + abs)`，而用户预览走的是
+ * `/api/projects/:pid/artifact-file/*`（http）。**两条通道不同源**，于是：
+ *
+ *   - `location.protocol` 守卫（导出 zip 用 file:// 打开时关掉客户端路由那种）
+ *     在自检时触发，agent 看到的是退化行为
+ *   - `fetch`/XHR 被 CORS 拒 —— 任何加载 JSON 的站点在自检里是死的
+ *   - **localStorage 的 origin 是字符串 "null"**，全部任务共用一个桶；而用户
+ *     预览下它们各自独立。mock-app 产线「写了刷新还在」那条硬定义正好踩在
+ *     这上面 —— agent 验的东西和用户看的东西不是一回事
+ *   - Service Worker / 动态 import 同理
+ *
+ * 一个 agent 为此花了 4 次截图 + 一次把 `location.protocol` 写进 DOM 再截图，
+ * 才反推出来自己被 file:// 打开了（问题库 iss_msxk2oci_0v0v）。
+ *
+ * ## 凭什么能走 http
+ *
+ * MCP 工具的 handler 跟 express server 跑在**同一个进程**里，而 token 是无状态
+ * HMAC：`mintToken(ownerId)` 当场铸一个、塞进 chromium 的 cookie jar 即可。
+ * 拿到的权限跟项目所有者在浏览器里一模一样——不是新开一道后门，是走用户那道门。
+ * （web/scripts/shot-live.mjs 早就是这么干的，这里只是把它收进产品代码。）
+ *
+ * ⚠️ 铸出来的 token 只进本机 chromium 的 cookie jar，不写日志、不进返回文本。
+ * ⚠️ 前提是**调用方跟 HTTP server 同进程**（共用 NODESIGN_AUTH_SECRET）。独立脚本
+ *    里直接调这个 helper 会铸出对不上号的 token，服务端回 401 —— 那是环境问题不是
+ *    产品 bug，跑验证脚本记得 `node --env-file=.env`。
+ */
+
+import path from 'node:path';
+import { getProject } from '../../../../projects/store.js';
+import { COOKIE_NAME, mintToken, authEnabled } from '../../../../auth/session.js';
+import { getUserById } from '../../../../auth/users-store.js';
+
+// ── 渲染层保真（2026-08-07 立，2026-08-18 从 screenshot.js 挪来收成一份）──
+// Chromium 的强制暗色（Auto Dark）会在 paint 层反转颜色，而页面自己的 JS
+// 一点都测不到 —— 2026-08-05 那次「位图深色 / computed style 浅色」事故就是它。
+// ⚠️ 这组参数以前只有 screenshot / screenshot-url 两条路带，query_elements /
+// get_computed_styles / list_pages 是裸奔的 —— 同一个 DOM 两条通道两种渲染，
+// 正是「判据本身要先验一遍」那类坑。现在收成一份，谁开 chromium 都带上。
+export const FIDELITY_LAUNCH_ARGS = [
+  '--disable-features=WebContentsForceDark',  // 自动暗色：paint 层反转，页面自己测不到
+  '--force-color-profile=srgb',               // 色彩配置固定 srgb，排除 ICC 差异
+];
+
+/** 服务端自己的监听口。跟 server/index.js 同一个默认值，改端口两处一起改。 */
+const PORT = Number(process.env.PORT || 4001);
+
+/** 127.0.0.1 而不是 localhost：避免 ::1/127.0.0.1 双栈解析下 cookie 域对不上 */
+export const PERCEPTION_ORIGIN = `http://127.0.0.1:${PORT}`;
+/**
+ * 站点检查的真实设备宽（08-21 收成一份：以前 screenshot / explain_style / profile_scroll
+ * 各抄一份 {desktop:1440,…}）。站点没有"比例"，版面是宽度算出来的，所以档位给
+ * 真实设备宽、直接当 viewport、不缩放。
+ */
+export const SITE_DEVICE_W = { desktop: 1440, tablet: 834, mobile: 390 };
+
+/**
+ * 开一个「保真」chromium。凡是要把页面变成给人或给模型看的像素的地方都走这里 ——
+ * 参数散在九个调用点上时，有三个是漏的（2026-08-18 逐处对账才发现，当天收敛完）。
+ *
+ * ⚠️ **有两处故意不走这里**，别顺手也"收敛"掉：
+ *   `screenshot-url.js` 和 `engine/browse/registry.js`。它们打的是**外部 URL**，
+ *   必须挂 `--proxy-server` 走出网闸（lib/browse-proxy.js）；而这个函数开的浏览器
+ *   专门打 `127.0.0.1:4001` 上我们自己的产物 —— 那正是出网闸要拦的地址。
+ *   两条通道的**安全前提相反**，共用一个 launch 只会让其中一条失守或不通。
+ */
+export async function launchPerceptionBrowser() {
+  const { chromium } = await import('playwright');
+  return chromium.launch({ headless: true, args: FIDELITY_LAUNCH_ARGS });
+}
+
+/**
+ * 工作区相对路径 → 用户预览用的同一个 URL。
+ * 逐段 encodeURIComponent —— 任务名和文件名大量是中文，整体编码会把 `/` 也吃掉。
+ */
+export function artifactFileUrl(projectId, relPath, { raw = true } = {}) {
+  const sub = String(relPath || '').split('/').filter(Boolean).map(encodeURIComponent).join('/');
+  // ⭐ `?nd=raw` —— 不走显示改写层，拿原始 HTML + 原图。
+  //
+  // artifact-file 平时是**显示通道**：给 html 注 srcset/sizes/loading=lazy、给图发
+  // 降尺寸的 webp/avif 派生图。对用户预览这些都对（省 90% 流量）。但 agent 的眼睛
+  // 走同一条路由之后，它看到的就不是**交付物**了 —— 发布出去的站点是原始 HTML
+  // （site-publish 拷原文，没有这层注入）。
+  //
+  // ⛔ 实测差别（2026-08-18 审查攻出来的）：一张 1800px 宽、没有 CSS 宽约束的图，
+  // 注入 `sizes="100vw"` 之后在 agent 眼里渲染成 1440px、`overflow:false`；
+  // 而访客那边是 1800px、`overflow:true` —— **显示改写层把横向溢出藏起来了**，
+  // 而「忘写 max-width:100%」正是最常见的那类真 bug。顺带图也不是原图
+  // （naturalWidth 1440 vs 1800），逐像素/锐度类判断跟着失真。
+  //
+  // ⚠️ 代价：感知页加载原图更慢更吃 CPU（1 vCPU 上是真代价）。取舍是**眼睛的
+  // 正确性优先于自检速度** —— 一个看错的自检比一个慢的自检坏得多。
+  // （http 同源那半边不受影响：fetch/localStorage/SW 照旧跟用户预览一致，实测过。）
+  return `${PERCEPTION_ORIGIN}/api/projects/${projectId}/artifact-file/${sub}${raw ? '?nd=raw' : ''}`;
+}
+
+/**
+ * 退化提示 → 一行可以直接拼进返回文本的话。
+ *
+ * `openArtifactPage` 的契约是「note 非空 = 没能走成 http，调用方必须把它写进
+ * 返回文本」。⛔ 实测只有 screenshot 一个调用方照做了，另外五个工具连 `.note`
+ * 两个字都没出现过（grep 计数 0）—— 也就是 07-29 那个「file:// 静默回退」的
+ * bug 被重新种了一遍：`profile_scroll` 的描述铁口直断"走 http 同源"，一旦回退，
+ * 它按 Resource Timing 报「images 0 files 0KB」，那正好是它主诊断的反面，
+ * 而唯一能解释这件事的 note 被丢掉了。
+ *
+ * 所以把措辞收成一份，调用点无脑拼。配套有个 lint 钉住"import 了就必须用"。
+ */
+export function degradedNote(opened) {
+  if (!opened?.note) return null;
+  return `⚠️ 这一页没能按用户预览的方式打开（${opened.note}）。`
+    + 'fetch/XHR/localStorage 的行为跟用户那边不一样，凡是依赖它们的结论都不作数。';
+}
+
+/**
+ * 打开一个产物页面，返回 { page, context, url, note }。
+ *
+ * - `note` 非空表示**没能走成 http**（退回了 file://），调用方应把它写进 caption：
+ *   悄悄退回去就是把这个 bug 重新种一遍。
+ * - HTTP 状态 >= 400 直接抛错，不截一张 JSON 错误页给 agent 当产物看。
+ *
+ * @param {import('playwright').Browser} browser
+ * @param {object} opts
+ * @param {string} opts.projectId
+ * @param {string} opts.workspaceRoot  项目工作区根（= artifact-file 的可服务根）
+ * @param {string} opts.absPath        要打开的文件绝对路径
+ * @param {object} [opts.viewport]
+ * @param {number} [opts.deviceScaleFactor]
+ * @param {number} [opts.timeout]
+ * @param {string} [opts.waitUntil]
+ */
+export async function openArtifactPage(browser, {
+  projectId, workspaceRoot, absPath,
+  viewport, deviceScaleFactor = 1, timeout = 15000, waitUntil = 'networkidle',
+}) {
+  const contextOpts = { colorScheme: 'light', deviceScaleFactor };
+  if (viewport) contextOpts.viewport = viewport;
+  // ⭐ `?nd=raw` 只挂在**主文档**的 URL 上，页面里 `<img src="assets/x.png">` 发出去的
+  // 请求不带任何 query —— 于是主文档拿到了原样 HTML，图片却照旧走派生图。实测：
+  // 一张 1.36MB 的 PNG 发出去是 **35.7KB 的 webp（2.6%）**。两个后果都真实：
+  //   ① 没有 CSS 宽约束的图按**固有尺寸**排版，派生图尺寸不同 → 版面跟访客不一样；
+  //   ② `profile_scroll` 的"图片总字节"少报了几十倍，而它的头号建议就是按体积开药。
+  // 每个请求都带一个头最省：query 要改写 HTML（那就不叫 raw 了）。
+  //
+  // ⚠️ 但**不能用 context 级 extraHTTPHeaders**（第一版就是，agent 上报逮到）：
+  // 那会把这个自定义头带给页面请求的**所有主机**，而任何自定义头都会把跨域字体
+  // 请求从「简单请求」升级成要 CORS 预检 —— fonts.gstatic.com 不认这个头，预检
+  // 挂掉，Google Fonts 整站全灭，感知截图里字体全部回退。头只对感知源有意义
+  //（assets.js 读它决定给不给原图），所以用 route 只加在同源请求上。
+  const context = await browser.newContext(contextOpts);
+  await context.route(`${PERCEPTION_ORIGIN}/**`, (route) => route.continue({
+    headers: { ...route.request().headers(), 'X-ND-Raw': '1' },
+  }));
+
+  let url = null;
+  let note = null;
+
+  const rel = projectId && workspaceRoot
+    ? path.relative(workspaceRoot, absPath)
+    : null;
+  const insideWorkspace = rel != null && rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+
+  if (insideWorkspace) {
+    url = artifactFileUrl(projectId, rel.split(path.sep).join('/'));
+    if (authEnabled()) {
+      // 项目所有者的身份 —— guardProject 只认 owner 或 admin
+      const ownerId = getProject(projectId)?.ownerId;
+      // ⚠️ 光有 ownerId 不够：`mintToken` 只把 id 烤进签名，而 `requestUser` 会
+      // **重新查库**并拒掉 disabled / 已删除的用户。于是账号一被停用，六个感知工具
+      // 全部报「artifact-file returned HTTP 401」—— 一句完全指不到根因的话
+      // （真因是账号状态，跟文件、路径、权限配置都无关）。这里提前认出来，
+      // 退到 file:// 并把真原因写进 note（note 会被所有调用方拼进返回文本，
+      // 有 lint 钉着）。
+      const owner = ownerId ? getUserById(ownerId) : null;
+      if (ownerId && owner && !owner.disabled) {
+        await context.addCookies([{
+          name: COOKIE_NAME, value: mintToken(ownerId), url: PERCEPTION_ORIGIN,
+        }]);
+      } else {
+        const why = !ownerId ? 'project owner unknown'
+          : (!owner ? `owner account ${ownerId} no longer exists`
+            : `owner account ${owner.username} is disabled — an admin has to re-enable it; `
+              + 'this is an account-state problem, not a file or path problem');
+        note = `${why} — loaded via file:// (fetch/XHR/localStorage behave differently from the user preview)`;
+        url = null;
+      }
+    }
+  } else {
+    // 产物落在工作区外（不该发生，但寻址层出岔子时别整个瞎掉）
+    note = 'file is outside the project workspace — loaded via file:// (fetch/XHR/localStorage behave differently from the user preview)';
+  }
+
+  const page = await context.newPage();
+  if (!url) {
+    return { page, context, url: `file://${absPath}`, note, viaHttp: false, goto: () => page.goto(`file://${absPath}`, { waitUntil, timeout }) };
+  }
+
+  return {
+    page, context, url, note, viaHttp: true,
+    goto: async () => {
+      const resp = await page.goto(url, { waitUntil, timeout });
+      // 401/403/404 会渲成一张 JSON 错误页 —— 截它等于给 agent 一张假产物
+      const status = resp?.status();
+      if (status && status >= 400) {
+        throw new Error(`artifact-file returned HTTP ${status} for ${decodeURIComponent(url.replace(PERCEPTION_ORIGIN, ''))}`);
+      }
+      return resp;
+    },
+  };
+}

package/server/engine/mcp/tools/helpers/reference-download.js

@@ -0,0 +1,103 @@
+/**
+ * server/engine/mcp/tools/helpers/reference-download.js
+ * 把搜到的参考图下载进 `assets/references/`（2026-08-18 从 web-search.js 拆出）
+ *
+ * 拆的直接原因是行数棘轮，但拆对了：这跟"搜索"是两件事 —— 一件是问 provider 要结果，
+ * 一件是把图落进工作区。`browser_capture` 也往同一个目录写，两边的落点约定
+ * （`assets/references/`、`.meta/<主干>.json` 出处 sidecar）应该看得见彼此。
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import crypto from 'node:crypto';
+
+// ── reference image download ──
+
+const DL_TIMEOUT_MS = 10_000;
+const DL_MAX_BYTES = 5 * 1024 * 1024; // 5MB（Anthropic image content block 单图上限）
+const DL_MIN_BYTES = 5 * 1024;        // 5KB（< 这个多半是 logo / 损坏）
+
+const MIME_TO_EXT = {
+  'image/jpeg': '.jpg',
+  'image/jpg': '.jpg',
+  'image/png': '.png',
+  'image/webp': '.webp',
+  'image/gif': '.gif',
+};
+
+function shortHash(s) {
+  return crypto.createHash('sha256').update(s).digest('hex').slice(0, 10);
+}
+
+/**
+ * 下载一张图到 <root>/assets/references/ref-<hash>-<role>.<ext>。
+ * 已存在 → 直接返回（按 hash 去重）。
+ *
+ * @returns {Promise<{ relPath: string, absPath: string, sizeBytes: number, mimeType: string } | null>}
+ *   失败/校验不通过 → null（caller 跳过这一张）
+ */
+async function downloadOneImage(url, refsDir) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), DL_TIMEOUT_MS);
+  try {
+    const hash = shortHash(url);
+    const res = await fetch(url, { signal: controller.signal, redirect: 'follow' });
+    if (!res.ok) return null;
+    const mime = (res.headers.get('content-type') || '').toLowerCase().split(';')[0].trim();
+    const ext = MIME_TO_EXT[mime];
+    if (!ext) return null;
+
+    const buf = Buffer.from(await res.arrayBuffer());
+    if (buf.length < DL_MIN_BYTES || buf.length > DL_MAX_BYTES) return null;
+
+    const fileName = `ref-${hash}${ext}`;
+    const absPath = path.join(refsDir, fileName);
+    // 去重：同 url → 同 hash → 同文件名 → 已存在就跳写
+    let exists = false;
+    try { await fs.access(absPath); exists = true; } catch { /* not exists */ }
+    if (!exists) await fs.writeFile(absPath, buf);
+
+    return {
+      relPath: path.posix.join('assets', 'references', fileName),
+      absPath,
+      sizeBytes: buf.length,
+      mimeType: mime,
+      base64: buf.toString('base64'), // 直接传给 CallToolResult image block
+    };
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * 并发下载 top-N 图，filter 掉失败/超大/过小。
+ *
+ * @returns {Promise<Array<{url, description, title, relPath, absPath, sizeBytes, mimeType}>>}
+ */
+export async function downloadReferenceImages(images, { workspaceRoot, sharedRoot, stopAfter = Infinity }) {
+  const baseRoot = sharedRoot || workspaceRoot;
+  if (!baseRoot) return [];
+  const refsDir = path.join(baseRoot, 'assets', 'references');
+  await fs.mkdir(refsDir, { recursive: true });
+
+  // ⚠️ **够了就停**（2026-08-18）。原来是把候选全并发下完再 slice，于是多下的那些
+  // 留在磁盘上、agent 不知道它们存在、却照样占空间和进导出包。候选多给是为了容错
+  // （有些 URL 会 404），不是为了多存。
+  // 代价：从全并发变成小批并发，慢一点；换来的是"盘上有什么 = 报了什么"。
+  const out = [];
+  const BATCH = 3;
+  for (let i = 0; i < images.length && out.length < stopAfter; i += BATCH) {
+    const settled = await Promise.allSettled(
+      images.slice(i, i + BATCH).map(async (img) => {
+        const dl = await downloadOneImage(img.url, refsDir);
+        return dl ? { ...img, ...dl } : null;
+      }),
+    );
+    for (const r of settled) {
+      if (r.status === 'fulfilled' && r.value && out.length < stopAfter) out.push(r.value);
+    }
+  }
+  return out;
+}

package/server/engine/mcp/tools/helpers/rembg-bridge.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""rembg-bridge — read source PNG/JPEG from stdin, write transparent RGBA PNG to stdout.
+
+Args:
+  --model NAME        rembg session model name. Default: birefnet-general-lite.
+                      Options: u2net / isnet-general-use / birefnet-general-lite /
+                      birefnet-general / silueta etc. (see rembg docs)
+  --alpha-matting     Enable rembg trimap alpha matting post-process. Drastically
+                      reduces edge halo / 伪影 at cost of ~1-2× inference time.
+
+调用方（Node 端 helpers/rembg.js）spawn 这个脚本，stdin 喂 NB2 生图字节，
+stdout 拿 rembg 抠完背景的 PNG。stderr 走 logging（urllib3 LibreSSL 警告等
+非致命噪声 silence 掉，真错让 caller 看到非零 exit code）。
+
+依赖：server/.venv-rembg/ 装了 rembg + onnxruntime + 模型缓存到 ~/.u2net/
+（首次 cold load 自动下载，birefnet-general-lite ~214MB / birefnet-general ~880MB）。
+
+跑法：
+  printf '<png-bytes>' | <server>/.venv-rembg/bin/python3 rembg-bridge.py \\
+      --model birefnet-general-lite --alpha-matting > out.png
+"""
+import argparse
+import os
+import sys
+import warnings
+
+# urllib3 v2 + LibreSSL（macOS 自带 Python 用 LibreSSL 不是 OpenSSL）只是警告，
+# 抠图不受影响。silence 防污染 stderr 让 caller 误判失败。
+warnings.filterwarnings('ignore')
+
+from rembg import remove, new_session
+
+
+def _resolve_providers():
+    """决定 onnxruntime providers，与 rembg-service.py 一致：
+    darwin 默认 CPU only（绕 CoreML+birefnet 卡死），其它平台 ort 自选；
+    env NODESIGN_REMBG_PROVIDERS 覆盖。"""
+    env = os.environ.get('NODESIGN_REMBG_PROVIDERS', '').strip()
+    if env:
+        return [p.strip() for p in env.split(',') if p.strip()]
+    if sys.platform == 'darwin':
+        return ['CPUExecutionProvider']
+    return None
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description='rembg bridge: stdin → stdout')
+    parser.add_argument(
+        '--model',
+        default='birefnet-general-lite',
+        help='rembg session model name (default: birefnet-general-lite)',
+    )
+    parser.add_argument(
+        '--alpha-matting',
+        action='store_true',
+        help='enable rembg trimap alpha matting (cleaner edges, ~1-2× slower)',
+    )
+    args = parser.parse_args()
+
+    try:
+        input_data = sys.stdin.buffer.read()
+        if not input_data:
+            print('rembg-bridge: empty stdin', file=sys.stderr)
+            return 2
+
+        session = new_session(args.model, providers=_resolve_providers())
+        output_data = remove(
+            input_data,
+            session=session,
+            alpha_matting=args.alpha_matting,
+        )
+        sys.stdout.buffer.write(output_data)
+        return 0
+    except Exception as e:
+        print(f'rembg-bridge error: {type(e).__name__}: {e}', file=sys.stderr)
+        return 1
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/server/engine/mcp/tools/helpers/rembg.js

@@ -0,0 +1,273 @@
+/**
+ * helpers/rembg.js — Node 侧抠图调用包装。两条路径：
+ *
+ *   1. **优先 Unix socket service**（warm，~5-15s/张）—— server 启动时
+ *      services/rembg-launcher.js 已 spawn rembg-service.py 常驻进程，
+ *      onnxruntime session 在内存。每次请求走 HTTP-over-Unix-socket。
+ *
+ *   2. **降级到 spawn-bridge**（cold，~30-180s/张）—— service down / 不可用时
+ *      fallback 到 per-call spawn .venv-rembg/bin/python3 跑 rembg-bridge.py。
+ *      首次部署 / dev 没装 service 时这条路径仍能跑通。
+ *
+ * Fail-soft：两条路径都失败时 return null，调用方降级（不抛）。
+ *
+ * Env override：
+ *   NODESIGN_REMBG_SOCKET   Unix socket 路径（默认 /tmp/nodesign-rembg.sock）
+ *   NODESIGN_REMBG_PYTHON   venv python 路径（默认 server/.venv-rembg/bin/python3）
+ *   NODESIGN_REMBG_HELPER   spawn-bridge 脚本路径
+ *   NODESIGN_REMBG_TIMEOUT  fallback 路径 subprocess 超时 ms
+ */
+
+import { spawn } from 'node:child_process';
+import http from 'node:http';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// helpers/ 在 server/engine/mcp/tools/helpers/，server root 上溯 4 层
+const SERVER_ROOT = path.resolve(__dirname, '../../../../');
+
+// venv 里 python 的位置按平台走（Windows 是 Scripts\python.exe，不是 bin/python3）；
+// 安装提示同源，launcher / capabilities / remove_background 三处都引这里，别各写一遍
+const IS_WIN = process.platform === 'win32';
+export const REMBG_VENV_PYTHON = IS_WIN
+  ? path.join(SERVER_ROOT, '.venv-rembg', 'Scripts', 'python.exe')
+  : path.join(SERVER_ROOT, '.venv-rembg', 'bin', 'python3');
+export const REMBG_SETUP_HINT = IS_WIN
+  ? 'cd server && python -m venv .venv-rembg && .venv-rembg\\Scripts\\python.exe -m pip install rembg onnxruntime'
+  : 'cd server && python3 -m venv .venv-rembg && .venv-rembg/bin/python3 -m pip install rembg onnxruntime';
+const DEFAULT_PYTHON = REMBG_VENV_PYTHON;
+const DEFAULT_HELPER = path.join(__dirname, 'rembg-bridge.py');
+const DEFAULT_SOCKET = '/tmp/nodesign-rembg.sock';
+// fallback spawn 的 timeout——首次冷启 + 模型 load 留余量
+const DEFAULT_FALLBACK_TIMEOUT_MS = 60_000;
+
+function resolvePython() { return process.env.NODESIGN_REMBG_PYTHON || DEFAULT_PYTHON; }
+function resolveHelper() { return process.env.NODESIGN_REMBG_HELPER || DEFAULT_HELPER; }
+function resolveSocket() { return process.env.NODESIGN_REMBG_SOCKET || DEFAULT_SOCKET; }
+
+// service health check 缓存（避免每次 request 都探一遍 /health）
+let serviceHealthCache = { ok: false, checkedAt: 0 };
+const HEALTH_CACHE_MS = 5_000;
+
+/**
+ * 探活 service：HTTP GET /health on Unix socket。带 5s cache 避免高频探测。
+ */
+async function isServiceHealthy() {
+  const now = Date.now();
+  if (now - serviceHealthCache.checkedAt < HEALTH_CACHE_MS) {
+    return serviceHealthCache.ok;
+  }
+  const socketPath = resolveSocket();
+  // 先 stat 文件存在再 connect，省一次 ECONNREFUSED 的 noise
+  try {
+    await fs.access(socketPath);
+  } catch {
+    serviceHealthCache = { ok: false, checkedAt: now };
+    return false;
+  }
+  const ok = await new Promise((resolve) => {
+    const req = http.request({
+      socketPath,
+      path: '/health',
+      method: 'GET',
+      timeout: 2000,
+    }, (res) => {
+      res.resume(); // drain
+      resolve(res.statusCode === 200);
+    });
+    req.on('error', () => resolve(false));
+    req.on('timeout', () => { req.destroy(); resolve(false); });
+    req.end();
+  });
+  serviceHealthCache = { ok, checkedAt: now };
+  return ok;
+}
+
+/**
+ * 通过 service Unix socket 调 /remove。
+ * @returns {Promise<Buffer | null>}
+ */
+async function removeViaService(inputBuf, opts) {
+  const socketPath = resolveSocket();
+  const model = opts.model || 'birefnet-general-lite';
+  const alphaMatting = opts.alphaMatting !== false;
+  const timeoutMs = opts.timeoutMs || 180_000;
+
+  return new Promise((resolve) => {
+    const req = http.request({
+      socketPath,
+      path: '/remove',
+      method: 'POST',
+      timeout: timeoutMs,
+      headers: {
+        'content-type': 'application/octet-stream',
+        'content-length': inputBuf.length,
+        'x-model': model,
+        'x-alpha-matting': alphaMatting ? '1' : '0',
+      },
+    }, (res) => {
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => {
+        if (res.statusCode === 200) {
+          resolve(Buffer.concat(chunks));
+        } else {
+          const text = Buffer.concat(chunks).toString().slice(0, 300);
+          console.warn(`[rembg] service status ${res.statusCode}: ${text}`);
+          resolve(null);
+        }
+      });
+      res.on('error', () => resolve(null));
+    });
+    req.on('error', (err) => {
+      console.warn(`[rembg] service request error: ${err.message}`);
+      // 任何 socket 错都让 cache 立刻失效，下次会重新探活
+      serviceHealthCache = { ok: false, checkedAt: 0 };
+      resolve(null);
+    });
+    req.on('timeout', () => {
+      console.warn(`[rembg] service timeout after ${timeoutMs}ms`);
+      req.destroy();
+      resolve(null);
+    });
+    req.write(inputBuf);
+    req.end();
+  });
+}
+
+/**
+ * Fallback：spawn rembg-bridge.py per-call（cold path）。
+ * @returns {Promise<Buffer | null>}
+ */
+async function removeViaSpawn(inputBuf, opts) {
+  const py = resolvePython();
+  const helper = resolveHelper();
+  const model = opts.model || 'birefnet-general-lite';
+  const alphaMatting = opts.alphaMatting !== false;
+  const timeoutMs = opts.timeoutMs
+    || Number(process.env.NODESIGN_REMBG_TIMEOUT)
+    || DEFAULT_FALLBACK_TIMEOUT_MS;
+
+  const args = [helper, '--model', model];
+  if (alphaMatting) args.push('--alpha-matting');
+
+  return new Promise((resolve) => {
+    let proc;
+    try {
+      proc = spawn(py, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+    } catch (err) {
+      console.warn('[rembg] spawn failed:', err.message);
+      resolve(null);
+      return;
+    }
+
+    const stdoutChunks = [];
+    let stderrText = '';
+    let settled = false;
+
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      try { proc.kill(); } catch { /* already dead */ }
+      resolve(result);
+    };
+
+    const timer = setTimeout(() => {
+      console.warn(`[rembg] spawn timeout after ${timeoutMs}ms`);
+      finish(null);
+    }, timeoutMs);
+
+    proc.stdout.on('data', (chunk) => stdoutChunks.push(chunk));
+    proc.stderr.on('data', (chunk) => { stderrText += chunk.toString(); });
+
+    proc.on('error', (err) => {
+      clearTimeout(timer);
+      console.warn('[rembg] spawn process error:', err.message);
+      finish(null);
+    });
+
+    proc.on('close', (code) => {
+      clearTimeout(timer);
+      if (code !== 0) {
+        console.warn(
+          `[rembg] spawn exit ${code} (model=${model}, alphaMatting=${alphaMatting}): ${stderrText.slice(0, 300).trim() || '(no stderr)'}`,
+        );
+        finish(null);
+        return;
+      }
+      const out = Buffer.concat(stdoutChunks);
+      if (out.length === 0) {
+        console.warn(`[rembg] spawn empty stdout despite exit 0 (model=${model})`);
+        finish(null);
+        return;
+      }
+      finish(out);
+    });
+
+    try {
+      proc.stdin.write(inputBuf);
+      proc.stdin.end();
+    } catch (err) {
+      console.warn('[rembg] spawn stdin write failed:', err.message);
+      clearTimeout(timer);
+      finish(null);
+    }
+  });
+}
+
+/**
+ * 检查 rembg 整体可用——service 在线 OR fallback (venv + bridge) 文件齐。
+ * 不实际推理，只探活 + stat 文件。
+ *
+ * @returns {Promise<{ available: boolean, mode?: 'service'|'spawn', reason?: string }>}
+ */
+export async function isAvailable() {
+  if (await isServiceHealthy()) {
+    return { available: true, mode: 'service' };
+  }
+  const py = resolvePython();
+  const helper = resolveHelper();
+  try {
+    await fs.access(py);
+  } catch {
+    return { available: false, reason: `service down + python not found: ${py}` };
+  }
+  try {
+    await fs.access(helper);
+  } catch {
+    return { available: false, reason: `service down + bridge script not found: ${helper}` };
+  }
+  return { available: true, mode: 'spawn' };
+}
+
+/**
+ * 抠掉背景 → 返 transparent RGBA PNG Buffer。
+ *
+ * 路径选择：先试 service（warm，~5-15s）→ 失败降级 spawn（cold，30-180s）。
+ *
+ * @param {Buffer} inputBuf
+ * @param {object} [opts]
+ * @param {string} [opts.model='birefnet-general-lite']
+ * @param {boolean} [opts.alphaMatting=true]
+ * @param {number} [opts.timeoutMs] - service 路径默认 180s，spawn 路径默认 60s
+ * @returns {Promise<Buffer | null>}
+ */
+export async function removeBackground(inputBuf, opts = {}) {
+  if (!Buffer.isBuffer(inputBuf) || inputBuf.length === 0) {
+    console.warn('[rembg] empty input buffer');
+    return null;
+  }
+
+  // 路径 1：service warm
+  if (await isServiceHealthy()) {
+    const out = await removeViaService(inputBuf, opts);
+    if (out) return out;
+    console.warn('[rembg] service path failed, falling back to spawn');
+    // service request 失败 → 降级到 spawn 不要直接返 null
+  }
+
+  // 路径 2：spawn cold fallback
+  return removeViaSpawn(inputBuf, opts);
+}