Rapid-MLX 服务商 RafaelFerrara60340/rapid-mlx-dsh-provider

@raullenchai/dsh-provider

一个原生 Rapid-MLX 服务商，用于 DeepSeek Harness——这样 dsh 就能从服务器获取模型信息，而不是从你在 settings.yaml 里手写的那些内容。

状态：已发布到 npm，包名 @raullenchai/dsh-provider。
已验证 里的端到端 dsh 运行是在 M3 Ultra 上针对
dsh 0.1.0-rc.7 完成的；dsh 0.1.0-rc.8 在 API 上兼容——LlmAdapter
契约逐字节一致，改动全是新增——适配器也已在协议和单元测试层面针对 rc.8 重新验证。
DSH 仍是快速迭代的开发者预览版，所以请把它当作跟踪一个移动目标，而不是冻结的兼容承诺。

它能为你做什么

DSH 已经能通过通用的 openai-completions 服务商连接本地 Rapid-MLX 服务器。这条路能用——但它对你的模型一无所知，只知道你手写的内容：

what the generic route makes you maintain, by hand, per model
llm-pi-ai:
providers:
rapid-mlx:
baseURL: http://localhost:8000/v1
defaultContextWindow: 262144 # you looked this up. is it still right?
models:
- id: qwen3.6-35b-8bit
contextWindow: 262144
reasoningEfforts: {off: none, low: low, medium: medium, high: high}

Rapid-MLX 的 /v1/models 已经发布了所有这些信息，甚至更多。这个适配器会读取它，所以：

1. 不用手写，切换模型时也不用重写。 换掉 rapid-mlx serve 正在跑的东西，dsh 就会跟着变。不用重跑安装，没有过期的数字。

2. 推理控制说的是实话。 Rapid-MLX 会报告模型是否真的有推理解析器。不能推理的模型不再显示一个毫无作用的 off/low/medium/high 选择器。

3. 压缩按这台 Mac 实际能容纳的容量计时，而不是一个漂移的数字。 这一条会悄悄让你付出代价。
dsh-compaction-basic 向服务商询问路由的容量，并在 thresholdRatio × capacity（默认 0.8）处压缩。服务商优先采用服务器的 max_model_len——Rapid-MLX 按内存拟合的上限（统一内存里能装下的：权重 + KV 缓存），采用 vLLM/SGLang 标准字段——而不是原生的 context_window；如果服务器较旧、不报告该字段，则回退到 context_window。所以压缩按机器实际能容纳的量计时，而不是模型宣称的窗口（可能没地方放），也不是从别的模型抄来的手写数字。

安装

需要 Node ≥ 22.15（dsh 导入了 Node 的 Zstd 流 API 却没有声明依赖）以及一个正在运行的 Rapid-MLX 服务器。

From npm:
dsh plugin --profile web add @raullenchai/dsh-provider

…或直接从源码安装 —— 这个包是纯 JS，没有构建步骤：
dsh plugin --profile web add github:raullenchai/rapid-mlx-dsh-provider

export RAPID_MLX_BASE_URL=http://localhost:8000/v1 # 可选；这是默认值
dsh web

然后让智能体指向这条路由：

$DSH_HOME/settings.yaml
agent-default-model:
provider: rapid-mlx
model: qwen3.6-35b-8bit

已验证：这条命令能安装，并作为配置档层激活，对应 dsh 0.1.0-rc.7。想改本地代码，见本地开发。

模型管理（v0.2.0）

除了提供路由，插件还注册五个工具和一条 /rapid-mlx 命令，让智能体不用离开会话就能查看和管理模型。划分依据是每个事实实际归哪个界面管：服务中的模型信息来自结构化 HTTP /v1/models；下载缓存和 pull/remove 只有命令行才有，所以只有这些——也仅限于这些——通过 harness 的子进程接口调用 rapid-mlx。

| 工具 | 来源 | 作用 |
| rapid_mlx_serving | HTTP /v1/models | 当前正在服务的模型，去重后列出，附带上下文窗口、推理/工具解析器、MoE/混合架构和模态。 |
| rapid_mlx_cached | rapid-mlx models --cached | 已下载的模型及其磁盘占用。 |
| rapid_mlx_pull | rapid-mlx pull <name> | 下载模型（别名或 HF 仓库 id）。可取消；没有固定时限。 |
| rapid_mlx_remove | rapid-mlx rm -y <name> | 删除缓存模型，释放磁盘。 |
| rapid_mlx_health | HTTP + rapid-mlx --version | API 是否在线？命令行是否可达？作为两个独立事实报告。 |

/rapid-mlx 打印一次性概览：健康状况、正在服务的模型及其信息、缓存总磁盘占用。

命令行从 cliCommand 配置解析（默认是 PATH 上的 rapid-mlx，或 $RAPID_MLX_CLI）；如果二进制不在 harness 的 PATH 上，就设成绝对路径。rapid_mlx_pull/rapid_mlx_remove 是仅有的会改动磁盘的工具，它们以非交互方式运行（rm 强制加 -y，因为子进程接口忽略 stdin）。

已验证

在 M3 Ultra 上对应 dsh 0.1.0-rc.7：

- 能安装，并作为配置档层激活（没有「declares no dsh.bundle」警告；条目会出现在 dsh --profile headless --dump-config 里）。
- 用 ctx.llm 注册 rapid-mlx 路由，能处理真实查询。
- 纯聊天、单次工具调用，以及作为 Rapid-MLX 发布门槛的多步修 bug 任务——最后一项修好了 bug，目标仓库自带的测试也通过了，独立验证，在 qwen3.6-35b-8bit 上耗时 36 秒。

尚未完成

说清楚，因为适配器的意义就是用服务器说的东西，而其中一部分目前只读不用：

- recommended_sampling —— 应该按模型自动应用。
- tool_call_parser —— 应该让 dsh 在模型无法发出 tool_calls 时快速失败，而不是空转。
- is_hybrid / is_moe / capabilities — 已读取，尚未据此采取动作。
- 感知内存的容量。 目前 resolveModel() 报告的是模型对外宣称的上下文窗口。在 Mac 上，真正的上限是统一内存，改为报告这个数字是剩下最大的一项收益 —— 但前提是 Rapid-MLX 先暴露一个可用的容量数值。
- 图片不会经由 stream() 传递 —— 但现在会按 cookbook 的要求拒绝，抛出 LlmError(..., 'UNSUPPORTED')，而不是悄悄丢弃。文本、推理和工具调用都会传递。
- 路由注册为 rapid-mlx。如果你的 settings.yaml 在 llm-pi-ai 下也声明了 rapid-mlx 服务商，两者会争抢同一个路由名（registerAdapter 保证服务商独占）。二选一，或者给我们这个改个名。

与官方适配器契约的一致性

基于 docs/cookbook/adding-an-llm-adapter.md 及其「协议义务」一节构建。每一项都有对应测试：

| 义务 | 如何满足 |
| usage 在 finish 之前，finish 之后不再有任何内容 | usage 先缓冲，到流结束时统一刷出，因此末尾只含 usage 的 chunk 无法打乱顺序 |
| 工具调用的 arguments 全程是原始 JSON 字符串 | 分片以 argumentsDelta 流式下发，重新拼装时不解析 |
| 块索引按首次出现顺序，每个块复用同一索引 | 在一个先推理后文本的响应上验证过 |
| 错误只走两条被认可的通路 | 传输/协议失败抛出带稳定错误码的 LlmError；不会有任何情况让流悄悄结束 |
| 遵守 options.signal | 传给 fetch 和 SSE 读取器；AbortError 原样重新抛出，不重新归类 |
| 服务商无法满足的字段抛出 UNSUPPORTED | 图片内容直接拒绝，而不是被悄悄裁掉 |
| 配置是带环境变量回退的 schemastery schema | export const Config，由 cordis.patch.yml 经 !!js process.env.RAPID_MLX_BASE_URL 注入 |

不发出 finish.replayState：Rapid-MLX 在后续调用中不需要原生响应 id 或签名，因此没有可无损投影的内容。

改这份代码前值得知道的三件事

每一条都花过实打实的调试时间：

1. package.json 里的 dsh.bundle 才是让它成为插件的东西。 没有它，这个包只会作为惰性依赖安装，dsh 仅警告。它也是让包被追加到配置档 dsh.profile.bundles 的依据。一旦缺失，CI 会失败。
2. LlmReasoningEffortInfo.name 是必填项。 只返回 {id} 会让整个模型报 INVALID_MODEL_REASONING 失败 —— 这个错误只点名模型，不点名缺失的字段。
3. DSH 没有 tool 角色。 Message.role 只有 system|user|assistant；工具结果是一条 user 角色消息，其 source.kind === 'tool' 携带 callId，内容里放一个 ToolResultBlock。把这些压平成普通用户文本，模型就会永远重复发起同一个调用 ——症状是返回空答案、退出码非零，而且 stderr 上什么都没有。

本地开发

pnpm 会把本地路径链接到配置档目录树之外，于是 Node 向上查找父目录时永远到不了 $DSH_HOME/profiles/node_modules，peer 依赖也就解析失败。把它们软链进来——仅限开发，node_modules 已加入 gitignore，也不在发布用的 files 里：

mkdir -p node_modules/@deepseek-ai
ln -sfn <dsh-install>/node_modules/@deepseek-ai/dsh-llm node_modules/@deepseek-ai/dsh-llm
ln -sfn <dsh-install>/node_modules/@deepseek-ai/cordis node_modules/@deepseek-ai/cordis

export DSH_HOME=/tmp/dsh-dev # never your real ~/.dsh
dsh plugin --profile headless add "$PWD"
export RAPID_MLX_BASE_URL=http://127.0.0.1:8000/v1
dsh --profile headless "say hello"

真正跑一次 npm install 就不需要这些：包会落在配置档目录树里面，扁平回退在那里能正常解析裸名。

测试智能体行为时，用 8-bit 的强模型。这里有个多步任务在 qwen3.5-9b-4bit 上失败，在 qwen3.6-35b-8bit 上通过——4-bit 会把「模型弱」和「集成坏了」混在一起。

引擎侧会守住这些字段

这个包住在自己的仓库里，意味着 Rapid-MLX 那边改个名字，就会悄悄弄坏它——那边没有任何代码 import 它，这边的 CI 也不在那边跑。所以字段钉在拥有它们的一侧，由 Rapid-MLX 里的 tests/test_model_card_client_contract.py 负责，那个测试文件明确写了这个包就是它存在的理由。它钉住的是传输形状：字段名、可空性，以及 ModelInfo 不设 exclude_none 这一点——正因如此，"reasoning_parser": null 才能和完全省略该键的旧服务器区分开。

如果你在这里开始读 /v1/models 的新字段，那边也要加上。 否则这道防线会悄悄不再覆盖这个包实际用到的东西。

许可证

Apache-2.0，与 Rapid-MLX 一致。