robbywang25/dsh-llm-mlx

English

把本机 MLX-LM 或 MLX-VLM 模型作为 DeepSeek Harness 提供方使用。插件通过 DSH 内置的 OpenAI-compatible 适配器增加 local-mlx 路由，也可以在 DSH 进程存活期间启动并托管 mlx_lm.server 或 mlx_vlm.server。

仓库不包含任何模型权重。托管启动仅支持 Apple 芯片 macOS，服务固定绑定 127.0.0.1。

本 bundle 还会在 macOS 上用插件依赖树里的同一份上游实现替换 DSH Desktop 2.0.3 的 subprocess provider，规避 packaged node-pty 把 app.asar.unpacked 再改成不存在的 app.asar.unpacked.unpacked 路径。Read Only／Workspace Write 仍走 DSH 内置 Seatbelt 隔离；Linux 与 Windows 的进程 provider 不变。

前置条件

• 托管 MLX 启动需要 Apple 芯片 macOS。
• DeepSeek Harness 0.1.0-rc.6 或 0.1.1-rc.1+。
• 一个已经安装 mlx-lm 或 mlx-vlm 的本机 Python 环境（与模型类型匹配）， 以及下载好的 MLX 模型。

插件也可以复用已经独立运行在 http://127.0.0.1:18080/v1 的 OpenAI-compatible 服务；这种模式下 DSH 不拥有该进程。

安装

安装到 Web profile：

dsh plugin --profile web add https://github.com/robbywang25/dsh-llm-mlx/releases/download/v0.4.0/dsh-llm-mlx-0.4.0.tgz

安装到 DSH Desktop profile：

dsh plugin --profile desktop add https://github.com/robbywang25/dsh-llm-mlx/releases/download/v0.4.0/dsh-llm-mlx-0.4.0.tgz

固定版本的 Release 包含已经构建好的 lib/，没有安装期 lifecycle script。 也可通过 github:robbywang25/dsh-llm-mlx 安装 Git 源码。dsh-market 目录独立更新， 使用时应核对条目中的制品版本。

v0.4.0 的自定义 RuntimeDependencies 适配器需要提供 verifyModel。设置 modelPath 时，内置适配器会校验服务器声明的模型元数据；身份未知或不匹配会拒绝 复用。这不证明权重内容或生成质量。可选代理的预算和中断响应行为见下文。

方案 A：复用已有 MLX 服务

在已安装 mlx-lm 的 Python 环境中启动：

python -m mlx_lm server \
  --model /模型的绝对路径 \
  --host 127.0.0.1 \
  --port 18080 \
  --max-tokens 512 \
  --chat-template-args '{"enable_thinking":false}'

视觉语言模型使用安装了 mlx-vlm 的环境：

python -m mlx_vlm.server \
  --model /MLX-VLM模型的绝对路径 \
  --host 127.0.0.1 \
  --port 18080 \
  --max-tokens 512

然后进入 DSH 设置 → 模型 → Local MLX，填写任意非空本机占位值，例如 local-only。本机 MLX 服务不校验这个值；通用 OpenAI 客户端只要求 API Key 字段 非空。该值只会发送到回环地址。

新建会话并选择 MLX Local Model。

方案 B：让 DSH 托管 MLX 服务

启动 DSH 前设置：

export DSH_MLX_MODEL_PATH=/模型的绝对路径
export DSH_MLX_PYTHON=/Python解释器的绝对路径
dsh web

设置 DSH_MLX_MODEL_PATH 默认会开启 mlx-lm 托管启动。插件会先检查模型配置、 tokenizer 配置和 safetensors 权重，然后才启动 Python。设置了 modelPath 时，复用 健康服务还须通过 /health 和 /v1/models 的模型身份校验；不同模型或无法确认的 身份会明确报错，已有进程保持不变。托管启动会等待身份一致，失败时只清理本次启动的 子进程；不接管被其它服务占用的端口。

MLX-VLM 优先使用已加载模型字段，避免把下载缓存当作当前模型。MLX-LM 则要求模型 列表中存在唯一的本地绝对路径；Hub 仓库名不能证明本地默认模型。路径比较使用完整 规范路径并解析符号链接，不按目录名猜测。歧义或畸形元数据会被拒绝；每次元数据读取 限时 1 秒、上限 64 KiB。没有设置 modelPath 的独立服务保留原有健康检查复用方式； 需要约束目标模型时，应明确设置该路径。

这项检查发生在插件启用时，验证的是服务声明的模型身份，不验证权重内容、Python 引擎身份或实际生成能力。serverEngine 用于选择托管启动命令；完整链路仍需真实生成验收。

若要使用持久的本机 profile 配置，可在对应 profile 的 cordis.patch.yml 中加入：

- id: llm-mlx-runtime
  config:
    autoStart: true
    serverEngine: mlx-lm
    modelPath: /模型的绝对路径
    pythonExecutable: /Python解释器的绝对路径

视觉语言模型设置 serverEngine: mlx-vlm。托管启动会改用 MLX-VLM 模块及其 支持的服务参数，不会把 MLX-LM 专属采样参数传给它。内存受限的 Mac 若需要把 多个 Agent 请求改为串行排队，可设置 maxNumSeqs: 1，避免无上限 continuous batch 同时解码。

可选的 CC Switch／Claude Desktop SSE 兼容层

部分 MLX-VLM 版本会在每个 OpenAI 流式 delta 中同时输出 reasoning_content 和弃用别名 reasoning。CC Switch 3.20.x 用同一个 serde 字段解析这两个名字，因重复字段而丢弃整块 SSE；因此可能出现非流式调用成功、 Claude Desktop 却没有正文的现象。

只有复现该症状时，才在第二个端口开启插件的回环兼容代理：

- id: llm-mlx-runtime
  config:
    autoStart: true
    serverEngine: mlx-vlm
    modelPath: /模型的绝对路径
    pythonExecutable: /Python解释器的绝对路径
    port: 18081
    maxNumSeqs: 1
    ccSwitchProxyPort: 18082
    ccSwitchChatOnly: true

DSH 继续指向原始模型端点；只把 CC Switch 的 Claude Desktop provider 的 OpenAI Chat Completions Base URL 设为 http://127.0.0.1:18082/v1。代理仅删除重复的弃用 别名，其余字段逐流转发；它只绑定回环地址并随 DSH 插件停止。删除 ccSwitchProxyPort 即可关闭。

ccSwitchChatOnly: true 会把 Cowork 的 Agent／developer 指令替换为精简的本机 聊天指令，删除 OpenAI 工具声明和工具结果消息，同时保留用户／助手对话正文。首次 在 Claude Desktop 体验本机或解除对齐的模型时建议开启最小权限模式；即使用户只 要求文本，Cowork 仍可能附带大量工具目录和 Agent 提示。此模式明确不支持 Cowork 工具执行；代理不会记录消息正文或凭据。只有明确需要并已单独信任本机模型的工具 调用时，才省略此设置。

可选代理默认允许 10 秒建立连接；完整请求发送后，最多等待 5 分钟接收首个响应 正文数据。收到正文后，每个数据块都会重新开始独立的 5 分钟空闲计时。只有响应头 不算完成预填充等待；只要正文持续到达，就没有整次生成的总时长截止。较慢的本机 模型可以调整预算，同时保留边界：

    ccSwitchProxyLimits:
      connectTimeoutMs: 10000
      firstByteTimeoutMs: 300000
      idleTimeoutMs: 300000
      maxSseEventBytes: 1048576

各项必须为正整数；超时最多支持 1 小时，SSE 事件缓冲最多支持 16 MiB。默认 1 MiB 按每个事件的 UTF-8 字节计数，包含分隔符，不限制整段流的累计大小。普通 JSON 响应直接转发，不收集完整正文。超时在输出开始前返回 504；超大 SSE 事件 或上游响应中断返回 502。已经开始输出时会直接终止不完整响应，不追加错误正文； 客户端应将该回答视为未完成。客户端取消或代理退出时会关闭对应的上游请求。 格式不合法的请求 URL 会返回 400，不向上游发起请求，也不会让代理宿主进程退出。 这些设置只作用于可选代理，不会自动开启它或改变直连模型的路由。代码调用方可将 相同字段传入 options.limits。

不要把某位用户的本机模型路径提交到公共仓库。

默认值

设置	默认值
托管服务引擎	mlx-lm
MLX-VLM 并发序列	使用服务默认值；可选 maxNumSeqs
CC Switch SSE 兼容代理	默认关闭；可选 ccSwitchProxyPort
CC Switch 纯聊天工具边界	默认关闭；可选 ccSwitchChatOnly
Provider	local-mlx
模型 ID	default_model
API Base URL	http://127.0.0.1:18080/v1
向 DSH 声明的上下文窗口	16,384 tokens
最大输出	512 tokens
Temperature / top-p / top-k	0.6 / 0.8 / 20
Thinking 模板参数	关闭
托管启动	只有设置 DSH_MLX_MODEL_PATH 才开启

提供方配置仍可在 DSH 模型页修改。如果服务使用其他端口，必须同时修改运行时端口 和 provider Base URL。

安全边界

• 托管服务的 host 固定为 127.0.0.1，插件不提供局域网或公网监听选项。
• 可选的 CC Switch 兼容代理同样只绑定 127.0.0.1，只接受回环 MLX 上游， 不记录凭据或消息正文。
• 模型路径必须是已存在的本机绝对路径；插件不会下载模型。
• Python 使用参数数组启动，不经过 shell。
• 插件不上传权重、prompt、回复、凭据或遥测。
• DSH_MLX_API_KEY 只是本机占位符，不是外部凭据。
• macOS PTY 兼容 provider 只改变同一份上游 subprocess 实现及其原生 helper 的加载位置，不削弱 DSH 权限 preset，也不绕过 Seatbelt。
• 插件卸载时只停止自己创建的子进程，不会停止独立管理的服务。

MLX HTTP 服务用于本机开发。请只在回环地址使用，不要直接暴露到 不受信任的网络。

验证

curl --fail http://127.0.0.1:18080/health
curl --fail http://127.0.0.1:18080/v1/models

对于受影响的 DSH Desktop 版本，还需分别在 Full Access 与 Read Only 下用 pwd 等无副作用命令验证 Bash。Read Only 必须报告 Seatbelt 隔离成功，不能静默退化为 无隔离执行。

最终验收必须是：新建 DSH 会话，选择 MLX Local Model，并实际收到模型回复。 只有模型卡可见或 health 返回 200，都不等于完整 DSH 链路通过。

仓库校验：

npm ci --ignore-scripts
npm run check

卸载

dsh plugin --profile web remove dsh-llm-mlx
# 或
dsh plugin --profile desktop remove dsh-llm-mlx

由插件托管的服务会随插件卸载而停止；独立服务需单独停止。卸载后可在 DSH 模型 设置中删除本机占位凭据。

许可证

MIT。MLX-LM、MLX-VLM 与每个模型继续适用各自许可证；本仓库不重新分发它们。