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

典型用法¶

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

常用场景示例：

单模型 + 视觉

• 启动模式：单模型
• 模型：...\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