dsh-copilot-vision 1.0.0 → 1.3.1

package/src/render.js

@@ -1,4 +1,4 @@
-// 位置编码渲染：把差分区域裁出来、4x 最近邻放大、叠加半透明红色网格，
+// 位置编码渲染：把差分区域裁出来、按面积自适应倍率最近邻放大、叠加半透明红色网格，
 // 让模型在「带标尺的放大镜」上数格子，而不是在全屏小图上目测偏移。
 //
 // 选型（不引新依赖）：只用 pngjs + 手写 Bresenham。
@@ -14,11 +14,29 @@ import { resolveShotsDir } from './paths.js'
 
 export const GRID_SCALE = 4
 export const GRID_STEP_PHYSICAL = 20
+// 4x 档的图内步距（放大图上每格像素数）；其余档位 = GRID_STEP_PHYSICAL × 倍数。
 export const GRID_STEP_IMAGE = GRID_SCALE * GRID_STEP_PHYSICAL // 80
 
-// 4x 放大后的缓冲是源面积的 16 倍（RGBA 字节数 64 倍）。250k 物理像素 ≈ 4M 放大像素 ≈ 16MB buffer，
-// 再大就不适合当「局部放大镜」了 —— 退回看全屏截图更合理。
-export const MAX_GRID_SOURCE_AREA = 250_000
+// 自适应倍率阈值（物理像素面积）：小区域 4x 保极限精度，中区域 2x 体积减半，
+// 大区域（整页刷新级）1x 只画网格 —— 1920x1200 全屏若 4x = 7680x4800 ≈ 147MB RGBA，绝不可接受。
+// 1x 后输出不可能超过源截图本身，所以不再需要旧的 250k 物理像素 gridSkipped 上限。
+export const GRID_AREA_MAX_4X = 50_000
+export const GRID_AREA_MAX_2X = 200_000
+
+// 面积小但极细长的区域（4344x4 的边框/分隔线）会骗过面积档位：4x 后变成 17376x16 的超长图。
+// 因此再按单边长度封顶：放大后任何一边都不得超过 2000 像素（即 4x 要求长边 <=500，2x 要求 <=1000）。
+// 1x 不再放大，允许输出等于源区域本身，即使源区域长边超过 2000（裁剪尺寸不能凭空压缩）。
+export const GRID_MAX_OUTPUT_EDGE = 2000
+
+/** 按区域物理像素尺寸选放大倍数：面积定基础档位，单边上限再降档。 */
+export function resolveGridScale(width, height) {
+  const area = width * height
+  const maxEdge = Math.max(width, height)
+  let scale = area <= GRID_AREA_MAX_4X ? 4 : area <= GRID_AREA_MAX_2X ? 2 : 1
+  if (scale === 4 && maxEdge * 4 > GRID_MAX_OUTPUT_EDGE) scale = 2
+  if (scale === 2 && maxEdge * 2 > GRID_MAX_OUTPUT_EDGE) scale = 1
+  return scale
+}
 
 const LINE_R = 255
 const LINE_G = 0
@@ -59,7 +77,8 @@ function drawLine(png, x0, y0, x1, y1, alpha = GRID_ALPHA) {
 }
 
 /**
- * 从源截图裁剪 bbox、最近邻放大 GRID_SCALE 倍、每 GRID_STEP_PHYSICAL 物理像素画一条半透明红线，
+ * 从源截图裁剪 bbox、按 resolveGridScale(宽, 高) 自适应倍率最近邻放大、
+ * 每 GRID_STEP_PHYSICAL 物理像素画一条半透明红线，
  * 落盘为 vp-grid-<shotId>-<index>.png。网格原点 = bbox 左上角（bbox 内第 0 个物理像素）。
  *
  * 文件名里的 shotId/index 不在规格签名里，但文件名要求它们，所以通过第 4 个参数传入；
@@ -85,13 +104,7 @@ export function generateGridImage(sourcePngPath, bbox, scaleFactor, { shotId, in
       `收到 shotId=${shotId}, index=${index}`,
     )
   }
-  const area = bbox.width * bbox.height
-  if (area > MAX_GRID_SOURCE_AREA) {
-    throw new Error(
-      `generateGridImage: 区域 ${bbox.width}x${bbox.height}（${area} 像素）超过网格图上限 ` +
-      `${MAX_GRID_SOURCE_AREA}，不放大（放大后缓冲为源面积的 16 倍）`,
-    )
-  }
+  const scale = resolveGridScale(bbox.width, bbox.height)
 
   const source = PNG.sync.read(readFileSync(sourcePngPath))
   if (bbox.x + bbox.width > source.width || bbox.y + bbox.height > source.height) {
@@ -101,28 +114,28 @@ export function generateGridImage(sourcePngPath, bbox, scaleFactor, { shotId, in
     )
   }
 
-  const outWidth = bbox.width * GRID_SCALE
-  const outHeight = bbox.height * GRID_SCALE
+  const outWidth = bbox.width * scale
+  const outHeight = bbox.height * scale
   const out = new PNG({ width: outWidth, height: outHeight })
   const rowBuf = Buffer.alloc(outWidth * 4)
 
   for (let sy = 0; sy < bbox.height; sy++) {
     const srcRow = ((bbox.y + sy) * source.width + bbox.x) * 4
     for (let dx4 = 0; dx4 < outWidth * 4; dx4 += 4) {
-      // dx4/4 = 目标列，再除以 GRID_SCALE 才是源列（最近邻：目标 4 列共用 1 源像素）。
-      const from = srcRow + ((dx4 / (4 * GRID_SCALE)) | 0) * 4
+      // dx4/4 = 目标列，再除以 scale 才是源列（最近邻：目标 scale 列共用 1 源像素）。
+      const from = srcRow + ((dx4 / (4 * scale)) | 0) * 4
       rowBuf[dx4] = source.data[from]
       rowBuf[dx4 + 1] = source.data[from + 1]
       rowBuf[dx4 + 2] = source.data[from + 2]
       rowBuf[dx4 + 3] = source.data[from + 3]
     }
-    for (let k = 0; k < GRID_SCALE; k++) {
-      rowBuf.copy(out.data, (sy * GRID_SCALE + k) * outWidth * 4)
+    for (let k = 0; k < scale; k++) {
+      rowBuf.copy(out.data, (sy * scale + k) * outWidth * 4)
     }
   }
 
-  for (let x = 0; x < outWidth; x += GRID_STEP_IMAGE) drawLine(out, x, 0, x, outHeight - 1)
-  for (let y = 0; y < outHeight; y += GRID_STEP_IMAGE) drawLine(out, 0, y, outWidth - 1, y)
+  for (let x = 0; x < outWidth; x += GRID_STEP_PHYSICAL * scale) drawLine(out, x, 0, x, outHeight - 1)
+  for (let y = 0; y < outHeight; y += GRID_STEP_PHYSICAL * scale) drawLine(out, 0, y, outWidth - 1, y)
 
   const dir = resolveShotsDir()
   mkdirSync(dir, { recursive: true })

package/src/shot-index.js

@@ -5,7 +5,7 @@
 // 落盘策略是有意的：JSON 不是行式格式，无法像审计日志那样 append，
 // 所以每次 record 都用 writeFileSync 全量覆盖。MVP 假定单进程、工具调用串行，
 // 因此不做并发保护（两个进程同时写会互相覆盖，属于已知取舍，不是隐藏 bug）。
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { resolveShotsDir } from './paths.js'
 
@@ -107,6 +107,31 @@ export function get(shotId) {
   return load()[String(shotId)]
 }
 
+/**
+ * vp_summarize 把保留的截图移进 archives/ 后，同步改索引里的路径，
+ * 否则「关键截图」虽然还在盘上，差分却会读不到。
+ */
+export function relocate(shotId, newPath) {
+  const entry = get(shotId)
+  if (entry === undefined) return false
+  entry.path = newPath
+  flush()
+  return true
+}
+
+/**
+ * 索引条目还在、文件却被 vp_summarize 清掉时，给出确定的错误而不是裸 ENOENT。
+ * 条目本身刻意不删：nextShotId 靠索引最大键播种，删条目会让宿主重启后复用旧 shotId，
+ * 静默指向一张新截图 —— 那比「文件不存在」危险得多。
+ */
+export function assertShotFileExists(shotId, meta, toolName) {
+  if (!existsSync(meta.path)) {
+    throw new Error(
+      `${toolName}: shotId ${shotId} 的截图文件已不存在（可能已被 vp_summarize 清理），请重新截图`,
+    )
+  }
+}
+
 /**
  * 把差分区域挂到某张截图的索引条目上。
  * vp_click_relative 用 shotId + 1-based index 反查 bbox，所以区域必须随索引落盘 ——
@@ -118,7 +143,7 @@ export function recordRegions(shotId, regions) {
   entry.regions = regions.map((region) => ({
     bbox: { ...region.bbox },
     localPath: region.localPath,
-    ...(region.gridPath !== undefined ? { gridPath: region.gridPath } : {}),
+    ...(region.gridPath !== undefined ? { gridPath: region.gridPath, gridScale: region.gridScale } : {}),
   }))
   flush()
   return true

package/src/summarize.js

@@ -0,0 +1,131 @@
+// 语义级记忆压缩：把关键截图归档，其余临时碎片一次清空。
+//
+// 与 paths.js 的 cleanupVisualFragments 的分工（两者不冲突）：
+//   - cleanupVisualFragments 是「按时间的兜底」：只在插件启动时删 3 天前的 diff/grid，
+//     永远不碰 vp-shot-*，永远不递归子目录。
+//   - 本函数是「按语义的主清理」：由模型在收工时显式调用，删所有 diff/grid 和没被保留的 vp-shot-*。
+//   主清理的目标集合是兜底清理的超集，先跑谁都不会破坏另一方。
+//
+// 绝对不动的三样：audit.log（证据链）、shot-index.json（shotId 播种与相对点击依赖它）、archives/（归档本体）。
+import { existsSync } from 'node:fs'
+import { appendFile, mkdir, readdir, rename, stat, unlink } from 'node:fs/promises'
+import { basename, join } from 'node:path'
+import { resolveShotsDir } from './paths.js'
+import { get, relocate } from './shot-index.js'
+
+export const ARCHIVE_DIR_NAME = 'archives'
+export const SUMMARY_FILE_NAME = 'archive-summary.txt'
+
+export function archiveDir() {
+  return join(resolveShotsDir(), ARCHIVE_DIR_NAME)
+}
+
+export function summaryPath() {
+  return join(resolveShotsDir(), SUMMARY_FILE_NAME)
+}
+
+const DIFF_RE = /^vp-diff-\d+-\d+\.png$/
+const GRID_RE = /^vp-grid-\d+-\d+\.png$/
+const SHOT_RE = /^vp-shot-.*\.png$/
+
+/**
+ * 收工清理。
+ * @param {{keepShotIds: number[], summary: string}} args
+ * @returns 归档/缺失清单与各类删除计数（供工具层回显）。
+ */
+export async function summarizeAction({ keepShotIds = [], summary } = {}) {
+  if (!Array.isArray(keepShotIds) || keepShotIds.some((id) => !Number.isInteger(id))) {
+    throw new Error(`vp_summarize: keepShotIds 必须是整数数组，收到 ${JSON.stringify(keepShotIds)}`)
+  }
+  if (typeof summary !== 'string' || summary.trim() === '') {
+    throw new Error('vp_summarize: summary 必须是非空字符串')
+  }
+
+  const dir = resolveShotsDir()
+  const archives = archiveDir()
+  await mkdir(archives, { recursive: true })
+
+  const archivedShotIds = []
+  const missingShotIds = []
+  const failedShotIds = []
+  const keepNames = new Set()
+
+  // 先归档再删除：顺序反了会把要保留的图当成「没被选中」删掉。
+  for (const shotId of new Set(keepShotIds)) {
+    const meta = get(shotId)
+    if (meta === undefined) {
+      missingShotIds.push(shotId)
+      continue
+    }
+    const name = basename(meta.path)
+    const sourcePath = join(dir, name)
+    const archivedPath = join(archives, name)
+
+    try {
+      if (existsSync(sourcePath)) {
+        await rename(sourcePath, archivedPath)
+      }
+    } catch {
+      // 归档失败（文件被别的程序占用等）时绝不能继续往下走：
+      // 删循环会把仍在原位的源文件当成「没被保留」删掉。先把它记进 keepNames 保命。
+      keepNames.add(name)
+      failedShotIds.push(shotId)
+      continue
+    }
+    // 源和归档都不在，说明这张图已经丢过一次了，如实报缺失。
+    if (!existsSync(archivedPath)) {
+      missingShotIds.push(shotId)
+      continue
+    }
+
+    relocate(shotId, archivedPath)
+    keepNames.add(name)
+    archivedShotIds.push(shotId)
+  }
+
+  const block = [
+    `[${new Date().toISOString()}] keep=${archivedShotIds.join(',') || '(none)'}`,
+    summary.trim(),
+    '',
+  ].join('\n')
+  await appendFile(summaryPath(), block, 'utf8')
+
+  let removedShots = 0
+  let removedDiff = 0
+  let removedGrid = 0
+  let failedDeletes = 0
+
+  // 只扫顶层：archives/ 是目录，正则匹配不到；即便将来名字撞上，isFile 检查也会挡住。
+  for (const name of await readdir(dir)) {
+    const isDiff = DIFF_RE.test(name)
+    const isGrid = GRID_RE.test(name)
+    const isShot = SHOT_RE.test(name)
+    if (!isDiff && !isGrid && !isShot) continue
+    if (isShot && keepNames.has(name)) continue
+    try {
+      const info = await stat(join(dir, name))
+      if (!info.isFile()) continue
+      await unlink(join(dir, name))
+      if (isDiff) removedDiff++
+      else if (isGrid) removedGrid++
+      else removedShots++
+    } catch {
+      failedDeletes++
+    }
+  }
+
+  return {
+    summary: summary.trim(),
+    archivedShotIds,
+    missingShotIds,
+    failedShotIds,
+    failedArchives: failedShotIds.length,
+    removedShots,
+    removedDiff,
+    removedGrid,
+    removedTotal: removedShots + removedDiff + removedGrid,
+    failedDeletes,
+    archivesDir: archives,
+    summaryPath: summaryPath(),
+  }
+}

package/src/wait.js

@@ -13,7 +13,7 @@ import { readFileSync } from 'node:fs'
 import { PNG } from 'pngjs'
 import pixelmatch from 'pixelmatch'
 import { loadRobotTs } from './robot-ts.js'
-import { get } from './shot-index.js'
+import { get, assertShotFileExists } from './shot-index.js'
 import { screenshotAction } from './actions.js'
 import { diffPair, connectedComponents, DEFAULT_MIN_REGION_AREA } from './diff.js'
 
@@ -72,6 +72,7 @@ export async function waitChangeAction({
       `vp_wait_change: baseline shotId ${baseline} 不存在，可先用 vp_screenshot 截一张`,
     )
   }
+  assertShotFileExists(baseline, baselineMeta, 'vp_wait_change')
   const baselineImg = readPng(baselineMeta.path)
 
   const { Session } = loadRobotTs()