前言¶

在 DeepSeek Harness（dsh）里接云端模型，常见做法是自己在 llm-pi-ai 里配路由、维护模型列表，并单独处理密钥与用量。若目标是 Ollama Cloud（https://ollama.com/v1），还要对齐 /api/show 返回的能力字段、thinking 档位，以及网关对多模态请求大小的限制。

社区插件 dsh-ollama-cloud（维护者 pei-lin-001，分类：模型推理）把「一把 API Key + 自动目录同步 + 配额与用量展示」收进一条 llm-pi-ai 路由，聊天与工具调用仍由 dsh-llm-pi-ai 走 OpenAI Completions 兼容传输；插件负责目录、凭证和配套 UI。下面介绍它做什么、如何安装，以及使用时需要留意的边界。

这是什么¶

dsh-ollama-cloud 是面向 DeepSeek Harness 的 Ollama Cloud 集成插件：无需在本机安装 Ollama，只需 Ollama 账号的 API Key。启动时、密钥变更时或手动触发时，插件会拉取账号模型目录并写入 llm-pi-ai 的 ollama-cloud 路由，模型出现在选择器里；同时提供设置页、侧栏配额芯片、斜杠命令与同源 HTTP 路由，用于同步目录和查看 5 小时 / 7 天配额与用量。

核心功能¶

模型目录与推理能力映射¶

插件通过 GET /v1/models 取模型 id，再对每个模型 POST /api/show，把结果写成 llm-pi-ai 路由条目：

• capabilities 决定哪些模型启用 tools、vision 与 thinking 集合；默认未声明 tools 的模型不会进入选择器，除非开启 includeNonToolModels。
• <arch>.context_length 映射为 contextWindow。
• thinking.values 映射为 reasoningEfforts：false 对应 off: 'none'（避免空值回落到模型默认，通常为开）；true 对应单一 medium；分级名称（如 xhigh、max）一对一保留。

目录会整体替换该路由下的 models 列表；若某段配置未变化则不会重复写盘。

聊天、工具与托管 Web 能力¶

对话、tools、vision、thinking 由 dsh-llm-pi-ai 处理（api: openai-completions，baseURL: https://ollama.com/v1）。插件额外注册两个工具：ollama_web_search、ollama_web_fetch，分别调用 /api/web_search 与 /api/web_fetch，使用同一 API Key。

配额、用量与本地计量¶

• GET /api/balance 提供 5 小时会话窗口与 7 天周窗口配额。
• GET /api/usage 在当前套餐下可报告 token 与费用；旧套餐仅报告请求数。

对旧套餐，插件还会从本 harness 经 llm/stream 发出的请求里统计 usage 块，按模型、按小时桶累计输入 / 缓存 / 输出，保留 30 天于 $DSH_HOME/ollama-cloud-usage.json，并与 balance 报告的重置时间对齐。其他客户端产生的流量不会进入该本地表；若服务端有数据，以服务端为准。

设置页分四块：连接、配额条、图表、按模型表格。24 小时图为按小时请求数；7 天图在请求与 token 之间切换（因各套餐都返回请求序列）。侧栏底部展示两个配额窗口。界面文案为中文。

多模态请求体积¶

历史中的图片会在每一步重发；Ollama Cloud 在网关层对过大请求返回 413（资料中观测约 12 MB）。插件将单请求内图片 base64 预算控制在 6 MiB 以内：在 0.2.x 上写入路由的 maxRequestImageBytes，由适配器截断并让 harness 卸掉最旧图片后重试；在 0.1.0-rc.x 上适配器无该字段时，由插件自行从 outgoing 请求中丢弃最旧图片。文本不计入该预算。

安装与启用¶

插件以当前 dsh 进程权限运行，安装前请自行审阅 GitHub 仓库 源码与 MIT 许可证。engines.dsh 要求 >=0.1.0-rc.6 <1.0.0；README 记载在 0.1.0-rc.6（CLI）与 0.2.1-rc.2（桌面端捆绑运行时）上做过验证。

按 profile 安装（命令来自官方 README）：

# desktop app profile and/or web profile
dsh plugin --profile desktop add git:github.com/pei-lin-001/dsh-ollama-cloud
dsh plugin --profile web add git:github.com/pei-lin-001/dsh-ollama-cloud

安装后打开 Settings → Ollama Cloud，在 ollama.com/settings/keys 创建 Key 并粘贴，点击 保存并同步。密钥写入凭证服务（$DSH_HOME/.credentials.yaml），不会进入浏览器。目录写入 llm-pi-ai 的 ollama-cloud 路由后，模型出现在选择器中。

进程环境变量 OLLAMA_API_KEY 也可生效；它会覆盖已存储的 Key，且此时凭证服务会拒绝写入。

配置¶

入口配置在 ollama-cloud 设置段，可在 profile patch 中覆盖：

- id: ollama-cloud
  config:
    provider: ollama-cloud        # llm-pi-ai route name
    displayName: Ollama Cloud
    apiKeyRef: OLLAMA_API_KEY     # credential reference, never the secret
    baseURL: https://ollama.com
    syncOnStart: true             # pull the catalog on boot
    includeNonToolModels: false   # keep tool-less models out of the picker
    webTools: true                # register ollama_web_search / ollama_web_fetch
    maxOutputChars: 20000         # per ollama_web_fetch result
    usageCacheSeconds: 120        # /api/balance + /api/usage cache
    maxRequestImageBytes: 6291456 # base64 image budget per request; 0 = adapter default

模型的 contextWindow 来自 /api/show。编写器里模型按钮旁的「上下文」芯片可仅对当前选中模型覆盖上限，选择保存在 $DSH_HOME/ollama-cloud-context.json，并在每次目录同步后叠加；重置则恢复接口报告值。

webTools 与 includeNonToolModels 在工具注册时读取，修改后需重启；客户端侧改动同样需要重启。

典型用法¶

设置页与密钥¶

按上文完成 Key 保存与同步即可。需要仅查状态而不打开完整设置页时，可使用同源路由（见下节）。

斜杠命令¶

/ollama-cloud [status|sync|usage]

默认子命令为 usage。示例输出形态如下（数值为 README 示例，非实测）：

Ollama Cloud 用量：
  会话（5h） ▕█░░░░░░░░░▏ 已用 7.2% · 3 小时后重置
  每周（7d） ▕█░░░░░░░░░▏ 已用 6.4% · 18 小时后重置
  5h 统计：267 次请求 · 输入 8.9k · 输出 127
  7d 统计：1.2k 次请求 · 输入 8.9k · 输出 127

HTTP 路由（同源）¶

设置页与侧栏通过下列路径访问；脚本在同源或受信任的 loopback 场景下也可调用：

POST /key 与 POST /sync 仅允许应用自身页面（同源，或 opaque 的 file:// 源）且 Host 为 loopback 或 IP 字面量；其余来源返回 403。用量接口每用户每分钟 10 次；一次刷新约三次调用，因此结果默认缓存 usageCacheSeconds（120 秒），侧栏约每五分钟轮询。

运行时差异¶

适用场景与注意¶

适合谁： 已在用或打算用 DeepSeek Harness，希望用 Ollama Cloud 账号统一选模型、开 thinking、用托管网页搜索 / 抓取，并在 UI 里看 5h/7d 配额与用量，而不想手维护 llm-pi-ai 模型列表的开发者。

已知限制（摘自 README）：

• 无法从此插件侧可靠限制输出长度：dsh-llm-pi-ai 的兼容探测发送 max_completion_tokens，Ollama 忽略该字段（认 max_tokens），且适配器未暴露对应开关。
• 本地计量仅覆盖本 harness 实例发出的流量；其他机器或其他客户端不会出现在 token 合计里，按小时分桶可能导致窗口边界最多差一小时。
• 目录同步会整体替换 llm-pi-ai.providers.ollama-cloud，对手工改过的路由会丢失；若设 syncOnStart: false，需自行调用同步。
• 用量相关接口有频率限制，依赖缓存与侧栏轮询间隔。

DSH 生态强调「一切皆插件」；SkillHub 目录页 为社区站点，与 DeepSeek / 幻方无官方从属关系。

结尾¶

dsh-ollama-cloud 把 Ollama Cloud 的密钥、模型目录、thinking 档位、托管 Web 工具与配额用量 UI 接到 DeepSeek Harness 的一条标准 llm-pi-ai 路由上，减少手配路由与猜模型能力字段的成本。进一步了解可查看目录页与仓库：

• 目录：https://www.skillhub.cn/plugins/pei-lin-001/dsh-ollama-cloud
• GitHub：https://github.com/pei-lin-001/dsh-ollama-cloud