@goodandready/dsh-ollama-cloud-provider 0.0.0-stage → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+## 0.1.2 — 2026-10-21
+
+- Test connection falls back to the reasoning text when a thinking model returns
+  no content, and uses a 64-token budget (#17).
+- Production acceptance of 0.1.1 confirmed chat, catalog and balance; the probe
+  is the only follow-up defect.
+
+## 0.1.1 — 2026-10-21
+
+Audit fixes (Gitea #1–#15):
+
+- A transient transport/timeout/server failure no longer cools down the only
+  configured account; the harness retry policy can recover. Credential and quota
+  rejections still cool the key (#1).
+- Removed the unimplemented `toolUpdate: 'addition-only'` declaration so the
+  model always receives the full tool list (#2).
+- `/dsh-ollama/key` and `/key/clear` only accept this plugin's credential
+  references (`apiKeyEnv`, configured account refs and `OLLAMA_*`) (#3).
+- The sidebar quota card honors `showSidebarQuota`, stays unmounted while the
+  setting is off and stops polling `/state` (#4).
+- The injected stylesheet carries `data-dsh-plugin` so neighbouring plugin
+  cleanup cannot strip it (#5).
+- Analytics uses the shared `estimateCost` implementation and applies
+  `priceOverrides` (#7).
+- Empty catch blocks report through `bestEffortFailed` at debug level (#8).
+- Removed unused modules and exports (`quota-runway`, `requireImages`,
+  `clearAnalyticsCache`, `PLUGIN_PROVIDERS`, `showUrlFor`) (#9).
+- Heatmap and theme values no longer hardcode colors (#10).
+- Test-connection requests disable thinking and use a 32-token budget (#11).
+- The request log is flushed on shutdown (#12).
+- Architecture documentation moved to `docs/design/ARCHITECTURE.md`; the
+  design contract lives in `docs/design/DESIGN.md` (#13).
+- Added wiring, analytics, route-guard and adapter regression tests (#14).
+- Account rows show the 7-day spend without a meaningless percentage (#15).
+
+## 0.1.0
+
+Initial release.
+
+- Registers the `ollama-cloud` provider route for DeepSeek Harness.
+- Native `/api/chat` transport (NDJSON) with thinking, tool calls, images and usage counters.
+- OpenAI-compatible `/v1/chat/completions` transport selectable per model.
+- Live model catalog from `/v1/models` enriched with `/api/tags` capabilities, plus an offline snapshot.
+- Balance from `/api/balance` (credits and legacy percentage windows) and spend from `/api/usage`
+  with 24-hour, 7-day and 30-day windows and per-model groups.
+- Multi-account rotation before the first streamed token, persistent cooldowns, sticky sessions and
+  model → account glob rules.
+- Price estimates including off-peak rates and per-model overrides.
+- Settings page, sidebar quota card, quota/analytics panel with a request heatmap, `/ollama` command,
+  TUI settings section and one-click plugin update.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-opencode-provider contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,15 @@
+dsh-ollama-cloud-provider
+Copyright (c) 2026 GooDAnDReaDY
+
+This product is MIT-licensed (see LICENSE).
+
+Third-party references and attribution:
+
+- The plugin structure, cordis lifecycle wiring, HTTP route guards, request log, analytics reader,
+  quota runway and generic client widgets were adapted from the author's own
+  `@goodandready/dsh-opencode-provider` (MIT).
+- The feature set was informed by `@goodandready/dsh-clinebot` (MIT) and
+  `@mars-sea/dsh-commandcode-provider` (MIT). No vendor code from those packages is bundled.
+- DeepSeek Harness packages (`@deepseek-ai/*`) are host-owned peer dependencies and are not bundled.
+- Ollama Cloud API facts were verified against the public documentation and live endpoints on
+  2026-10-21. Ollama is a trademark of its respective owner; this plugin is unofficial.

package/README.md

@@ -1,3 +1,233 @@
-# Temporary Holding Version
+# 📦 @goodandready/dsh-ollama-cloud-provider
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<div align="center">
+
+<h3>Ollama Cloud LLM Provider for DeepSeek Harness</h3>
+
+<p>
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-ollama-cloud-provider"><img src="https://img.shields.io/npm/v/@goodandready/dsh-ollama-cloud-provider?style=for-the-badge&color=crimson&logo=npm" alt="npm version"></a>
+</p>
+
+</div>
+
+---
+
+Ollama Cloud provider plugin for [DeepSeek Harness](https://deepseek-harness.github.io/deepseek-harness/) (dsh).
+
+It registers one native LLM route, `ollama-cloud`, served by `https://ollama.com`, with two wire protocols:
+
+| Transport | Endpoint | When |
+|---|---|---|
+| `native` (default) | `POST /api/chat` | thinking, tool calls, usage counters |
+| `openai-chat` | `POST /v1/chat/completions` | OpenAI-compatible deployments and fallback |
+
+Requests resolve the key per call, so a changed credential reaches the next request without a restart.
+
+## Architecture
+
+```mermaid
+graph LR
+    subgraph DSH["DeepSeek Harness Core"]
+        Agent["DSH Agent / Chat"]
+        Creds["Credentials / launch env"]
+    end
+
+    subgraph Plugin["dsh-ollama-cloud-provider"]
+        Router{"Route: ollama-cloud"}
+        Pool["Account pool<br/>rotation, cooldowns, sticky"]
+        Catalog["Live catalog<br/>/v1/models + /api/tags"]
+        Usage["Balance & usage<br/>/api/balance + /api/usage"]
+
+        subgraph Transports["Wire protocols"]
+            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
+```
+
+## Features
+
+- **Two wire transports** chosen per model: the native Ollama API (NDJSON) and the OpenAI-compatible gateway (SSE).
+- **Text, thinking, tool calls, images, usage and finish reasons** on both transports.
+- **Live catalog** from `GET /v1/models`, enriched with capability flags from `GET /api/tags`.
+- **Accurate limits** for the dsh picker: context window, input modalities, reasoning levels and their default, tool support, and API visibility.
+- **Balance and usage** from the official `/api/balance` and `/api/usage` endpoints: included credits, purchased credits, 24-hour / 7-day / 30-day spend, and spend by model.
+- **Multi-account rotation** before any content is streamed: 401/403/429 and quota rejections mark a key and retry with the next one. Cooldowns persist across restarts.
+- **Sticky accounts** per conversation, plus model → account glob rules.
+- **Price estimates** from the published Ollama pricing table, including off-peak rates, with per-model overrides.
+- **Browser UI**:
+  - **Settings → Ollama Cloud**: key, balance, accounts, rules, model allowlist, per-model transport, connection settings.
+  - **Sidebar quota card** (off by default, and it does not poll `/state` while disabled): a ring with the highest used window and rows with remaining credits or legacy windows.
+  - **Center quota panel**: spend windows, spend by model, accounts, routing trace, usage analytics and a request heatmap.
+- **`/ollama` command** for status, usage, balance, accounts, models, rules and `test [model]`.
+- **TUI settings section** for terminal profiles.
+- **One-click plugin update** in Settings → Ollama Cloud.
+
+## Install
+
+Build and pack first:
+
+```bash
+npm install
+npm run build
+npm pack
+```
+
+Install the packed tarball into a profile:
+
+```bash
+dsh plugin --profile web add /absolute/path/to/goodandready-dsh-ollama-cloud-provider-0.1.0.tgz
+# DSH Desktop:
+dsh plugin --profile desktop add /absolute/path/to/goodandready-dsh-ollama-cloud-provider-0.1.0.tgz
+```
+
+Restart dsh (or DSH Desktop), then pick **Ollama Cloud** in the model picker.
+
+> **Use the tarball, not the directory.** On dsh 0.2.1-rc.2 the Desktop CLI aliases a local
+> directory passed to `dsh plugin add` and overwrites the target's `package.json`.
+
+## Configure
+
+```yaml
+- id: llm-ollama-cloud
+  name: "@goodandready/dsh-ollama-cloud-provider"
+  config:
+    apiKeyEnv: OLLAMA_API_KEY      # default
+    # apiKey: ...                  # composition only, never commit
+    transport: native              # native | openai-chat
+    requestTimeoutMs: 300000
+    streamIdleTimeoutMs: 300000
+    visibleModels: []
+    modelTransports: {}
+    # contextWindowOverrides: { "gpt-oss:120b": 131072 }
+    # maxOutputTokens: 32768
+    accounts:
+      - label: Work
+        apiKeyEnv: OLLAMA_API_KEY_2
+    activeAccount: ''              # label or credential name to pin
+    stickySession: true
+    showSidebarQuota: false
+```
+
+Every field except `apiKey` is volatile and appears in dsh settings.
+
+### Keys
+
+1. `config.apiKey` (composition only, `role('secret')`).
+2. The dsh credential seam under `apiKeyEnv` (default `OLLAMA_API_KEY`).
+3. The launch environment (process, project `.env`, `$DSH_HOME/.env`).
+
+Create a key at <https://ollama.com/settings/keys>. Keys do not expire; `x-api-key` is **not** accepted, only `Authorization: Bearer`.
+
+### Accounts and rotation
+
+Add a second account in **Settings → Ollama Cloud → Accounts**: give it a name and a credential reference (for example `OLLAMA_API_KEY_2`), paste its key, then Save. The default account always serves first unless `activeAccount` pins another one.
+
+Rotation happens **before any content is streamed**. When the serving key is rejected with an invalid credential, a rate limit or an exhausted quota, the adapter marks that key and retries the same request with the next usable account. A request that already started streaming is not replayed. Cooldowns are stored in `~/.dsh/storages/dsh-ollama/cooldowns.json` keyed by a SHA-256 fingerprint — raw keys are never written.
+
+### Model → account rules
+
+Pin a model to a preferred account with a glob. The first matching rule wins; `*` and `?` are supported and matching is case-insensitive. Other accounts remain fallbacks.
+
+```yaml
+modelAccountRules:
+  - pattern: "*flash*"
+    account: "Work"
+```
+
+## Balance and usage
+
+The plugin uses the documented cloud endpoints:
+
+- `GET /api/balance` → `included.balance_usd` / `included.allowance_usd` / `included.period` and `purchased.balance_usd`. Legacy accounts return `included.session.remaining_percent` and `included.weekly.remaining_percent`; both formats are displayed.
+- `GET /api/usage?range=24h|7d|30d&group_by=model` → totals and per-model groups with request count, USD, input, cached input and output tokens.
+
+`/api/usage` is limited to **10 requests per minute per user**, so the reader caches each range (balance 60 s, usage 120 s, failures 30 s) and never polls in the background. Quota failures are fail-open: chat never depends on them.
+
+## Settings page
+
+Open **Settings → Ollama Cloud**:
+
+- **Key** — status, paste a key, clear it, run **Test connection** against a chosen model. The probe disables thinking so the reply is visible.
+- **Balance and usage** — credit bar or legacy windows, spend windows, warning at 80 % and exhausted at 95 %.
+- **Accounts** — extra keys, per-account spend, pin, remove, set a key.
+- **Model → account rules** — glob rules.
+- **Routing** — sticky session per conversation.
+- **Models** — search, refresh the live catalog, hide models, override the wire transport per model, see price, context and capabilities.
+- **Connection** — native and OpenAI bases, usage and balance endpoints, transport, timeouts, output cap and context override.
+- **Sidebar** — show or hide the quota card.
+- **Plugin update** — current/latest version and **Update now**.
+
+The Host serves `/dsh-ollama/state`, `/health`, `/analytics`, `/usage`, `/balance`, `/config`, `/key`, `/key/clear`, `/refresh`, `/models/refresh`, `/test` and `/update`. Writes require JSON, are refused for cross-origin requests, and are restricted to loopback (`127.0.0.1` / `::1`).
+
+## Command
+
+```
+/ollama status            # provider, accounts, quota and model count
+/ollama usage             # 7-day spend windows and spend by model
+/ollama balance           # included and purchased credits
+/ollama accounts          # labels, source, active/cooling, 7-day spend
+/ollama models            # ids, price, context, capabilities
+/ollama rules             # model → account rules
+/ollama test [model]      # minimal real request, default gpt-oss:120b
+```
+
+## Verified API facts
+
+Checked live on 2026-10-21:
+
+- `GET https://ollama.com/v1/models` is public and returns `data[]` plus a non-standard `models[]` array carrying `context_window`, `max_context_window`, `input_modalities`, `supported_reasoning_levels`, `default_reasoning_level`, `visibility` and `supported_in_api`.
+- `GET https://ollama.com/api/tags` is public and is the only per-model source of `capabilities` (`completion`, `tools`, `thinking`, `vision`).
+- The live catalog returned 23 cloud models.
+- Native `/api/chat` streams NDJSON and reports `prompt_eval_count`, `prompt_eval_cached_count`, `eval_count` and `done_reason` in the final line.
+- OpenAI `/v1/chat/completions` supports streaming, tools, vision, `reasoning_effort` and `stream_options.include_usage`.
+- Anthropic compatibility (`/v1/messages`) exists but is partial; this plugin does not use it.
+
+## Development
+
+```bash
+npm run typecheck
+npm test
+npm run build
+npm run check         # typecheck + tests + build
+npm run release       # check + packed tarball
+node scripts/probe.mjs
+```
+
+`scripts/probe.mjs` is read-only against the public catalog; with `OLLAMA_API_KEY` set it also probes chat, balance and usage and prints the raw shapes.
+
+## Visual verification
+
+The Ollama Cloud settings page in DSH Desktop (dark theme): configured
+credential, balance and usage, and the connection probe.
+
+![Ollama Cloud settings](media/visual-verification.png)
+
+## Limitations
+
+- **Cloud only.** Local `http://localhost:11434` is not registered as a route.
+- Embeddings are not exposed: no cloud model in the live catalog advertises the `embedding` capability.
+- File attachments are forwarded as deterministic handle text, not inline bytes.
+- The usage endpoint is limited to 10 requests per minute; caches and the UI account for that.
+- Cost values are estimates from the published table (including off-peak rates); the gateway is the authority.
+- Automatic update requires the DSH CLI entry in the runtime.
+- The UI requires a web profile; the TUI keeps the `/ollama` command and the model route.
+
+## License
+
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY). See [LICENSE](./LICENSE) and [NOTICE](./NOTICE).

package/README.ru.md

@@ -0,0 +1,131 @@
+# 📦 @goodandready/dsh-ollama-cloud-provider
+
+Провайдер **Ollama Cloud** для DeepSeek Harness (dsh).
+
+Плагин регистрирует один маршрут `ollama-cloud` (`https://ollama.com`) и два протокола:
+
+| Транспорт | Endpoint | Когда используется |
+|---|---|---|
+| `native` (по умолчанию) | `POST /api/chat` | thinking, вызовы инструментов, счётчики usage |
+| `openai-chat` | `POST /v1/chat/completions` | OpenAI-совместимые развёртывания и запасной путь |
+
+Ключ разрешается на каждый запрос, поэтому смена credential применяется без перезапуска.
+
+## Возможности
+
+- Два транспорта, выбираемые по модели.
+- Текст, reasoning/thinking, tool calls, изображения, usage и finish reasons.
+- Живой каталог из `GET /v1/models`, дополненный `capabilities` из `GET /api/tags`.
+- Точные метаданные для picker: контекст, модальности, уровни reasoning и уровень по умолчанию, поддержка инструментов, видимость в API.
+- Баланс и расход из официальных `/api/balance` и `/api/usage`: включённые и купленные кредиты, расход за 24 часа / 7 дней / 30 дней, расход по моделям.
+- Мультиаккаунт с ротацией **до первого токена** на 401/403/429 и исчерпанную квоту; cooldown'ы сохраняются между перезапусками.
+- Липкий аккаунт на диалог и правила `модель → аккаунт` по glob.
+- Оценка стоимости по published-тарифу Ollama, включая off-peak, с ручными overrides.
+- UI: страница **Настройки → Ollama Cloud**, карточка квоты в сайдбаре (по умолчанию выключена и не опрашивает `/state`, пока выключена), панель с расходом, аналитикой и heatmap.
+- Команда `/ollama`, секция TUI и обновление плагина в один клик.
+
+## Установка
+
+```bash
+npm install
+npm run build
+npm pack
+dsh plugin --profile web add /absolute/path/to/goodandready-dsh-ollama-cloud-provider-0.1.0.tgz
+# DSH Desktop:
+dsh plugin --profile desktop add /absolute/path/to/goodandready-dsh-ollama-cloud-provider-0.1.0.tgz
+```
+
+После установки перезапустите dsh и выберите **Ollama Cloud** в списке моделей.
+
+## Настройка
+
+```yaml
+- id: llm-ollama-cloud
+  name: "@goodandready/dsh-ollama-cloud-provider"
+  config:
+    apiKeyEnv: OLLAMA_API_KEY
+    transport: native            # native | openai-chat
+    requestTimeoutMs: 300000
+    streamIdleTimeoutMs: 300000
+    visibleModels: []
+    accounts:
+      - label: Work
+        apiKeyEnv: OLLAMA_API_KEY_2
+    activeAccount: ''
+    stickySession: true
+    showSidebarQuota: false
+```
+
+Все поля, кроме `apiKey`, доступны в настройках DSH.
+
+### Ключи
+
+1. `config.apiKey` — только в composition, `role('secret')`.
+2. Credential-сервис по имени `apiKeyEnv` (по умолчанию `OLLAMA_API_KEY`).
+3. Переменные окружения запуска.
+
+Ключ создаётся на <https://ollama.com/settings/keys>, не истекает. Принимается только `Authorization: Bearer`; `x-api-key` cloud отклоняет.
+
+### Аккаунты и ротация
+
+Дополнительный аккаунт добавляется в **Настройки → Ollama Cloud → Аккаунты**: имя + ссылка на credential (например `OLLAMA_API_KEY_2`), затем ключ и «Сохранить». Ротация происходит до стриминга: отклонённый ключ получает cooldown, запрос повторяется следующим ключом. Cooldown'ы лежат в `~/.dsh/storages/dsh-ollama/cooldowns.json` и хранятся по SHA-256 fingerprint — сырые ключи не пишутся.
+
+### Правила модель → аккаунт
+
+```yaml
+modelAccountRules:
+  - pattern: "*flash*"
+    account: "Work"
+```
+
+Первый совпавший glob ставит аккаунт первым; остальные остаются fallback.
+
+## Баланс и расход
+
+- `GET /api/balance` — новый формат (`included.balance_usd`, `allowance_usd`, `period`, `purchased.balance_usd`) и legacy-формат (`session` / `weekly` с `remaining_percent`). Поддерживаются оба.
+- `GET /api/usage?range=24h|7d|30d&group_by=model` — totals и группы по моделям.
+
+У `/api/usage` лимит **10 запросов в минуту на пользователя**, поэтому баланс кэшируется на 60 с, usage — на 120 с, ошибки — на 30 с. Фонового опроса нет. Недоступность квот не блокирует чат.
+
+## Команда
+
+```
+/ollama status
+/ollama usage
+/ollama balance
+/ollama accounts
+/ollama models
+/ollama rules
+/ollama test [model]
+```
+
+## Проверенные факты API (2026-10-21)
+
+- `GET https://ollama.com/v1/models` публичный и, кроме стандартного `data[]`, отдаёт нестандартный `models[]` с контекстом, модальностями, уровнями reasoning, `visibility` и `supported_in_api`.
+- `GET https://ollama.com/api/tags` публичный и единственный источник `capabilities` по моделям.
+- Live-каталог вернул 23 облачные модели.
+- Нативный `/api/chat` — NDJSON, счётчики и `done_reason` в финальной строке.
+- OpenAI `/v1/chat/completions` поддерживает стриминг, tools, vision, `reasoning_effort` и `include_usage`.
+- Anthropic-совместимость (`/v1/messages`) частичная и плагином не используется.
+
+## Разработка
+
+```bash
+npm run typecheck
+npm test
+npm run build
+npm run check
+node scripts/probe.mjs
+```
+
+## Ограничения
+
+- Только Ollama Cloud; локальный `http://localhost:11434` не регистрируется.
+- Embeddings не поддерживаются: ни одна облачная модель не объявляет capability `embedding`.
+- Файловые вложения передаются текстовыми handle-заглушками, не байтами.
+- Стоимость — оценка по опубликованному тарифу; финальным авторитетом остаётся gateway.
+- UI требует web-профиль; в TUI остаются команда `/ollama` и маршрут модели.
+
+## Лицензия
+
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY). См. [LICENSE](./LICENSE) и [NOTICE](./NOTICE).

package/README.zh.md

@@ -0,0 +1,131 @@
+# 📦 @goodandready/dsh-ollama-cloud-provider
+
+DeepSeek Harness（dsh）的 **Ollama Cloud** 模型提供方插件。
+
+插件注册一个路由 `ollama-cloud`（`https://ollama.com`），支持两种传输协议：
+
+| 传输 | 端点 | 用途 |
+|---|---|---|
+| `native`（默认） | `POST /api/chat` | thinking、工具调用、usage 计数 |
+| `openai-chat` | `POST /v1/chat/completions` | OpenAI 兼容部署与回退 |
+
+密钥在每次请求时解析，更换凭据无需重启。
+
+## 功能
+
+- 按模型选择两种传输协议。
+- 文本、thinking、工具调用、图像、usage 和结束原因。
+- 从 `GET /v1/models` 读取实时模型目录，并用 `GET /api/tags` 的 `capabilities` 补充能力。
+- 模型选择器中的准确元数据：上下文窗口、输入模态、推理等级及默认值、工具支持、API 可见性。
+- 从官方 `/api/balance` 和 `/api/usage` 读取余额与用量：包含额度、购买额度、24 小时 / 7 天 / 30 天支出、按模型支出。
+- 多账号轮换在**首个 token 之前**完成：401/403/429 与配额耗尽会标记密钥并切换到下一个。冷却状态重启后保留。
+- 每个会话的粘性账号，以及 `模型 → 账号` 的 glob 规则。
+- 按 Ollama 公开价目表估算费用，包含 off-peak 价格，并支持按模型覆盖。
+- 浏览器界面：**设置 → Ollama Cloud**、侧边栏配额卡片（默认关闭，关闭时不会轮询 `/state`）、含用量分析、热力图和路由记录的中央面板。
+- `/ollama` 命令、TUI 设置区、一键插件更新。
+
+## 安装
+
+```bash
+npm install
+npm run build
+npm pack
+dsh plugin --profile web add /absolute/path/to/goodandready-dsh-ollama-cloud-provider-0.1.0.tgz
+# DSH Desktop:
+dsh plugin --profile desktop add /absolute/path/to/goodandready-dsh-ollama-cloud-provider-0.1.0.tgz
+```
+
+重启 dsh，然后在模型列表中选择 **Ollama Cloud**。
+
+## 配置
+
+```yaml
+- id: llm-ollama-cloud
+  name: "@goodandready/dsh-ollama-cloud-provider"
+  config:
+    apiKeyEnv: OLLAMA_API_KEY
+    transport: native            # native | openai-chat
+    requestTimeoutMs: 300000
+    streamIdleTimeoutMs: 300000
+    visibleModels: []
+    accounts:
+      - label: Work
+        apiKeyEnv: OLLAMA_API_KEY_2
+    activeAccount: ''
+    stickySession: true
+    showSidebarQuota: false
+```
+
+除 `apiKey` 外的所有字段都是 volatile，可直接在 dsh 设置中编辑。
+
+### 密钥
+
+1. `config.apiKey`：仅用于 composition，`role('secret')`。
+2. dsh 凭据服务中的 `apiKeyEnv`（默认 `OLLAMA_API_KEY`）。
+3. 启动环境变量。
+
+在 <https://ollama.com/settings/keys> 创建密钥，密钥不会过期。云端只接受 `Authorization: Bearer`，不接受 `x-api-key`。
+
+### 账号与轮换
+
+在 **设置 → Ollama Cloud → 账号** 中添加账号：填写名称与凭据引用（如 `OLLAMA_API_KEY_2`），粘贴密钥并保存。轮换发生在流式输出之前；被拒绝的密钥进入冷却，请求由下一个可用密钥继续。冷却信息保存在 `~/.dsh/storages/dsh-ollama/cooldowns.json`，仅使用 SHA-256 指纹，不写入原始密钥。
+
+### 模型 → 账号规则
+
+```yaml
+modelAccountRules:
+  - pattern: "*flash*"
+    account: "Work"
+```
+
+第一个匹配的 glob 优先使用指定账号，其余账号仍作后备。
+
+## 余额与用量
+
+- `GET /api/balance`：新格式（`included.balance_usd`、`allowance_usd`、`period`、`purchased.balance_usd`）与旧格式（`session` / `weekly` 的 `remaining_percent`）均支持。
+- `GET /api/usage?range=24h|7d|30d&group_by=model`：总计与按模型分组。
+
+`/api/usage` 限制为**每位用户每分钟 10 次请求**，因此余额缓存 60 秒、用量缓存 120 秒、失败缓存 30 秒，不做后台轮询。配额不可用不影响聊天。
+
+## 命令
+
+```
+/ollama status
+/ollama usage
+/ollama balance
+/ollama accounts
+/ollama models
+/ollama rules
+/ollama test [model]
+```
+
+## 已验证的 API 事实（2026-10-21）
+
+- `GET https://ollama.com/v1/models` 公开，除标准 `data[]` 外还返回非标准 `models[]`，包含上下文、模态、推理等级、`visibility` 和 `supported_in_api`。
+- `GET https://ollama.com/api/tags` 公开，是按模型获取 `capabilities` 的唯一来源。
+- 实时目录返回 23 个云端模型。
+- 原生 `/api/chat` 使用 NDJSON，最后一行包含计数与 `done_reason`。
+- OpenAI `/v1/chat/completions` 支持流式、工具、图像、`reasoning_effort` 与 `include_usage`。
+- Anthropic 兼容接口（`/v1/messages`）仅部分支持，本插件未使用。
+
+## 开发
+
+```bash
+npm run typecheck
+npm test
+npm run build
+npm run check
+node scripts/probe.mjs
+```
+
+## 限制
+
+- 仅支持 Ollama Cloud；不注册本地 `http://localhost:11434`。
+- 不支持 embeddings：实时目录中没有模型声明 `embedding` 能力。
+- 文件附件以确定的文本句柄传递，而不是内联字节。
+- 费用为公开价目表的估算值，最终以网关为准。
+- UI 需要 web profile；TUI 保留 `/ollama` 命令与模型路由。
+
+## 许可证
+
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)。参见 [LICENSE](./LICENSE) 与 [NOTICE](./NOTICE)。

package/cordis.patch.yml

@@ -0,0 +1,11 @@
+# dsh-ollama-cloud-provider bundle layer.
+# Registers the `ollama-cloud` provider route. All fields are optional —
+# schema defaults apply.
+#
+# `name` must be the FULL package specifier as installed in the profile's
+# node_modules. Quote it: an unquoted YAML scalar starting with `@` fails.
+- insert:
+    - id: llm-ollama-cloud
+      name: "@goodandready/dsh-ollama-cloud-provider"
+      config:
+        apiKeyEnv: OLLAMA_API_KEY