前言¶
DeepSeek Harness（DSH）通过插件扩展模型 provider，本地或自托管推理往往走 OpenAI 兼容 HTTP 接口。若后端是 llama.cpp 的 llama-server，除了把 base URL 配进 Harness，开发者通常还需要自己查 /models、看 slot 占用和 prompt/decode 吞吐。社区插件 dsh-llm-llamacpp（维护者 slaren，分类：模型推理）在 DSH 0.2.x 下把一台或多台 llama-server 注册为模型 provider，并在 Composer 侧展示本会话的 prompt/decode 进度与服务器读数。下面介绍它的定位、能力与安装配置方式。
这是什么¶
dsh-llm-llamacpp 是面向 DeepSeek Harness 的 Cordis 插件：为 Harness 增加一个或多个 llama.cpp 服务端路由，并在 composer dock 中显示当前会话的实时 prompt 与 decode 进度。包未发布到 npm（private package）；README 写明在 DSH 0.2.x 与当前构建的 llama-server 上做过测试。插件代码采用 MIT License；与 ggml-org 无隶属或背书关系。
核心功能¶
资料中可核对的能力如下。
显式路由，不做拦截或自动改写。 servers 配置里每个键对应一条 provider 路由，各自拥有 baseURL、可选 alias 与可选凭证引用；不会自动发现或改写端点。
与 Settings → Models 集成。 可在 Models 页添加、编辑 server；每行有绿/红可达性指示。删除路由需手动编辑 servers 映射。
在线发现模型与上下文。 模型列表来自 /v1/models；已加载上下文、输出上限与 modalities 来自 /props；reasoning 等级来自服务端 /apply-template 列表。模型 id、上下文窗口、输出上限与 reasoning 等级均由 server 读取，不在插件配置里写死。
Dock 药丸与对话框。 流式请求期间显示 prompt 进度（含 ETA）、当前 prompt/decode tok/s、各 slot 的 context 与 KV 使用、缓存命中率及原始 server metrics。
并发下的 slot 亲和。 会话固定到稳定的 llama.cpp slot，空闲 slot 复用且不会挤掉活跃对话。
流式行为对齐。 可重试的失败码、assistant reasoning 回放、图像处理、并行 tool call、分离的 usage 统计与 stock pi-ai 路由一致。
无 Web UI 仍可用。 路由、发现与流式在无 web server 环境下仍工作；药丸与对话框不会挂载。
环境要求¶
- DeepSeek Harness 0.2.x。
- 带 OpenAI 兼容 API 的
llama-server。插件依赖：/props提供模型与上下文信息，/apply-template提供 reasoning 等级，/metrics与/slots提供实时读数（后两者可选，缺失时对话框会降级）。
插件不会启动或管理 llama-server，需自行在 Harness 能访问的地址上运行。
启动 llama-server¶
README 建议用下列参数暴露插件要展示的读数：
llama-server \
-m /path/to/model.gguf \
--host 127.0.0.1 --port 9931 \
--metrics --slots --jinja
--metrics：启用/metrics（吞吐、prompt-cache 命中率、投机解码等）；可选，无则 All metrics 仅提示 metrics 已关闭，药丸与 Server slots 仍可用。--slots：启用/slots，供 Server slots 与会话上下文行使用；当前构建默认开启，除非接受失去这些读数，否则不要用--no-slots。--jinja：使用模型 Jinja chat 模板，reasoning 与 tool call 依赖于此；当前构建默认开启，若构建关闭 Jinja 需显式加上。--api-key可选；若启用，在 DSH provider 卡片中配置相同 key。-np大于 1 可让并发会话占用不同 slot；-c设置上下文窗口；二者由/props读取，不在 DSH 里配置。
--props 非必需：插件仅用 GET 读 /props；该 flag 只影响 POST /props。
安装与启用¶
从 GitHub 安装 bundle。可在 Settings → Plugins 按 GitHub 规格安装，或对 plugin_manager 使用 action: install_bundle 并传入：
github:slaren/dsh-llm-llamacpp
HTTPS 形式 https://github.com/slaren/dsh-llm-llamacpp 同样可用。管理器会安装包与依赖、选中 bundle 并应用 bundled 的 cordis.patch.yml；若 DSH 提示需要重启 host，请重启。
命令行等价安装（web 为要安装到的 profile，可按需替换）：
npx @deepseek-ai/dsh plugin --profile web add github:slaren/dsh-llm-llamacpp
若 dsh 已在 PATH 上，可将 npx @deepseek-ai/dsh plugin 换为 dsh plugin。
安装前请自行查看仓库源码与许可证；插件以当前 DSH 进程权限运行，只安装你信任的来源。
配置 provider¶
界面方式：
- 打开 Settings → Models → Add model provider，选择 llama.cpp (new server)。
- 填写完整 API base URL，例如
http://127.0.0.1:9931/v1；仅host:port会被拒绝。 - 可选设置 alias 与 API key（以 DSH credential 引用存储，对应
--api-key启动的 server）；密钥不会写入插件 config 明文。
或在 profile patch 中声明路由：
- insert:
- id: dsh-llm-llamacpp
name: dsh-llm-llamacpp
config:
servers:
llamacpp-local:
alias: local
baseURL: http://127.0.0.1:9931/v1
apiKeyEnv: LLAMACPP_LOCAL_API_KEY
典型用法¶
配置完成并选中 discovered 模型后，照常通过 DSH 发起对话。请求流式输出时，composer dock 上的药丸会显示类似：
- prompt 阶段：
prompt 250/1K (25%) · ETA 5s · 100 tok/s - decode 阶段：
decode · 226 tok · 44 tok/s
点击药丸可展开 Live progress、Server slots、All metrics；折叠状态会保留标题，偏好保存在 localStorage。
无 --metrics 且无 /slots 时，对话框可能没有 server 读数，仅剩药丸自身的 SSE 进度。
适用场景与注意¶
适合： 已在本地或内网运行 llama-server、希望 Harness 统一走 OpenAI 兼容路由，并要在 UI 里观察 slot、KV 与吞吐的 DSH 0.2.x 用户；headless 场景下仍可使用路由与流式，只是没有 dock UI。
注意：
- 遥测端点可选；缺失时对话框功能降级，核心对话仍依赖
/v1与 discovery 端点。 - 社区插件目录（如 SkillHub 上的条目）为独立站点，与 DeepSeek / 幻方无官方从属；安装来源以 GitHub 仓库 README 为准。
icon.svg与客户端药丸/对话框标题中的 llama.brand 为第三方素材，MIT 未再授权该标识，详见仓库CREDITS.md。
链接¶
- 社区目录页：https://www.skillhub.cn/plugins/slaren/dsh-llm-llamacpp
- 源码与完整说明：https://github.com/slaren/dsh-llm-llamacpp
经过上面的步骤，你可以在 DSH 里把 llama.cpp 当作一等 provider 使用，并在需要时用 dock 读数对照 server 侧行为，而无需改 Harness 核心。
