@dsh-external/dsh-image-tiler

Readme

# @dsh-external/dsh-image-tiler

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

DSH 高清图自动切片插件：发送前把大图切成 **≤800×800 的小图**，绕过 DeepSeek API 后端把图片统一压到 800×800 导致的细节丢失。

## 功能

- 仅对 DeepSeek provider（`deepseek` / `deepseek-official`）生效。
- 自动在 `agent/pre-step` 改写用户新上传的图片消息：读原图 → sharp 切片（默认 10% 重叠）→ 保存为 DSH 附件 → 替换为多张图片块。
- 已 ≤800px 的图片、GIF 原样透传。
- 插件设置 → “高清图切片”卡片，可开关、调切片边长和重叠率。

## 构建与注入

> ⚠️ 构建脚本依赖本机存在 DeepSeek Harness（DSH）源码 checkout。公开环境请在安装/构建前准备好 DSH checkout，并通过 `DSH_CHECKOUT` 指向它。

```bash
# 1. 准备 DSH checkout 后执行：
DSH_CHECKOUT=<deepseek-harness-checkout> npm install

# 2. 构建 host 与 client
npm run build

# 3. 注入器环境内：
dev_inject_plugin <本目录>
```

如果没有设置 `DSH_CHECKOUT`，构建脚本会尝试探测常见路径，例如：

```text
~/Downloads/deepseek-harness-master
~/dsh-harness
~/dsh
~/.dsh/dsh-harness
```

## 配置

| 字段 | 默认 | 说明 |
| --- | --- | --- |
| `enabled` | `true` | 总开关 |
| `tileSize` | `800` | 切片边长（px），64~2000 |
| `overlap` | `0.1` | 相邻切片重叠比例，0~0.5 |

配置写入 DSH 设置文件（namespace `image-tiler`），设置页通过 `/image-tiler/api/config` 读写，仅允许本机回环访问。

## ⚠️ 使用前需要调高 DSH 图片准入上限

DSH 默认在**上传阶段**就会拒绝任一边超过 `2000px` 的图片，插件还没机会切片。要支持 4K 原图，请在 profile 的 `cordis.patch.yml` 中加入：

```yaml
- id: attachment-local
  config:
    maxImageBytes: 20971520
    maxImagesPerMessage: 30
    maxMessageImageBytes: 104857600
    maxImagePixels: 80000000
    maxImageDimension: 4096
```

修改后 DSH 通常会热重载；如果没生效，重启 DSH Web。

## 已知边界

- 只处理用户新上传/新消息里的图片；`read_image` 工具结果里的图片暂不处理。
- 若切片过程中出错，会保留原图并记录警告，不阻断对话。
- 公开环境构建需要 DSH checkout；GitHub Actions 当前只做轻量 typecheck + 单元测试，不执行完整构建。

## 相关文档

- [更新日志](CHANGELOG.md)
- [安全说明](SECURITY.md)
- [贡献指南](CONTRIBUTING.md)
- [行为准则](CODE_OF_CONDUCT.md)

## 许可证

[BSD-3-Clause](LICENSE)

本项目允许任何人**二次修改、传播、商用**，只要求保留原项目署名及本声明。没有“禁止盈利”之类的限制。

## AI 参与声明 / 高度 AI 属性

本项目具有**高度 AI 性质**：

- 本项目由 **TIKO** 发起。
- 设计、编码、测试、文档整理由 **DeepSeek** 大量参与完成。
- **本插件仅由 DeepSeek 参与，没有其他 AI 参与。**
- **连项目提交都是 DeepSeek 操作的。**

任何人若基于本项目二次修改或传播，请保留：

- 原项目名 `dsh-image-tiler`
- 原作者署名 **TIKO**
- 本 AI 参与声明
- 本项目许可证与版权声明