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 倉庫