DeepSeek Harness 插件：llama.cpp 图形启动台

前言¶

本地跑 llama.cpp 通常需要记住一长串参数，反复拼命令、换模型时重复劳动。DeepSeek Harness（DSH）的插件生态允许按需扩展能力，这个插件就是给 DSH 加一个常驻的图形化启动台：选模型、调参数、点启动，不用再背命令行。

插件介绍¶

插件名称是 dsh-llamacpp-studio，维护者为 yu234567。它是一个客户端插件，为 DSH 提供一个 Graphical llama.cpp launcher 和 full parameter workbench。它不替代 Harness 的模型供应商配置，职责是把本地 llama-server 跑起来并让你看得见它。

核心功能¶

1. 完整参数表单¶

插件覆盖 llama.cpp build 10236 的 llama-server --help，共 234 项启动参数，按功能分组：

模型与上下文：-c、-n、-b、LoRA、Control vector、HF / URL / Docker 下载、Embedding、Rerank
CPU / 上下文缓存：线程、批线程、CPU 亲和、优先级、轮询、Flash Attention、RoPE / YaRN、cache type、prompt cache、KV 复用、上下文检查点
GPU / 显存：-ngl、split mode、tensor split、main GPU、--fit、device、MoE CPU offload、KV offload、load mode
采样：temperature、top-k/p/min-p、XTC、DRY、Mirostat、动态温度、grammar、JSON Schema、logit bias
投机解码：draft model、spec type、ngram 系列、draft cache、draft 设备与 GPU 层数
HTTP 服务：CORS、API prefix、Web UI 配置、MCP、Agent 工具、API key 文件、SSL、metrics、slots、router
对话模板与推理：--jinja、chat template、模板参数、reasoning 格式 / 预算 / 保留策略、prefill、warmup
多模态 / 视觉：--mmproj、mmproj URL、图像 token 限制、mmproj GPU offload
日志：日志文件、颜色、verbosity、时间戳、prompt 日志
官方预设：FIM、gpt-oss、Gemma 3 vision、EmbeddingGemma、spec-default
已弃用：--mlock、--mmap、--direct-io、--defrag-thold，保留用于旧命令兼容

「全部参数」页采用左侧分类导航 + 右侧参数区的布局，支持搜索。常用值有下拉预设，布尔参数是三态（不设置 / 开启 / 关闭），可选值参数用下拉框，路径和自由文本可直接输入。额外原始参数是逃生口，按 shell 引号规则解析，追加在表单参数之后。

2. 模型发现¶

自动探测 PATH、~/llama.cpp/build/bin、WinGet 的 ggml.llamacpp_* 包、常见盘符目录；支持手动填写可执行文件和模型目录。递归扫描 .gguf（最多 4 层、4000 个文件），区分模型与 mmproj。模型列表带文件大小，可直接设为模型或 mmproj。目录扫描结果缓存 60 秒，点「扫描模型」强制刷新。

3. 进程生命周期¶

启动前校验可执行文件、模型 / Router 目录、mmproj、端口占用，再以参数数组 spawn，不经过 shell。就绪探测轮询 /health，失败时回退 /v1/models；带 --api-key 时会带 Bearer 头。启动超时、进程提前退出、端口占用都会作为错误显示在页面，同时写进日志。停止时先发 SIGTERM，宽限期后升级 SIGKILL，Windows 下再兜底 taskkill /T /F。插件卸载或 DSH 退出时会停止由它启动的进程，避免孤儿进程。

4. 配置档案¶

「保存配置」写当前表单，「保存为档案」保存整个配置快照，支持多个模型 / 量化 / Router 方案。支持载入、删除档案，导出 / 导入当前配置 JSON。配置文件路径：$DSH_HOME/llamacpp-studio/config.json（Windows 默认 C:\Users\<you>\.dsh\llamacpp-studio\config.json）。

5. 日志¶

环形缓冲保留最近 3000 行，分为 stdout、stderr、system 三类，带序号与时间。支持过滤、自动跟随、复制、下载 .log。启动命令在日志里会把 API Key 和 HF Token 打码。

安全边界¶

这个插件会启动本机可执行文件，因此刻意把攻击面收窄：

只允许回环 socket；浏览器半会附带 x-llamacpp-studio: 1 同源标记，跨站来源的请求会被拒绝
启动使用 spawn(executable, argv) 参数数组，不经过 shell
请求体限制 1 MiB，只接受 JSON
配置与日志只在本机文件系统；没有遥测、没有外发请求
API Key、HF Token 会写入本机配置文件。共享机器上请自行注意文件权限
插件启动的进程归插件管理；卸载 / 退出 DSH 会停止它

如果你通过局域网地址访问 Harness，启动台 API 会拒绝请求，这是预期行为。需要远程使用时，建议在 DSH 前面做认证反向代理，并单独评估风险。

安装与启用¶

这个插件没有运行时依赖、没有构建步骤，直接安装仓库目录即可。

在 DSH 的 设置 → 插件 → 添加插件 里选择「本地目录」，填入仓库目录，例如：

E:\DS\dsh-llamacpp-studio

或者使用 plugin_manager 工具 / CLI（如果 dsh 在 PATH 上）：

dsh plugin --profile desktop add E:\DS\dsh-llamacpp-studio

安装后，如果 Host 没有热加载，重启 DSH；浏览器硬刷新（Ctrl+Shift+R）；侧边栏会出现 llama.cpp 启动台。

也可以从 npm pack 安装：

cd dsh-llamacpp-studio
npm pack
dsh plugin --profile desktop add ./dsh-llamacpp-studio-0.2.4.tgz

典型用法¶

打开侧边栏 llama.cpp 启动台。
点 自动检测，确认 llama-server 路径和模型目录；也可以手动填。
在模型页扫描目录，选一个 .gguf；视觉模型再选对应的 mmproj。
在 快速启动 调整 host / port / ctx / GPU 层数等常用项；需要时到 全部参数 调整。
点 启动服务器，等状态变成 运行中。
点 打开 Web UI 访问 http://127.0.0.1:8080/；或者把该地址填到 DSH 的 OpenAI 兼容 provider 中。
在 运行日志 看加载过程；点 停止服务器 结束进程。

常用场景示例：

单模型 + 视觉

启动模式：单模型
模型：...\Qwen2.5-VL-7B-Q4.gguf
mmproj：...\mmproj-Qwen2.5-VL-7B-f16.gguf
核心参数：ctx-size=8192、gpu-layers=all、flash-attn=on

Router 模式（多模型，不重启进程）

启动模式：Router（模型目录）
模型目录：E:\models
在全部参数里按需设置 --models-max、--models-autoload、--no-models-autoload
注意：Router 模式不传 -m 和 --mmproj，与 llama.cpp 的 router 语义一致。

多 GPU

gpu-layers=all
split-mode=layer（或 row）
tensor-split=3,1
main-gpu=0

低显存

gpu-layers 设为具体层数
开启 --fit
cache-type-k=q8_0、cache-type-v=q8_0
需要时把 MoE 权重留在 CPU：--n-cpu-moe 或 --cpu-moe

适用场景与注意¶

适合需要本地运行 llama.cpp 的 DSH 用户，尤其是希望图形化管理和调参、支持多模型 / Router 场景、需要多 GPU 优化或低显存部署的用户。

插件以当前 dsh 进程权限运行，安装前应检查源码与许可证（MIT）。配置与日志只在本机文件系统，API Key、HF Token 会写入本机配置文件，共享机器上请自行注意文件权限。

结语¶

这个插件把本地 llama-server 的启动、参数配置、进程控制和日志查看整合进 DSH，让本地 LLM 开发更直观。目录页：https://www.skillhub.cn/plugins/yu234567/dsh-llamacpp-studio；GitHub：https://github.com/yu234567/dsh-llamacpp-studio