前言¶
在 DeepSeek Harness（DSH）里跑本地小模型，常见做法是单独起 llama-server，再在 profile 里手写 OpenAI 兼容路由。启停、上下文与路由不一致、长对话压缩溢出、以及「线上模型能不能把翻译/OCR 这类杂活甩给本机」往往要分好几处改配置。维护者 verson00 的 dsh-local-llm 把本机 llama.cpp 上的 Qwen3.5-4B 收进 设置 → 本地模型 一页：启停、启动参数、部署路径、与 cordis 的路由和压缩策略联动，并附带请求形状诊断与 local_worker 混合作业。插件分类为模型推理，当前 GitHub 星标为 0，许可证 MIT，版本 1.0.2。
这是什么¶
dsh-local-llm 是 DSH 的 bundle 插件：host 半为 ESM（index.js），client 半为手写模块，零依赖、零构建，装进 profile 即可用。面向 DSH 0.2.x（README 写明在 0.2.1-rc.5 上开发与验证；package.json 要求 engines.dsh 为 >=0.2.2-rc.1 <0.3.0）。运行环境文档写明为 Windows + NVIDIA GPU（8 GB 显存可跑 4B Q4），需自备 llama-server.exe（项目在 b12069 验证）及 Qwen3.5-4B 的 GGUF 与 mmproj。
目录与源码：
- 插件目录页：https://www.skillhub.cn/plugins/verson00/dsh-local-llm
- GitHub：https://github.com/verson00/dsh-local-llm
核心功能¶
启停与状态¶
插件自行 spawn 本机 llama-server，参数由设置页决定，支持一键启动、停止、重启。状态灯含义：绿为就绪、黄闪为加载中、灰为已停止、红为失败；失败时可展开 server.err.log 末尾。页面显示加载耗时、PID、端口、显存占用与当前启动参数。可与手动脚本共存：与 start.ps1 共用 pid 文件与日志时，页面显示「已就绪（外部启动）」，也可从页面停止。
启动参数¶
可配上下文长度（512–262144，8 GB 卡建议 ≤ 65536）、线程数、端口、主模型与视觉投影文件（自动扫描模型目录 .gguf）、视觉开关、思考模式与预算、历史思考保留、采样温度等。
部署路径与检测¶
四项路径——安装根目录、llama-server.exe、模型目录、日志目录——留空时按根目录推导：
exe = <root>\bin\llama-b12069\llama-server.exe
models = <root>\models
logs = <root>\logs
「检测」会校验存在性、列出模型目录中的 .gguf，给出「部署可用」或「不完整」。模型装在其它盘时改路径即可，无需改插件代码。
模型路由与压缩策略联动¶
自动将 provider local-qwen 的 contextWindow、maxTokens、baseURL 与页面设置对齐（写 cordis.patch.yml 并保留注释）。对 compaction-basic 写入本地模型专用压缩策略（headroomTokens: 0 加显式摘要上限），避免小窗口下触发点为负、每步压缩、摘要请求自身溢出的默认行为。
请求捕获（诊断）¶
插件在默认 loopback 端口 8091 起透明反向代理，把 provider 路由指过去后可观察 DSH 真实请求形状：消息数与角色分布、思考字段形态、工具输出体量、schema 字节数、max_tokens、是否流式等。只记录形状、不存正文、不落盘。页面可一键切换「经代理」或「直连」。
混合工作流（local_worker）¶
开启后注册 local_worker 工具与系统提示，在线模型可把自包含杂活交给本地 4B：
| action | 用途 | 输入 |
|---|---|---|
text |
翻译、摘要、改写、提取要点、格式化 | path 或 input |
image |
看图、OCR、抄写画面文字 | paths |
video |
等距抽帧后逐帧分析，返回带时间戳文字 | path + frames |
每请求自动带 chat_template_kwargs: { enable_thinking: false }，避免输出预算耗尽在思考块、正文为空。
安装与启用¶
前置¶
- DSH
>=0.2.2-rc.1 <0.3.0（不满足时组合阶段会跳过本 bundle）。 - Windows、NVIDIA GPU、llama-server、Qwen3.5-4B GGUF 与 mmproj（见下文模型文件）。
安装步骤¶
-
取得插件目录（克隆或解压），确认含
package.json、index.js、lib/、client/。 -
装进 DSH profile：让 agent 执行（路径换成本机绝对路径）：
plugin_manager install_bundle（action: install_bundle, target: <本目录的绝对路径>）
等价做法：在 profile 的 package.json 增加 "dsh-local-llm": "link:<本目录>"，并在 bundle 选择列表加入 dsh-local-llm。
-
重启 DSH（host 半在启动时加载）。重启后设置页左侧出现「本地模型」。
-
若尚未配置路由，在 profile 的
cordis.patch.yml增加 OpenAI 兼容路由（示例与 README 一致）：
- id: llm-pi-ai
name: "@deepseek-ai/dsh-llm-pi-ai"
config:
providers:
local-qwen:
displayName: 本地 Qwen3.5 4B
api: openai-completions
baseURL: http://127.0.0.1:8080/v1
headers:
Authorization: Bearer local-no-auth
models:
- id: qwen3.5-4b
name: Qwen3.5 4B (本地)
contextWindow: 65536
maxTokens: 8192
input: [text, image]
reasoningEfforts: false
- 将
Qwen3.5-4B-UD-Q4_K_XL.gguf与mmproj-F16.gguf放入<安装根目录>\models\，确认llama-server.exe在<安装根目录>\bin\llama-b12069\。
收录进插件市场前，也可在 插件 → 添加插件 填仓库地址，或命令行：
dsh plugin --profile <profile> add github:verson00/dsh-local-llm
https://github.com/verson00/dsh-local-llm
典型用法¶
- 打开 设置 → 本地模型。
- 展开「部署路径」，确认四项均为 ✓，或改为本机路径后点「检测」。
- 展开「启动参数」，按显存设置上下文（8 GB 卡建议 ≤ 65536），点「保存」。
- 在「服务状态」点「启动」，待状态灯变绿（约 3–10 秒）。
- 在模型选择器选「本地 Qwen3.5 4B」对话；或在会话中让 agent 使用
local_worker。 - 需要混合作业时，展开「混合工作流」打开开关并保存。
停止：设置页点「停止」，或 stop-llm.cmd。插件停止时不会结束已独立运行的模型进程。
spawn 失败或旧版崩溃时的外部启动¶
1.0.1 曾因未监听 spawn 的 error 事件导致点「启动」后 DSH 整体退出；1.0.2 已修复为仅标红并提示原因。若 Windows 上仍无法由插件 spawn，可按 README 用 PowerShell 外部启动；插件通过 /health 与 logs\server.pid 识别，页面显示「已就绪（外部启动）」，路由与 local_worker 仍可用。外部启动示例参数中强调 --parallel 1、--ctx-size 与设置页一致、--reasoning off、看图需 --mmproj。
模型文件¶
- 基座：Qwen/Qwen3.5-4B
- 本机常用：
Qwen3.5-4B-UD-Q4_K_XL.gguf（约 2.8 GB）、mmproj-F16.gguf（约 0.7 GB） - GGUF 可从 Hugging Face 上 Qwen3.5-4B 的 GGUF 仓库获取，例如 unsloth/Qwen3.5-4B-GGUF
README 给出 RTX 4060 8 GB 下的实测表（32768 ctx 约 62.9 tok/s；162144 ctx 约 17.7 tok/s 且更多分页到系统内存）。超过约 64K 上下文速度会明显下降，长对话应依赖压缩策略。
适用场景与注意¶
适合谁：已在 DSH 0.2.x 上开发、想在 Windows 本机固定跑 Qwen3.5-4B，并希望路由、压缩、诊断与「线上主模型 + 本地杂活」在同一套 profile 里维护的开发者。
环境与权限：插件以当前 DSH 宿主进程权限运行；安装前应阅读仓库源码与 MIT 许可证，确认路径与 spawn 行为符合本机安全策略。请求捕获代理仅记元数据，但仍会短暂经过 loopback，诊断结束后建议改回直连。
常见问题（摘自 README）：模型路径错误导致红灯；8080 端口占用；路由「不一致」时点「同步」；local_worker 报未运行时需先启动服务或开启「需要时自动拉起」。
DSH 生态强调「一切皆插件」；SkillHub 等社区目录为独立站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-local-llm 把本机 llama.cpp Qwen3.5-4B 的运维面、与 Cordis 的路由/压缩一致性、请求形状诊断和 local_worker 混合作业收进一页设置，减少「脚本、YAML、手动对齐」的分散操作。详情与 issue 见 GitHub：https://github.com/verson00/dsh-local-llm；目录条目见 https://www.skillhub.cn/plugins/verson00/dsh-local-llm。
