dsh-copilot-vision 1.3.1 → 1.3.2

package/README.md

@@ -18,6 +18,9 @@ V1.3 起授权只有三态：`unauthorized` / `pending-persistent` / `persistent
 
 - **进入授权**：按 Shift+Space 直接进入持续授权；或模型调 `vp_request_auth(mode='persistent')`，你在问答卡片上确认一次。
 - **急停**：任何时候再按一次 Shift+Space，立即回到 `unauthorized`。这是物理热键，不经过模型、不依赖宿主 UI。
+- **热键失效即收权（Fail-Closed）**：热键是急停的唯一通道，它一旦失效就不能继续留着持续授权。EventTap 启动失败、监听线程退出、心跳（默认每 2 秒）发现钩子不再活跃，都会立刻把状态强制收回 `unauthorized` 并写一条 `revokeAll` 审计；不会出现「授权还在、却按不动撤销」的状态。
+- **撤销与注入竞态**：每个动作在放行时记下授权代数，真正调用 robot-ts 前再用微任务同步复核一次。人按撤销的瞬间，正在飞的这一下最多落到「已执行的移动」为止，后续注入立即中止；已经排队的其他动作一并作废。
+- **等待可被打断**：`vp_wait_change` 轮询期间一旦授权被撤销，立刻抛「授权已被撤销，等待中断」，不会空等到超时。
 - **未授权即拦截**：`vp_click` / `vp_click_relative` / `vp_type` / `vp_key` 在未授权时直接抛错并提示人类开启持续授权，不会自己弹卡片。
 - **审计**：JSON Lines 记录每次授权迁移，以及每次注入的放行/拒绝（`actionAllowed` / `actionDenied`），只记动作与工具名，不记任何按键内容。
 
@@ -100,7 +103,7 @@ DSH_HOME=<DSH_HOME> dsh plugin --profile web add dsh-copilot-vision
 
 # 或从本地 tarball 安装（开发调试）
 npm pack
-DSH_HOME=<DSH_HOME> dsh plugin --profile web add file:<绝对路径>/dsh-copilot-vision-1.3.1.tgz
+DSH_HOME=<DSH_HOME> dsh plugin --profile web add file:<绝对路径>/dsh-copilot-vision-1.3.2.tgz
 ```
 
 - **宿主**：web（问答卡片授权）/ headless（无 UI 答者，只能 Shift+Space，需真人在场）/ desktop（待 DSH 市场审核后内置验证）。
@@ -116,6 +119,8 @@ DSH_HOME=<DSH_HOME> dsh plugin --profile web add file:<绝对路径>/dsh-copilot
 - **聊天窗口自干扰**：宿主聊天窗口的流式重绘会被当成屏幕变化（实测覆盖率约为变化门限的 14 倍）。等页面加载时，先把聊天窗口移出主屏或最小化。
 - **鼠标移动不可检测**：Windows 屏幕捕获不含硬件光标，挪鼠标不产生任何像素变化。
 - **热键无法区分真人与合成按键**：按键事件流不携带注入标记，审计日志只作事后追溯、不作防伪。真正的护栏在插件之外——宿主安全分类器与操作纪律。
+- **静默摘钩不可观测**：心跳只能读到 robot-ts 暴露的「监听线程是否存活」。Windows 若在消息循环仍在跑的情况下静默卸掉低层钩子，绑定层看不到；此时心跳无法判定失效。插件启动失败与线程退出这两条路径已按 Fail-Closed 处理。
+- **无热键时的残余风险**：EventTap 启动即不可用时，插件不会自动收权（启动状态本就是 `unauthorized`），但人仍可通过 `vp_request_auth` 卡片确认进入 `persistent`——此时没有物理急停通道。是否放行由人在卡片上判断；本轮未禁止该路径。
 - **索引并发**：截图索引整份覆盖写、不做跨进程并发保护，多进程共用 `VP_SHOT_DIR` 会互相覆盖；回归测试一律用独立目录。
 - **临时目录卫生**：超过 3 天的差分/网格切片（`vp-diff-*` / `vp-grid-*`）会在插件启动时被自动清理；模型在收工时调用 `vp_summarize` 会把关键截图归档到 `archives/` 并清空其余全部碎片。基准截图（`vp-shot-*`）、审计日志、索引与 `archives/` 永久保留。
 
@@ -124,7 +129,8 @@ DSH_HOME=<DSH_HOME> dsh plugin --profile web add file:<绝对路径>/dsh-copilot
 > 以下脚本为开发期本机验证用，含本机绝对路径，**不随仓库与 npm 包分发**（`.gitignore` 已排除 `test-*.mjs`）。克隆仓库后需自备对应脚本。
 
 ```bash
-node test-mvp.mjs        # 三态授权 + 热键急停/接管 + 无时钟衰减（约 45s，真实点击屏幕中心）
+node test-hotkey.mjs     # 热键 Fail-Closed：触发沿、心跳失效/抛错、启动失败、dispose 幂等（全假 Session）
+node test-mvp.mjs        # 三态授权 + 热键急停/接管 + 撤销竞态 + 等待中断 + 无时钟衰减（约 45s，真实点击屏幕中心）
 node test-diff.mjs       # 差分与索引（单元层不碰屏幕；--integration 需配合动屏）
 node test-relative.mjs   # 网格渲染 + 相对坐标换算 + 未授权闸门（不截图、不注入）
 node test-wait.mjs       # 轮询语义（--integration 配合静屏/动屏/假基线）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-copilot-vision",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "Computer Use enhancement plugin for DeepSeek Harness (DSH). 纯 JS 视觉差分、网格位置编码、键盘注入、语义级记忆压缩、长程任务闭环与人机共驾授权。",
   "main": "./src/index.js",
   "scripts": {

package/src/actions.js

@@ -7,7 +7,7 @@ import { join } from 'node:path'
 import { physicalToLogical, relativeToPhysical } from './coords.js'
 import { parseKeySpec, resolveUnicodeChar } from './keys.js'
 import { loadRobotTs } from './robot-ts.js'
-import { checkCanClick, getStatus } from './auth.js'
+import { checkCanClick, getAuthEpoch, getStatus } from './auth.js'
 import { logState } from './audit.js'
 import { resolveShotsDir } from './paths.js'
 import { get, nextShotId, record } from './shot-index.js'
@@ -77,9 +77,29 @@ function denyInjection(tool, gate, extra = {}) {
 }
 
 /** 放行注入后记一笔；不改变授权状态，只留「这一次真的注入了」的证据。 */
-function allowInjection(tool, extra = {}) {
+function allowInjection(tool, extra = {}, grantedState = getStatus().state) {
+  logState('actionAllowed', 'tool', grantedState, getStatus().state, { tool, ...extra })
+}
+
+/** 放行快照：决策时的授权代数与状态，注入前用它做最后一次同步复核。 */
+function captureGrant(tool) {
+  const gate = checkCanClick()
+  if (!gate.allowed) denyInjection(tool, gate)
+  return { epoch: getAuthEpoch(), state: getStatus().state }
+}
+
+/**
+ * 注入前的最后闸门。动作在放行之后还要建会话、取显示器、换算坐标，这期间人可能已经
+ * 按了 Shift+Space。先让出一个微任务，给已排队的撤销回调落地；再做同步复核。
+ * 复核通过到 native 调用之间没有 await，JS 单线程保证不会再有授权翻转插进来。
+ * 用 epoch 而不是只看 allowed：撤销后又立刻授权也算翻转，旧动作不得继续飞。
+ */
+async function assertGrantStillValid(tool, grant) {
+  await Promise.resolve()
+  if (checkCanClick().allowed && getAuthEpoch() === grant.epoch) return
   const state = getStatus().state
-  logState('actionAllowed', 'tool', state, state, { tool, ...extra })
+  logState('actionDenied', 'tool', state, state, { tool, reason: '授权已被撤销' })
+  throw new Error(`授权已被撤销，动作已中止（${tool}）`)
 }
 
 /**
@@ -95,6 +115,7 @@ export async function clickAction(args = {}) {
     denyInjection('vp_click', gate,
       Number.isFinite(x) && Number.isFinite(y) ? { physical: { x, y } } : {})
   }
+  const grant = { epoch: getAuthEpoch(), state: getStatus().state }
   const { button = 'left' } = args
 
   if (!Number.isFinite(x) || !Number.isFinite(y)) {
@@ -104,11 +125,11 @@ export async function clickAction(args = {}) {
     throw new Error(`vp_click: 坐标不能为负数，收到 x=${x}, y=${y}`)
   }
 
-  return await injectClick({ x, y, button, thought: args.thought, tool: 'vp_click' })
+  return await injectClick({ x, y, button, thought: args.thought, tool: 'vp_click', grant })
 }
 
 /** 真实注入的共用实现：参数校验、越界检查、换算逻辑坐标、移动并点击。 */
-async function injectClick({ x, y, button = 'left', thought, tool }) {
+async function injectClick({ x, y, button = 'left', thought, tool, grant }) {
   const { Session, MouseButton } = loadRobotTs()
   const buttons = {
     left: MouseButton.Left,
@@ -135,9 +156,12 @@ async function injectClick({ x, y, button = 'left', thought, tool }) {
     }
 
     const logical = physicalToLogical({ x, y }, primary.scaleFactor)
+    await assertGrantStillValid(tool, grant)
     await session.mouse.move(logical)
+    // 移动本身已是一次注入；点击前再复核一次，撤销发生在 move 期间就停在这里。
+    await assertGrantStillValid(tool, grant)
     await session.mouse.click(buttons[button])
-    allowInjection(tool, { physical: { x, y }, button })
+    allowInjection(tool, { physical: { x, y }, button }, grant.state)
 
     return {
       thought: normalizeThought(thought, `点击屏幕物理坐标 (${x}, ${y})`),
@@ -158,10 +182,7 @@ async function injectClick({ x, y, button = 'left', thought, tool }) {
  * V1.3 取消了键盘独立通道——单次确认卡片会把焦点抢回 DSH，注入反而落错窗口。
  */
 export async function typeAction(args = {}) {
-  const gate = checkCanClick()
-  if (!gate.allowed) {
-    denyInjection('vp_type', gate)
-  }
+  const grant = captureGrant('vp_type')
 
   const { text } = args
   if (typeof text !== 'string' || text.length === 0) {
@@ -179,8 +200,9 @@ export async function typeAction(args = {}) {
     }
     // robot-ts 的 typeText 走 KEYEVENTF_UNICODE 直接注入码点，与键盘布局无关，
     // 中文/emoji 都能原样打出来，不需要剪贴板中转。
+    await assertGrantStillValid('vp_type', grant)
     await session.keyboard.typeText(text)
-    allowInjection('vp_type', { chars: text.length })
+    allowInjection('vp_type', { chars: text.length }, grant.state)
     return {
       typed: text,
       method: 'unicode',
@@ -215,10 +237,7 @@ export function describeKeySpec(key) {
  *     这样组合键语义是真的（Ctrl+V 实测能粘上），space 也能激活聚焦的按钮。
  */
 export async function keyAction(args = {}) {
-  const gate = checkCanClick()
-  if (!gate.allowed) {
-    denyInjection('vp_key', gate)
-  }
+  const grant = captureGrant('vp_key')
 
   const { key } = args
   const { Session, Key, Modifier } = loadRobotTs()
@@ -236,12 +255,13 @@ export async function keyAction(args = {}) {
     if (unicodeChar !== null && !session.capabilities.canTypeUnicode) {
       throw new Error('当前宿主环境不支持 Unicode 文本注入（canTypeUnicode=false）')
     }
+    await assertGrantStillValid('vp_key', grant)
     if (unicodeChar !== null) {
       await session.keyboard.typeChar(unicodeChar.codePointAt(0))
     } else {
       await session.keyboard.tap(spec.code, spec.modifiers)
     }
-    allowInjection('vp_key', { key: spec.spec })
+    allowInjection('vp_key', { key: spec.spec }, grant.state)
     return {
       key: spec.spec,
       keyName: spec.keyName,
@@ -288,10 +308,7 @@ export function resolveRelativeTarget({ shotId, index, xPercent, yPercent }) {
  * 授权 → 参数合法性 → 越界 → 注入，所以未授权时不会读索引、不会新建 robot-ts 会话。
  */
 export async function clickRelativeAction(args = {}) {
-  const gate = checkCanClick()
-  if (!gate.allowed) {
-    denyInjection('vp_click_relative', gate)
-  }
+  const grant = captureGrant('vp_click_relative')
 
   const { shotId, index, xPercent, yPercent, button = 'left' } = args
   const { bbox, physical } = resolveRelativeTarget({ shotId, index, xPercent, yPercent })
@@ -301,6 +318,7 @@ export async function clickRelativeAction(args = {}) {
     button,
     thought: args.thought,
     tool: 'vp_click_relative',
+    grant,
   })
   return {
     thought: clicked.thought,

package/src/audit.js

@@ -14,6 +14,7 @@ export const AUDIT_ACTIONS = [
   'confirmPending',
   'cancelPending',
   'togglePersistent',
+  'revokeAll',
   'actionAllowed',
   'actionDenied',
 ]

package/src/auth.js

@@ -28,6 +28,9 @@ const state = {
   /** @type {{requestId: string, mode: 'persistent', requestedAt: number, controller: AbortController} | null} */
   pendingRequest: null,
   requestSeq: 0,
+  // 放行态的代数：每次 persistent 翻转 +1。动作在 checkCanClick() 放行时记下它，
+  // 注入前再比一次——即使中途「撤销又立刻授权」，旧动作也不会带着旧授权继续飞。
+  epoch: 0,
 }
 
 /** 当前授权状态（只读快照，不含内部的 AbortController）。 */
@@ -109,6 +112,7 @@ export function confirmPending(requestId) {
   const previousState = getStatus().state
   state.pendingRequest = null
   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 }
@@ -135,10 +139,30 @@ export function togglePersistent(source = 'hotkey') {
     state.persistent = true
     clearPending({ code: 'AUTH_CANCELLED', reason: '热键接管' })
   }
+  state.epoch += 1
   audit('togglePersistent', source, previousState)
   return getStatus()
 }
 
+/**
+ * 系统侧的强制回收：EventTap 失效时调用，无条件回到 unauthorized。
+ * 与 togglePersistent 的区别是它只会撤销、不会开启；pending 一并清掉，
+ * 因为这个状态机已经没有可信的人类急停通道了（fail-closed）。
+ */
+export function revokeAll(reason = 'system') {
+  const previousState = getStatus().state
+  state.persistent = false
+  clearPending({ code: 'AUTH_CANCELLED', reason })
+  state.epoch += 1
+  audit('revokeAll', 'system', previousState, { reason })
+  return getStatus()
+}
+
+/** 当前放行态的代数（见 state.epoch 的注释）。 */
+export function getAuthEpoch() {
+  return state.epoch
+}
+
 /**
  * 鼠标与键盘共用的放行判断（不消费、不改状态）。
  * 键盘不再有独立通道：persistent 下鼠标与键盘一律放行。
@@ -158,6 +182,7 @@ export function _resetForTests() {
   state.persistent = false
   clearPending({ code: 'AUTH_CANCELLED', reason: '测试重置' })
   state.requestSeq = 0
+  state.epoch += 1
 }
 
 /** 测试专用：读内部标志位（getStatus 看不到 persistent 期间挂着的 pending 详情之外的东西）。 */

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/wait.js

@@ -14,6 +14,7 @@ import { PNG } from 'pngjs'
 import pixelmatch from 'pixelmatch'
 import { loadRobotTs } from './robot-ts.js'
 import { get, assertShotFileExists } from './shot-index.js'
+import { checkCanClick, getAuthEpoch } from './auth.js'
 import { screenshotAction } from './actions.js'
 import { diffPair, connectedComponents, DEFAULT_MIN_REGION_AREA } from './diff.js'
 
@@ -75,6 +76,19 @@ export async function waitChangeAction({
   assertShotFileExists(baseline, baselineMeta, 'vp_wait_change')
   const baselineImg = readPng(baselineMeta.path)
 
+  // 等待本身不要求授权；只有「带着持久授权开始等」的调用会被撤销打断。
+  // 记在会话创建之前，这样建会话期间发生的撤销在第一次轮询时就能发现。
+  const startedAllowed = checkCanClick().allowed
+  const startedEpoch = getAuthEpoch()
+  const assertWaitGrant = async () => {
+    if (!startedAllowed) return
+    // 让排队的撤销回调先落地，再同步复核；epoch 变化（含撤销后立刻重授权）一律中断。
+    await Promise.resolve()
+    if (!checkCanClick().allowed || getAuthEpoch() !== startedEpoch) {
+      throw new Error('授权已被撤销，等待中断')
+    }
+  }
+
   const { Session } = loadRobotTs()
   const session = await Session.create()
   const startedAt = Date.now()
@@ -106,6 +120,7 @@ export async function waitChangeAction({
     const mask = new Uint8Array(pixels)
 
     for (;;) {
+      await assertWaitGrant()
       const tickStartedAt = Date.now()
       const frame = await session.screen.captureMonitor(primary.id)
       const current = frame.toBuffer()
@@ -123,6 +138,8 @@ export async function waitChangeAction({
       }
       // 已经开始的这一帧一定跑完，所以超时路径上的 waitedMs 必然 >= timeoutMs。
       if (waitedMs >= timeoutMs) break
+      // 睡之前再查一次：把「撤销 → 醒来才发现」的延迟压到一帧以内。
+      await assertWaitGrant()
       await sleep(Math.max(0, pollIntervalMs - (Date.now() - tickStartedAt)))
     }
   } finally {