dsh-copilot-vision 1.1.0 → 1.3.2

package/src/auth.js

@@ -1,23 +1,23 @@
 // Vision-Pilot 授权状态机（宿主无关，纯内存单例）。
 //
-// 原则：授权状态只由人的明确动作改变，不由时钟改变。
-// 因此本文件没有任何到期判断，也不返回 remainingMs —— persistent 一经进入就一直有效，
-// 直到用户再次按 Shift+Space 撤销。
+// 授权模型（V1.3）：只有两种权限结论 + 一种等待态。
+//   unauthorized        未授权，一切鼠标与键盘操作直接拦截
+//   pending-persistent  已请求持续授权、等待人类在卡片上确认
+//   persistent          持续授权中，鼠标与键盘一律直接放行
 //
-// 五种 state：
-//   unauthorized        未授权
-//   pending-once        已请求单次授权、等待人类确认（带 pendingRequest）
-//   authorized-once     已确认、等待下一次点击消费（无 pendingRequest）
-//   pending-persistent  已请求持续授权、等待人类确认
-//   persistent          持续授权中，无到期
+// 铁律：授权只由人的明确动作改变——按 Shift+Space，或在卡片上确认 persistent 请求。
+// 不由时钟改变：没有任何到期判断，也不返回 remainingMs。
 //
-// 分工：checkCanClick() 只看是否放行、不改变状态；consumeOnce() 才真正消费
-// authorized-once。因此坐标越界等失败路径不会浪费一次单次授权。
+// V1.3 取消了两样东西，别再引回来：
+//   - 单次授权（pending-once / authorized-once / consumeOnce）：点「允许」会把焦点抢回
+//     DSH 窗口，紧接着的注入落进错误窗口，是实测确认的故障来源。
+//   - 键盘独立通道（keyboardGranted / checkCanKeyboard / consumeKeyboard）：键盘与鼠标
+//     共用 checkCanClick()，persistent 下一律放行，unauthorized 下一律拦截。
 //
-// 每次动作（含被拒绝的点击）都会追加一条审计记录，见 src/audit.js。
+// 每次授权动作与每次被拒绝/放行的注入都追加审计记录，见 src/audit.js。
 //
-// 竞态约定（P0 修复）：pendingRequest 的生命周期绑一个 AbortController。任何清空 pending 的
-// 动作（热键接管/撤销、cancelPending）都必须 abort 它，让调用方那侧「还在等人点卡片」的
+// 竞态约定：pendingRequest 的生命周期绑一个 AbortController。任何清空 pending 的动作
+// （热键接管/撤销、cancelPending）都必须 abort 它，让调用方那侧「还在等人点卡片」的
 // promise 立刻收到 AUTH_CANCELLED 并正常返回，而不是等那个答案迟到后撞进 confirmPending()。
 // confirmPending 只认自己那一次的 requestId：对不上就是迟到的答案，安全丢弃。
 
@@ -25,26 +25,32 @@ import { logState } from './audit.js'
 
 const state = {
   persistent: false,
-  onceGranted: false,
-  /** @type {{requestId: string, mode: 'once'|'persistent', requestedAt: number, controller: AbortController} | null} */
+  /** @type {{requestId: string, mode: 'persistent', requestedAt: number, controller: AbortController} | null} */
   pendingRequest: null,
   requestSeq: 0,
+  // 放行态的代数：每次 persistent 翻转 +1。动作在 checkCanClick() 放行时记下它，
+  // 注入前再比一次——即使中途「撤销又立刻授权」，旧动作也不会带着旧授权继续飞。
+  epoch: 0,
 }
 
 /** 当前授权状态（只读快照，不含内部的 AbortController）。 */
 export function getStatus() {
+  // 待确认请求独立于 state 展示：persistent 在位时也可能挂着一张卡片，
+  // 藏起来的话人/model 都看不到「还有一张卡在等」。
+  const pending = state.pendingRequest === null
+    ? {}
+    : {
+      pendingRequest: {
+        requestId: state.pendingRequest.requestId,
+        mode: state.pendingRequest.mode,
+        requestedAt: state.pendingRequest.requestedAt,
+      },
+    }
   if (state.persistent) {
-    return { state: 'persistent' }
+    return { state: 'persistent', ...pending }
   }
   if (state.pendingRequest !== null) {
-    const { requestId, mode, requestedAt } = state.pendingRequest
-    return {
-      state: mode === 'once' ? 'pending-once' : 'pending-persistent',
-      pendingRequest: { requestId, mode, requestedAt },
-    }
-  }
-  if (state.onceGranted) {
-    return { state: 'authorized-once' }
+    return { state: 'pending-persistent', ...pending }
   }
   return { state: 'unauthorized' }
 }
@@ -65,14 +71,11 @@ function clearPending(reason) {
 }
 
 /**
- * 模型侧发起授权请求。只登记 pendingRequest，不改变放行状态。
+ * 登记一个持续授权请求，不改变放行状态。
  * 返回的 signal 会在该请求被热键接管或被取消时 abort，调用方用它把「等人回答」的
  * promise 换成一个可取消的等待。
  */
-export function requestAuth(mode) {
-  if (mode !== 'once' && mode !== 'persistent') {
-    throw new Error(`requestAuth: mode 必须是 once 或 persistent，收到 ${mode}`)
-  }
+function startRequest() {
   const previousState = getStatus().state
   // 连着发两次请求时，前一张卡片不能变成悬空的：它一被答就撞上「已丢弃」，
   // 所以这里同样要 abort 掉，让前一次等待立刻正常返回。
@@ -80,13 +83,24 @@ export function requestAuth(mode) {
   state.requestSeq += 1
   const requestId = `auth-${state.requestSeq}`
   const controller = new AbortController()
-  state.pendingRequest = { requestId, mode, requestedAt: Date.now(), controller }
-  audit('requestAuth', 'tool', previousState, { requestId, mode })
+  state.pendingRequest = { requestId, mode: 'persistent', requestedAt: Date.now(), controller }
+  audit('requestAuth', 'tool', previousState, { requestId, mode: 'persistent' })
   return { requestId, signal: controller.signal, status: getStatus() }
 }
 
 /**
- * 人侧确认：pending-once → authorized-once；pending-persistent → persistent。
+ * 模型侧发起持续授权请求。只登记 pendingRequest，不改变放行状态。
+ * mode 只为接口稳定保留：V1.3 起只接受 'persistent'，other 值直接报错。
+ */
+export function requestAuth(mode = 'persistent') {
+  if (mode !== 'persistent') {
+    throw new Error(`requestAuth: mode 只支持 persistent（V1.3 已取消单次授权），收到 ${mode}`)
+  }
+  return startRequest()
+}
+
+/**
+ * 人侧确认：pending-persistent → persistent。
  * 只认 requestId 对应的那一次请求。对不上（已被热键接管或已取消）时不改状态、
  * 不写审计、不抛错，返回 confirmed:false —— 迟到的答案本来就该被丢弃。
  */
@@ -97,82 +111,66 @@ export function confirmPending(requestId) {
   }
   const previousState = getStatus().state
   state.pendingRequest = null
-  if (request.mode === 'once') {
-    state.onceGranted = true
-  } else {
-    state.persistent = true
-    state.onceGranted = false
-  }
+  state.persistent = true
+  state.epoch += 1
   request.controller.abort({ code: 'AUTH_CANCELLED', reason: '已由人确认' })
   audit('confirmPending', 'user-question', previousState, { mode: request.mode, requestId })
   return { ...getStatus(), confirmed: true }
 }
 
-/** 取消待确认请求与单次授权。persistent 不受影响（它只能由热键撤销）。 */
+/** 取消待确认请求。persistent 不受影响（它只能由热键撤销）。 */
 export function cancelPending() {
   const previousState = getStatus().state
-  state.onceGranted = false
   clearPending({ code: 'AUTH_CANCELLED', reason: '已取消' })
   audit('cancelPending', 'tool', previousState)
   return getStatus()
 }
 
 /**
- * 热键调用。热键优先级最高，且是 persistent 唯一的入口与出口：
- * persistent 中 → 撤销回 unauthorized；其余状态 → 进入 persistent（清 pending/authorized-once）。
- *
- * 撤销分支必须全清：persistent 期间人确认的「允许一次」会置 onceGranted，而 persistent 下的点击
- * 走 persistent 放行分支、不消费它。若撤销时不清 onceGranted，撤销后状态就成了 authorized-once，
- * 下一次点击仍会静默放行 —— 人以为已经收干净了。
+ * 热键调用，也是 persistent 唯一的入口与出口：
+ * persistent 中 → 撤销回 unauthorized；其余状态 → 进入 persistent（清 pending）。
  */
 export function togglePersistent(source = 'hotkey') {
   const previousState = getStatus().state
   if (state.persistent) {
     state.persistent = false
-    state.onceGranted = false
     clearPending({ code: 'AUTH_CANCELLED', reason: '热键撤销' })
   } else {
     state.persistent = true
-    state.onceGranted = false
     clearPending({ code: 'AUTH_CANCELLED', reason: '热键接管' })
   }
+  state.epoch += 1
   audit('togglePersistent', source, previousState)
   return getStatus()
 }
 
 /**
- * 消费一次放行。持续授权下放行且不改变状态；单次授权放行即清空。
- * 返回 { allowed, mode?, reason? }。
+ * 系统侧的强制回收：EventTap 失效时调用，无条件回到 unauthorized。
+ * 与 togglePersistent 的区别是它只会撤销、不会开启；pending 一并清掉，
+ * 因为这个状态机已经没有可信的人类急停通道了（fail-closed）。
  */
-export function consumeOnce() {
+export function revokeAll(reason = 'system') {
   const previousState = getStatus().state
-  if (state.persistent) {
-    audit('consumeOnce', 'tool', previousState, { allowed: true, mode: 'persistent' })
-    return { allowed: true, mode: 'persistent' }
-  }
-  if (state.onceGranted) {
-    state.onceGranted = false
-    audit('consumeOnce', 'tool', previousState, { allowed: true, mode: 'once' })
-    return { allowed: true, mode: 'once' }
-  }
-  audit('consumeOnce', 'tool', previousState, {
-    allowed: false,
-    reason: state.pendingRequest !== null ? '授权请求待确认' : '未授权',
-  })
-  return {
-    allowed: false,
-    reason: state.pendingRequest !== null ? '授权请求待确认' : '未授权',
-  }
+  state.persistent = false
+  clearPending({ code: 'AUTH_CANCELLED', reason })
+  state.epoch += 1
+  audit('revokeAll', 'system', previousState, { reason })
+  return getStatus()
 }
 
-/** vp_click 的放行判断（不消费）。 */
+/** 当前放行态的代数（见 state.epoch 的注释）。 */
+export function getAuthEpoch() {
+  return state.epoch
+}
+
+/**
+ * 鼠标与键盘共用的放行判断（不消费、不改状态）。
+ * 键盘不再有独立通道：persistent 下鼠标与键盘一律放行。
+ */
 export function checkCanClick() {
   if (state.persistent) {
     return { allowed: true, reason: '持续授权有效' }
   }
-  if (state.onceGranted) {
-    return { allowed: true, reason: '单次授权待使用' }
-  }
   if (state.pendingRequest !== null) {
     return { allowed: false, reason: '授权请求待确认' }
   }
@@ -182,19 +180,15 @@ export function checkCanClick() {
 /** 测试专用：重置为未授权。 */
 export function _resetForTests() {
   state.persistent = false
-  state.onceGranted = false
   clearPending({ code: 'AUTH_CANCELLED', reason: '测试重置' })
   state.requestSeq = 0
+  state.epoch += 1
 }
 
-/**
- * 测试专用：读内部标志位。persistent 期间 onceGranted 是否还挂着，
- * getStatus() 看不出来（persistent 优先返回 'persistent'），只能从这里取证。
- */
+/** 测试专用：读内部标志位（getStatus 看不到 persistent 期间挂着的 pending 详情之外的东西）。 */
 export function _peekForTests() {
   return {
     persistent: state.persistent,
-    onceGranted: state.onceGranted,
     hasPending: state.pendingRequest !== null,
   }
 }

package/src/diff.js

@@ -14,7 +14,7 @@ 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, resolveGridScale } from './render.js'
 
@@ -186,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/hotkey.js

@@ -1,17 +1,60 @@
 // 全局热键：Shift+Space → togglePersistent()。
 // robot-ts 没有 hotkey API，但 EventTap 能全局捕获键盘事件（非管理员可用）。
 // 生命周期由 index.js 的 ctx.effect 负责 dispose —— 这是长驻资源，不随单次工具调用结束。
+//
+// Fail-Closed：热键是 persistent 唯一的人类急停通道。监听器一旦失效（线程退出、系统卸载、
+// 会话被回收），必须立刻通知宿主把授权强制收回 unauthorized，而不是留着一个按不动的持续授权。
+// 心跳只能看见绑定暴露的状态（isEventTapRunning）；Windows 静默摘钩但消息循环仍在跑的
+// 情况在该 API 下不可观测，见 README「已知限制」。
 
 import { loadRobotTs } from './robot-ts.js'
 
-export async function startHotkey({ onToggle }) {
+export const DEFAULT_HEALTH_CHECK_INTERVAL_MS = 2000
+
+export async function startHotkey({
+  onToggle,
+  onUnavailable,
+  healthCheckIntervalMs = DEFAULT_HEALTH_CHECK_INTERVAL_MS,
+  // 依赖注入点：生产用真实 robot-ts，回归测试用假 Session 驱动心跳。
+  load = loadRobotTs,
+} = {}) {
   let session
+  let disposed = false
+  let failed = false
+  let timer
+
+  const stopHealthCheck = () => {
+    if (timer !== undefined) {
+      clearInterval(timer)
+      timer = undefined
+    }
+  }
+
+  const shutdown = async () => {
+    stopHealthCheck()
+    try { await session?.eventTap.stop() } catch { /* already stopped */ }
+    try { await session?.dispose() } catch { /* already disposed */ }
+  }
+
+  // 只通知一次：心跳与 dispose 可能同时到达，重复 revokeAll 会污染审计。
+  const markUnavailable = (reason) => {
+    if (failed || disposed) return
+    failed = true
+    stopHealthCheck()
+    try {
+      onUnavailable?.(reason)
+    } catch {
+      // 回调是 fail-closed 的通知通道，它自己出错也不能让钩子线程崩。
+    }
+    void shutdown()
+  }
+
   try {
-    const { Session, Key } = loadRobotTs()
+    const { Session, Key } = load()
     session = await Session.create()
 
     if (!session.eventTap.isSupported) {
-      await session.dispose()
+      await shutdown()
       return { available: false, error: '当前环境不支持 EventTap 全局键盘捕获', dispose: async () => {} }
     }
 
@@ -20,41 +63,62 @@ export async function startHotkey({ onToggle }) {
 
     // KeyInputEvent 只有 { type, key, down }，native 绑定的属性名里也没有任何注入标记，
     // 所以这里无法过滤合成按键 —— 见 README「安全边界」。
-
     await session.eventTap.start((event) => {
-      if (event.type !== 'key') return
-      if (event.key === Key.LeftShift || event.key === Key.RightShift) {
-        shiftHeld = event.down
-        return
-      }
-      if (event.key !== Key.Space) return
-      const wasDown = spaceHeld
-      spaceHeld = event.down
-      // 只在 Space 的按下沿触发，避免按住时的键盘重复把授权反复开关。
-      if (event.down && !wasDown && shiftHeld) {
-        try {
+      try {
+        if (event.type !== 'key') return
+        if (event.key === Key.LeftShift || event.key === Key.RightShift) {
+          shiftHeld = event.down
+          return
+        }
+        if (event.key !== Key.Space) return
+        const wasDown = spaceHeld
+        spaceHeld = event.down
+        // 只在 Space 的按下沿触发，避免按住时的键盘重复把授权反复开关。
+        if (event.down && !wasDown && shiftHeld) {
           onToggle()
-        } catch {
-          // 热键回调运行在原生钩子路径上，异常绝不能外抛。
         }
+      } catch {
+        // 热键回调运行在原生钩子路径上，异常绝不能外抛。
       }
     })
 
+    // 心跳：定时问绑定「钩子线程还活着吗」。start 成功后再装，避免把启动期误判成失效。
+    // healthCheckIntervalMs <= 0 表示关闭（保留给需要零后台定时的宿主）。
+    if (healthCheckIntervalMs > 0) {
+      timer = setInterval(() => {
+        let running
+        try {
+          running = session.eventTap.isRunning
+        } catch (error) {
+          markUnavailable(
+            `EventTap 心跳检查失败：${error instanceof Error ? error.message : String(error)}，已强制撤销全部授权`,
+          )
+          return
+        }
+        if (!running) {
+          markUnavailable('EventTap 已停止：全局钩子失效，已强制撤销全部授权')
+        }
+      }, healthCheckIntervalMs)
+      timer.unref?.()
+    }
+
     return {
       available: true,
       error: undefined,
+      healthCheckIntervalMs,
       dispose: async () => {
-        try { await session.eventTap.stop() } catch { /* already stopped */ }
-        try { await session.dispose() } catch { /* already disposed */ }
+        if (disposed) return
+        disposed = true
+        await shutdown()
       },
     }
   } catch (error) {
-    if (session !== undefined) {
-      try { await session.dispose() } catch { /* already disposed */ }
-    }
+    await shutdown()
+    const message = error instanceof Error ? error.message : String(error)
+    markUnavailable(`EventTap 启动失败：${message}，已强制撤销全部授权`)
     return {
       available: false,
-      error: error instanceof Error ? error.message : String(error),
+      error: message,
       dispose: async () => {},
     }
   }

package/src/index.js

@@ -11,7 +11,7 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { createPlugin } from './plugin.js'
 import { startHotkey } from './hotkey.js'
-import { togglePersistent } from './auth.js'
+import { togglePersistent, revokeAll } from './auth.js'
 import { cleanupVisualFragments } from './paths.js'
 
 export const name = 'dsh-copilot-vision'
@@ -30,6 +30,12 @@ export function apply(ctx) {
       onToggle: () => {
         togglePersistent()
       },
+      // 急停通道失效 = 不能继续相信 persistent：先摘掉热键可用标记，再强制回 unauthorized。
+      onUnavailable: (reason) => {
+        hotkeyState.available = false
+        hotkeyState.error = reason
+        revokeAll('eventtap')
+      },
     }).then((started) => {
       hotkeyState.available = started.available
       hotkeyState.error = started.error

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
+}