dsh-composer-image-tools

Readme

# 🖼️ dsh-composer-image-tools · 聊天输入框图片工具

> 给 DSH 聊天输入框补上"看图"的入口 —— 上传图片 + 自定义区域截图，**自研实现**，零依赖。
> **Image tools for the DeepSeek Harness composer: upload & region-screenshot, straight into the draft.**

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![DSH](https://img.shields.io/badge/DSH-0.1.0--rc.7-4D6BFE.svg)](https://github.com/deepseek-ai/deepseek-harness)
[![GitHub](https://img.shields.io/badge/GitHub-ai--yucheng-181717?logo=github)](https://github.com/ai-yucheng/dsh-composer-image-tools)

在 DSH 聊天输入框工具栏加两个按钮：**📎 上传图片** 和 **📷 区域截图**。图片进入 DSH 草稿图片轨，随消息发送，可被 modlens / describe-image 等图片插件读取——让模型真正"看见"你发的图。

---

## 📖 目录

- [🎯 这是什么？](#-这是什么)
- [✨ 核心功能](#-核心功能)
- [🧠 工作原理](#-工作原理)
- [🚀 快速开始（小白向，2 分钟）](#-快速开始小白向2-分钟)
- [🎯 使用教程](#-使用教程)
- [❓ 常见问题 FAQ](#-常见问题-faq)
- [📸 示例截图](#-示例截图)
- [🤝 配套项目](#-配套项目)
- [📜 更新日志](#-更新日志)
- [📄 协议](#-协议)

---

## 🎯 这是什么？

| 能力 | 说明 |
|---|---|
| 📎 **上传图片** | 打开系统文件选择器（可多选），图片注入草稿，随消息发送。超过 **10MB** 自动拦截（超大图按 tile 计费消耗大量 token） |
| 📷 **区域截图** | **自定义位置截图**：点击 → 全屏显示捕获画面 → 鼠标拖拽框选任意区域 → 裁剪成 PNG 注入草稿。不依赖微信/任何外部截图工具；`Esc` 取消 |

> 💡 **微信 Alt+A 截图怎么办？** DSH 原生支持 **Ctrl+V 粘贴图片**——Alt+A 截图后直接在输入框 Ctrl+V 即可。📷 按钮是"自定义框选截图"的独立能力，两者互不干扰，满足"没登录微信也要能截图"的场景。

---

## ✨ 核心功能

### 📎 上传图片

- 多选图片，注入 DSH 官方草稿图片轨（与拖拽上传同一路径）
- **≤10MB 限制**：超限文件拦截并提示（"超大图片会消耗大量token"），未超限的正常上传
- 按钮悬停显示限制说明

### 📷 区域截图（自定义框选）

- **不依赖浏览器 getDisplayMedia**（在 DSH 的 Electron 环境实测 `NotSupportedError`）——改走**插件服务端**（Electron 主进程 `desktopCapturer`）截取整屏
- 前端全屏遮罩显示捕获画面 → **鼠标拖拽框选** → 松开即裁剪注入
- 坐标换算零偏移：显示尺寸由 JS 精确计算，选框用屏幕坐标直算
- `Esc` 取消；选区 <5px 自动取消；截屏失败有可操作提示

### 🛡️ 设计特点

- 纯客户端能力零依赖；服务端仅一个截屏路由
- 图标、样式、交互全部自研（未复制任何现成插件代码），CSS 前缀 `dcit-` 防冲突
- 与 dsh-audio-copilot 的 🎤 麦克风按钮同栏并排

---

## 🧠 工作原理

```
┌──────────────────────── 浏览器端 (dsh.client) ────────────────────────┐
│  聊天输入框工具栏 ── 📎 上传  📷 截图（与 🎤 同栏）                    │
│                                                                      │
│  📎 上传：input[type=file] 多选 → 构造 DataTransfer → 合成 drop 事件  │
│          → DSH document 级 drop 监听 → createDraftImages（官方路径） │
│                                                                      │
│  📷 截图：GET /composer-image-tools/capture-screen（fetch）           │
│          → 拿到整屏 PNG → 全屏遮罩 → 拖拽框选 → 裁剪 → 同样合成 drop │
└───────────────┬────────────────────────────────────────────────────────┘
                ▼
┌──────────────────────── 服务端 (cordis 插件) ──────────────────────────┐
│  GET /composer-image-tools/capture-screen                             │
│    Electron desktopCapturer 截取主屏 → PNG base64 返回                 │
│    （浏览器 getDisplayMedia 在 Electron 不可用，必须走主进程）          │
└────────────────────────────────────────────────────────────────────────┘
```

---

## 🚀 快速开始（小白向，2 分钟）

### 第 0 步：确认前置

- **DSH Desktop** 已安装
- **Node.js ≥ 20**（DSH 自带）

### 第 1 步：安装插件

在 DSH 的 profile web 目录执行：

```bash
# 方式 A：GitHub 源码（推荐）
git clone https://github.com/ai-yucheng/dsh-composer-image-tools.git
pnpm add dsh-composer-image-tools@link:C:/绝对路径/dsh-composer-image-tools

# 方式 B：npm（若已发布）
pnpm add dsh-composer-image-tools
```

在 profile 的 `package.json` → `dsh.profile.bundles` 数组追加：

```json
"dsh-composer-image-tools"
```

### 第 2 步：重启 + 验证

1. **重启 DSH Desktop**（服务端截屏路由生效）
2. **硬刷新浏览器** Ctrl+Shift+R
3. 聊天框工具栏出现 📎 和 📷 按钮 → 🎉

---

## 🎯 使用教程

### 上传图片

1. 点击工具栏 **📎** 按钮
2. 系统文件选择器里选一张或多张图片（≤10MB）
3. 图片出现在输入框上方草稿区
4. 输入文字（可选）→ 发送

### 区域截图

1. 点击工具栏 **📷** 按钮
2. 屏幕被全屏遮罩覆盖，顶部提示"拖动鼠标框选截图区域 · Esc 取消"
3. **按住左键拖拽**框选想要截取的区域 → 松开
4. 选区自动裁剪成图片出现在草稿区 → 发送

> 不想截了：按 `Esc` 取消。

### 微信 Alt+A 截图

Alt+A 截图后（图在剪贴板）→ 直接在输入框 **Ctrl+V** 粘贴即可，无需点任何按钮。

---

## ❓ 常见问题 FAQ

**Q：按钮不出现？**
重启 DSH + 硬刷新；确认 `dsh.profile.bundles` 已加本插件。

**Q：点 📷 提示"截图服务未就绪:请重启 DSH"？**
服务端截屏路由未加载——重启 DSH Desktop 即可（路由在插件服务端注册）。

**Q：上传超大图没反应？**
超 10MB 会被拦截并 toast 提示，这是设计（防烧 token）。

**Q：📷 框选有偏移？**
已修复：坐标由 JS 精确计算，选框直接跟随鼠标。如仍有偏移请反馈（附 DSH 版本）。

**Q：截图会依赖微信吗？**
不依赖。📷 是独立的自定义框选截图；微信 Alt+A 走 DSH 原生 Ctrl+V，两者分开。

---

## 📸 示例截图

| 使用界面 | 本地上传 | 相机框选 | 输入框图片工具 |
|---|---|---|---|
| ![使用界面](docs/screenshots/使用界面.png) | ![本地上传](docs/screenshots/本地上传.png) | ![相机框选](docs/screenshots/相机框选.png) | ![输入框图片工具](docs/screenshots/输入框图片工具.png) |

---

## 🤝 配套项目

同系列 DSH 插件（均为自研，开源）：

- [**dsh-audio-copilot**](https://github.com/ai-yucheng/dsh-audio-copilot) —— 语音工作台：🎤 语音输入按钮（多引擎转写，中文/方言/外语）+ 🔊 文字转语音 + audio_probe/ask 工具。与本插件的 📎📷 按钮同栏并排。

---

## 📜 更新日志

详见 [CHANGELOG.md](CHANGELOG.md)。关键里程碑：

- `0.1.0` — 区域截图改走主进程 desktopCapturer（修复 Electron 下 getDisplayMedia 不可用）、上传大小限制、框选零偏移

---

## 📄 协议

MIT © [ai-yucheng](https://github.com/ai-yucheng)