前言¶
用 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–2max_tokens（integer，可选）：输出上限，默认取配置中的 maxTokensstop（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 MBimage_urls（string[]，可选）：data:image/...或 http(s):// URLtemperature（number，可选）：OCR 建议约 0.2max_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 / 幻方无官方从属关系。
