@senguoyun/dsh-arkme 0.1.74 → 0.1.76

package/docs/desktop-screenshot.md

@@ -1,33 +1,57 @@
-# 对话输入框截屏（桌面原生与浏览器）
+# 对话输入框截图与编辑
 
-## 范围
+## 当前实现（2026-09-21）
 
-- 发给自己、私聊、群聊（含自己的主题）工具栏，表情右侧新增“截屏”。
-- Arkme 桌面运行环境保留 macOS 原生区域框选；普通浏览器改为“浏览器选择屏幕/窗口 → 静态截图裁剪 → 加入草稿”。
-- 不自动发送、不覆盖文字和既有附件，恢复原光标位置。
-- Esc 取消静默处理。切换会话、退出输入场景、切换账号或关闭页面时取消，不向新会话添加截图。
-- 无标注、马赛克、全局快捷键、自动隐藏应用；浏览器不提供跨桌面的原生框选覆盖层。Windows 原生截屏暂不支持，但支持选屏的浏览器可使用网页流程。
-- 未改已安装的 Arkme 客户端、宿主原生代码或权限配置。macOS 屏幕录制授权由系统决定，不绕过授权。
+新客户端通过 `arkmeScreenshot.version === 1` 优先启用 Electron `desktopCapturer`。客户端主进程保持发起窗口可见、捕获各屏静态 PNG，再创建无边框覆盖窗口；插件在 `?arkmeScreenshot=1` 页面只挂载截图编辑器。每屏独立框选，首次选区确认后关闭其他屏覆盖窗口，不跨屏拼接。
 
-## 浏览器流程与边界
+原始图像像素尺寸来自 NativeImage；编辑坐标按显示区域与图像宽高分别换算，适用于高 DPI 和负坐标副屏。框选后、绘图前可移动或调整选区。
 
-1. 只有用户点击剪刀后才调用 `getDisplayMedia({ video: true, audio: false })`；同一点击调用栈内发起，不在前面等待宿主能力请求。
-2. 用户在浏览器中选择屏幕、窗口或标签页。得到第一帧后立即停止所有轨道，再显示裁剪弹窗；不会在编辑时持续共享，也不采集音频。
-3. 截图弹窗支持拖动选区（含反向拖动）、取消、使用整张、完成裁剪；同时适配明暗主题、窄窗口和键盘关闭。
-4. 只有确认后才复用附件暂存。截图不会自动发送，不替换原文字和已有附件，完成或取消后恢复原输入位置。
-5. 会话、账号、页面可见状态变化或组件卸载时取消；浏览器选屏窗口无法由网页强制关闭，但后续即使授权返回，也立即停止流，不添加到新会话。
-6. 等待选屏超过 120 秒取消本次操作，读取画面超过 10 秒释放共享；裁剪静态画面不设操作限时。
-7. 不安全地址、缺少选屏能力、拒绝授权、系统权限或读取失败均显示提示，并提供“兼容浏览器/系统截屏后粘贴”的替代路径。
+工具栏仅显示 SVG 图标，hover/focus tooltip 和 aria-label 提供中文名称。支持矩形、圆形/椭圆、箭头、画笔、马赛克、文本、撤销/重做、重选、保存、取消、完成。选中对应工具才显示颜色、粗细、字号或马赛克大小。马赛克直接合成进 PNG；导出文件不附带原图或编辑历史。
 
-原实现只有本机 `desktop.screenshot.capture` 路径，并不能证明普通浏览器拥有原生框选能力。现在以现有 `arkmeDesktop.appVersion / harnessVersion` 桥接标识识别 Arkme 客户端；不把所有 Electron 内嵌浏览器都当成 Arkme 原生客户端。
+- 保存：客户端系统保存对话框，浏览器下载；取消保存不退出编辑。
+- 完成：合成选区后通过原有附件流程加入发起会话草稿，不自动发送，不替换文字或已有附件。
+- 取消：Esc 或取消按钮，恢复发起窗口；会话/账号切换丢弃迟到结果。
+- 快捷键：Cmd/Ctrl+Z 撤销、Cmd/Ctrl+Shift+Z 重做、Cmd/Ctrl+S 保存、Enter 完成；文本中保留原生编辑快捷键，Cmd/Ctrl+Enter 确认文本。
+- 捕获/加载限时 20 秒，静态编辑不限时。原窗口导航/销毁、账号 scope 变化、显示器新增/移除/尺寸变化会取消并销毁覆盖窗口。
 
-浏览器安全限制不能绕过：每次都需要用户主动操作并选择共享来源；某些内嵌浏览器即使暴露 API，也需要宿主实现选屏支持。参见 [W3C Screen Capture](https://www.w3.org/TR/screen-capture/) 和 [Electron desktopCapturer](https://www.electronjs.org/docs/latest/api/desktop-capturer)。本次不改 Arkme 或其他应用的宿主权限配置。
+## 宿主边界与兼容
 
-## macOS 原生路径约束
+客户端主进程验证顶层 frame、当前可信 origin、主窗口/有效会话窗口身份。截图窗口仅可读取本屏图像、选择、保存、完成或取消；发起者的 cancel 必须匹配本次 requestId。保存路径只来自系统对话框，插件不传入本地路径；PNG 解码与尺寸限制在主进程校验。
 
-只在明确点击按钮后启动 `/usr/sbin/screencapture -i -s -x -t png`，不执行 shell、不接受调用方路径、不读取剪贴板。接口要求本机连接、当前同源页面和有效登录账号，截屏前后核对账号；不注册为 MCP 工具。默认 120 秒超时，仅允许一个截屏进程；页面取消和账号退出会终止进程。
+普通浏览器继续 `getDisplayMedia({video:true,audio:false})`，抓取一帧后立即停流，使用同一编辑器。新客户端与旧插件组合仍由旧插件使用旧服务；新插件与旧客户端组合保留旧 macOS `screencapture` 流程（没有新原生编辑桥接）。无需改动既有后端截图 API。
 
-PNG 先写入独立的私有临时目录，校验大小及签名后只返回图片内容，不返回本机路径。成功、取消、出错均清理该临时目录。图片加入草稿时沿用已有文件数量和大小限制，只有用户点发送才进入消息发送流程。
+系统屏幕录制权限仍由 OS 管理，不绕过授权；多屏来源匹配失败明确报错，不猜测屏幕。截图内容不写日志。Windows/macOS 原生路径需在实际设备完成权限与多屏验收。
+
+## 可重复验证
+
+相关测试：`tests/*screenshot*.test.*`。新增 `native-screenshot`、编辑模型和输入框桥接回归。客户端对应 `desktop-screenshot-session`、`desktop-screenshot-ipc` 测试。
+
+真实 Electron 渲染使用合成屏幕，不读取实际桌面。插件仓中执行：
+
+```sh
+mkdir -p /tmp/arkme-screenshot-qa
+./node_modules/.bin/rolldown tests/fixtures/screenshot-editor-preview.tsx --platform browser --format iife --file /tmp/arkme-screenshot-qa/editor.js
+```
+
+在该目录创建 `index.html`，内容为 `<meta charset="utf-8"><div id="root"></div><script src="editor.js"></script>`；使用客户端安装的 Electron 运行：
+
+```sh
+/path/to/electron tests/fixtures/screenshot-editor-electron.cjs /tmp/arkme-screenshot-qa
+```
+
+夹具验证图形像素、马赛克区域变化、裁剪后的 980×500 PNG、全部编辑工具、文本、撤销/重做、保存和完成，产出 editor.png、export.png。系统授权、实际桌面捕获和跨平台多屏并未被合成图验证替代。
+
+## 真实设备验收清单
+
+1. 客户端安装当前客户端和插件产物。主窗口及独立会话窗口均点击截图，验证发起窗口保持可见、覆盖层不进入截图。
+2. 在各屏分别框选，测试 Retina/混合缩放/负坐标副屏；不支持跨屏拼接。
+3. 六种工具绘制、撤销/重做、重选；保存与取消保存；完成后仅增加草稿图片，原文字/附件保留。
+4. 拒绝屏幕权限、捕获中取消、加载失败、切换账号/会话、关闭原窗口、接入/拔出显示器，验证恢复和资源清理。
+5. 浏览器截图复用相同工具，编辑时屏幕共享已停止；旧客户端截图仍可用。
+
+## 历史记录
+
+以下记录针对旧流程，不代表本次原生编辑功能已完成真实设备验收。
 
 ## 原生路径历史验证记录（2026-09-19）
 
@@ -48,12 +72,35 @@ PNG 先写入独立的私有临时目录，校验大小及签名后只返回图
 - 原生路径仅保留既有实现，未修改或重启已安装 Arkme 客户端。本次没有新开端口或迁移登录信息，只更新隔离预览的前端产物。
 - **尚未验收：真实浏览器/内嵌宿主的系统选屏授权，以及 macOS 原生框选权限。** 合成流测试不能代替这些宿主能力；不支持时应按界面提示使用兼容浏览器或系统截屏后粘贴。
 
-## 真实环境验收
+### 双平台窗口吸附（2026-09-21）
+
+- macOS：通过现有 Koffi 调用 CGWindowListCopyWindowInfo/CoreFoundation，读取当前可见窗口矩形和顺序；保留正常及浮动应用窗口，过滤桌面、菜单层、全透明和不可见窗口。原生窗口列表在截图覆盖层创建前读取，不激活目标应用。
+- Windows：EnumWindows 获取句柄快照，GW_HWNDPREV 计算前后顺序（带循环/次数限制），过滤隐藏、最小化、cloaked、全透明 layered 和桌面/任务栏窗口；DWM extended frame bounds 获取不含不可见调整边框的物理矩形，失败退到 GetWindowRect。
+- 窗口信息只包含矩形，不返回标题/进程名。Windows 用 Electron dipToScreenRect 将显示器边界转为物理坐标，macOS 使用 Quartz 逻辑坐标；每屏分别裁剪并按实际截图尺寸映射像素。跨屏窗口只选择当前屏部分。
+- 桥接 context 可选 windows 字段，旧版本缺少字段或原生 API 失败时继续手动框选。悬浮匹配最前方窗口；单击（4 CSS px 内抖动）设为选区，拖动自由框选；选中后可移动/调整/标注。重选回到窗口识别。
+- 已验证：macOS 原生窗口边界、重叠顺序、隐藏过滤；真实 Electron 合成画面的原生鼠标悬浮、点击吸附、框选、标注、撤销重做、保存、完成。Windows 适配过滤/排序与几何逻辑通过模拟 API 测试，尚无 Windows 真机验收。
+- 客户端可复验：构建后 `electron tests/fixtures/screenshot-window-native.cjs`，同一夹具支持 macOS/Windows，不捕获用户桌面像素。Windows 验收应额外覆盖 100%/125%/150% 双屏、负坐标、cloaked 虚拟桌面及全透明置顶窗口。
+- 独立审查发现全透明 Windows 窗口过滤缺口，补 GetLayeredWindowAttributes 和回归后通过。手势复验发现 pointerup 最终坐标会被旧 selection 覆盖，已按实际释放坐标计算并补回归。
+
+### 截图启动延迟排查与优化（2026-09-21）
+
+排查流程：跟踪 capture → 原生窗口列表 → 各屏 getSources → toPNG → 编辑窗口创建/loadURL → context 解码 → ready/show；通过只加计时的原实现副本和同环境改进版本做对照。
+
+根因：逐个取不同尺寸显示器，导致重复全屏采集等待串行叠加；主进程同步编码 PNG；编辑窗口也串行加载；渲染端 Uint8Array.from(atob(...), callback) 对每字节执行 JS 回调。新增的窗口吸附并非主要瓶颈（首次原生库初始化约 28ms，后续枚举约 0.7ms）。一次分段采样的两次 getSources 合计约 459ms，PNG 编码约 196ms。
+
+已改为按尺寸缓存 pending Promise 并发取图（保留各屏原生尺寸、无重采样），所有帧采集完毕才创建覆盖层，再并行加载各编辑器。全部 ready 后才显示，取消/异常依然清理租约。渲染端采用 Chromium Uint8Array.fromBase64；旧版使用预分配数组+循环，保持精确字节，不用有损格式。
+
+验证：同设备双屏3024×1964/3840×2160、同一个独立编辑器 HTTP 页面、真实桌面仅在内存读取且不落盘。旧版本从 invoke 到全部 overlay visible 的3次耗时983/683/657ms，新版576/544/547ms。该夹具隔离宿主业务初始化，不应作为完整客户端每次固定耗时的承诺。另以3MB合成数据验证旧解码87.6ms，原生解码1.3ms且逐字节一致。系统截图、PNG 编码和首次进程初始化仍有成本，尚未实现预热/驻留或原生低延迟渲染路径。
+
+性能修复最终回归：客户端33项、插件79项相关测试通过，两仓类型检查和构建通过。独立审查发现后续窗口初始化同步失败时先前 loadURL 的 rejection 未接管；改为 Promise.all(async map) 并补故障注入回归，已验证无 unhandled rejection。Dev 已更新。
+
+### 箭头尖端凸起修复（2026-09-21）
+对照用户图片检查 arrow 绘制路径，再以真实 Electron Canvas 复现：线杆直接画至箭头尖端且 lineCap=round，圆帽伸出尖端约线宽的一半。现将线杆截于三角底部，短箭头按手势长度缩短且省略不适合的线杆，零长度不绘制。新增36组方向/粗细/长短组合的真实像素回归，检查没有越过尖端或向后溢出，并保留整体编辑/导出烟测；全部通过。类型检查与打包通过。
+
+## 截图快捷键
+
+客户端注册全局快捷键：macOS 默认 `Command+Shift+A`，Windows 默认 `Control+Shift+A`。快捷键复用当前可用会话的截图入口和附件草稿流程；后台触发不主动激活主窗口，未登录或没有可用截图输入框时不发起截图。
 
-1. 已登录 3098 后，分别进入发给自己、私聊、群聊；保留文字及一个已有附件。
-2. 将光标置于文字中间，点击表情右侧的剪刀。浏览器先选择共享来源，再在网页弹窗框选并确认；Arkme 桌面原生路径直接框选。确认新增缩略图、文字未改、光标恢复，消息未自动发送。
-3. 再次截屏按 Esc，确认原草稿不变。重复点击只能打开一个截屏流程。
-4. 拒绝系统屏幕录制权限时应出现明确提示，不生成空附件。允许权限后重试。
-5. 切换会话或账号后，迟到的图片不得出现在新会话；已完成的草稿附件仍由原有草稿规则保留。
+在设置 → 通用设置 → 通用中编辑截图快捷键。弹窗显示当前组合并接收键盘录入；确认后由客户端原子保存到用户数据目录，重新启动继续生效。取消不修改设置。录入期间暂停当前全局注册，退出弹窗、页面导航或窗口销毁时恢复。组合无效、注册被占用或保存失败时保留旧设置并显示错误。设置为此设备客户端级别，不跨设备同步。旧客户端和浏览器不显示该设置。
 
-系统权限通常属于实际启动插件的运行环境；请以 macOS 权限面板显示的应用名称为准，不修改或清空其他客户端权限。
+验证：快捷键模型、IPC 来源校验/恢复/广播、弹窗录入/确认/取消/冲突、截图触发去重和 tooltip 同步；真实 Electron 原生键盘输入与弹窗保存检查。Windows 原生快捷键与多显示器操作仍需 Windows 实机验收。

package/lib/bundle-runtime.js

@@ -1,2 +1,2 @@
-import { i as invokeArkmeBundle, n as arkmeBundleActive, r as deactivateArkmeBundle, t as applyArkmeBundleHostExtension } from "./bundle-runtime-CE73h3vS.js";
+import { i as invokeArkmeBundle, n as arkmeBundleActive, r as deactivateArkmeBundle, t as applyArkmeBundleHostExtension } from "./bundle-runtime-QUG0eHSZ.js";
 export { applyArkmeBundleHostExtension, arkmeBundleActive, deactivateArkmeBundle, invokeArkmeBundle };