Built-in plugin feature previews
内置插件功能配图
A one-line plugin description does not always show what a plugin produces. Users deciding whether to enable an official bundle benefit from a picture of its result, such as a document ending with the badge that the DSH badge skill adds. A picture of this kind needs an owner, a localization rule, and a delivery path to the Client.
English
Problem
A one-line plugin description does not always show what a plugin produces. Users deciding whether to enable an official bundle benefit from a picture of its result, such as a document ending with the badge that the DSH badge skill adds. A picture of this kind needs an owner, a localization rule, and a delivery path to the Client.
Decision
In this note, built-in plugins are the official bundles that ship with DSH. Plugin Manager owns every feature preview of these bundles. PluginManagerPage.tsx maps package names to { en, zh } images, in the same file and with the same hardcoding that defines its optional bundle lists. The images live under packages/client/ui-plugin-manager/src/client/assets/. The shared client tsdown preset embeds them in the Plugin Manager client bundle as data URLs. The bundle details page shows the image for the UI language below the description and status notices, whether or not the bundle is enabled.
Every built-in feature preview is an entry in this map. Packages cannot declare a preview, so the map is not a plugin-author interface and can change without a compatibility path.
Alternatives considered
A preview field in the package manifest. Declaring preview in DshPackageManifest and PluginLocalizedMeta, read through app-boot package metadata and checked by the publication and catalog gates, makes image paths, the language map, size limits, and design rules a public contract for every plugin author before any third-party plugin needs one. One official bundle has artwork, which does not justify a public format.
Keeping the images in each bundle package and fetching them from the Host. This keeps artwork beside its feature, but it still requires a Host read path and a resource interface between bundles and Plugin Manager.
Consequences
Built-in feature previews need no metadata reader, manifest validation, publication rule, or catalog field. Adding one means adding an image and a map entry in Plugin Manager. Each preview adds its encoded size to the Plugin Manager client bundle; the badge skill images add about 207 KB.
Third-party plugins cannot show a preview or other introduction before they are enabled; a bundle's own plugins.bundle.config content appears only while its Client half is loaded. The long-term plan is a way for third-party plugins to present their README in Plugin Manager. That design will define its own format and trust rules, and built-in feature previews may move to it then.
中文
问题
一行插件描述不一定能说明插件产生什么结果。用户决定是否启用官方组合包时，一张展示其结果的图片会有帮助，例如一份以 DSH badge skill 添加的徽章结尾的文档。这类图片需要所有者、本地化规则和发送到 Client 的途径。
决策
在本记录中，内置插件指随 DSH 发布的官方组合包。插件管理拥有这些组合包的所有功能配图。PluginManagerPage.tsx 把包名映射到 { en, zh } 图片；该映射与定义其可选组合包列表的代码位于同一文件，并采用相同的硬编码方式。图片放在 packages/client/ui-plugin-manager/src/client/assets/ 下。共享的 client tsdown preset 把图片以 data URL 嵌入插件管理 client bundle。组合包详情页在描述和状态提示下方显示当前 UI 语言对应的图片，无论组合包是否启用。
每个内置功能配图都是这个映射中的一项。包不能声明配图，因此该映射不是面向插件作者的接口，修改时不需要兼容路径。
考虑过的替代方案
在包 manifest 中增加 preview 字段。 在 DshPackageManifest 和 PluginLocalizedMeta 中声明 preview，通过 app-boot 包元数据读取，并由发布和目录检查校验，会在任何第三方插件需要之前，使图片路径、语言映射、大小限制和设计规则成为所有插件作者都要遵守的公开约定。只有一个官方组合包有配图，不足以支持一个公开格式。
把图片留在各组合包中，从 Host 获取。 这样配图与功能放在一起，但仍需要 Host 读取路径以及组合包与插件管理之间的资源接口。
后果
内置功能配图不需要元数据读取器、manifest 校验、发布规则或目录字段。增加一张配图意味着在插件管理中添加图片和映射项。每张配图都会把其编码后的大小加到插件管理 client bundle 中；badge skill 的图片约增加 207 KB。
第三方插件在启用前无法显示配图或其他介绍内容；组合包自身的 plugins.bundle.config 内容仅在其 Client 部分加载时显示。长期计划是提供一种方式，让第三方插件在插件管理中展示其 README。该设计将定义自己的格式和信任规则，届时内置功能配图可能迁移过去。