# @goodandready/dsh-ollama-cloud-provider 中文文档

规范地址：https://npmcn.com/package/%40goodandready/dsh-ollama-cloud-provider/

版本：0\.1\.39
npm 元数据更新时间：2026-11-15T21:21:22.284Z
中文译文更新时间：2026-11-16T19:09:45.557Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：548 kB，67 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：0 个
- peer 依赖：react ^18\.2\.0，@deepseek-ai/cordis ~4\.0\.4 \|\| ~4\.0\.5 \|\| ~4\.0\.6-alpha\.1 \|\| ~4\.1\.0，@deepseek-ai/dsh-llm 0\.2\.0-rc\.2 \|\| \>=0\.2\.1-rc\.2 \<0\.2\.3-0 \|\| \>=0\.2\.2-0 \<0\.2\.3-0，@deepseek-ai/dsh-web 0\.2\.0-rc\.2 \|\| \>=0\.2\.1-rc\.2 \<0\.2\.3-0 \|\| \>=0\.2\.2-0 \<0\.2\.3-0，@deepseek-ai/schemastery ~3\.18\.4 \|\| ~3\.18\.5 \|\| ~3\.18\.6-alpha\.1 \|\| ~3\.19\.0，@deepseek-ai/dsh-commands 0\.2\.0-rc\.2 \|\| \>=0\.2\.1-rc\.2 \<0\.2\.3-0 \|\| \>=0\.2\.2-0 \<0\.2\.3-0，@deepseek-ai/dsh-settings 0\.2\.0-rc\.2 \|\| \>=0\.2\.1-rc\.2 \<0\.2\.3-0 \|\| \>=0\.2\.2-0 \<0\.2\.3-0，@deepseek-ai/dsh-attachment 0\.2\.0-rc\.2 \|\| \>=0\.2\.1-rc\.2 \<0\.2\.3-0 \|\| \>=0\.2\.2-0 \<0\.2\.3-0，@deepseek-ai/dsh-credentials 0\.2\.0-rc\.2 \|\| \>=0\.2\.1-rc\.2 \<0\.2\.3-0 \|\| \>=0\.2\.2-0 \<0\.2\.3-0，@deepseek-ai/dsh-client-locale 0\.2\.0-rc\.2 \|\| \>=0\.2\.1-rc\.2 \<0\.2\.3-0 \|\| \>=0\.2\.2-0 \<0\.2\.3-0，@deepseek-ai/dsh-host-webserver 0\.2\.0-rc\.2 \|\| \>=0\.2\.1-rc\.2 \<0\.2\.3-0 \|\| \>=0\.2\.2-0 \<0\.2\.3-0，@deepseek-ai/dsh-client-ui-slots 0\.2\.0-rc\.2 \|\| \>=0\.2\.1-rc\.2 \<0\.2\.3-0 \|\| \>=0\.2\.2-0 \<0\.2\.3-0，@deepseek-ai/dsh-client-ui-renderer 0\.2\.0-rc\.2 \|\| \>=0\.2\.1-rc\.2 \<0\.2\.3-0 \|\| \>=0\.2\.2-0 \<0\.2\.3-0，@deepseek-ai/dsh-client-ui-settings 0\.2\.0-rc\.2 \|\| \>=0\.2\.1-rc\.2 \<0\.2\.3-0 \|\| \>=0\.2\.2-0 \<0\.2\.3-0，@deepseek-ai/dsh-launch-environment 0\.2\.0-rc\.2 \|\| \>=0\.2\.1-rc\.2 \<0\.2\.3-0 \|\| \>=0\.2\.2-0 \<0\.2\.3-0
- 首次发布：2026-10-21T16:07:01.248Z
- 最新版本发布：2026-11-15T21:21:22.032Z
- 近 30 天下载量：9223（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：38（近 12 个月 38 个）

## 中文简介

Ollama Cloud LLM 为 DeepSeek Harness (dsh) 提供插件.

## 安装

```sh
npm install @goodandready/dsh-ollama-cloud-provider
```

也可以使用：`pnpm add @goodandready/dsh-ollama-cloud-provider`、`yarn add @goodandready/dsh-ollama-cloud-provider`、`bun add @goodandready/dsh-ollama-cloud-provider`

## README

# 📦 @goodandready/dsh-ollama-cloud-provider

### 面向 DeepSeek Harness 的 Ollama Cloud 模型提供商插件

[![GoodAndReady 展厅](https://img.shields.io/badge/%F0%9F%8C%90_DSH_Hub-goodandready.app-ff4500.svg?style=for-the-badge&labelColor=1a1a2e)](https://goodandready.app/) [![npm 版本](https://img.shields.io/npm/v/@goodandready/dsh-ollama-cloud-provider?style=for-the-badge&color=crimson&logo=npm)](https://www.npmjs.com/package/@goodandready/dsh-ollama-cloud-provider) [![许可证](https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge)](https://github.com/GooDAnDReaDY/dsh-ollama-cloud-provider/blob/main/LICENSE)

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

* * *

面向 [DeepSeek Harness](https://deepseek-harness.github.io/deepseek-harness/)（dsh）的 **Ollama Cloud** 模型提供商插件。

插件注册一个原生 LLM 路由 `ollama-cloud`（`https://ollama.com`），支持两种底层传输协议：

| 传输协议 | 端点 | 用途 |
| --- | --- | --- |
| `native`（默认） | `POST /api/chat` | thinking、工具调用、usage 计数（NDJSON） |
| `openai-chat` | `POST /v1/chat/completions` | OpenAI 兼容部署与备用网关（SSE） |

密钥在每次请求时动态解析：在设置中更换凭据无需重启即可立即生效。

## 架构示意

```mermaid
graph LR
    subgraph DSH["DeepSeek Harness 核心"]
        Agent["DSH 智能体 / 聊天"]
        Creds["凭据服务 / 环境变量"]
    end

    subgraph Plugin["dsh-ollama-cloud-provider"]
        Router{"路由: ollama-cloud"}
        Pool["多账号连接池<br/>轮换、冷却、粘性会话"]
        Catalog["实时模型目录<br/>/v1/models + /api/tags"]
        Usage["余额与用量监控<br/>/api/balance + /api/usage"]

        subgraph Transports["底层传输协议"]
            T1["Native /api/chat (NDJSON)"]
            T2["OpenAI /v1/chat/completions (SSE)"]
        end
    end

    subgraph Ollama["Ollama Cloud 云端网关"]
        Chat["ollama.com/api/chat"]
        OpenAI["ollama.com/v1/chat/completions"]
        Billing["/api/balance, /api/usage"]
    end

    Agent --> Router
    Creds -.-> Pool
    Router --> Pool
    Pool --> Transports
    T1 --> Chat
    T2 --> OpenAI
    Catalog --> Router
    Usage --> Billing
```

## 功能全貌

-   **两种底层传输协议**：按模型选择 Ollama 原生协议（NDJSON）或 OpenAI 兼容协议（SSE）。
-   **全要素流式交互**：文本、深度思考（thinking）、工具调用、多模态图像、Token 统计与 finish reasons。
-   **全局唯一工具调用 ID**：自动生成跨步不重复的工具调用标识符，彻底防止多步对话（如 PTC 预设）因 ID 冲突导致 DSH 会话日志校验失败。
-   **实时模型目录**：自动从 `GET /v1/models` 获取模型列表，并结合 `GET /api/tags` 补全能力标记（`tools`、`thinking`、`vision`）。
-   **精准模型元数据**：上下文长度、输入模态、推理等级与默认配置、工具支持状态及 API 开放性。
-   **官方余额与用量分析**：集成官方 `/api/balance` 与 `/api/usage`，呈现可用额度、已购额度、24小时/7天/30天支出及按模型细分报表。
-   **多账号智能轮换**：在输出首个 Token 之前，遇到 401/403/429 或额度耗尽自动切换至备用账号。冷却时间通过 SHA-256 哈希安全持久化。
-   **会话粘性与路由规则**：支持单会话锁定同一账号，以及基于 Glob 通配符的 `模型 → 账号` 绑定规则。
-   **成本透明估算**：依据官方发布的价目表（包含闲时优惠折扣）进行费用估算，支持按模型覆盖价格。
-   **Web UI 与交互卡片**：
    -   **设置 → Ollama Cloud**：密钥配置、余额显示、账号池管理、模型白名单与协议切换。
    -   **侧边栏配额指示卡片**：环形展示最高额度窗口（默认关闭且不产生后台轮询；可在名称旁显示 `planLabel`，例如 `PRO`）。
    -   **中央用量分析面板**：支出窗口、请求热力图与用量走势。
-   **`/ollama` 快捷指令**：快速查询状态、额度、余额、账号列表与执行联通性测试。
-   **一键热更新**：在 DSH 设置页直接检测 npm 最新版本并快速安装更新。

## Requirements / 系统要求

-   **DeepSeek Harness**: `0.2.0-rc.2 || >=0.2.1-rc.2 <0.2.3-0 || >=0.2.2-0 <0.2.3-0`（桌面版与 Web 配置文件）。
-   **Node.js**: `>=22.0.0`。
-   **Ollama Cloud 账户**: 一个或多个有效的 Ollama Cloud API Key 或兼容的代理端点。

## 安装指南

从源码构建与打包：

```bash
npm install
npm run build
npm pack
```

从 npm 安装已发布版本：

```bash
dsh plugin --profile web add @goodandready/dsh-ollama-cloud-provider@0.1.39
# DSH 桌面端：
dsh plugin --profile desktop add @goodandready/dsh-ollama-cloud-provider@0.1.39
```

或通过打包文件安装：

```bash
dsh plugin --profile web add /absolute/path/to/goodandready-dsh-ollama-cloud-provider-0.1.39.tgz
# DSH 桌面端：
dsh plugin --profile desktop add /absolute/path/to/goodandready-dsh-ollama-cloud-provider-0.1.39.tgz
```

安装完成后重启 dsh 或 DSH 桌面端，在模型列表中选择 **Ollama Cloud** 即可。

## 配置示例

```yaml
- id: llm-ollama-cloud
  name: "@goodandready/dsh-ollama-cloud-provider"
  config:
    apiKeyEnv: OLLAMA_API_KEY      # 环境变量名或 DSH 凭据名
    # apiKey: ...                  # 仅本地调试，严禁提交代码库
    transport: native              # native | openai-chat
    requestTimeoutMs: 300000
    streamIdleTimeoutMs: 300000
    visibleModels: []
    modelTransports: {}
    accounts:
      - label: Work
        apiKeyEnv: OLLAMA_API_KEY_2
    activeAccount: ''              # 固定指定活跃账号
    stickySession: true
    showSidebarQuota: false
    planLabel: ''                  # 可选，例如 PRO
```

除 `apiKey` 外的所有配置项均可在 DSH 设置页直接修改。

### 密钥配置

1.  DSH 配置中的 `config.apiKey`。
2.  DSH 凭据服务中的 `apiKeyEnv`（默认 `OLLAMA_API_KEY`）。
3.  环境变量或 `$DSH_HOME/.env`。

密钥可在官方后台生成：[https://ollama.com/settings/keys](https://ollama.com/settings/keys)。云端网关仅接受 `Authorization: Bearer` 请求头。

### 多账号轮换与冷却重置

多账号在首字输出前自动轮换。鉴权失败（401/403）进入 5 分钟冷却期，配额错误遵循 Retry-After 响应头。可在设置页中通过「重置冷却」按钮或调用 `POST /dsh-ollama/cooldowns/reset` 随时清除冷却状态。

### 模型到账号路由规则

```yaml
modelAccountRules:
  - pattern: "*flash*"
    account: "Work"
```

## 界面与视觉验收

DSH Desktop（暗黑主题）中的 Ollama Cloud 设置与用量面板：

![Ollama Cloud 设置](https://npmcn.com/package/%40goodandready/dsh-ollama-cloud-provider/media/visual-verification.png)

## 常用指令

```bash
/ollama status            # 查看服务商状态、配额与模型数
/ollama usage             # 7 天支出与按模型细分
/ollama balance           # 包含额度与充值额度
/ollama accounts          # 账号池健康与支出
/ollama models            # 模型目录与参数能力
/ollama rules             # 模型到账号规则
/ollama test [model]      # 发送连通性测试请求
```

## 安全说明

-   写入路由要求 loopback 套接字、同源 `Origin`/`Referer` 以及宿主机认证；DNS 名称永远不会被视为 loopback。
-   API 密钥通过 DSH 凭据服务解析；浏览器只能获知是否已配置，无法读取密钥值。
-   自定义端点必须是完整的 `http(s)` 地址，不得包含账号密码或片段；link-local 与 metadata 地址会被拒绝。
-   `/status` 缓存 10 秒；刷新、测试与端点发现路由为单飞并限流。

## 限制与注意事项

-   仅支持 Ollama Cloud 云端模型；不会注册本地 `http://localhost:11434` 路由。
-   云端 API 暂不提供向量嵌入（Embeddings）模型。
-   文件附件以文本句柄（handle）形式转发。
-   `/api/usage` 限制为每分钟 10 次请求，插件已内置本地缓存以确保顺畅使用。
-   完整功能需要 Web 配置文件；TUI 终端环境保留 `/ollama` 命令与模型推理。

## 许可证

MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)。详见 [LICENSE](https://npmcn.com/package/%40goodandready/dsh-ollama-cloud-provider/LICENSE) 与 [NOTICE](https://npmcn.com/package/%40goodandready/dsh-ollama-cloud-provider/NOTICE)。

## 常见问题

### @goodandready/dsh-ollama-cloud-provider 是什么？

Ollama Cloud LLM 为 DeepSeek Harness \(dsh\) 提供插件\.

### 如何安装 @goodandready/dsh-ollama-cloud-provider？

在项目目录运行 npm install @goodandready/dsh-ollama-cloud-provider，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.2\.0）、@deepseek-ai/cordis（~4\.0\.4 \|\| ~4\.0\.5 \|\| ~4\.0\.6-alpha\.1 \|\| ~4\.1\.0）、@deepseek-ai/dsh-llm（0\.2\.0-rc\.2 \|\| \>=0\.2\.1-rc\.2 \<0\.2\.3-0 \|\| \>=0\.2\.2-0 \<0\.2\.3-0）、@deepseek-ai/dsh-web（0\.2\.0-rc\.2 \|\| \>=0\.2\.1-rc\.2 \<0\.2\.3-0 \|\| \>=0\.2\.2-0 \<0\.2\.3-0）、@deepseek-ai/schemastery（~3\.18\.4 \|\| ~3\.18\.5 \|\| ~3\.18\.6-alpha\.1 \|\| ~3\.19\.0）、@deepseek-ai/dsh-commands（0\.2\.0-rc\.2 \|\| \>=0\.2\.1-rc\.2 \<0\.2\.3-0 \|\| \>=0\.2\.2-0 \<0\.2\.3-0）、@deepseek-ai/dsh-settings（0\.2\.0-rc\.2 \|\| \>=0\.2\.1-rc\.2 \<0\.2\.3-0 \|\| \>=0\.2\.2-0 \<0\.2\.3-0）、@deepseek-ai/dsh-attachment（0\.2\.0-rc\.2 \|\| \>=0\.2\.1-rc\.2 \<0\.2\.3-0 \|\| \>=0\.2\.2-0 \<0\.2\.3-0）、@deepseek-ai/dsh-credentials（0\.2\.0-rc\.2 \|\| \>=0\.2\.1-rc\.2 \<0\.2\.3-0 \|\| \>=0\.2\.2-0 \<0\.2\.3-0）、@deepseek-ai/dsh-client-locale（0\.2\.0-rc\.2 \|\| \>=0\.2\.1-rc\.2 \<0\.2\.3-0 \|\| \>=0\.2\.2-0 \<0\.2\.3-0）、@deepseek-ai/dsh-host-webserver（0\.2\.0-rc\.2 \|\| \>=0\.2\.1-rc\.2 \<0\.2\.3-0 \|\| \>=0\.2\.2-0 \<0\.2\.3-0）、@deepseek-ai/dsh-client-ui-slots（0\.2\.0-rc\.2 \|\| \>=0\.2\.1-rc\.2 \<0\.2\.3-0 \|\| \>=0\.2\.2-0 \<0\.2\.3-0）、@deepseek-ai/dsh-client-ui-renderer（0\.2\.0-rc\.2 \|\| \>=0\.2\.1-rc\.2 \<0\.2\.3-0 \|\| \>=0\.2\.2-0 \<0\.2\.3-0）、@deepseek-ai/dsh-client-ui-settings（0\.2\.0-rc\.2 \|\| \>=0\.2\.1-rc\.2 \<0\.2\.3-0 \|\| \>=0\.2\.2-0 \<0\.2\.3-0）、@deepseek-ai/dsh-launch-environment（0\.2\.0-rc\.2 \|\| \>=0\.2\.1-rc\.2 \<0\.2\.3-0 \|\| \>=0\.2\.2-0 \<0\.2\.3-0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @goodandready/dsh-ollama-cloud-provider 支持 TypeScript 吗？

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

### @goodandready/dsh-ollama-cloud-provider 支持 ESM 还是 CommonJS？

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

### @goodandready/dsh-ollama-cloud-provider 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @goodandready/dsh-ollama-cloud-provider 可以商用吗？

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

### @goodandready/dsh-ollama-cloud-provider 的下载量有多少？

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

### @goodandready/dsh-ollama-cloud-provider 还在维护吗？

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

