dsh-ocr-local 0.4.0

package/dsh/index.js

@@ -0,0 +1,514 @@
+/**
+ * dsh-ocr-local — host half (cordis plugin), Web only.
+ *
+ * 1. Registers the `ocr_image` tool: local PP-OCRv5 (ONNX Runtime) OCR on an
+ *    image path, fully offline. Models cached in ~/.dsh-ocr/models.
+ * 2. Registers the `ocr_setup` tool: one-command bootstrap (venv + deps +
+ *    models), so first use is automatic instead of a manual pip dance.
+ * 3. Auto-OCR (`autoOcr`): watches `user/message` events for image
+ *    attachments. The Web composer intakes pasted image files natively, so
+ *    the attachment is the single entry point — no client-side interception.
+ *    Only when the routed model is **explicitly** declared as not accepting
+ *    image input does the plugin save the image to ~/.dsh/ocr/cache and
+ *    inject its path, so the text-only model can call `ocr_image` on it.
+ *
+ *    - model declares `image`  → silent; the vision path handles it, and the
+ *      harness already gives the model a read-only copy path it may OCR when
+ *      verbatim text matters.
+ *    - model declares text only → the harness substitutes an opaque
+ *      "[image omitted ...]" placeholder with no path, so this plugin is the
+ *      only way the model can read the image.
+ *    - cannot be determined      → silent (see dsh/capability.js).
+ *
+ * Loaded via cordis.patch.yml; zero runtime dependencies (node builtins).
+ */
+import { execFile } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { autoOcrMode, modalityCacheKey, pickRoute, shouldInjectOcrPath } from './capability.js'
+
+export const name = 'dsh-ocr-local'
+export const inject = ['tools', 'agents']
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const PLUGIN_ROOT = join(__dirname, '..')
+const OCR_SCRIPT = join(PLUGIN_ROOT, 'ocr', 'ocr.py')
+const SETUP_SCRIPT = join(PLUGIN_ROOT, 'ocr', 'setup.py')
+const OCR_HOME = join(homedir(), '.dsh-ocr')
+const MODELS_DIR = join(OCR_HOME, 'models')
+const VENV_DIR = join(OCR_HOME, 'venv')
+/** 图片缓存目录（内容去重 + 按数量/天数清理）。 */
+const CACHE_DIR = join(homedir(), '.dsh', 'ocr', 'cache')
+
+/* ------------------------------------------------------------------ */
+/* 环境解析                                                             */
+/* ------------------------------------------------------------------ */
+
+function venvPythonPath() {
+  return process.platform === 'win32'
+    ? join(VENV_DIR, 'Scripts', 'python.exe')
+    : join(VENV_DIR, 'bin', 'python')
+}
+
+/** python 解析链：config.pythonPath → DSH_OCR_PYTHON → 内置 venv → python3 → python */
+function resolvePython(config = {}) {
+  const candidates = [
+    config.pythonPath,
+    process.env.DSH_OCR_PYTHON,
+    venvPythonPath(),
+    process.platform === 'win32' ? 'python.exe' : 'python3',
+    'python',
+  ].filter(Boolean)
+  for (const c of candidates) {
+    if (!/[/\\]/.test(c) || existsSync(c)) return c
+  }
+  return candidates[0]
+}
+
+/* ------------------------------------------------------------------ */
+/* OCR 执行与诊断                                                        */
+/* ------------------------------------------------------------------ */
+
+function runDoctor(config = {}) {
+  return new Promise(resolve => {
+    const python = resolvePython(config)
+    execFile(
+      python,
+      ['-X', 'utf8', OCR_SCRIPT, '--doctor', ...(config.modelDir ? ['--model-dir', config.modelDir] : [])],
+      { encoding: 'utf8', windowsHide: true, timeout: 30000 },
+      (error, stdout) => {
+        if (error) {
+          resolve({ ok: false, python: { ok: false, error: 'python 不可用：' + String(error.message || error).slice(0, 120) } })
+          return
+        }
+        try {
+          resolve(JSON.parse(stdout))
+        } catch {
+          resolve({ ok: false, python: { ok: true, error: 'doctor 输出无法解析' } })
+        }
+      },
+    )
+  })
+}
+
+function runOcr(path, config = {}) {
+  return new Promise(resolve => {
+    const python = resolvePython(config)
+    const args = [OCR_SCRIPT, path, '--full', ...(config.modelDir ? ['--model-dir', config.modelDir] : [])]
+    execFile(
+      python,
+      ['-X', 'utf8', ...args],
+      { encoding: 'utf8', windowsHide: true, timeout: 120000, maxBuffer: 32 * 1024 * 1024 },
+      (error, stdout) => {
+        if (error) {
+          let pyErr = null
+          try {
+            pyErr = JSON.parse(stdout.trim())
+          } catch { /* stdout 不是 JSON */ }
+          const reason = pyErr && pyErr.error ? pyErr.error : String(error.message || error).slice(0, 300)
+          runDoctor(config).then(doctor => resolve({ text: '', path, error: reason, doctor }))
+          return
+        }
+        let data = null
+        try {
+          data = JSON.parse(stdout)
+        } catch { /* ignore */ }
+        if (!data || !Array.isArray(data.lines)) {
+          resolve({ text: '', path, error: 'OCR 输出无法解析' })
+          return
+        }
+        resolve({
+          text: data.lines.map(l => l.text).join('\n'),
+          lines: data.lines,
+          blocks: data.blocks || [],
+          path,
+          engine: 'ppocrv5',
+        })
+      },
+    )
+  })
+}
+
+/* ------------------------------------------------------------------ */
+/* 渲染                                                                */
+/* ------------------------------------------------------------------ */
+
+function missingNames(doctor) {
+  const missing = []
+  if (doctor.python && doctor.python.ok === false) missing.push('python')
+  for (const [k, v] of Object.entries(doctor.dependencies || {})) if (!v.ok) missing.push(k)
+  for (const [k, v] of Object.entries(doctor.models || {})) {
+    if (!v.present) missing.push(k)
+    else if (v.sha256_ok === false) missing.push(`${k}(损坏)`)
+  }
+  return missing
+}
+
+function renderText(value) {
+  if (value.error) {
+    const doc = value.doctor
+    let hint
+    if (doc && doc.ok === false) {
+      const missing = missingNames(doc).join('、')
+      hint = `环境未就绪，缺少: ${missing}。\n调用 ocr_setup 工具可一键安装（建 venv + 装依赖 + 下模型），或手动运行:\n  ${SETUP_SCRIPT}`
+    } else {
+      hint = `可调用 ocr_setup 工具检查/安装环境。`
+    }
+    return `[dsh-ocr] ${value.error}\n${hint}`
+  }
+  const head = `图片识别结果（${value.path}）：`
+  const lines = value.lines || []
+  const body = lines.map(l => l.text).join('\n').trim()
+  const low = lines.filter(l => l.low_confidence)
+  let tail = ''
+  if (low.length) {
+    const names = low.map(l => `「${l.text.slice(0, 10)}」(字高${l.font_px ?? '?'}px/置信${Math.round((l.confidence ?? 0) * 100)}%)`).join('、')
+    tail = `\n\n⚠ 以下 ${low.length} 行字太小或检测置信度低，可能有误: ${names}`
+  }
+  return body ? `${head}\n${body}${tail}` : `${head}\n（未识别到文字）`
+}
+
+function renderSetup(value) {
+  if (value.error) return `[dsh-ocr] 安装失败: ${value.error}`
+  if (value.checkOnly) return `[dsh-ocr] ${value.ok ? '环境就绪 ✓' : '环境未就绪 ✗'}`
+  const steps = Object.entries(value.steps || {})
+    .map(([k, v]) => `  - ${k}: ${v}`)
+    .join('\n')
+  return `[dsh-ocr] 安装${value.ok ? '完成 ✓' : '未完成 ✗'}\n${steps}`
+}
+
+/* ------------------------------------------------------------------ */
+/* 图片缓存：去重 + 类型感知命名 + 清理                                    */
+/* ------------------------------------------------------------------ */
+
+/** 附件媒体类型 → 落盘扩展名。 */
+const IMAGE_EXT = {
+  'image/png': '.png',
+  'image/jpeg': '.jpg',
+  'image/webp': '.webp',
+  'image/gif': '.gif',
+  'image/bmp': '.bmp',
+}
+
+/** timestamped cache filename: yyyyMMdd-HHmmss.fffffff-<hash8><ext> */
+function pasteName(ext, hash, now = new Date()) {
+  const p = (n, w) => String(n).padStart(w, '0')
+  const base = `${now.getFullYear()}${p(now.getMonth() + 1, 2)}${p(now.getDate(), 2)}-` +
+    `${p(now.getHours(), 2)}${p(now.getMinutes(), 2)}${p(now.getSeconds(), 2)}.` +
+    `${p(now.getMilliseconds() * 10000, 7)}-${hash}`
+  return `${base}${ext}`
+}
+
+/** 按内容哈希查重：返回已存在的相同图片路径 */
+function findByHashIn(hash, dir) {
+  let names
+  try {
+    names = readdirSync(dir)
+  } catch {
+    return null
+  }
+  for (const n of names) {
+    if (n.includes(`-${hash}.`)) {
+      const p = join(dir, n)
+      if (existsSync(p)) return p
+    }
+  }
+  return null
+}
+
+function pruneCacheIn(dir, maxFiles, maxAgeDays) {
+  if (maxFiles <= 0 && maxAgeDays <= 0) return
+  let entries
+  try {
+    entries = readdirSync(dir)
+      .map(n => {
+        try {
+          const s = statSync(join(dir, n))
+          return s.isFile() ? { n, m: s.mtimeMs } : null
+        } catch {
+          return null
+        }
+      })
+      .filter(Boolean)
+  } catch {
+    return
+  }
+  const now = Date.now()
+  if (maxAgeDays > 0) {
+    for (const e of entries) {
+      if (now - e.m > maxAgeDays * 864e5) {
+        try {
+          unlinkSync(join(dir, e.n))
+        } catch { /* ignore */ }
+      }
+    }
+  }
+  if (maxFiles > 0) {
+    const remaining = readdirSync(dir).length
+    const excess = remaining - maxFiles
+    if (excess > 0) {
+      const alive = entries
+        .sort((a, b) => a.m - b.m)
+        .slice(0, excess)
+      for (const e of alive) {
+        try {
+          unlinkSync(join(dir, e.n))
+        } catch { /* ignore */ }
+      }
+    }
+  }
+}
+
+/** 保存图片字节到缓存目录（内容去重 + 类型命名 + 清理）。返回路径。 */
+function saveImageToCache(buffer, mediaType, opts = {}) {
+  const dir = opts.cacheDir || CACHE_DIR
+  const maxFiles = Number(opts.maxFiles ?? 300)
+  const maxAgeDays = Number(opts.maxAgeDays ?? 30)
+  const hash = createHash('sha1').update(buffer).digest('hex').slice(0, 8)
+  const existing = findByHashIn(hash, dir)
+  if (existing) return { path: existing, deduped: true }
+  mkdirSync(dir, { recursive: true })
+  const ext = IMAGE_EXT[mediaType] || '.png'
+  const target = join(dir, pasteName(ext, hash))
+  writeFileSync(target, buffer)
+  pruneCacheIn(dir, maxFiles, maxAgeDays)
+  return { path: target, deduped: false }
+}
+
+/**
+ * 读取一个**可选**服务，不写进 inject 契约。
+ *
+ * `ctx.reflect.get(name)` 默认 strict：只返回「提供该服务的 fiber 当前处于活动
+ * 状态」的实现。这里再退一步用 strict=false 兜底，避免因为作用域判定而让插件
+ * 永久静默——静默本身是本插件的正常行为，但它必须来自「模型能力判定」，
+ * 而不是来自「我们拿不到服务」。
+ *
+ * @param ctx - cordis 上下文。
+ * @param name - 服务名。
+ * @returns 服务实例，取不到时 undefined。
+ */
+function optionalService(ctx, name) {
+  const reflect = ctx?.reflect
+  if (!reflect || typeof reflect.get !== 'function') return undefined
+  try {
+    return reflect.get(name) ?? reflect.get(name, false)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Auto-OCR: 监听 user/message 里的图片附件，**只在路由到的模型明确不支持
+ * 图片输入时**把图片存到 ~/.dsh/ocr/cache 并把路径注入 agent 上下文，让该模型
+ * 调 ocr_image 本地识别。
+ *
+ * Web 端粘贴的图片由 composer 原生收进附件流程，插件不做任何客户端拦截。
+ * 视觉模型下插件完全静默：harness 自己会在图片前附带只读副本路径，模型需要
+ * 逐字核对时可直接调 ocr_image。判定逻辑见 dsh/capability.js。
+ */
+function registerAutoOcr(ctx, config = {}) {
+  const mode = autoOcrMode(config)
+  if (mode === 'off') return
+  const maxFiles = Number(config.maxCacheFiles ?? 300)
+  const maxAgeDays = Number(config.maxCacheAgeDays ?? 30)
+  // 已处理过的附件引用（防事件重放重复注入）；有界缓存。
+  const seen = new Set()
+  // session.id → 用户刚切换、尚未发请求的模型选择（来源优先级见 pickRoute）。
+  const pendingRoutes = new Map()
+  // `${provider}\0${model}` → inputModalities 数组 | null（查询失败）。
+  const modalityCache = new Map()
+
+  /** 解析某个 provider/model 声明的输入模态；失败或服务缺失返回 undefined。 */
+  async function resolveModalities(route) {
+    if (!route) return undefined
+    const key = modalityCacheKey(route.provider, route.model)
+    if (modalityCache.has(key)) return modalityCache.get(key) ?? undefined
+    let modalities
+    try {
+      const llm = optionalService(ctx, 'llm')
+      if (llm && typeof llm.resolveModelInfo === 'function') {
+        const info = await llm.resolveModelInfo(route.provider, route.model)
+        if (Array.isArray(info?.inputModalities) && info.inputModalities.length > 0) {
+          modalities = [...info.inputModalities]
+        }
+      }
+    } catch { /* 未注册 provider / 未知模型 / 适配器报错 → 视为无法确定 */ }
+    modalityCache.set(key, modalities ?? null)
+    return modalities
+  }
+
+  ctx.on('session/event', async (session, event) => {
+    // 用户在客户端切换模型 → 记下待生效路由，供下一次判定优先采用。
+    if (event.type === 'model/selection') {
+      const route = pickRoute({ pending: event.data })
+      if (route) pendingRoutes.set(session.id, route)
+      return
+    }
+    if (event.type !== 'user/message') return
+    const content = Array.isArray(event.data?.content) ? event.data.content : []
+    const refs = content
+      .filter(b => b && b.type === 'image' && b.attachment)
+      .map(b => b.attachment)
+    if (refs.length === 0) return
+
+    const agent = ctx.agents?.get?.(session.id) || ctx.agents?.list?.().find(a => a.session?.id === session.id)
+    if (!agent || typeof agent.inject !== 'function') return
+
+    // 'always' 模式无条件介入，不必查询模型能力。
+    if (mode !== 'always') {
+      let header
+      try {
+        header = session.requestHeader?.()?.config
+      } catch { /* 无请求头则退回其它来源 */ }
+      const route = pickRoute({ pending: pendingRoutes.get(session.id), header, options: agent.options })
+      const modalities = await resolveModalities(route)
+      if (!shouldInjectOcrPath(mode, modalities)) return
+    }
+
+    const attachments = optionalService(ctx, 'attachments')
+    if (!attachments || typeof attachments.readImage !== 'function') return
+    const paths = []
+    for (const ref of refs) {
+      // 稳定标识是 attachmentId（sha256:…）；ref.id 只是兼容兜底。
+      const refKey = ref.attachmentId ?? ref.id
+      if (refKey && seen.has(refKey)) continue
+      try {
+        const stored = await attachments.readImage(ref)
+        const bytes = Buffer.from(stored.data ?? stored)
+        if (bytes.length === 0) continue
+        const saved = saveImageToCache(bytes, ref.mediaType || 'image/png', { maxFiles, maxAgeDays })
+        if (refKey) seen.add(refKey)
+        paths.push(saved.path)
+      } catch { /* 附件读取失败则跳过，不影响其它图片 */ }
+    }
+    if (seen.size > 5000) seen.clear()
+    if (paths.length === 0) return
+    agent.inject({
+      role: 'user',
+      content: [{
+        type: 'text',
+        text: '用户附上了图片，当前模型不支持图片输入，图片已保存到本地缓存。'
+          + '请用 ocr_image 工具读取其中的文字：\n' + paths.join('\n'),
+      }],
+      source: {
+        kind: 'plugin',
+        plugin: 'dsh-ocr-local',
+        form: 'notice',
+        summary: `已保存 ${paths.length} 张图片到本地 OCR 缓存`,
+      },
+    })
+  })
+}
+
+/* ------------------------------------------------------------------ */
+/* 工具注册                                                             */
+/* ------------------------------------------------------------------ */
+
+function runSetup(python, argv) {
+  return new Promise(resolve => {
+    execFile(
+      python,
+      ['-X', 'utf8', ...argv],
+      { encoding: 'utf8', windowsHide: true, timeout: 900000, maxBuffer: 16 * 1024 * 1024 },
+      (error, stdout, stderr) => {
+        if (error) {
+          let data = null
+          try {
+            data = JSON.parse(stdout.trim())
+          } catch { /* ignore */ }
+          resolve(data || { ok: false, error: (data?.error) || String(error.message || error).slice(0, 300) + (stderr ? ' / ' + stderr.slice(-200) : '') })
+          return
+        }
+        try {
+          resolve(JSON.parse(stdout.trim()))
+        } catch {
+          resolve({ ok: false, error: 'setup 输出无法解析' })
+        }
+      },
+    )
+  })
+}
+
+export function apply(ctx, config = {}) {
+  registerAutoOcr(ctx, config)
+
+  ctx.tools.register(defineTool({
+    name: 'ocr_image',
+    description:
+      'Run local OCR (PP-OCRv5, fully offline) on an image file and return its text content. ' +
+      'Use it when the user references an image file and you need the text in it — no vision model ' +
+      'required. With a model that accepts image input the harness also sends the image itself plus a ' +
+      'read-only copy path; call this tool on that path when you need verbatim characters (code, error ' +
+      'messages, logs, table numbers) or per-line confidence instead of a visual reading. ' +
+      'Returns the recognized text lines with per-line confidence, or a diagnosis (plus a hint to run ' +
+      'the ocr_setup tool) when the OCR engine is not installed yet.',
+    parameters: {
+      path: {
+        type: 'string',
+        required: true,
+        description: 'Absolute path of the image file (png/jpg/webp).',
+      },
+      full: {
+        type: 'boolean',
+        description: 'Return structured JSON (lines + blocks with confidence and box coordinates) instead of plain text.',
+      },
+    },
+    output: {
+      schema: { type: 'object', additionalProperties: true },
+      render: (_args, value) => [{ type: 'text', text: renderText(value) }],
+    },
+    execute: async args => {
+      const path = String(args.path ?? '').trim()
+      if (!path) return { text: '', error: '缺少 path 参数（图片文件路径）', path: '' }
+      if (!existsSync(path)) {
+        return { text: '', error: `图片文件不存在：${path}`, path }
+      }
+      const result = await runOcr(path, config)
+      if (args.full) result.full = { lines: result.lines || [], blocks: result.blocks || [] }
+      return result
+    },
+    timeoutMs: 120000,
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'ocr_setup',
+    description:
+      'Install or verify the local OCR engine (creates a venv, installs onnxruntime/numpy/opencv, ' +
+      'downloads the PP-OCRv5 models with sha256 verification). Use when ocr_image reports the engine ' +
+      'is not ready. Idempotent — safe to run repeatedly. Supports a mirror via DSH_OCR_MODELS_MIRROR.',
+    parameters: {
+      checkOnly: {
+        type: 'boolean',
+        description: 'Only check readiness (python + deps + models), do not install anything.',
+      },
+      noModels: {
+        type: 'boolean',
+        description: 'Install dependencies only, skip model download.',
+      },
+      force: {
+        type: 'boolean',
+        description: 'Force reinstall dependencies even if imports succeed.',
+      },
+    },
+    output: {
+      schema: { type: 'object', additionalProperties: true },
+      render: (_args, value) => [{ type: 'text', text: renderSetup(value) }],
+    },
+    execute: async args => {
+      const python = resolvePython(config)
+      const argv = [SETUP_SCRIPT, '--json']
+      if (args.checkOnly) argv.push('--check')
+      if (args.noModels) argv.push('--no-models')
+      if (args.force) argv.push('--force')
+      if (config.modelDir) argv.push('--model-dir', config.modelDir)
+      const result = await runSetup(python, argv)
+      result.checkOnly = Boolean(args.checkOnly)
+      return result
+    },
+    timeoutMs: 900000,
+  }))
+}

package/ocr/download_models.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+下载 PP-OCRv5 ONNX 模型与字典到缓存目录（默认 ~/.dsh-ocr/models）。
+
+特点：
+- sha256 校验：已存在且校验通过则跳过；损坏/不完整文件自动删除重下
+- 镜像支持：DSH_OCR_MODELS_MIRROR 指定镜像前缀（ghproxy 风格，直接拼在原 URL 前）
+- 原子写入：先写 .part 再 rename，中断不会留下半截"可用"文件
+- 自动重试：单文件最多 3 次
+
+用法:
+    python download_models.py                 # 下载到 ~/.dsh-ocr/models
+    python download_models.py --model-dir D   # 自定义目录
+    DSH_OCR_MODELS_MIRROR=https://ghproxy.com/ python download_models.py
+
+模型来源：paddleocr-onnx 社区发布（PaddleOCR v5 官方模型导出），Apache-2.0 许可。
+"""
+import argparse
+import hashlib
+import os
+import sys
+import time
+import urllib.request
+from pathlib import Path
+
+BASE = "https://github.com/MeKo-Christian/paddleocr-onnx/releases/download/v1.0.0"
+DICT_URL = "https://raw.githubusercontent.com/PaddlePaddle/PaddleOCR/main/ppocr/utils/dict/ppocrv5_dict.txt"
+
+# 文件 -> (默认 URL, sha256)。镜像通过环境变量 DSH_OCR_MODELS_MIRROR 注入。
+MANIFEST = {
+    "PP-OCRv5_mobile_det.onnx": (
+        f"{BASE}/PP-OCRv5_mobile_det.onnx",
+        "ca3014670099126189c9519ef770470c03bf41695fb138c6bc19737bd4ba2875",
+    ),
+    "PP-OCRv5_mobile_rec.onnx": (
+        f"{BASE}/PP-OCRv5_mobile_rec.onnx",
+        "64ea1b54ea0506609378a3638ff5b2547af7e24809b890e501fb0cce54de21f7",
+    ),
+    "ppocrv5_dict.txt": (
+        DICT_URL,
+        "d1979e9f794c464c0d2e0b70a7fe14dd978e9dc644c0e71f14158cdf8342af1b",
+    ),
+}
+
+MODELS_DIR = Path(os.environ.get("DSH_OCR_MODELS") or Path.home() / ".dsh-ocr" / "models")
+RETRIES = 3
+
+
+def sha256_of(path: Path) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(256 * 1024), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def effective_url(url: str) -> str:
+    mirror = os.environ.get("DSH_OCR_MODELS_MIRROR", "").strip().rstrip("/")
+    return f"{mirror}/{url}" if mirror else url
+
+
+def download(url: str, dest: Path, expected_sha: str) -> bool:
+    if dest.exists():
+        try:
+            if dest.stat().st_size > 0 and sha256_of(dest) == expected_sha:
+                print(f"  已存在且校验通过，跳过: {dest.name}")
+                return True
+            print(f"  文件损坏（sha256 不匹配），重新下载: {dest.name}")
+            dest.unlink()
+        except OSError as e:
+            print(f"  校验失败: {dest.name}: {e}", file=sys.stderr)
+            return False
+
+    url = effective_url(url)
+    for attempt in range(1, RETRIES + 1):
+        tmp = dest.with_suffix(dest.suffix + f".part{attempt}")
+        try:
+            print(f"  下载 {dest.name} (尝试 {attempt}/{RETRIES}) ...")
+            req = urllib.request.Request(url, headers={"User-Agent": "dsh-ocr-local/0.3.3"})
+            with urllib.request.urlopen(req, timeout=120) as resp, open(tmp, "wb") as f:
+                total = int(resp.headers.get("Content-Length") or 0)
+                done = 0
+                while True:
+                    chunk = resp.read(256 * 1024)
+                    if not chunk:
+                        break
+                    f.write(chunk)
+                    done += len(chunk)
+                    if total:
+                        pct = done * 100 // total
+                        sys.stdout.write(f"\r    {pct}% ({done // 1024 // 1024}MB/{total // 1024 // 1024}MB)")
+                        sys.stdout.flush()
+            sys.stdout.write("\n")
+            actual = sha256_of(tmp)
+            if actual != expected_sha:
+                print(f"  sha256 不匹配（期望 {expected_sha[:12]}…，实际 {actual[:12]}…），重试", file=sys.stderr)
+                tmp.unlink(missing_ok=True)
+                continue
+            tmp.rename(dest)
+            print(f"  完成: {dest.name} ({dest.stat().st_size} 字节)")
+            return True
+        except Exception as e:
+            tmp.unlink(missing_ok=True)
+            print(f"  失败: {dest.name}: {e}", file=sys.stderr)
+            if attempt < RETRIES:
+                time.sleep(1)
+    return False
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="下载 PP-OCRv5 ONNX 模型（含 sha256 校验）")
+    ap.add_argument("--model-dir", default=str(MODELS_DIR), help="模型缓存目录")
+    args = ap.parse_args()
+    md = Path(args.model_dir)
+    md.mkdir(parents=True, exist_ok=True)
+    print(f"模型目录: {md}")
+    ok = True
+    for name, (url, sha) in MANIFEST.items():
+        if not download(url, md / name, sha):
+            ok = False
+    if ok:
+        print("全部完成 ✓")
+        return 0
+    print("存在失败项，请检查网络或设置 DSH_OCR_MODELS_MIRROR", file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())