fulander0301/dsh-tool-read-tiff

dsh-tool-read-tiff — TIFF 读取工具插件

dsh-plugin

模型侧 read_tiff 工具：为纯文本模型（DeepSeek V4 等）提供读取 TIFF/TIF 图片的能力——
这是普通视觉管线与浏览器都无法直接处理的格式。每次调用加载一个 TIFF（本地文件路径或
http(s) URL），把指定页解码成可预览的 PNG，并返回完整的头部元数据（尺寸、页数、压缩方式、
光度解释、各通道位深、字节序）。配置了视觉端点后，它还会把解码出的 PNG 交给 OpenAI 兼容的
视觉模型描述；只有文本与元数据进入对话，TIFF 与 PNG 的字节绝不进入会话记录。

解码由 sharp（libvips + libtiff）完成，常见的真实 TIFF
变体开箱即用：经典与 BigTIFF、多页、LZW / Deflate / PackBits / CCITT Group 3 & 4 / JPEG
压缩、二值（1-bit）、8/16 位与浮点采样。

能力

| 能力 | 说明 |
| --- | --- |
| 两种输入 | 本地绝对路径，或 http(s) URL（拒绝重定向） |
| 解码 + 转换 | 把指定页解码成 PNG，写到源文件旁（URL 输入则写到 outputDir / 系统临时目录）；路径经 convertedPath 返回，会话中可直接预览 |
| 完整头部元数据 | width / height / pages / page / channels / depth / space / density，外加 TIFF 特有信息：compression（lzw、deflate、ccitt-group4、jpeg、none…）、photometric（rgb、black-is-zero、cmyk…）、bitsPerSample、samplesPerPixel、byteOrder、variant（classic / bigtiff） |
| 多页 | page 是零基页索引；pages 报告总页数，模型可逐页遍历多页传真 / 扫描件 |
| 可选视觉 | 配置 baseURL + model 后，解码出的 PNG 发给 OpenAI 兼容端点（Chat Completions），答案以 text 返回；prompt 参数携带你的精确指令 |
| 无配置也能组合 | 未配置端点时，工具仍解码 + 转换 + 报告元数据，并返回 note 引导模型对 convertedPath 调用 describe_image |
| 实时配置卡 | 设置 → 插件配置 → 「TIFF reading」卡修改 baseURL / model / API key / 各项上限，即时生效，无需重启 |

安全模型

- 视觉请求与 URL 下载均拒绝 HTTP 重定向（redirect: 'error'），bearer 凭证与图片字节
不会转发到部署配置之外的源。
- 视觉请求体携带 base64 PNG 但不携带密钥；不记录请求头与已解析凭证。
- 仅接受 http(s) URL 与本地路径，其余 URL 协议一律拒绝。
- 响应体先按上限截断再解析；错误摘要有界（200 字符）。
- TIFF 与 PNG 字节绝不返回进对话——只有文本与元数据。

安装

本插件是标准 cordis bundle。从 GitHub 安装到 web profile（prepare 脚本会在安装时自动编译；
若 pnpm 提示，需在 pnpm-workspace.yaml 的 allowBuilds 里放行 sharp）：

dsh plugin --profile web add git+https://github.com/fulander0301/dsh-tool-read-tiff.git

或从本地检出安装：

dsh plugin --profile web add file:/path/to/dsh-tool-read-tiff

然后重启 dsh web。bundle 声明 sharp 与 schemastery 为运行时依赖；@deepseek-ai/* 服务
从 dsh 安装解析，与其它 dsh-web-ui 工具插件一致。

配置

工具零配置即可用（仅解码 + 转换 + 元数据）。要启用一步到位的视觉描述，配置视觉端点
（设置 → 插件配置 → 「TIFF reading」，或组合条目）：

| 键 | 默认 | 含义 |
| --- | --- | --- |
| baseURL | — | OpenAI 兼容端点根（如 https://dashscope.aliyuncs.com/compatible-mode/v1），末尾斜杠自动去除 |
| model | — | 视觉模型 id |
| apiKey | — | 内联密钥；建议用 apiKeyEnv |
| apiKeyEnv | VISION_API_KEY | 密钥所在环境变量名（与 describe-image 工具共用约定） |
| defaultPrompt | 见源码 | 调用未带 prompt 时的指令 |
| maxBytes | 67108864 | TIFF 字节上限（本地文件与下载一致） |
| maxOutputTokens | 1024 | 发送给视觉模型的输出 token 上限 |
| timeoutMs | 60000 | 单次视觉请求超时 |
| outputDir | —（URL 输入用临时目录） | 非本地文件来源时转换 PNG 的落盘目录 |

带配置的挂载示例（cordis.patch.yml / 组合文件）：

- id: read-tiff
name: 'dsh-tool-read-tiff'
config:
baseURL: https://dashscope.aliyuncs.com/compatible-mode/v1
model: qwen-vl-max
apiKey: !!js process.env.VISION_API_KEY

使用

把工具指向一个 TIFF，并（可选）给视觉模型精确指令：

- 「转录这份扫描传真里的全部文字」
- 「把表格提取为 CSV」
- 「描述地图要素与投影」
- 「角落里的标签写的是什么」

多页文件用 page: 1、page: 2 逐页调用；pages 告诉你总共有多少页。未配置视觉端点时，
工具仍返回全部解码信息与 convertedPath，可交给已安装的 describe_image 工具查看内容。

已知限制

- 每次调用一页：多页 TIFF 经 page 逐页读取。
- 极大或特殊的 TIFF（复杂浮点多波段科学栅格）可能需要预处理；无法解码时工具会以清晰信息
返回 sharp 的错误。
- 可选视觉步骤仅支持 Chat Completions 协议。

许可证

MIT（插件本身）；sharp 与 schemastery 各自遵循其许可证。