dsh-quicksight：DeepSeek Harness 双层图片识别插件

DeepSeek Harness（DSH）遵循“一切皆插件”的架构理念。对于基于纯文本模型的智能体开发，图片识别能力往往是一个短板。dsh-quicksight 插件通过“本地 OCR + 视觉模型”的双层策略，为纯文本模型补上了识图能力。

该插件由 Isanti2016 维护，采用 MIT 许可证。它注册了一个名为 quicksight_ocr 的工具，能够根据图片内容自动决定是调用本地 OCR 引擎，还是回落到视觉模型进行结构化分析。

工作原理¶

插件的核心逻辑是“先快后准”：先尝试用本地 OCR 快速提取文字，若结果不达标（如字符数不足或乱码），再调用视觉模型进行深度分析。

图片输入
    │
    ▼
quicksight_ocr 工具
    ├─ Tier-1: 本地 RapidOCR
    │   └─ 文本 ≥ minChars(默认20) → 直接返回文本
    │      （耗时约 2-3 秒，完全离线，零 API 成本）
    └─ Tier-2: modlens 视觉模型
       └─ OCR 失败或需要结构化证据 → 调用视觉引擎
          （耗时约 20 秒，返回 summary/OCR/版面/语义）

安装与依赖¶

1. 安装插件¶

使用官方安装命令添加插件。安装后需重启 dsh web 服务，工具才会生效。

npx -y @deepseek-ai/dsh plugin --profile web add dsh-quicksight

2. 准备 Tier-1 本地 OCR（推荐）¶

Tier-1 依赖 Python 环境和 RapidOCR。建议创建独立的虚拟环境。

# 创建虚拟环境
python -m venv ~/.dsh/tools/ocr-venv

# 安装 RapidOCR
~/.dsh/tools/ocr-venv/Scripts/pip install rapidocr_onnxruntime   # Windows
~/.dsh/tools/ocr-venv/bin/pip install rapidocr_onnxruntime       # macOS/Linux

3. 准备 Tier-2 视觉引擎（可选）¶

Tier-2 复用 modlens 生态，需安装 modlens 插件并配置至少一个视觉引擎（如 Nvidia NIM）。

npx -y @liustack/modlens config set openai.baseUrl <https://.../v1>
npx -y @liustack/modlens config set openai.apiKey <你的 key>
npx -y @liustack/modlens config set openai.model <视觉模型>
npx -y @liustack/modlens config set provider openai

配置项¶

插件支持通过环境变量或 cordis.patch.yml 配置。主要配置项如下：

配置键	默认值	说明
`toolName`	`quicksight_ocr`	注册的工具名称
`minChars`	`20`	Tier-1 视为成功的文字阈值（字符数）
`ocrPython`	`~/.dsh/tools/ocr-venv/{Scripts\\|bin}/python`	指向装有 rapidocr 的 Python 解释器
`modlensEnabled`	`true`	是否启用 Tier-2 回落机制
`timeoutMs`	`120000`	单次识别超时时间（毫秒）

运行时与安全¶

端口监听：插件不监听任何端口，属于纯工具型插件，不产生 HTTP/WS 服务。
隐私策略：
- Tier-1：图片完全在本地处理，不上传至任何服务器，零 API 成本。
- Tier-2：图片会发送至用户配置的视觉引擎（如 Nvidia NIM、Gemini 等）。
凭据管理：API Key 仅存储在本地 ~/.modlens/config.json，不包含在插件代码中，不写入会话日志。

已知限制¶

免费引擎限制：若使用免费的视觉引擎（如部分免费额度），可能遇到速率限制（返回 429/404），Tier-2 失败时会降级报错。
能力边界：Tier-1 仅提取文字，不支持颜色、布局、图表或人脸分析；此类分析需依赖 Tier-2 视觉模型。
格式支持：支持常见图片格式（PNG/JPG/BMP/TIFF/WebP），不支持 PDF 文档。