本地模型接入 umerkhalid204/dsh-plugin-local-llm

dsh-plugin-local-llm

让智能体跑在你自己机器上服务的模型上。插件把本地推理引擎注册成普通的 Harness 服务商路由，本地模型和托管模型一样，在编辑器的模型选择器里挑选；每个引擎都声明为可配置的第三方服务商。

支持的引擎

| 服务商 id | 默认端点 | 目录方言 |
| lmstudio | http://127.0.0.1:1234/v1 | LM Studio（/api/v0/models 补充信息：加载状态、量化、视觉） |
| ollama | http://127.0.0.1:11434/v1 | Ollama（/api/tags，外加每个模型的大小和量化） |
| strata | http://127.0.0.1:8080/v1 | Strata（按量化命名模型包） |
| lemonade | http://127.0.0.1:13305/v1 | Lemonade Server（标签：chat、vision、tool-calling、reasoning） |
| local-openai| http://127.0.0.1:8081/v1 | llama.cpp server、vLLM、LocalAI、TGI，以及任何兼容 OpenAI 的服务 —— 默认关闭，免得两个引擎抢同一个端口 |

这五个都讲兼容 OpenAI 的 /v1/chat/completions，区别只在模型列表怎么描述。Strata 的列表没有文档化的约定，所以用 providers.strata.models 声明你服务的模型包（名称和上下文窗口），服务端没给的部分由这份声明补上。

安装

从这个检出目录打包，然后安装打出来的包，不要直接装目录：

npm pack --pack-destination dist # -> dist/dsh-plugin-local-llm-<version>.tgz

然后在 Harness 里打开 Settings → Plugins → Install bundle，指向那个 .tgz。bundle 是叠加在 Loader 条目列表上的补丁层，所以如果你更想手动声明，就往 ~/.dsh/profiles/<profile>/cordis.patch.yml 加一行：

- insert:
- id: local-llm
name: 'dsh-plugin-local-llm'

条目 id local-llm 是它的配置、设置命名空间和 /local-llm/api 路由的键；name 是包说明符，版本取决于你装的是哪个。安装包才是受支持的布局 —— 只有这样插件才能解析自己的依赖，也才有设置表单（见下文）。

用法

local_models scan # 哪些引擎在线，能服务什么 local_models use provider=strata model=iq3_s local_models ping provider=lemonade model=Qwen3-0.6B-GGUF local_models settings # 设置界面能编辑这些引擎吗？

use 会写入配置档的默认模型，新会话就从那条路由起步。任何已注册的路由都接受 —— 包括别的适配器拥有的路由。

设置：要出现在 Models 页面需要什么

注册了还不够。只有三件事同时对上，服务商才会显示成一张卡片，而每一件都花了一轮调试才搞明白：

1. 目录条目。 这一行的配置里，providers.<id> 是某个引擎的唯一事实来源：endpoint、允许覆盖它的 baseURLEnv 名称、apiKey、enabled，以及手工声明的 models 目录。插件在可配置服务商目录里声明每个引擎，用 settingsNs: local-llm 和 settingsPath: ["providers", <id>] —— 这就是服务商卡片读写的位置。
2. 一个描述过的设置命名空间。 settings.describe() 会枚举活跃的插件条目，条件是它的 Config 是 schemastery 实例，所以 schema 必须能从已安装的包里导入 —— 见下面的安装布局。这一行还要调用 settings.configure({ auto: false })，因为 Models 页面会渲染自己的卡片；不这么做，旁边就会多出一个自动生成的重复页面。
3. 一个 meta.volatile 标记。 这个最容易漏：设置服务只根据最近 schema 节点带 meta.volatile 的字段来构建表单，一个都没标记时它根本不返回描述符，而 mutate 会拒绝任何不在 volatile 节点之下的写入路径。providers 被标记了，这也正是 endpoint 能重新指向而不用重新挂载这一行的原因 —— 所以 index.js 在扫描、发现或应答工具之前会重新读取实时配置。普通旋钮（probeTimeoutMs、scanTtlMs、maxTokens、默认 apiKey）故意不标记 volatile：它们在激活时生效，而表单会暗示并非如此。

schemastery v3 没有用于标记的工厂，但工厂返回的实例上，节点的 meta 是活对象，所以通过修改来挂上它。用工厂组合，而不是把裸节点树交给构造函数：settings 会对它递归进入的每个子节点调用 toJSON()，手写的树会让裸节点留在 dict 里，在 describe() 里抛错，连带整个设置文档一起挂掉。

两种安装布局行为不同：

- 作为包安装（tarball 或 registry）—— 副本位于 ~/.dsh/profiles/<profile>/node_modules/dsh-plugin-local-llm，它声明的依赖在这里能解析。这是你想要的布局：npm pack --pack-destination ..\pkg-out，然后安装 .tgz。
- 从源码检出链接（install_bundle 指向该目录）—— Node 从检出目录解析裸导入，那里没有任何 @deepseek-ai/* 包。插件仍会激活，因为 index.js 把 Harness 模块当作可选的，回退到 vendor/llm-contract.js，但 Config 保持 undefined，所以不会出现生成的字段，endpoint 编辑走配置档补丁（~/.dsh/profiles/<profile>/cordis.patch.yml）。
两种情形都在同一个配置档里出现过：链接安装时，各引擎已被认领、扫描、探测并列入服务商目录，而 Config 却报告 absent；打包安装时，同一批源解析出了依赖。

服务商 id 是争夺地带

服务商 id 是全局的，适配器注册表和可配置服务商目录都是全有或全无的注册。所以这个插件只在没有其他所有者占用某个 id 时才认领它，其余的如实报告：

served by local-llm: lmstudio, ollama, lemonade | left to another owner: strata@http://127.0.0.1:8080/v1

如果你自己声明了 strata（比如作为 pi-ai 服务商），那个所有者继续提供它——这正是让现有大脑继续工作的原因——而这个插件仍然会扫描、探测并选中那个端点。想把这条路由交给这个引擎，删掉另一处服务商声明，然后重新加载配置档。

开发说明

- node --check index.js；ESM，无构建步骤。
- node test/dry-run.mjs 运行 30 项离线检查，包括：providers 是标记为 volatile 的字典、引擎 api key 声明为 secret、暂存的配置以响应式单元的形式到达插件（这样读取环节一旦回归就会大声失败，而不是悄悄回退到默认值）。它先暂存一棵一次性目录树：运行时源复制到 test/shim/pkg，test/shims/ 里的替身放到 test/shim/node_modules/@deepseek-ai/{dsh-llm,schemastery}，这样副本的裸导入就在那里解析，包和工作区都不会多出 node_modules（test/shim/ 已加入 gitignore）。这一步暂存很关键：放在检出目录自身模块链里的替身会满足链接安装，并悄悄替换掉真正的 Harness 模块。
- test/shims/schemastery.js 镜像真实的 v3 接口——Schema 是可调用的类，工厂是小写静态方法且嵌套而非链式，节点的 meta 是可直接修改的活对象——所以调用不存在的构建器方法会在离线时失败，而不是等到激活时。
- 五个假服务器，每种目录方言一个，支撑整套测试，也可以手动运行：PORT=12340 ENGINE=lmstudio node test/fake-openai-server.mjs，其中 ENGINE=lmstudio|ollama|strata|lemonade|openai（LM Studio 夹具放在 12340，这样绝不会与 1234 上的真实 LM Studio 冲突，也不会误测到它）。它们还响应 /v1/chat/completions：提示词包含 TOOLTEST 时流式返回一个拆分的工具调用，包含 HALFTOKEN 时以 finish_reason length 结束。
- 宿主代码在插件关/开切换时热重载。package.json 和 cordis.patch.yml 的改动需要重新安装。
- 没有 Client 半边：没有 composer-dock 行，也没有 chip。本地模型只出现在模型选择器和设置里。

配置参考

- insert:
- id: local-llm
name: 'dsh-plugin-local-llm'
config:
probeTimeoutMs: 2500 # per listing request
scanTtlMs: 15000 # reuse a scan for this long
maxTokens: 0 # 0 = leave the cap to the server
apiKey: 'dsh-local' # default bearer
providers:
lemonade:
baseURL: 'http://192.168.1.20:13305/v1'
apiKey: 'set when that server exports LEMONADE_API_KEY'
local-openai:
enabled: true
baseURL: 'http://127.0.0.1:8080/v1'

MIT 协议；见 LICENSE。