dsh-plugin-guide 0.3.42 → 0.4.0

package/references/official-docs/docs/user/guide/plugin-market.md

@@ -1,148 +0,0 @@
-# Plugin markets
-
-English | [中文](plugin-market.zh.md)
-
-## Summary
-
-A plugin market is one JSON index file that lists installable DSH bundles with their titles, icons, authors, and versions. Turn on the experimental **Custom plugin markets** bundle to browse markets in a **Discover** tab on the Plugins page and install a listed version after a confirmation. To publish a market, write or generate an index file and serve it, together with its icon files, from any static host.
-
-## Table of Contents
-
-- [Turn on Discover](#turn-on)
-- [Browse and install](#browse-and-install)
-- [Publish an index](#publish-an-index)
-- [Generate an index with the reference generator](#generate-an-index)
-- [Index format reference](#index-format)
-- [Further Exploration](#further-exploration)
-
-<a id="turn-on"></a>
-## Turn on Discover
-
-Open **Plugins**, select **More** beside **Experimental plugins**, find **Custom plugin markets**, and switch it on. A **Discover** tab appears next to **Installed**, and Creator mode gains the read-only `plugin_market` tool. Switching the bundle off removes both again.
-
-DSH ships no index source. Select **Discover**, choose **Add index source**, and enter the URL of an index file. A URL must use `http:` or `https:` and must not contain a user name, password, or `#` fragment. Anyone on the network path can change an `http:` index, including the install specs it lists, so use `https:` for a market reached over a network you do not control. Each source belongs to the current profile.
-
-<a id="browse-and-install"></a>
-## Browse and install
-
-The market menu at the left of the toolbar switches between sources and opens **Manage index sources…**, where each source shows its last error. Search matches names, authors, keywords, and titles, descriptions, categories, and labels in every language, and tolerates typos; results come in best-match order until you choose another. The **Labels** menu, category pills, and **Sort** menu use the categories, labels, and sort keys that the market declares, and **Publish date** sorts by each plugin's latest version.
-
-Each card shows the plugin's recommended version: the highest version compatible with the running DSH that is not a prerelease, or the highest compatible prerelease when the plugin lists no version without a prerelease tag. **Install** opens a confirmation with that version's source: the npm package and registry, or the Git repository, commit, and directory. Confirming starts the normal plugin installation, including its compatibility and registry checks; nothing is installed without that confirmation.
-
-Select a card to open its page. The **Versions** list shows every listed version with its compatibility and offers **Install** for any version DSH accepts, including older releases and prereleases. A card that shows **Installed**, **Update available**, or **Provided by DSH** opens the installed bundle instead.
-
-Markets are third-party content. A market chooses each plugin's title, description, icon, author, and source; DSH checks the file format but not those claims. Add only sources you trust, and check the source in the confirmation before installing.
-
-<a id="publish-an-index"></a>
-## Publish an index
-
-An index is a UTF-8 JSON file, at most 128 MiB by default, served with a 2xx status and without redirects. Put it on any static host, for example GitLab Pages, GitHub Pages, or an object store behind https.
-
-Icons can be inline or separate files. An inline icon is a base64 `data:` URL in the index; it needs no extra request but makes the index larger. A separate icon is a URL. A relative icon resolves against the index URL, the way an image in a web page resolves against the page: for an index at `https://market.example/dsh/index.json`, `"icon": "icons/foo.svg"` loads `https://market.example/dsh/icons/foo.svg`. Publishing the index and an `icons/` directory side by side therefore works on any host without editing the file. An absolute icon URL on another origin (scheme, host, and port) must use `https:`.
-
-This is a minimal index with one npm plugin and one plugin from a Git monorepo:
-
-```json
-{
-  "format": 1,
-  "title": { "en": "Team plugins", "zh": "团队插件" },
-  "plugins": [
-    {
-      "name": "dsh-plugin-foo",
-      "title": "Foo",
-      "description": "Adds the foo tool",
-      "icon": "icons/foo.svg",
-      "author": "Jane Doe",
-      "homepage": "https://github.com/jane/dsh-plugin-foo#readme",
-      "repository": { "url": "https://github.com/jane/dsh-plugin-foo" },
-      "versions": [
-        { "version": "1.1.0", "publishTimestamp": 1790476800, "source": { "type": "npm" }, "engines": { "dsh": ">=0.2.0-rc.2" } },
-        { "version": "1.0.0", "publishTimestamp": 1788000000, "source": { "type": "npm" } }
-      ]
-    },
-    {
-      "name": "@team/dsh-bar",
-      "versions": [
-        {
-          "version": "0.3.0",
-          "publishTimestamp": 1789000000,
-          "source": {
-            "type": "git",
-            "url": "https://gitlab.example.com/team/dsh-plugins",
-            "commit": "3f9c2e1d8a4b6c0e7f1a2b3c4d5e6f708192a3b4",
-            "path": "packages/bar"
-          }
-        }
-      ]
-    }
-  ]
-}
-```
-
-DSH rejects the whole index when any rule below is violated and shows the reason, with the JSON path of the offending value, under the source in **Manage index sources…**.
-
-<a id="generate-an-index"></a>
-## Generate an index with the reference generator
-
-The repository includes a [reference generator](../../../apps/plugin-market-generator/README.md) that builds an index from a plain list. Write one npm package name or https Git repository URL per line; blank lines and lines starting with `#` are ignored:
-
-```text
-@team/dsh-foo
-https://gitlab.example.com/team/dsh-plugins
-```
-
-Run it from a DSH checkout:
-
-```sh
-pnpm --filter @deepseek-ai/dsh-plugin-market-generator start --input plugins.txt --output site/index.json --title "Team plugins"
-```
-
-For an npm package, the index lists every version that is not deprecated and declares `dsh.bundle`. For a Git repository, it finds the bundle packages on the default branch and lists their versions at `vX.Y.Z`, `X.Y.Z`, and `<name>@X.Y.Z` tags, plus each package's version on the default branch. Titles, descriptions, icons, authors, and homepages come from each plugin's highest version. Paths are relative to the directory where you run pnpm.
-
-The generator only downloads and reads files; it never installs packages or runs their code. It keeps a cache in `.plugin-market-cache` next to the list, so a repeated run downloads only new versions and commits. Publish the output directory, `index.json` together with its `icons/` directory, as described above.
-
-<a id="index-format"></a>
-## Index format reference
-
-Text fields marked `LocalizedText` are a string or an object of strings keyed by lowercase language ids, such as `{ "en": "Foo", "zh": "甲" }`; an object must contain `en`. Members DSH does not know are ignored.
-
-| Index field | Required | Meaning |
-|---|---|---|
-| `format` | yes | `1`. |
-| `title`, `description` | `title` only | Market name and description, `LocalizedText`. |
-| `metadata.categories`, `metadata.labels` | no | Objects mapping an id to `{ "title": LocalizedText }`. |
-| `metadata.sortKeys` | no | Object mapping an id to `{ "title": LocalizedText, "order": "asc" \| "desc" }`; `order` is the initial direction. |
-| `plugins` | yes | Plugins in the market's default order. |
-
-| Plugin field | Required | Meaning |
-|---|---|---|
-| `name` | yes | npm package name, unique in the index. |
-| `title`, `description` | no | `LocalizedText`; the card shows `name` without a title. |
-| `icon` | no | Inline `data:` URL (SVG, PNG, JPEG, or WebP, at most 32 KiB) or URL, as described above. |
-| `author` | no | Display text. |
-| `homepage` | no | Absolute `https:` or `http:` URL of a page about the plugin; the plugin page links it. |
-| `repository` | no | `{ "url": string, "directory"?: string }`: the source repository's web page, and the package directory inside it. The plugin page links it as **Source code**. |
-| `metadata.category` | no | One declared category id. |
-| `metadata.labels` | no | Declared label ids. |
-| `metadata.sortKeys` | no | Object mapping declared sort-key ids to numbers, such as downloads or ratings. |
-| `versions` | yes | At least one version, in any order. |
-
-| Version field | Required | Meaning |
-|---|---|---|
-| `version` | yes | Exact SemVer version, unique within the plugin. |
-| `publishTimestamp` | yes | Publish time in Unix seconds. |
-| `source` | yes | `{ "type": "npm", "registry"?: url }`, or `{ "type": "git", "url": https-url, "commit": 40-hex-sha, "path"?: directory }`. |
-| `engines.dsh` | no | SemVer range of DSH versions this version runs on; absent means any. |
-
-DSH installs an npm version as `name@version`, asking `registry` first when present, and a Git version as `git+<url>.git#<commit>` with `&path:/<path>` for a package in a subdirectory. `engines.dsh` should match the package's own `engines.dsh`, which DSH checks again at installation; a package without one is checked against its `@deepseek-ai/dsh*` peer dependencies instead. The [format note](../../../.agents/notes/implemented/feature/2026-10-02-plugin-market-index-format.md) defines every rule.
-
-<a id="further-exploration"></a>
-## Further Exploration
-
-- [Discover tab reference](../../../packages/client/ui-plugin-market/README.md) describes the tab's controls and states.
-- [Plugin market service](../../../packages/boot/plugin-market/README.md) covers fetch limits, caching, and the `plugin_market` tool.
-- [Index validator](../../../packages/util/plugin-market-index/README.md) is the library generators can use to check an index before publishing it.
-
-## Dev Note
-
-None.

package/references/official-docs/docs/user/guide/plugin-market.zh.md

@@ -1,148 +0,0 @@
-# 插件市场
-
-[English](plugin-market.md) | 中文
-
-## 概述
-
-插件市场是一个 JSON 索引文件，列出可安装的 DSH 组合包（bundle）及其标题、图标、作者和版本。打开实验性的**自定义插件市场**组合包后，可以在插件页的**发现**标签页中浏览市场，并在确认后安装列出的版本。要发布市场，编写或生成一个索引文件，并把它和图标文件一起放到任意静态主机上。
-
-## 目录
-
-- [打开「发现」](#turn-on)
-- [浏览和安装](#browse-and-install)
-- [发布索引](#publish-an-index)
-- [用参考生成器生成索引](#generate-an-index)
-- [索引格式参考](#index-format)
-- [延伸阅读](#further-exploration)
-
-<a id="turn-on"></a>
-## 打开「发现」
-
-打开**插件**，点击**实验性插件**旁的**更多**，找到**自定义插件市场**并打开开关。**已安装**旁边会出现**发现**标签页，Creator 模式也会获得只读的 `plugin_market` 工具。关闭该组合包会再次移除这两者。
-
-DSH 不内置任何索引源。选择**发现**，点击**添加索引源**，输入一个索引文件的 URL。URL 必须使用 `http:` 或 `https:`，并且不能包含用户名、密码或 `#` 片段。网络路径上的任何人都能修改 `http:` 索引，包括其中列出的安装 spec，因此经由不受你控制的网络访问的市场应使用 `https:`。每个索引源属于当前 profile。
-
-<a id="browse-and-install"></a>
-## 浏览和安装
-
-工具栏左侧的市场菜单用于切换索引源，并可打开**管理索引源…**，其中每个索引源显示它最近一次的错误。搜索匹配名称、作者、关键词，以及所有语言的标题、描述、分类和标签，并容忍拼写错误；在你选择其他排序之前，结果按最佳匹配排序。**标签**菜单、分类按钮和**排序**菜单使用市场声明的分类、标签和排序键，**发布时间**按每个插件最新版本的时间排序。
-
-每张卡片显示插件的推荐版本：与当前运行的 DSH 兼容、且不是预发布版本的最高版本；插件没有列出任何非预发布版本时，则是兼容的最高预发布版本。**安装**会打开确认框，显示该版本的来源：npm 包和注册表，或 Git 仓库、提交和目录。确认后开始常规的插件安装，包括其中的兼容性检查和注册表检查；未经确认不会安装任何内容。
-
-选择卡片会打开插件页面。**版本**列表显示列出的每个版本及其兼容性，并为 DSH 接受的任何版本提供**安装**，包括旧版本和预发布版本。显示**已安装**、**有新版本**或**随 DSH 提供**的卡片会改为打开已安装的组合包。
-
-市场是第三方内容。每个插件的标题、描述、图标、作者和来源都由市场决定；DSH 检查文件格式，但不验证这些声明。只添加你信任的索引源，并在安装前核对确认框中的来源。
-
-<a id="publish-an-index"></a>
-## 发布索引
-
-索引是 UTF-8 编码的 JSON 文件，默认不超过 128 MiB，以 2xx 状态码返回且不经过重定向。把它放到任意静态主机上即可，例如 GitLab Pages、GitHub Pages，或通过 https 访问的对象存储。
-
-图标可以内联，也可以是单独的文件。内联图标是索引中的 base64 `data:` URL；它不需要额外请求，但会使索引变大。单独的图标是一个 URL。相对图标相对于索引 URL 解析，与网页中的图片相对于页面解析的方式相同：对于位于 `https://market.example/dsh/index.json` 的索引，`"icon": "icons/foo.svg"` 会加载 `https://market.example/dsh/icons/foo.svg`。因此把索引和 `icons/` 目录并排发布，在任何主机上都能使用，无需修改文件。指向其他源（协议、主机和端口）的绝对图标 URL 必须使用 `https:`。
-
-下面是一个最小的索引，包含一个 npm 插件和一个来自 Git monorepo 的插件：
-
-```json
-{
-  "format": 1,
-  "title": { "en": "Team plugins", "zh": "团队插件" },
-  "plugins": [
-    {
-      "name": "dsh-plugin-foo",
-      "title": "Foo",
-      "description": "Adds the foo tool",
-      "icon": "icons/foo.svg",
-      "author": "Jane Doe",
-      "homepage": "https://github.com/jane/dsh-plugin-foo#readme",
-      "repository": { "url": "https://github.com/jane/dsh-plugin-foo" },
-      "versions": [
-        { "version": "1.1.0", "publishTimestamp": 1790476800, "source": { "type": "npm" }, "engines": { "dsh": ">=0.2.0-rc.2" } },
-        { "version": "1.0.0", "publishTimestamp": 1788000000, "source": { "type": "npm" } }
-      ]
-    },
-    {
-      "name": "@team/dsh-bar",
-      "versions": [
-        {
-          "version": "0.3.0",
-          "publishTimestamp": 1789000000,
-          "source": {
-            "type": "git",
-            "url": "https://gitlab.example.com/team/dsh-plugins",
-            "commit": "3f9c2e1d8a4b6c0e7f1a2b3c4d5e6f708192a3b4",
-            "path": "packages/bar"
-          }
-        }
-      ]
-    }
-  ]
-}
-```
-
-违反下列任何一条规则时，DSH 会拒绝整个索引，并在**管理索引源…**中该索引源下方显示原因及违规值的 JSON 路径。
-
-<a id="generate-an-index"></a>
-## 用参考生成器生成索引
-
-仓库包含一个[参考生成器](../../../apps/plugin-market-generator/README.zh.md)，可以从一份纯文本列表构建索引。每行写一个 npm 包名或 https Git 仓库 URL；空行和以 `#` 开头的行会被忽略：
-
-```text
-@team/dsh-foo
-https://gitlab.example.com/team/dsh-plugins
-```
-
-在 DSH 代码仓库中运行它：
-
-```sh
-pnpm --filter @deepseek-ai/dsh-plugin-market-generator start --input plugins.txt --output site/index.json --title "Team plugins"
-```
-
-对于 npm 包，索引列出所有未弃用且声明了 `dsh.bundle` 的版本。对于 Git 仓库，生成器在默认分支上查找组合包，列出它们在 `vX.Y.Z`、`X.Y.Z` 和 `<name>@X.Y.Z` 标签处的版本，以及每个包在默认分支上的版本。标题、描述、图标、作者和主页取自每个插件的最高版本。路径相对于你运行 pnpm 的目录。
-
-生成器只下载和读取文件，从不安装包或运行其代码。它在列表旁的 `.plugin-market-cache` 中保存缓存，因此再次运行时只下载新的版本和提交。按上文所述发布输出目录，即 `index.json` 及其 `icons/` 目录。
-
-<a id="index-format"></a>
-## 索引格式参考
-
-标为 `LocalizedText` 的文本字段是字符串，或以小写语言 id 为键的字符串对象，例如 `{ "en": "Foo", "zh": "甲" }`；对象必须包含 `en`。DSH 不认识的成员会被忽略。
-
-| 索引字段 | 必填 | 含义 |
-|---|---|---|
-| `format` | 是 | `1`。 |
-| `title`、`description` | 仅 `title` | 市场名称和描述，类型为 `LocalizedText`。 |
-| `metadata.categories`、`metadata.labels` | 否 | 将 id 映射为 `{ "title": LocalizedText }` 的对象。 |
-| `metadata.sortKeys` | 否 | 将 id 映射为 `{ "title": LocalizedText, "order": "asc" \| "desc" }` 的对象；`order` 是初始方向。 |
-| `plugins` | 是 | 按市场默认顺序排列的插件。 |
-
-| 插件字段 | 必填 | 含义 |
-|---|---|---|
-| `name` | 是 | npm 包名，在索引内唯一。 |
-| `title`、`description` | 否 | `LocalizedText`；没有标题时卡片显示 `name`。 |
-| `icon` | 否 | 内联 `data:` URL（SVG、PNG、JPEG 或 WebP，不超过 32 KiB）或 URL，见上文。 |
-| `author` | 否 | 显示文本。 |
-| `homepage` | 否 | 介绍该插件的页面的绝对 `https:` 或 `http:` URL；插件页面会链接到它。 |
-| `repository` | 否 | `{ "url": string, "directory"?: string }`：源代码仓库的网页，以及包在其中的目录。插件页面以**源代码**链接到它。 |
-| `metadata.category` | 否 | 一个已声明的分类 id。 |
-| `metadata.labels` | 否 | 已声明的标签 id。 |
-| `metadata.sortKeys` | 否 | 将已声明的排序键 id 映射为数值的对象，例如下载量或评分。 |
-| `versions` | 是 | 至少一个版本，顺序不限。 |
-
-| 版本字段 | 必填 | 含义 |
-|---|---|---|
-| `version` | 是 | 精确的 SemVer 版本，在插件内唯一。 |
-| `publishTimestamp` | 是 | 发布时间，Unix 秒。 |
-| `source` | 是 | `{ "type": "npm", "registry"?: url }`，或 `{ "type": "git", "url": https-url, "commit": 40 位十六进制 SHA, "path"?: 目录 }`。 |
-| `engines.dsh` | 否 | 该版本可运行的 DSH 版本的 SemVer 范围；缺省表示任意版本。 |
-
-DSH 将 npm 版本安装为 `name@version`，存在 `registry` 时先询问它；将 Git 版本安装为 `git+<url>.git#<commit>`，包位于子目录时追加 `&path:/<path>`。`engines.dsh` 应与包自身的 `engines.dsh` 一致，DSH 会在安装时再次检查；没有该字段的包改为按其 `@deepseek-ai/dsh*` peer 依赖检查。[格式说明](../../../.agents/notes/implemented/feature/2026-10-02-plugin-market-index-format.zh.md)定义了全部规则。
-
-<a id="further-exploration"></a>
-## 延伸阅读
-
-- [「发现」标签页参考](../../../packages/client/ui-plugin-market/README.zh.md)说明该标签页的控件和状态。
-- [插件市场服务](../../../packages/boot/plugin-market/README.zh.md)说明获取限制、缓存和 `plugin_market` 工具。
-- [索引校验器](../../../packages/util/plugin-market-index/README.zh.md)是生成器可以用来在发布前检查索引的库。
-
-## 开发备注
-
-无。

package/references/official-docs/docs/user/guide/providers.i18n.yaml

@@ -1,40 +0,0 @@
-# Bilingual-pair consistency record for providers.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write docs/user/guide/providers.md
-/configure-models:
-  en: b1631dcf25e805a1
-  zh: 8ded02e2ae87f00b
-/configure-models/configure-deepseek:
-  en: 2c6b665adc256b4e
-  zh: 2240e4c1573ebe9c
-/configure-models/add-a-third-party-provider:
-  en: f6fb44a85dc5e4dd
-  zh: 2b86ea4492c32ed7
-/configure-models/add-a-custom-model-api:
-  en: 17867305a3e1b52a
-  zh: 876fedf1f6f563e4
-/configure-models/add-a-custom-model-api/discover-models:
-  en: 97318c5a115199ff
-  zh: 0c455e4232cf0265
-/configure-models/select-a-model:
-  en: 6a94264c99535caf
-  zh: f97bb0dc6a40c0d3
-/configure-models/advanced-configuration:
-  en: b882ec69a6899d8a
-  zh: 66a1713aca0e6f1c
-/configure-models/advanced-configuration/image-input:
-  en: 75350cb615da03a4
-  zh: 6f8b3510085e4ac4
-/configure-models/advanced-configuration/deepseek-account-models:
-  en: fc09d02a89b211a7
-  zh: e0f23a8912a24178
-/configure-models/advanced-configuration/reasoning-effort:
-  en: f2ffb493997dcc72
-  zh: dee9238f072e53ad
-/configure-models/advanced-configuration/request-compatibility:
-  en: 6f52195d1502783e
-  zh: 34dbbeacb541afd4
-/configure-models/troubleshooting:
-  en: af9f866bec7701f0
-  zh: 0e4f5e1da975be41

package/references/official-docs/docs/user/guide/providers.md

@@ -1,227 +0,0 @@
-# Configure models
-
-English | [中文](providers.zh.md)
-
-This guide assumes you started the Web UI through the [root README](../../../README.md#run). Model changes take effect on the next request without restarting the server.
-
-## Configure DeepSeek
-
-Open **Settings → Models**. The DeepSeek card exposes one API-key field; enter the key and save it.
-
-![The Models page: the DeepSeek card, with Add model provider below it](providers-models-page.png)
-
-Keys are write-only. The page receives a redacted descriptor after saving, never the literal secret. The key is stored in `$DSH_HOME/.credentials.yaml`, while settings retain only its credential reference.
-
-## Add a third-party provider
-
-Choose **Add model provider**. The card opens on **Third-party model provider**: pick a provider dsh ships with — the list shows provider ids such as `anthropic`, `openai`, `moonshotai` for Kimi, or `zai` for GLM — enter its API key, and save. The installed catalog supplies the endpoint, protocol, and model list.
-
-The authentication **?** explains saved-credential priority and environment fallbacks. Leave the key blank to use a saved credential or try the listed environment variables. A green hint identifies a detected environment variable. A yellow hint means no credential variable was detected; enter an API key or configure the listed variable. An unconfirmed hint means the status read failed. Detection does not validate the credential or test the connection. Provider-managed credential files, including AWS profiles and Google application-default credentials, are outside this check. Providers without native key authentication, such as `openai-codex`, show no key field unless the profile explicitly names a credential reference.
-
-A saved credential uses the placeholder **Leave blank to use saved credentials**, with no status text below the input. Environment fallback uses **Leave blank to use env as auth** and one detection hint while the input is empty. A nonempty input shows no authentication status text. Address configuration variables appear under **Base URL** and do not count as credentials.
-
-A nonempty key input has an eye button. Select **Show secret** to check what you typed, and **Hide secret** to mask it again. Changing the input masks it again. Stored credentials remain write-only.
-
-## Add a custom model API
-
-Switch the card to **Custom model API** for a relay, a company gateway, a self-hosted server, or any provider absent from the installed catalog. Supply a lowercase Provider ID, base URL, API protocol, credential, and at least one model. The **API protocol** must be the one your gateway speaks, and the picker offers three: OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages, stored in the active profile's `cordis.patch.yml` as `openai-completions`, `openai-responses`, and `anthropic-messages`. A provider speaks one protocol, so a gateway that serves two needs two providers.
-
-![The custom model API form: Provider ID, display name, base URL, API protocol, and API key](providers-custom-form.png)
-
-The Provider ID is permanent because requests, saved sessions, model defaults, and credential references use it. To rename a provider, add a new provider and delete the old one. The display name, base URL, protocol, credential, and models remain editable.
-
-### Discover models
-
-Under **Model catalog**, choose **Fetch available models** to ask the endpoint which models it serves. The request uses the base URL, protocol, and key currently in the form, or a saved provider's stored key, and the reply opens a searchable picker: search, tick the models you want, and choose **Add selected**. Nothing is stored until you save or create the provider.
-
-Discovery reads the listing formats common gateways publish, but not every endpoint answers in one of them, so treat it as a convenience rather than a guarantee: when it fails or lists nothing, add the model ids by hand and they work just the same. A built-in provider is always answered from the installed catalog, even when its base URL points at a gateway, so fetch through a custom provider to see what the gateway really serves.
-
-## Select a model
-
-Configured providers appear in the model picker. Selecting a model also makes it the default for new sessions. A session that has already sent a request retains the model recorded in its own log.
-
-If a saved default names a provider that was deleted, the composer displays **Select model** and blocks input until another model is selected.
-
-## Advanced configuration
-
-The generated [plugin configuration catalog](../../config-catalog.md) lists every supported field and default for every plugin; [`dsh-llm-pi-ai`](../../config-catalog.md#deepseek-aidsh-llm-pi-ai) is the provider section this page configures. The [`dsh-llm-pi-ai`](../../../packages/llm/llm-pi-ai/README.md) and [`dsh-llm-deepseek`](../../../packages/llm/llm-deepseek/README.md) references own direct `cordis.patch.yml` configuration, catalog resolution, reasoning controls, credentials, and adapter errors.
-
-::: tip Additional settings
-The Models page exposes the API key, display name, base URL, API protocol, and each model's id, display name, context window, max output tokens, and input types, plus the reasoning levels of a model on a custom model API provider. Configure the reasoning levels of a built-in provider's models, request-compatibility switches, headers, timeouts, and retry policy in `$DSH_HOME/profiles/<profile>/cordis.patch.yml`, the same document the page writes. Edit it directly, or, when the browser runs on the same machine as the server, open it with **Open configuration file** in the Settings header; the adapters re-read it on the next request, so nothing needs a restart. The subsections below cover the fields most gateways need.
-
-For the standard Web UI launch with `dsh web`, `<profile>` is `web`, so the path is `$DSH_HOME/profiles/web/cordis.patch.yml`. If you launch a custom profile, use the name selected at startup instead.
-:::
-
-### Image input
-
-In **Settings → Models**, edit the provider, open **Customized settings**, and expand the model's **Model options**. **Input types** occupies its own row below the capacity fields. Select **Image** for a model that accepts images, and save. **Text** starts selected for a new custom model with no inherited image capability. At least one type must remain selected; select Image before clearing Text for an image-only model.
-
-The checkboxes save `input` for pi-ai models and `inputModalities` for the direct DeepSeek adapter. You can also edit the model in `$DSH_HOME/profiles/<profile>/cordis.patch.yml`; for example, this custom pi-ai provider declares one text-only model and one vision model:
-
-These examples show config fields inside a profile patch. A Cordis config override replaces the complete entry config; preserve other providers and fields when editing an existing override.
-
-```yaml
-- id: llm-pi-ai
-  config:
-    providers:
-      my-gateway:
-        apiKeyEnv: GATEWAY_API_KEY
-        api: openai-completions
-        baseURL: https://gateway.example/v1
-        models:
-          - id: legacy-chat
-          - id: vision-preview
-            input: [text, image]
-```
-
-Pi-ai's `input` accepts `text` and `image` and applies to that model alone. An explicit nonempty selection takes priority. An omitted or empty `input` inherits the installed catalog's input types, then the route's `defaultInput`, which defaults to `[text]`. The checkboxes display these inherited values without saving an override when you merely open the row.
-
-DeepSeek treats an omitted `inputModalities` as text-only and rejects an empty list. Clearing Image also removes that model's `imagePixelBudget` and `imageMaxBytes`, because DeepSeek rejects image limits on a text-only model. Set those limits again if you later enable images and need custom limits.
-
-To restore inheritance after editing the checkboxes, remove the model's `input` or `inputModalities` field from `cordis.patch.yml`. **Restore defaults** removes the entire model-catalog override, including other model edits, so use it only when you want to restore the whole catalog.
-
-If every model you entered by hand takes images, set the fallback once on the route instead of on each of them:
-
-```yaml
-- id: llm-pi-ai
-  config:
-    providers:
-      vision-gateway:
-        apiKeyEnv: GATEWAY_API_KEY
-        api: openai-completions
-        baseURL: https://vision.example/v1
-        defaultInput: [text, image]
-        models:
-          - id: first-model
-          - id: second-model
-```
-
-`defaultInput` is a fallback, not an override, and defaults to `[text]`: on a built-in provider it answers only for models its catalog does not describe, so it never removes images from a catalog model that has them. Narrow one of those with that model's own `input`. When a built-in provider has no explicit `models` list, write it under `modelOverrides`, keyed by model id:
-
-```yaml
-- id: llm-pi-ai
-  config:
-    providers:
-      anthropic:
-        modelOverrides:
-          claude-sonnet-4-5:
-            input: [text]
-```
-
-In pi-ai configuration, every list must name at least one modality except a model's own `input`, where an empty list means the same as omitting it. An unknown modality is refused wherever it is written.
-
-Both fields state a claim about your endpoint rather than checking it. A model that declares images its endpoint does not serve is not caught here; the provider rejects the request instead.
-
-### DeepSeek account models
-
-A signed-in DeepSeek account lists its models from the account service, so the Models page offers no model editor for it. Adjust a single model with `modelOverrides` in `$DSH_HOME/profiles/<profile>/cordis.patch.yml`; the fields match a DeepSeek `models` entry, and unset fields keep the listed values:
-
-```yaml
-- id: llm-deepseek-account
-  config:
-    modelOverrides:
-      deepseek-flash:
-        contextWindow: 524288
-        maxTokens: 131072
-```
-
-A model that needs a newer DeepSeek Harness fails with `CLIENT_UPGRADE_REQUIRED`, which names the version to install. The [account provider reference](../../../packages/llm/llm-deepseek-account/README.md) owns the listing, fallback, and gating rules.
-
-### Reasoning effort
-
-The model picker offers an **Effort** menu for a model that declares reasoning levels. A built-in provider's models inherit their levels from the installed catalog, and DeepSeek's models keep the adapter's levels. A model you enter by hand declares none until you add them, so until then the Effort entry does not appear in the menu and the endpoint's own default decides whether the model thinks.
-
-On a custom model API provider, declare the levels in **Settings → Models**: edit the provider, open **Customized settings**, expand the model's **Model options**, and turn on **Reasoning levels**. The rows start with off, low, medium, and high. Each row pairs a level with the **API value** sent for it, which defaults to the level name; change it only where the model provider's API documentation spells the level differently. Add or delete rows to match what the endpoint supports, keep at least one level besides off, and save. Turning the switch off removes the declaration.
-
-The page writes `reasoningEfforts` in `$DSH_HOME/profiles/<profile>/cordis.patch.yml`, where you can also declare the levels directly:
-
-```yaml
-- id: llm-pi-ai
-  config:
-    providers:
-      my-gateway:
-        apiKeyEnv: GATEWAY_API_KEY
-        api: openai-completions
-        baseURL: https://gateway.example/v1
-        reasoning: high
-        models:
-          - id: my-reasoner
-            reasoningEfforts:
-              off:
-              high: high
-              max: max
-```
-
-Each key is a level the menu offers, and its value is the spelling sent on the wire as `reasoning_effort`, so `max: xhigh` renames a level for a gateway with its own vocabulary. Only `off` may stay empty, because for most endpoints not thinking is the parameter's absence. The route's `reasoning` is the level used while a session has picked none; choosing an effort in the picker saves it, with the model, as the default for new sessions.
-
-An `off` left empty sends nothing, which only stops a model that thinks on request; an `off` given a value sends that value as `reasoning_effort` instead. A model that thinks unless told not to — DeepSeek V4 behind an OpenAI-compatible gateway, for example — needs `compat.thinkingFormat: deepseek`, which makes `off` send `thinking: {type: disabled}` and every other level send `thinking: {type: enabled}` beside the effort:
-
-```yaml
-        models:
-          - id: deepseek-v4-pro
-            compat:
-              thinkingFormat: deepseek
-            reasoningEfforts:
-              off:
-              high: high
-              max: max
-```
-
-A built-in provider's model whose gateway does not reason loses its levels with `reasoningEfforts: false` under `modelOverrides`; selecting an effort for it is then refused as `UNSUPPORTED_REASONING_EFFORT`. DeepSeek's own route needs none of this: its models already offer `off`, `low`, `high`, and `max`, and `llm-deepseek.reasoningEffort` sets the default the picker starts from:
-
-```yaml
-- id: llm-deepseek
-  config:
-    reasoningEffort: max
-```
-
-### Request compatibility
-
-A gateway can hold a working key at a reachable address and still refuse every request. pi-ai decides the shape of a request — which role carries the system prompt, which field caps the output, how a thinking level travels — from the endpoint's URL, and an address it does not recognize is addressed as though it were OpenAI itself. Most OpenAI-compatible gateways refuse at least one thing OpenAI accepts.
-
-Two account for most of it. A model that declares reasoning has its system prompt sent as `role: "developer"`, which many gateways reject outright, and the output cap is sent as `max_completion_tokens`, which a server that only knows `max_tokens` refuses. The form has no field for either; correct them on the route in `$DSH_HOME/profiles/<profile>/cordis.patch.yml`:
-
-```yaml
-- id: llm-pi-ai
-  config:
-    providers:
-      my-gateway:
-        apiKeyEnv: GATEWAY_API_KEY
-        api: openai-completions
-        baseURL: https://gateway.example/v1
-        compat:
-          supportsDeveloperRole: false
-          maxTokensField: max_tokens
-        models:
-          - id: my-model
-```
-
-A route's `compat` is the default for its models, and a model's own wins field by field, so one model can be corrected without restating the route:
-
-```yaml
-        models:
-          - id: my-model
-          - id: my-reasoner
-            compat:
-              thinkingFormat: deepseek
-```
-
-What neither sets keeps the installed catalog's value for that model, and what the catalog does not describe falls to pi-ai's detection. Give every switch you name a value: a key left empty (`supportsDeveloperRole:`) is refused rather than ignored, because an empty value would erase what the catalog knows while saying nothing in its place. A name no protocol accepts is refused too, and the message lists the ones that are available.
-
-Each switch belongs to the protocols that declare it, so a switch valid on one `api` may be refused on another — the message names what that protocol does offer. Like `input` above, a switch states a claim about your endpoint rather than checking it: setting one your gateway does not actually need simply sends a different request.
-
-Every switch, its accepted values, and the protocols that take it are listed under `PiAiCompatProfile` in the [generated `dsh-llm-pi-ai` configuration reference](../../config-catalog.md#deepseek-aidsh-llm-pi-ai) — which is derived from the source, so it cannot fall behind what the adapter accepts.
-
-## Troubleshooting
-
-- **`MISSING_CREDENTIAL`** — Store the provider key through the Models page or supply the referenced environment variable.
-- **`UNKNOWN_MODEL`** — Select a configured model or add the missing model to the custom provider.
-- **Fetching available models returns 401** — Check the key. Model discovery calls the OpenAI-compatible `GET /models` endpoint; enter models manually for endpoints that do not provide it.
-- **Fetching available models reports neither a `data` array nor a `models` object** — The endpoint's listing is in a format discovery does not read. Enter the models by hand.
-- **The gateway refuses every request although the key and URL are right** — Its request shape differs from OpenAI's. Start with `compat.supportsDeveloperRole: false` and `compat.maxTokensField: max_tokens` on the route.
-- **Only reasoning models fail** — pi-ai sends their system prompt as the `developer` role, which the gateway rejects. Set `compat.supportsDeveloperRole: false`.
-- **The Effort menu does not appear for a model you entered by hand** — It declares no levels. On a custom model API provider, turn on **Reasoning levels** in the model's **Model options**; elsewhere, add `reasoningEfforts` to the model in `cordis.patch.yml`.
-- **`off` does not stop a DeepSeek model from thinking** — An empty `off` sends no reasoning field at all, and an endpoint that thinks by default keeps thinking. Set `compat.thinkingFormat: deepseek` on the model or the route.
-- **A compat switch is refused as having no value** — A key written with nothing after the colon. Give it a value, or remove the key to keep the installed catalog's.
-- **An image is refused before sending** — The model declares no image modality. Give a custom provider's model `input: [text, image]`; on DeepSeek's own route, select an image-capable entry from the configured catalog (`deepseek-flash` by default) and confirm that your gateway serves that model with image input.
-- **The provider rejects a request carrying an image** — The model declares images its endpoint does not actually serve. Remove `image` from whichever list granted it — the model's `input`, or the route's `defaultInput` — then start a new session: the attached image stays in the session log, so the same request repeats until the session moves off it.