[graydovee]

概述 / Summary

浏览器工具从「按编号点击/输入」扩展为一层通用输入能力：指针手势与坐标、组合键与按住、光标插入与逐键输入、剪贴板（文本/富文本）、文件上传、单 iframe 精读；并新增 browser_clipboard / browser_upload 两个工具。

动机 / Motivation

富文本编辑器、画布/SVG 白板、代码编辑器和拖拽界面没有语义角色，快照清单点不到；原 browser_press 只有单键且是合成事件，Cmd+A/Cmd+V 不生效；编辑器自持文档模型，直接写 value 会被回滚。缺口是输入原语，不是应用适配。

改动内容 / Changes

• 扩展既有工具：browser_snapshot（frame、query）、browser_click（selector/point/action/drag/trusted 等）、browser_type（selector/mode/trusted）、browser_press（modifiers/action down-up/repeat）、browser_scroll（point 真实滚轮）、browser_follow_tab（activate）。
• 新增 browser_clipboard（write / paste event / system paste）与 browser_upload（宿主侧路径校验 + CDP 设置文件）。
• 共享 chrome.debugger broker：devtools 与 input 共用单标签页附加，输入空闲 20s 释放；input 只用 Input.* + Emulation.setFocusEmulationEnabled。
• 输入状态按标签页保存（按住修饰键/鼠标键），导航与关标签页重置；坐标按 frame 局部 + 祖先 frame 偏移换算。
• macOS 编辑快捷键补 commands（selectAll/copy/paste/cut/undo/redo）；keystrokes 模式保留大写；粘贴事件未被消费时对普通 input 回退插入。
• 滚轮要求活动标签页 + 聚焦窗口（后台页会被冻结），守卫快速失败并提示 follow_tab {activate:true}；截图拒绝未聚焦窗口，避免过期帧。
• 导航只释放 input 占用，devtools 抓包跨 reload 存活。
• 中英文 README / 设计记录 / 变更日志同步；新增 10 个测试文件。

测试 / Testing

• pnpm run typecheck、pnpm run test（桥 222 + 扩展 700）、pnpm run build、Firefox 构建、pnpm run check:runtime、node scripts/smoke-runtime.mjs 全部通过。
• 真机验证（macOS Chrome 155 + DSH Desktop，Confluence 草稿页 + 临时标签页 + 本地 fixture）：三轮共 94 / 40 / 21 项；最终 20 PASS / 0 FAIL / 1 SKIP。12 个首轮失败项全部修复并复测通过，含 selector-only 目标、Meta+A/Meta+V、keystrokes 大写、滚轮前台/后台守卫、抓包跨 reload、upload 路径校验、截图新鲜度、paste 回退。
• SKIP：真实文件上传到 Confluence 正文编辑器（会修改草稿正文，改用本地 fixture 验证成功路径）。

影响范围 / Impact

• Chrome/Edge：新增 clipboardWrite、offscreen 权限与离屏剪贴板页；真实输入会附加调试器（显示提示条、该标签页暂不能开 DevTools），空闲自动释放。
• Firefox：无真实输入/系统剪贴板写入/文件上传，自动降级为合成输入并标注 (synthetic)；元素寻址、文本、粘贴事件、query 照常。
• macOS：Meta 类编辑快捷键依赖 commands；其它平台行为不变。
• 默认后台执行：不激活标签页、不聚焦窗口、不移动系统鼠标；滚轮与截图例外（需要前台/聚焦窗口）。

Checklist

• 已在相关平台实测通过 / Tested on the relevant platforms
• 已通过 pnpm run build / bash -n scripts/install.sh 等基础检查 / Passed basic checks
• 文档已同步更新（如需要）/ Docs updated if needed
• 不包含无关改动 / No unrelated changes included