dsh-screenshot-xn

dsh-screenshot-xn（DSH 截图）

简体中文 ｜ English

给 DSH Desktop 加一个截图插件：点输入框旁的按钮（或按 Alt+A）→ 屏幕整体变暗、出现独立的全屏截图面板（微信式：覆盖整屏含任务栏，DSH 窗口先被临时隐藏，所以你看到的就是真实桌面）→ 框选并标注（矩形／椭圆／箭头／画笔／马赛克／文字，可撤销重做）→ 点「插入对话／复制／另存为」，面板关闭，结果落到 DSH 里。

同一块选区还能识别文字和翻译：工具栏最左边的「识别文字」把框选区域读成可复制、可编辑的文本（默认引擎 PP-OCRv6，在本机跑，离线、无密钥；模型没就绪时回落 Windows 自带 OCR），「翻译」再把它翻成 9 种语言的任意一种（用你在 DSH 里已经配好的模型，默认零配置）；原文与译文都落在同一张结果卡片上，各自带「复制 / Copy」。

效果预览

下面三张都是真机实拍（本机 3440×1440 主屏），没有摆拍、没有合成：

① 框选 + 标注 + 区域识别（面板） —— 拖出选区后工具栏出现（第一行最左边是「识别文字」与「翻译」两个按钮），红框/椭圆、黄色箭头与手绘曲线、两个文字标注都画在选区里；下方是「识别文字」的结果卡片（引擎 ppocr-v6-small、耗时、行数，行尾「复制 / Copy」）。识别读的是屏幕上原图：画在文字上的红框不会进识别结果。

② 抓屏模式（右键截图按钮） —— 「穿透截图（隐藏 DSH）」与「普通截图（含 DSH 窗口）」，当前选中的那条前面是蓝点；选择会被记住，左键 / Alt+A 都用它。

③ DSH 插件页里的同一项配置 —— 插件 → DSH 截图（xn），下拉框写的是同一份 captureMode，改完立即生效、重启保留。

插件名：dsh-screenshot-xn（2026-09-30 由 dsh-screenshot 改名，用于和市面上同名/近名的截屏插件区分）。 目录（改名当天）仍是 E:\dshplugins\dsh-screenshot；改的只是包名与 cordis 行 id/name（插件列表与插件页显示的就是它）。 2026-10-11：仓库目录迁到 E:\dsh-screenshot-xn\dsh-screenshot（与仓库名对齐，老路径 E:\dshplugins\dsh-screenshot 作废）。目录一搬，profile 里那条 link: 就指向了不存在的路径 —— 在 DSH Desktop 2.0.17 上这是启动级故障（整个应用起不来），不是「插件不生效」：见「故障排查」第一行。 保持不变（都是冻结契约，改名不碰）：路由 /api/dsh-screenshot/*、度量头 X-DSH-Screenshot、 槽位条目 id dsh-screenshot.button / dsh-screenshot.overlay、DOM 标记 data-dsh-screenshot-ui。 同名迁移已做：活动 profile 的注册（依赖键 / bundles / 行 id+name）、captureMode 持久化覆盖、node_modules 链接。

• 代码产地：E:\dsh-screenshot-xn\dsh-screenshot（2026-10-11 起；此前为 E:\dshplugins\dsh-screenshot）
• 运行时：DSH Desktop（Windows）。宿主半依赖 Windows PowerShell 5.1 + .NET System.Drawing（系统自带，无第三方原生依赖）；独立面板用系统浏览器（Edge / Chrome）的 kiosk 窗口承载；客户端半是纯浏览器代码。
• 验证过的版本：DSH 0.1.7-rc.2、活动 profile comfyui、node v24.14.1、Windows PowerShell 5.1.26100.9444（R-06：DSH 升级后请重新目视核对槽位与路由）。

改完代码要重启 DSH Desktop：宿主半（index.js 的路由、kiosk 拉起、退出清理）只在 DSH 进程启动时加载。若宿主还是旧版，点截图会看到「独立截图面板不可用…（overlay.start http 404）」并自动回退到下面「局限」里说的 DSH 内覆盖层流程——功能不缺失，但那不是本版本的主路径。

---

安装

安装由官方 plugin_manager 工具负责，不要手写 profile 的 package.json / cordis.patch.yml，也不要在 profile 目录执行 pnpm。

1. 用 plugin_manager 的 install_bundle 指向本目录的绝对路径：

   plugin_manager
     action: install_bundle
     target: E:\dsh-screenshot-xn\dsh-screenshot
   

   该动作会调用 pnpm 把本地目录装进活动 profile，并按 package.json 的 dsh.bundle.patch 应用 cordis.patch.yml。 target 就是本仓库当前所在的绝对路径（上面是这台开发机上的路径；换机器 / 搬目录请换成你自己的）。装完后 profile 的 package.json 里会留下一条 "dsh-screenshot-xn": "link:<该路径>"，<profile>/node_modules/dsh-screenshot-xn 也指向同一目录。 这两处任意一处指向不存在的路径，DSH Desktop 2.0.17 就拒绝启动（症状与修法见「故障排查」第一行）。

2. 需要批准：安装动作（以及可能的构建脚本）会请求用户批准；未批准时安装不会生效。若返回体里出现 pendingBuilds，本插件不需要任何构建脚本，不要为它授权。

3. 记录 install_bundle 返回的 application 字段（DoD A-7）：

   application	含义与后续动作
   applied	当场生效（客户端半热加载）；宿主半的路由仍以进程启动时加载的那份为准，改过 index.js 请重启 DSH
   restart-required	需要重启 DSH Desktop 后再核对
   overridden	有更高优先级的层覆盖了本行，检查 profile 的 patch 层
   failed	看返回体的 warnings/错误原因；常见原因是 target 不是本目录的绝对路径

   前置开关（每一台新机器都要看）：整屏面板需要 DSH Desktop 放行"普通浏览器访问"。 主路径的「独立整屏截图面板」是由系统浏览器（Edge / Chrome 的 kiosk 窗口）去加载 http://127.0.0.1:<DSH 端口>/api/dsh-screenshot/overlay/page 实现的；而 DSH Desktop 的 webServer 默认只放行带渲染器令牌的请求 —— 实测 DSH Desktop 2.0.15 里 lib/webserver.js 的 permits() 每次请求现查 desktopBrowserAccess，lib/desktop-browser-access-*.js 的 decideDesktopBrowserAccess 在 ordinaryBrowserEnabled 为 false（=openBrowser 的默认值）时对一切非 Electron 渲染器请求返回 denied，于是响应是 403 + 正文就 9 个字节 forbidden。 在默认设置下，kiosk 窗口拿到的就是这个 403：插件在抓屏之前就会预检出来（desktop-browser-access-denied）， 给出可见提示，并自动回退到「DSH 内覆盖层」流程（DSH 窗口里先出一张冻结帧，再在这张图上框选）。 这不是故障，也不是装的版本不对 —— 功能不缺失，但那不是主路径。

   打开方式（任选其一，改完重启 DSH Desktop；host 半只在进程启动时加载）：

   • 界面：DSH Desktop 设置 → 「浏览器与局域网」→ 勾选「允许在浏览器中打开」。该开关只在窗口模式为「兼容模式」时可用，否则是灰的并写着「浏览器访问仅在兼容模式下可用；如需开启，请先选择兼容模式。」；

   • 配置：往当前 profile 的 cordis.patch.yml 里加下面这一行（本机就是靠它验证的，case 与缩进照抄）：

     - id: desktop-shell
       name: dsh-plugin-desktop
       config:
         mode: compatibility
         openBrowser: true
         networkExposure: loopback
     

   不打开也能用：整屏面板那一套每次都走回退路径，标注、识别、翻译、插入、复制、另存为的行为完全一样。

   前置条件 2（不要提权）：DSH Desktop 必须以普通权限运行。 被提权的父进程拉起 Chromium（Edge / Chrome）时，浏览器会走 AutoDeElevate：它检测到自己由提权进程启动就立刻退出，让 shell 以普通权限重新启动自己；命令行偏长时这次中继会把参数丢掉，于是 kiosk 根本没打开面板 URL。现象：点截图后窗口闪一下就不见了、DSH 日志里 panel files fetched: 0 (none)，而浏览器自己的日志（插件已开 --enable-logging，落在临时 profile 的 chrome_debug.log）只有一行 Edge is running elevated: 1；上游是 Chromium issue 436869753。 插件自 t81 起已在 kiosk 旗标里带上游的规避开关 --do-not-de-elevate，提权时一般也能正常打开面板 —— 代价是浏览器会一并留在提权状态（这是它唯一的副作用），所以推荐的做法始终是不要提权。 特别地，如果 DSH 的 exe 被打了兼容性层 ~ RUNASADMIN（在 HKCU\Software\Microsoft\Windows NT\CurrentVersion\AppCompatFlags\Layers 下），提权就是必然的：启动日志会直接点名（DSH is running with the RUNASADMIN compatibility layer (__COMPAT_LAYER=…)）。去掉那一层、以普通权限重启 DSH Desktop 即可。

4. 自检清单（安装 + 重启后 30 秒内可做完）：

   • 打开任意普通会话，输入框动作区出现截图按钮，悬停显示"截图 / Screenshot"；
   • 点按钮：DSH 窗口一闪（被临时隐藏后恢复），随后整个屏幕被截图面板盖住（含任务栏）。若看到的是"DSH 窗口里出现一张冻结帧"，说明上面那条前置开关还没开（已知回退，不是故障，对照下一条）；
   • 框选一块区域 → 工具栏出现 → 点「复制」→ 面板关闭、回 DSH，出现成功提示；
   • 在面板里按 Esc（或右键、或框太小）→ 面板关闭，DSH 里的草稿文字与附件与进入前完全一致；
   • 把 Edge / Chrome 都临时改名（模拟"没有浏览器"）→ 点截图出现「未找到可用的浏览器…」并照样能截（回退 DSH 内覆盖层）。
   • 点按钮后 kiosk 窗口闪一下就没有下文（既没有整屏面板，也没有冻结帧）→ 对照「安装」里的前置条件 2：DSH 提权运行时 Chromium 的 AutoDeElevate 会把这次启动整个吞掉，日志里 panel files fetched: 0 (none) 且浏览器日志只有 Edge is running elevated: 1。

---

配置

配置写在 cordis.patch.yml 那一行的 config: 里（config: {} 即全部使用默认值）。所有键都是可选的，未知键会被忽略。 其中 captureMode 比较特别：它由 Config schema 声明为 volatile 字段，并由 client 半边贡献到 DSH 插件页的 plugins.bundle.config（key = 包名 dsh-screenshot）—— 所以它会以「截图模式 / Capture mode」下拉框出现在 插件 → dsh-screenshot 那一页，和语音输入插件的「识别服务 / 识别语言」同一套机制。你在那里（或右键菜单里）改的值由 DSH 写进当前 profile 的 cordis.patch.yml（不是本插件的 bundle patch），改完立即生效、重启保留。手写 config: { captureMode: normal } 同样有效。

注：DSH 插件页只在有客户端贡献时才渲染配置区（renderSlot("plugins.bundle.config", …, { entryKey: pkg.name }) 外面那层 configured ? … : null），所以这一项必须由本插件的 client.js 贡献 —— 这是 t74 补上的最后一环。 长这样（真机实拍）：见「效果预览」的 ③ 插件页切换模式。

- insert:
    - id: dsh-screenshot-xn
      name: dsh-screenshot-xn
      config:
        timeoutMs: 20000
        cacheTtlMs: 1500
        keepTempFile: false

抓屏（宿主）

独立截图面板（覆盖层，B1）

区域识别与翻译（t75）

识别引擎（t77：默认换成 PP-OCRv6，本地跑）

Windows 自带引擎对小字中文截图很差（同一张 1978×1059 的实机截图，「截取屏幕、框选并标注，然后复制、另存为或插入当前对话。」 被读成「截取驛幂梃选并标注 然 制 、 另 存 为 或 入 当 前 对 话」）。所以默认引擎换成了 PP-OCRv6（检测 + 识别）跑在 onnxruntime-node 上：同样这张图，它能读成 DSH 截图 v1.0.0 / dsh-screenshot / 截取屏幕、框选并标注，然后复制、另存为或插入当前对话。 / 穿透截图(隐藏 DSH) / Through (hide DSH)，耗时约 1.6s（CPU、960 长边、30 行）。

依赖与体积：运行时是 npm 包 onnxruntime-node（预编译，免 Python/GPU/管理员），声明为 可选依赖：不允许构建脚本 / 装不上 / 离线时插件照样能装能用，OCR 自动回落 Windows 引擎（auto 档）。 它的 postinstall 会下载原生库，所以安装时允许构建脚本能让 OCR 更强（管理器会问）。这个包把各平台二进制都打进 tarball（实测 287MB）， 本插件带一个裁剪助手，只留当前平台：

node lib/prune-onnx-runtime.mjs            # 先看能省多少（只报告）
node lib/prune-onnx-runtime.mjs --apply    # 真删：288MB → 65MB（win-x64），重装依赖即可恢复

模型与 ONNX Runtime 都不随包分发，也不进 git。许可：PP-OCR 模型与 RapidOCR 清单为 Apache-2.0， onnxruntime-node 为 MIT；本插件只下载官方直链并按官方 SHA256 校验（清单见 lib/ocr-models.mjs）。

| translateEnabled | true | false 时翻译接口回 503 translate.disabled。翻译会真的调用你的模型（花 token），所以给了独立的开关 | | translateProvider / translateModel | 空 / 空 | 翻译用哪条模型路由；两个都留空 = 用 DSH 当前默认模型（agentDefaultModel.currentSelection()），所以默认零配置 | | translateTarget | zh-Hans | 默认目标语言，取值是 lib/ocr.mjs 里那张闭集的 id（zh-Hans/zh-Hant/en/ja/ko/fr/de/es/ru）。它只决定面板下拉框的初值：用户在卡片里改只影响本次会话 | | translateTimeoutMs | 45000 | 单次翻译的上限；到点用 AbortController 收回请求并回 504 translate.timeout | | translateMaxTokens | 4000 | 译文输出上限（一屏文字用不到更多） | | translatePrompt | 空 | 追加到 system 提示词后面的额外要求（例如"术语保持英文"），会与内置规则逐条并列 |

宿主路由（客户端半依赖它，也可用于自检）

注意：度量头用的是 base64url 字母表（-、_，无 = 填充），客户端解码时要先还原成标准 base64。

抓屏链路：index.js → lib/capture.ps1（DPI-aware，SetProcessDpiAwarenessContext(PER_MONITOR_AWARE_V2)）→ 输出 ---JSON-BEGIN--- {...} ---JSON-END---；脚本失败时以非零退出码 + ok:false 的 JSON 报错。优先使用宿主已提供的 subprocess 进程 Service，不可用时回退 node:child_process；两条路径都受 timeoutMs 约束、隐藏子进程控制台窗口、超时强制终止（D-7：无残留进程）。

抓屏时隐藏 DSH（贯穿两条路径）

• 语义：抓屏前把 DSH 自己的窗口临时隐藏（SW_HIDE，或 hideMethod: minimize），等待 hideWaitMs 让桌面合成器重绘，抓一帧，然后立即恢复（SW_RESTORE + SetForegroundWindow）。因此被 DSH 遮住的桌面内容可以截到，而且面板里看到的画面不含 DSH 界面。

• 只动自己的窗口：脚本按 ①父进程 pid ②映像名 ③标题片段 三条判据确认"这是 DSH 的窗口"，且必须是可见的顶层窗口、且不是脚本自己。任何一条都对不上就不隐藏，直接回退普通抓屏（响应仍是 200，只是 mode 回到 normal，图里含 DSH）——宁可截到 DSH，也不会去最小化用户的其它窗口。

• 恢复不依赖运气：隐藏+等待+抓屏+恢复全程在脚本的 try/finally 里；恢复判据是"窗口重新可见且未最小化"，SW_RESTORE 会重试并依次降级到 SW_SHOW/SW_SHOWNORMAL；如果脚本报 restoreOk:false，宿主还会再跑一次 -RestoreOnly 救援入口（幂等，5 s 上限）。恢复未确认时整次请求返回 502，不会把"可能停在被隐藏状态"的图交给客户端。

• 耗时（本机 3440×1440 实测，脚本内计时取 3 次中位数）：

  路径	脚本总耗时	其中隐藏段 hiddenMs	端到端（含进程启动）
  普通（不隐藏）	89 ms	0	≈ 490 ms
  隐藏再抓（hideWaitMs: 250）	539 ms	325 ms	≈ 980 ms
  隐藏再抓（hideWaitMs: 150）	442 ms	230 ms	≈ 890 ms

  即隐藏比不隐藏多约 350–450 ms。要把面板弹得更快，把 hideWaitMs 调到 150（少等待可能让个别窗口停留在半透明淡出帧上，可自行权衡）。

---

卸载

两种方式，任选其一：

1. 彻底移除：plugin_manager → action: remove_bundle，target: dsh-screenshot-xn。该动作会从活动 profile 移除包与 bundle 行；按提示重启后按钮消失，DSH 正常启动（F-4）。工作区源码目录不受影响。
2. 临时停用：plugin_manager → action: set_bundle，target: dsh-screenshot-xn，enabled: false。重启后插件不激活，输入框不受影响（D-5）；enabled: true 即可恢复。

残留检查：卸载后 %TEMP%\dsh-screenshot-xn 里最多有本插件留下的临时 PNG（正常路径下读完即删）；%TEMP%\dsh-screenshot-xn-overlay-<token> 是面板浏览器的一次性 profile，会话结束即删（强杀等异常路径可能留下空目录，可直接删除）。

---

故障排查

---

功能与交互（对照 DoD B 段）

• 入口：输入框动作区（conversation.input.right）的截图按钮，文案"截图 / Screenshot"；Alt+A 是同一入口（应用内快捷键，见"局限"）。
• 两种抓屏模式（右键菜单，C-6）：右键单击截图图标弹出模式菜单（真机实拍见「效果预览」的 ② 右键菜单切换模式），选「穿透截图（隐藏 DSH）」（默认）或「普通截图（含 DSH 窗口）」：
  • 穿透：抓屏前临时隐藏 DSH、抓完恢复，画面里没有 DSH（正常截图都用这个）；
  • 普通：不隐藏，画面里就是有 DSH 窗口（用来截 DSH 自己的界面）；这种情况下面板的提示行会写明「普通模式：这次画面里包含 DSH 窗口…」，DSH 侧也会给一条「普通模式：本次画面会包含 DSH 窗口」的提示 —— 不会让你以为是插件坏了；
  • 选择会被记住（t73）：选完立刻写回宿主 → 宿主写进插件配置（captureMode，也就是设置页 / 插件管理里那一项，落在当前 profile 的 patch 里），因此 DSH 重启后不用重选；左键 / Alt+A 都用记住的模式；菜单本身不触发截图（截图永远由左键 / Alt+A 显式触发）。菜单支持键盘：↑↓ 移动、Enter/Space 选定、Esc 或点外面关闭，按钮上有 aria-haspopup="menu" / aria-expanded。
  • 两种切法等价：右键菜单（顺