raullenchai/rapid-mlx-dsh-provider

@raullenchai/dsh-provider

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

CI

状态：已发布到 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 服务器
通信。那条路径是可行的 —— 但它对你的模型一无所知，只知道你手写的内容：

通用路径迫使你为每个模型手动维护的内容
llm-pi-ai:
providers:
rapid-mlx:
baseURL: http://localhost:8000/v1
defaultContextWindow: 262144      # 你查出来的。它现在还对吗？
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. 压缩（compaction）的时机依据的是实际适配这台 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 服务器。

从 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

然后将 agent 指向该路由：

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

已验证：该命令在 dsh 0.1.0-rc.7 上作为 profile 层安装并激活。若想在本地对其进行修改，请参阅
本地开发。

模型管理（v0.2.0）

除了 provider 路由之外，该插件还注册了五个工具和一个 /rapid-mlx
命令，使 agent 无需离开会话即可查看和管理模型。
这种划分遵循每个事实实际归属于哪个界面：served-model 事实
来自结构化的 HTTP /v1/models；下载缓存和 pull/remove
仅限 CLI，因此——且仅限这些——通过
harness 子进程接缝调用 rapid-mlx。

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

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

CLI 从 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：

- 安装并作为 profile 层激活（没有 "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 provider，两者会争夺同一个路由名（registerAdapter 拥有 provider 独占权）。请只使用其中一个，或重命名我们的。

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

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

| 义务 | 如何满足 |
|---|---|
| usage 在 finish 之前，finish 之后无任何内容 | usage 被缓冲并在流结束时刷新，因此末尾仅含 usage 的 chunk 无法使其乱序 |
| 工具调用的 arguments 端到端都是原始 JSON 字符串 | 片段以 argumentsDelta 流式传输，并在未解析的情况下重新组装 |
| 块索引按首次出现顺序排列，每个块复用 | 已在一个先推理后文本的响应中验证 |
| 错误只走恰好两条被认可路径 | 传输/协议失败会抛出带有稳定代码的 LlmError；没有任何情况会悄悄结束流 |
| 遵守 options.signal | 传递给 fetch 和 SSE reader；AbortError 会原样重新抛出，而不会被重新分类 |
| provider 无法满足的字段会抛出 UNSUPPORTED | 图像内容会被拒绝，而不是被收窄掉 |
| 配置是带环境变量回退的 schemastery schema | export const Config，通过 !!js process.env.RAPID_MLX_BASE_URL 从 cordis.patch.yml 注入 |

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

在编辑此内容之前值得了解的三件事

每一件都耗费了真实的调试时间：

1. package.json 中的 dsh.bundle 是使其成为插件的原因。 没有它，
该包会作为惰性依赖安装，而 dsh 只会警告。它也是将其追加到
profile 的 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 链接的是 profile 树之外的本地路径，因此 Node 的父目录遍历永远无法到达 $DSH_HOME/profiles/node_modules，对等依赖也就无法解析。把它们软链接进来——仅限开发环境，node_modules 已被 gitignore 忽略，并且从发布的 files 中排除：

mkdir -p node_modules/@deepseek-ai
ln -sfn /node_modules/@deepseek-ai/dsh-llm node_modules/@deepseek-ai/dsh-llm
ln -sfn /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 完全不需要这些：包会落在 profile 树内部，扁平回退机制会在那里正常解析裸名称。

在测试 agent 行为时，请使用强大的 8-bit 模型。这里的一个多步骤任务在 qwen3.5-9b-4bit 上失败，而在 qwen3.6-35b-8bit 上通过——4-bit 会把“模型弱”和“集成损坏”混为一谈。

引擎侧守护这些字段

由于它位于自己的仓库中，Rapid-MLX 中的一次重命名会悄无声息地破坏这个包——那里没有任何东西导入它，而这个 CI 也不会在那里运行。因此，这些字段由拥有它们的一方固定下来，即 Rapid-MLX 中的 tests/test_model_card_client_contract.py，该文件将本包列为其存在的原因。它固定的是传输形状：字段名、可空性，以及 ModelInfo 不设置 exclude_none 这一事实——正是这一点使得 "reasoning_parser": null 能够与完全省略该键的旧服务器区分开来。

如果你在这里开始读取新的 /v1/models 字段，也要在那里添加它。 否则该守护会悄无声息地不再覆盖这个包实际使用的内容。

许可证

Apache-2.0，与 Rapid-MLX 一致。