From 5535f0bcf76bd8e9cbd34853ef7fd6aff4f51b7f Mon Sep 17 00:00:00 2001 From: turtle1999 Date: Sat, 3 Oct 2026 12:01:21 +0800 Subject: [PATCH] docs(notes): add an optional homepage to market index plugins --- .../2026-10-02-plugin-market-index-format.i18n.yaml | 12 ++++++------ .../feature/2026-10-02-plugin-market-index-format.md | 6 ++++-- .../2026-10-02-plugin-market-index-format.zh.md | 6 ++++-- 3 files changed, 14 insertions(+), 10 deletions(-) diff --git a/.agents/notes/proposed/feature/2026-10-02-plugin-market-index-format.i18n.yaml b/.agents/notes/proposed/feature/2026-10-02-plugin-market-index-format.i18n.yaml index d2cddab8a5..55e15276b5 100644 --- a/.agents/notes/proposed/feature/2026-10-02-plugin-market-index-format.i18n.yaml +++ b/.agents/notes/proposed/feature/2026-10-02-plugin-market-index-format.i18n.yaml @@ -18,8 +18,8 @@ en: 4fac5a9b8261342d zh: f9168a8a4209feab /agent-note-plugin-market-index-format/proposal/plugin-fields: - en: aa544c156b4592b4 - zh: 69970e21ccb9eebd + en: f728927a89754892 + zh: 3bc3b18cac60cdc1 /agent-note-plugin-market-index-format/proposal/version-fields: en: d82d84e9f15f0a8c zh: fa65770cd7607c15 @@ -30,14 +30,14 @@ en: 323c997bccd7cf4a zh: fd588d37925d3732 /agent-note-plugin-market-index-format/proposal/generator-obligations: - en: bd44312d55afce0c - zh: 8d341a2ae095dbca + en: 2355bd40a77e615c + zh: a83fa20f47b49e44 /agent-note-plugin-market-index-format/proposal/reader-rules: en: 40613286c82370b2 zh: f6b2452c75e9fc71 /agent-note-plugin-market-index-format/alternatives-considered: - en: ef519b0d5da71645 - zh: 428dbcd6502bbfb5 + en: d102d17d4203c592 + zh: b98f970545e3e07f /agent-note-plugin-market-index-format/acceptance-criteria: en: f364af5c0343a23e zh: 8b8c2a3ec3f6a57f diff --git a/.agents/notes/proposed/feature/2026-10-02-plugin-market-index-format.md b/.agents/notes/proposed/feature/2026-10-02-plugin-market-index-format.md index cdd1a85fbb..2d6b0c10a4 100644 --- a/.agents/notes/proposed/feature/2026-10-02-plugin-market-index-format.md +++ b/.agents/notes/proposed/feature/2026-10-02-plugin-market-index-format.md @@ -42,6 +42,7 @@ Separate the **index** from the **index generator**. DSH defines and reads one J "description": { "en": "Per-tool LLM authorization review", "zh": "逐工具 LLM 授权审查" }, "icon": "icons/auto-review.svg", "author": "Example Labs", + "homepage": "https://example.com/dsh-auto-review", "metadata": { "category": "productivity", "labels": ["official"], @@ -109,6 +110,7 @@ Category, label, and sort-key ids are non-empty strings. Readers look ids up as | `description` | no | `LocalizedText`. | | `icon` | no | Either `data:;base64,`, where `` is `image/svg+xml`, `image/png`, `image/jpeg`, or `image/webp`, `` is canonically padded base64, and the decoded payload is at most 256 KiB; or a URL reference whose resolution against the index URL is an `https:` URL or has the index URL's origin. | | `author` | no | String with at least one non-whitespace character. | +| `homepage` | no | Absolute `https:` or `http:` URL of a page about the plugin. | | `metadata` | no | Object holding the three values below. | | `metadata.category` | no | One declared category id. | | `metadata.labels` | no | Array of distinct declared label ids. | @@ -153,7 +155,7 @@ A reader cannot verify these rules; a generator that violates them publishes a m - `publishTimestamp` is the registry publish time of `version` for npm sources and the committer time of `commit` for Git sources. - `engines.dsh` copies the manifest's `engines.dsh`. Without one, it is the conjunction, as defined in DSH compatibility, of the manifest's DSH peer ranges after publication rewriting, omitting `workspace:*`, `workspace:^`, and `workspace:~`, because installation treats them as the running DSH version; with no remaining range, `engines.dsh` is absent. Installation finds any other `workspace:` range incompatible with every DSH version, so generators do not list such a version. - Each listed version declares `dsh.bundle`. Installation independently refuses a package without a bundle patch. -- `title`, `description`, `icon`, and `author` come from the highest listed version's locale `meta` fields, manifest fields, and icon, using the rules for installed plugin display metadata. +- `title`, `description`, `icon`, and `author` come from the highest listed version's locale `meta` fields, manifest fields, and icon, using the rules for installed plugin display metadata. `homepage` copies that version's manifest `homepage` and is absent without one. ### Reader rules @@ -177,7 +179,7 @@ A reader evaluates each version's compatibility from `engines.dsh` with the rule **One `source` per plugin, with only the pin per version.** A plugin that moves to another repository, directory, or registry between releases could not list its older versions. -**Display fields per version.** A list shows one row per plugin, so older display text would cost index size without a reader that shows it. +**Display fields per version.** A list shows one row per plugin, so older display text, icons, authors, and homepages would cost index size without a reader that shows them. **Inline icons only.** A list without extra requests needs inline icons, but 256 KiB of raw bytes is about 341 KiB as base64, so a 100-plugin index could reach about 35 MB. URL icons trade extra requests, and disclosure of the user's IP address to the image host, for a small index. diff --git a/.agents/notes/proposed/feature/2026-10-02-plugin-market-index-format.zh.md b/.agents/notes/proposed/feature/2026-10-02-plugin-market-index-format.zh.md index 3cebaa7380..abdeaf78c4 100644 --- a/.agents/notes/proposed/feature/2026-10-02-plugin-market-index-format.zh.md +++ b/.agents/notes/proposed/feature/2026-10-02-plugin-market-index-format.zh.md @@ -42,6 +42,7 @@ DSH 只能从用户已知的 spec 安装第三方组合包（bundle）：npm 包 "description": { "en": "Per-tool LLM authorization review", "zh": "逐工具 LLM 授权审查" }, "icon": "icons/auto-review.svg", "author": "Example Labs", + "homepage": "https://example.com/dsh-auto-review", "metadata": { "category": "productivity", "labels": ["official"], @@ -109,6 +110,7 @@ DSH 只能从用户已知的 spec 安装第三方组合包（bundle）：npm 包 | `description` | 否 | `LocalizedText`。 | | `icon` | 否 | 以下两种形式之一：`data:;base64,`，其中 `` 为 `image/svg+xml`、`image/png`、`image/jpeg` 或 `image/webp`，`` 是按规范填充的 base64，解码后的载荷不超过 256 KiB；或者 URL 引用，它相对于索引 URL 解析的结果是 `https:` URL，或与索引 URL 同源。 | | `author` | 否 | 至少包含一个非空白字符的字符串。 | +| `homepage` | 否 | 介绍该插件的页面的绝对 `https:` 或 `http:` URL。 | | `metadata` | 否 | 包含下列三个值的对象。 | | `metadata.category` | 否 | 一个已声明的分类 id。 | | `metadata.labels` | 否 | 由互不相同的已声明标签 id 组成的数组。 | @@ -153,7 +155,7 @@ DSH 安装检查读取包 manifest 中的 `engines.dsh`。存在该字段时， - 对于 npm 来源，`publishTimestamp` 是 `version` 在 registry 中的发布时间；对于 Git 来源，它是 `commit` 的提交者时间。 - `engines.dsh` 复制 manifest 中的 `engines.dsh`。manifest 没有该字段时，它是 manifest 中经发布改写后的 DSH peer 范围按 DSH 兼容性一节定义的合取，并省略 `workspace:*`、`workspace:^` 和 `workspace:~`，因为安装时会将它们视为当前运行的 DSH 版本；没有剩余范围时省略 `engines.dsh`。安装检查认为其他任何 `workspace:` 范围与所有 DSH 版本都不兼容，因此生成器不列出此类版本。 - 列出的每个版本都声明了 `dsh.bundle`。安装时也会独立拒绝没有组合包 patch 的包。 -- `title`、`description`、`icon` 和 `author` 来自所列最高版本的语言文件 `meta` 字段、manifest 字段和图标，并采用已安装插件显示元数据的规则。 +- `title`、`description`、`icon` 和 `author` 来自所列最高版本的语言文件 `meta` 字段、manifest 字段和图标，并采用已安装插件显示元数据的规则。`homepage` 复制该版本 manifest 的 `homepage`，manifest 没有该字段时省略。 ### 读取器规则 @@ -177,7 +179,7 @@ DSH 安装检查读取包 manifest 中的 `engines.dsh`。存在该字段时， **每个插件一个 `source`，每个版本只记录固定点。** 在两次发布之间换了仓库、目录或 registry 的插件将无法列出旧版本。 -**每个版本各有显示字段。** 列表每个插件只显示一行，旧的显示文本会增加索引大小，却没有读取器显示它。 +**每个版本各有显示字段。** 列表每个插件只显示一行，旧的显示文本、图标、作者和主页会增加索引大小，却没有读取器显示它们。 **只允许内联图标。** 不发额外请求的列表需要内联图标，但 256 KiB 原始字节编码为 base64 后约为 341 KiB，因此 100 个插件的索引可能达到约 35 MB。URL 图标以额外请求和向图片主机暴露用户 IP 地址为代价，换取较小的索引。