dsh-copilot-vision 1.0.0 → 1.3.1

package/src/diff.js

@@ -3,8 +3,9 @@
 //
 // 边界（有意为之，不是欠债）：
 //   - localPath 仍是原尺寸裁剪：局部坐标 + bbox 左上角 = 全局物理坐标，模型可以直接换算。
-//   - 额外产出的 gridPath 是 4x 最近邻放大的「网格放大镜」（见 render.js），
-//     它只用于目测/相对点击，不改变 localPath 的 1:1 语义。
+//   - 额外产出的 gridPath 是按面积与单边长度自适应倍率的「网格放大镜」（小区域 4x / 中区域 2x / 大区域 1x，
+//     放大后单边不超过 2000 像素，见 render.js），
+//     它只用于目测/相对点击，不改变 localPath 的 1:1 语义；倍数随区域以 gridScale 字段返回。
 //   - 不做高频抽帧，只在调用时截一张当前图。
 //   - 尺寸/缩放不一致时直接抛错，不做任何重采样或硬算 —— 显示器或缩放变了，
 //     旧截图的坐标系已经不可信，勉强对齐只会给出错误坐标。
@@ -13,14 +14,14 @@ import { join } from 'node:path'
 import { PNG } from 'pngjs'
 import pixelmatch from 'pixelmatch'
 import { screenshotAction } from './actions.js'
-import { get, recordRegions } from './shot-index.js'
+import { get, recordRegions, assertShotFileExists } from './shot-index.js'
 import { resolveShotsDir } from './paths.js'
-import { generateGridImage, MAX_GRID_SOURCE_AREA } from './render.js'
+import { generateGridImage, resolveGridScale } from './render.js'
 
 // 小于这个像素数的连通区域按噪声丢弃（光标闪烁、 blinking caret、亚像素抖动）。
 export const DEFAULT_MIN_REGION_AREA = 100
 
-// 网格图的成本是「每个区域一次 4x 放大 + PNG 编码」，差异块很多时（实测出现过单次 105 块）
+// 网格图的成本是「每个区域一次放大 + PNG 编码」，差异块很多时（实测出现过单次 105 块）
 // 全量生成只会拖慢工具并堆满临时目录，所以只给前 N 个（按面积降序）配网格图。
 export const MAX_GRID_REGIONS = 12
 
@@ -148,10 +149,8 @@ export function diffPair({
     }
     if (i >= MAX_GRID_REGIONS) {
       region.gridSkipped = `只给前 ${MAX_GRID_REGIONS} 个区域生成网格图（本区域排第 ${i + 1}）`
-    } else if (bbox.width * bbox.height > MAX_GRID_SOURCE_AREA) {
-      region.gridSkipped =
-        `区域 ${bbox.width}x${bbox.height} 超过网格图上限 ${MAX_GRID_SOURCE_AREA} 物理像素，直接看全屏更合适`
     } else {
+      region.gridScale = resolveGridScale(bbox.width, bbox.height)
       region.gridPath = generateGridImage(currentMeta.path, bbox, currentMeta.scaleFactor, {
         shotId: currentShotId,
         index: i + 1,
@@ -187,6 +186,7 @@ export async function diffAction({
       `vp_screenshot_diff: baseline shotId ${baseline} 不存在，可先用 vp_screenshot 截一张`,
     )
   }
+  assertShotFileExists(baseline, baselineMeta, 'vp_screenshot_diff')
   const current = await screenshotAction()
   return diffPair({
     baselineMeta,

package/src/keys.js

@@ -0,0 +1,175 @@
+// 按键写法解析：把 "enter" / "ctrl+c" / "f5" 这类人类写法翻译成 robot-ts 的 Key 码与修饰键。
+//
+// 键码不在这里写死：直接从 robot-ts 导出的 Key 枚举反查（枚举名即官方键名），
+// 别名表只补口语写法（esc / del / pgup / 数字键…）。这样上游改键值时我们跟着走，
+// 不会像写死常量那样悄悄注入错键。
+//
+// 解析是纯函数：Key/Modifier 枚举由调用方（actions.js）从 robot-ts 取出后传入，
+// 这样本模块既不 import native，也不依赖宿主。
+
+// 别名 → robot-ts Key 枚举名（小写形式）
+const KEY_ALIASES = {
+  esc: 'escape',
+  return: 'enter',
+  del: 'delete',
+  ins: 'insert',
+  pgup: 'pageup',
+  pgdn: 'pagedown',
+  pgdown: 'pagedown',
+  up: 'uparrow',
+  down: 'downarrow',
+  left: 'leftarrow',
+  right: 'rightarrow',
+  plus: 'equal',
+  1: 'digit1',
+  2: 'digit2',
+  3: 'digit3',
+  4: 'digit4',
+  5: 'digit5',
+  6: 'digit6',
+  7: 'digit7',
+  8: 'digit8',
+  9: 'digit9',
+  0: 'digit0',
+  '-': 'minus',
+  '=': 'equal',
+  '[': 'leftbracket',
+  ']': 'rightbracket',
+  '\\': 'backslash',
+  ';': 'semicolon',
+  "'": 'quote',
+  '`': 'grave',
+  ',': 'comma',
+  '.': 'period',
+  '/': 'slash',
+}
+
+// 别名 → robot-ts Modifier 枚举值
+const MODIFIER_ALIASES = {
+  ctrl: 'Control',
+  control: 'Control',
+  shift: 'Shift',
+  alt: 'Alt',
+  option: 'Alt',
+  meta: 'Meta',
+  cmd: 'Meta',
+  win: 'Meta',
+  super: 'Meta',
+}
+
+// 字符键 → 它在文本里对应的字符。
+//
+// 只给「无修饰键的字符键」准备：这类键改走 Unicode 直注（见 resolveUnicodeChar）。
+// 原因是 robot-ts 的按键注入走 KEYEVENTF_SCANCODE，会经过系统输入法 ——
+// 本机中文输入法实测会把字母键吞成拼音组合串（按下不落字，直到下一次 Enter 才吐出幽灵字符），
+// 还会把引号改写成中文弯引号。Unicode 直注绕开输入法，字符原样落下。
+//
+// space 不在表里：扫描码空格实测正常，而且只有真实按键才能激活聚焦的按钮。
+const CHARACTER_KEYS = {
+  a: 'a', b: 'b', c: 'c', d: 'd', e: 'e', f: 'f', g: 'g', h: 'h', i: 'i', j: 'j',
+  k: 'k', l: 'l', m: 'm', n: 'n', o: 'o', p: 'p', q: 'q', r: 'r', s: 's', t: 't',
+  u: 'u', v: 'v', w: 'w', x: 'x', y: 'y', z: 'z',
+  digit1: '1', digit2: '2', digit3: '3', digit4: '4', digit5: '5',
+  digit6: '6', digit7: '7', digit8: '8', digit9: '9', digit0: '0',
+  minus: '-', equal: '=', leftbracket: '[', rightbracket: ']', backslash: '\\',
+  nonushash: '#', semicolon: ';', quote: "'", grave: '`', comma: ',', period: '.', slash: '/',
+}
+
+export const MODIFIER_NAMES = ['ctrl', 'shift', 'alt', 'meta']
+
+/** Key 枚举 → 小写名到码值的索引（枚举成员名即官方键名）。 */
+function keyIndex(keyEnum) {
+  const index = new Map()
+  for (const [name, value] of Object.entries(keyEnum)) {
+    if (typeof value === 'number') index.set(name.toLowerCase(), value)
+  }
+  return index
+}
+
+/**
+ * 解析按键写法。
+ * 返回 { code, keyName, modifiers, spec }：
+ *   code      robot-ts 的 Key 码（数字）
+ *   keyName   规范化的主键名（robot-ts 枚举名）
+ *   modifiers 修饰键枚举值数组，如 ['Control']
+ *   spec      原样回显的写法
+ * 解析失败一律抛错，错误文案里带上可用的修饰键名。
+ */
+export function parseKeySpec(spec, keyEnum, modifierEnum) {
+  if (typeof spec !== 'string') {
+    throw new Error(`vp_key: key 必须是字符串，收到 ${spec === null ? 'null' : typeof spec}`)
+  }
+  const trimmed = spec.trim()
+  if (trimmed === '') {
+    throw new Error('vp_key: key 不能为空字符串')
+  }
+
+  const parts = trimmed
+    .split('+')
+    .map((part) => part.trim())
+    .filter((part) => part !== '')
+  if (parts.length === 0) {
+    throw new Error('vp_key: key 不能为空字符串')
+  }
+
+  const modifiers = []
+  for (const part of parts.slice(0, -1)) {
+    const modifier = MODIFIER_ALIASES[part.toLowerCase()]
+    if (modifier === undefined) {
+      throw new Error(
+        `vp_key: 不认识的修饰键 "${part}"（可用：${MODIFIER_NAMES.join(' / ')}）`,
+      )
+    }
+    if (!Object.values(modifierEnum).includes(modifier)) {
+      throw new Error(`vp_key: robot-ts 不支持修饰键 "${modifier}"`)
+    }
+    modifiers.push(modifier)
+  }
+
+  const rawKey = parts[parts.length - 1]
+  const lowerKey = rawKey.toLowerCase()
+  if (MODIFIER_ALIASES[lowerKey] !== undefined) {
+    throw new Error(
+      `vp_key: "${rawKey}" 只是修饰键，必须同时给一个主键（例如 ctrl+c、shift+tab）`,
+    )
+  }
+
+  const canonical = KEY_ALIASES[lowerKey] ?? lowerKey
+  const code = keyIndex(keyEnum).get(canonical)
+  if (code === undefined) {
+    throw new Error(
+      `vp_key: 不认识的按键 "${rawKey}"。可用示例：enter / esc / tab / space / backspace / ` +
+      'delete / up / down / left / right / f1-f12 / a-z / 0-9 / ctrl+c / shift+tab',
+    )
+  }
+
+  return {
+    code,
+    keyName: canonical,
+    modifiers,
+    spec: trimmed,
+  }
+}
+
+/** 该键是否是一个字符键；是则返回它对应的字符，否则返回 null。 */
+export function characterForKey(keyName) {
+  return CHARACTER_KEYS[String(keyName).toLowerCase()] ?? null
+}
+
+/**
+ * 判断这个键是否该改走 Unicode 直注，返回要注入的字符；不该改走就返回 null。
+ *
+ * 规则（依据本机实测）：
+ *   - 无修饰键的字符键 → 注入该字符本身
+ *   - 只带 shift 的字母键 → 注入大写字母
+ *   - 其余（带 ctrl/alt/meta 的组合键、控制键、space）→ null，走真实扫描码
+ */
+export function resolveUnicodeChar(spec) {
+  const base = characterForKey(spec.keyName)
+  if (base === null) return null
+  if (spec.modifiers.length === 0) return base
+  if (spec.modifiers.length === 1 && spec.modifiers[0] === 'Shift' && /^[a-z]$/.test(base)) {
+    return base.toUpperCase()
+  }
+  return null
+}