# rapid-mlx-dsh-provider

> 为 DeepSeek Harness 提供 Rapid-MLX 本地模型路由，自动读取服务端模型元数据（上下文窗口、推理/工具解析器），省去手写 settings.yaml 的麻烦。

## Metadata

- Author: [@raullenchai](https://github.com/raullenchai)
- Repo: <https://github.com/raullenchai/rapid-mlx-dsh-provider.git>
- GitHub: [raullenchai/rapid-mlx-dsh-provider](https://github.com/raullenchai/rapid-mlx-dsh-provider)
- Stars: 20
- Language: JavaScript
- License: [Apache-2.0](https://spdx.org/licenses/Apache-2.0.html)
- Homepage: <https://github.com/raullenchai/Rapid-MLX>
- Topics: `apple-silicon`, `coding-agent`, `deepseek-harness`, `dsh`, `dsh-plugin`, `llm`, `local-llm`, `mlx`, `openai-api`, `rapid-mlx`
- Forks: 19
- Open Issues: 0
- Last push: 2026-08-19T19:34:33.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add @raullenchai/dsh-provider
```

## Wiki

## 一句话定位
为 DeepSeek Harness (DSH) 添加本地 Rapid-MLX 模型路由，直接从服务端读取模型事实（上下文窗口、是否支持推理/工具调用等），免去手动维护 settings.yaml；并附带 5 个模型管理工具和 `/rapid-mlx` 总览命令，让 Agent 在会话内就能查看、下载、删除本地模型。

## 核心能力
- 自动发现模型元数据：注册时调用本地 Rapid-MLX 服务端的 `/v1/models`，把上下文窗口、推理/工具解析器、MoE/hybrid 架构、视觉能力等信息写进路由
- 优先使用内存拟合的容量上限：上下文窗口取服务端 `max_model_len`（按 Apple Silicon 统一内存估算的容量），老版本服务端回退到 `context_window`，确保 dsh-compaction-basic 压缩时机正确
- 让推理档位"说实话"：服务端报告 `reasoning_parser: null` 的模型不再展示 off/low/medium/high 选择器（选了也没用）
- 提供 5 个模型管理工具：`rapid_mlx_serving`（查看正在服务的模型）、`rapid_mlx_cached`（查看下载缓存）、`rapid_mlx_pull`（下载模型，可取消）、`rapid_mlx_remove`（删除缓存，强制 -y）、`rapid_mlx_health`（独立报告 API 和 CLI 健康）
- 注册 `/rapid-mlx` 总览命令：一行输出服务端/CLI 健康、当前服务模型事实、缓存总占用

## 技术实现
- **语言**: JavaScript（ESM，纯 JS 无构建步骤）
- **关键依赖**: `@deepseek-ai/dsh-llm`（LlmAdapter 基类与 LlmError 契约）、`@deepseek-ai/schemastery`（Config schema 校验与默认值）、`@deepseek-ai/dsh-tools`（defineTool 注册工具）、`@deepseek-ai/dsh-subprocess`（跑 CLI 的 subprocess seam）
- **架构模式**: 通过 `cordis.patch.yml` 作为 profile bundle layer 注入；插件 inject `['llm', 'tools', 'subprocess', 'commands']` 四个服务，依赖 `dsh.bundle` 字段被 profile 加载；`Config` 用 schemastery 声明 + 环境变量回退（`RAPID_MLX_BASE_URL` / `RAPID_MLX_CLI`）
- **入口文件**: `lib/index.js`（`apply(ctx, config)` 是 cordis 钩子入口）

## 适用场景
DSH 用户希望让 Agent 直接连本机跑的 Rapid-MLX 服务端（典型如 Apple Silicon 上的 MLX 模型）时使用本插件。最直接的痛点是：通用 `openai-completions` 路由让你必须手动填 baseURL、上下文窗口和推理档位，换模型还得改；而本插件从服务端拉元数据，无需维护就能跟随服务端切换模型，并让 dsh-compaction-basic 在合适的时机触发压缩。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DeepSeek Harness | ^0.1.0-rc.8（peerDependencies） | 已对 0.1.0-rc.7 端到端验证；rc.8 与 rc.7 的 LlmAdapter 合约字节一致 |
| Node | >= 22.15.0 | README 与 GitHub Actions CI 均强制 22.15（dsh 用到 Node Zstd stream API） |
| Cordis | ^4.0.1 | peerDependency |
| Rapid-MLX 服务端 | 任意能跑 OpenAI 兼容 `/v1/models` 的版本 | `max_model_len` 是 vLLM/SGLang 标准字段；老版本只有 `context_window` 也可工作 |
| 运行平台 | macOS (Apple Silicon) | Rapid-MLX 本身依赖 Apple Silicon MLX；插件代码是纯 JS 跨平台，但实际能用必须本机有 Rapid-MLX 服务 |
| 原生模块 | 无 | 仅依赖 Node 内置 `node:os.tmpdir` |

## 安装方式
```bash
dsh plugin --profile web add @raullenchai/dsh-provider
```

## 配置项
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| `baseURL` | string | 本地 Rapid-MLX OpenAI 兼容 API 的根地址。可通过环境变量 `RAPID_MLX_BASE_URL` 覆盖 | `http://localhost:8000/v1` |
| `cliCommand` | string | 用于下载/删除/查询缓存的 `rapid-mlx` 可执行文件名（PATH 解析）或绝对路径。可通过环境变量 `RAPID_MLX_CLI` 覆盖 | `rapid-mlx` |

## 常见问题

**Q: 安装后需要在 settings.yaml 里写模型配置吗？**

A: 不需要写上下文窗口、推理档位、视觉能力这些字段了。只需要把 `agent-default-model` 的 `provider` 设为 `rapid-mlx`、`model` 设为服务端实际跑的模型名（短别名或 Hugging Face repo id 都行）。其他元数据由插件从服务端拉。

**Q: `max_model_len` 和 `context_window` 有什么区别？**

A: `context_window` 是模型训练时定的"理论最大上下文"；`max_model_len` 是服务端按当前机器的统一内存（权重 + KV 缓存）估算的"实际能塞下的上限"。插件优先用后者喂给压缩模块，避免压缩时机晚于机器实际能承载的长度。

**Q: 能在非 Apple Silicon 机器上跑吗？**

A: 插件代码是纯 JS、跨平台。但实际可用必须本机能运行 Rapid-MLX（MLX 后端限制 Apple Silicon）。在 Intel Mac 或 Linux 上安装插件本身没问题，只是没有可用的服务端连。

**Q: 服务端响应慢或 502，插件会怎样？**

A: `stream()` 路径下：HTTP 非 2xx 抛 `LlmError`（401/403 → 凭证错误码、429 → QUOTA、413 → 上下文超限、5xx → PROVIDER_ERROR）。`/v1/models` 拉取失败时静默返回空列表，让 DSH 走"未知模型"的分支而不是中断整个会话。

**Q: 工具调用和思考链支持吗？**

A: 支持。流式输出里 tool-call 增量按 `argumentsDelta` 拼接，完整 `ToolCallBlock` 在 `block-end` 一次性给出；`reasoning_content` 单独走 reasoning 通道，不混入正文文本。但图片内容会抛 `UNSUPPORTED`，不会悄悄丢弃。

**Q: 怎么卸载？**

A: `dsh plugin --profile web remove @raullenchai/dsh-provider`。移除后 `rapid-mlx` 路由和 5 个工具、 `/rapid-mlx` 命令一并下线，不影响你已有的 settings.yaml 内容。

**Q: dsh 升级到新版本会不会坏？**

A: 截至 rc.8，`LlmAdapter` 合约与 rc.7 字节一致，插件向上兼容。dsh 是开发者预览，演进很快，建议关注 cordis.patch.yml 的 inject 字段（当前 `['llm', 'tools', 'subprocess', 'commands']`）和 Config schema 是否需要新增。

## 上手难度
入门 — 本地有现成的 Rapid-MLX 服务端跑着的话，`dsh plugin add` 一行即可使用，settings.yaml 只改 provider 和 model 两行。

## 已知问题与限制
- `recommended_sampling`（每模型推荐采样参数）只读取，未自动应用
- `tool_call_parser` 只读取，未用于"模型不支持工具调用时快速失败"，目前仍可能进入循环
- `is_hybrid` / `is_moe` / `capabilities` 只读取，尚未在路由层据此改变行为
- 真正的内存感知容量仍未接入：`resolveModel()` 目前返回服务端报告的 max_model_len，这本身已经是"按机器估算的"值，但更精细的"当前可用容量"需要 Rapid-MLX 侧先暴露 `usable-capacity` 字段
- 图片输入目前直接抛 `LlmError('UNSUPPORTED')`，不静默丢弃；如果需要看图，请改用通用 openai-completions provider
- 路由名固定为 `rapid-mlx`，如果你的 settings.yaml 已在 `llm-pi-ai.providers` 下声明过同名 provider，`registerAdapter` 的 provider 排他性会导致冲突——需二选一或重命名

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [rapid-mlx-dsh-provider](https://deepseek-plugin.org/plugins/raullenchai/rapid-mlx-dsh-provider)
Wiki generated by AI (model: `MiniMax-M3`)