dsh-koboldcpp-hands

dsh plugin --profile web add dsh-koboldcpp-hands

<div align="center">

KoboldCpp for DeepSeek Harness

dsh-koboldcpp-hands — 给 DeepSeek Harness 的智能体一双本地的手。





[English](README.md) · [中文](README.zh-CN.md)

</div>

一个为 DeepSeek Harness 编写的第三方工具插件：让在线大模型（你的主对话模型）把重复、耗 token 的简单劳动交给本机 KoboldCpp（llama.cpp）服务器完成——包括纯文本工作和视觉工作（识图 / OCR / 图片对比）。

主模型保持在你部署的位置不变。当它认为某个任务更适合本地完成时，它会调用：

• koboldcpp_run — 在本地文本模型上运行一条提示词（批量改写、名字翻译、字符串处理、短文本摘要、结构化提取）。
• koboldcpp_vision — 把图片交给本地多模态模型（OCR、图像分析、多图对比），使用结构化报告模板。

插件负责本地服务器生命周期：用你的 KoboldCpp 可执行文件和你的 .kcpps 启动配置（后端、模型、mmproj、端口都在里面）按需拉起，等待模型加载完成，并按 stopBehavior（exit / idle / never）停止。你自己启动的 KoboldCpp 会被复用，绝不会被杀死。

---

做了哪些事（What it does）

• 两个模型可见工具，按官方 dsh-tools 契约注册（defineTool、canonical JSON 返回值、纯 render/presenter、exec.signal 转发）。
• 按需的服务器生命周期：首次工具调用才拉起 exePath（带你的 kcppsPath + --port），轮询 /v1/models 直到健康；服务器崩溃后自动自愈；按 stopBehavior 停止。Windows 上做进程树终止（taskkill /T），因为 KoboldCpp 会自我派生子进程。
• 文本 + 视觉 wire 支持：非流式 OpenAI 兼容 chat-completions；图片按标准多模态 content 数组发送。
• 三种图片来源（视觉工具）：本地文件路径、data:/http(s): URL、或当前会话中已附带的图片（经 harness attachment 服务读取）。注意：会话附件来源要求主模型声明支持图片输入，纯文本主模型下只有 image_paths / image_urls 可用（见「当前版本限制」一节）。
• 结构化视觉提示词：结构化报告契约 —— analyze（8 段报告）、ocr（逐字提取）、compare（多图、5 段报告），并附 fidelity 规则（逐字转发、不得编造、保留不确定性）。
• 热配置：harness 用户设置文档中的 llm-koboldcpp: 节可无需重启覆盖插件配置；KOBOOLDCPP_EXE / KOBOOLDCPP_KCPPS 环境变量兜底。
• 安全的归属关系：外部 KoboldCpp 进程只复用、绝不触碰；只有插件自己拉起的服务器才会被停止。

没做哪些事（What it does NOT do）

• 不替换 harness 的模型提供方（provider）——在线模型始终是主模型，本地模型只能通过两个工具触达。
• 不替你决定 GPU 后端、模型路径或模板。KoboldCpp 的一切启动设置都在你的 .kcpps 文件里（usecuda/usevulkan/usecpu、model_param、mmproj、端口）。不探测、不自动加参数。
• 不修改任何 DeepSeek Harness 文件——纯插件，即插即卸。
• 不捆绑/托管 GGUF 或 mmproj 模型文件——模型自备。
• 不用流式、不用 API key（本地服务，无凭据参与）。
• 不在 harness 进程内常驻服务——只在需要时派生独立 KoboldCpp 进程。

环境要求

项 · 要求

Node.js · ≥ 20

DeepSeek Harness · 已安装（npx @deepseek-ai/dsh web 或源码检出）

KoboldCpp 可执行文件 · koboldcpp.exe（NVIDIA/CUDA）或 koboldcpp-nocuda.exe（AMD/Vulkan），任一提供 /v1/chat/completions 的版本

GGUF 模型 · 自备；视觉场景另需多模态 GGUF 及其 mmproj（在 kcpps 的 "mmproj" 字段配置）

安装方式

在 harness 项目目录（组合文件 cordis.yml / cordis.patch.yml 所在处）：

npm install dsh-koboldcpp-hands

源码检出方式，可把插件条目直接指向本仓库的克隆：

- insert:
    - id: koboldcpp-tool
      name: '../dsh-koboldcpp-hands'

使用方法（配置）

启动设置归你所有。npm 安装后插件行已由 bundle 自动插入，请在 profile 的 cordis.patch.yml 中用不带 insert 的 id 覆盖形式修改（同 id 再 insert 会导致 loader 崩溃 duplicate loader entry id）：

- id: koboldcpp-tool
  name: 'dsh-koboldcpp-hands'
  config:
    baseURL: 'http://127.0.0.1:5001'                     # 必须与 kcpps 中的端口一致
    exePath: 'C:\path\to\koboldcpp-nocuda.exe'           # 你的二进制（CUDA 或 Vulkan 版）
    kcppsPath: 'C:\path\to\your-model.kcpps'             # 你的启动配置：后端 + 模型 + mmproj + 端口
    autoStart: true
    stopBehavior: idle
    idleStopMinutes: 30

（git/本地路径的普通依赖安装方式则用 - insert: 加同一行即可。）

实际启动的命令就是：

koboldcpp-nocuda.exe "C:\path\to\your-model.kcpps" --port 5001

全部 17 个配置字段及默认值：见 [docs/api.md](docs/api.md) §1.2。

工具用法

koboldcpp_run — 文本

参数 · 类型 · 必填 · 说明

prompt · string · 是 · 发给本地模型的指令/文本（user 消息）

system · string · 否 · 可选系统指令

temperature · number · 否 · 采样温度（0–2）

max_tokens · integer · 否 · 输出上限（默认 maxTokens）

stop · string[] · 否 · 停止序列

返回 { text, reasoning?, model, usage, elapsedMs }。

koboldcpp_vision — 图片 / OCR

参数 · 类型 · 必填 · 说明

mode · analyze/ocr/compare · 否 · 内置提示词模板（默认 analyze）

prompt · string · 否 · 自定义指令（覆盖模板）

image_paths · string[] · 否 · 本地图片（png/jpg/jpeg/webp/gif/bmp，单张 ≤20 MB）

image_urls · string[] · 否 · data:image/... 或 http(s):// URL

temperature · number · 否 · 采样温度（OCR 建议 ~0.2）

max_tokens · integer · 否 · 输出上限

stop · string[] · 否 · 停止序列

图片来源按序解析：显式 image_paths + image_urls → 会话中最近的图片 → 清晰报错。compare 一次请求发送 2–4 张图做联合推理。

返回 { text, reasoning?, model, images, usage, elapsedMs }。

视觉需要多模态 GGUF 及其 mmproj 投影器（配置在 kcpps 中）。没有 mmproj 时请求正常完成，但模型看不到图片。

当前版本限制：纯文本主模型只能通过「在线链接」和「本地路径」送图

当前版本（插件 0.1.0，harness 0.1.0-rc.6）下，如果主模型是纯文本模型，koboldcpp_vision 只能通过两个显式渠道收到图片：image_paths（本地文件路径）和 image_urls（在线 / data: 链接）。 会话附件渠道在这种组合下不可用——这是 harness 的硬限制，不是本插件的限制：

1. 在纯文本模型下粘贴/拖入图片，dsh 会在消息进入会话之前直接拒绝整条消息（attachment-error / MODEL_DOES_NOT_SUPPORT_IMAGES，界面提示"当前模型不支持图片，请切换支持图片的模型"）。检查点在 dsh-host-apiproxy：所选模型在 pi-ai 模型目录中声明的输入模态必须包含 image；目录里声明 input: ["text"] 的模型（如 opencode-go 路由下的 deepseek-v4-flash / deepseek-v4-pro）会被拒绝。

2. 即使图片部分能进入消息，dsh-llm-pi-ai 的流式适配器也会对同样的纯文本模型拒绝图片内容（UNSUPPORTED_CONTENT）；子代理续写会话则在浏览器端直接屏蔽图片。

3. 由于消息在持久化为附件之前就被拒绝，"读取会话最近附带图片"的来源无图可读——与 OpenCode / Pi 不同，dsh 目前不会把粘贴的图片变成临时文件路径交给纯文本模型。

当前可用的绕行方式：

• 让模型调用 koboldcpp_vision 时传 image_paths: ["C:\\...\\photo.png"]——任何 harness 进程可读的路径都行。
• 或传在线链接 image_urls: ["https://example.com/photo.png"]（也支持 data: URL）。
• 或把主模型换成目录里声明支持图片输入的模型（如 opencode-go 下的 minimax-m3、qwen3.7-plus、kimi-k2.6、kimi-k3、grok-4.5），会话附件渠道即可自动生效。

上游已跟踪：deepseek-harness 讨论 #1378（建议：纯文本模型也允许图片附件，并以链接/路径形式交给工具处理）。harness 放宽限制后我们会更新本节。

路线（Roadmap）

可以走的方向：

• 更多视觉模式与提示词

…(truncated)