jwilson411/dsh-llamacpp

dsh-llamacpp

一个用于本地 llama.cpp 服务器的 DeepSeek Harness LLM 适配器插件，通过其兼容 OpenAI 的 /v1/chat/completions API 进行通信。

这是 llama.cpp，不是 Ollama。 它直接与 llama-server 通信——即你从 llama.cpp 构建或下载的那个二进制文件——并且对 Ollama 的模型注册表、其 /api/ 路由或其自动模型拉取一无所知。如果你运行的是 Ollama，那么这个插件不适合你。

它也不是一个工具。它不会在 ctx.tools 上注册任何内容；它会在官方 LLM 接缝上注册一个提供者：

ctx.llm.registerAdapter(['llamacpp'], adapter)

一旦注册，llamacpp 就像其他任何提供者路由一样，harness 会通过 ctx.llm.stream() 将模型调用路由到它。

安装

dsh plugin --profile web add github:jwilson411/dsh-llamacpp

该包附带指向 cordis.patch.yml 的 dsh.bundle.patch，因此添加它会将一行配置好的 llamacpp 插件插入到 profile 中。

固定版本的 harness RC

基于 @deepseek-ai/dsh- 包的 0.1.1-rc.2 构建——与 jwilson411/dsh-plugin-kit 和 jwilson411/dsh-spend-receipt 相同的 RC。请注意，@deepseek-ai/dsh-llm 的 latest dist-tag 仍指向 0.0.1-rc.1；RC 系列位于 next 标签下，这就是为什么开发依赖固定为精确版本而不是跟踪 latest。

所使用的接缝是来自 @deepseek-ai/dsh-llm 的 LlmAdapter、LlmError、attributionHeaders 和 errorChain。如果其中某个名称在后续 RC 中发生变动，此包将保持固定到 0.1.1-rc.2，直到被有意更新。

运行 llama.cpp

使用你已有的权重启动 llama-server。对此插件有影响的标志：

| 标志 | 为何在此重要 |
| --- | --- |
| --port 8080 | 默认 baseURL（http://127.0.0.1:8080/v1）中的端口。 |
| --alias qwen | 服务器接受且此插件发送的模型名称。将其设置为与 model 匹配，或将 model 设置为与它匹配。 |
| --api-key | 如果设置，每个请求都必须携带 Authorization: Bearer …。将 apiKey（或 DSH_LLAMACPP_API_KEY）配置为相同的值。 |
| -c / --ctx-size | 上下文窗口。超过它的请求会在服务器端失败；此插件会呈现该失败而不是截断。 |

示例：

llama-server -m qwen.gguf --port 8080 --alias qwen -c 32768 --api-key $DSH_LLAMACPP_API_KEY

卸载标志（-ngl、张量分割等）是你和你硬件之间的事——它们不会改变任何线路协议，因此此插件对它们没有意见。

配置

| 键 | 环境变量回退 | 默认值 |
| --- | --- | --- |
| baseURL | DSH_LLAMACPP_BASE_URL | http://127.0.0.1:8080/v1 |
| model | DSH_LLAMACPP_MODEL | qwen |
| apiKey | DSH_LLAMACPP_API_KEY | （未设置——不发送 Authorization 头） |
| provider | — | ['llamacpp'] |

patch 行优先于环境变量；环境变量填补该行未设置的内容。一个
导出但为空的变量算作未设置。

baseURL 已经包含 /v1，请求会发往 ${baseURL}/chat/completions —— /v1 永远不会被重复。
如果你的服务器位于会剥离该前缀的代理之后，请将 baseURL 设置为代理实际提供的基础地址。

Cordis 覆盖

要将插件指向不同的服务器、模型或凭据，请在你的 profile 覆盖中定位 llamacpp id。以 id 为目标的补丁会替换整个 config 对象，因此请重复你想要的每一个字段，而不只是你正在更改的那个：

- id: llamacpp
config:
baseURL: http://127.0.0.1:9090/v1
model: qwen3-coder
apiKey: change-me

它发送什么

每次模型调用，发送一个 POST ${baseURL}/chat/completions，并带有 stream: true。每个请求都会合并来自 @deepseek-ai/dsh-llm 的 attributionHeaders()（一个标识该 harness 的 User-Agent —— 这是公开的产品事实，不含机密），并转发 options.signal，因此中止的回合会中止 HTTP 请求。

请求映射：

- options.system 作为 system 消息前置。
- options.messages 变为 OpenAI 的 { role, content } 消息；文本块会被拼接。
- options.tools 变为 OpenAI 的 tools 数组。
- options.temperature、options.stop 直接传递。
- options.maxTokens 映射为 max_tokens —— llama.cpp 的服务器不读取 max_completion_tokens。
- 当请求携带 options.model 时使用它，否则使用配置的 model。

它产出什么

harness 的 StreamChunk 协议，按顺序：

1. block-start，索引 0，blockType 为 text
2. 每个 choices[0].delta.content 字符串对应一个 text-delta
3. block-end，携带完整组装后的 { type: 'text', text }
4. usage，当服务器报告了任何用量时（prompt_tokens → inputTokens，completion_tokens → outputTokens；llama.cpp 没有缓存拆分，因此不会虚构缓存字段）
5. finish，最后

没有产生任何文本的响应不会打开块，因此每个 block-start 仍然有其对应的 block-end。

finish_reason 映射为 { kind: 'stop' }，tool_calls 映射为 { kind: 'tool-calls' }，length 映射为 { kind: 'max-tokens' } —— 被截断的答案不会被报告为完整的答案。

某些构建和代理会忽略 stream: true，并以单个 JSON chat.completion 作答。这会被转换为完全相同的 chunk 序列。

失败会大声报错

没有任何东西会被吞掉变成空流。每个失败都是一个带有稳定 code 的 LlmError：

| 代码 | 何时 |
| --- | --- |
| PROVIDER_UNREACHABLE | 连接被拒绝、DNS 失败、流中途重置 —— 通常是 llama-server 未运行。 |
| PROVIDER_HTTP_ERROR | 非 2xx 应答；携带 HTTP status 并引用响应体。 |
| PROVIDER_ERROR | 服务器以 error 负载在带内报告了自身的失败。 |
| PROVIDER_PROTOCOL_ERROR | 一个不是 JSON 的流帧。 |
| UNSUPPORTED_CONTENT | 消息携带了图像、工具调用或工具结果块。 |
调用方驱动的中止会原样重新抛出，因此运行时将其报告为 aborted 完成，
而不是服务器死掉。

仅文本

这是一个轻量适配器。它发送文本并流式返回文本。图像块会被拒绝，而不是
悄悄丢弃，因为丢弃一个图像块会把调用方从未编写的对话交给模型；工具调用和工具结果块
也是如此，因此完整的工具往返在此不在范围内，尽管 options.tools 会被转发，并且会报告
tool_calls 完成。

开发

npm install
npm test

测试使用 Node 的 http 和 node:test 模拟一个 OpenAI 兼容服务器。无需 GPU、无需下载权重、
无需真实的 llama.cpp 进程，也无需回环之外的网络。

许可证

MIT © 2026 jwilson411