dsh-copilot-vision 1.0.0 → 1.3.1

package/README.md

@@ -6,23 +6,30 @@
 
 ### 双轨执行
 
-本地轨道经 robot-ts 直连 Windows（屏幕捕获 + 鼠标注入 + 低层键盘钩子）；`src/vp-ssh-core.js` 预留远程轨道接口。当前发版只启用本地轨道，远程不注册任何工具——接口在那里，能力按需放开。
+本地轨道经 robot-ts 直连 Windows（屏幕捕获 + 鼠标注入 + 键盘注入 + 低层键盘钩子）；`src/vp-ssh-core.js` 预留远程轨道接口。当前发版只启用本地轨道，远程不注册任何工具——接口在那里，能力按需放开。
 
 ### 动态视觉感知：不传全屏，传差分
 
-`vp_screenshot_diff` 用 pixelmatch 逐像素比对，4 邻域连通块合并，小于 100 像素的噪声（光标、闪烁）直接丢弃，把「哪里变了」而不是「整屏是什么」交还给模型。`vp_wait_change` 更进一步：每 100ms 在内存里截屏比对，**轮询期零落盘**，变化出现的瞬间才落一张正式截图。「等页面加载」从反复截图碰运气，变成一次有明确语义的等待。换显示器或改缩放后坐标即不可信——宽高或 scaleFactor 不一致直接报错，绝不重采样硬算。
+`vp_screenshot_diff` 用 pixelmatch 逐像素比对，4 邻域连通块合并，小于 100 像素的噪声（光标、闪烁）直接丢弃，把「哪里变了」而不是「整屏是什么」交还给模型。`vp_wait_change` 更进一步：每 100ms 在内存里截屏比对，**轮询期零落盘**，变化出现的瞬间才落一张正式截图。「等页面加载」从反复截图碰运气，变成一次有明确语义的等待。换显示器或改缩放后坐标即不可信——宽高或 scaleFactor 不一致直接报错，绝不重采样硬算。网格放大图不再固定 4 倍：按区域面积自适应倍率——≤50,000 物理像素 4x、≤200,000 2x、更大 1x 只画网格，大区域不再产出巨图；同时以「放大后单边 ≤2,000 像素」兜底，4,344×4 这类细长条不会被放大成 17,376 宽的畸形长图。每个区域以 `gridScale` 字段标明实际倍数。`coverage` 只是变色像素的比例，白底同类元素位移时可能仅 2% 却已改天换地——判断变化要看 `regions` 与 `gridPath` 的实际内容，不能只看覆盖率。上下文策略同样内置在工具 description 里（「长程上下文纪律」）：旧图会被清理、历史路径随时可能失效，模型必须以最新一次观察为准，偏离预期就直接重新截图，不翻历史记录。
 
-### 人机共驾安全
+### 人机共驾安全：持续授权 + 物理热键急停
 
-授权是一个五态状态机（unauthorized / pending-once / authorized-once / pending-persistent / persistent），铁律：**授权只由人的动作进入和撤销，不由时钟改变**——没有到期时间，没有剩余毫秒，持续授权等再久都不失效（回归测试用 35 秒等待证明这一点）。人有三条通道：问答卡片上点「允许」、Shift+Space 热键随时接管或撤销、JSON Lines 审计日志事后追溯（只记状态机动作与来源，不记任何按键内容）。点击闸门顺序是授权 → 参数 → 越界 → 消费，失败路径不浪费单次授权。
+V1.3 起授权只有三态：`unauthorized` / `pending-persistent` / `persistent`。铁律：**授权只由人的动作进入和撤销，不由时钟改变**——没有到期时间，没有剩余毫秒，持续授权等再久都不失效（回归测试用 35 秒等待证明这一点）。
+
+- **进入授权**：按 Shift+Space 直接进入持续授权；或模型调 `vp_request_auth(mode='persistent')`，你在问答卡片上确认一次。
+- **急停**：任何时候再按一次 Shift+Space，立即回到 `unauthorized`。这是物理热键，不经过模型、不依赖宿主 UI。
+- **未授权即拦截**：`vp_click` / `vp_click_relative` / `vp_type` / `vp_key` 在未授权时直接抛错并提示人类开启持续授权，不会自己弹卡片。
+- **审计**：JSON Lines 记录每次授权迁移，以及每次注入的放行/拒绝（`actionAllowed` / `actionDenied`），只记动作与工具名，不记任何按键内容。
+
+为什么取消单次授权：V1.2.2 实测发现，点卡片上的「允许」会把焦点抢回 DSH 窗口，紧接着的注入就落进错误窗口。V1.3 让键盘与鼠标共用持续授权，注入前不再有任何焦点跳转。
 
 <!-- 配图位 1：授权问答卡片截图（宿主内 vp_request_auth 弹出的人类确认卡片） -->
 
 ### 位置编码注入
 
-大模型在原尺寸小图上数错行、估偏上百像素是常态。Vision-Pilot 把坐标计算交还给代码：每个差分区域附一张 `gridPath` 放大图——4x 最近邻放大，每 20 物理像素一条半透明红线，网格原点就是区域左上角（pngjs + 手写 Bresenham，零新增依赖）。模型只负责数格子、报百分比，`vp_click_relative` 完成精确换算。实测：模型按网格估点落进文字区，误差 ≤ 2.5px；同一场景靠肉眼估坐标偏过 111px。
+大模型在原尺寸小图上数错行、估偏上百像素是常态。Vision-Pilot 把坐标计算交还给代码：每个差分区域附一张 `gridPath` 放大图——按区域面积与单边长度自适应倍率（4x / 2x / 1x，放大后单边 ≤2,000 像素）的最近邻放大，每 20 物理像素一条半透明红线，网格原点就是区域左上角（pngjs + 手写 Bresenham，零新增依赖）。模型只负责数格子、报百分比，`vp_click_relative` 完成精确换算。实测：模型按网格估点落进文字区，误差 ≤ 2.5px；同一场景靠肉眼估坐标偏过 111px。
 
-<!-- 配图位 2：vp-grid-*.png 网格放大图示例（4x，红线每格 = 20 物理像素） -->
+<!-- 配图位 2：vp-grid-*.png 网格放大图示例（自适应倍率 4x/2x/1x 且单边 ≤2,000 像素，红线每格 = 20 物理像素） -->
 
 ## 工具集
 
@@ -31,14 +38,50 @@
 | `vp_screenshot` | 截主屏全屏，返回 `shotId`——后续一切操作的句柄。 |
 | `vp_screenshot_diff` | 与历史截图逐像素差分，输出差异区域 + 网格放大图。 |
 | `vp_wait_change` | 高频轮询等待屏幕变化，变化即返回；超时不消耗 shotId。 |
-| `vp_click` | 按绝对物理坐标点击（内部换算逻辑坐标，需已授权）。 |
-| `vp_click_relative` | 在差分区域的网格图内按相对百分比点击（需已授权）。 |
-| `vp_request_auth` | 请求人类授权（once / persistent），经宿主问答卡片等待确认。 |
+| `vp_click` | 按绝对物理坐标点击（内部换算逻辑坐标，需持续授权）。 |
+| `vp_click_relative` | 在差分区域的网格图内按相对百分比点击（需持续授权）。 |
+| `vp_type` | 在当前焦点输入一段文本（Unicode 直注，中英文通吃；**绝不自动回车**；需持续授权）。 |
+| `vp_key` | 发送一次按键或组合键（enter / tab / esc / ctrl+c）；**回车只能由它触发**；需持续授权。 |
+| `vp_request_auth` | 请求人类开启持续授权（仅 `mode='persistent'`），经宿主问答卡片等待确认。 |
 | `vp_auth_status` | 只读查询授权状态、热键可用性与审计日志路径。 |
+| `vp_summarize` | **收工必调**：归档关键截图、写入总结，清空其余全部临时碎片。 |
+
+## 语义级记忆压缩（vp_summarize）
+
+临时图会跨会话堆积。`vp_summarize` 让模型在**一个任务周期结束、准备收工或切换任务时**主动做一次收尾：
+
+1. `keepShotIds` 里的关键截图（例如「初始页」和「结果页」）被移进 `archives/` 子目录，索引路径同步更新——归档后仍然可以做差分回看；
+2. `summary` 连同本次保留清单追加写入 `archive-summary.txt`；
+3. 当前目录下其余所有 `vp-shot-*`、`vp-diff-*`、`vp-grid-*` 立即删除，返回各类碎片数量。
+
+**保护区**：`audit.log`（证据链）、`shot-index.json`（shotId 播种与相对点击依赖）、`archives/`（冷存储，一次归档永久保留）永远不会被删除。被清理掉的 shotId 在索引里保留条目，避免 `nextShotId` 回退导致旧 shotId 静默指向新截图；此时对它们做差分/等待会得到「文件已被 vp_summarize 清理，请重新截图」的明确错误。
+
+与 `paths.js` 里的 `cleanupVisualFragments`（启动时删 3 天前的 diff/grid）**不冲突**：那个是按时间的兜底，只碰 diff/grid；本工具是按语义的主清理，目标集合是它的超集。
+
+## 键盘注入：与鼠标共用持续授权
+
+键盘能力分两个工具：`vp_type` 负责输入文本，`vp_key` 负责发送按键与组合键。V1.3 起键盘不再有独立的逐次确认通道，规则只有三条：
+
+1. **键盘与鼠标共用 `checkCanClick()`**——`persistent` 下两者一律直接放行，`unauthorized` 下一律直接拦截。注入前不再弹卡片，因此不会出现「点允许 → 焦点跳回 DSH → 注入落错窗口」。
+2. **`vp_type` 绝不自动发送 Enter**——回车只能由 `vp_key` 单独触发，且必须在 `vp_key` 的 `thought` 里说明意图。
+3. **每个动作工具都要写旁白**——`vp_click` / `vp_click_relative` / `vp_type` / `vp_key` 都带必填的 `thought` 参数，用一句自然语言说明当前动作，原样回显在返回 JSON 里，作为给人看的进度旁白。
+
+### 输入法（IME）实测结论
+
+robot-ts 有两条注入通道，本插件按键的性质分流：
+
+| 通道 | 底层 | 适用 |
+|---|---|---|
+| Unicode 直注 | `KEYEVENTF_UNICODE` | 文本字符，绕开键盘布局与输入法 |
+| 真实扫描码 | `KEYEVENTF_SCANCODE` | 控制键与组合键，保留真实按键语义 |
+
+本机中文输入法（WeType）实测会**吞掉扫描码注入的字母键**：按下不落字，要到下一次 Enter 才吐出幽灵字符；还会把引号改写成中文弯引号。因此 `vp_key` 对「无修饰键的字符键（字母/数字/符号）」改走 Unicode 直注——`vp_key "a"` 会立刻落下 `a`，不会留下幽灵文本。控制键（enter / esc / tab / 方向键 / backspace / delete / f1-f12）、空格、以及任何带 ctrl / alt / meta 的组合键走真实扫描码：实测 Ctrl 修饰键确实送达（Ctrl+V 能粘上内容），Shift+End 能选出整段。返回值里的 `method` 字段会告诉你这次走的是哪条通道。
+
+注意：如果用户正在用输入法打字，组合串还挂在输入法里，此时 `vp_key enter` 会把它一起提交出去。
 
 ## 长程任务工作流（The OSA V Loop）
 
-这段协议内嵌在全部 7 个工具的 description 里，模型每次调用都会被提醒：
+这段协议内嵌在全部 10 个工具的 description 里，模型每次调用都会被提醒：
 
 1. **观察 Observe**——每步开始前，用截图或差分确认当前屏幕状态。
 2. **行动 Act**——点击目标（绝对坐标或相对百分比）。
@@ -57,33 +100,36 @@ 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.0.0.tgz
+DSH_HOME=<DSH_HOME> dsh plugin --profile web add file:<绝对路径>/dsh-copilot-vision-1.3.1.tgz
 ```
 
 - **宿主**：web（问答卡片授权）/ headless（无 UI 答者，只能 Shift+Space，需真人在场）/ desktop（待 DSH 市场审核后内置验证）。
-- **授权**：模型调 `vp_request_auth`，你在卡片上确认；或随时 Shift+Space 进入持续授权、再按撤销。
+- **授权**：按 Shift+Space 开启或撤销持续授权；模型也可调 `vp_request_auth(mode='persistent')` 请求，你在卡片上确认一次。单次授权已取消。
 - **平台**：仅 Windows、仅本地主屏。pnpm 11 拦截构建脚本时，在 profile 的 `pnpm-workspace.yaml` 中允许 `robot-ts` 构建；native 缺失时插件仍可加载，调用时返回可读错误。
 - **落盘**：截图、索引、审计日志默认在 `os.tmpdir()/vision-pilot-shots/`，`VP_SHOT_DIR` 可整体重定向。
 - **迭代**：tarball 是快照，同版本重新 `add` 会被判 "Already up to date"——改源码后标准流程是 `npm pack` → `remove` → `add`。
 
 ## 限制与边界
 
-- **输入能力边界**：不支持键盘注入、拖拽、滚轮、双击。模型无法自己「在地址栏输入」，该步需人代做。
+- **输入能力边界**：支持键盘输入（`vp_type` 文本 / `vp_key` 按键与组合键）；不支持拖拽、滚轮、双击。键盘只作用于**当前焦点控件**，模型无法自己「在地址栏输入」前必须先用鼠标点中输入框。
+- **输入法干扰**：中文输入法会吞掉扫描码注入的字母键（按下不落字，要到下一次 Enter 才吐幽灵字符）。插件已对无修饰键的字符键改走 Unicode 直注绕开它，但用户在输入法里挂着的组合串仍会被 `vp_key enter` 一起提交。
 - **聊天窗口自干扰**：宿主聊天窗口的流式重绘会被当成屏幕变化（实测覆盖率约为变化门限的 14 倍）。等页面加载时，先把聊天窗口移出主屏或最小化。
 - **鼠标移动不可检测**：Windows 屏幕捕获不含硬件光标，挪鼠标不产生任何像素变化。
 - **热键无法区分真人与合成按键**：按键事件流不携带注入标记，审计日志只作事后追溯、不作防伪。真正的护栏在插件之外——宿主安全分类器与操作纪律。
 - **索引并发**：截图索引整份覆盖写、不做跨进程并发保护，多进程共用 `VP_SHOT_DIR` 会互相覆盖；回归测试一律用独立目录。
-- **临时目录卫生**：超过 3 天的差分/网格切片（`vp-diff-*` / `vp-grid-*`）会在插件启动时被自动清理，基准截图（`vp-shot-*`）和审计日志永久保留。
+- **临时目录卫生**：超过 3 天的差分/网格切片（`vp-diff-*` / `vp-grid-*`）会在插件启动时被自动清理；模型在收工时调用 `vp_summarize` 会把关键截图归档到 `archives/` 并清空其余全部碎片。基准截图（`vp-shot-*`）、审计日志、索引与 `archives/` 永久保留。
 
 ## 本地验证
 
 > 以下脚本为开发期本机验证用，含本机绝对路径，**不随仓库与 npm 包分发**（`.gitignore` 已排除 `test-*.mjs`）。克隆仓库后需自备对应脚本。
 
 ```bash
-node test-mvp.mjs        # 五态授权 + 热键/卡片竞态 + 无时钟衰减（约 45s，真实点击屏幕中心）
+node test-mvp.mjs        # 三态授权 + 热键急停/接管 + 无时钟衰减（约 45s，真实点击屏幕中心）
 node test-diff.mjs       # 差分与索引（单元层不碰屏幕；--integration 需配合动屏）
 node test-relative.mjs   # 网格渲染 + 相对坐标换算 + 未授权闸门（不截图、不注入）
 node test-wait.mjs       # 轮询语义（--integration 配合静屏/动屏/假基线）
+node test-keyboard.mjs   # 键名解析 + 注入通道分流 + 持续授权闸门（--live 会真的抢一次键盘焦点）
+node test-summarize.mjs  # 记忆压缩：5 张截图保留 2 张，校验清理、保护区与幂等（不碰屏幕）
 ```
 
 ---

package/package.json

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

package/src/actions.js

@@ -5,8 +5,9 @@
 import { mkdir } from 'node:fs/promises'
 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, consumeOnce, getStatus } from './auth.js'
+import { checkCanClick, getStatus } from './auth.js'
 import { logState } from './audit.js'
 import { resolveShotsDir } from './paths.js'
 import { get, nextShotId, record } from './shot-index.js'
@@ -54,25 +55,45 @@ export async function screenshotAction() {
   }
 }
 
-/** 按物理像素坐标点击一次。x/y 来自 vp_screenshot 的图像坐标系；授权闸门先于坐标校验。 */
+/**
+ * 旁白归一化：模型给的 thought 原样回显；没给（或只给空白）时用一句默认描述兜底。
+ * 旁白是给人看的进度说明，不参与任何判定，所以缺失不该让操作失败。
+ */
+export function normalizeThought(thought, fallback) {
+  if (typeof thought === 'string' && thought.trim() !== '') {
+    return thought.trim()
+  }
+  return fallback
+}
+
+const AUTH_HINT =
+  "请提示用户按 Shift+Space 开启持续授权，或调用 vp_request_auth(mode='persistent') 申请授权。"
+
+/** 四种注入共用的拒绝路径：先落审计，再抛一句模型能照着做的错误。 */
+function denyInjection(tool, gate, extra = {}) {
+  const state = getStatus().state
+  logState('actionDenied', 'tool', state, state, { tool, reason: gate.reason, ...extra })
+  throw new Error(gate.reason === '未授权' ? `未获授权。${AUTH_HINT}` : `${gate.reason}。${AUTH_HINT}`)
+}
+
+/** 放行注入后记一笔；不改变授权状态，只留「这一次真的注入了」的证据。 */
+function allowInjection(tool, extra = {}) {
+  const state = getStatus().state
+  logState('actionAllowed', 'tool', state, state, { tool, ...extra })
+}
+
+/**
+ * 按物理像素坐标点击一次。x/y 来自 vp_screenshot 的图像坐标系；授权闸门先于坐标校验。
+ * 授权只认 persistent：unauthorized 直接抛错，不弹卡片、不消费任何东西。
+ */
 export async function clickAction(args = {}) {
   const { x, y } = args
   const gate = checkCanClick()
   if (!gate.allowed) {
     // 闸门在坐标校验之前，所以这里的 x/y 还没验过；只在确认是数值时才写进审计，
-    // 避免把任意入参当成坐标记录。logical 此刻拿不到 scaleFactor（不为此新建会话），故省略。
-    const state = getStatus().state
-    logState('clickDenied', 'tool', state, state, {
-      reason: gate.reason,
-      ...(Number.isFinite(x) && Number.isFinite(y) ? { physical: { x, y } } : {}),
-    })
-    throw new Error(`vp_click 未获授权：${gate.reason}。可调用 vp_request_auth 请求，或按 Shift+Space 进入持续授权。`)
-  }
-  const { Session, MouseButton } = loadRobotTs()
-  const buttons = {
-    left: MouseButton.Left,
-    right: MouseButton.Right,
-    middle: MouseButton.Middle,
+    // 避免把任意入参当成坐标记录。
+    denyInjection('vp_click', gate,
+      Number.isFinite(x) && Number.isFinite(y) ? { physical: { x, y } } : {})
   }
   const { button = 'left' } = args
 
@@ -82,6 +103,18 @@ export async function clickAction(args = {}) {
   if (x < 0 || y < 0) {
     throw new Error(`vp_click: 坐标不能为负数，收到 x=${x}, y=${y}`)
   }
+
+  return await injectClick({ x, y, button, thought: args.thought, tool: 'vp_click' })
+}
+
+/** 真实注入的共用实现：参数校验、越界检查、换算逻辑坐标、移动并点击。 */
+async function injectClick({ x, y, button = 'left', thought, tool }) {
+  const { Session, MouseButton } = loadRobotTs()
+  const buttons = {
+    left: MouseButton.Left,
+    right: MouseButton.Right,
+    middle: MouseButton.Middle,
+  }
   if (!Object.hasOwn(buttons, button)) {
     throw new Error(`vp_click: button 必须是 left|right|middle，收到 ${button}`)
   }
@@ -102,15 +135,12 @@ export async function clickAction(args = {}) {
     }
 
     const logical = physicalToLogical({ x, y }, primary.scaleFactor)
-    // 参数与越界都通过后才消费放行，避免一次失败的调用浪费单次授权。
-    const consumed = consumeOnce()
-    if (!consumed.allowed) {
-      throw new Error(`vp_click 未获授权：${consumed.reason}。可调用 vp_request_auth 请求，或按 Shift+Space 进入持续授权。`)
-    }
     await session.mouse.move(logical)
     await session.mouse.click(buttons[button])
+    allowInjection(tool, { physical: { x, y }, button })
 
     return {
+      thought: normalizeThought(thought, `点击屏幕物理坐标 (${x}, ${y})`),
       clicked: true,
       physical: { x, y },
       logical,
@@ -121,6 +151,108 @@ export async function clickAction(args = {}) {
   }
 }
 
+/**
+ * 在当前焦点位置输入文本。绝对不包含回车：回车只能由 vp_key 单独触发。
+ *
+ * 授权与鼠标完全一致：persistent 直接放行，unauthorized 直接拦截。
+ * V1.3 取消了键盘独立通道——单次确认卡片会把焦点抢回 DSH，注入反而落错窗口。
+ */
+export async function typeAction(args = {}) {
+  const gate = checkCanClick()
+  if (!gate.allowed) {
+    denyInjection('vp_type', gate)
+  }
+
+  const { text } = args
+  if (typeof text !== 'string' || text.length === 0) {
+    throw new Error(`vp_type: text 必须是非空字符串，收到 ${typeof text === 'string' ? '空串' : typeof text}`)
+  }
+
+  const { Session } = loadRobotTs()
+  const session = await Session.create()
+  try {
+    if (!session.capabilities.canInjectKeyboard) {
+      throw new Error('当前宿主环境不支持键盘注入（canInjectKeyboard=false）')
+    }
+    if (!session.capabilities.canTypeUnicode) {
+      throw new Error('当前宿主环境不支持 Unicode 文本注入（canTypeUnicode=false）')
+    }
+    // robot-ts 的 typeText 走 KEYEVENTF_UNICODE 直接注入码点，与键盘布局无关，
+    // 中文/emoji 都能原样打出来，不需要剪贴板中转。
+    await session.keyboard.typeText(text)
+    allowInjection('vp_type', { chars: text.length })
+    return {
+      typed: text,
+      method: 'unicode',
+      chars: text.length,
+    }
+  } finally {
+    await session.dispose()
+  }
+}
+
+/**
+ * 只解析按键写法，不碰屏幕、不碰授权。
+ * 供宿主层在真正注入前提前报错，键名写错不该走到会话创建。
+ */
+export function describeKeySpec(key) {
+  const { Key, Modifier } = loadRobotTs()
+  const spec = parseKeySpec(key, Key, Modifier)
+  if (!Object.values(Key).includes(spec.code)) {
+    throw new Error(`vp_key: 键码 ${spec.code} 不在 robot-ts 的键表里（上游键表可能已变更）`)
+  }
+  return spec
+}
+
+/**
+ * 发送一次按键或组合键（如 enter / tab / esc / ctrl+c）。
+ * 授权闸门与 vp_type 完全相同：persistent 直接放行，unauthorized 直接拦截。
+ *
+ * 注入通道按键的性质分流（本机实测）：
+ *   - 无修饰键的字符键（字母/数字/符号）→ Unicode 直注。扫描码通道会经过系统输入法，
+ *     中文输入法实测会吞掉字母键（按下不落字，下一次 Enter 才吐幽灵字符）、把引号改成中文弯引号。
+ *   - 其余（控制键、space、带 ctrl/alt/meta 的组合键）→ 真实扫描码，
+ *     这样组合键语义是真的（Ctrl+V 实测能粘上），space 也能激活聚焦的按钮。
+ */
+export async function keyAction(args = {}) {
+  const gate = checkCanClick()
+  if (!gate.allowed) {
+    denyInjection('vp_key', gate)
+  }
+
+  const { key } = args
+  const { Session, Key, Modifier } = loadRobotTs()
+  const spec = parseKeySpec(key, Key, Modifier)
+  const unicodeChar = resolveUnicodeChar(spec)
+
+  const session = await Session.create()
+  try {
+    if (!session.capabilities.canInjectKeyboard) {
+      throw new Error('当前宿主环境不支持键盘注入（canInjectKeyboard=false）')
+    }
+    if (!Object.values(Key).includes(spec.code)) {
+      throw new Error(`vp_key: 键码 ${spec.code} 不在 robot-ts 的键表里（上游键表可能已变更）`)
+    }
+    if (unicodeChar !== null && !session.capabilities.canTypeUnicode) {
+      throw new Error('当前宿主环境不支持 Unicode 文本注入（canTypeUnicode=false）')
+    }
+    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 })
+    return {
+      key: spec.spec,
+      keyName: spec.keyName,
+      modifiers: spec.modifiers,
+      method: unicodeChar !== null ? 'unicode' : 'scancode',
+    }
+  } finally {
+    await session.dispose()
+  }
+}
+
 /**
  * 把「shotId + 1-based region 序号 + 相对百分比」解析成全局物理坐标。
  * 只查索引与做算数，不碰屏幕、不碰授权，所以可以被测试直接调用。
@@ -152,23 +284,26 @@ export function resolveRelativeTarget({ shotId, index, xPercent, yPercent }) {
 }
 
 /**
- * 在差分区域内部按相对位置点击。授权闸门与 vp_click 保持同一顺序：
- * 授权 → 参数合法性 → 越界 → 消费，所以未授权时不会读索引、不会新建 robot-ts 会话。
+ * 在差分区域内部按相对位置点击。授权闸门与 vp_click 同一顺序：
+ * 授权 → 参数合法性 → 越界 → 注入，所以未授权时不会读索引、不会新建 robot-ts 会话。
  */
 export async function clickRelativeAction(args = {}) {
   const gate = checkCanClick()
   if (!gate.allowed) {
-    const state = getStatus().state
-    logState('clickDenied', 'tool', state, state, { reason: gate.reason, tool: 'vp_click_relative' })
-    throw new Error(
-      `vp_click_relative 未获授权：${gate.reason}。可调用 vp_request_auth 请求，或按 Shift+Space 进入持续授权。`,
-    )
+    denyInjection('vp_click_relative', gate)
   }
 
   const { shotId, index, xPercent, yPercent, button = 'left' } = args
   const { bbox, physical } = resolveRelativeTarget({ shotId, index, xPercent, yPercent })
-  const clicked = await clickAction({ x: physical.x, y: physical.y, button })
+  const clicked = await injectClick({
+    x: physical.x,
+    y: physical.y,
+    button,
+    thought: args.thought,
+    tool: 'vp_click_relative',
+  })
   return {
+    thought: clicked.thought,
     clicked: true,
     shotId,
     index,

package/src/audit.js

@@ -8,13 +8,14 @@ import { join } from 'node:path'
 import { resolveShotsDir } from './paths.js'
 
 // 状态机会记录的动作集合（回归测试据此校验，不要在这里放实现分支）。
+// actionAllowed / actionDenied 不改变授权状态，只记录某次注入被放行或被闸门拦截。
 export const AUDIT_ACTIONS = [
   'requestAuth',
   'confirmPending',
   'cancelPending',
   'togglePersistent',
-  'consumeOnce',
-  'clickDenied',
+  'actionAllowed',
+  'actionDenied',
 ]
 
 export function auditLogPath() {

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,29 @@ 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,
 }
 
 /** 当前授权状态（只读快照，不含内部的 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 +68,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 +80,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,43 +108,31 @@ 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
   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: '热键接管' })
   }
   audit('togglePersistent', source, previousState)
@@ -141,38 +140,13 @@ export function togglePersistent(source = 'hotkey') {
 }
 
 /**
- * 消费一次放行。持续授权下放行且不改变状态；单次授权放行即清空。
- * 返回 { allowed, mode?, reason? }。
+ * 鼠标与键盘共用的放行判断（不消费、不改状态）。
+ * 键盘不再有独立通道：persistent 下鼠标与键盘一律放行。
  */
-export function consumeOnce() {
-  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 ? '授权请求待确认' : '未授权',
-  }
-}
-
-/** vp_click 的放行判断（不消费）。 */
 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 +156,14 @@ export function checkCanClick() {
 /** 测试专用：重置为未授权。 */
 export function _resetForTests() {
   state.persistent = false
-  state.onceGranted = false
   clearPending({ code: 'AUTH_CANCELLED', reason: '测试重置' })
   state.requestSeq = 0
 }
 
-/**
- * 测试专用：读内部标志位。persistent 期间 onceGranted 是否还挂着，
- * getStatus() 看不出来（persistent 优先返回 'persistent'），只能从这里取证。
- */
+/** 测试专用：读内部标志位（getStatus 看不到 persistent 期间挂着的 pending 详情之外的东西）。 */
 export function _peekForTests() {
   return {
     persistent: state.persistent,
-    onceGranted: state.onceGranted,
     hasPending: state.pendingRequest !== null,
   }
 }