dsh-unsloth-hands
Unsloth for DeepSeek Harness——一个纯客户端工具插件，将 Harness 在线模型连接到本地运行的 Unsloth Desktop（Unsloth Studio）服务器，用于重复性文本和视觉（OCR）工作。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add dsh-unsloth-hands@0.1.0Unsloth Hands 以 dsh-unsloth-hands 发布，当前版本为 0.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
dsh-unsloth-hands — give your DeepSeek Harness agent a pair of local hands.
A third-party tool plugin for DeepSeek Harness that lets the online model (your main conversation model) hand repetitive, token-cheap labor to a local Unsloth Desktop (Unsloth Studio) server — plain text work and vision work (image analysis / OCR / comparison).
The main model stays where your deployment puts it. When it decides a job is better done locally, it calls:
unsloth_run — run one prompt on the local text model (batch rewrites, name translations, string munging, short summarization, extraction).unsloth_vision — send images to the local multimodal model (OCR, image analysis, multi-image comparison) with structured report templates.The plugin is a pure client: it only connects to the Unsloth Desktop you are already running. Model selection, downloading, quantization and context settings all happen in the Unsloth app itself — the plugin never starts, owns, or stops any process, and never kills anything.
ctx.tools), following the official dsh-tools contract (defineTool, canonical JSON values, pure render/presenters, exec.signal forwarding).Authorization: Bearer sk-unsloth-…. The key comes from the apiKey config or the UNSLOTH_API_KEY environment variable (create it in Unsloth Settings → API)./v1/models; if Unsloth Desktop is not running you get a clear, actionable error instead of a generic network failure. A wrong/missing key surfaces as AUTH with a hint.content array.data:/http(s): URLs, or the images attached to the current conversation (read through the harness attachment service).analyze (8-section report), ocr (character-exact), compare (multi-image, 5-section) — plus a fidelity rule for the online model (relay verbatim, never invent, preserve uncertainty).llm-unsloth: section in the harness user-settings document overrides the plugin config without a restart.| Item | Requirement |
|---|---|
| Node.js | ≥ 20 |
| DeepSeek Harness | installed (npx @deepseek-ai/dsh web or a source checkout), 0.1.0-rc series |
| Unsloth Desktop | running, with a model loaded and an API key created (Settings → API) |
| Model | any GGUF/safetensors model loaded in Unsloth; vision needs a multimodal model (e.g. Qwen3-VL / Gemma vision GGUFs) |
The package is a standard harness bundle (declares dsh.bundle with its cordis.patch.yml), so the official install path works:
dsh plugin --profile <name> add dsh-unsloth-hands # from npm registry
dsh plugin --profile <name> add github:MicroHEROX/dsh-unsloth-hands # straight from GitHub
It can also be installed as a plain npm dependency in your harness project (the directory whose cordis.yml / cordis.patch.yml composes your deployment), then add the plugin row yourself:
npm install dsh-unsloth-hands
- insert:
- id: unsloth-tool
name: 'dsh-unsloth-hands'
From a source checkout of the harness, you can point the plugin row directly at a clone of this repo:
- insert:
- id: unsloth-tool
name: '../dsh-unsloth-hands'
Installing from GitHub? pnpm may refuse to run the package's
preparebuild script until you allowlist it (exact package key printed by pnpm) in your profile'spnpm-workspace.yaml:allowBuilds: dsh-unsloth-hands: trueThen re-run the
add. Installing from the npm registry needs no such step.
sk-unsloth-… value (it is only shown once).cordis.patch.yml:- insert:
- id: unsloth-tool
name: 'dsh-unsloth-hands'
config:
baseURL: 'http://127.0.0.1:8888' # Unsloth's default port
apiKey: 'sk-unsloth-xxxx...' # from Unsloth Settings → API
That's it. The plugin connects to whatever model is currently loaded — no model names, no config files, no launch flags. Alternatively set UNSLOTH_API_KEY in your environment instead of apiKey.
Installed via
dsh plugin add? The bundle already inserts theunsloth-toolrow — just override its config in your profile'scordis.patch.yml(the harness override form, nonameneeded):- id: unsloth-tool config: apiKey: 'sk-unsloth-xxxx...'
Full config reference (all 10 fields with defaults): docs/api.md §1.2.
unsloth_run — text| param | type | required | meaning |
|---|---|---|---|
prompt | string | yes | instruction/text sent as a user message |
system | string | no | optional system instructions |
temperature | number | no | sampling temperature (0–2) |
max_tokens | integer | no | output cap (default maxTokens) |
stop | string[] | no | stop sequences |
Returns { text, reasoning?, model, usage, elapsedMs }.
unsloth_vision — images / OCR| param | type | required | meaning |
|---|---|---|---|
mode | analyze/ocr/compare | no | built-in prompt template (default analyze) |
prompt | string | no | custom instruction (overrides the template) |
image_paths | string[] | no | local images (png/jpg/jpeg/webp/gif/bmp, ≤20 MB each) |
image_urls | string[] | no | data:image/... or http(s):// URLs |
temperature | number | no | sampling temperature (lower for OCR, ~0.2) |
max_tokens | integer | no | output cap |
stop | string[] | no | stop sequences |
Image sources resolve in order: explicit image_paths + image_urls → the most recent image(s) attached to the conversation → clear error. compare sends 2–4 images in ONE request for joint reasoning.
Returns { text, reasoning?, model, images, usage, elapsedMs }.
Vision requires the model currently loaded in Unsloth to be multimodal. Unsloth serves one loaded model at a time — switch to a vision model in the app before calling
unsloth_vision.
My main model is text-only — how do images get in?
DeepSeek's flagship chat models (and most other routes) are text-only: the harness refuses to send image messages to them (the adapter rejects them with UNSUPPORTED_CONTENT), so you cannot attach an image to the conversation. That is exactly the case unsloth_vision is built for — no harness upload is involved:
unsloth_vision with image_paths: ["<that path>"] (or an image_urls entry), and the local vision model reads the file directly.For a main model that DOES support images, the conversation-attachment source also works automatically.
My requests get 401 Unauthorized?
Unsloth requires a valid key on every request. Create one in Settings → API (revoked keys fail with 401) and put it in apiKey or UNSLOTH_API_KEY. The health probe treats a 401 as "server is running" — the error surfaces from the tool call itself with an actionable message.
Possible / planned directions:
/v1/models to fill the wire model field automatically.dsh-plugin topic.Deliberately NOT planned:
cordis.patch.yml (or cordis.yml):
# delete this block
- insert:
- id: unsloth-tool
name: 'dsh-unsloth-hands'
dsh plugin? dsh plugin --profile <name> remove dsh-unsloth-hands removes both the dependency and its bundle layer.unsloth_run, unsloth_vision) are unregistered automatically — the online model no longer sees them.npm uninstall dsh-unsloth-hands.| Component | Version |
|---|---|
| This plugin | 0.1.0 |
| DeepSeek Harness | 0.1.0-rc series (tested against npm @deepseek-ai/* 0.1.0-rc.6) |
| Node.js | ≥ 20 |
| Unsloth Desktop | any version exposing the external API (/v1/chat/completions) |
Peer dependencies (runtime): @deepseek-ai/cordis ^4.0.1, @deepseek-ai/dsh-tools/dsh-llm/dsh-session/dsh-attachment/dsh-settings/dsh-launch-environment >=0.1.0-rc.2, @deepseek-ai/schemastery ^3.18.1.
npm install
npm run typecheck # tsc --noEmit
npm test # vitest run (46 tests: unit, tool, integration, Loader composition)
npm run build # clean + tsc -> lib/
Tests include a REAL-composition tier (app boot → Cordis Loader → cordis.yml) per the harness testing policy, and a real-machine driver (tests/real-driver.mjs) for main / auth / not-running scenarios.
| doc | content |
|---|---|
| docs/engineering.md | structure, plugin contract, commands, test tiers |
| docs/api.md | authoritative API reference (Config, tools, classes, error codes) |
| docs/glossary.md | standard terminology |
| docs/solutions.md | pitfalls, troubleshooting, methodology |
dsh-llm-deepseek, dsh-tool-todo) that define the patterns we follow.dsh-koboldcpp-hands this project evolved from.MIT. Not affiliated with DeepSeek AI or Unsloth AI; dsh and unsloth are trademarks of their respective owners.