前言¶

在 DSH 這類插件化運行環境裏，一個常見的問題是：文本模型本身不接收圖片，但開發者經常需要把截圖、票據、界面文字交給模型處理。常見做法是把模型配置成多模態，或者直接把圖片字節發給遠端模型 API。本文介紹的 maxwell-feng/dsh-windows-ocr 是另一個做法：在 Windows 本機先用 Windows.Media.Ocr 識別圖片，再把識別出的文本發送給模型。下面介紹它的功能、安裝方式和注意事項。

這是什麼¶

maxwell-feng/dsh-windows-ocr 是 DeepSeek Harness (dsh) 插件，由 maxwell-feng 維護，採用 MIT 許可證。

它的作用是：讓 text-only 模型接受附加圖片；插件先用 Windows 內置 OCR 引擎 Windows.Media.Ocr 在本地識別圖片，再把識別文本發給模型。對於真正的視覺模型，是否透傳原始圖片字節是可選行爲。

核心功能¶

下面這些是已覈實的插件能力：

• 讓 text-only 模型接受附加圖片。
• 使用 Windows.Media.Ocr 在本地識別圖片。
• 默認只向模型 API 發送識別出的文本，不發送原始圖片字節。
• 支持可選 passthrough: true，讓真正的視覺模型接收原始圖片字節。
• 不需要在 settings.yaml 中把模型改成 input: [text, image]。
• 支持 dsh 中任意 provider/model；默認在請求離開本機前對附加圖片做 OCR。
• fail-closed：插件未加載時，模型保持 text-only 並拒絕圖片附件。
• 缺失附件會被替換爲 refusal text block，而不是保留 raw image。
• 提供 language、passthrough、ocrScript、timeoutMs、maxCacheEntries 配置項。
• 從 npm 安裝的版本預構建並帶 Sigstore provenance，無需源碼構建或 allowBuilds。

安裝與啓用¶

安裝前先確認環境滿足：Windows 10/11，Windows PowerShell 5.1+，目標語言的 Windows OCR 語言包；中文需要可用的 Chinese language pack；已有 dsh 和 profile，package.json 聲明 Node.js >= 20。README 說明測試版本爲 dsh 0.1.0-rc.8。

從 npm 安裝¶

先執行下面命令，將插件安裝到 web profile：

dsh plugin --profile web add @maxwell-feng/dsh-windows-ocr

如果使用的是其他 profile，把 web 替換爲 tui 等 profile 名。

npm 安裝版本會自行註冊 windows-ocr loader entry，不要再手動添加同一個 entry id。

永久安裝¶

如果是源碼或手動文件方式，先準備插件文件路徑。下面示例追加到 profile 的 cordis.patch.yml：

- insert:
    - id: windows-ocr
      name: 'file:///C:/absolute/path/to/windows-ocr/lib/index.js'
      config:
        language: ''
        passthrough: false

Windows 文件路徑必須使用 file:// URL；裸 C:/... 路徑會被 loader 拒絕。

配置 passthrough 時，false 表示默認 OCR 所有圖片；true 才讓視覺模型接收未處理圖片。

修改後重啓 dsh web。

臨時安裝¶

臨時安裝可以先準備同樣的 rows 到 overlay 文件，再執行：

dsh --profile web --patch C:/path/to/overlay.yml

這種方式不會修改 profile。

覆蓋配置¶

如果 windows-ocr row 已存在，用 id-targeted row 覆蓋配置，而不是再 insert 一個同名 row。示例：

- id: windows-ocr
  config:
    language: zh-Hans

典型用法¶

下面從安裝到驗證按順序做。

1、安裝完成後，啓動 dsh web，在啓動日誌中查看 windows-ocr。

2、給一個文本模型會話附加圖片。

3、觀察模型是否用識別出的文本回答。

模型看到圖片時，每個 image block 會被替換爲類似下面的文本塊：

<image_ocr>
...
</image_ocr>

如果啓動 dsh web 時出現 EADDRINUSE，先執行下面命令找到佔用 3080 端口的舊實例並停止它：

netstat -ano | findstr :3080

適用場景與注意¶

適合的場景：

• 在 Windows 10/11 上運行 dsh，並希望文本模型能處理本地圖片中的文字。
• 希望默認不把原始圖片字節發送到模型 API，而只發送本地 OCR 後的文本。
• 需要在 dsh 中切換不同 provider/model，但不想逐個修改模型能力配置。

注意：

• 不要同時使用 npm bundle 和手動 insert 註冊同一個 windows-ocr entry id；否則 dsh 啓動會失敗，報錯爲 duplicate loader entry id: windows-ocr。
• passthrough: false 是默認行爲，OCR 所有圖片；只有顯式設置 passthrough: true，真正的視覺模型才接收未處理圖片。
• 插件未加載時是 fail-closed：模型保持 text-only 並拒絕圖片附件，缺失附件會被替換爲 refusal text block，而不是保留 raw image。
• 插件以當前 dsh 進程權限運行；安裝前應檢查源碼、依賴和 MIT 許可證。
• 中文 OCR 需要可用的 Chinese language pack；其他語言也需要對應的 Windows OCR 可用語言包。

結尾¶

maxwell-feng/dsh-windows-ocr 的價值在於：把“文本模型處理圖片”這件事落成本地 OCR 與文本注入，默認只向模型 API 發送識別文本。下面鏈接可用於查看項目：

• 插件目錄頁：https://www.skillhub.cn/plugins/maxwell-feng/dsh-windows-ocr
• GitHub 倉庫：https://github.com/maxwell-feng/dsh-windows-ocr