dsh-llamacpp: 本地 llama.cpp 适配器

DeepSeek Harness (DSH) 采用插件化架构。如果你需要在 Harness 环境中调用本地部署的模型（如 llama.cpp），需要通过适配器将请求转发到本地服务器。dsh-llamacpp 插件正是为此设计的连接器。

插件定位¶

这是 jwilson411 开发的 DeepSeek Harness LLM 适配器插件，用于连接本地 llama-server。

它通过 llama.cpp 的 OpenAI 兼容接口 /v1/chat/completions 与服务器通信，并在 Harness 的 ctx.llm 路由中注册为 llamacpp provider。安装后，llamacpp 作为一个 provider 路由存在，Harness 会通过 ctx.llm.stream() 调用它。

核心功能¶

• 连接本地 llama.cpp OpenAI 兼容服务器
• 注册 llamacpp provider 路由
• 支持流式文本输出
• 支持工具调用 (tools) 转发
• 包含多种错误处理逻辑

安装¶

通过命令行安装插件。该包包含 dsh.bundle.patch，会自动将配置好的 llamacpp 行插入到当前 profile 中。

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

典型用法¶

确保本地已启动 llama-server。以下是启动示例：

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

在 Harness 的 Cordis overlay 配置中，指向该服务器：

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

配置说明¶

插件的配置项及默认值如下：

配置逻辑说明：
- baseURL 已包含 /v1，请求会发送到 ${baseURL}/chat/completions，注意不要在 URL 中重复 /v1。
- 环境变量优先级高于配置项。如果配置项为空，会尝试读取对应的环境变量；若环境变量为空，则视为未设置。
- provider 默认值为 ['llamacpp']。

错误处理与限制¶

插件会显式抛出错误，不会吞没任何失败情况。

错误码¶

• PROVIDER_UNREACHABLE: 连接被拒绝、DNS 失败或流中断（通常 llama-server 未运行）。
• PROVIDER_HTTP_ERROR: 非 2xx HTTP 响应。
• PROVIDER_ERROR: 服务器返回的 error 负载。
• PROVIDER_PROTOCOL_ERROR: 流式帧不是 JSON 格式。
• UNSUPPORTED_CONTENT: 消息中包含图片、工具调用或工具结果块（插件仅支持文本）。

限制¶

• 仅支持文本：不支持图片或工具结果。
• 不是工具：它注册的是 provider，不是工具，不会注册到 ctx.tools。
• 不支持 Ollama：它只认识 llama-server，不认识 Ollama 的 /api/* 路由或自动模型拉取机制。

结语¶

dsh-llamacpp 是一个专注于文本流的轻量级适配器。如果你使用的是原生 llama.cpp 服务器，它可以直接将 Harness 的调用转化为 OpenAI 格式的请求。目前仅支持文本，不支持图片和复杂的工具调用链路。

• 插件目录
• GitHub 仓库