dsh-plugin-dev-kb 1.6.0 → 1.8.1

package/kb/site/en/reference/tool-execution-pipeline.md

@@ -8,7 +8,7 @@ rawMarkdownPath: "en/reference/tool-execution-pipeline.md"
 
 # Tool Execution Pipeline
 
-This graph shows where policy, hooks, sandboxing, filesystem guards, result rewriting, final-outcome observation, and UI rendering run without changing the loop. The `tools/pre-execute` waterfall runs first, monotonic guards run next, and the `tools/execute` and `tools/post-execute` waterfalls follow; the three waterfalls may transform a call. Definition-owned `projectContent` installs prepared content before post-execute; `finalizeContent` and `tools/result` run afterward.
+Built-in executors own raw batch parsing, scheduling, cancellation, and Session call/result logging. This graph shows where their shared invocation pipeline applies policy, hooks, sandboxing, filesystem guards, result rewriting, final-outcome observation, and UI rendering without changing the loop. The `tools/pre-execute` waterfall runs first, monotonic guards run next, and the `tools/execute` and `tools/post-execute` waterfalls follow; the three waterfalls may transform a call. Definition-owned `projectContent` installs prepared content before post-execute; `finalizeContent` and `tools/result` run afterward.
 
 ```mermaid
 flowchart TD
@@ -25,14 +25,15 @@ flowchart TD
   owned["Tool-owned session events<br/><code>todo/write</code>, <code>fs/observed</code>, <code>hook/invoked</code>, <code>hook/result</code>, <code>tool/ptc-dispatch</code>"]
   project["ToolDefinition.projectContent<br/>execution-prepared text and images"]
   post["<code>tools/post-execute</code> waterfall<br/>accept, block, replace, add context"]
-  normalized["Registry outer normalization<br/>pipeline/result snapshot throws become isError"]
+  normalized["Invocation pipeline normalization<br/>pipeline/result snapshot throws become isError"]
   finalize["ToolDefinition.finalizeContent<br/>last content-only invariant"]
   final["<code>tools/result</code> synchronous notification<br/>frozen authoritative outcome"]
   context["Active-batch additionalContexts FIFO<br/>injected user/message after recorded tool results"]
   toolResult["Session event: <code>tool/result</code><br/>single model-facing outcome"]
   allResults["Tool batch settled<br/>recorded tool/result events complete"]
   presentResult["UI completed card<br/>presentResult(args, result)"]
-  model --> toolCall
+  executor["Selected ToolExecutor.execute<br/>raw batch, Agent, optional logging step"]
+  model --> executor --> toolCall
   toolCall --> presentCall
   toolCall --> pre
   pre -->|allow| guards
@@ -65,6 +66,6 @@ flowchart TD
   allResults --> context
 ```
 
-Filesystem read-before-edit checks stay below `tool-fs` on `fs/*` events. Generic pre/post waterfalls host hooks and approval policy; `ctx.approval` resolves asks before monotonic guards, and owner policy that must not be reordered remains a registered guard. Around-dispatch concerns such as timeouts wrap `tools/execute`. The registry losslessly snapshots the candidate result and normalizes a snapshot failure before the visible definition's snapshotted `finalizeContent` callback enforces its synchronous content-only invariant. `tools/result` then observes the immutable, lossless-JSON outcome. This lets hooks span tool families without coupling the tools to one policy service. PTC mode sends both the reserved `run_code` transport and its serialized sub-calls through the pipeline; sub-calls carry the parent token, log `tool/ptc-dispatch`, return denials as binding rejections, and omit `additionalContexts` to preserve call/result adjacency.
+Filesystem read-before-edit checks stay below `tool-fs` on `fs/*` events. Generic pre/post waterfalls host hooks and approval policy; `ctx.approval` resolves asks before monotonic guards, and owner policy that must not be reordered remains a registered guard. Around-dispatch concerns such as timeouts wrap `tools/execute`. The pipeline losslessly snapshots the candidate result and normalizes a snapshot failure before the visible definition's snapshotted `finalizeContent` callback enforces its synchronous content-only invariant. `tools/result` then observes the immutable, lossless-JSON outcome. This lets hooks span tool families without coupling the tools to one policy service. PTC mode sends both the reserved `run_code` transport and its ordered sub-calls through the pipeline; sub-calls carry the parent token, log `tool/ptc-dispatch`, return denials as binding rejections, and omit `additionalContexts` to preserve call/result adjacency.
 
 Maintenance mode: curated Mermaid flow; exact tool schemas and event signatures live in generated catalogs.

package/kb/site/guide/desktop-uninstall-cleanup.md

@@ -0,0 +1,63 @@
+---
+editSource: "docs/user/guide/desktop-uninstall-cleanup.zh.md"
+rawMarkdownPath: "guide/desktop-uninstall-cleanup.md"
+---
+
+# 卸载 DSH 桌面端
+
+本指南介绍如何在 macOS 或 Windows 上卸载 DeepSeek Harness 桌面端。清理本地数据是可选操作。
+
+## 1. 卸载应用
+
+先结束使用桌面端内置 CLI（命令行界面）的命令。如果曾通过 Desktop 安装 `dsh` 命令，请先在应用菜单中选择 **管理 dsh 命令… → 移除**。此操作移除桌面端的命令注册，不卸载独立安装的 CLI 程序。
+
+退出 DeepSeek Harness，然后按所在平台的方式卸载：
+
+- **macOS：** 在 Finder 的“应用程序”中删除应用。
+- **Windows：** 在 Windows 11 的“设置 → 应用 → 已安装的应用”，或“控制面板 → 程序 → 程序和功能”中卸载。
+
+## 2. 清理本地数据
+
+此步骤为可选操作。如果需要清理本地数据，请选择下方对应平台的脚本，在 macOS 的终端或 Windows 的 PowerShell 中粘贴运行。
+
+脚本会永久删除当前用户默认的 Harness 主目录及下方列出的 Desktop 数据路径，包括会话、凭据、设置、插件、缓存和与 CLI 共用的状态。如果配置了 `DSH_HOME`，删除前请单独检查该目录；脚本仍会删除默认的 `~/.dsh`。隔离的开发和测试数据目录不在此清理范围内。
+
+Windows 卸载程序通常会删除脚本中列出的两个应用数据目录，但保留 Harness 主目录。若卸载时有文件残留或保留了应用数据，脚本也会清理这些目录。
+
+::: code-group
+
+```sh [macOS]
+sh -c '
+rm -rf -- \
+  "$HOME/.dsh" \
+  "$HOME/Library/Application Support/@deepseek-ai/dsh-desktop" \
+  "$HOME/Library/Logs/DeepSeek Harness" \
+  "$HOME/Library/Preferences/com.deepseek.dsh.plist" \
+  "$HOME/Library/Preferences/ByHost"/com.deepseek.dsh.ShipIt.*.plist \
+  "$HOME/Library/Caches/com.deepseek.dsh" \
+  "$HOME/Library/Caches/com.deepseek.dsh.ShipIt" \
+  "$HOME/Library/HTTPStorages/com.deepseek.dsh" \
+  "$HOME/Library/Caches/@deepseek-aidsh-desktop-updater" \
+  "$(getconf DARWIN_USER_CACHE_DIR)/com.deepseek.dsh" \
+  "$(getconf DARWIN_USER_CACHE_DIR)/com.deepseek.dsh.helper"
+'
+```
+
+```powershell [Windows]
+$ErrorActionPreference = 'Stop'
+@(
+    (Join-Path $env:USERPROFILE '.dsh'),
+    (Join-Path $env:APPDATA '@deepseek-ai\dsh-desktop'),
+    (Join-Path $env:LOCALAPPDATA '@deepseek-aidsh-desktop-updater')
+) | ForEach-Object {
+    if (Test-Path -LiteralPath $_) {
+        Remove-Item -LiteralPath $_ -Recurse -Force
+    }
+}
+```
+
+:::
+
+## 3. 验证清理结果
+
+如果运行了清理脚本，请在重新安装前确认脚本中列出的路径已不存在。如果脚本报错，请解决错误后重跑脚本，再次检查所有列出的路径。Windows 脚本会在首次报错时停止，后续路径可能仍未清理。

package/kb/site/guide/network-proxy.md

@@ -60,7 +60,7 @@ export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
 
 Node 只在进程启动时读取该变量，所以要在运行 `dsh` 之前导出。
 
-**DSH 替你运行的工具遵循同一个代理。** bash 工具里的命令、`git`、`gh`，以及作为子进程启动的 MCP 服务器都会继承这些变量。子进程若本身是 Node 程序，则需 Node 22.21 或更高版本才会遵循；更旧的 Node 会直连。如果你的某个代理变量是 DSH 拒绝的值——比如 SOCKS URL——基于 Node 的工具同样直连而不是起不来，`curl` 与 `git` 则仍会读取那个值。
+**DSH 替你运行的工具遵循同一个代理。** bash 工具里的命令、`git`、`gh`，以及作为子进程启动的 MCP 服务器都会继承这些变量。Node 子程序使用自己安装的运行时：Node 22.21+ 和 Node 24+ 遵循这些变量；更旧的运行时会直连。如果你的某个代理变量是 DSH 拒绝的值——比如 SOCKS URL——基于 Node 的工具同样直连而不是起不来，`curl` 与 `git` 则仍会读取那个值。
 
 **代理 URL 里的密码同样会到达这些工具。** `HTTPS_PROXY=http://alice:s3cret@proxy.example:8080` 就是一个普通环境变量，因此 DSH 运行的每一条命令——包括模型编写的那些——都能读到它，而打印环境的命令会把密码写进被保留的输出。这与该变量在你 shell 里对其他一切程序的行为一致。若这一点重要，请为代理提供一个无需凭据的入口，或改用 URL 之外的方式认证。
 

package/kb/site/guide/plugin-market.md

@@ -1,151 +1,153 @@
----
-editSource: "docs/user/guide/plugin-market.zh.md"
-rawMarkdownPath: "guide/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>
-## 用参考生成器生成索引
-
-仓库包含一个[参考生成器](https://github.com/deepseek-ai/deepseek-harness/blob/master/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 依赖检查。[格式说明](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/feature/2026-10-02-plugin-market-index-format.zh.md)定义了全部规则。
-
-<a id="further-exploration"></a>
-## 延伸阅读
-
-- [「发现」标签页参考](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/client/ui-plugin-market/README.zh.md)说明该标签页的控件和状态。
-- [插件市场服务](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/boot/plugin-market/README.zh.md)说明获取限制、缓存和 `plugin_market` 工具。
-- [索引校验器](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/util/plugin-market-index/README.zh.md)是生成器可以用来在发布前检查索引的库。
-
-## 开发备注
-
-无。
+---
+editSource: "docs/user/guide/plugin-market.zh.md"
+rawMarkdownPath: "guide/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>
+## 用参考生成器生成索引
+
+仓库包含一个[参考生成器](https://github.com/deepseek-ai/deepseek-harness/blob/master/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 仓库，生成器在默认分支上查找 `package.json` 没有设置 `"private": true` 的组合包，列出它们在 `vX.Y.Z`、`X.Y.Z` 和 `<name>@X.Y.Z` 标签处的版本，以及每个包在默认分支上的版本。标题、描述、图标、作者和主页取自每个插件的最高版本。路径相对于你运行 pnpm 的目录。
+
+生成器只下载和读取文件，从不安装包或运行其代码。它在列表旁的 `.plugin-market-cache` 中保存包数据，并复用未变更的版本和提交。每次运行仍会读取源文档或 Git 引用，并刷新已启用的指标；不可用的指标值会被省略。设置 `GITHUB_TOKEN` 以采集 GitHub star 数；没有非空白令牌时，不会发起 GitHub 指标请求，也不会输出 `github_stars`，但 npm 周下载量仍保持启用。按上文所述发布输出目录，即 `index.json` 及其 `icons/` 目录。
+
+<a id="index-format"></a>
+## 索引格式参考
+
+标为 `LocalizedText` 的文本字段是字符串，或以小写语言 id 为键的字符串对象，例如 `{ "en": "Foo", "zh": "甲" }`；对象必须包含 `en`。DSH 在每一层都忽略未知的对象字段。已知字段和 `source.type` 仍须具有有效值；声明映射、本地化文本映射和插件排序值映射中的键作为数据进行校验。
+
+| 索引字段 | 必填 | 含义 |
+|---|---|---|
+| `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 映射为有限数值的对象；不可用时值为 `null`。 |
+| `versions` | 是 | 至少一个版本，顺序不限。 |
+
+插件可以省略 `metadata`、其中的任意字段或单个排序值，也可以用 `null` 表示数据不可用。无论升序还是降序，缺失值都排在最后；实际的零是有效值，不是缺失数据。建议采用的统一定义是：`github_stars` 表示仓库的 GitHub star 数，`npm_weekly_downloads` 表示公共 npm 包在 npm `last-week` 时间窗口内的下载量。两者均为非负整数；周下载量不是月下载量。发布者使用这些键时，在根级 `metadata.sortKeys` 中声明，并在各插件的 `metadata.sortKeys` 中填入可用值。其他已声明的数值键仍受支持。
+
+| 版本字段 | 必填 | 含义 |
+|---|---|---|
+| `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 依赖检查。[格式说明](https://github.com/deepseek-ai/deepseek-harness/blob/master/.agents/notes/implemented/feature/2026-10-02-plugin-market-index-format.zh.md)定义了全部规则。
+
+<a id="further-exploration"></a>
+## 延伸阅读
+
+- [「发现」标签页参考](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/client/ui-plugin-market/README.zh.md)说明该标签页的控件和状态。
+- [插件索引服务](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/boot/plugin-market/README.zh.md)说明获取限制、缓存和 `plugin_market` 工具。
+- [索引校验器](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/util/plugin-market-index/README.zh.md)是生成器可以用来在发布前检查索引的库。
+
+## 开发备注
+
+无。