@max-null/dsh-capture

Readme

# @max-null/dsh-capture

> 源码仓库：https://github.com/Max-Null/dsh-capture（npm: `@max-null/dsh-capture`）

本插件属于 **`@max-null/*` 插件系列**——这一系列共同构成 **[SSID（思灵 · Seek Soul in Darkness）](https://github.com/Max-Null/seek-soul-in-darkness)** 桌面体验。SSID 是整合它们的盒：`dsh-capture` · `dsh-chat-rail` · `dsh-chinese-thinking` · `dsh-draft-polish` · `dsh-guardian` · `dsh-habit` · `dsh-memory` · `dsh-node-appearance` · `dsh-plugin-center` · `dsh-quick-toolbar` · `dsh-skill-mcp-center` · `dsh-ssid-panels` · `dsh-ssid-zh-ui` · `dsh-achievements`。
This plugin belongs to the **`@max-null/*` family** — a set of plugins that together form the **[SSID (思灵 · Seek Soul in Darkness)](https://github.com/Max-Null/seek-soul-in-darkness)** desktop experience.

DSH 双引擎快捷截图引用：框选屏幕任意区域 → 标注（矩形/椭圆/**箭头**/**文字**，
8 色可选）→ 图片自动进入**当前会话的输入框**（作为图片附件草稿，可加文字、
可删除，回车才发送）。**有标注时投递「原图 + 编辑图」两张**——原图不遮挡任何
原始内容，编辑图承载框/箭头/文字的强调，帮助理解方（人/模型）对照上下文。

**原图预览编辑闭环**：任何已插入的图片（截图/上传/历史消息）打开「原图预览」
即可直接 ✎ 编辑（整图标注，同一套工具），完成后编辑图自动投递，无需重新截图。

## 截图速览

### 框选与标注

| 截图时（框选选区） | 编辑模式（进入时，尚未标注） | 画箭头 / 文字（标注后） |
| --- | --- | --- |
| ![截图时](shot/截图时.png) | ![编辑截图时](shot/编辑截图时.png) | ![使用截图工具](shot/使用截图工具.png) |

### 投递结果与原图预览编辑

| 确认后插入原图和编辑图 | 图片预览时编辑按钮位置 | 图片预览时编辑页 |
| --- | --- | --- |
| ![确认后插入原图和编辑图的截图](shot/确认后插入原图和编辑图的截图.png) | ![图片预览时编辑按钮位置截图](shot/图片预览时编辑按钮位置截图.png) | ![图片预览时编辑页](shot/图片预览时编辑页.png) |

### 设置

| 设置页 |
| --- |
| ![设置页截图](shot/设置页截图.png) |

## 双引擎

| | 思灵壳（SSiD）内 | 纯 DSH（浏览器） |
| --- | --- | --- |
| 触发 | 托盘「截图引用」＋ 全局快捷键（设置→通用修改）＋ 输入框相机按钮 | 输入框相机按钮 |
| 捕获 | desktopCapturer 逐屏抓帧：多显示器、像素级 1:1、全屏无边框浮层 | `getDisplayMedia` 系统选择器（一次选一个屏幕） |
| 遮蔽 | 独立浮层窗口（DSH 页面零侵入） | 页面内全屏遮罩（框选 + 标注交互相同） |
| 隐藏窗口 | ✅（设置→通用「截图时隐藏思灵窗口」） | ❌（无此能力，设置行自动隐藏） |
| 投递 | 官方 composer 图片 intake（合成 drop，与拖拽等价） | 同左 |

运行时探测（host 的 shellAvailable）自动选择引擎；无壳时按钮点击即走浏览器捕获。

## 标注能力

- **矩形 / 椭圆框**：拖拽绘制，实时预览 + 合成（带同色半透明填充）
- **箭头**：拖拽指向要改的内容，头翼自动按方向绘制
- **文字**：点一下放置锚点内联输入，回车提交；文字带细黑描边（任意底色可读，无背景块）
- **8 色调色板**：红橙黄绿青紫品红白，每条标注独立着色（默认红）
- 撤销/逐级回退（右键或 Esc）：画框中 → 撤标注 → 重选 → 退出

## 操作（思灵壳内）

1. 打开任意 DSH 会话（没有会话时截图不会进入任何地方）。
2. 托盘 →「截图引用」，或按全局快捷键（默认 `Ctrl+Shift+A`）。
3. 屏上出现冻结帧 + 十字准星：
   - **左键拖拽** 框选区域 → 选区定格后出现**工具条**（选区旁，微信式）。
   - 工具条选色/选工具后 **左键拖拽**（箭头）/ **点一下**（文字）标注；
     **回车 / 双击 /「完成」** 一次确认发送。
   - **右键 / Esc** 逐级回退：标注中 → 撤标注 → 重选 → 退出截图。
4. 图片出现在输入框图片位；可追加文字后回车发送。

## 操作（纯 DSH）

1. 打开任意 DSH 会话；点输入框相机按钮（润色按钮左侧）。
2. 浏览器弹出「选择要共享的屏幕」→ 选一个屏幕 → 捕获一帧后自动停止共享。
3. 页面全屏遮罩出现：**左键拖拽**框选 → 选区工具条出现 → 同画面标注 →
   回车/「完成」发送；**右键/Esc** 逐级回退。

## 原图预览编辑

1. 任意图片（草稿附件或消息图片）点击缩略图 → DSH「原图预览」对话框。
2. 预览右上角 **✎ 编辑按钮**（官方关闭按钮旁）→ 整图编辑浮层（不必框选）。
3. 标注（同截图工具）→ **完成**：编辑图投递到输入框，预览窗口随编辑一并关闭；
   未标注直接完成 = 视为未修改，关闭且不投递；取消/回退放弃编辑，预览保留。

## 设置（思灵壳内：设置 → 通用）

- **截图时隐藏思灵窗口**：开 = 冻结帧不含思灵自身（引用其他应用）；关 = 冻结帧包含
  思灵（可框选对话内容）。默认开。
- **截图全局快捷键**：Electron accelerator 语法（如 `Control+Alt+B`），回车/失焦即
  保存并立即重注册。

## 实现要点（维护者）

- 本仓库是插件**唯一源码真身**（lib/ 为构建产物，不入库：`pnpm install && pnpm run build`）。
  思灵（SSiD）安装包以 `shell/profile-template/vendor/dsh-capture`（构建产物
  拷贝）作为内置分发载体，本仓库之外不再维护第二份源码。
- 壳层（engine A）在思灵仓库 `shell/main.mjs` + `shell/screenshot.html`：`desktopCapturer`
  逐屏抓帧 → 每屏一个全屏无边框置顶浮层（不侵入 DSH 页面 DOM）→ 单阶段标注
  （选区工具条 + 原图坐标系绘制，合成时按选区裁剪）→ `executeJavaScript`
  派发 `ssid:screenshot` CustomEvent（v2 协议 `{ uid, source, annotated? }`，
  主进程带 uid；旧版字符串监听器自然失效，防双投递）。
- 浏览器（engine B）在 `src/client/CaptureOverlay.tsx`：`getDisplayMedia` 抓帧 →
  `createPortal` 全屏遮罩（同一套框选/标注交互）→ 官方 drop intake。
- 原图预览编辑在 `src/client/ImagePreviewEdit.tsx`：MutationObserver 探测官方
  ImageLightbox（`role=dialog` + `aria-label` 原图预览/Original image preview，
  不依赖 CSS hash），注入 ✎ 按钮；复用 CaptureOverlay 的 immediate 整图模式。
- 投递：`delivery.ts` 的合成 drop（`new DataTransfer()` + `DragEvent('drop')`）走 DSH
  官方 composer 图片 intake（ui-attachment 的 document 级 drop 处理器）。无 DSH 核心
  改动；数量/大小/类型限制与官方拖拽一致。
- host 半 `/ssid/api/screenshot/{get,set,trigger}`（trusted-fence 同 panels）；
  壳能力经 `ssid.shell.screenshot` 服务注入（bare dsh web 时 shellAvailable=false，
  引擎 B 接管）。
- 浮层 3 分钟无交互自动取消（防卡屏；交互随时重置）。

## 已知边界

- 纯 DSH：一次一个屏幕（系统选择器选）；无法隐藏宿主窗口（设置行自动隐藏）；
  无法使用全局快捷键（无壳机制）。
- 无当前会话时截图静默丢弃（浮层文案已提示「先打开一个会话」）。
- 模型不支持图片时由 DSH 官方提示。
- 原图预览编辑投递的是**编辑图**（原图已在对话里，不再重复投递）。