dsh-image-to-path

Readme

# dsh-image-to-path

**让 DSH 纯文本模型对话也能拖图/贴图:图片自动保存到会话工作区,以文件路径交给模型。**

*Let DSH text-only-model conversations accept images: saved to the session workspace and handed to the model as a file path.*

[English](README.en.md) | [中文](README.md)

![DSH](https://img.shields.io/badge/DSH-0.1.x-4c1d95) ![Version](https://img.shields.io/badge/version-0.1.0-blue) ![License](https://img.shields.io/badge/license-MIT-green)

## 解决什么问题

DSH WebUI 把拖入的图片作为 base64 附件发送,纯文本模型会直接拒绝——**无论装没装视觉工具,只要当前对话是纯文本模型,图片就发不出去**。本插件接管拖放/粘贴,把图片保存到当前会话工作区,以**路径文本**插入输入框,模型拿到路径后可交给任何工具(包括视觉工具)处理。

- **多模态模型不受影响**:自动检测当前模型能力,支持图片的模型走原生附件通道,只有纯文本模型才走路径方案;
- **没有视觉工具也能用**:发送的只是路径文本;提示会如实告知当前环境能否看图;
- **不产生重复拷贝**:内容寻址去重,同一张图只落一份;工作区已有的图直接原位引用。

## 安装

```sh
# 本地开发(先 pnpm install 装全 peer 依赖)
dsh plugin --profile web add /path/to/dsh-image-to-path

# 从 GitHub(仓库已提交 lib/,免构建授权)
dsh plugin --profile web add github:cesaryike/dsh-image-to-path

# 或 tarball
pnpm pack && dsh plugin --profile web add ./dsh-image-to-path-0.1.0.tgz
```

安装后重启 Web Profile 生效。

## 使用

拖入或粘贴图片即可:图片保存到工作区的 `dsh-image-to-path-uploads/` 目录,输入框出现**文件名芯片**,发送时模型收到完整路径。该目录可随时手动清理,不影响插件。

## 配置

| 字段 | 默认 | 说明 |
|---|---|---|
| `subdir` | `dsh-image-to-path-uploads` | 保存子目录 |
| `maxImageBytes` | `10485760` | 单图上限(10 MiB) |
| `interceptUnknownModels` | `false` | 未声明能力的模型是否按纯文本拦截(内置适配器均声明,一般无需改动)。注意:即使开启,provider 未注册或能力查询失败时仍按放行处理(fail-open),并在宿主日志记录警告 |

按行 id `image-to-path` 在 profile 的 `cordis.patch.yml` 中覆盖。

## 工作原理

```
拖图/贴图 → 当前模型支持图片?→ 是:原生附件通道(体验不变)
                          → 否(纯文本):上传 → 魔数校验 → SHA-256 去重 → 原子写入工作区
                          → 引用芯片插入输入框 → 发送时序列化为路径文本 → 模型/视觉工具
```

## 安全

仅接受图片魔数、服务端命名、原子写、10 MiB 上限、同源校验;无任何远程请求。

## 许可

[MIT](LICENSE)

## 贡献者

- [cesaryike](https://github.com/cesaryike):作者——产品定义、功能方向、文档与发布;
- DeepSeek AI(DSH agent):核心工程实现与修复(见提交历史)。