dsh-plugin-guide 0.3.35 → 0.3.37

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.3/plugin-engines-dsh/guide.zh.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "插件兼容性检查先读 engines.dsh，再读 DSH peerDependencies；拒绝记录改用 requirements 代替 peers。"
+---
+
+# 插件兼容性先读 `engines.dsh`
+
+[English](guide.md) | 中文
+
+## 变更
+
+在 v0.2.1-alpha.3 中，安装和 profile 启动只依据插件或组合包在 `peerDependencies` 中对 `@deepseek-ai/dsh` 和 `@deepseek-ai/dsh-*` 的声明判定兼容性，忽略 `engines.dsh`。下一版本中，包自身的 `engines.dsh` 范围单独决定结果，并忽略这些 peer；只有缺少 `engines.dsh` 时才使用 peer 规则。`workspace:` 值只在 peer 中有效；出现在 `engines.dsh` 中时视为不兼容。`engines` 不是对象或 `engines.dsh` 不是字符串时，兼容性检查无法读取清单，该包会被拒绝。受影响的是声明了 `engines.dsh`，或把 `engines` 声明为非对象值的插件作者。
+
+插件管理器返回给客户端的 `incompatible-version` 拒绝记录 `IncompatiblePlugin`，以及 app-boot 的 `PluginCompatibility` 结果，将 `peers` 重命名为 `requirements`。按 engines 规则判定时键为 `engines.dsh`，回退到 peer 规则时键为 peer 包名。读取这些记录的代码受影响。
+
+## 迁移
+
+1. 如果包声明了 `engines.dsh`，让该范围覆盖包支持的所有 DSH 版本，因为 DSH peer 范围不再放宽或收窄它。删除 `engines.dsh` 可保留基于 peer 的检查。
+2. 将 `engines.dsh` 中的 `workspace:` 值替换为语义化版本范围。
+3. 从 `IncompatiblePlugin` 和 `PluginCompatibility` 读取 `requirements`，不再读取 `peers`。
+4. 用 `dsh plugin --profile <profile> add <package@version>` 或插件管理器安装该包确认迁移：不匹配时，拒绝信息会列出 `engines.dsh` 或对应 peer 包。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.4/account-notification-fields/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.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/upgrade-guide/v0.2.1-alpha.4/account-notification-fields/guide.md
+/:
+  en: 9b6666d42852a11b
+  zh: b14c7d8590c54ba5
+/update-account-notification-consumers:
+  en: 586faed9ab20343f
+  zh: fb3cc099b39b0386
+/update-account-notification-consumers/change:
+  en: 20cc8ba42b771270
+  zh: da0ca5f650c74117
+/update-account-notification-consumers/migration:
+  en: e9fe0c1ebba8acfc
+  zh: 05b94685fb4c5ead

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.4/account-notification-fields/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "AccountBonusNotification exposes unvalidated optional metadata and permits notices without an expiry."
+---
+
+# Update account notification consumers
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The public `AccountBonusNotification` returned by `DeepSeekAccount.getUnnotifiedBonuses()` and `account/getUnnotifiedBonuses` preserves `campaign`, `amount`, `currency`, and `grantedAt` as optional, unvalidated metadata typed as `JsonValue`. Notifications retain `orderId`, `message`, and `expiresAt`, and add an optional `title`. An empty `expiresAt` means the notification never expires. `orderId` accepts arbitrary strings rather than requiring UUIDs.
+
+## Migration
+
+1. Narrow the optional metadata values before using them; their presence and format are no longer guaranteed. Display `message` and use the client's default title when `title` is absent.
+2. Treat an empty `expiresAt` as no expiry before parsing timestamps. Keep `orderId` unchanged when acknowledging a notification.
+3. Update provider fixtures to use the current fields. Confirm that a notification with a non-UUID ID and empty expiry displays and can be acknowledged.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.4/account-notification-fields/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "AccountBonusNotification 提供未经校验的可选元数据，并允许通知永不过期。"
+---
+
+# 更新账号通知使用方
+
+[English](guide.md) | 中文
+
+## 变更
+
+`DeepSeekAccount.getUnnotifiedBonuses()` 和 `account/getUnnotifiedBonuses` 返回的公开类型 `AccountBonusNotification` 保留 `campaign`、`amount`、`currency` 和 `grantedAt`，作为类型为 `JsonValue` 的可选元数据，不做校验。通知保留 `orderId`、`message` 和 `expiresAt`，并新增可选的 `title`。空字符串 `expiresAt` 表示通知永不过期。`orderId` 接受任意字符串，不再要求 UUID 格式。
+
+## 迁移
+
+1. 使用可选元数据前先收窄类型；这些值不再保证存在或符合原有格式。展示 `message`，在 `title` 缺省时使用客户端默认标题。
+2. 解析时间戳前，将空字符串 `expiresAt` 视为永不过期。确认通知时原样传递 `orderId`。
+3. 更新提供者测试夹具以使用当前字段。确认非 UUID 标识、空过期时间的通知可以展示并确认。

package/references/official-docs/docs/user/develop/basic/publish.i18n.yaml

@@ -9,11 +9,11 @@
   en: 341c334cee646f58
   zh: 1ac8f40609a71123
 /package-and-install-a-plugin/two-concepts-two-manifests/the-bundle-manifest:
-  en: 1c59ba70e2d643ea
-  zh: 403667f567bcc77c
+  en: 3013d78e5b04e2d9
+  zh: e6f02c61cf681829
 /package-and-install-a-plugin/two-concepts-two-manifests/the-profile-manifest:
-  en: e2bd00d8de99da67
-  zh: e70b17787bdb53a5
+  en: 00c4218e1af87e9d
+  zh: bd49e41ae376606c
 /package-and-install-a-plugin/install-into-a-profile:
   en: 78baf6471bd6e82b
   zh: 0453a7d35fd57399

package/references/official-docs/docs/user/develop/basic/publish.md

@@ -63,6 +63,8 @@ Create `hello-plugin/cordis.patch.yml`. The patch is a YAML array like the `--pa
 
 `patch` also accepts an ordered list of files, for example `["./base.patch.yml", "./web.patch.yml"]`; the launcher applies them in that order as one layer, and each file's relative plugin paths resolve beside that file. A package without the `dsh.bundle` declaration still installs, but only as a plain dependency: `dsh plugin` prints a warning and activates no layer. Use that package format for a library that plugin packages import rather than a plugin users enable.
 
+Declare the DSH releases the bundle supports with an `engines.dsh` SemVer range, for example `"engines": { "dsh": ">=0.2.0 <0.3.0" }`. Installation and profile startup refuse a bundle whose range the running DSH does not satisfy; without `engines.dsh`, they check its `@deepseek-ai/dsh*` peer dependency ranges instead ([rule](../../../../packages/boot/app-boot/README.md#profiles)).
+
 ### The profile manifest
 
 A profile directory holds two files:
@@ -70,7 +72,7 @@ A profile directory holds two files:
 - `package.json` — the profile's out-of-tree plugin dependencies (managed by pnpm) plus the `dsh.profile` manifest with its ordered `bundles` list.
 - `cordis.patch.yml` — the user's own patch layer, applied after every bundle layer.
 
-You never write a profile manifest by hand: `dsh --profile <name> --from-default-profile <template>` can create one from a shipped application template, while `dsh plugin` creates a base-backed profile and maintains its installed bundle list. The [CLI behavior reference](../../../../apps/cli/reference/README.md#profile-boot) owns the creation rules; the next section shows the plugin path.
+You never write a profile manifest by hand: `dsh --profile <name> --from-default-profile <template>` can create or reset one from a shipped application template, while `dsh plugin` creates a base-backed profile and maintains its installed bundle list. The [CLI behavior reference](../../../../apps/cli/reference/README.md#profile-boot) owns the creation rules; the next section shows the plugin path.
 
 ## Install into a profile
 

package/references/official-docs/docs/user/develop/basic/publish.zh.md

@@ -63,6 +63,8 @@ export function apply() {
 
 `patch` 也接受一个有序的文件列表，例如 `["./base.patch.yml", "./web.patch.yml"]`；launcher 按该顺序把它们作为同一层应用，每个文件中的相对插件路径相对于该文件解析。没有 `dsh.bundle` 声明的包仍然可以安装，但只作为普通依赖：`dsh plugin` 会打印警告，且不激活任何层。如果一个库供插件包 import，而不是供用户启用，就使用这种包格式。
 
+使用 `engines.dsh` SemVer 范围声明组合包支持的 DSH 版本，例如 `"engines": { "dsh": ">=0.2.0 <0.3.0" }`。安装和 profile 启动会拒绝当前运行的 DSH 不满足该范围的组合包；没有 `engines.dsh` 时，改为检查其 `@deepseek-ai/dsh*` peer 依赖范围（[规则](../../../../packages/boot/app-boot/README.zh.md#profiles)）。
+
 ### profile manifest
 
 profile 目录包含两个文件：
@@ -70,7 +72,7 @@ profile 目录包含两个文件：
 - `package.json` — profile 的树外插件依赖（由 pnpm 管理），加上 `dsh.profile` manifest 及其有序的 `bundles` 列表。
 - `cordis.patch.yml` — 用户自己的 patch 层，在每个组合包层之后应用。
 
-profile manifest 从不需要手写：`dsh --profile <name> --from-default-profile <template>` 可以从随附应用模板创建 profile，`dsh plugin` 则创建一个以 base 为基础的 profile，并维护其中已安装的 bundle 列表。创建规则以 [CLI（命令行界面）行为参考](../../../../apps/cli/reference/README.zh.md#profile-boot)为准；下一节展示插件路径。
+profile manifest 从不需要手写：`dsh --profile <name> --from-default-profile <template>` 可以从随附应用模板创建或重置 profile，`dsh plugin` 则创建一个以 base 为基础的 profile，并维护其中已安装的 bundle 列表。创建规则以 [CLI（命令行界面）行为参考](../../../../apps/cli/reference/README.zh.md#profile-boot)为准；下一节展示插件路径。
 
 ## 安装进 profile
 

package/references/official-docs/docs/user/guide/plugin-market.i18n.yaml

@@ -0,0 +1,34 @@
+# Bilingual-pair consistency record for plugin-market.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/plugin-market.md
+/plugin-markets:
+  en: 09b2a6328dcae63c
+  zh: ac7bce767e4f5011
+/plugin-markets/summary:
+  en: 2716b194b8a12aa7
+  zh: b90773d095851969
+/plugin-markets/table-of-contents:
+  en: a8d1e6785c3c3c30
+  zh: 7ea1eaa8204a5a1e
+/plugin-markets/turn-on-discover:
+  en: 96b2fd994f8f3e7e
+  zh: 203e8460ec6aed7a
+/plugin-markets/browse-and-install:
+  en: cf616bba26958533
+  zh: 1e32df16a6f4bba7
+/plugin-markets/publish-an-index:
+  en: b85b82b22c1e14b8
+  zh: 920c0d6f20956c07
+/plugin-markets/generate-an-index-with-the-reference-generator:
+  en: 57a48912c00e1c85
+  zh: 69f2934eed0fbadf
+/plugin-markets/index-format-reference:
+  en: d058d12c27433f64
+  zh: f43b85e4934817f3
+/plugin-markets/further-exploration:
+  en: 3c0a90e8bf73c89b
+  zh: 95608eb4f6278cb4
+/plugin-markets/dev-note:
+  en: b75c8458928b72b9
+  zh: 003ba4e17b4b5269

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

@@ -0,0 +1,148 @@
+# 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

@@ -0,0 +1,148 @@
+# 插件市场
+
+[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

@@ -9,8 +9,8 @@
   en: 2c6b665adc256b4e
   zh: 2240e4c1573ebe9c
 /configure-models/add-a-third-party-provider:
-  en: 0fe5f88e692f618c
-  zh: 4f2e493818d8934f
+  en: f6fb44a85dc5e4dd
+  zh: 2b86ea4492c32ed7
 /configure-models/add-a-custom-model-api:
   en: 17867305a3e1b52a
   zh: 876fedf1f6f563e4
@@ -21,17 +21,20 @@
   en: 6a94264c99535caf
   zh: f97bb0dc6a40c0d3
 /configure-models/advanced-configuration:
-  en: aaefe21c2fb77396
-  zh: c02d1e2a6b2a1290
+  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: f7581a0760fdfd2c
-  zh: dc6eaa16f74a0e9f
+  en: f2ffb493997dcc72
+  zh: dee9238f072e53ad
 /configure-models/advanced-configuration/request-compatibility:
   en: 6f52195d1502783e
   zh: 34dbbeacb541afd4
 /configure-models/troubleshooting:
-  en: 0477cd6fa2772d6b
-  zh: 780619fe998bdef7
+  en: af9f866bec7701f0
+  zh: 0e4f5e1da975be41