工程文档（Engineering）

August 14, 2026 · View on GitHub

dsh-koboldcpp —— DeepSeek Harness 第三方工具插件。在线大模型通过 koboldcpp_run / koboldcpp_vision 工具把重复、耗 token 的文本与视觉劳动交给本机 KoboldCpp（llama.cpp）完成。

1. 项目定位

类型：DeepSeek Harness 工具插件（tool plugin），遵循 docs/cookbook/adding-a-tool.md 契约。
不做什么：不替换 harness 的模型提供方（provider）；不改写任何 deepseek-harness 文件；不自建监听服务。
做什么：
1. 在线模型（主模型）按需调用 koboldcpp_run（文本）与 koboldcpp_vision（多模态/OCR）。
2. 首次调用时自动拉起本机 KoboldCpp（exePath + kcppsPath --port），等待模型加载。
3. 按 stopBehavior（exit/idle/never）管理服务器生命周期；外部已运行的 KoboldCpp 只复用、绝不终止。

2. 环境要求

项	要求
Node.js	≥ 20（开发/测试用 24.x）
DeepSeek Harness	`npx @deepseek-ai/dsh web` 或源码检出（npm 包版本 ≥ 0.1.0-rc.2）
KoboldCpp	官方 Releases 的 `koboldcpp[-nocuda].exe`（NVIDIA 用含 CUDA 的版本，AMD 用 nocuda/Vulkan）
模型	GGUF 文件；视觉场景另需 `mmproj` 投影器（在 kcpps 中配置）

3. 目录结构

DSHKOBOLDCPP/
├─ package.json            # npm 包定义；peerDependencies 只含运行时依赖
├─ tsconfig.json           # 类型检查（allowImportingTsExtensions + rewriteRelativeImportExtensions）
├─ tsconfig.build.json     # 构建（src → lib/）
├─ vitest.config.ts        # 测试配置（node 环境）
├─ README.md               # 用户安装/配置/使用（对外；精简版 API 见 docs/api.md）
├─ docs/                   # 本文档集（engineering / glossary / api / solutions）
├─ src/
│  ├─ index.ts             # 插件入口：Config、resolveOptions、apply、两个工具、settings 段
│  ├─ launch.ts            # KoboldCppServer 进程生命周期
│  ├─ koboldcpp.ts         # 非流式 chat-completions 客户端（文本+多模态）与错误映射
│  ├─ images.ts            # 图像准备：文件/URL/会话附件 → data URL
│  └─ prompts.ts           # 视觉报告模板与 fidelity 规则
└─ tests/                  # 各模块单测 + integration + loader + real-driver（见 §7）

4. 常用命令

npm install        # 安装依赖（含 harness 包 devDependencies）
npm run typecheck  # tsc -p tsconfig.json --noEmit
npm test           # vitest run（45 个测试）
npm run build      # tsc -p tsconfig.build.json → lib/

发布前：npm run prepublishOnly（typecheck + test + build 依次执行）。

5. 插件契约要点（DeepSeek Harness 规范）

契约	实现
`name`	`'koboldcpp-tool'`（kebab-case）
`inject`	`['tools']`（依赖 `ctx.tools`）
`Config`	schemastery schema，与 `llm-koboldcpp:` settings 段同形（详见 docs/api.md）
`apply(ctx, config)`	注册工具、设置段、进程管理；配置变更（settings）热重注册工具
工具注册	`ctx.tools.register(defineTool({...}))`；fiber 卸载自动注销（幂等）
卸载	`ctx.effect(() => async () => { await server.dispose() })`（async disposer 被 fiber 等待）
并发	不声明 `isConcurrencySafe` → 注册表默认 exclusive（串行），适配 KoboldCpp 单序列 KV cache
错误	工具抛错 → `isError` + 可读消息；客户端抛 `LlmError`（稳定 code）

6. 源码约定

相对导入使用 .ts 扩展名（import './koboldcpp.ts'），构建时由 rewriteRelativeImportExtensions 重写为 .js，保证 Node type-stripping 可直接运行源码（Loader 场景）。
禁止 parameter properties（constructor(private x)）：Node strip-only 模式不支持；用显式字段声明。
工具执行必须 forward exec.signal（与 AbortSignal.timeout 合并）。
模型可见描述为英文；代码注释为中文或英文均可，术语遵循 docs/glossary.md。
新增/修改行为必须同步更新 docs/api.md 与 tests。

7. 测试分层（对应 harness testing.md）

层	文件	覆盖
单元	`koboldcpp.spec.ts` / `prompts.spec.ts`	客户端、模板、图像助手
工具	`tool.spec.ts`	schema、执行、canonical value、卸载、失败隔离
集成	`integration.spec.ts`	插件 + ToolRuntime 组合，自动拉起 fake 服务器与停服
REAL-composition	`loader.spec.ts`	`dsh-app-boot` → Loader → `cordis.yml`（规范硬性要求）
真实行为	`real-driver.mjs`（手动）	真实 koboldcpp 三场景：autostart / reuse / notrunning —— 运行方法与判据见 docs/solutions.md §8

8. 与 harness 集成（安装/配置/卸载）

安装：harness 项目内 npm install dsh-koboldcpp；源码方式可用 name: '../DSHKOBOLDCPP'（包根即 Cordis 插件模块）。

配置：profile 的 cordis.patch.yml 增加一行 insert（详见 README「Configure」）。

卸载：删除该条目即可。运行中卸载（HMR/设置变更）会：注销两个工具、按 stopBehavior 停掉插件自启的服务器、释放 settings 段。外部服务器与 harness 其他组件不受影响（有测试证明）。

9. 已知限制与对策

见 docs/solutions.md §10（本处不再重复）。