@goodandready/dsh-ollama-cloud-provider

中文文档
0.1.39发布于 2026/11/16MITTypeScriptES Module零依赖近 30 天下载 9223

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

中文使用文档
文档目录14 节
  1. 面向 DeepSeek Harness 的 Ollama Cloud 模型提供商插件
  2. 架构示意
  3. 功能全貌
  4. Requirements / 系统要求
  5. 安装指南
  6. 配置示例
  7. 密钥配置
  8. 多账号轮换与冷却重置
  9. 模型到账号路由规则
  10. 界面与视觉验收
  11. 常用指令
  12. 安全说明
  13. 限制与注意事项
  14. 许可证

📦 @goodandready/dsh-ollama-cloud-provider

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

GoodAndReady 展厅 npm 版本 许可证

⭐ 如果您喜欢这个插件,请在 GitHub 上为它点亮 Star — 这能让我知道插件对您有用,并鼓励我继续开发和维护它。

🐛 如果您发现 Bug 或希望增加功能,请使用任意语言在 GitHub 上提交 Issue — 我会评估您的建议,并在后续版本中实现有价值的改进。

面向 DeepSeek Harness(dsh)的 Ollama Cloud 模型提供商插件。

插件注册一个原生 LLM 路由 ollama-cloud(https://ollama.com),支持两种底层传输协议:

传输协议端点用途
native(默认)POST /api/chatthinking、工具调用、usage 计数(NDJSON)
openai-chatPOST /v1/chat/completionsOpenAI 兼容部署与备用网关(SSE)

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

架构示意

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 或兼容的代理端点。

安装指南

从源码构建与打包:

npm install
npm run build
npm pack

从 npm 安装已发布版本:

dsh plugin --profile web add @goodandready/[email protected]
# DSH 桌面端:
dsh plugin --profile desktop add @goodandready/[email protected]

或通过打包文件安装:

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 即可。

配置示例

- 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。云端网关仅接受 Authorization: Bearer 请求头。

多账号轮换与冷却重置

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

模型到账号路由规则

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

界面与视觉验收

DSH Desktop(暗黑主题)中的 Ollama Cloud 设置与用量面板:

Ollama Cloud 设置

常用指令

/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。详见 LICENSE 与 NOTICE。

版本与发布记录

@goodandready/dsh-ollama-cloud-provider 共发布 38 个版本,首次发布于 2026/10/22;过去 12 个月发布了 38 个版本。

版本发布日期距今
0.1.39latest2026/11/16今天
0.1.382026/11/124 天前
0.1.372026/11/115 天前
0.1.362026/11/106 天前
0.1.352026/11/097 天前
0.1.342026/11/079 天前

关于 @goodandready/dsh-ollama-cloud-provider 的常见问题

@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 和提交记录判断。