本地模型桥接 orfeomorello/dsh-localforge

LocalForge for DeepSeek Harness

高性能、MIT 协议的适配器，把 DeepSeek Harness（dsh）接到本地 LLM 服务器上——主要是 LM Studio，也支持其他任何兼容 OpenAI 或兼容 Anthropic 的端点（Ollama、vLLM、llama.cpp 的 HTTP server、text-generation-inference 等）。

为什么选 LocalForge？

dsh 上已经有另外三个 LM Studio 插件（我们认真读过全部三个——见灵感来源和对比）。LocalForge 补上了其他适配器都缺的那些东西：

- 实时发现缓存 —— /v1/models + 原生 /api/v0/models 兜底，带 TTL 和显式失效。其他插件每次 resolveModel 都要重新探测服务器。
- 自动加载 —— 请求的模型没驻留在 LM Studio 时，让服务器加载它（POST /api/v0/models/{id}/load），然后轮询直到就绪。
- 按模型限流 —— 量化模型上并行流会把 LM Studio 打满；LocalForge 按模型 id 串行化。
- 模型回退链 —— fallback: [primary, secondary]。主模型返回可恢复错误时，自动尝试下一个。
- 推理预算 —— 限制模型在给出最终答案前能做多少内部「思考」。
- 采样预设 —— code、chat、creative、precise，给出合理默认值，你可以按请求覆盖。
- Token 预检 —— 会撑爆上下文窗口的请求直接拒绝，不用先付一次往返的代价。
- Prometheus 指标 —— /metrics 暴露 TTFT、TPS、队列深度、错误率、缓存命中。
- 可选健康检查 —— 开启后定期探测并自动重连；/metrics 的 up gauge 反映状态。
- 兼容 Anthropic 的适配器 —— 第二条服务商路由，走 /v1/messages，适合 Claude 风格的提示词和工具调用。
- 结构化日志，凭据脱敏 —— 每行日志都能直接发到 Loki / ELK，不用再清洗。
- 严格 TypeScript —— strict + noUncheckedIndexedAccess，测试全覆盖，GitHub Actions CI。

安装

前置条件

- DeepSeek Harness（dsh），并启用 web 配置档。
- 本地 LLM 服务器。测试最多的是 LM Studio 0.4.8+，打开 Developer → Start Server（默认端口 1234）；任何兼容 OpenAI 或兼容 Anthropic 的服务器都能用。
- Node.js ≥ 22.19 和 pnpm ≥ 9。

来自 DSH 插件页面

1. 打开 Settings → Plugins → Repository source → Add。
2. 输入 github:orfeomorello/dsh-localforge#main 并安装。
3. 在插件列表里启用 LocalForge；如果弹出提示，重启 dsh web。

仓库安装器会立即挂载社区插件。这个仓库还包含编译好的 lib/ 运行时，因为仓库插件管理器会直接导入那个入口；GitHub 的安装器不会为它构建 TypeScript 源码。如果想改用 bundle 方式从终端安装，用：

dsh plugin --profile web add github:orfeomorello/dsh-localforge#main
dsh web --dump-config # verify the dsh-localforge bundle layer
Restart dsh web after installing the bundle

页面顶部的模型选择器里，现在会看到 LocalForge 作为一个服务商；挑一个 LM Studio 已加载的模型即可。如果 UI 仍然报 failed to import，请抓取完整的浏览器控制台错误，或者 dsh web 终端诊断信息：UI 上那句简短提示不会暴露底层的模块解析错误。

快速开始

~/.dsh/settings.yaml 里最小的一段配置：

llm-localforge:
defaultConnection:
baseURL: http://localhost:1234/v1
models:
- id: qwen/qwen3-8b
preset: code
fallback:
- qwen/qwen3-4b
- llama-3.1-8b

就这样。把 dsh 指向任意会话，选择「LocalForge」作为服务商，流量就会流向 LM Studio。你的 DeepSeek API 余额分文不动。

配置

完整参考见 docs/CONFIGURATION.md（每个小节、每个字段、每个默认值）。

架构

设计说明见 docs/ARCHITECTURE.md —— 逐请求解析器的小技巧、双端点发现、SSE 解析、Prometheus 指标集，以及测试策略。

灵感来源

LocalForge 是净室重写。我们读了三个现有插件来学习套路，然后用自己写的代码、自己的协议从零实现。灵感来源是：

- Viktirr/dsh-llm-lmstudio ——最干净的 TypeScript 树内适配器，逐请求解析器模式的出处。
- jtc268/deepseek-harness-lmstudio —— Qwen 专用工具调用健壮性的灵感来源。
- starlightzfy/dsh-plugin-lmstudio ——插件 bundle 发现体验的灵感来源。

没有复制任何代码。完整的功能对照矩阵见 docs/COMPARISON.md。

协议

MIT © 2026 The LocalForge authors。