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 文檔。