Fruffel/dsh-llm-llamacpp

dsh-llm-llamacpp

一个用于 DeepSeek Harness 的 llama-cpp 提供程序：它是
huggingface/pi-llama 在 harness 一侧的孪生实现。

一个正在运行的 llama-server 就是全部配置。该插件从 GET /v1/models 读取模型
目录，并且——这正是本练习的重点——从服务器本身读取上下文
窗口，因此压缩、token 计量器以及 GUI 的
上下文显示都会根据服务器当前加载的内容自动调整大小。
替换服务器背后的模型后，下一轮就已经知道新的
窗口；这里无需编辑任何内容。

GET /props     → default_generation_settings.n_ctx  ← 权威上下文窗口
chat_template                      ← 决定思考能力
GET /v1/models → data[].meta.n_ctx                  ← /props 缺失时的回退
row contextWindow                                   ← 你固定的覆盖值，优先于以上两者

这两个事实都来自同一次探测，并且该探测与 1.5 秒的
截止时间赛跑：缓慢或不可达的服务器只会一次性带来一点延迟，而绝不会
影响答案——下一次调用会发现它已被缓存。上下文窗口缓存 60 秒，
模板能力则在模型保持不变期间一直缓存。

安装

该插件是一个自包含的包：将此目录复制到运行
harness 的机器上的任意位置，并从 profile 的补丁文件中挂载它。

- insert:
- id: llm-llamacpp
name: /absolute/path/to/dsh-llm-llamacpp/index.mjs
config:
baseURL: http://localhost:8080/v1

Web profile 会实时重载 cordis.patch.yml，因此该提供程序无需
重启即可出现。journalctl --user -u dsh-web -f 会显示挂载情况和任何诊断信息。

发布变更

此仓库是事实来源；部署会挂载它的一个检出副本。
在开发它的机器上，部署是一个 dsh-ops 检出副本，其
plugins.conf 指定了此仓库，因此循环如下：

in this checkout
git commit && git push
in the deployment
bin/dsh-plugins.sh --update      # fast-forwards the clone under plugins/
bin/dsh-install-assets.sh        # copies the package into the profile layer
systemctl --user restart dsh-web # the harness keeps the module it imported

配置编辑（新的 baseURL）无需重启即可生效——profile
会重载其补丁层，并且该值按请求读取。代码编辑则
不会：harness 会保留它导入的模块，因此 index.mjs、client.mjs 和
lib/.mjs 需要重启。

harness 需要从宿主机获得两样东西：

harnessRoot —— harness 检出副本所在的位置。该插件从它导入
harness 自身的 LlmAdapter、LlmError 和 attributionHeaders，以便
错误标识和归属信息与运行时预期的完全一致。该
字段之所以存在，是因为默认值是某台机器的构建路径；请将其设置为你自己的路径。
* Node 22+，harness 已经要求这一点。

配置卡片
Web GUI 会就地编辑此提供方。设置 → 模型会显示一行
llama.cpp，其卡片在被请求之前保持关闭：一行状态会
报告所配置的端点是否有响应——有响应时显示绿点，没有响应时显示
红点，旁边附上原因——以及该端点是哪个，
以及它提供多少个模型。点击该行——它自己的 Configure
控件，而不是页面的 Edit 按钮（后者会为此系列打开 Host 的通用编辑器）
——会展开一张包含以下所有字段的卡片、一个 Test connection
按钮（它会查询正在输入的端点，并报告它找到的模型和
上下文窗口），以及 Reset to composition（它会清除该部分，
使该行自身的值再次生效）。

那个点是卡片自己的，而且是有意为之：llama.cpp 会忽略
凭据，因此页面自己的凭据点永远不会为此系列亮起，而且
除了实时探测之外，没有什么能说明路由背后的服务器是否已启动。该
探测与 Test connection 按钮所做的 llm/discoverModels 调用相同，
因此该点和模型列表不可能不一致；它在卡片
出现时运行一次，并在每次保存或重置后再次运行。

该卡片是本包的浏览器部分（client.mjs，在 package.json 中声明为
dsh.client），以 llm-llamacpp 键注册到 settings.models.provider-card
槽位中。编辑会落到设置文档中的 llm-llamacpp，并
到达下一个请求——无需重启。只有对插件自身代码的更改才需要
重启。

Configure

harness/cordis.patch.web.yml 中的一行（安装程序会将其渲染为
~/.dsh/profiles/web/cordis.patch.yml）：

- insert:
- id: llm-llamacpp
name: ./dsh-llm-llamacpp/index.mjs
config:
baseURL: http://localhost:18080/v1   # ← the one knob
displayName: llama.cpp

baseURL 按以下顺序解析：此行，然后是环境中的 LLAMA_BASE_URL，
然后是 http://localhost:8080/v1。没有尾部 /v1 的值会
被加上一个，因此 http://host:8080 和 http://host:8080/v1 是同一个端点。

| 字段 | 默认值 | 含义 |
| --- | --- | --- |
| baseURL | 环境变量 LLAMA_BASE_URL，然后是 http://localhost:8080/v1 | llama.cpp API 基础地址 |
| apiKey | 环境变量 LLAMA_API_KEY，然后是 no-key | Bearer 令牌；除非设置了 llama-server --api-key，否则会被忽略 |
| headers | 无 | 额外请求头，用于服务器前面的代理 |
| displayName | llama.cpp | 提供方选择器中的名称 |
| contextWindow | 自动发现 | 固定的上下文大小 |
| discoverContext | true | 询问 /props；从不响应的服务器仍可提供聊天 |
| maxTokens | 从上下文窗口推导 | 每个请求通告的输出上限 |
| temperature | 无 | 当请求未指定时应用 |
| probeTimeoutMs | 1500 | 在请求不等待它而继续之前，/props 可以花费多长时间 |
| logLevel | silent | info 会记录启动时发现的内容 |
| harnessRoot | 此构建的检出目录 | 从中加载 LLM 接缝的 Harness |
除了 displayName 和 harnessRoot 之外，卡片上的每个字段都可编辑，
这两个字段保持在组合层：显示名称属于声明该路由的那一行，
而检出路径是机器的属性，不是端点的属性。

每个字段同时也是 llm-llamacpp 设置分区 的基础层，
因此 Settings 和 Models 页面可以编辑实时端点，而无需改动组合或重启任何东西。解析是按调用进行的：设置变更会作用于下一个请求。

使用

路由 id 是 llama-cpp，模型 id 是服务器所通告的任意值
（GET /v1/models，例如 GGUF 别名）。将其选为会话模型，或在 ~/.dsh/settings.yaml 中将其设为默认值：

agent-default-model:
provider: llama-cpp
model: Qwen3-8B-Q4_K_M

重新加载

Web 配置文件会实时重新加载 cordis.patch.yml，因此 配置 编辑（新的
baseURL）会作用于下一个请求，无需重启。编辑插件自身的
代码 则不会：harness 的模块图会保留它导入的版本，因此
更改后的 index.mjs/lib/.mjs 需要先运行 npm run assets，再
重启 dsh-web 才能生效。

注意事项与限制

仅文本。 携带图片或文件附件的消息会失败并返回
UNSUPPORTED_CONTENT，而不是静默丢弃它。视觉模型会在目录中报告
其模态，但此处未实现投影。
* 思考。 llama.cpp 没有 effort 阶梯，因此读取
enable_thinking 的模板会通告 off | low | medium | high | max，其中 off
发送 enable_thinking: false，其他每个级别都发送 true；默认
为 off。没有该开关的模板完全不通告任何推理，harness
随后会拒绝显式的 effort，而不是静默忽略它。
在 Qwen3.8-27B 上实测：off 用 2 个 token 作答且无推理，high
在给出相同答案前花费 33 个推理 token。
* 不带 /v1 的基础 URL 会被补上一个，因此 http://host:8080 和
http://host:8080/v1 指向同一台服务器。如果其他东西已经占用了
你想要的端口（llama-server --port 18080），失败会是来自那个其他服务的
404 或挂起，而不是来自此插件。
* 目录缓存 5 秒，发现的上下文窗口缓存 60 秒；重启后的服务器
会在那之后的下一个请求中被识别。

验证

npm test                    # 44 tests, no network, no model
npm run mock                # a stand-in llama-server on 127.0.0.1:18080
npm run check:server -- http://desktop:8080/v1 off   # against a real server
npm run check:card -- "http://127.0.0.1:3080/?token="   # the GUI card

check:card 通过 CDP 驱动无头 Chrome，经过 Settings → Models：它
读取 llama.cpp 行显示的关闭状态行，打开卡片，读取
渲染出的字段，按下 Test connection，保存一个值，然后重置——并且
如果其中任何一项没有发生就会失败。它需要一个 Chrome/Chromium 二进制文件
（CHROME=/path/to/chrome 会覆盖自动发现；Playwright 安装的 Chromium
也可以正常工作）。

npm test 覆盖了纯 wire 辅助函数、分块翻译契约、
针对模拟 llama.cpp 端点的适配器（流式传输、工具调用、错误、
上下文发现、回退、推理能力、冷启动思考）、
插件自身的 apply() 针对 llm 和 settings 服务的桩 —
以及浏览器部分，在 jsdom 中通过页面所使用的同一个
__ModuleLoader__ 接缝针对桩远程对象进行渲染（在被请求前保持关闭、端点的点、
它揭示的字段，以及写入触发的重新探测）。
模拟服务器故意在目录中声明 8192，而在
/props 上声明 40960，因此解析出 40960 就证明上下文来自服务器。

test/verify-against-server.mjs 是另一半：它通过适配器驱动一个真实的
llama-server，并打印出它发现了什么，以及一轮对话实际产生了什么，按思考模式分别展示。