dsh-copilot-vision 1.1.0 → 1.3.2

package/src/plugin.js

@@ -3,9 +3,10 @@
 // 因此本地可以用 mock 验证注册结构，index.js 则传入真实宿主对象。
 // 本文件不直接 import 宿主包。
 
-import { screenshotAction, clickAction, clickRelativeAction } from './actions.js'
+import { screenshotAction, clickAction, clickRelativeAction, typeAction, keyAction, normalizeThought } from './actions.js'
 import { diffAction } from './diff.js'
 import { waitChangeAction } from './wait.js'
+import { summarizeAction } from './summarize.js'
 import { getStatus, requestAuth, confirmPending, cancelPending } from './auth.js'
 import { auditLogPath } from './audit.js'
 import { consumeNotice } from './shot-index.js'
@@ -46,6 +47,12 @@ const COVERAGE_WARNING =
   '如果界面是相同背景色（如白底）的元素位移或扩展，coverage 会非常低，但界面布局可能已经发生巨变。' +
   '判断界面是否发生重要改变，不要只看 coverage，要以返回的 regions 和 gridPath 的实际内容为准。'
 
+// 旁白要求：模型必须用一句自然语言说明自己在干什么，这句话会展示给用户。
+const THOUGHT_REQUIRED =
+  '【必须写旁白】调用本工具时必须通过 thought 参数，用一句自然语言描述你当前正在做什么' +
+  '（例如「我点击了搜索框，准备输入文字」）。这句话会作为进度旁白展示给用户，' +
+  '也是人判断「这个工具到底在干什么」的唯一依据，不许省略、不许写「执行操作」这类空话。'
+
 const SCREENSHOT_DESCRIPTION =
   '截取主屏全屏并保存为 PNG 文件，返回文件路径（不是 base64，避免占用 token）。' +
   '返回的图像尺寸为物理像素，坐标原点为主屏左上角。' +
@@ -113,8 +120,10 @@ const CLICK_DESCRIPTION =
   '与 vp_screenshot 返回图像的坐标系一致。' +
   '内部会除以主屏 scaleFactor 换算成逻辑坐标再注入鼠标，调用方不要自己换算。' +
   '坐标越界会直接抛错，不会静默夹到边界。' +
-  '调用前必须已获授权：可用 vp_request_auth 请求人类确认，或由用户按 Shift+Space 进入持续授权。' +
-  'MVP 阶段仅支持单击：不支持拖拽、滚轮、双击和键盘输入。' +
+  '调用前必须处于持续授权（persistent）：由用户按 Shift+Space 开启，' +
+  "或调用 vp_request_auth(mode='persistent') 请求人类确认。未授权时会直接抛错，不会弹卡片。" +
+  'MVP 阶段仅支持单击：不支持拖拽、滚轮、双击；键盘输入请用 vp_type / vp_key。' +
+  THOUGHT_REQUIRED +
   BLIND_CLICK_WARNING +
   AGENT_PROTOCOL
 
@@ -127,14 +136,48 @@ const CLICK_RELATIVE_DESCRIPTION =
   '换算由本工具完成：physical.x = bbox.x + round(xPercent × (bbox.width - 1))，y 同理；不要自己算。' +
   'index 越界、百分比不在 0~1、shotId 没有差分区域时直接抛错。' +
   '只有 vp_screenshot_diff / vp_wait_change 产生的区域可点；普通 vp_screenshot 的 shotId 没有区域。' +
-  '调用前同样需要授权：vp_request_auth，或由用户按 Shift+Space 进入持续授权。' +
+  '调用前同样必须处于持续授权：由用户按 Shift+Space 开启，' +
+  "或调用 vp_request_auth(mode='persistent') 请求。未授权时直接抛错，不会弹卡片。" +
+  THOUGHT_REQUIRED +
   BLIND_CLICK_WARNING +
   AGENT_PROTOCOL
 
+const TYPE_DESCRIPTION =
+  '在当前有光标的焦点框内输入一段文本（输入框、搜索框、编辑区等）。' +
+  '底层直接注入 Unicode 码点，与键盘布局无关，中英文、符号、emoji 都能原样打出来。' +
+  '【绝对不含回车】：本工具只负责把文字打进去，绝不自动发送 Enter。' +
+  '需要提交时另调 vp_key（key=enter），并且在它的 thought 里说明你要提交。' +
+  '【必须先点中输入框】：调用前请确保已经用鼠标点击激活了正确的输入位置，' +
+  '否则文字会打到当前焦点所在的任何控件里。' +
+  '【授权与鼠标一致】：只要处于持续授权（persistent）就直接注入，不再弹卡片、不再抢焦点；' +
+  "未授权时直接抛错，请提示用户按 Shift+Space，或调用 vp_request_auth(mode='persistent')。" +
+  THOUGHT_REQUIRED +
+  AGENT_PROTOCOL
+
+const KEY_DESCRIPTION =
+  '发送一次按键或组合键（例如 enter、tab、esc、space、f5、ctrl+c、shift+tab）。' +
+  '键名不区分大小写，支持 ctrl / shift / alt / meta 四种修饰键，用加号连接：ctrl+c。' +
+  '用途是发送控制键：回车提交、Esc 退出、Tab 切换焦点。' +
+  '【高危，请谨慎使用】：Enter 会提交/发送，Ctrl 组合键会复制、粘贴、全选、关闭窗口等，' +
+  '发之前必须先想清楚后果，不要为了「试试看」去按。' +
+  '【必须先点中目标】：本工具只把按键发给当前焦点控件，焦点不对就作用在错的窗口上。' +
+  '【授权与鼠标一致】：只要处于持续授权（persistent）就直接注入，不再弹卡片、不再抢焦点；' +
+  "未授权时直接抛错，请提示用户按 Shift+Space，或调用 vp_request_auth(mode='persistent')。" +
+  '【回车只能由本工具触发】：vp_type 绝不会自动回车；按回车前必须在 thought 里说清意图。' +
+  '【注入通道分两种，返回的 method 会告诉你走的哪条】：' +
+  '不带修饰键的字符键（字母/数字/符号）走 Unicode 直注——因为系统输入法会吞掉扫描码字母键' +
+  '（中文输入法下实测按下不落字，要到下一次 Enter 才吐出幽灵字符），Unicode 直注绕开输入法；' +
+  '控制键（enter/esc/tab/方向键/backspace/delete/f1-f12）、空格、以及任何带 ctrl/alt/meta 的组合键' +
+  '走真实扫描码，组合键语义是真的。' +
+  '【输入法提示】：如果用户正在用输入法打字，组合串还挂在输入法里，本工具按 Enter 会把它一起提交出去。' +
+  THOUGHT_REQUIRED +
+  AGENT_PROTOCOL
+
 const AUTH_REQUEST_DESCRIPTION =
-  '请求人类授权 Vision-Pilot 执行鼠标点击。这是请求，不是授权本身：' +
+  '请求人类开启持续授权（persistent）。这是请求，不是授权本身：' +
   '工具会暂停，并通过宿主的人类问答界面等待用户选择“允许”或“拒绝”。' +
-  'mode=once 只放行下一次点击；mode=persistent 放行此后所有点击，直到用户按 Shift+Space 撤销。' +
+  '确认后放行此后所有鼠标与键盘操作，直到用户按 Shift+Space 急停撤销。' +
+  'V1.3 起只支持持续授权，没有单次授权——单次卡片会抢走焦点，反而破坏后续注入。' +
   '用户拒绝、取消或问答超时不会改变授权状态。' +
   '等待期间用户按了 Shift+Space 会取代这次请求：那时本工具正常返回 confirmed:false 并带 reason 说明' +
   '（热键接管/热键撤销），不是报错；以返回的 state 为准，不要重试请求。' +
@@ -142,15 +185,101 @@ const AUTH_REQUEST_DESCRIPTION =
 
 const AUTH_STATUS_DESCRIPTION =
   '查看 Vision-Pilot 的授权状态（只读，不改变任何权限）。' +
-  'state 有五种：unauthorized（未授权）、pending-once（单次授权待人类确认）、' +
-  'authorized-once（单次授权已确认、待下一次点击消费）、pending-persistent（持续授权待确认）、' +
-  'persistent（持续授权中）。' +
+  'state 有三种：unauthorized（未授权）、pending-persistent（持续授权待人类确认）、' +
+  'persistent（持续授权中，鼠标与键盘一律放行）。' +
   '持续授权一直有效，直到用户按 Shift+Space 撤销；没有到期时间，也不返回剩余毫秒。' +
   '另返回待确认请求 pendingRequest、全局热键（Shift+Space）是否可用 hotkeyAvailable / hotkeyError，' +
   '以及授权审计日志路径 auditLogPath。' +
   AGENT_PROTOCOL
 
-const AUTH_STATES = ['unauthorized', 'pending-once', 'authorized-once', 'pending-persistent', 'persistent']
+const SUMMARIZE_DESCRIPTION =
+  '清理本任务的视觉记忆：归档关键截图，其余临时碎片一键清空。' +
+  '【收工必调】：完成一个完整任务周期、准备收工或切换任务时，必须调用本工具——' +
+  '否则临时图会跨会话堆积，换几次会话就留一堆垃圾。' +
+  'keepShotIds 填你要长期保留的关键截图 shotId（例如「初始页」和「结果页」），' +
+  '这些全屏截图会被移动进 archives 子目录，索引也会同步到新路径，之后仍可做差分；' +
+  '其余所有 vp-shot-* 全屏截图、vp-diff-* 差分切片、vp-grid-* 网格图会被立即彻底删除。' +
+  'summary 是一段文字总结，会和本次保留清单一起追加写入 archive-summary.txt。' +
+  '审计日志 audit.log、截图索引 shot-index.json、archives 目录永远不被删除。' +
+  '【删除不可撤销】：调用前请确认 keepShotIds 已包含所有还需要回看的截图。' +
+  AGENT_PROTOCOL
+
+const AUTH_STATES = ['unauthorized', 'pending-persistent', 'persistent']
+
+/**
+ * 弹持续授权卡片并等人类回答。V1.3 只有这一种授权卡片；
+ * 键盘与鼠标共用持续授权，不再各自弹卡。
+ *
+ * 卡片和热键是两个都能改 pendingRequest 的人，谁先落地谁说话：热键一按，
+ * signal 就 abort，这里把它变成一次 reject，和 ask() 赛跑，而不是让答案撞进
+ * confirmPending() 变成「没有待确认的授权请求」。
+ */
+async function askAuthCard(ctx, exec, { question, allowDescription, rejectDescription }) {
+  const request = requestAuth('persistent')
+  const cancelled = new Promise((_resolve, reject) => {
+    const abort = () => reject(request.signal.reason)
+    if (request.signal.aborted) abort()
+    else request.signal.addEventListener('abort', abort, { once: true })
+  })
+  // ask() 还没建立就可能同步抛错（宿主没有 userQuestions），那时没人接住这个 reject。
+  cancelled.catch(() => {})
+  let answer
+  try {
+    if (ctx?.userQuestions === undefined) {
+      throw new Error('宿主未提供 userQuestions 服务')
+    }
+    const asking = ctx.userQuestions.ask({
+      questions: [{
+        id: 'vp-auth',
+        header: 'Vision-Pilot 持续授权',
+        question,
+        options: [
+          { label: '允许', description: allowDescription },
+          { label: '拒绝', description: rejectDescription ?? '不改变授权状态' },
+        ],
+      }],
+      ...(exec?.agent !== undefined ? { agent: exec.agent } : {}),
+      ...(exec?.signal !== undefined ? { signal: exec.signal } : {}),
+    })
+    // 本工具返回后那张卡片还在人面前，被关掉时宿主可能 reject；不能让悬空 rejection 冒出去。
+    asking.catch(() => {})
+    answer = await Promise.race([asking, cancelled])
+  } catch (error) {
+    if (error?.code === 'AUTH_CANCELLED') {
+      // 不算失败：请求被更明确的人的动作取代了，把终态如实报回去。
+      return {
+        requestId: request.requestId,
+        state: getStatus().state,
+        confirmed: false,
+        reason: typeof error.reason === 'string' ? error.reason : '本次请求已被取消',
+      }
+    }
+    cancelPending()
+    throw new Error(
+      `授权确认失败：${error instanceof Error ? error.message : String(error)}`,
+    )
+  }
+
+  const selected = answer?.answers?.[0]?.selected ?? []
+  if (!selected.includes('允许')) {
+    cancelPending()
+    return {
+      requestId: request.requestId,
+      state: getStatus().state,
+      confirmed: false,
+    }
+  }
+
+  const status = confirmPending(request.requestId)
+  return {
+    requestId: request.requestId,
+    state: status.state,
+    confirmed: status.confirmed,
+    ...(status.confirmed
+      ? {}
+      : { reason: '答案到达时这次请求已被热键接管或已取消，按丢弃处理' }),
+  }
+}
 
 /** 索引损坏等只说一次的告知；render 每个结果调用一次，所以用户会看到但它不会刷屏。 */
 function noticeLine() {
@@ -243,12 +372,18 @@ export function createPlugin(defineTool, ctx, hotkeyState = { available: false,
         default: 'left',
         description: '鼠标按键，默认 left',
       },
+      thought: {
+        type: 'string',
+        required: true,
+        description: '一句话说明你现在要做什么（例如「我点击了地址栏，准备输入搜索词」），会作为进度旁白展示给用户',
+      },
     },
     output: {
       schema: {
         type: 'object',
         additionalProperties: false,
         properties: {
+          thought: { type: 'string', required: true },
           clicked: { type: 'boolean', required: true },
           physical: {
             type: 'object',
@@ -274,6 +409,7 @@ export function createPlugin(defineTool, ctx, hotkeyState = { available: false,
       render: (_args, value) => [{
         type: 'text',
         text:
+          `旁白：${value.thought}\n` +
           `点击完成：物理 (${value.physical.x}, ${value.physical.y}) → ` +
           `逻辑 (${value.logical.x}, ${value.logical.y})，按键 ${value.button}\n` +
           JSON.stringify(value),
@@ -314,12 +450,18 @@ export function createPlugin(defineTool, ctx, hotkeyState = { available: false,
         default: 'left',
         description: '鼠标按键，默认 left',
       },
+      thought: {
+        type: 'string',
+        required: true,
+        description: '一句话说明你现在要做什么（例如「我点击了搜索结果里的第二条」），会作为进度旁白展示给用户',
+      },
     },
     output: {
       schema: {
         type: 'object',
         additionalProperties: false,
         properties: {
+          thought: { type: 'string', required: true },
           clicked: { type: 'boolean', required: true },
           shotId: { type: 'number', required: true },
           index: { type: 'number', required: true },
@@ -357,6 +499,7 @@ export function createPlugin(defineTool, ctx, hotkeyState = { available: false,
       render: (_args, value) => [{
         type: 'text',
         text:
+          `旁白：${value.thought}\n` +
           `相对点击完成：shot #${value.shotId} region #${value.index}，` +
           `相对 (${value.relative.xPercent}, ${value.relative.yPercent}) → ` +
           `物理 (${value.physical.x}, ${value.physical.y}) → ` +
@@ -370,6 +513,109 @@ export function createPlugin(defineTool, ctx, hotkeyState = { available: false,
     },
   })
 
+  const typeTool = defineTool({
+    name: 'vp_type',
+    description: TYPE_DESCRIPTION,
+    parameters: {
+      text: {
+        type: 'string',
+        required: true,
+        description: '要输入的文本（支持中英文/符号/emoji）。本工具绝不自动发送回车。',
+      },
+      thought: {
+        type: 'string',
+        required: true,
+        description: '一句话说明你现在要做什么（例如「我在搜索框里输入 DeepSeek」），会作为进度旁白展示给用户',
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          thought: { type: 'string', required: true },
+          typed: { type: 'string', required: true },
+          success: { type: 'boolean', required: true },
+          method: { type: 'string', enum: ['unicode'], required: true },
+          chars: { type: 'number', required: true },
+        },
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text:
+          `旁白：${value.thought}\n` +
+          `输入完成：${value.typed}（${value.chars} 字符，Unicode 直注，未发送回车）\n` +
+          JSON.stringify(value),
+      }],
+    },
+    async execute(args) {
+      const thought = normalizeThought(args.thought, '（模型未提供旁白）')
+      // 授权与注入都在 typeAction 内完成：persistent 直接打字，unauthorized 直接抛错。
+      // V1.3 起这里不再弹卡片——点「允许」会把焦点抢回 DSH，紧接着的注入就落错窗口了。
+      const result = await typeAction({ text: args.text, thought })
+      return {
+        thought,
+        typed: result.typed,
+        success: true,
+        method: result.method,
+        chars: result.chars,
+      }
+    },
+  })
+
+  const keyTool = defineTool({
+    name: 'vp_key',
+    description: KEY_DESCRIPTION,
+    parameters: {
+      key: {
+        type: 'string',
+        required: true,
+        description: '键名或组合键，例如 enter / esc / tab / space / f5 / ctrl+c / shift+tab',
+      },
+      thought: {
+        type: 'string',
+        required: true,
+        description: '一句话说明你现在要按这个键做什么（例如「我按回车提交搜索」），会作为进度旁白展示给用户',
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          thought: { type: 'string', required: true },
+          key: { type: 'string', required: true },
+          keyName: { type: 'string', required: true },
+          modifiers: { type: 'array', required: true, items: { type: 'string' } },
+          method: { type: 'string', enum: ['unicode', 'scancode'], required: true },
+          success: { type: 'boolean', required: true },
+        },
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text:
+          `旁白：${value.thought}\n` +
+          `按键完成：${value.key}` +
+          `${value.modifiers.length > 0 ? `（修饰键：${value.modifiers.join('+')}）` : ''}` +
+          `（通道：${value.method === 'unicode' ? 'Unicode 直注' : '真实扫描码'}）\n` +
+          JSON.stringify(value),
+      }],
+    },
+    async execute(args) {
+      const thought = normalizeThought(args.thought, '（模型未提供旁白）')
+      // 授权与注入都在 keyAction 内完成：persistent 直接按键，unauthorized 直接抛错。
+      const result = await keyAction({ key: args.key, thought })
+      return {
+        thought,
+        key: result.key,
+        keyName: result.keyName,
+        modifiers: result.modifiers,
+        method: result.method,
+        success: true,
+      }
+    },
+  })
+
   const diffTool = defineTool({
     name: 'vp_screenshot_diff',
     description: DIFF_DESCRIPTION,
@@ -522,9 +768,9 @@ export function createPlugin(defineTool, ctx, hotkeyState = { available: false,
     parameters: {
       mode: {
         type: 'string',
-        enum: ['once', 'persistent'],
+        enum: ['persistent'],
         required: true,
-        description: 'once=只放行下一次点击；persistent=确认后持续放行，直到用户按 Shift+Space 撤销',
+        description: "只支持 persistent：确认后持续放行鼠标与键盘，直到用户按 Shift+Space 撤销",
       },
     },
     output: {
@@ -547,78 +793,12 @@ export function createPlugin(defineTool, ctx, hotkeyState = { available: false,
       }],
     },
     async execute(args, exec) {
-      const request = requestAuth(args.mode)
-      // 卡片和热键是两个都能改 pendingRequest 的人，谁先落地谁说话：热键一按，
-      // signal 就 abort，这里把它变成一次 reject，和 ask() 赛跑，而不是让答案撞进
-      // confirmPending() 变成「没有待确认的授权请求」。
-      const cancelled = new Promise((_resolve, reject) => {
-        const abort = () => reject(request.signal.reason)
-        if (request.signal.aborted) abort()
-        else request.signal.addEventListener('abort', abort, { once: true })
+      const card = await askAuthCard(ctx, exec, {
+        question: '是否允许 Vision-Pilot 持续执行鼠标与键盘操作，直到你按 Shift+Space 撤销？',
+        allowDescription: '持续放行，直到按 Shift+Space 撤销',
+        rejectDescription: '不改变授权状态',
       })
-      // ask() 还没建立就可能同步抛错（宿主没有 userQuestions），那时没人接住这个 reject。
-      cancelled.catch(() => {})
-      let answer
-      try {
-        if (ctx?.userQuestions === undefined) {
-          throw new Error('宿主未提供 userQuestions 服务')
-        }
-        const asking = ctx.userQuestions.ask({
-          questions: [{
-            id: 'vp-auth',
-            header: 'Vision-Pilot 授权',
-            question: args.mode === 'once'
-              ? '是否允许 Vision-Pilot 执行下一次鼠标点击？'
-              : '是否允许 Vision-Pilot 持续执行鼠标点击，直到你按 Shift+Space 撤销？',
-            options: [
-              {
-                label: '允许',
-                description: args.mode === 'once' ? '只放行下一次点击' : '持续放行，直到按 Shift+Space 撤销',
-              },
-              { label: '拒绝', description: '不改变授权状态' },
-            ],
-          }],
-          ...(exec?.agent !== undefined ? { agent: exec.agent } : {}),
-          ...(exec?.signal !== undefined ? { signal: exec.signal } : {}),
-        })
-        // 本工具返回后那张卡片还在人面前，被关掉时宿主可能 reject；不能让悬空 rejection 冒出去。
-        asking.catch(() => {})
-        answer = await Promise.race([asking, cancelled])
-      } catch (error) {
-        if (error?.code === 'AUTH_CANCELLED') {
-          // 不算失败：请求被更明确的人的动作取代了，把终态如实报回去。
-          return {
-            requestId: request.requestId,
-            state: getStatus().state,
-            confirmed: false,
-            reason: typeof error.reason === 'string' ? error.reason : '本次请求已被取消',
-          }
-        }
-        cancelPending()
-        throw new Error(
-          `授权确认失败：${error instanceof Error ? error.message : String(error)}`,
-        )
-      }
-
-      const selected = answer?.answers?.[0]?.selected ?? []
-      if (!selected.includes('允许')) {
-        cancelPending()
-        return {
-          requestId: request.requestId,
-          state: getStatus().state,
-          confirmed: false,
-        }
-      }
-
-      const status = confirmPending(request.requestId)
-      return {
-        requestId: request.requestId,
-        state: status.state,
-        confirmed: status.confirmed,
-        ...(status.confirmed
-          ? {}
-          : { reason: '答案到达时这次请求已被热键接管或已取消，按丢弃处理' }),
-      }
+      return card
     },
   })
 
@@ -637,7 +817,7 @@ export function createPlugin(defineTool, ctx, hotkeyState = { available: false,
             additionalProperties: false,
             properties: {
               requestId: { type: 'string', required: true },
-              mode: { type: 'string', enum: ['once', 'persistent'], required: true },
+              mode: { type: 'string', enum: ['persistent'], required: true },
               requestedAt: { type: 'number', required: true },
             },
           },
@@ -665,7 +845,72 @@ export function createPlugin(defineTool, ctx, hotkeyState = { available: false,
     },
   })
 
-  const tools = [screenshotTool, diffTool, waitTool, clickTool, clickRelativeTool, requestAuthTool, authStatusTool]
+  const summarizeTool = defineTool({
+    name: 'vp_summarize',
+    description: SUMMARIZE_DESCRIPTION,
+    parameters: {
+      keepShotIds: {
+        type: 'array',
+        required: true,
+        items: { type: 'number' },
+        description: '要长期保留的关键截图 shotId 列表（例如初始页与结果页）；其余截图会被删除',
+      },
+      summary: {
+        type: 'string',
+        required: true,
+        description: '本次任务的文字总结，会连同保留清单追加写入 archive-summary.txt',
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          summary: { type: 'string', required: true },
+          archivedShotIds: { type: 'array', required: true, items: { type: 'number' } },
+          missingShotIds: { type: 'array', required: true, items: { type: 'number' } },
+          failedShotIds: { type: 'array', required: true, items: { type: 'number' } },
+          failedArchives: { type: 'number', required: true },
+          removedShots: { type: 'number', required: true },
+          removedDiff: { type: 'number', required: true },
+          removedGrid: { type: 'number', required: true },
+          removedTotal: { type: 'number', required: true },
+          failedDeletes: { type: 'number', required: true },
+          archivesDir: { type: 'string', required: true },
+          summaryPath: { type: 'string', required: true },
+        },
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text:
+          `记忆压缩完成：归档 ${value.archivedShotIds.length} 张关键截图，` +
+          `清理 ${value.removedTotal} 个临时碎片` +
+          `（截图 ${value.removedShots}、差分 ${value.removedDiff}、网格 ${value.removedGrid}）\n` +
+          (value.failedArchives > 0
+            ? `注意：shotId ${value.failedShotIds.join(',')} 归档失败（可能被占用），源文件已保留未删除\n`
+            : '') +
+          `总结：${value.summary}\n` +
+          `归档目录：${value.archivesDir}\n` +
+          JSON.stringify(value),
+      }],
+    },
+    async execute(args) {
+      return await summarizeAction(args)
+    },
+  })
+
+  const tools = [
+    screenshotTool,
+    diffTool,
+    waitTool,
+    clickTool,
+    clickRelativeTool,
+    typeTool,
+    keyTool,
+    requestAuthTool,
+    authStatusTool,
+    summarizeTool,
+  ]
 
   // 不再提供 apply() 方法：注册的唯一生产路径是 index.js 的 apply(ctx)（逐个 register tools），
   // 此前挂在本方法里的启动清理因无人调用而从未触发，清理已随接线修复移入 index.js。

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，所以区域必须随索引落盘 ——