dsh-mmx

Readme

# dsh-mmx

**MiniMax CLI bridge for DeepSeek Harness** — 把 [MiniMax CLI（`mmx`）](https://github.com/MiniMax-AI/cli) 的网络搜索与图像理解接入 DSH：搜索自动回退、贴图自动识图、首次使用按操作系统给出安装指引，CLI 就绪后 30 秒内自动启用。

> 语言：[English](./README.en.md)

## 功能

1. **网络搜索回退**：向 `ctx.web` 注册 `mmx-search` 搜索 provider。通过 profile patch 将 `searchProvider` 指向 `mmx-search`（或在未钉选 provider 时由 DSH 自动选用唯一可用的 provider），`web_search` 工具即可透明地由 MiniMax 提供服务。
2. **透明识图**：纯文本模型发送图片时，插件在发送前调用 `mmx vision describe` 生成文字描述，并以「模型可见替换」方式注入——对话记录中正常显示图片，模型实际收到的是 `[图片内容描述] …` 文字；`read_image` 工具同样返回文字描述而非 `UNSUPPORTED_CONTENT`。多模态模型默认原样放行（`alwaysUseMmx: true` 可改为总是走 mmx）。
3. **首次使用引导（OOBE）**：mmx 未安装或未登录时，两个能力自动停用；设置页卡片提供**一键安装**（填入 API Key → 自动 `npm install -g mmx-cli` + `mmx auth login` → 完成后刷新状态），并附按操作系统区分的**手动安装**指引（Windows PowerShell / macOS / Linux Terminal）。插件每 30 秒重新探测，CLI 就绪后自动开启，无需重启。

## 截图

设置 → 插件 → 「MiniMax 桥接 (dsh-mmx)」配置卡片：

<img src="assets/settings.png" width="420" alt="dsh-mmx settings card">

## 安装

### 方式一：插件市场

在 DSH Web 设置页的「插件市场」中搜索 `dsh-mmx` 并一键安装（提交审核后可用）。

### 方式二：命令行

```sh
# GitHub（推荐）
dsh plugin --profile web add github:crazyma99/dsh-mmx
# npm registry
dsh plugin --profile web add dsh-mmx
# 本地目录
dsh plugin --profile web add file:/path/to/dsh-mmx
```

安装后重启 dsh web。

### 前置：MiniMax CLI

| 操作系统 | 终端 | 命令 |
|---|---|---|
| Windows | PowerShell | `npm install -g mmx-cli` → `mmx auth login --api-key <你的 MiniMax API Key>` |
| macOS | Terminal | `npm install -g mmx-cli` → `mmx auth login --api-key <你的 MiniMax API Key>` |
| Linux | Terminal | `npm install -g mmx-cli` → `mmx auth login --api-key <你的 MiniMax API Key>` |

> 前置条件：Node.js ≥ 20。验证安装：`mmx quota`（可查看 TokenPlan 余额）。
> 本插件不读取、不打印、不存储你的 API Key——仅判断本地 `~/.mmx/config.json` 中是否存在密钥。

### 搜索 provider 钉选（重要）

DSH 基础 bundle 默认将搜索 provider 钉选为 `deepseek-official`。若 DeepSeek 搜索未配置有效 key，请在 profile 的 `cordis.patch.yml` 中覆盖：

```yaml
- id: web
  config:
    searchProvider: mmx-search
```

> 若后续获得有效的 DeepSeek 搜索 key，可改回 `deepseek-official`；在未钉选 provider 时，DSH 会自动选用唯一 `available()` 的 provider。

## 配置

优先级：settings 命名空间 `dsh-mmx` ＞ `cordis.patch.yml` 的 `config` 行 ＞ 默认值。

| 键 | 默认值 | 说明 |
|---|---|---|
| `enabled` | `true` | 总开关 |
| `searchEnabled` | `true` | 注册 mmx 搜索 provider |
| `visionEnabled` | `true` | 透明识图 |
| `patchAdmission` | `true` | 包装 `resolveModelInfo` 放行图片准入（仅 mmx 就绪时生效） |
| `alwaysUseMmx` | `false` | `true` = 多模态模型也走 mmx 识图 |
| `visionPrompt` | 中文详细描述模板 | 识图提示词 |
| `mmxBin` | `mmx` | CLI 命令名或绝对路径 |
| `npmBin` | `npm` | 一键安装使用的 npm 命令名或绝对路径 |
| `timeoutMs` | `60000` | 单次 CLI 调用超时（5000–300000 ms） |

### 配置入口

1. **设置页卡片**：设置 → 插件 → 「MiniMax 桥接 (dsh-mmx)」。布尔开关即时保存；文本/数字字段编辑后点击「保存」。卡片底部提供**一键安装**（填 API Key → 自动安装并登录 → 刷新状态）与按操作系统切换的手动安装指引。
   - 需要将 `'dsh-mmx'` 加入 DSH `WEB_SETTINGS_NAMESPACES` 白名单（`packages/host/apiproxy/src/api-proxy.ts`，一行；升级 DSH 后需重打）。
2. **`~/.dsh/settings.yaml`**（热加载，无需重启）：

   ```yaml
   dsh-mmx:
     enabled: true
     searchEnabled: true
     visionEnabled: true
     patchAdmission: true
     alwaysUseMmx: false
     mmxBin: mmx
     timeoutMs: 60000
   ```

3. **profile `cordis.patch.yml` 的 `config` 行**（需重启）。

## 搜索回退语义

- 未钉选 provider 且 DeepSeek 搜索无有效 key → 自动使用 `mmx-search`；
- 钉选 `mmx-search` → 始终使用 MiniMax（本仓库推荐配置）；
- DeepSeek 与 mmx 同时可用且未钉选 → DSH 报 `WEB_PROVIDER_AMBIGUOUS`，需显式钉选其一。

## 兼容性

- 目标平台：DeepSeek Harness Web profile（0.1.0-rc.x）。
- 宿主侧零运行时依赖；客户端 bundle 仅依赖 React（由 DSH 客户端运行时提供）。

## 隐私与安全

- 图片经 mmx CLI 上传至 MiniMax API（base64）用于识图；搜索查询词发送至 MiniMax 搜索接口；
- 所有子进程调用均以参数数组直接 `spawn`（不经 shell），并设置超时与取消传播；
- API Key 永不读取、打印或记录；一键安装接口 `POST /dsh-mmx/install` 强制同源校验、请求体 4 KiB 封顶、互斥串行，API Key 仅透传给 `mmx auth login` 一次、不回显；临时图片文件权限 `0600`，用完即删；
- 标准输出/错误捕获设有 4 MiB 上限，防止失控进程耗尽内存。

## 卸载

```sh
dsh plugin --profile web remove dsh-mmx
```

卸载后重启 dsh web；`settings.yaml` 中的 `dsh-mmx:` 段可手动删除。

## License

[MIT](./LICENSE)