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

English | 中文

模型侧 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 各自遵循其许可证。