@caesarloo/dsh-deepseek-account-vision 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+本项目的所有重要改动都记录在这里。版本号遵循语义化版本（主.次.修）。
+
+## 0.1.0 — 2026-10-19
+
+首个版本。npm 包名为 `@caesarloo/dsh-deepseek-account-vision`
+（无 scope 的同义名已被他人占用，故加 scope 并保留 account 语义）。
+
+### 新增
+
+- **`deepseek_vision` 工具**：主模型是任意模型时，都能用 DeepSeek 账号的
+  DeepSeek-V4.1-Flash（`deepseek-flash`，1017 版）识别图片——支持本地
+  PNG/JPEG/WebP/GIF 路径与 `http(s)` 图片 URL，可选 `prompt` 指定识别重点。
+- **自动转译路由**：为每个已注册 provider 包一层 `<provider>-vision` 路由
+  （默认显示名 `<provider 名称> + 自动识图`），在 GUI 里给纯文本主模型贴图时，
+  图片先由 DeepSeek-V4.1-Flash 转成文字，再交给原模型作答。
+  - `wrapAllProviders`（默认开）覆盖已注册与之后动态注册的 provider；
+    `innerProviders` 可改为只包裹指定 provider。
+  - `failureMode: placeholder`（默认）在转译失败时插入 `[图片转译失败: …]`
+    并继续对话；`error` 则让整轮失败。
+- **零密钥**：识图请求统一走 `ctx.llm.stream()` 的 DeepSeek 账号路由
+  （默认 `deepseek-account`），复用 DSH 的 DeepSeek 登录态，插件不保存凭据。
+- **稳定与省费**：按图片内容 SHA-256 的进程内缓存、同键并发合并、
+  失败图片 60 秒冷却、请求超时快速失败。
+- **发布闸门**：`prepublishOnly` 先跑离线单测 + UTF-8 BOM 检查 + 本机指纹/凭据扫描
+  （`scripts/check-leaks.mjs`，规则自足、含路径写法变体；`.leak-patterns.local` 不进库）
+  + bundle 清单一致性检查（入口 / patch 随包 / insert name / engines.dsh）；
+  中英双语 README 通过结构与指纹审核。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Caesar Loo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,243 @@
-# Temporary Holding Version
+# @caesarloo/dsh-deepseek-account-vision
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[English](#english) | [中文](#中文)
+
+---
+
+## English
+
+Give **any** main model in DeepSeek Harness the vision of the DeepSeek account: recognize images with **DeepSeek-V4.1-Flash** (`deepseek-flash`, release 1017) — through a `deepseek_vision` tool, or automatically for images attached to a text-only chat model. No API key, no extra VLM account, no image library.
+
+### What it does
+
+- Adds a model-facing tool `deepseek_vision`: pass a local PNG/JPEG/WebP/GIF path or an `http(s)` image URL, get back a complete textual rendition (verbatim OCR, layout, visual elements, key details).
+- Answers with the **DeepSeek account route** (`deepseek-account` / `deepseek-flash` by default), so it reuses the DeepSeek login you already have in DSH — the plugin never stores credentials.
+- Registers automatic image-transcription routes: for every registered provider it adds a `<provider>-vision` route that declares image input, turns each attached image into text with DeepSeek-V4.1-Flash, then delegates the conversation to the original model. A pure-text main model can finally "see" a pasted screenshot.
+- Caches results by image content hash (in-process only), merges concurrent identical requests, cools down a failed image for 60 s, and fails fast instead of hanging.
+- Works alongside everything: text-only conversations pass through untouched; the original model, tools and history shape stay the same.
+
+### Install
+
+```sh
+dsh plugin --profile <profile> add @caesarloo/dsh-deepseek-account-vision
+```
+
+From a local checkout, install by directory instead: `dsh plugin --profile <profile> add <project-directory>`.
+
+Restart DSH once (bundle layers have no hot reload), then verify that `deepseek_vision` appears in the tool list of a new session. A patch-layer development install (`- insert:` with the plugin entry file) reloads hot without a restart.
+
+Requirements: DSH `>= 0.2.1-rc.2`, a signed-in DeepSeek account, and the standard `llm` / `attachments` / `fs` services (all present in the shipped bundle).
+
+### Usage
+
+**1. Tool — any main model can call it**
+
+```json
+{
+  "image_path": "screenshot.png",
+  "prompt": "Transcribe every visible character and describe the layout"
+}
+```
+
+or, for a remote image:
+
+```json
+{ "image_url": "https://example.com/chart.png" }
+```
+
+The tool returns `{ text, model, source, truncated }`. The image never enters the main model's context — only the transcription does. A custom `prompt` is passed to the vision model verbatim; leave it out to use the built-in full-transcription prompt.
+
+**2. Automatic transcription route — paste images into a text-only chat**
+
+Pick the route named **`<provider> + 自动识图`** (id `<provider>-vision`, configurable) in the model selector, then attach an image as usual. The image block is transcribed before the original adapter sees the request:
+
+```
+GUI image ──▶ <provider>-vision route (declares image input → attachment admitted)
+                  │  each image block is transcribed by DeepSeek-V4.1-Flash
+                  ▼
+            original model (receives plain text, answers normally)
+```
+
+Transcribed text is prefixed with `[图片转译]`. When transcription fails and `failureMode` is `placeholder` (default), an explicit `[图片转译失败: …]` marker is inserted and the conversation continues.
+
+| Situation | What to use |
+|---|---|
+| Any model, image exists as a file or URL | `deepseek_vision` tool |
+| Text-only model, image attached in the GUI | the `<provider>-vision` route |
+| Main model already accepts images | no plugin needed for that turn |
+
+### Configuration
+
+Defaults ship in `cordis.patch.yml`; override them in your profile's `cordis.patch.yml` with an `- id: dsh-deepseek-account-vision` entry. Unlisted keys fall back to the defaults below.
+
+| Key | Default | Meaning |
+|---|---|---|
+| `visionProvider` | `deepseek-account` | Registered provider route used for image recognition |
+| `visionModel` | `deepseek-flash` | Vision model id (DeepSeek-V4.1-Flash / 1017) |
+| `visionMaxTokens` | `4096` | Output cap for the vision model |
+| `timeoutMs` | `120000` | Per-image recognition timeout |
+| `tool` | `true` | Register the `deepseek_vision` tool |
+| `toolName` | `deepseek_vision` | Tool name exposed to models |
+| `autoTranscribe` | `true` | Register automatic image-transcription routes |
+| `wrapAllProviders` | `true` | Wrap every registered provider (including ones registered later) |
+| `innerProviders` | `[]` | Providers to wrap when `wrapAllProviders=false` |
+| `routeSuffix` | `-vision` | Route id suffix: `<provider><routeSuffix>` |
+| `routeNameTemplate` | `{name} + 自动识图` | Route display name; `{name}` / `{provider}` are substituted |
+| `marker` | `[图片转译]` | Prefix added to each transcription |
+| `failureMode` | `placeholder` | `placeholder` keeps the turn alive; `error` fails the whole turn |
+| `transcribePrompt` | `''` | Override the automatic-transcription prompt (empty = built-in) |
+| `recognitionPrompt` | `''` | Override the `deepseek_vision` prompt (empty = built-in) |
+| `cacheSize` | `200` | In-process result cache entries (0 disables) |
+| `urlTimeoutMs` | `30000` | Timeout for downloading an `http(s)` image |
+
+### Dependencies
+
+- **No API key, no separate VLM account.** Recognition goes through `ctx.llm.stream()` on the DeepSeek account route; DSH's account service owns the credentials.
+- **No image library.** Attachment normalization (size, pixels, format validation) is done by DSH's attachment service; the plugin only ships `schemastery` for config.
+- **Node built-ins only** beyond that (`crypto`, `path`, global `fetch` / `AbortSignal`).
+
+### Boundaries
+
+- It does **not** turn the main model into a multimodal model: the original model still receives only text. It **does** make image input usable for it via transcription.
+- It does **not** replace `read_image`: `read_image` hands the native image block to an image-capable model; `deepseek_vision` returns text so any model can consume it.
+- It only accepts **PNG / JPEG / WebP / GIF** — no PDF, audio or video.
+- Transcription is a lossy summary for dense screenshots: very small text or fine UI details may be missed. Use a stronger `visionModel` or a more explicit `prompt` when exactness matters.
+- Images are sent to DeepSeek with the recognition request (that is the point) and are not otherwise persisted by the plugin; the result cache lives in process memory only.
+
+### Development
+
+```sh
+pnpm install
+npm test                 # unit tests + BOM + fingerprint/credential + bundle-manifest checks
+npm run check-leaks      # fingerprint scan only
+```
+
+`prepublishOnly` runs `npm test`, so a package with a failing test, a BOM-prefixed source file, or a machine-specific fingerprint cannot be published. Publish explicitly against the official registry:
+
+```sh
+npm publish --registry https://registry.npmjs.org/
+```
+
+### License
+
+MIT
+
+---
+
+## 中文
+
+让 DeepSeek Harness 里的**任意主模型**都用上 DeepSeek 账号的视觉能力：用 **DeepSeek-V4.1-Flash**（`deepseek-flash`，1017 版）识别图片——既可以由模型调用 `deepseek_vision` 工具，也可以给纯文本主模型自动转译 GUI 里贴的图片。不需要 API Key，不需要另找视觉模型账号，不装图像库。
+
+### 它做什么
+
+- 注册模型可见的工具 `deepseek_vision`：给一个本地 PNG/JPEG/WebP/GIF 路径或 `http(s)` 图片地址，返回完整文字转译（逐字 OCR、版面结构、视觉元素、关键细节）。
+- 识图后端走 **DeepSeek 账号路由**（默认 `deepseek-account` / `deepseek-flash`），复用 DSH 里已登录的 DeepSeek 账号，插件自身不保存任何凭据。
+- 注册自动转译路由：为每个已注册 provider 加一条 `<provider>-vision` 路由，对外声明支持图片输入，收到图片后先用 DeepSeek-V4.1-Flash 转成文字，再交给原模型作答。纯文本主模型也能“看到”粘贴的截图。
+- 按图片内容哈希缓存（仅进程内）、合并并发的同图请求、失败图片冷却 60 秒、超时快速失败而不是卡死。
+- 与现有能力并存：纯文本对话零改动直达原模型，原模型、工具与会话历史结构都不变。
+
+### 安装
+
+```sh
+dsh plugin --profile <profile> add @caesarloo/dsh-deepseek-account-vision
+```
+
+本地检出目录安装：`dsh plugin --profile <profile> add <项目目录>`。
+
+安装后重启一次 DSH（bundle 层不支持热重载），再在新会话的工具列表里确认出现 `deepseek_vision`。开发期也可以用 patch 层 `- insert:` 指向插件入口文件装载，改完热生效、无需重启。
+
+依赖：DSH `>= 0.2.1-rc.2`、已登录的 DeepSeek 账号，以及标准的 `llm` / `attachments` / `fs` 服务（随官方 bundle 提供）。
+
+### 使用
+
+**1. 工具——任意主模型都能调**
+
+```json
+{
+  "image_path": "screenshot.png",
+  "prompt": "逐字识别所有可见文字，并说明版式"
+}
+```
+
+远程图片：
+
+```json
+{ "image_url": "https://example.com/chart.png" }
+```
+
+返回 `{ text, model, source, truncated }`。图片本身不会进入主模型上下文，只有转译文字会。自定义 `prompt` 会原样交给识图模型；留空才使用内置的完整转译提示词。
+
+**2. 自动转译路由——给纯文本模型直接贴图**
+
+在模型选择器里选 **`<provider> + 自动识图`**（id 为 `<provider>-vision`，可配置），然后照常附加图片。图片块会在原适配器收到请求之前被转译：
+
+```
+GUI 图片 ──▶ <provider>-vision 路由（声明支持图片 → 附件放行）
+                  │  每个 image 块交给 DeepSeek-V4.1-Flash 转译
+                  ▼
+            原模型（收到纯文本，正常作答）
+```
+
+转译文本带 `[图片转译]` 前缀。转译失败且 `failureMode` 为默认的 `placeholder` 时，会插入 `[图片转译失败: …]` 占位文本并继续对话。
+
+| 场景 | 用什么 |
+|---|---|
+| 任意模型，图片是文件或 URL | `deepseek_vision` 工具 |
+| 纯文本模型，在 GUI 里贴图 | `<provider>-vision` 路由 |
+| 主模型本来就支持图片 | 该轮不需要本插件 |
+
+### 配置
+
+默认值随 `cordis.patch.yml` 提供；在 profile 的 `cordis.patch.yml` 里用 `- id: dsh-deepseek-account-vision` 条目覆盖。未列出的键回落到下表默认值。
+
+| 键 | 缺省 | 含义 |
+|---|---|---|
+| `visionProvider` | `deepseek-account` | 识图使用的已注册 provider 路由 |
+| `visionModel` | `deepseek-flash` | 识图模型 id（DeepSeek-V4.1-Flash / 1017） |
+| `visionMaxTokens` | `4096` | 识图模型输出上限 |
+| `timeoutMs` | `120000` | 单张图片识图超时 |
+| `tool` | `true` | 是否注册 `deepseek_vision` 工具 |
+| `toolName` | `deepseek_vision` | 暴露给模型的工具名 |
+| `autoTranscribe` | `true` | 是否注册自动转译路由 |
+| `wrapAllProviders` | `true` | 包裹全部已注册 provider（含之后动态注册的） |
+| `innerProviders` | `[]` | `wrapAllProviders=false` 时要包裹的 provider |
+| `routeSuffix` | `-vision` | 路由 id 后缀：`<provider><routeSuffix>` |
+| `routeNameTemplate` | `{name} + 自动识图` | 路由显示名；`{name}` / `{provider}` 会被替换 |
+| `marker` | `[图片转译]` | 每条转译文本的前缀 |
+| `failureMode` | `placeholder` | `placeholder` 保住本轮对话；`error` 让整轮失败 |
+| `transcribePrompt` | `''` | 覆盖自动转译提示词（留空用内置） |
+| `recognitionPrompt` | `''` | 覆盖 `deepseek_vision` 提示词（留空用内置） |
+| `cacheSize` | `200` | 进程内结果缓存条数（0 关闭） |
+| `urlTimeoutMs` | `30000` | 下载 `http(s)` 图片的超时 |
+
+### 依赖约定
+
+- **无 API Key、无独立视觉账号**：识图经 `ctx.llm.stream()` 打在 DeepSeek 账号路由上，凭据由 DSH 账号服务持有。
+- **无图像库**：尺寸/像素/格式归一化由 DSH 附件服务完成；插件自身只依赖 `schemastery` 做配置校验。
+- 其余只用 Node 内建能力（`crypto`、`path`、全局 `fetch` / `AbortSignal`）。
+
+### 边界（明确不做）
+
+- **不把主模型变成多模态模型**：原模型收到的仍然只有文字；本插件做的是“把图片转成文字再交给它”。
+- **不替代 `read_image`**：`read_image` 把原生图片块交给支持图片的模型；`deepseek_vision` 返回文字，所以任何模型都能消费。
+- 只接受 **PNG / JPEG / WebP / GIF**，不支持 PDF、音频、视频。
+- 转译对密集截图是有损摘要：极小的字或精细 UI 细节可能丢失；要求精确时换更强的 `visionModel` 或把 `prompt` 写具体。
+- 图片只随识图请求发送到 DeepSeek（这正是功能本身），插件不另行持久化；结果缓存只在进程内存中。
+
+### 开发与发布
+
+```sh
+pnpm install
+npm test                 # 单测 + BOM + 本机指纹/凭据 + bundle 清单一致性检查
+npm run check-leaks      # 只跑指纹扫描
+```
+
+`prepublishOnly` 跑 `npm test`：单测失败、源码带 BOM、或命中本机指纹/凭据时都发不出去。发布时显式指定官方 registry：
+
+```sh
+npm publish --registry https://registry.npmjs.org/
+```
+
+### License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,40 @@
+# @caesarloo/dsh-deepseek-account-vision bundle patch：在 profile 树上插入一行插件。
+# 只有当本包作为 profile 依赖被安装（例如
+# `dsh plugin add @caesarloo/dsh-deepseek-account-vision`）时，这一行才会被组合进运行时。
+#
+# 默认策略：
+# - 注册 deepseek_vision 工具：主模型是任意模型时都能调用它，用 DeepSeek 账号的
+#   DeepSeek-V4.1-Flash（deepseek-flash）识别本地图片路径或 http(s) 图片链接。
+# - autoTranscribe: 为所有已注册的模型提供方各包一层“识图路由”
+#   （<provider>-vision），把附带的图片自动转译成文字后再交给原模型。
+#   这样在 GUI 里给任意纯文本主模型贴图也能用。
+# - 所有识图请求都走 DeepSeek 账号登录态（ctx.llm 的 deepseek-account 路由），
+#   不需要任何 API Key。
+
+- insert:
+    - id: dsh-deepseek-account-vision
+      name: '@caesarloo/dsh-deepseek-account-vision'
+      config:
+        # 识图后端（默认：DeepSeek 账号自带的 DeepSeek-V4.1-Flash）
+        visionProvider: deepseek-account
+        visionModel: deepseek-flash
+        visionMaxTokens: 4096
+        timeoutMs: 120000
+
+        # deepseek_vision 工具
+        tool: true
+        toolName: deepseek_vision
+
+        # 自动转译路由
+        autoTranscribe: true
+        wrapAllProviders: true
+        innerProviders: []          # wrapAllProviders=false 时只包裹这些 provider
+        routeSuffix: '-vision'
+        routeNameTemplate: '{name} + 自动识图'
+        marker: '[图片转译]'
+        failureMode: placeholder    # placeholder | error
+        transcribePrompt: ''        # 留空用内置提示词
+        recognitionPrompt: ''       # 留空用内置提示词
+
+        cacheSize: 200
+        urlTimeoutMs: 30000

package/lib/cache.js

@@ -0,0 +1,77 @@
+/**
+ * 进程内缓存与同键并发合并。
+ *
+ * - `VisionCache`：有上限的 LRU（Map 插入序实现），按图片内容哈希去重；
+ *   从不落盘。
+ * - `SingleFlight`：同一张图片在同一时刻只发起一次识图请求，其余调用等待
+ *   同一个 Promise（一轮回复里同一张图出现多次时不会重复计费）。
+ *
+ * @module dsh-deepseek-account-vision/cache
+ */
+
+/** 有上限的 LRU 缓存。`limit <= 0` 时退化为不缓存。 */
+export class VisionCache {
+    /** @param {number} limit 最大条目数。 */
+    constructor(limit) {
+        this.limit = Number.isInteger(limit) && limit > 0 ? limit : 0;
+        /** @type {Map<string, unknown>} */
+        this.entries = new Map();
+    }
+
+    /** @param {string} key 缓存键。 @returns {unknown} 命中值或 undefined。 */
+    get(key) {
+        const value = this.entries.get(key);
+        if (value === undefined) return undefined;
+        // 命中后移到队尾，维持 LRU 顺序。
+        this.entries.delete(key);
+        this.entries.set(key, value);
+        return value;
+    }
+
+    /** @param {string} key 缓存键。 @param {unknown} value 缓存值。 */
+    set(key, value) {
+        if (this.limit <= 0) return;
+        if (this.entries.has(key)) this.entries.delete(key);
+        else if (this.entries.size >= this.limit) {
+            const oldest = this.entries.keys().next();
+            if (oldest.done !== true) this.entries.delete(oldest.value);
+        }
+        this.entries.set(key, value);
+    }
+
+    /** @param {string} key 缓存键。 */
+    delete(key) {
+        this.entries.delete(key);
+    }
+
+    /** 当前条目数。 */
+    get size() {
+        return this.entries.size;
+    }
+}
+
+/** 同键并发合并：相同 key 的并发调用共享同一个 Promise。 */
+export class SingleFlight {
+    constructor() {
+        /** @type {Map<string, Promise<unknown>>} */
+        this.inflight = new Map();
+    }
+
+    /**
+     * @template T
+     * @param {string} key 合并键。
+     * @param {() => Promise<T>} task 真正执行的任务。
+     * @returns {Promise<T>}
+     */
+    run(key, task) {
+        const existing = this.inflight.get(key);
+        if (existing !== undefined) return /** @type {Promise<T>} */ (existing);
+        const promise = Promise.resolve()
+            .then(task)
+            .finally(() => {
+                this.inflight.delete(key);
+            });
+        this.inflight.set(key, promise);
+        return promise;
+    }
+}

package/lib/config.js

@@ -0,0 +1,139 @@
+/**
+ * dsh-deepseek-account-vision：配置、默认提示词与配置归一化。
+ *
+ * 本插件不自带任何 API Key：识图请求全部经 `ctx.llm` 的 DeepSeek 账号路由
+ * （默认 `deepseek-account` / `deepseek-flash`）发出，复用 DSH 里已登录的
+ * DeepSeek 账号凭据。这既是本插件与“直连第三方 VLM”的 dsh-vision-proxy 的
+ * 核心区别，也意味着用户不需要再配置 key。
+ *
+ * @module dsh-deepseek-account-vision/config
+ */
+import z from 'schemastery';
+
+/** 默认识图后端：DeepSeek 账号路由。 */
+export const DEFAULT_VISION_PROVIDER = 'deepseek-account';
+/** 默认识图模型：目录名 DeepSeek-V4.1-Flash（1017），同时支持文本与图片输入。 */
+export const DEFAULT_VISION_MODEL = 'deepseek-flash';
+/** 自动转译文本的默认前缀标记。 */
+export const DEFAULT_MARKER = '[图片转译]';
+/** 默认注册的工具名（模型可见，snake_case）。 */
+export const DEFAULT_TOOL_NAME = 'deepseek_vision';
+/** 识图路由默认后缀：`<innerProvider>-vision`。 */
+export const DEFAULT_ROUTE_SUFFIX = '-vision';
+/** 识图路由默认显示名模板。 */
+export const DEFAULT_ROUTE_NAME = '{name} + 自动识图';
+
+/** 工具默认提示词：面向“主模型看不到图，需要完整转译”的场景。 */
+export const DEFAULT_RECOGNITION_PROMPT = `你正在直接观察用户给出的这张图片，你的输出会交给另一位看不到图片的模型阅读。请输出一份忠实、完整、结构化的文字结果：
+1. 一句话总览：这张图是什么（截图 / 照片 / 图表 / 海报 / 表情包 / 文档 / 界面等）以及主题。
+2. 全部可见文字：逐字转录，保留原语言、顺序与层级；表格按行列输出；不要概括、不要漏字。
+3. 版面与视觉结构：区域划分、主要对象、人物或动物、颜色、图标、界面控件、图表及其数据。
+4. 关键细节：数字、时间、地址、URL、代码、报错信息、按钮文案等。
+要求：只描述图片本身，不要寒暄；不要输出“如果看不到图”“可以想象成”之类的假设性描述；看不清的地方标注“（不清晰）”；不要臆造不存在的内容。`;
+
+/** 自动转译路由默认提示词：结果会替换原图片块进入主模型上下文。 */
+export const DEFAULT_TRANSCRIBE_PROMPT = `你正在直接观察用户给出的这张图片，你的转译会交给另一位看不到图片、需要据此回答用户的纯文本模型。
+请输出：
+1. 图片类型与一句话总览；
+2. 全部可见文字逐字转录（保留原语言与结构；表格按行列输出）；
+3. 版面、结构、主要对象、颜色、图标、界面元素等关键视觉信息；
+4. 数字、时间、URL、代码等关键细节。
+要求：忠实、完整；不寒暄、不臆造；不要输出“如果看不到图”“可以想象成”之类的假设性描述；看不清处标注“（不清晰）”。输出语言与图中主要文字一致；图中没有文字时用中文。`;
+
+/** 自定义工具提示词时不再追加任何指令：用户/主模型给什么就按什么识别。 */
+
+/**
+ * 插件配置 schema。bundle patch 只写部分键时，未列出的键回落到这里的默认值。
+ */
+export const Config = z.object({
+    visionProvider: z.string().default(DEFAULT_VISION_PROVIDER)
+        .description('识图后端使用的已注册 provider 路由；默认 DeepSeek 账号路由'),
+    visionModel: z.string().default(DEFAULT_VISION_MODEL)
+        .description('识图模型 id；默认 deepseek-flash（DeepSeek-V4.1-Flash / 1017，原生多模态）'),
+    visionMaxTokens: z.number().step(1).min(1).max(32_768).default(4096)
+        .description('识图模型的输出上限；思考型模型请留足预算'),
+    timeoutMs: z.number().step(1).min(1_000).max(300_000).default(120_000)
+        .description('单张图片识图请求的超时时间'),
+    tool: z.boolean().default(true)
+        .description('是否注册 deepseek_vision 工具（主模型是任意模型时都可调用）'),
+    toolName: z.string().default(DEFAULT_TOOL_NAME)
+        .description('注册的工具名（模型可见，建议 snake_case）'),
+    autoTranscribe: z.boolean().default(true)
+        .description('是否为模型提供方注册自动转译路由，把 GUI 附带的图片转成文字'),
+    wrapAllProviders: z.boolean().default(true)
+        .description('true = 自动包裹所有已注册 provider（含之后动态注册的）；false = 只包裹 innerProviders'),
+    innerProviders: z.array(z.string()).default([])
+        .description('wrapAllProviders=false 时要包裹的 provider 路由 id 列表'),
+    routeSuffix: z.string().default(DEFAULT_ROUTE_SUFFIX)
+        .description('识图路由 id 后缀，最终 id 为 <innerProvider><routeSuffix>'),
+    routeNameTemplate: z.string().default(DEFAULT_ROUTE_NAME)
+        .description('识图路由显示名模板；{name} 会被替换成被包裹路由的名称'),
+    marker: z.string().default(DEFAULT_MARKER)
+        .description('自动转译文本的前缀标记'),
+    failureMode: z.union(['placeholder', 'error']).default('placeholder')
+        .description('自动转译失败时的行为：placeholder 插入失败占位文本并继续对话（默认），error 让整轮失败'),
+    transcribePrompt: z.string().default('')
+        .description('覆盖自动转译提示词；留空使用内置提示词'),
+    recognitionPrompt: z.string().default('')
+        .description('覆盖工具识图提示词；留空使用内置提示词'),
+    cacheSize: z.number().step(1).min(0).max(5_000).default(200)
+        .description('进程内识图结果缓存条数（按图片内容 SHA-256 去重；0 关闭）'),
+    urlTimeoutMs: z.number().step(1).min(1_000).max(120_000).default(30_000)
+        .description('deepseek_vision 拉取 http(s) 图片的超时时间'),
+});
+
+function requireNonEmptyString(key, value) {
+    if (typeof value !== 'string' || value.trim() === '') throw new Error(`dsh-deepseek-account-vision: config.${key} must be a non-empty string`);
+    return value.trim();
+}
+
+function requirePositiveInteger(key, value, { min = 1, max = Number.MAX_SAFE_INTEGER } = {}) {
+    if (!Number.isInteger(value) || value < min || value > max) throw new Error(`dsh-deepseek-account-vision: config.${key} must be an integer between ${min} and ${max}`);
+    return value;
+}
+
+/**
+ * 把 loader 解析后的配置（或测试/手工传入的部分配置）归一化为冻结对象。
+ * bundle patch 里只写少数字段时也能安全补全默认值。
+ * @param {Record<string, unknown>} [input] 原始配置。
+ * @returns {Readonly<Record<string, unknown>>} 归一化后的配置。
+ */
+export function resolveConfig(input = {}) {
+    const raw = input === null || typeof input !== 'object' ? {} : input;
+    const pick = (key, fallback) => (raw[key] === undefined || raw[key] === null ? fallback : raw[key]);
+
+    const failureMode = pick('failureMode', 'placeholder');
+    if (failureMode !== 'placeholder' && failureMode !== 'error') {
+        throw new Error('dsh-deepseek-account-vision: config.failureMode must be "placeholder" or "error"');
+    }
+    const innerProviders = pick('innerProviders', []);
+    if (!Array.isArray(innerProviders) || innerProviders.some((id) => typeof id !== 'string' || id.trim() === '')) {
+        throw new Error('dsh-deepseek-account-vision: config.innerProviders must be an array of non-empty provider ids');
+    }
+    const wrapAllProviders = pick('wrapAllProviders', true);
+    if (typeof wrapAllProviders !== 'boolean') throw new Error('dsh-deepseek-account-vision: config.wrapAllProviders must be a boolean');
+    const tool = pick('tool', true);
+    if (typeof tool !== 'boolean') throw new Error('dsh-deepseek-account-vision: config.tool must be a boolean');
+    const autoTranscribe = pick('autoTranscribe', true);
+    if (typeof autoTranscribe !== 'boolean') throw new Error('dsh-deepseek-account-vision: config.autoTranscribe must be a boolean');
+
+    return Object.freeze({
+        visionProvider: requireNonEmptyString('visionProvider', pick('visionProvider', DEFAULT_VISION_PROVIDER)),
+        visionModel: requireNonEmptyString('visionModel', pick('visionModel', DEFAULT_VISION_MODEL)),
+        visionMaxTokens: requirePositiveInteger('visionMaxTokens', pick('visionMaxTokens', 4096), { max: 32_768 }),
+        timeoutMs: requirePositiveInteger('timeoutMs', pick('timeoutMs', 120_000), { min: 1_000, max: 300_000 }),
+        tool,
+        toolName: requireNonEmptyString('toolName', pick('toolName', DEFAULT_TOOL_NAME)),
+        autoTranscribe,
+        wrapAllProviders,
+        innerProviders: Object.freeze(innerProviders.map((id) => id.trim())),
+        routeSuffix: requireNonEmptyString('routeSuffix', pick('routeSuffix', DEFAULT_ROUTE_SUFFIX)),
+        routeNameTemplate: requireNonEmptyString('routeNameTemplate', pick('routeNameTemplate', DEFAULT_ROUTE_NAME)),
+        marker: typeof pick('marker', DEFAULT_MARKER) === 'string' ? pick('marker', DEFAULT_MARKER) : DEFAULT_MARKER,
+        failureMode,
+        transcribePrompt: typeof pick('transcribePrompt', '') === 'string' ? pick('transcribePrompt', '').trim() : '',
+        recognitionPrompt: typeof pick('recognitionPrompt', '') === 'string' ? pick('recognitionPrompt', '').trim() : '',
+        cacheSize: requirePositiveInteger('cacheSize', pick('cacheSize', 200), { min: 0, max: 5_000 }),
+        urlTimeoutMs: requirePositiveInteger('urlTimeoutMs', pick('urlTimeoutMs', 30_000), { min: 1_000, max: 120_000 }),
+    });
+}

package/lib/errors.js

@@ -0,0 +1,80 @@
+/**
+ * 识图失败的分类与可操作提示。
+ *
+ * `ctx.llm.stream()` 的终止 `finish` 分片携带规范化后的 `LlmFailure`
+ * （稳定 code + message + status）。本模块只依据 code 分支，不解析 message 文本。
+ *
+ * @module dsh-deepseek-account-vision/errors
+ */
+
+/** 识图失败。`code` 为稳定错误码，`hint` 为可操作的中文提示。 */
+export class VisionError extends Error {
+    /**
+     * @param {string} message 面向诊断的错误信息。
+     * @param {string} code 稳定错误码。
+     * @param {string} [hint] 面向用户的可操作提示。
+     */
+    constructor(message, code, hint) {
+        super(hint === undefined ? message : `${message}（${hint}）`);
+        this.name = 'VisionError';
+        this.code = code;
+        this.hint = hint;
+    }
+}
+
+/** 失败码 → 可操作提示。未列出的码保留原始 message。 */
+const HINTS = {
+    ACCOUNT_SIGN_IN_REQUIRED: '请先在 DSH 里登录 DeepSeek 账号（设置 → 账号）；登录后即可直接识图，无需 API Key',
+    NO_ADAPTER: 'visionProvider 指向的模型路由没有注册；检查插件配置里的 visionProvider',
+    MISSING_CREDENTIAL: 'DeepSeek 账号凭据缺失，请重新登录 DeepSeek 账号',
+    AUTH: 'DeepSeek 账号登录已失效，请重新登录账号',
+    ACCOUNT_TOKEN_INVALID: 'DeepSeek 账号登录已失效，请重新登录账号',
+    INVALID_CREDENTIAL: 'DeepSeek 账号凭据无效，请重新登录账号',
+    RATE_LIMIT: '识图请求被限流，请稍后重试',
+    QUOTA: '识图模型额度不足，请检查 DeepSeek 账号额度',
+    ACCOUNT_QUOTA: 'DeepSeek 账号余额不足，请充值后重试',
+    CONTEXT_WINDOW_EXCEEDED: '图片太大或上下文超限，请换更小的图片重试',
+    IMAGE_OFFLOAD_REQUIRED: '图片体积超出该模型的请求预算，请换更小的图片重试',
+    MODEL_UNSUPPORTED: '当前账号/DSH 版本不支持该识图模型，请检查 visionModel 或升级 DSH',
+    CLIENT_UPGRADE_REQUIRED: '该识图模型要求更高的 DSH 版本，请升级 DSH',
+    UNKNOWN_MODEL: '识图模型 id 不被该路由认识，请检查 visionModel',
+    TIMEOUT: '识图请求超时，请检查网络后重试',
+    ABORTED: '识图请求被取消',
+    EMPTY_RESPONSE: '识图模型没有返回任何文本，请换个提示词或换张图片重试',
+    NO_FINISH: '识图请求没有正常结束，请重试',
+};
+
+/**
+ * 把 `finish.failure` 映射成 `VisionError`。
+ * @param {{ code?: string, message?: string, status?: number } | undefined} failure 终止失败信息。
+ * @param {string} provider 识图 provider id。
+ * @param {string} model 识图 model id。
+ * @returns {VisionError}
+ */
+export function failureToVisionError(failure, provider, model) {
+    const code = typeof failure?.code === 'string' && failure.code !== '' ? failure.code : 'LLM_ERROR';
+    const detail = typeof failure?.message === 'string' && failure.message !== '' ? failure.message : 'no failure message';
+    const status = typeof failure?.status === 'number' ? ` HTTP ${failure.status}` : '';
+    const message = `识图模型 ${provider}/${model} 调用失败 [${code}${status}]: ${detail}`;
+    const hint = HINTS[code];
+    return new VisionError(message, code, hint);
+}
+
+/**
+ * 把任意异常归一化为 `VisionError`（用于工具错误与占位文本）。
+ * @param {unknown} error 原始异常。
+ * @param {string} [fallbackCode] 无法识别时使用的错误码。
+ * @returns {VisionError}
+ */
+export function toVisionError(error, fallbackCode = 'VISION_FAILED') {
+    if (error instanceof VisionError) return error;
+    const message = error instanceof Error ? error.message : String(error);
+    return new VisionError(`识图失败: ${message}`, fallbackCode);
+}
+
+/** 生成自动转译占位文本（不把整段错误堆栈塞进会话历史）。 */
+export function failurePlaceholder(error) {
+    const visionError = toVisionError(error);
+    const reason = visionError.message.length > 240 ? `${visionError.message.slice(0, 240)}…` : visionError.message;
+    return `[图片转译失败: ${reason}]`;
+}

package/lib/hash.js

@@ -0,0 +1,13 @@
+/**
+ * 用一行 `sha256` 摘要给图片/提示词做内容键（缓存与并发合并都靠它）。
+ * @module dsh-deepseek-account-vision/hash
+ */
+import { createHash } from 'node:crypto';
+
+/**
+ * @param {Uint8Array | string} data 待摘要的字节或字符串。
+ * @returns {string} 32 字节十六进制摘要。
+ */
+export function sha256Hex(data) {
+    return createHash('sha256').update(data).digest('hex');
+}