wertyBSd/dsh-local-llm

dsh-local-llm

一个 DeepSeek Harness 插件，用于管理本地 GGUF 模型并通过 llama-server 提供服务——无需 Ollama。

dsh plugin --profile web add https://github.com/wertyBSd/dsh-local-llm

llama-server 运行时从插件 UI 下载，并且仅在用户点击启动按钮时启动。在服务器就绪之前发出的请求会返回明确的错误。

功能

- 从 Hugging Face 或直接 URL 下载 GGUF 模型。
- 搜索内置模型目录。
- 通过粘贴直接的 .gguf URL 添加任意模型。
- 显示已下载的模型和文件大小。
- 通过 SSE 将下载进度流式传输到 UI。
- 删除已下载的模型。
- 防止通过模型文件名进行路径遍历。
- 遵循 HTTP 重定向并清理未完成的下载。
- 对同一模型的并发下载进行去重。
- 为所选模型自动选择合适的上下文大小。
- 在发送请求之前检测 TinyLlama 是否无法容纳 Harness 提示词。
- 在侧边栏页脚提供 on/off 服务器指示器。

要求

- Node.js 18 或更高版本。
- 带有 llm 和 webServer 服务的 DeepSeek Harness。
- 用于文本生成的本地推理运行时。

@deepseek-ai/cordis 包提供 Cordis 运行时。llm 和 webServer 服务必须由 Harness 或其插件提供。

安装与构建

npm install
npm run build

宿主插件入口点是 dist/index.js。侧边栏客户端包是 dist/client.js。

包清单公开了 dsh.bundle 和 dsh.client。重启 Harness 后，插件会被加载到客户端图中。

dist/ 已提交到仓库（未被 gitignore），并且必须与 src/ 保持同步。当使用 pnpm dsh plugin --profile web add  安装 Harness 时，pnpm 的供应链策略会阻止对 git 托管的包运行 build/prepare 脚本，因此该插件以预构建形式发布。在推送更改之前，请始终运行 npm run build 并提交 dist/。

对于本地 Windows 安装，请运行：

Set-Location C:\git\dsh-local-llm
npm install
npm run build

Set-Location C:\git\deepseek-harness
pnpm dsh plugin --profile web add C:\git\dsh-local-llm
pnpm dsh --profile web --dump-config | Select-String dsh-local-llm

验证输出应包含 name: dsh-local-llm。完全停止任何正在运行的 Harness 进程，然后再次启动它：

pnpm dsh web

刷新浏览器页面是不够的，因为客户端插件图是在 web 配置文件启动时构建的。

开发命令：

npm run dev       # watch TypeScript compilation
npm run dev:ui    # watch UI build

配置

配置示例：

{
"model": "mistral-7b-instruct-v0.3-Q4_K_M.gguf",
"modelPath": "",
"runtimeUrl": "http://127.0.0.1:8080",
"contextSize": 8192,
"autoContextSize": true,
"port": 8080,
"downloadDir": "./models"
}

参数：
- model - 内置模型名称或 .gguf 文件的直接 URL。
- modelPath - 现有模型文件的路径。如果省略，配置的模型将自动下载。
- runtimeUrl - 兼容 OpenAI 的本地运行时（如 llama-server）的 URL。
- contextSize - 传递给 llama-server 的最小上下文大小，以 token 为单位。默认值为 8192。
- autoContextSize - 自动选择取决于模型的上下文大小。默认启用。
- port - 插件配置值；Harness Web 服务器拥有其 HTTP 端口。
- downloadDir - 模型目录。默认为 ./models。

内置模型名称包括：

- mistral-7b-instruct-v0.3-Q4_K_M.gguf；
- llama-3-8b-instruct-q4_K_M.gguf；
- deepseek-coder-6.7b-instruct-q4_K_M.gguf；
- qwen-2.5-7b-instruct-q4_K_M.gguf。

本地服务器

服务器不会自动下载或启动。打开 Local models，点击 Download and install server，等待安装完成，选择一个已下载的模型，然后点击 Start。该插件从官方 ggml-org/llama.cpp 发布版下载 llama-server，并将其绑定到 127.0.0.1。

服务器参数：

- serverDir - 二进制文件和日志目录。默认为 ./llama-server。
- serverUrl - 可选的直接服务器归档 URL。如果为空，则从最新的 GitHub 发布版中选择兼容的归档。
- serverBuild - 选择运行时构建：auto 优先使用 CUDA，并回退到 CPU；cuda 要求 CUDA 归档；cpu 强制使用非 CUDA 归档。默认为 auto。

模型管理器包含一个服务器构建选择器。在切换构建之前停止服务器，选择 CUDA、CPU 或 Automatic，然后点击 Install selected build。所选模式会持久化在浏览器中，已安装模式会记录在 serverDir 内的 server-build.json 中，因此该选择在 Harness 重启后仍然保留。从一个已安装构建切换到另一个构建会替换 serverDir 中的运行时文件。
- serverPort - llama-server 端口。默认为 8080。
- contextSize - 以 token 为单位的最小上下文大小。Harness 系统指令和工具可能需要更大的值；插件绝不会以低于 8192 token 启动托管服务器。
- autoContextSize - 启用时，常规模型至少使用 16384 token；TinyLlama 受其模型限制 2048 token 的约束。

当选择不同的模型时，服务器会自动重启，因此新模型的上下文大小会生效。活动上下文大小会包含在服务器状态中。服务器日志写入 llama-server/llama-server.log。

更改上下文设置或更新插件后，请停止并启动一次托管服务器，以便应用新的 --ctx-size 值。TinyLlama 报告可用上下文为 2048，因为这是其模型限制。适配器会估算请求大小，并在发送前拒绝过大的 Harness 提示。

打开模型管理器 UI

该插件向 Harness 侧边栏添加了两个入口点：
- 在 New session 之后立即放置一个 Local models 按钮。这需要本地 Harness shell 槽位 sidebar.after-new-session，而该槽位并非在每个 Harness 构建中都存在。
- 在侧边栏页脚中放置一个开/关指示器（sidebar.footer.action），该指示器始终可用。点击指示器本身即可打开相同的设置对话框。

如果你的构建中未出现 New session 按钮变体，请改为点击页脚指示器——两者都会打开相同的 Local models 对话框，其中包含模型下载、服务器控制和语言选择。

本地化

模型管理器支持英语、俄语、中文、法语、西班牙语、意大利语、波兰语、德语、印地语和日语。默认使用英语。所选语言存储在浏览器中，并应用于模型窗口、错误、服务器控制和 local models 指示器。

API

- GET /api/local-llm/models - 列出已下载的模型。
- POST /api/local-llm/download，请求体为 { "model": "model-file.gguf" } - 下载模型。
- GET /api/local-llm/progress?model=... - 以 SSE 形式接收下载进度。
- POST /api/local-llm/delete，请求体为 { "model": "model-file.gguf" } - 删除模型。
- GET /api/local-llm/server/status - 获取服务器状态。
- POST /api/local-llm/server/install - 下载并解压服务器。
- POST /api/local-llm/server/start，请求体为 { "model": "model-file.gguf" } - 使用模型启动服务器。
- POST /api/local-llm/server/stop - 停止服务器。

Harness 集成

该插件在可配置的提供程序目录中注册 local-llm，并通过 registerAdapter(['local-llm'], ...) 激活它。重启 web profile 后，该提供程序将出现在 Harness 模型选择器中。

适配器向 ${runtimeUrl}/v1/chat/completions 发送流式请求。如果 runtimeUrl 为空，则使用插件在 http://127.0.0.1:8080 启动的服务器。Harness 工具会被转换为 OpenAI function-tool 格式，适配器在发送请求前会等待 /health。

可选的、紧跟在 New session 之后的侧边栏位置需要本地 DeepSeek Harness shell 槽位 sidebar.after-new-session。如果没有该本地 shell 补丁，该插件仍与标准页脚操作槽位兼容。

已知限制

- 内置目录使用固定的 Hugging Face URL。
- 下载的文件不会根据校验和进行验证。
- SSE 行为取决于 DeepSeek Harness web 服务器的实现。
- 在服务器安装、启动并准备就绪之前，文本生成不可用。

许可证

MIT