# @goodandready/dsh-model-sync 中文文档

规范地址：https://npmcn.com/package/%40goodandready/dsh-model-sync/

版本：0\.5\.29
npm 元数据更新时间：2026-11-14T12:19:24.312Z
中文译文更新时间：2026-11-16T19:12:35.270Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40goodandready/dsh-model-sync
原文对照：https://npmcn.com/package/%40goodandready/dsh-model-sync/?lang=original
项目主页：https://github.com/GooDAnDReaDY/dsh-model-sync
源码仓库：https://github.com/GooDAnDReaDY/dsh-model-sync

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：549 kB，55 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@deepseek-ai/cordis ^4\.0\.1，@deepseek-ai/dsh-llm ^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1 \|\| \>=0\.2\.1-alpha\.1，@deepseek-ai/schemastery ^3\.18\.4，@deepseek-ai/dsh-settings ^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1 \|\| \>=0\.2\.1-alpha\.1，@deepseek-ai/dsh-credentials ^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1 \|\| \>=0\.2\.1-alpha\.1，@deepseek-ai/dsh-host-webserver ^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1 \|\| \>=0\.2\.1-alpha\.1
- 首次发布：2026-08-23T17:43:21.350Z
- 最新版本发布：2026-11-14T12:19:24.155Z
- 近 30 天下载量：4689（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：71（近 12 个月 71 个）

## 中文简介

API-key DeepSeek Harness供应商的自动模型目录同步.

## 安装

```sh
npm install @goodandready/dsh-model-sync
```

也可以使用：`pnpm add @goodandready/dsh-model-sync`、`yarn add @goodandready/dsh-model-sync`、`bun add @goodandready/dsh-model-sync`

## README

# 📦 @goodandready/dsh-model-sync

### 面向 DeepSeek Harness 的动态大模型目录同步与自动化余额监控插件

[![npm version](https://img.shields.io/npm/v/@goodandready/dsh-model-sync.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b)](https://www.npmjs.com/package/@goodandready/dsh-model-sync) [![license](https://img.shields.io/badge/License-MIT-10b981.svg?style=for-the-badge&color=10b981&labelColor=064e3b)](https://npmcn.com/package/%40goodandready/dsh-model-sync/LICENSE) [![DSH Plugin](https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065)](https://github.com/topics/dsh-plugin) [![Node version](https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03)](https://nodejs.org/)

[![作者所有项目](https://img.shields.io/badge/%E4%BD%9C%E8%80%85%E6%89%80%E6%9C%89%E9%A1%B9%E7%9B%AE-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e)](https://goodandready.app/)

[**🇬🇧 English**](https://npmcn.com/package/%40goodandready/dsh-model-sync/README.md) • [**🇷🇺 Русский**](https://npmcn.com/package/%40goodandready/dsh-model-sync/README.ru.md) • [**🇨🇳 中文说明**](https://npmcn.com/package/%40goodandready/dsh-model-sync/README.zh.md)

<table><tbody><tr><td align="center">⭐ <strong>如果您喜欢这个插件，请在 GitHub 上为它点亮 Star</strong> — 这能让我知道插件对您有用，并鼓励我继续开发和维护它。<br><br>🐛 <strong>如果您发现 Bug 或希望增加功能</strong>，请使用任意语言在 GitHub 上提交 Issue — 我会评估您的建议，并在后续版本中实现有价值的改进。</td></tr></tbody></table>

* * *

## ⚡ 插件概览

**`dsh-model-sync`** 保持您的 **DeepSeek Harness** 模型目录与上游各大 AI 服务商最新发布完全同步。

每当服务商推出新模型、调整上下文窗口上限或变更费率时，不再需要手动逐项编辑 YAML 配置文件。`dsh-model-sync` 能够自动发现新版本、更新模型能力元数据（`vision`、`tools`、`reasoning`、`embeddings`）、监控账户余额并在无需重启服务的情况下即时对齐模型目录。

```mermaid
graph LR
    subgraph Trigger [调度与手动触发]
        Cron[⏰ 后台轮询调度器] --> Engine[dsh-model-sync 核心引擎]
        WebUI[🖥️ 设置面板: 立即同步按钮] --> Engine
    end

    subgraph Providers [25+ 上游服务商]
        Engine --> Registry{适配器注册中心}
        Registry -->|Bearer 认证| P1[OpenAI / DeepSeek / OpenRouter / Groq]
        Registry -->|x-api-key 认证| P2[Anthropic Claude / 自定义网关]
        Registry -->|query-key 认证| P3[Google Gemini]
        Registry -->|本地探测| P4[本地 Ollama / vLLM / SGLang]
        Registry -->|CommandCode 接口| P5[Command Code / visibleModels]
        Registry -->|套餐检测| P6[ClineBot 订阅套餐]
    end

    subgraph Reconcile [目录对齐与审计追踪]
        P1 --> Normalizer[模型标准化器与能力打标]
        P2 --> Normalizer
        P3 --> Normalizer
        P4 --> Normalizer
        P5 --> Normalizer
        P6 --> Normalizer
        Normalizer --> Diff[差异跟踪: 新增 / 已废弃]
        Diff --> Catalog[当前可用 DSH 模型目录与 visibleModels]
    end

    style Trigger fill:#1e1e2e,stroke:#89b4fa,stroke-width:2px,color:#cdd6f4
    style Providers fill:#181825,stroke:#cba6f7,stroke-width:2px,color:#cdd6f4
    style Reconcile fill:#11111b,stroke:#a6e3a1,stroke-width:2px,color:#cdd6f4
```

* * *

## ✨ 核心特性

-   🏷️ **智能集合与模型自动标签**：同步时自动识别并标记模型分类标签（`coding` 编程、`reasoning` 思考推理、`fast` 极速轻量、`vision` 多模态、`long-context` 128k+ 长上下文），支持 UI 药丸胶囊快速筛选与一键精选顶级旗舰预设（"⭐ 精选最佳"）。
-   ⚡ **延迟雷达 (TTFT) 与火花线可视化**：实时测量模型响应时间与首字延迟 (TTFT)，提供火花线走势（`▂▃▂`）及 4 档速度徽章（⚡ `< 300ms`、🟢 `< 1.2s`、🟡 `1.5 - 3.0s`、🔴 `> 3.0s`），并开放 `GET /dsh-model-sync/health/latency` 路由接口。
-   💸 **实时价格动态后台同步与提示词缓存**：定期从 OpenRouter 和 LiteLLM 获取最新模型单价，支持本地磁盘降级缓存，支持提示词缓存读写定价（`cacheReadPerToken`、`cacheWritePerToken`），并提供 `GET /dsh-model-sync/pricing` 和 `POST /dsh-model-sync/pricing/sync` 端点。
-   💰 **内置基准价格数据库**：自动为 OpenAI、Anthropic、Groq、Mistral、xAI 和 DeepSeek 模型补充 Token 价格数据，即使服务商接口未返回价格，也可无缝支持成本上限过滤与 `@cheap` 别名解析。
-   🎯 **动态智能虚拟别名与故障转移**：支持 `@fast`、`@cheap`、`@best-code` 等虚拟别名及故障转移链，在熔断器打开或健康检查失败时自动切换至备用模型。
-   📏 **真实上下文限制与边界安全 (`contextWindow` / `maxOutputTokens`)**：精确区分输入与输出令牌限制，通过自动限制防止 400 `max_tokens` 错误，并在 Web UI 中显示 `输入: 128k | 输出: 8k` 徽章。
-   🧠 **统一的深度思考与推理配置 (Reasoning & Thinking)**：自动检测参数格式 (`effort`, `budget_tokens`, `boolean`) 并转换推理预算，自动屏蔽不兼容参数（如 o1/o3 的 `temperature`）。
-   🔔 **外部差异通知 Webhook 与事件分发**：支持 HMAC-SHA256 签名验证的实时 Webhook 通知与 Cordis `model-sync/diff` 事件，可在新模型上线、模型废弃或价格变更时即时推送。
-   ⚡ **高性能模型策略过滤**：在未配置过滤策略时，`filterModels` 采用快速路径直接返回模型目录，避免不必要的正则表达式编译和数组遍历。
-   🔄 **一键检查与更新**：内置设置面板更新检查，在手动刷新时通过 `?fresh=1` 或 `Cache-Control: no-cache` 绕过 npm 缓存，即时获取最新版本。
-   🔄 **自动化目录同步**：自动对齐 25+ 服务商的模型清单、别名、上下文窗口及能力标签（`vision`、`tools`、`reasoning`、`embeddings`）。
-   🛡️ **Minijinja 聊天模板与角色兼容性保障**：自动为 Groq 开源模型（Qwen、Llama、Mistral、Gemma、DeepSeek）及 DeepSeek API 注入 `compat.supportsDeveloperRole: false`，避免推理模型报 400 `Unexpected message role` 错误，同时保留用户自定义配置。
-   🌐 **内置 25+ 服务商适配器**：预置支持 OpenAI、Anthropic、Google、DeepSeek、xAI、OpenRouter、Groq、Mistral、Cerebras、Fireworks、HuggingFace、Moonshot、NVIDIA、Qwen、Together、Xiaomi MiMo、SiliconFlow、Command Code、ClineBot 以及本地 Ollama。
-   🎛️ **Command Code 模型精细管理**：完整发现 Command Code 模型目录，在 Web 界面提供勾选过滤，自动同步 `visibleModels` 至 `llm-commandcode` 设置中。
-   🎯 **ClineBot 订阅套餐精准匹配**：专属适配器直接调用 `GET /users/me/plan`，只拉取当前有效订阅套餐包含的模型，彻底解决全量拉取 400+ 外部模型导致的混淆。
-   🔌 **通用与自定义适配器扩展**：支持接入任意兼容 OpenAI `/v1/models` 规范的网关，支持多种认证方式（`bearer`、`x-api-key`、`query-key`、`none`）。
-   📊 **余额与用量监控**：实时查询上游计费端点，精准反馈账户额度并防止因欠费导致任务中断。
-   📜 **同步历史与变更审计**：完整记录新模型上线、旧模型废弃及能力变更的时间线与详细差异。
-   🖥️ **全功能 Web 管理面板 (**设置 → 模型同步**)**：
    -   每个服务商的卡片化状态展示与模型计数；
    -   一键即时同步（Sync Now）；
    -   模型勾选过滤与显示控制；
    -   服务商启用开关及自定义 Endpoint 地址输入。

* * *

## 🛠️ 支持的服务商列表

| 服务商标识符 | 认证机制 | 能力自检与特性说明 |
| --- | --- | --- |
| `openai` | Bearer Token | `vision`, `tools`, `reasoning`, `embeddings` |
| `anthropic` | `x-api-key` 请求头 | `vision`, `tools`, `reasoning` |
| `google` | Query 参数 / 密钥 | `vision`, `tools`, `reasoning`, `embeddings` |
| `deepseek` | Bearer Token | `tools`, `reasoning` |
| `xai` | Bearer Token | `vision`, `tools`, `reasoning` |
| `openrouter` | Bearer Token | 多厂商汇聚模型目录，包含计费与上下文规格 |
| `groq` | Bearer Token | `tools`, `reasoning`, `vision`, `supportsDeveloperRole: false` |
| `mistral` | Bearer Token | `tools`, `reasoning`, `vision` |
| `commandcode` | Bearer Token | 对接 `https://api.commandcode.ai/provider/v1/models`，同步勾选至 `llm-commandcode` 的 `visibleModels` |
| `clinebot` | Bearer Token | 仅同步有效订阅套餐 (`/users/me/plan`) 包含的模型 |
| `fireworks` | Bearer Token | 开源权重推理节点 |
| `huggingface` | Bearer Token | Serverless Inference API 目录 |
| `together` | Bearer Token | 开源大模型服务网络 |
| `ollama` | 本地 HTTP (`none`) | 本地离线模型实时发现 (`/api/tags`) |
| `custom` | 自定义配置 | 任意兼容 OpenAI 或 Google 规范的 API 网关 |

* * *

## 📦 快速安装

```bash
dsh plugin --profile web add @goodandready/dsh-model-sync
```

> \[!IMPORTANT\] 安装后请重启 DSH Web 界面 (`systemctl --user restart dsh-web`)，以激活后台目录自动同步。

* * *

## ⚙️ 配置说明 (`settings.yaml`)

```yaml
dsh-model-sync:
  enabled: true
  scheduleEnabled: false
  intervalMinutes: 60
  autoApply: false
  requestTimeoutMs: 15000
  retryAttempts: 3
  concurrency: 4
  providers:
    - provider: commandcode
      enabled: true
      autoApply: false
    - provider: clinebot
      enabled: true
      autoApply: false
```

| 参数名称 | 类型 | 默认值 | 功能说明 |
| --- | --- | --- | --- |
| `enabled` | `boolean` | `true` | 后台自动同步主开关 |
| `scheduleEnabled` | `boolean` | `false` | 启用周期性后台定时同步任务 |
| `intervalMinutes` | `number` | `60` | 目录更新轮询间隔（分钟） |
| `autoApply` | `boolean` | `false` | 是否自动将新发现的模型生效至可用列表 |
| `requestTimeoutMs` | `number` | `15000` | 目录拉取 HTTP 请求超时时间（毫秒） |
| `retryAttempts` | `number` | `3` | 瞬态网络故障的最大重试次数 |
| `concurrency` | `number` | `4` | 最大并发服务商同步任务数 |
| `providers` | `array` | `[]` | 服务商独立配置列表（`provider`、`enabled`、`autoApply`） |

* * *

### 🔍 主动硬件能力探测 (Capability Probing)

-   **微探针测试**：真实验证模型能力，杜绝虚标：
    -   `JSON Schema`：测试结构化 JSON 生成。
    -   `Tools / Functions`：测试函数与工具调用能力。
    -   `Vision`：测试多模态图像理解。
    -   `Developer Role`：测试推理模型的 `developer` 角色支持。
-   **Web UI 操作**：服务商卡片专属“🔍 验证能力”按钮，全局工具栏支持“🔍 验证所有模型”与“⚡ 仅验证新模型”。
-   **能力认证徽章**：绿色认证标识（`✔ Tools`, `✔ Vision`, `✔ JSON`, `✔ DevRole`）持久化存储。

### 🦙 Ollama 本地模型管理中心

-   **Web 端直接管理**：无需登录终端即可在 DSH 界面直接拉取、查看与删除 Ollama 本地模型。
-   **实时下载进度条**：流式展示层下载百分比与传输大小。
-   **显存调度 (VRAM)**：监控显存中活跃模型（`/api/ps`），支持一键“⏏ 释放显存” (`keep_alive: 0`)。
-   **量化与架构信息**：清晰展示量化格式（`Q4_K_M`, `Q8_0`）、模型系列及真实上下文窗口。

* * *

## 📄 开源协议

MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

## 常见问题

### @goodandready/dsh-model-sync 是什么？

API-key DeepSeek Harness供应商的自动模型目录同步\.

### 如何安装 @goodandready/dsh-model-sync？

在项目目录运行 npm install @goodandready/dsh-model-sync，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@deepseek-ai/cordis（^4\.0\.1）、@deepseek-ai/dsh-llm（^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1 \|\| \>=0\.2\.1-alpha\.1）、@deepseek-ai/schemastery（^3\.18\.4）、@deepseek-ai/dsh-settings（^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1 \|\| \>=0\.2\.1-alpha\.1）、@deepseek-ai/dsh-credentials（^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1 \|\| \>=0\.2\.1-alpha\.1）、@deepseek-ai/dsh-host-webserver（^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1 \|\| \>=0\.2\.1-alpha\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @goodandready/dsh-model-sync 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @goodandready/dsh-model-sync 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @goodandready/dsh-model-sync 可以商用吗？

@goodandready/dsh-model-sync 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @goodandready/dsh-model-sync 的下载量有多少？

根据 npm 官方下载统计，@goodandready/dsh-model-sync 在 2026/10/17 – 2026/11/15 这 30 天内被下载 4,689 次，日均约 156 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @goodandready/dsh-model-sync 还在维护吗？

最新版本 0\.5\.29 发布于 2026/11/14（2 天前）；至今共发布 71 个版本，其中过去 12 个月发布了 71 个；首次发布于 2026/08/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

