Nicholas023/vision-exp-tile

写在前面

这个插件是我用 DeepSeek Harness 写的——我本人没有写代码相关的知识，这个插件只是提供一个思路，外加自用。

DeepSeek-v4-flash-vision-exp 发布后，官方会把大图压缩到 800×800 像素，为了不丢失图片细节，就让 DeepSeek 帮我写了这个插件。

各位随意取用：有问题可以提交 Issue（如果能自己改的话就更好了——你提交了 Issue，我也只能给 DeepSeek 看然后让他自己改；我本人尝试过多次，均未学会任何写代码的能力，也是乘上 AI 的东风，让我有了开发插件的能力）。

本次更新（v0.4.2）完全由 DeepSeek Harness 自主完成，内容：
① 与 picturereader 共存分工引导：探测 picturereader 是否在场（注册表工具 image_scan / 插件目录双通道），在场时给本插件三个工具（vision_tile_split / vision_tile_recognize / vision_region_crop）的末尾追加一句分工引导——大图切块/批量/区域识别用本插件，小图/像素级/整页文档用 picturereader 的 image_scan/image_ocr/image_batch/document_to_image；省模型空转轮数。不在场则工具描述与以前逐字节一致（零回归）。
② 视觉端点复用：picturereader 已在 settings.yaml 配好的 vlm_base/vlm_model，当本插件 baseURL/model 未显式设置时直接复用（免重复配置；用户显式 > peer > 默认）。
③ OCR venv 共享：本插件默认 venv 缺失时，复用 picturereader 已建好的 paddle_venv/rapid_venv（同目录 $HOME/，失败安全回退）。
④ 其余：新增 tests/peer.test.js（共存探测/分工/peer 配置读取/venv 优先级）；无新 npm 依赖，不改动 picturereader 任何文件。
⑤ 致谢与边界声明：本版与上游 picturereader（MIT；作者 @jing-hy，感谢上游作者与社区）做了共存协作优化。本插件保持完全独立：不安装 picturereader 时功能与旧版完全一致；所有协作探测失败都会安全回退（自动当作"未安装"）；双方互不修改、互不占用——picturereader 的代码、配置与文件均不被本插件改动。

vision-exp-tile ◆ 为 deepseek-v4-flash-vision-exp 定制的大图智能识图插件

简介：DSH（DeepSeek Harness）插件——大图智能识别：整图预检 → 本地 OCR + 像素网格转录文字 → 兴趣点区域按比例切块（最长边 800）让视觉模型精读 → 自动汇总；支持模型编排（smart）/ 全自动（pipeline）/ 全图网格（full）三种策略。为 deepseek-v4-flash-vision-exp 量身定制，识别大图"看不清"的最后一公里。

MIT License
node
version
DSH

独立 DSH 插件：零依赖任何第三方 DSH 插件（picturereader 等均未使用，仅用纯官方 DSH 服务 + 可选开源 OCR 环境）。把大图切成 800×800 无损小块（官方缩放规则的"甜蜜点"：块在模型侧不被降采样、每块≤384 token），携带坐标标注 + 分块聚合逻辑直接调用 DeepSeek 视觉 API 完成识别与聚合，返回结构化答案（不统计 token、不计算费用）。

🎬 宣传片（v0.4.0）

▶️ 观看宣传片（128 秒 · 带 BGM · 含致谢页）
视频背景音乐：《春景故人来》—— 铁痕电台-MSR × Kirara Magic；DeepSeek 官方鲸鱼形象（deepseek.com）。

一、为什么要 800×800

官方文档（api-docs.deepseek.com/guides/vision）规定：每张图进模型前自动缩放——总像素  推荐用 npm run selfcheck（即 node scripts/self-check.mjs）：先自动识别设备（CPU/内存/GPU → 档位），再问"是否运行全量测试？"（一般推荐运行，因为要根据实测确认插件可用性），并按设备档位自动注入超时/倍率跑测试。慢机仍超时？在设置页「图像识别→高级」调高 ocr_pool_timeout_ms（或设 performance_tier=slow），或开启 test_skip_timing 声明跳过时序敏感断言（对应环境变量 VISION_TEST_SKIP_TIMING=1）。

1. npm test：网格/坐标/提示模板/mock API 全部通过（新增 device/suite-env 纯逻辑测试）；
2. dsh --profile vision-test --dump-config：输出树中应出现 vision-exp-tile 行；
3. 启动 dsh --profile vision-test --port 3081 → 新会话 → 工具列表出现 vision_tile_split / vision_tile_recognize；
4. 上传一张 4000×3000 测试图 → 调 vision_tile_split → 检查输出目录 20 块 + overview + 坐标清单；
5. 调 vision_tile_recognize（需环境变量 DEEPSEEK_API_KEY 有值）→ 检查结构化识别答案与统计（不显示 token/费用）。

六、开发与测试工作流（双环境）

插件的任何改动都先在隔离测试实例验证，确认无误后再让正式实例生效——两者共用同一份源码（junction），互不干扰。

| 端口 | 实例 | 用途 |
|---|---|---|
| 3080 | web profile（正式） | 日常使用（生产环境） |
| 3081 | vision-test profile（隔离测试） | 改动验证、实验，零风险 |

标准流程（改插件源码时）

1. 在 3081 验证（改动后）：
一键：校验挂载 + 启动测试实例（自动拆建 junction）
powershell -ExecutionPolicy Bypass -File .\scripts\run-test-profile.ps1
浏览器打开 http://127.0.0.1:3081 → 新会话问"列出工具" → 真实跑一张图

2. 3081 通过后，重启 3080 让正式实例加载新代码（dsh web 重启即可；宿主插件不热重载）；
3. 改动即时性：源码经 junction 直连 → 重启对应实例即生效，无需重新安装/构建。

依赖版本约束（重要）

- 插件的 sharp 版本必须与 DSH 内置 sharp 一致（当前两者均为 0.35.3）；
- 若不一致，同进程会出现两个 sharp 原生库，报 colourspace: parameter space not set 类错误；
- 升级 DSH 后如遇该错误：npm install sharp@（DSH 版本见 node_modules\@deepseek-ai\dsh\node_modules\sharp\package.json）。

环境重置
- 关闭 3081：Ctrl+C（或联系杀掉进程）；
- 彻底清理测试环境：删除 ~/.dsh/profiles/vision-test 与 ~/.dsh/plugins/vision-exp-tile（正式 profile 不受影响）；
- 正式环境卸载/回滚：powershell -File .\scripts\install-to-web-profile.ps1 -Rollback（自动还原 package.json 备份）。

七、依赖与适配（对其他用户环境）

最低要求（人人可跑）：DSH 基础环境（tools/fs 服务，官方 dsh-base 自带）· Node ≥ 20 · DeepSeek API key（环境变量 DEEPSEEK_API_KEY）· npm install（sharp/pngjs/jpeg-js，sharp 有全平台预编译二进制）。

| 能力 | 依赖 | 缺失时的表现 |
|---|---|---|
| 切块 / 预检 / 兴趣点识别 / 像素网格 | 插件自带（pixelgrid 自实现，不依赖任何其它插件） | ✅ 始终可用 |
| pipeline 本地 OCR | 探测本机 paddle_venv / rapid_venv（$HOME 下，路径可用 DSH_PADDLE_PYTHON/DSH_RAPID_PYTHON 覆盖）→ 无则用 Windows OCR（WinRT，零依赖） | ✅ 自动降级；仍无 OCR（如 Linux 未装 venv）→ 自动转交视觉 API 转录该区域，pipeline 不中断 |
| smart 模式文字识别 | 本插件自带（vision_region_crop 视觉直读转录） | ✅ 始终可用，零依赖第三方插件 |
| 与 picturereader 共存 | 探测其是否在场（注册表工具 image_scan / 插件目录双通道） | ✅ 在场时给本插件工具追加分工引导（大图→本插件，小图/文档→picturereader）；复用其已配视觉端点（vlm_base/vlm_model）与已建 OCR venv（paddle_venv/rapid_venv）；不在场则行为与无此插件时完全一致，且不改动 picturereader 任何文件 |

结论：本插件零依赖任何第三方 DSH 插件（picturereader 等均未使用）；paddle/rapid 是用户可选安装的开源 OCR 环境（Apache-2.0，仅环境探测，非插件依赖），装了中文转录质量最好，不装也完全可用。

八、已知边界

- 插件直连官方 API，不受 DSH 内置 deepseek 适配器 text-only 限制；结果以文本回流会话；
- 官方限制：图片仅可在 user 消息（已遵守）；单请求 ≤600 图（本插件默认 ≤240 更保守）；base64 请求体 ≤48MiB（超预算自动提示分批/转 JPEG）；
- "完美识别"是质量目标：块数越多难度越高，分层聚合显著缓解；跨块被切断的细线级元素仍可能合并出错（建议 overlap=64）；
- 全自动 pipeline 无交互通道：预检"重点不明确"时会在结果中说明，可改用 smart（模型先问你）或 vision_region_crop 指定坐标；
- arm64/WSL/容器环境建议开启保守预设（默认已 platform_fallback=auto 自动降级：块格式 jpeg、OCR 池并发 2、不自动开 GPU）；如确需更强算力可设 platform_fallback=off 或显式覆盖。

用户如何安装发布版

下载 Release 里的 vision-exp-tile-vX.Y.Z.zip，解压后按前面"二、安装与挂载"步骤操作（放到 ~/.dsh/plugins/vision-exp-tile + profile 挂 link: 依赖），或直接从源码仓库 git clone 后同样挂载。

许可

MIT © vision-exp-tile contributors

如果这个插件对你有帮助，欢迎点个 ⭐ Star 支持一下～（你的支持就是持续更新的动力）