前言¶

用 DeepSeek Harness 搭智能體，日常會碰到一類任務：批量改寫文案、把一批名稱翻譯成目標語言、清洗字符串、給截圖做 OCR。這些活機械重複、輸出短，如果只能靠在線主模型完成，消耗的就是實打實的 token。

另一邊，很多開發者本機上已經用 Unsloth Desktop 加載了本地模型。問題只剩一個：智能體怎麼「夠到」它。dsh-unsloth-hands 的答案是把兩個工具註冊進 harness 的工具註冊表，讓在線模型在合適的時機把這類工作委託給本地模型。

這是什麼¶

dsh-unsloth-hands（Unsloth for DeepSeek Harness）由 MicroHEROX 維護，MIT 許可，當前版本 0.1.0。一句話定位：一個純客戶端工具插件，讓 DeepSeek Harness 在線模型把重複性的文本與視覺（OCR）工作交給本地運行的 Unsloth Desktop 處理。

兩點設計決定了它的邊界：

• 純客戶端。插件不啓動、不擁有、不停止任何進程，只通過 HTTP 與你已經在運行的 Unsloth Desktop 通信。選模型、下載量化包、設置上下文長度，都在 Unsloth 自己的界面裏完成。
• 工具而非後端。它不替代 harness 的 LLM provider——在線模型仍是主模型，本地模型只通過工具觸達；也不修改 DeepSeek Harness 或 Unsloth 的任何文件。

這個思路和 DSH「一切皆插件」的理念一致：能力以插件形式掛進 ctx.tools，主對話流程不需要動。

核心功能¶

插件註冊兩個面向模型的工具，遵循官方 dsh-tools 契約（defineTool、canonical JSON values、pure render/presenters、exec.signal 轉發）：

1、unsloth_run：向本地文本模型運行一條 prompt，適合批量改寫、名稱翻譯、字符串處理、簡短摘要、信息抽取。

2、unsloth_vision：向本地多模態模型發送圖片，做 OCR、圖像分析、多圖對比，帶結構化報告模板。

幾個工程細節：

• 認證：每次請求攜帶 Authorization: Bearer sk-unsloth-…，密鑰來自 apiKey 配置或 UNSLOTH_API_KEY 環境變量。
• 失敗可操作：每次調用前先探測 /v1/models。Unsloth Desktop 未運行時返回明確可操作的錯誤，而不是籠統的網絡失敗；密鑰錯誤或缺失返回 AUTH 及提示。
• 線路格式：非流式 OpenAI 兼容 chat-completions；圖片以標準多模態 content 數組發送。不支持流式響應，工具調用一次性返回完整答案。
• 活配置：harness 用戶設置文檔中的 llm-unsloth: 段落可以在不重啓的情況下覆蓋插件配置。

視覺工具內置機器可驗證的報告契約：analyze 生成 8 段報告，ocr 要求逐字符精確，compare 對多圖輸出 5 段對比；同時給在線模型定了保真規則——原樣轉述、不編造、保留不確定性。

安裝與啓用¶

安裝¶

這個包是標準的 harness bundle（聲明瞭 dsh.bundle 及配套的 cordis.patch.yml），官方安裝路徑直接可用：

dsh plugin --profile <name> add dsh-unsloth-hands        # from npm registry
dsh plugin --profile <name> add github:MicroHEROX/dsh-unsloth-hands   # straight from GitHub

從 GitHub 安裝時，pnpm 可能要求先在 profile 的 pnpm-workspace.yaml 裏放行 prepare 構建腳本，再重跑 add：

allowBuilds:
  dsh-unsloth-hands: true

從 npm registry 安裝則不需要這一步。

也可以作爲普通 npm 依賴裝進你的 harness 項目，然後手動添加插件行：

npm install dsh-unsloth-hands

- insert:
    - id: unsloth-tool
      name: 'dsh-unsloth-hands'

配置¶

按順序做三件事：

1、啓動 Unsloth Desktop 並加載模型。模型下載和加載都在 Unsloth 的界面裏完成，插件連的就是當前加載的模型，不需要在插件裏寫模型名。

2、創建 API key：avatar → Settings → API → Create，複製 sk-unsloth-… 值（只顯示一次）。

3、在 profile 的 cordis.patch.yml 插入插件行並寫上配置：

- insert:
    - id: unsloth-tool
      name: 'dsh-unsloth-hands'
      config:
        baseURL: 'http://127.0.0.1:8888'              # Unsloth 的默認端口
        apiKey: 'sk-unsloth-xxxx...'                   # 來自 Unsloth Settings → API

也可以用環境變量 UNSLOTH_API_KEY 替代 apiKey。

如果已經通過 dsh plugin add 安裝，bundle 會自動插入 unsloth-tool 行，只需要在 cordis.patch.yml 裏用覆蓋形式改配置：

- id: unsloth-tool
  config:
    apiKey: 'sk-unsloth-xxxx...'

完整的配置參考（全部 10 個字段及默認值）見 docs/api.md §1.2。

兩個工具怎麼用¶

unsloth_run：文本¶

參數：

• prompt（string，必填）：作爲 user 消息發送的指令或文本
• system（string，可選）：system 指令
• temperature（number，可選）：採樣溫度，0–2
• max_tokens（integer，可選）：輸出上限，默認取配置中的 maxTokens
• stop（string[]，可選）：停止序列

返回 { text, reasoning?, model, usage, elapsedMs }。

unsloth_vision：圖片與 OCR¶

參數：

• mode（analyze / ocr / compare，默認 analyze）：內置提示模板
• prompt（string，可選）：自定義指令，覆蓋模板
• image_paths（string[]，可選）：本地圖片，支持 png/jpg/jpeg/webp/gif/bmp，單張 ≤ 20 MB
• image_urls（string[]，可選）：data:image/... 或 http(s):// URL
• temperature（number，可選）：OCR 建議約 0.2
• max_tokens、stop：同上

返回 { text, reasoning?, model, images, usage, elapsedMs }。

圖片來源按順序解析：顯式的 image_paths + image_urls → 當前會話最近附加的圖片（經 harness attachment service 讀取）→ 明確報錯。compare 模式在一次請求裏發送 2–4 張圖做聯合推理。

適用場景與注意事項¶

適合誰：

• 已經在本地跑 Unsloth Desktop、加載了 GGUF/safetensors 模型，希望智能體能調用它的 DSH 用戶
• 工作流裏有重複性文本處理（改寫、翻譯、抽取），或截圖 OCR、多圖對比需求
• 視覺功能需要多模態模型，例如 Qwen3-VL 或 Gemma vision GGUFs

環境要求：Node.js ≥ 20；DeepSeek Harness 已安裝（npx @deepseek-ai/dsh web 或源碼 checkout），0.1.0-rc 系列；Unsloth Desktop 正在運行、已加載模型並創建了 API key。

幾點注意：

• 插件不接管模型生命週期。服務沒啓動、模型沒加載，工具只會報錯，不會替你啓動或下載任何東西，也不會打包或託管 GGUF 模型文件。
• 不支持流式。工具調用一次性返回完整答案，長輸出時需要等待完整結果。
• 它不是離線模式。在線主模型仍是主模型，本地模型只在被工具調用時參與。

安全提醒：和所有第三方插件一樣，dsh-unsloth-hands 以當前 dsh 進程的權限運行。雖然它的設計只做 HTTP 通信、不碰任何進程，安裝前仍建議檢查源碼與許可證。本項目爲 MIT 許可，源碼在 GitHub 公開。

結語¶

dsh-unsloth-hands 解決的問題很具體：不改動主模型的部署，不給 Unsloth 增加管理負擔，只加兩個工具，把「本地模型就在那裏」變成智能體可以直接使用的一項能力。如果你已經在用 Unsloth Desktop，安裝和配置加起來只是幾條命令的事。

• GitHub：https://github.com/MicroHEROX/dsh-unsloth-hands
• 社區目錄頁：https://www.skillhub.cn/plugins/MicroHEROX/dsh-unsloth-hands

社區目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。