dsh-drawai 0.2.4 → 0.2.5

package/lib/index.js

@@ -19,7 +19,13 @@ import { readdir } from 'node:fs/promises'
 import { isAbsolute, resolve as resolvePath, join as joinPath } from 'node:path'
 import { applyDocToMxfile, buildMxfile, contentHash, parseMxfile } from './mxfile.js'
 import { decodeRaster } from './raster.js'
-import { TRACE_DEFAULTS, traceRasterToSvg } from './trace-image.js'
+import {
+  TRACE_DEFAULTS,
+  TRACE_PRESET_NAMES,
+  resolveTraceOptions,
+  summarizeTraceForAi,
+  traceRasterToSvg,
+} from './trace-image.js'
 import {
   ARROW_KINDS,
   DASH_KINDS,
@@ -408,8 +414,17 @@ function fontColorFieldOf(style) {
 const DEFAULT_SVG_W = 80
 const DEFAULT_SVG_H = 80
 
-/** 一段内嵌 SVG 标记的长度上限。超了直接拒：一个单元格几十万字符会把文件和上下文一起撑爆。 */
-const SVG_MARKUP_LIMIT = 60000
+/**
+ * 一段内嵌 SVG 标记的长度上限。超了直接拒：一个单元格几十万字符会把文件和上下文一起撑爆。
+ *
+ * 为什么是 250000：**这是整图矢量化精细度的直接瓶颈**。实测一张 1024×1536 的立绘，
+ * grid 800 的原始产出就要 249630 字符 —— 卡在 60000 时管线只能压掉 5.4 倍（eps 抬到 3.2、
+ * 小环大量丢弃，环保留从 10235 掉到 2049），于是"脸和细节糊"就成了必然。
+ * 放到 250000：同一张图 grid 1000 只压 2 次、环保留 5455（翻 2.7 倍）。
+ * 再往上（不压缩约 327000 字符）文件会到 440KB/节点、读回时上下文开销约 8~9 万 token，
+ * 收益递减，所以停在 250000。要更细请用 cropX/cropY/cropW/cropH 做局部（那不受这个上限的边际影响）。
+ */
+const SVG_MARKUP_LIMIT = 250000
 /** traceImage 能读的图片字节上限（够任何截图，又不至于让一次调用把宿主内存吃干）。 */
 const TRACE_IMAGE_MAX_BYTES = 32 * 1024 * 1024
 /** diagram_read 里回显 svg 的长度上限（超了截断并注明总长）。 */
@@ -625,6 +640,54 @@ function styleNote(style) {
   return bits.length === 0 ? '' : ' [' + bits.join(', ') + ']'
 }
 
+/**
+ * 解析 traceImage 的裁剪矩形（cropX / cropY / cropW / cropH，都相对原图像素坐标）。
+ *
+ * 为什么要裁剪：矢量化的工作分辨率上限由 grid（默认 499px 宽）决定 —— 整张图画进去时，
+ * 一张 1024 宽的立绘里"脸"只有约 38px 宽、眼睛 3~4px，量化后五官必然消失。
+ * 裁出局部再描，同一块区域就占满工作图宽度，脸能有 190px —— 这是唯一能真正改善
+ * "面部特征缺失"的手段（调 colors / protectLuma 都无效：已经实测扫过参数）。
+ *
+ * 只写 cropW/cropH 时默认从左上角裁；一个字段都不给 = 整图（返回 null）。
+ * 裁剪后的 SVG viewBox 会平移回原图像素系，所以节点位置仍与原图对齐。
+ */
+function traceCropRect(op, where) {
+  const given = ['cropX', 'cropY', 'cropW', 'cropH'].filter((key) => has(op, key))
+  if (given.length === 0) return null
+  const box = {
+    x: Math.round(numberOr(op.cropX, 0)),
+    y: Math.round(numberOr(op.cropY, 0)),
+    w: Math.round(numberOr(op.cropW, 0)),
+    h: Math.round(numberOr(op.cropH, 0)),
+  }
+  if (box.w <= 0 || box.h <= 0) {
+    throw new Error(
+      where + ': 裁剪区域要给出正数 cropW / cropH（当前 ' + box.w + '×' + box.h +
+        '）；cropX / cropY 缺省为 0（左上角）。只给 cropX/cropY 不是裁剪，给全 cropX/cropY/cropW/cropH。',
+    )
+  }
+  if (box.x < 0 || box.y < 0) {
+    throw new Error(where + ': cropX / cropY 不能是负数（当前 ' + box.x + ',' + box.y + '）')
+  }
+  return box
+}
+
+/** 裁出 raster 的 [x, x+w) × [y, y+h) 一块（RGBA8，逐行拷）。越界会报错，不静默补白。 */
+function cropRaster(raster, box, where) {
+  if (box.x + box.w > raster.width || box.y + box.h > raster.height) {
+    throw new Error(
+      where + ': 裁剪区域超出图片范围（图片 ' + raster.width + '×' + raster.height +
+        '，要裁 x=' + box.x + ' y=' + box.y + ' ' + box.w + '×' + box.h + '）',
+    )
+  }
+  const out = new Uint8Array(box.w * box.h * 4)
+  for (let row = 0; row < box.h; row += 1) {
+    const from = ((box.y + row) * raster.width + box.x) * 4
+    out.set(raster.data.subarray(from, from + box.w * 4), row * box.w * 4)
+  }
+  return { width: box.w, height: box.h, data: out }
+}
+
 /**
  * 施加 ops。语义校验在这里：任何指向不存在节点的边、任何未知 id，都直接抛错并列出已知节点，
  * 于是失败发生在写盘之前 —— 不会画出半张烂图。
@@ -762,6 +825,7 @@ async function applyOps(doc, ops, out, opctx) {
       //
       // 这一步要读像素（I/O），所以整条 applyOps 是 async 的 —— 别把它当成同步 op 来加。
       const where = 'ops[' + i + '] traceImage'
+      const traceCrop = traceCropRect(op, where)
       if (opctx === undefined || opctx === null) throw new Error(where + ': 这个上下文不支持读图片（内部错误）')
       const rawImage = typeof op.image === 'string' && op.image.length > 0 ? op.image : undefined
       if (rawImage === undefined) {
@@ -774,26 +838,65 @@ async function applyOps(doc, ops, out, opctx) {
       } catch (error) {
         throw new Error(where + ': ' + messageOf(error))
       }
-      const traced = traceRasterToSvg(raster, {
-        colors: numberOr(op.colors, TRACE_DEFAULTS.colors),
-        grid: numberOr(op.grid, TRACE_DEFAULTS.grid),
-        scale: numberOr(op.scale, TRACE_DEFAULTS.scale),
-        epsilon: numberOr(op.epsilon, TRACE_DEFAULTS.epsilon),
-        precision: numberOr(op.precision, TRACE_DEFAULTS.precision),
-        minArea: numberOr(op.minArea, TRACE_DEFAULTS.minArea),
-        bgBright: numberOr(op.bgBright, TRACE_DEFAULTS.bgBright),
-        bgTol: numberOr(op.bgTol, TRACE_DEFAULTS.bgTol),
-        seeds: numberOr(op.seeds, TRACE_DEFAULTS.seeds),
-        maxBytes: Math.min(numberOr(op.maxBytes, TRACE_DEFAULTS.maxBytes), SVG_MARKUP_LIMIT - 2000),
-      })
+      // 裁剪：只把这一块交给矢量化，于是这块区域能占满整个工作分辨率（见 traceCropRect 的说明）。
+      let tracedFrom = raster
+      if (traceCrop !== null) {
+        try {
+          tracedFrom = cropRaster(raster, traceCrop, where)
+        } catch (error) {
+          throw new Error(where + ': ' + messageOf(error))
+        }
+      }
+      // 显式字段覆盖预设：没写的键用 undefined，让 resolveTraceOptions / 默认值接手
+      // 没给 maxBytes 时按上限走：细则由这个预算决定（预算越小，管线越要抬 epsilon、丢小环）
+      const rawTraceBudget = has(op, 'maxBytes')
+        ? numberOr(op.maxBytes, TRACE_DEFAULTS.maxBytes)
+        : SVG_MARKUP_LIMIT - 2000
+      const rawTrace = {
+        preset: typeof op.preset === 'string' ? op.preset : TRACE_DEFAULTS.preset,
+        colors: has(op, 'colors') ? op.colors : undefined,
+        colorsDark: has(op, 'colorsDark') ? op.colorsDark : undefined,
+        colorsFill: has(op, 'colorsFill') ? op.colorsFill : undefined,
+        grid: has(op, 'grid') ? op.grid : undefined,
+        gridH: has(op, 'gridH') ? op.gridH : undefined,
+        scale: has(op, 'scale') ? op.scale : undefined,
+        epsilon: has(op, 'epsilon') ? op.epsilon : undefined,
+        precision: has(op, 'precision') ? op.precision : undefined,
+        minArea: has(op, 'minArea') ? op.minArea : undefined,
+        minRegionArea: has(op, 'minRegionArea') ? op.minRegionArea : undefined,
+        protectLuma: has(op, 'protectLuma') ? op.protectLuma : undefined,
+        majorityContrast: has(op, 'majorityContrast') ? op.majorityContrast : undefined,
+        bgBright: has(op, 'bgBright') ? op.bgBright : undefined,
+        bgTol: has(op, 'bgTol') ? op.bgTol : undefined,
+        bgColor: has(op, 'bgColor') ? op.bgColor : undefined,
+        seeds: has(op, 'seeds') ? op.seeds : undefined,
+        maxBytes: Math.min(rawTraceBudget, SVG_MARKUP_LIMIT - 2000),
+      }
+      // 清掉 undefined，避免 Object.assign 把预设盖成 undefined
+      for (const key of Object.keys(rawTrace)) {
+        if (rawTrace[key] === undefined) delete rawTrace[key]
+      }
+      let resolved
+      try {
+        resolved = resolveTraceOptions(rawTrace)
+      } catch (error) {
+        throw new Error(where + ': ' + messageOf(error))
+      }
+      const traced = traceRasterToSvg(tracedFrom, resolved.options)
       const metrics = traced.metrics
       if (traced.svg.length > SVG_MARKUP_LIMIT) {
         throw new Error(
           where + ': 描出来的 SVG 太长（' + traced.svg.length + ' 字符，上限 ' + SVG_MARKUP_LIMIT +
-            '）。调小 grid（当前 ' + metrics.work.width + '）、调大 epsilon（当前 ' + op.epsilon + '）、或减少 colors。',
+            '）。调小 grid（当前 ' + metrics.work.width + '）、调大 epsilon、减少 colors，或 preset:"simple"。' +
+            (metrics.tuneHint ? ' 建议：' + metrics.tuneHint : ''),
         )
       }
-      // 尺寸：默认 1:1（画布坐标 = 原图像素坐标），w/h 显式给了就用给的
+      // 尺寸：默认 1:1（画布坐标 = 原图像素坐标），w/h 显式给了就用给的。
+      //
+      // 裁剪块的 SVG 里路径坐标是**裁剪局部**的（viewBox = 0 0 cropW cropH）—— 别去平移 viewBox：
+      // 路径不会跟着走，内容会整体跑出可视区（实测渲染出空白）。要让它落在原图对应的位置上，
+      // 靠的是节点框的**比例**：节点 w/h ≈ 原图尺寸 × (裁剪块尺寸 / 该块缩放)，
+      // 配合 imageAspect=0 拉伸铺满，局部坐标系就正好铺到原图那一块。
       const w = numberOr(op.w, raster.width)
       const h = numberOr(op.h, raster.height)
       const synthetic = {
@@ -801,7 +904,7 @@ async function applyOps(doc, ops, out, opctx) {
         svg: traced.svg,
         w: w,
         h: h,
-        keys: { imageAspect: 0 }, // 拉伸铺满：viewBox 就是原图像素系，节点框按它 1:1 画
+        keys: { imageAspect: 0 }, // 拉伸铺满：局部 viewBox 按节点框等比铺开
       }
       if (typeof op.id === 'string') synthetic.id = op.id
       if (typeof op.as === 'string') synthetic.as = op.as
@@ -809,15 +912,33 @@ async function applyOps(doc, ops, out, opctx) {
       if (typeof op.label === 'string') synthetic.label = op.label
       if (has(op, 'x')) synthetic.x = op.x
       if (has(op, 'y')) synthetic.y = op.y
+      // 裁剪块没给坐标时，落在原图里它该在的位置（否则会堆到原点压住整图）
+      if (traceCrop !== null && has(op, 'x') === false) synthetic.x = traceCrop.x
+      if (traceCrop !== null && has(op, 'y') === false) synthetic.y = traceCrop.y
       // 就地插一条 addNode 紧随其后（读像素是 async 的，所以这条 op 不能在解析参数时先展开）。
       // 注意：这里改的必须是**我们自己那份** ops —— 调用方（execute）已经 slice 过，
       // 因为宿主给的 arguments 是深冻结的，直接 splice 会抛 "object is not extensible"。
       ops.splice(i + 1, 0, synthetic)
+      // 节点 id：显式 id / as 别名会在下一条 addNode 里落地；这里先记 as 或 id 方便回执
+      const nodeRef = typeof op.id === 'string' ? op.id : typeof op.as === 'string' ? op.as : undefined
+      if (traceCrop !== null) metrics.crop = { x: traceCrop.x, y: traceCrop.y, w: traceCrop.w, h: traceCrop.h }
+      if (out !== undefined && out !== null) {
+        if (!Array.isArray(out.trace)) out.trace = []
+        out.trace.push(summarizeTraceForAi(metrics, { image: rawImage, nodeId: nodeRef }))
+      }
       notes.push(
-        '🖼 ' + rawImage + ' → 逐像素矢量化：' + metrics.palette.length + ' 色 / ' + metrics.paths + ' 条 path / ' +
+        '🖼 ' + rawImage +
+          (traceCrop === null ? '' : ' 裁剪 ' + traceCrop.w + '×' + traceCrop.h + '@' + traceCrop.x + ',' + traceCrop.y) +
+          ' → 逐像素矢量化 preset=' + metrics.preset + '：' +
+          metrics.palette.length + ' 色 / ' + metrics.paths + ' 条 path / ' +
           metrics.loopsKept + ' 个轮廓环 / ' + metrics.svgChars + ' 字符' +
-          '（工作图 ' + metrics.work.width + '×' + metrics.work.height + '，像素覆盖' +
-          (metrics.exactPixelCoverage === true ? '精确' : '不精确 ' + metrics.drawnPixels + '/' + metrics.totalPixels) + '）',
+          '（工作图 ' + metrics.work.width + '×' + metrics.work.height +
+          ', scale ' + metrics.scaleApplied +
+          (metrics.sizeNotes ? '; ' + metrics.sizeNotes : '') +
+          '，像素覆盖' +
+          (metrics.exactPixelCoverage === true ? '精确' : '不精确 ' + metrics.drawnPixels + '/' + metrics.totalPixels) +
+          '）' +
+          (metrics.tuneHint ? '\n   调参：' + metrics.tuneHint : ''),
       )
       continue
     }
@@ -1848,7 +1969,7 @@ diagram_read —— 返回里的 path 就是它（这两条是一致的，同一
     {op:"setLayer", id|ids, layer}
     {op:"setLayerProps", layer, name?, visible?, locked?}
     {op:"export", format?:"svg"|"png", name?}
-    {op:"traceImage", image, w?, h?, x?, y?, colors?, grid?, scale?, epsilon?, minArea?, as?, layer?}
+    {op:"traceImage", image, preset?, w?, h?, x?, y?, colors?, colorsDark?, colorsFill?, grid?, gridH?, scale?, epsilon?, minArea?, minRegionArea?, protectLuma?, majorityContrast?, bgColor?, cropX?, cropY?, cropW?, cropH?, as?, layer?}
     {op:"move", id|ids, dx?, dy?, x?, y?}
     {op:"remove", id|ids}
     {op:"highlight", ids:["n1","n2"]}
@@ -1874,17 +1995,25 @@ diagram_read —— 返回里的 path 就是它（这两条是一致的，同一
   pending → done（带文件路径）/ downloaded / failed。看到 pending 说明画布还没刷新 ——
   别反复请求，等下一次 read 再看（或提醒用户打开那张画布）。
 - **把一张位图"描"成矢量图用 traceImage**：{op:"traceImage", image:"ref.png", x:40, y:40}。
-  它**真的读那张图的像素**（宿主里跑的管线：四边泛洪去背景 → k-means 定调色板 →
-  3× 超采样归类 + 众数滤波 → 按颜色分连通域、沿像素格边取闭合轮廓 → RDP 简化 →
-  每色一条 nonzero path，按面积降序铺），建成一个 svg 内容节点。
+  它**真的读那张图的像素**，建成一个 svg 内容节点。
   **不要用"手写一段近似的 svg"冒充复刻** —— 形状词汇表表达不了的照片/插画就直接用这个 op。
-  · 默认 **w/h = 原图像素尺寸**、viewBox = 原图像素坐标系，所以画布坐标就是图片坐标（1:1 铺满）。
-  · 要更简洁：colors 调小（默认 12）、scale:2 或 3（先降采样）、grid 调小（工作宽度）。
-    要更保真：epsilon 调小（默认 2px）、minArea 调小（默认 10px²）。
-  · 输出会告诉你要点：色数 / 路径数 / 轮廓环数 / SVG 字符数 / **像素覆盖是否精确**
-    （精确 = 每色轮廓面积之和等于图像总像素，没有像素丢失或重复）。
-  · 单次上限：SVG 标记 60000 字符（超了会自己收紧 epsilon 与碎块阈值，仍超就报错让你调参）。
-  · 输入支持 PNG（自带解码器，零依赖）与 JPEG/GIF/WebP（需要宿主装了 sharp）。
+  · 默认 **w/h = 原图像素尺寸**、viewBox = 原图像素坐标系（1:1 铺满）。
+  · **先选 preset，再按需覆盖单字段**（合并：默认 ← preset ← 显式字段）：
+    - preset:"lineart" 插画/线稿（多暗色配额、严保细线）
+    - preset:"photo" 照片/渐变
+    - preset:"simple" 图标/简单图（少色+降采样，省字符）
+    - 不写 = "default"
+  · 调参闭环：看返回值里的 **trace[]**（结构化指标 + hint），不满意就 **remove 旧节点再 traceImage**（改 preset/字段）。
+    常见：字符紧 → scale:2 / 加大 epsilon / preset:"simple"；线糊断 → preset:"lineart" 或提高 protectLuma/colorsDark。
+  · 单次上限：SVG 标记 250000 字符（整图的精细度主要由它决定：预算紧时管线会抬 epsilon、丢小环，
+    把细节压掉——想要更细也可以给 maxBytes 顶到上限，或干脆用下面的裁剪只描局部）；
+    输入 PNG（零依赖）与 JPEG/GIF/WebP（需 sharp）。
+  · **五官/小物件糊成一团时，别只调参 —— 用 cropX/cropY/cropW/cropH 裁出那一块单独描**：
+    工作分辨率上限是 grid（默认 499px 宽），整张立绘塞进去时"脸"只占三四十像素，眼睛只有 3~4px，
+    量化后五官必然消失（实测把 colors 拉满 24、protectLuma 提到 235 也救不回来）。
+    裁出头部再描，同一块就占满工作图宽度 —— 脸能有一两百像素，五官才留得住。
+    裁剪块的坐标在**裁剪局部系**里，所以要按比例给它 w/h（= 整张图的 w/h × 裁剪块宽高 / 整块原尺寸），
+    x/y 不写时落在原图对应位置，可与整图那块叠着放（顺序在后 = 画在上面）。
 
 - **改一组用 ids**：{op:"setStyle", ids:["n1","n2","n5"], style:"green"} —— setStyle / setLabel /
   move / remove 都收 ids，不要为了"把这几个改成绿色"发 12 个 op。批量 move 只收 dx/dy
@@ -1945,7 +2074,7 @@ diagram_read —— 返回里的 path 就是它（这两条是一致的，同一
       （那就把 w/h 设成图形的比例，否则四周会留白）。
     · svg 节点**可以没有 label**（画图不带字）；要图下面带文字就照常给 label，它画在图上。
     · 颜色写在 SVG 自己身上（fill/stroke）—— 配色参数对它是无效的（图片不受 fillColor/strokeColor 影响）。
-    · 内容上限 60000 字符；**别放位图/base64**（那是图片不是图形，本画布画不出来）。
+    · 内容上限 250000 字符；**别放位图/base64**（那是图片不是图形，本画布画不出来）。
     · 改内容只能整段替换（没有"改某一根线"的 op）：先 read 拿回当前 svg，改完整段写回。
 - style：调色板名 plain|blue|green|orange|yellow|red|purple|grey，或直接给一段 style 串
 - dash：solid|dashed|dotted；arrow：end（单向）|both（双向）|none（无）|start（反向）
@@ -2768,7 +2897,7 @@ export function apply(ctx) {
       '{op:"setEdge", id, from?, to?, fromPoint?, toPoint?} / {op:"order", id|ids, to:"front"|"back"|"up"|"down"} / ' +
       '{op:"duplicate", id|ids, dx?, dy?, withEdges?, layer?, as?} / {op:"addLayer", name?, as?} / {op:"setLayer", id|ids, layer} / {op:"setLayerProps", layer, name?, visible?, locked?} / ' +
       '{op:"export", format?:"svg"|"png", name?} / ' +
-      '{op:"traceImage", image, w?, h?, x?, y?, colors?, grid?, scale?, epsilon?, minArea?, as?, layer?} / ' +
+      '{op:"traceImage", image, preset?, w?, h?, x?, y?, colors?, colorsDark?, colorsFill?, grid?, gridH?, scale?, epsilon?, minArea?, minRegionArea?, protectLuma?, majorityContrast?, bgColor?, as?, layer?} / ' +
       '{op:"move", id|ids, dx?, dy?, x?, y?} / {op:"remove", id|ids} / {op:"highlight", ids:[...]}；节点 id 省略时自动分配。' +
       '**改接一条边**用 setEdge（换 from/to 或某一端改成自由点）—— id、标签、标签位置、折点、端点约束全都留着；' +
       '不要 remove + addEdge 重画（那会把这些丢掉）。' +
@@ -2779,12 +2908,14 @@ export function apply(ctx) {
       '**图层**用 addLayer/setLayer/setLayerProps（加层、把单元移到别的层、改名/显示/隐藏/锁定；隐藏≠删除）。' +
       '**导出**用 export：format:"svg" 会让画布渲染一张 SVG 落在 .drawio 旁边、format:"png" 是浏览器下载；' +
       '这一步由画布执行，返回值里的 export.status 是 pending/done/downloaded/failed（pending = 画布还没刷新）。' +
-      '**照着一张位图描矢量图**用 traceImage：{op:"traceImage", image:"ref.png", x, y} 会真的去读那张图的像素' +
-      '（泛洪去背景 → k-means 定调色板 → 3× 超采样归类 → 按颜色取像素级闭合轮廓 → 每色一条 nonzero path），' +
-      '建成一个 svg 内容节点，**不是让模型凭印象重画**。默认 w/h = 原图像素尺寸、viewBox = 原图像素坐标系（1:1）。' +
-      '可调：colors（默认 12，少=更简洁）、grid（工作宽度，调小=更粗更快）、scale（先降采样几倍）、' +
-      'epsilon（轮廓简化容差 px，默认 2，调大=更省字符）、minArea（小于这个面积的碎块并进最相似邻色）。' +
-      '返回的 summary 里带"色数/路径数/轮廓环/像素覆盖是否精确"，据此判断质量。' +
+      '**照着一张位图描矢量图**用 traceImage：{op:"traceImage", image:"ref.png", x, y} 会真的读像素建成 svg 节点，' +
+      '**不是凭印象重画**。默认 w/h = 原图像素尺寸（1:1）。' +
+      '**调参**：先选 preset（' + TRACE_PRESET_NAMES.join('|') + '；lineart=插画线稿、photo=照片、simple=省字符、default=默认），' +
+      '再按需覆盖 colors/colorsDark/scale/epsilon/grid/gridH/minArea/minRegionArea/protectLuma/majorityContrast/bgColor 等。' +
+      '合并顺序：默认 ← preset ← 显式字段。' +
+      '返回值里的 **trace[]** 是结构化指标（svgChars/protectPixels/options/hint 等）；' +
+      '质量不够就根据 hint remove 旧节点再 trace（改 preset 或字段）。' +
+      '字符紧→scale:2/加大epsilon/preset:simple；线糊断→preset:lineart 或提高 protectLuma/colorsDark。' +
       '**一次改一组**就写 ids:[...]（setStyle/setLabel/move/remove 都收，move 的批量只收 dx/dy 相对位移）—— 用户说"把这几个换成绿色"时不要逐个发 op。' +
       '**引用刚建的那个**用 as:"名字"：{op:"addNode", label:"开始", as:"start"} 之后同一个 ops 数组里 from/to/id 可以直接写 "start"，不必猜自动分配的 n7。' +
       '**画图形（图标/logo/示意图）用 svg**：addNode {shape:"svg", svg:"<svg viewBox=…>…</svg>", w, h} 让节点的内容就是那段 SVG 标记' +
@@ -2876,6 +3007,64 @@ export function apply(ctx) {
               error: { type: 'string' },
             },
           },
+          // 本次调用里每次 traceImage 一条：给模型读指标再调参（additionalProperties:false 必须声明）
+          trace: {
+            type: 'array',
+            items: {
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                preset: { type: 'string' },
+                image: { type: 'string' },
+                nodeId: { type: 'string' },
+                // 只描了原图的一块时才有：那块在原图里的位置与尺寸（像素）
+                crop: {
+                  type: 'object',
+                  additionalProperties: false,
+                  properties: {
+                    x: { type: 'number' },
+                    y: { type: 'number' },
+                    w: { type: 'number' },
+                    h: { type: 'number' },
+                  },
+                },
+                source: {
+                  type: 'object',
+                  additionalProperties: false,
+                  properties: {
+                    width: { type: 'number' },
+                    height: { type: 'number' },
+                  },
+                },
+                work: {
+                  type: 'object',
+                  additionalProperties: false,
+                  properties: {
+                    width: { type: 'number' },
+                    height: { type: 'number' },
+                    scale: { type: 'number' },
+                  },
+                },
+                scaleApplied: { type: 'number' },
+                sizeNotes: { type: 'string' },
+                colors: { type: 'number' },
+                colorsDark: { type: 'number' },
+                colorsFill: { type: 'number' },
+                protectPixels: { type: 'number' },
+                majoritySkipped: { type: 'number' },
+                paths: { type: 'number' },
+                loopsKept: { type: 'number' },
+                loopsProtectedKept: { type: 'number' },
+                regionsProtected: { type: 'number' },
+                svgChars: { type: 'number' },
+                budget: { type: 'number' },
+                attempts: { type: 'number' },
+                exactPixelCoverage: { type: 'boolean' },
+                options: { type: 'json' },
+                hint: { type: 'string' },
+              },
+            },
+          },
         },
       },
       render: function (args, value) {
@@ -2886,6 +3075,24 @@ export function apply(ctx) {
         }
         if (Array.isArray(value.changed) && value.changed.length > 0) bits.push('改动 ' + value.changed.join(', '))
         if (Array.isArray(value.removed) && value.removed.length > 0) bits.push('删除 ' + value.removed.join(', '))
+        if (Array.isArray(value.trace) && value.trace.length > 0) {
+          bits.push(
+            '矢量化 ' +
+              value.trace
+                .map(function (t) {
+                  return (
+                    (t.image || '?') +
+                    ' preset=' +
+                    (t.preset || 'default') +
+                    ' ' +
+                    t.svgChars +
+                    '字' +
+                    (t.hint ? ' | ' + t.hint : '')
+                  )
+                })
+                .join('；'),
+          )
+        }
         return [
           {
             type: 'text',
@@ -3001,6 +3208,7 @@ export function apply(ctx) {
           created: [],
           changed: [],
           removed: [],
+          ...(Array.isArray(out.trace) && out.trace.length > 0 ? { trace: out.trace } : {}),
           ...(exportStateFor(sessionId, loaded.absolute) !== undefined ? { export: exportStateFor(sessionId, loaded.absolute) } : {}),
           summary: notes.length === 0 ? '(no change)' : notes.join('\n'),
         }
@@ -3052,6 +3260,7 @@ export function apply(ctx) {
         created: Array.isArray(out.created) ? out.created : [],
         changed: Array.isArray(out.changed) ? out.changed : [],
         removed: Array.isArray(out.removed) ? out.removed : [],
+        ...(Array.isArray(out.trace) && out.trace.length > 0 ? { trace: out.trace } : {}),
         ...(exportStateFor(sessionId, loaded.absolute) !== undefined ? { export: exportStateFor(sessionId, loaded.absolute) } : {}),
         summary: notes.length === 0 ? '(no change)' : notes.join('\n'),
       }

package/lib/raster.js

@@ -13,6 +13,8 @@
  */
 
 import { inflateSync } from 'node:zlib'
+import { createRequire } from 'node:module'
+import { pathToFileURL } from 'node:url'
 
 /** PNG 的 8 字节签名。 */
 const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]
@@ -267,24 +269,70 @@ export function looksLikeRaster(bytes) {
   return false
 }
 
+/**
+ * sharp 可能装在哪：包名 + DSH profile 里那份（本机是这么装的）。
+ *
+ * 为什么本机路径写死：sharp 是可选依赖，没装它的部署不该因为我们 import 不到就崩；
+ * 而宿主进程的 cwd 是**用户的工作区**、不在插件的 node_modules 链上，所以裸包名
+ * 在这种部署里注定解析不到（package.json 里 sharp 也不是依赖）。
+ */
+const SHARP_CANDIDATES = [
+  'sharp',
+  'C:/Users/86476/AppData/Roaming/npm/node_modules/@deepseek-ai/dsh/node_modules/sharp',
+]
+
+/**
+ * 把候选解成**可 import 的入口文件 URL**。
+ *
+ * 这里踩过两个坑，都只能在真机上才发现：
+ *   · 动态 import 的说明符必须是 URL 或裸包名，**给文件系统路径会抛
+ *     ERR_UNSUPPORTED_ESM_URL_SCHEME**（`C:/…/sharp` 和 `C:/…/sharp/dist/index.cjs` 都是）；
+ *   · 给**目录**还会抛 ERR_UNSUPPORTED_DIR_IMPORT —— ESM 不认目录，哪怕那个目录里有 package.json
+ *     （sharp 0.35 是 CJS，main 指向 ./dist/index.cjs）。
+ * 所以：先用 createRequire 的 require.resolve 解出**入口文件**，再用 pathToFileURL 转成
+ * file:// URL。require.resolve 只用来"定位"、不用来加载任何东西；也正因为它认 package.json 的
+ * exports/main，这条不依赖 sharp 内部目录布局（比写死 /dist/index.cjs 耐升级）。
+ */
+function resolveSharpImport() {
+  const urls = []
+  const req = createRequire(import.meta.url)
+  const add = (candidate) => {
+    try {
+      const entry = req.resolve(candidate)
+      const url = pathToFileURL(entry).href
+      if (urls.indexOf(url) < 0) urls.push(url)
+    } catch (error) {
+      /* 这个候选不在（没装 / 解析不到），换下一个 */
+    }
+  }
+  for (const candidate of SHARP_CANDIDATES) add(candidate)
+  // 兜底：require.resolve 那条也可能失败（例如导出图把它藏了），此时按目录试常见入口。
+  // pathToFileURL 会把目录路径照常编成 file:// URL，import 再按 package.json 的 main 解析。
+  for (const candidate of SHARP_CANDIDATES) {
+    if (candidate === 'sharp') continue
+    add(candidate)
+    add(candidate + '/dist/index.cjs')
+  }
+  // 去重：兜底可能补出与前一条相同的 URL（entry 与 /dist/index.cjs 同址时）
+  const unique = urls.filter((value, index) => urls.indexOf(value) === index)
+  return unique
+}
+
 /**
  * 非 PNG 的解码回退：**可选** sharp（宿主没装就返回 null，由调用方给一句人话报错）。
  *
  * 用动态 import 而不是顶层 import：没装 sharp 的部署不该连模块都加载不了。
- * 路径依次试：包名、DSH profile 里的那份（本机是这么装的）。
  */
 async function decodeWithSharp(bytes) {
-  const candidates = [
-    'sharp',
-    'C:/Users/86476/AppData/Roaming/npm/node_modules/@deepseek-ai/dsh/node_modules/sharp',
-  ]
-  for (const spec of candidates) {
+  for (const spec of resolveSharpImport()) {
     let sharp
     try {
-      sharp = (await import(spec)).default
+      const mod = await import(spec)
+      sharp = mod.default !== undefined && mod.default !== null ? mod.default : mod
     } catch (error) {
       continue
     }
+    if (typeof sharp !== 'function') continue
     try {
       const got = await sharp(Buffer.from(bytes)).ensureAlpha().raw().toBuffer({ resolveWithObject: true })
       return { width: got.info.width, height: got.info.height, data: got.data }

package/lib/trace-image.js

@@ -5,11 +5,12 @@
  * 这里只有**像素进、SVG 出**，不碰文件系统、不碰 ctx：宿主工具与命令行脚本共用同一份。
  *
  * 管线（每一步都能在返回的 metrics 里看到数字）：
- *   ① 四边泛洪判背景（近白 / 近灰 / 全透明）→ 不画截图底色
- *   ② k-means 定调色板（K 个前景色 + 背景单独占第 0 号）
- *   ③ 3× 超采样逐样本归类 → 3×3 众数滤波 → 降回原分辨率 → <minArea 的碎块并入邻色
- *   ④ 每色按连通域取闭合轮廓：像素**格边**上的有向图 + 左转跟随（区域恒在左侧）
- *   ⑤ RDP 简化 + 相对增量编码 → 每色一条 <path fill-rule="nonzero">
+ *   ① 工作图尺寸 = src/scale，再套 grid（宽）/ gridH（高）上限；透明像素合成到 bgColor
+ *   ② 四边泛洪判背景（近白 / 近灰 / 全透明）→ 不画截图底色
+ *   ③ 分层 k-means（colorsDark 暗色 + colorsFill 填充）定调色板；暗像素进保护区
+ *   ④ 3× 超采样归类 → 条件众数（高对比跳过）→ despeckle / minRegionArea（保护区不并）
+ *   ⑤ 每色按连通域取闭合轮廓：像素**格边**上的有向图 + 左转跟随（区域恒在左侧）
+ *   ⑥ RDP + 预算阶梯（受保护环不因 minLoopArea 丢弃）→ 每色一条 <path fill-rule="nonzero">
  *
  * 为什么是"格边跟随"而不是 marching squares：标签图在鞍点（对角相接）处 marching squares
  * 要人为定连通性，而格边有向图本身就无歧义 —— 每条边只属于一个区域，走完一圈恰好回到起点。
@@ -21,6 +22,11 @@ function clamp(v, lo, hi) {
   return v < lo ? lo : v > hi ? hi : v
 }
 
+/** 相对亮度（0..255），用于线稿/保护区与众数对比。 */
+function lumaRgb(r, g, b) {
+  return 0.299 * r + 0.587 * g + 0.114 * b
+}
+
 /* ────────────────────────── ① 背景 ────────────────────────── */
 
 /**
@@ -305,12 +311,21 @@ function traceLoops(comp, width, height, regionCount) {
  *   · 并进**颜色最接近**的邻色，而不是"面积最多的"—— 边缘的过渡色应该并回它看起来最像的那一侧；
  *   · **不连锁**：一轮里对固定快照判一次，避免小块并进小块滚雪球。
  */
-function despeckle(labels, width, height, palette, minArea) {
+/**
+ * 按颜色分块合并碎块。
+ * @param {Uint8Array|null} protectMask 非空时：块内受保护像素过半，或该 label 本身是保护色 → 不合并
+ * @param {Uint8Array|null} protectLabels 长度为 palette.length；1 = 该色永不被合并
+ */
+function despeckle(labels, width, height, palette, minArea, protectMask, protectLabels) {
+  if (!(minArea > 0)) {
+    return { mergedPixels: 0, blocksMerged: 0, blocks: 0, protectedSkipped: 0 }
+  }
   const colorCount = palette.length
   const comp = new Int32Array(width * height).fill(-1)
   const stack = []
   let mergedPixels = 0
   let blocksMerged = 0
+  let protectedSkipped = 0
 
   // 先把每块 4 连通区域找出来（一次，不随合并改变）
   const blocks = []
@@ -353,6 +368,18 @@ function despeckle(labels, width, height, palette, minArea) {
     if (block.pixels.length >= minArea) continue
     // 背景（label 0）不参与：它是"没画东西的地方"，并它等于把图啃出洞
     if (palette[block.label] === undefined) continue
+    if (protectLabels !== null && protectLabels !== undefined && protectLabels[block.label] === 1) {
+      protectedSkipped += 1
+      continue
+    }
+    if (protectMask !== null && protectMask !== undefined) {
+      let prot = 0
+      for (let k = 0; k < block.pixels.length; k += 1) if (protectMask[block.pixels[k]] === 1) prot += 1
+      if (prot * 2 >= block.pixels.length) {
+        protectedSkipped += 1
+        continue
+      }
+    }
     hist.fill(0)
     for (let k = 0; k < block.pixels.length; k += 1) {
       const p = block.pixels[k]
@@ -392,7 +419,109 @@ function despeckle(labels, width, height, palette, minArea) {
     mergedPixels += pixels.length
     blocksMerged += 1
   }
-  return { mergedPixels: mergedPixels, blocksMerged: blocksMerged, blocks: blocks.length }
+  return {
+    mergedPixels: mergedPixels,
+    blocksMerged: blocksMerged,
+    blocks: blocks.length,
+    protectedSkipped: protectedSkipped,
+  }
+}
+
+/**
+ * 分层调色板：暗像素单独 k-means（colorsDark），其余走 colorsFill。
+ * colorsDark=0 时退回单次 k-means（与旧行为一致）。
+ */
+function buildPalette(work, fgIndex, colors, colorsDark, colorsFill, protectLuma, seeds) {
+  const darkK = Math.max(0, Math.min(colors - 1, colorsDark))
+  const fillK = Math.max(1, colors - darkK)
+  // 显式 colorsFill 时以它为准（仍保证总和 = colors）
+  const useFill = colorsFill > 0 ? Math.max(1, Math.min(colors, colorsFill)) : fillK
+  const useDark = colorsFill > 0 ? Math.max(0, colors - useFill) : darkK
+
+  if (useDark === 0 || !(protectLuma > 0)) {
+    const samples = new Float64Array(fgIndex.length * 3)
+    for (let i = 0; i < fgIndex.length; i += 1) {
+      const o = fgIndex[i] * 4
+      samples[i * 3] = work[o]
+      samples[i * 3 + 1] = work[o + 1]
+      samples[i * 3 + 2] = work[o + 2]
+    }
+    let best = null
+    for (let s = 1; s <= seeds; s += 1) {
+      const got = kmeans(samples, colors, 24, s * 2654435761)
+      if (best === null || got.inertia < best.inertia) best = got
+    }
+    return {
+      cents: best.cent,
+      colorsDark: 0,
+      colorsFill: colors,
+      darkSamples: 0,
+      fillSamples: fgIndex.length,
+    }
+  }
+
+  const darkIdx = []
+  const fillIdx = []
+  for (let i = 0; i < fgIndex.length; i += 1) {
+    const p = fgIndex[i]
+    const o = p * 4
+    if (lumaRgb(work[o], work[o + 1], work[o + 2]) <= protectLuma) darkIdx.push(p)
+    else fillIdx.push(p)
+  }
+
+  // 某一侧为空时，把配额并给另一侧，避免空簇
+  let kDark = useDark
+  let kFill = useFill
+  if (darkIdx.length === 0) {
+    kFill = colors
+    kDark = 0
+  } else if (fillIdx.length === 0) {
+    kDark = colors
+    kFill = 0
+  }
+
+  const cents = []
+  function runK(indexes, k, seedBase) {
+    if (k <= 0 || indexes.length === 0) return
+    const samples = new Float64Array(indexes.length * 3)
+    for (let i = 0; i < indexes.length; i += 1) {
+      const o = indexes[i] * 4
+      samples[i * 3] = work[o]
+      samples[i * 3 + 1] = work[o + 1]
+      samples[i * 3 + 2] = work[o + 2]
+    }
+    const kk = Math.min(k, indexes.length)
+    let best = null
+    for (let s = 1; s <= seeds; s += 1) {
+      const got = kmeans(samples, kk, 24, seedBase + s * 2654435761)
+      if (best === null || got.inertia < best.inertia) best = got
+    }
+    for (let c = 0; c < best.cent.length; c += 1) cents.push(best.cent[c])
+  }
+  runK(darkIdx, kDark, 1)
+  runK(fillIdx, kFill, 100)
+  // 极端情况下簇数不足：用全体像素补满
+  if (cents.length < colors) {
+    const samples = new Float64Array(fgIndex.length * 3)
+    for (let i = 0; i < fgIndex.length; i += 1) {
+      const o = fgIndex[i] * 4
+      samples[i * 3] = work[o]
+      samples[i * 3 + 1] = work[o + 1]
+      samples[i * 3 + 2] = work[o + 2]
+    }
+    const need = colors - cents.length
+    const got = kmeans(samples, Math.min(colors, fgIndex.length), 24, 999 * 2654435761)
+    for (let c = 0; c < got.cent.length && cents.length < colors; c += 1) cents.push(got.cent[c])
+    void need
+  }
+
+  return {
+    cents: cents.slice(0, colors),
+    colorsDark: kDark,
+    colorsFill: kFill,
+    darkSamples: darkIdx.length,
+    fillSamples: fillIdx.length,
+  }
 }
 
 /* ────────────────────────── ⑤ 简化与编码 ────────────────────────── */
@@ -525,50 +654,249 @@ function encodeLoop(points, precision) {
 
 /* ────────────────────────── 门面 ────────────────────────── */
 
+/** 把 bgColor 规范成 [r,g,b]（数组或 #rrggbb；认不出就白）。 */
+function parseBgColor(raw) {
+  if (Array.isArray(raw) && raw.length >= 3) {
+    return [
+      clamp(Math.round(Number(raw[0])), 0, 255),
+      clamp(Math.round(Number(raw[1])), 0, 255),
+      clamp(Math.round(Number(raw[2])), 0, 255),
+    ]
+  }
+  if (typeof raw === 'string') {
+    const m = /^#?([0-9a-fA-F]{6})$/.exec(raw.trim())
+    if (m) {
+      const n = parseInt(m[1], 16)
+      return [(n >> 16) & 255, (n >> 8) & 255, n & 255]
+    }
+  }
+  return [255, 255, 255]
+}
+
+/**
+ * 工作图尺寸：先按 scale 降，再用 grid（宽）/ gridH（高，0=不限）做上限；超限等比压。
+ * @returns {{width:number,height:number,scaleRequested:number,scaleApplied:number,grid:number,gridH:number,sizeNotes:string}}
+ */
+function resolveWorkSize(srcWidth, srcHeight, options) {
+  const scaleRequested = Number(options.scale)
+  const scaleRounded = Math.round(scaleRequested)
+  const scaleApplied = scaleRounded >= 1 ? scaleRounded : 1
+  const grid = Math.max(16, Math.round(Number(options.grid)))
+  const gridHRaw = Number(options.gridH)
+  const gridH = gridHRaw > 0 ? Math.max(16, Math.round(gridHRaw)) : 0
+
+  const notes = []
+  if (!(scaleRequested >= 1) || scaleRounded !== scaleApplied) {
+    notes.push('scale clamped to ' + scaleApplied + ' (requested ' + scaleRequested + ')')
+  }
+
+  let width = Math.max(1, Math.round(srcWidth / scaleApplied))
+  let height = Math.max(1, Math.round(srcHeight / scaleApplied))
+  if (scaleApplied > 1) notes.push('scaleApplied ' + scaleApplied)
+
+  const capH = gridH > 0 ? gridH : Infinity
+  if (width > grid || height > capH) {
+    const factor = Math.min(grid / width, capH / height)
+    const nextW = Math.max(16, Math.round(width * factor))
+    const nextH = Math.max(16, Math.round(height * factor))
+    const parts = []
+    if (width > grid) parts.push('width')
+    if (height > capH) parts.push('height')
+    notes.push('grid capped ' + parts.join('+') + ' (' + width + '×' + height + ' → ' + nextW + '×' + nextH + ')')
+    width = nextW
+    height = nextH
+  }
+
+  return {
+    width: width,
+    height: height,
+    scaleRequested: scaleRequested,
+    scaleApplied: scaleApplied,
+    grid: grid,
+    gridH: gridH,
+    sizeNotes: notes.join('; '),
+  }
+}
+
 /** 矢量化的默认参数（宿主工具与命令行共用）。 */
 export const TRACE_DEFAULTS = {
-  colors: 12, // 前景调色板色数（背景另占 1 色）
-  grid: 499, // 按这个宽度做；高度按原图比例算，够大就原尺寸
-  scale: 1, // 先按 scale×scale 面积平均降采样，再做管线（=1 表示不降）
+  preset: 'default', // 命名预设，见 TRACE_PRESETS；显式字段覆盖预设
+  colors: 12, // 前景调色板色数（背景另占 1 色）= colorsDark + colorsFill（auto）
+  colorsDark: 3, // 暗色配额（线稿）；0 = 不分层，全体一次 k-means
+  colorsFill: 0, // 填充色配额；0 = 自动 colors - colorsDark
+  grid: 499, // 工作图宽度上限（px）；与 gridH 一起做等比封顶
+  gridH: 0, // 工作图高度上限（px）；0 = 不限高（只卡宽，兼容旧行为）
+  scale: 1, // 真降采样因子：work ≈ src/scale，再套 grid/gridH（=1 表示不按 scale 降）
   epsilon: 2.0, // RDP 简化容差（像素）
   precision: 1, // 坐标小数位
-  minArea: 10, // 小于这个面积（像素²）的碎块并进邻色
+  minArea: 10, // despeckle：小于这个面积（像素²）的碎块并进邻色；0 = 关
+  minRegionArea: 0, // despeckle 之后再按面积并区域；0 = 关（与 minArea 分开调）
+  protectLuma: 110, // 亮度 ≤ 此值的前景像素受保护（不 despeckle / 不 ladder 丢环）；0 = 关
+  majorityContrast: 40, // 局部亮度差 ≥ 此值则跳过众数滤波（保线稿）；0 = 全图滤波（旧行为）
   bgBright: 238, // 判"近白"的亮度下限
   bgTol: 10, // 判"近灰"的通道差上限
+  bgColor: [255, 255, 255], // 透明/半透明像素合成底色（再进泛洪与 k-means）
   seeds: 3, // k-means 重启次数（取 inertia 最小）
-  maxBytes: 50000, // SVG 上限（drawio style 里的 data URI 要塞得下；60000 是硬上限，留余量）
+  // SVG 上限（换算成 drawio style 里的 data URI 要塞得下）。宿主的硬上限是 250000 字符，
+  // 且它自己会再留 2000 的余量 —— 所以这里直接对齐到 248000：整图的精细度就由这个预算决定
+  // （预算越小，管线越要抬 epsilon、丢小环）。命令行想更省字符可显式传 --budget。
+  maxBytes: 248000,
   includeLabels: false, // 额外返回"去碎块后"的标签图（调试/比对用；会额外占 width*height 字节的 base64）
 }
 
+/**
+ * 命名预设：AI 先选场景，再按需覆盖单个字段。
+ * 合并顺序：TRACE_DEFAULTS ← preset ← 显式字段。
+ */
+export const TRACE_PRESETS = {
+  default: {},
+  /** 插画 / 线稿：多留暗色、严保细线、轮廓更细 */
+  lineart: {
+    colorsDark: 4,
+    protectLuma: 130,
+    majorityContrast: 32,
+    minArea: 4,
+    epsilon: 1.5,
+    precision: 2,
+  },
+  /** 照片 / 渐变：少暗色配额、碎块并多一点、轮廓可粗 */
+  photo: {
+    colors: 14,
+    colorsDark: 1,
+    protectLuma: 80,
+    majorityContrast: 55,
+    minArea: 16,
+    epsilon: 2.5,
+  },
+  /** 图标 / 简单截图：少色 + 降采样，压字符数 */
+  simple: {
+    colors: 6,
+    colorsDark: 2,
+    scale: 2,
+    grid: 320,
+    epsilon: 3,
+    minArea: 20,
+    protectLuma: 100,
+  },
+}
+
+/** 合法预设名列表（给报错 / 提示用）。 */
+export const TRACE_PRESET_NAMES = Object.keys(TRACE_PRESETS)
+
+/**
+ * 合并默认值 + 预设 + 显式覆盖。未知 preset 抛错（让 AI 立刻改，而不是静默当 default）。
+ * @returns {{options:object, preset:string}}
+ */
+export function resolveTraceOptions(rawOptions) {
+  const raw = rawOptions === undefined || rawOptions === null ? {} : rawOptions
+  const presetName = typeof raw.preset === 'string' && raw.preset.length > 0 ? raw.preset : 'default'
+  if (TRACE_PRESETS[presetName] === undefined) {
+    throw new Error(
+      '未知 trace preset "' + presetName + '"；可用：' + TRACE_PRESET_NAMES.join(', '),
+    )
+  }
+  const options = Object.assign({}, TRACE_DEFAULTS, TRACE_PRESETS[presetName], raw, { preset: presetName })
+  return { options: options, preset: presetName }
+}
+
+/**
+ * 根据 metrics 生成一句调参建议（给 AI 读，不是给用户的长文）。
+ */
+export function hintTraceTune(metrics) {
+  if (metrics === undefined || metrics === null) return ''
+  const hints = []
+  const budget = Number(metrics.budget) || TRACE_DEFAULTS.maxBytes
+  const chars = Number(metrics.svgChars) || 0
+  if (chars > budget * 0.9 || Number(metrics.attempts) > 1) {
+    hints.push('字符紧/触发预算阶梯 → 试 scale:2、加大 epsilon、减小 colors/grid，或 preset:"simple"')
+  }
+  if (Number(metrics.protectPixels) === 0 && metrics.preset !== 'photo') {
+    hints.push('无暗像素保护区 → 插画线稿可试 preset:"lineart" 或提高 protectLuma')
+  }
+  if (Number(metrics.colorsDark) === 0 && Number(metrics.darkSamples) === 0 && metrics.preset === 'lineart') {
+    hints.push('lineart 但没分到暗样本 → 提高 protectLuma 或检查原图对比度')
+  }
+  if (Number(metrics.majoritySkipped) === 0 && Number(metrics.majorityContrast) > 0) {
+    hints.push('众数未跳过任何像素 → 图对比偏低，可减小 majorityContrast 或改 preset')
+  }
+  if (chars < budget * 0.35 && Number(metrics.scaleApplied) >= 2) {
+    hints.push('字符很富余且已降采样 → 可 scale:1 或减小 epsilon 换保真')
+  }
+  if (hints.length === 0) {
+    hints.push('指标正常；线稿糊/断可试 preset:"lineart"；要更省字符用 preset:"simple"')
+  }
+  return hints.join('；')
+}
+
+/**
+ * 压缩给 AI 的结构化调参回执（diagram_apply.trace[]）。
+ */
+export function summarizeTraceForAi(metrics, extra) {
+  const base = {
+    preset: metrics.preset,
+    image: extra && extra.image !== undefined ? extra.image : undefined,
+    nodeId: extra && extra.nodeId !== undefined ? extra.nodeId : undefined,
+    // 只描了原图的一块时才有：那块在原图里的位置与尺寸（像素）——
+    // 模型据此知道"这次只覆盖了局部"，以及该按原图坐标把它摆到哪。
+    crop: metrics.crop,
+    source: metrics.source,
+    work: metrics.work,
+    scaleApplied: metrics.scaleApplied,
+    sizeNotes: metrics.sizeNotes,
+    colors: metrics.colors,
+    colorsDark: metrics.colorsDark,
+    colorsFill: metrics.colorsFill,
+    protectPixels: metrics.protectPixels,
+    majoritySkipped: metrics.majoritySkipped,
+    paths: metrics.paths,
+    loopsKept: metrics.loopsKept,
+    loopsProtectedKept: metrics.loopsProtectedKept,
+    regionsProtected: metrics.regionsProtected,
+    svgChars: metrics.svgChars,
+    budget: metrics.budget,
+    attempts: metrics.attempts,
+    exactPixelCoverage: metrics.exactPixelCoverage,
+    options: metrics.optionsApplied,
+    hint: metrics.tuneHint,
+  }
+  return base
+}
+
 /**
  * 位图 → SVG 标记。
  *
  * @param {{width:number,height:number,data:Buffer|Uint8Array}} raster RGBA8
- * @param {object} [rawOptions] 见 TRACE_DEFAULTS
+ * @param {object} [rawOptions] 见 TRACE_DEFAULTS / TRACE_PRESETS（可用 preset）
  * @returns {{svg:string, metrics:object}}
  */
 export function traceRasterToSvg(raster, rawOptions) {
-  const options = Object.assign({}, TRACE_DEFAULTS, rawOptions === undefined || rawOptions === null ? {} : rawOptions)
+  const resolved = resolveTraceOptions(rawOptions)
+  const options = resolved.options
+  const preset = resolved.preset
   const colors = Math.max(2, Math.min(24, Math.round(options.colors)))
-  const grid = Math.max(16, Math.round(options.grid))
-  const scale = Math.max(1, Math.round(options.scale))
-  const minArea = Math.max(1, Math.round(options.minArea))
+  const colorsDark = Math.max(0, Math.min(colors, Math.round(options.colorsDark)))
+  const colorsFillOpt = Math.max(0, Math.min(colors, Math.round(options.colorsFill)))
+  const minArea = Math.max(0, Math.round(options.minArea))
+  const minRegionArea = Math.max(0, Math.round(options.minRegionArea))
+  const protectLuma = Math.max(0, Number(options.protectLuma))
+  const majorityContrast = Math.max(0, Number(options.majorityContrast))
   const seeds = Math.max(1, Math.round(options.seeds))
+  const bgColor = parseBgColor(options.bgColor)
 
   const srcWidth = raster.width
   const srcHeight = raster.height
   const rgba = raster.data
 
-  // 目标尺寸：宽度向 grid 靠（够大就原尺寸），高度按比例（至少 16px）
-  let width = srcWidth
-  let height = srcHeight
-  if (grid < srcWidth) {
-    width = grid
-    height = Math.max(16, Math.round((srcHeight * grid) / srcWidth))
-  }
+  const sized = resolveWorkSize(srcWidth, srcHeight, options)
+  const width = sized.width
+  const height = sized.height
+  const scale = sized.scaleApplied
 
-  // 降采样（面积平均）+ 缩放：一次写完，后面只认 width×height 的工作图
+  // 降采样（面积平均）+ 把每个源像素先合成到 bgColor：一次写完，后面只认不透明的 width×height 工作图
   const work = new Uint8Array(width * height * 4)
+  const bgR = bgColor[0]
+  const bgG = bgColor[1]
+  const bgB = bgColor[2]
   for (let y = 0; y < height; y += 1) {
     const y0 = Math.floor((y * srcHeight) / height)
     const y1 = Math.max(y0 + 1, Math.floor(((y + 1) * srcHeight) / height))
@@ -583,10 +911,14 @@ export function traceRasterToSvg(raster, rawOptions) {
       for (let yy = y0; yy < y1; yy += 1) {
         for (let xx = x0; xx < x1; xx += 1) {
           const o = (yy * srcWidth + xx) * 4
-          r += rgba[o]
-          g += rgba[o + 1]
-          b += rgba[o + 2]
-          a += rgba[o + 3]
+          const srcA = rgba[o + 3]
+          const af = srcA / 255
+          const inv = 1 - af
+          // RGB 先合成到 bgColor，避免半透明边缘带着脏 RGB；alpha 原样平均留给 nearWhite(a<16)
+          r += rgba[o] * af + bgR * inv
+          g += rgba[o + 1] * af + bgG * inv
+          b += rgba[o + 2] * af + bgB * inv
+          a += srcA
           n += 1
         }
       }
@@ -622,31 +954,47 @@ export function traceRasterToSvg(raster, rawOptions) {
   for (let i = 0; i < width * height; i += 1) if (isBg[i] === 0) fgIndex.push(i)
   if (fgIndex.length === 0) throw new Error('这张图整幅都是背景色（近白/近灰），没有可画的像素')
 
-  let best = null
-  {
-    const samples = new Float64Array(fgIndex.length * 3)
+  // 保护区：暗前景像素（线稿）—— despeckle / ladder 都不动它们
+  const protectMask = new Uint8Array(width * height)
+  let protectPixels = 0
+  if (protectLuma > 0) {
     for (let i = 0; i < fgIndex.length; i += 1) {
-      const o = fgIndex[i] * 4
-      samples[i * 3] = work[o]
-      samples[i * 3 + 1] = work[o + 1]
-      samples[i * 3 + 2] = work[o + 2]
-    }
-    for (let s = 1; s <= seeds; s += 1) {
-      const got = kmeans(samples, colors, 24, s * 2654435761)
-      if (best === null || got.inertia < best.inertia) best = got
+      const p = fgIndex[i]
+      const o = p * 4
+      if (lumaRgb(work[o], work[o + 1], work[o + 2]) <= protectLuma) {
+        protectMask[p] = 1
+        protectPixels += 1
+      }
     }
   }
+
+  const built = buildPalette(work, fgIndex, colors, colorsDark, colorsFillOpt, protectLuma, seeds)
   const palette = [bgMean]
-  for (let c = 0; c < best.cent.length; c += 1) {
-    palette.push([clamp(Math.round(best.cent[c][0]), 0, 255), clamp(Math.round(best.cent[c][1]), 0, 255), clamp(Math.round(best.cent[c][2]), 0, 255)])
+  for (let c = 0; c < built.cents.length; c += 1) {
+    palette.push([
+      clamp(Math.round(built.cents[c][0]), 0, 255),
+      clamp(Math.round(built.cents[c][1]), 0, 255),
+      clamp(Math.round(built.cents[c][2]), 0, 255),
+    ])
   }
   const colorCount = palette.length
+  const protectLabels = new Uint8Array(colorCount)
+  if (protectLuma > 0) {
+    for (let c = 1; c < colorCount; c += 1) {
+      const p = palette[c]
+      if (lumaRgb(p[0], p[1], p[2]) <= protectLuma) protectLabels[c] = 1
+    }
+  }
 
-  // ③ 超采样归类（双线性）→ 众数滤波 → 降回原分辨率
+  // ③ 超采样归类（双线性）→ 条件众数滤波 → 降回原分辨率
   const ss = 3
   const sw = width * ss
   const sh = height * ss
   const gridLabels = new Uint8Array(sw * sh)
+  const paletteLuma = new Float64Array(colorCount)
+  for (let c = 0; c < colorCount; c += 1) {
+    paletteLuma[c] = lumaRgb(palette[c][0], palette[c][1], palette[c][2])
+  }
   const px = [0, 0, 0]
   for (let y = 0; y < sh; y += 1) {
     const fy = (y + 0.5) / ss - 0.5
@@ -687,8 +1035,32 @@ export function traceRasterToSvg(raster, rawOptions) {
 
   const scratch = new Uint8Array(gridLabels.length)
   const hist = new Int32Array(colorCount + 1)
+  let majoritySkipped = 0
+  let majorityApplied = 0
   for (let y = 0; y < sh; y += 1) {
     for (let x = 0; x < sw; x += 1) {
+      const self = gridLabels[y * sw + x]
+      // 局部对比高（线稿边缘）→ 跳过众数，避免细线被邻色吃掉
+      if (majorityContrast > 0) {
+        let minL = paletteLuma[self]
+        let maxL = minL
+        for (let dy = -1; dy <= 1; dy += 1) {
+          const yy = y + dy
+          if (yy < 0 || yy >= sh) continue
+          for (let dx = -1; dx <= 1; dx += 1) {
+            const xx = x + dx
+            if (xx < 0 || xx >= sw) continue
+            const L = paletteLuma[gridLabels[yy * sw + xx]]
+            if (L < minL) minL = L
+            if (L > maxL) maxL = L
+          }
+        }
+        if (maxL - minL >= majorityContrast) {
+          scratch[y * sw + x] = self
+          majoritySkipped += 1
+          continue
+        }
+      }
       hist.fill(0)
       for (let dy = -1; dy <= 1; dy += 1) {
         const yy = y + dy
@@ -699,7 +1071,7 @@ export function traceRasterToSvg(raster, rawOptions) {
           hist[gridLabels[yy * sw + xx]] += 1
         }
       }
-      let bi = gridLabels[y * sw + x]
+      let bi = self
       let bc = 0
       for (let c = 0; c < colorCount; c += 1) {
         if (hist[c] > bc) {
@@ -708,6 +1080,7 @@ export function traceRasterToSvg(raster, rawOptions) {
         }
       }
       scratch[y * sw + x] = bi
+      majorityApplied += 1
     }
   }
   gridLabels.set(scratch)
@@ -732,7 +1105,40 @@ export function traceRasterToSvg(raster, rawOptions) {
     }
   }
 
-  const speckle = despeckle(labels, width, height, palette, minArea)
+  // 背景色（label 0）只给泛洪底色用，且最终不画 path。
+  // 白衣白底时，角色内部的白也会被最近邻归到 palette[0] —— 若不改回前景色，
+  // 跳过绘制 label 0 就会把裙子/头发抠成透明洞。
+  let fgRelabeledFromBg = 0
+  let bgForced = 0
+  for (let i = 0; i < width * height; i += 1) {
+    if (isBg[i] === 1) {
+      if (labels[i] !== 0) bgForced += 1
+      labels[i] = 0
+      continue
+    }
+    if (labels[i] !== 0) continue
+    const o = i * 4
+    let bi = 1
+    let bd = Infinity
+    for (let c = 1; c < colorCount; c += 1) {
+      const p = palette[c]
+      const dr = work[o] - p[0]
+      const dg = work[o + 1] - p[1]
+      const db = work[o + 2] - p[2]
+      const d = dr * dr + dg * dg + db * db
+      if (d < bd) {
+        bd = d
+        bi = c
+      }
+    }
+    labels[i] = bi
+    fgRelabeledFromBg += 1
+  }
+
+  const maskOrNull = protectPixels > 0 ? protectMask : null
+  const labelsOrNull = protectLuma > 0 ? protectLabels : null
+  const speckle = despeckle(labels, width, height, palette, minArea, maskOrNull, labelsOrNull)
+  const regionMerge = despeckle(labels, width, height, palette, minRegionArea, maskOrNull, labelsOrNull)
   const labelDump = options.includeLabels === true
     ? {
         width: width, height: height, colors: colorCount,
@@ -741,21 +1147,24 @@ export function traceRasterToSvg(raster, rawOptions) {
       }
     : null
 
-  // ④ 连通域 + 轮廓
+  // ④ 连通域 + 轮廓（记下区域是否受保护，供 ladder 保留细环）
   const comp = new Int32Array(width * height).fill(-1)
   const regionLabel = []
   const regionArea = []
+  const regionProtected = []
   const stack = []
   for (let i = 0; i < width * height; i += 1) {
     if (comp[i] !== -1) continue
     const label = labels[i]
     const id = regionLabel.length
     let area = 0
+    let prot = protectLabels[label] === 1 ? 1 : 0
     comp[i] = id
     stack.push(i)
     while (stack.length > 0) {
       const p = stack.pop()
       area += 1
+      if (protectMask[p] === 1) prot = 1
       const x = p % width
       const y = (p - x) / width
       for (let dy = -1; dy <= 1; dy += 1) {
@@ -774,19 +1183,26 @@ export function traceRasterToSvg(raster, rawOptions) {
     }
     regionLabel.push(label)
     regionArea.push(area)
+    regionProtected.push(prot)
   }
 
   const loopsByRegion = traceLoops(comp, width, height, regionLabel.length)
 
-  // ⑤ 每色一条 path：外环（面积<0，顺时针）+ 洞（>0，反向）
+  // ⑤ 每色一条 path：外环（面积<0，顺时针）+ 洞（>0，反向）；环带 protected 标记
   const byColor = []
   for (let c = 0; c < colorCount; c += 1) byColor.push({ outer: [], hole: [], area: 0 })
   loopsByRegion.forEach(function (loops, id) {
     const label = regionLabel[id]
     const bucket = byColor[label]
+    const protectedLoop = regionProtected[id] === 1
     for (let i = 0; i < loops.length; i += 1) {
-      if (loops[i].area < 0) bucket.outer.push(loops[i])
-      else bucket.hole.push(loops[i])
+      const tagged = {
+        points: loops[i].points,
+        area: loops[i].area,
+        protected: protectedLoop,
+      }
+      if (loops[i].area < 0) bucket.outer.push(tagged)
+      else bucket.hole.push(tagged)
     }
     bucket.area += regionArea[id]
   })
@@ -806,8 +1222,9 @@ export function traceRasterToSvg(raster, rawOptions) {
   let attempts = 0
   let pathCount = 0
   let loopCount = 0
+  let loopsProtectedKept = 0
   let svg = ''
-  // 超预算就逐步收紧：先抬 RDP 容差，再丢小洞
+  // 超预算就逐步收紧：先抬 RDP 容差，再丢小洞（受保护环永不因 minLoopArea 丢弃）
   const ladder = [
     { epsilon: options.epsilon, minLoopArea: 4 },
     { epsilon: Math.max(options.epsilon, 2.5), minLoopArea: 4 },
@@ -821,19 +1238,25 @@ export function traceRasterToSvg(raster, rawOptions) {
     let body = ''
     pathCount = 0
     loopCount = 0
+    loopsProtectedKept = 0
     for (let k = 0; k < order.length; k += 1) {
+      // label 0 = 泛洪标出的截图底色：不画（SVG 该处透明）。
+      // 若画成 path，角色左右两块互不连通的底色会进同一条 nonzero path，
+      // 绕向抵消时会出现"一侧透明、一侧实心白"的假背景（插画发丝顶天立地时必现）。
+      if (order[k] === 0) continue
       const bucket = byColor[order[k]]
       let d = ''
       const all = bucket.outer.concat(bucket.hole)
       for (let i = 0; i < all.length; i += 1) {
         const loop = all[i]
-        if (Math.abs(loop.area) < plan.minLoopArea) continue
+        if (!loop.protected && Math.abs(loop.area) < plan.minLoopArea) continue
         // 洞反向 → nonzero 里挖空
         const points = loop.area > 0 ? loop.points.slice().reverse() : loop.points
         const seg = encodeLoop(simplifyClosed(points, plan.epsilon), options.precision)
         if (seg === null) continue
         d += seg
         loopCount += 1
+        if (loop.protected) loopsProtectedKept += 1
       }
       if (d === '') continue
       body += "<path fill='" + hex(palette[order[k]]) + "' fill-rule='nonzero' d='" + d + "'/>"
@@ -854,33 +1277,74 @@ export function traceRasterToSvg(raster, rawOptions) {
   let paletteArea = 0
   for (let c = 0; c < colorCount; c += 1) paletteArea += byColor[c].area
 
+  const optionsApplied = {
+    preset: preset,
+    colors: colors,
+    colorsDark: colorsDark,
+    colorsFill: colorsFillOpt,
+    grid: sized.grid,
+    gridH: sized.gridH,
+    scale: scale,
+    epsilon: options.epsilon,
+    precision: options.precision,
+    minArea: minArea,
+    minRegionArea: minRegionArea,
+    protectLuma: protectLuma,
+    majorityContrast: majorityContrast,
+  }
+
+  const metrics = {
+    preset: preset,
+    source: { width: srcWidth, height: srcHeight },
+    work: { width: width, height: height, scale: scale },
+    scaleRequested: sized.scaleRequested,
+    scaleApplied: sized.scaleApplied,
+    grid: sized.grid,
+    gridH: sized.gridH,
+    bgColor: bgColor.slice(),
+    sizeNotes: sized.sizeNotes,
+    colors: colorCount - 1,
+    colorsDark: built.colorsDark,
+    colorsFill: built.colorsFill,
+    darkSamples: built.darkSamples,
+    fillSamples: built.fillSamples,
+    protectLuma: protectLuma,
+    protectPixels: protectPixels,
+    fgRelabeledFromBg: fgRelabeledFromBg,
+    bgForced: bgForced,
+    majorityContrast: majorityContrast,
+    majoritySkipped: majoritySkipped,
+    majorityApplied: majorityApplied,
+    palette: palette.map(hex),
+    backgroundPixels: (function () {
+      let n = 0
+      for (let i = 0; i < width * height; i += 1) if (isBg[i] === 1) n += 1
+      return n
+    })(),
+    foregroundPixels: fgIndex.length,
+    despeckle: speckle,
+    regionMerge: regionMerge,
+    regions: regionLabel.length,
+    regionsProtected: regionProtected.reduce(function (n, v) { return n + v }, 0),
+    loops: loopsTotal.value,
+    paths: pathCount,
+    loopsKept: loopCount,
+    loopsProtectedKept: loopsProtectedKept,
+    drawnPixels: covered,
+    totalPixels: width * height,
+    exactPixelCoverage: covered === width * height,
+    svgChars: svg.length,
+    budget: options.maxBytes,
+    attempts: attempts,
+    paletteAreaSum: paletteArea,
+    optionsApplied: optionsApplied,
+  }
+  metrics.tuneHint = hintTraceTune(metrics)
+
   return {
     svg: svg,
     labels: labelDump,
-    metrics: {
-      source: { width: srcWidth, height: srcHeight },
-      work: { width: width, height: height, scale: scale },
-      colors: colorCount - 1,
-      palette: palette.map(hex),
-      backgroundPixels: (function () {
-        let n = 0
-        for (let i = 0; i < width * height; i += 1) if (isBg[i] === 1) n += 1
-        return n
-      })(),
-      foregroundPixels: fgIndex.length,
-      despeckle: speckle,
-      regions: regionLabel.length,
-      loops: loopsTotal.value,
-      paths: pathCount,
-      loopsKept: loopCount,
-      drawnPixels: covered,
-      totalPixels: width * height,
-      exactPixelCoverage: covered === width * height,
-      svgChars: svg.length,
-      budget: options.maxBytes,
-      attempts: attempts,
-      paletteAreaSum: paletteArea,
-    },
+    metrics: metrics,
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-drawai",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "type": "module",
   "description": "DSH 右侧栏的可编辑画布 + AI 语义绘图工具（diagram_apply / diagram_read），直接读写原生 .drawio 文件",
   "license": "MIT",