@linkdesk/plugin-docs 0.1.77 → 0.1.78

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/00-readme.md CHANGED
@@ -26,6 +26,7 @@
26
26
  | **Add a setting to my plugin** | [20-adding-a-setting](20-adding-a-setting.md) | → [03-contributes-spec](03-contributes-spec.md) |
27
27
  | **Let AI / keybindings / the Command Palette operate my plugin** | [21-command-ification-spec](21-command-ification-spec.md) | → [03-contributes-spec §3.1](03-contributes-spec.md) (every `commands` field) |
28
28
  | **Add an item to a menu (context menu / gear / hamburger)** | [22-menu-contribution-points](22-menu-contribution-points.md) | → [21-command-ification-spec](21-command-ification-spec.md) (make it a command first) · §3 "Payload" covers `commandArgs` vs `context` when a shared component opens the menu |
29
+ | **Turn my repo into a store source / open an author store / curate collections (incl. paid)** | [23-marketplace-catalog-and-author-store](23-marketplace-catalog-and-author-store.md) | → `@linkdesk/marketplace-kit` (`init` / `validate` / `keygen`) · [06-plugin-json-spec](06-plugin-json-spec.md) (category fields) |
29
30
  | **Let the user choose which plugin opens a file (the "Open with…" picker)** | [21-command-ification-spec §2.1](21-command-ification-spec.md) (call the **host command** via `@linkdesk/plugin-sdk`) | → [19-component-cheatsheet](19-component-cheatsheet.md) (`OpenWithPicker`: ⛔ don't build your own panel) · [06-plugin-json-spec `fileAssociations`](06-plugin-json-spec.md) (declare the types you can open) |
30
31
  | **Make several regions work together** (sidebar selection → main area switch → status bar update) | [18-cross-region-wiring](18-cross-region-wiring.md) | → [07-plugin-to-plugin-communication](07-plugin-to-plugin-communication.md) |
31
32
  | **Look up the API** (what can I call) | [01-plugin-api-contract §3](01-plugin-api-contract.md) (the entry table for the three API surfaces) | → the SDK package README cheatsheet / `linkdesk.d.ts` |
@@ -182,6 +183,7 @@ Full story → [04-distribution-format §Listing Is Two Steps](04-distribution-f
182
183
  | **20** | **[20-adding-a-setting](20-adding-a-setting.md)** | The minimal approach: declare one → it appears on the settings page automatically → read it in code |
183
184
  | **21** | **[21-command-ification-spec](21-command-ification-spec.md)** | **Let AI/keybindings/the Command Palette operate my plugin** — how to turn actions into commands, plus the author checklist; §2.1 covers calling **host** commands (`SHELL_COMMANDS` / helpers) without hard-coding their ids |
184
185
  | **22** | **[22-menu-contribution-points](22-menu-contribution-points.md)** | **Put an action into one of the host's menus** — the 14 slots, the `group`/`when` conventions, the public context-key table, and the menu **payload law** (`commandArgs` vs `context`) |
186
+ | **23** | **[23-marketplace-catalog-and-author-store](23-marketplace-catalog-and-author-store.md)** | **Marketplace data authoring** — single-plugin / multi-plugin / standalone-catalog forms · the closed category list in full · `marketplace.json`/author-block/two-form collections field reference · store-front recipes · kit usage · license issuing & official endorsement |
185
187
  | **T1** | **[themes/01-build-a-theme-plugin](themes/01-build-a-theme-plugin.md)** | The theme-authoring walkthrough (no code) |
186
188
  | **T2** | **[themes/02-theme-field-index](themes/02-theme-field-index.md)** | A cross-index of recipe fields and CSS variables |
187
189
 
@@ -29,7 +29,7 @@ A few key points (a summary of Matrix §2; the matrix wins on details):
29
29
 
30
30
  | Fact | Explanation |
31
31
  |------|------|
32
- | **The contract has 47 namespaces** | The pool injects 45 (shell-only faces `bridge` and `storage` are not injected into the pool); the shell injects 26; mock injects 13 — **the live readings of the `check-namespace-matrix` gate are authoritative** (this row is mechanically reconciled by it; ⛔ do not copy the comment in `surfaces.ts` — that one drifts too) |
32
+ | **The contract has 49 namespaces** | The pool injects 47 (shell-only faces `bridge` and `storage` are not injected into the pool); the shell injects 27; mock injects 13 — **the live readings of the `check-namespace-matrix` gate are authoritative** (this row is mechanically reconciled by it; ⛔ do not copy the comment in `surfaces.ts` — that one drifts too) |
33
33
  | **Pool = the plugin runtime source of truth** | Plugins run in the pool preload — namespaces injected by the pool are **required**; `bridge` is real-shell-only |
34
34
  | **"Shell-only" ≠ plugins can't call it** | `window.*`/`shell.*`/`hotExit.*`/`getFilePath` **are actually injected in the pool** — the older version's ❌ shell-only marking for those surfaces was wrong |
35
35
  | **Contract required-surface drift is now zero** | `env.get(pluginId)` forwarding, `clipboard.readText` shell completion, `dialog.openFile` shell completion — all three are implemented, with no `?` degradation |
@@ -44,7 +44,7 @@ A few key points (a summary of Matrix §2; the matrix wins on details):
44
44
 
45
45
  **Every method signature, parameter, return value, and payload type for `window.linkdesk.*` = [contracts/linkdesk.d.ts](https://github.com/Encaron/linkdesk/blob/electron/contracts/linkdesk.d.ts)** (auto-generated; do not hand-edit).
46
46
 
47
- - **Generation sources:** `src/core/api/linkdesk-api.ts` + `linkdesk-api/` (16 domain interfaces) + `src/core/types/ipc/*` + `src/core/types/pool/*` (wire payload types)
47
+ - **Generation sources:** `src/core/api/linkdesk-api.ts` + `linkdesk-api/` (17 domain interfaces) + `src/core/types/ipc/*` + `src/core/types/pool/*` (wire payload types)
48
48
  - **Generator:** `scripts/generate-contract.mjs` (Route C — the contract type file is the source; pure types bundled into a single file)
49
49
  - **Mechanical gate:** the preload on both sides `satisfies` the contract surface types → tsc drift gate; `contracts:check` byte-compares hashes inside `npm run check`
50
50
  - **Coverage matrix:** every namespace × pool/shell/mock coverage → [Namespace Matrix §2](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/归一化基建/契约生成/命名空间矩阵.md#2-命名空间--四面覆盖矩阵)
@@ -355,7 +355,7 @@ const file = await window.linkdesk.dialog.openFile({
355
355
  > ⚠️ **Notifications are not "auto-vanishing floating cards"** (notification-surface unification and correction): the bottom-right narrow toast pipeline has been deleted entirely, and **the only notification surface = the status bar bell wide panel**. Three things authors need to know:
356
356
  > 1. **Notifications don't pop a card, don't steal focus, and don't block interaction**—they go into the bell (unread count +1), and the user only sees them after opening it. Don't treat notifications as a "must be seen" channel: if the user has to decide on the spot → use `dialog.confirm` (modal, steals focus).
357
357
  > 2. **Persistent notifications per source are quota-limited**—grouped by `options.source`, at most 5 persistent per group; beyond that, the oldest one from the same source is pushed out. A flood won't pile into a wall, but **don't count on notifications for long-term records either**.
358
- > 3. **Keyboard reachability means "the panel is reachable", not "notifications are reachable"**—the bell can be focused and opened with the keyboard, everything inside the panel can be reached with Tab, and `Esc` closes it; but the panel **has no focus trap** (non-modal, focus can leave freely). **Don't write assumptions like "Tab gets you to my notification button"**—the user may never open the panel at all; and **don't count on a second surface**: the bell panel is the only notification face (user directive restated 2026-10-01 — the bottom-right "auto-vanishing card" was built twice and deleted twice).
358
+ > 3. **Keyboard reachability means "the panel is reachable", not "notifications are reachable"**—the bell can be focused and opened with the keyboard, everything inside the panel can be reached with Tab, and `Esc` closes it; but the panel **has no focus trap** (non-modal, focus can leave freely). **Don't write assumptions like "Tab gets you to my notification button"**—the user may never open the panel at all. **Light feedback ≠ notifications**: after the 2026-11-19 authorization reversal there is a separate light-toast channel (see below)—short, lightweight, one-liner acknowledgements go through `toasts.show`; anything that must be retained / decided on / shows progress still goes through notifications.
359
359
 
360
360
  **Notification action buttons (`actions` on `notifications.show`):** failure / user-action-required notifications can carry an `actions` button array—clicking runs through the **command system** (modeled after VS Code's `showErrorMessage(msg, { title, command })` actions). Command handlers are registered by the plugin itself (`commands.registerCommand`):
361
361
 
@@ -407,6 +407,21 @@ await window.linkdesk.notifications.show("Sync failed", { source: "myplugin" });
407
407
 
408
408
  > The full **behavior contract** (not signatures—for signatures see `contracts/linkdesk.d.ts`) is in the `notifications` row of [`01-plugin-api-contract.md`](01-plugin-api-contract.md) §3.2—this section only covers usage, and that one is authoritative for semantics.
409
409
 
410
+ **Light toast (`toasts.show`)—short, lightweight, one-liner acknowledgements (restored by user authorization 2026-11-19):** light feedback that needs no follow-up ("copied / check finished / refreshed") goes here; bottom-centered, auto-dismisses in 3s by default, at most 1 action. **The division of labor in one sentence: toast = "passing by", panel = "kept"**—errors / decisions / progress / long text still go through `notifications.show`:
411
+
412
+ ```tsx
413
+ // Light toast—bottom-centered, auto-dismisses in 3s; same key updates the existing entry (no card stacking)
414
+ await window.linkdesk.toasts.show({ message: "Link copied", key: "copy-done" });
415
+ await window.linkdesk.toasts.show({
416
+ message: "Check finished—3 updates available",
417
+ severity: "success", // info | success | warning (error auto-routes to the panel)
418
+ key: "check-updates",
419
+ action: { title: "View", command: "myplugin.openUpdates" },
420
+ });
421
+ ```
422
+
423
+ **Degradation routing runs on the shell, callers don't pre-judge**: `error` severity / more than 1 action / text beyond two visual lines (CJK counts 2) / `ttl ≥ 8000ms` entries auto-route to the panel—you express intent only; the shell decides the surface, and the handle's `presentation` field honestly reports where it landed. ⛔ Don't pre-route to another surface "to make sure it pops" (that's a second ruler); ⛔ don't hand-draw bottom hint overlays (all plugins share the same channel). Full contract in `contracts/linkdesk.d.ts` (`toasts`).
424
+
410
425
  **Rich-content confirm dialogs (`dialog.confirmContent`):** use this when the confirm dialog needs **more than one line of text** (a form / list / screenshot / custom layout)—**the dialog is the shell (centered, masking, Esc, focus lock, click-mask to cancel) and your view draws the content** (modeled after VS Code's "the dialog is the shell, the plugin defines the content"):
411
426
 
412
427
  ```tsx
@@ -602,6 +617,7 @@ both stylesheets land on the same element.
602
617
  | `ldk-view-skeleton-breath` | the content loading skeleton's breathing |
603
618
  | `ldk-welcome-skeleton-breath` | the welcome recent list loading skeleton's breathing |
604
619
  | `ldk-welcome-in` | the welcome page's entrance fade-up (its single authored moment) |
620
+ | `ldk-tt-in` | the host light toast (TransientToast) entry slide-up + fade-in |
605
621
 
606
622
  **The name you reference has to exist somewhere**—rule 2 above says "when you rename, change the reference in
607
623
  the same commit"; this is the other half, and **the machine checks it**: the name you write in
@@ -0,0 +1,277 @@
1
+ # 23 — Marketplace catalog & author store (marketplace.json / author blocks / collections)
2
+
3
+ > **In one sentence**: turn your repository into a "source" in the LinkDesk plugin store — the simplest form needs nothing at all (just `plugin.json`); you only need this guide when you want multiple plugins under one source, an author store front, or curated collections.
4
+ > This is the spec + recipes for **marketplace data authors**: how to write, self-check and publish the three pieces — `marketplace.json` (the catalog), `authors/<id>.json` (author block), `collections/` (collections).
5
+ > Field-level authority = the JSON Schema shipped inside `@linkdesk/marketplace-kit` (editor `$schema` completion & red squiggles); local checks = `npx marketplace-kit validate`.
6
+
7
+ ---
8
+
9
+ ## 1. Three author forms (pick a form first)
10
+
11
+ | Form | Repo contents | What you do | What users see |
12
+ |:--:|:--|:--|:--|
13
+ | **Single-plugin repo (zero config)** | only `plugin.json` | **nothing** | Your repo URL is added as a store source → this one plugin appears |
14
+ | **Multi-plugin repo** | `plugin.json`×N + root `marketplace.json` | `npx marketplace-kit init` to scaffold → fill entries | One source, several plugins |
15
+ | **Standalone catalog repo** | `marketplace.json` + `authors/<id>.json` (+ `collections/`) | `npx marketplace-kit init --author <yourGitHubUsername>` | One source + author card + author store front (multi-repo aggregation) |
16
+
17
+ **How to choose**:
18
+ - One plugin → **single-plugin repo, stop here** (you can skip the rest of this guide).
19
+ - Several plugins under one source → multi-plugin repo.
20
+ - Want an **author card** (avatar/intro/repo count) and an **author store front** (you arrange the home sections) → standalone catalog repo (or a multi-plugin repo plus the author block); declare the same `authorId` in every one of your repos and the store aggregates them into one author domain automatically.
21
+
22
+ ⚠️ **Never hand-write a root `marketplace.json` in a single-plugin repo** — once the store sees it (even empty) it stops falling back to `plugin.json`, and your plugin disappears from the store. For an author card there, `init --author` adds only `authors/<id>.json` and touches nothing else.
23
+
24
+ ---
25
+
26
+ ## 2. Category declaration (primary + subcategories — pick, don't invent)
27
+
28
+ Declare categories in **your plugin's own `plugin.json`** (English slugs):
29
+
30
+ ```json
31
+ {
32
+ "pluginId": "demo-plugin",
33
+ "category": "development",
34
+ "categories": ["code-editing"]
35
+ }
36
+ ```
37
+
38
+ - `category` (single) = primary category — decides which drawer bucket your plugin lives in;
39
+ - `categories` (multi, optional) = subcategory tags — feed the store's subcategory chips and search.
40
+
41
+ ### 2.1 The available list (pick from this table; inventing slugs is not allowed)
42
+
43
+ | Primary | zh | Subcategories |
44
+ |:--|:--|:--|
45
+ | `development` | 开发 | `code-editing` · `terminal` · `vcs` · `runtime` · `i18n` · `debug` · `snippets` |
46
+ | `documents` | 文档 | `viewer` · `convert` · `markdown` · `files` · `office-doc` · `notebook` |
47
+ | `hardware` | 硬件 | `serial` · `flash` · `probe` · `smart-control` · `home-automation` · `sensor` · `iot` · `can-bus` |
48
+ | `network` | 网络 | `browser` · `chat` · `cloud` · `download` · `packet-capture` · `proxy` · `remote` |
49
+ | `productivity` | 效率 | `clipboard` · `notes` · `ai` · `color` · `todo` · `timer` · `launcher` · `calculator` |
50
+ | `themes` | 主题 | `color-scheme` · `icon-pack` · `font-pack` · `wallpaper` · `cursor-set` · `sound-pack` |
51
+ | `entertainment` | 娱乐 | `player` · `game` · `music` · `comic` · `novel` · `stream` |
52
+
53
+ ### 2.2 How to choose
54
+
55
+ - Primary = **pick exactly one** of the 7 buckets above;
56
+ - Subcategories = **optional**, from the list of your primary bucket (multiple allowed); skipping them is perfectly legal — your plugin still shows, it just doesn't join the subcategory chips;
57
+ - Really can't decide the primary? Leave it out — your plugin lands in the "Other" bucket and stays visible forever (never dropped, never an error).
58
+
59
+ ### 2.3 What happens if you write an off-list value
60
+
61
+ - **No crash, no disappearance**: the plugin still ships, landing in the "Other" bucket (or the "untagged" fallback chip for subcategories);
62
+ - **You get a notice**: `npx marketplace-kit validate` warns, and the store's sources page records a declaration notice;
63
+ - The warning message **prints the current available list** — fix it right from the error, no docs needed.
64
+
65
+ ### 2.4 Does the list grow?
66
+
67
+ Yes — the store operator extends it as needed (pure data, nobody has to release anything). **The only thing you must do: treat the list printed by `marketplace-kit validate` as the truth** — it is always current.
68
+
69
+ ---
70
+
71
+ ## 3. `marketplace.json` field reference (the root file for multi-plugin / standalone catalog repos)
72
+
73
+ ```json
74
+ {
75
+ "$schema": "https://unpkg.com/@linkdesk/marketplace-kit/schemas/marketplace.schema.json",
76
+ "plugins": [ "……entries, see below……" ],
77
+ "collections": [ "……optional, see §5……" ],
78
+ "categoryRail": { "order": ["development", "documents"], "icons": { "development": "lucide:code" } }
79
+ }
80
+ ```
81
+
82
+ **Entry fields (`plugins[]`)** — publishing maintains entries for your built projects automatically; when hand-filling follow this table:
83
+
84
+ | Field | Required | Notes |
85
+ |:--|:--:|:--|
86
+ | `id` / `name` / `version` | ✅ | identity trio (`id` should match your pluginId) |
87
+ | `downloadUrl` | ✅ | direct link to the `.linkdesk-plugin` artifact (GitHub Release asset) |
88
+ | `versions[]` | ✅ | version history, **newest first**; each `{version, downloadUrl, publishedAt, changelog?}`. The catalog keeps the full history — the store detail page only renders the latest few, old entries are harmless |
89
+ | `description` / `license` / `repository` | opt | display & detail page |
90
+ | `author` / `authorId` | opt | `author` is the display name (`{name, url}` or a string); `authorId` is the **aggregation key** (GitHub username recommended) — same id aggregates an author domain and feeds the "official ✓" verification |
91
+ | `icon` / `marketIcon` | opt | **absolute URLs** (must resolve even when not installed); `marketIcon` wins as the store-row icon |
92
+ | `screenshots[]` | opt | string = image URL; at most 1 video item and it must come first: `{"type":"video","url":"…","poster":"…"}` (never autoplays) |
93
+ | `category` / `categories[]` | opt | see §2 |
94
+ | `pricing` | opt | paid listing, see §8 |
95
+ | `minAppVersion` | opt | minimum host version |
96
+ | `publishedAt` / `readmeUrl` / `size` | opt | publish date (any `versions[]` entry counts) / README direct link / byte size |
97
+
98
+ **Root fields**: `version`/`updatedAt` (maintained by the publish tool); `sources[]` is official-catalog-only (reviewed third-party source list — authors don't write it); `collections` (§5); `categoryRail` (category display order — slug order data; only the official catalog's rail takes effect).
99
+
100
+ Compatibility rule: **add fields only, never change semantics**. Old store versions reading a new catalog silently ignore unknown fields, never crash.
101
+
102
+ ---
103
+
104
+ ## 4. Store-front recipes (`homepage.sections`, copy-paste ready)
105
+
106
+ Author store-front sections are fully declaration-driven (`homepage.sections[]` inside `authors/<id>.json`, rendered in declared order).
107
+ **"Browse by category" needs no declaration** — it always closes the list and cannot be removed.
108
+
109
+ ```jsonc
110
+ // Hero carousel: 3–5 slides, you pick what makes the big screen
111
+ { "type": "hero", "title": "Editor's picks", "hint": "Hand-picked",
112
+ "slides": [ { "plugin": "demo-plugin", "tag": "Featured" } ] }
113
+
114
+ // Collection section: references a collection id (where collections live, see §5)
115
+ { "type": "collection", "collection": "must-have", "layout": "duo",
116
+ "hint": "Everyone installs these", "glow": false,
117
+ "more": { "label": "See all", "target": "category:hardware" } }
118
+
119
+ // Everything grid
120
+ { "type": "grid", "title": "All plugins" }
121
+
122
+ // Rank: a computed slot keyed by downloads
123
+ { "type": "rank", "top": 6, "scope": "self",
124
+ "more": { "label": "Full rank", "target": "rank" } }
125
+ ```
126
+
127
+ **Common section fields**: `title` (fully yours) · `hint` (sub-caption; undeclared ⇒ nothing) · `glow` (ambient glow, default on; `false` falls back to a neutral shadow — no custom colors) · `more` (heading jump link: `label` is free-form, `target` is a closed set — `category:<slug>` / `rank` / `repo:<id>`, never a web URL).
128
+
129
+ Boundaries: only the first hero carousel gets the top slot (extras warn and render in place); `type` accepts exactly `hero/collection/grid/rank`; a section referencing a missing collection renders empty with a declaration notice.
130
+
131
+ ---
132
+
133
+ ## 5. Two ways to declare collections (both readable, pick one)
134
+
135
+ **Form A (inline, in the root file)** — good for 1–3 collections:
136
+
137
+ ```json
138
+ "collections": [
139
+ { "id": "must-have", "title": "Must have", "layout": "strip",
140
+ "hint": "Curated by the store owner", "items": ["demo-plugin", "demo-tool"], "order": 1 }
141
+ ]
142
+ ```
143
+
144
+ **Form B (split folder)** — many collections, or you want home data maintained independently:
145
+ the root `marketplace.json` `collections` carries **string id references**, full declarations live in `collections/<id>.json`:
146
+
147
+ ```json
148
+ "collections": ["must-have", "themes-picks"]
149
+ ```
150
+
151
+ ```json
152
+ // collections/must-have.json — identical object shape to form A
153
+ { "id": "must-have", "title": "Must have", "layout": "strip", "items": ["demo-plugin"], "glow": false, "more": { "label": "See all", "target": "category:hardware" } }
154
+ ```
155
+
156
+ Rules:
157
+ - the store fetches referenced files **only for ids listed as strings** — declare none and nothing is fetched (old catalogs cost zero);
158
+ - the same id declared both ways → **the inline object in the root file wins**, the folder copy is ignored with a declaration notice (don't double-declare);
159
+ - the file's declaration shape is identical to inline (`id/title/items` required; `subtitle/hint/cover/layout/glow/more/order` optional);
160
+ - `items` referencing plugin ids that don't exist → those members are skipped silently (defensive, the store never crashes).
161
+
162
+ ---
163
+
164
+ ## 6. Author block (`authors/<authorId>.json`)
165
+
166
+ ```json
167
+ {
168
+ "$schema": "https://unpkg.com/@linkdesk/marketplace-kit/schemas/authors.schema.json",
169
+ "authorId": "your-github-username",
170
+ "name": "Your display name",
171
+ "intro": "One-line intro (GitHub provides avatar/name when resolvable; these are the non-GitHub fallback)",
172
+ "storeTitle": "Your Plugin Store",
173
+ "publicKey": "……(paid authors only, see §8)",
174
+ "repos": [
175
+ { "id": "main", "name": "Main repo", "sourceUrl": "https://raw.githubusercontent.com/you/your-marketplace/HEAD/marketplace.json" }
176
+ ],
177
+ "homepage": { "sections": [ "……recipes from §4……" ] }
178
+ }
179
+ ```
180
+
181
+ - **Aggregation**: the same `authorId` in every repo's source root → the store aggregates one author domain (avatar/name follow GitHub as the canon);
182
+ - **repos[]**: one segment per marketplace repo of yours (`sourceUrl` = that repo's marketplace.json direct link) — this is where the store-front repo-switch cards come from;
183
+ - Location: standalone catalog repos keep it at the repo root `authors/` folder; single-plugin and multi-plugin repos can host the same file at their own root when a plugin should join the author domain (the store looks in each source root).
184
+
185
+ ---
186
+
187
+ ## 7. Using marketplace-kit (scaffolds & local checks)
188
+
189
+ ```bash
190
+ npm i -D @linkdesk/marketplace-kit
191
+
192
+ npx marketplace-kit init # scaffold (auto-detects the repo form; never overwrites)
193
+ npx marketplace-kit init --author your-github-username # add the author block
194
+ npx marketplace-kit validate ./ # validate the whole folder (incl. cross-file collection refs)
195
+ npx marketplace-kit validate ./marketplace.json # validate one file
196
+
197
+ # Paid authors (see §8):
198
+ npx marketplace-kit keygen --author your-github-username
199
+ npx marketplace-kit sign-license --key your-github-username.private.key --plugin demo-plugin --exp 30d
200
+ ```
201
+
202
+ - `validate` **errors** (structure / unknown fields / closed-set typos) exit 1, **warnings** (off-list categories, collection refs… declaration notices) exit 0 — the warning codes use the same vocabulary as the store's sources-page notices;
203
+ - unknown fields are hard errors that print the allowed keys (the store silently drops keys it doesn't know — a typo means you wrote nothing, so catch it before publishing).
204
+
205
+ ---
206
+
207
+ ## 8. Paid plugins (pricing, public key, license issuing)
208
+
209
+ 1. **Declare pricing** (entry level; display only, the store never adjudicates):
210
+
211
+ ```json
212
+ "pricing": { "model": "paid", "price": 9.9, "currency": "USD",
213
+ "licenseUrl": "https://your-sales-page", "refundUrl": "https://your-refund-policy", "trialDays": 14 }
214
+ ```
215
+
216
+ Payment happens on your own sales page (LinkDesk never collects money or takes a cut); `trialDays` is display-only (real trial gating lives in your plugin code).
217
+
218
+ 2. **Generate a key pair**: `npx marketplace-kit keygen --author your-github-username` → a private key file (**never commit it, never share it; losing it means rotating keys and invalidating every license**) + a public key (one base64 line).
219
+
220
+ 3. **Place the public key**: paste it into `marketplace.config.json`'s `publicKey` (publish writes it into the author block) or directly into `authors/<id>.json`'s `publicKey` field.
221
+
222
+ 4. **Issue a license**: after a buyer pays, sign with their machine fingerprint —
223
+
224
+ ```bash
225
+ npx marketplace-kit sign-license --key your-github-username.private.key \
226
+ --plugin demo-plugin --machine <buyer machineFingerprint> --exp 2027-12-31
227
+ ```
228
+
229
+ `--exp` accepts `30d`/`12w`/`6m`/`1y` or a date; passing `--machine` makes it one-license-one-machine (buyers find the fingerprint in the shell's "this machine" info). Hand the `v1.…` key to the buyer; pasting it into the store's "I have a key" completes **offline verification** (in the shell, no server).
230
+
231
+ 5. **Refunds / rotation**: refunds go through your sales channel; rotating keys = keygen again + update the public key + re-issue licenses for existing buyers (licenses signed by the old key stop validating).
232
+
233
+ ---
234
+
235
+ ## 9. Publishing (multi-plugin / standalone catalog repos)
236
+
237
+ ```bash
238
+ npm run build # produce <id>.linkdesk-plugin (each plugin in its own project)
239
+ npm run publish # linkdesk-plugin-sdk publish: GitHub Release → upload asset → update this repo's marketplace.json
240
+ ```
241
+
242
+ With `marketplace.config.json` at the project root (generated by `init`), `publish` also maintains the author-side files **in the same run**:
243
+
244
+ | File | Written by | Contents |
245
+ |:--|:--|:--|
246
+ | `marketplace.json` | publish | your plugin entries (`versions[]` history, README link, changelog) |
247
+ | `authors/<authorId>.json` | publish (config is the truth) | identity/store title/public key/homepage sections + this repo's repos segment |
248
+ | `collections/<id>.json` + root string refs | publish | collections declared in config (split form) |
249
+
250
+ - Same-version reruns are intercepted (existing Release tag → bump first); new versions append history automatically;
251
+ - `--dry-run` previews every action; `--yes` for CI;
252
+ - publish updates the **remote** repo files — the closing hint reminds you to `git pull` your local clone.
253
+
254
+ ---
255
+
256
+ ## 10. How others use your repo
257
+
258
+ - Paste the repo URL (or the raw `marketplace.json` direct link) into the LinkDesk store's "add source";
259
+ - Official endorsement = a PR on the official catalog repo adding your source to `sources[]` (endorsement, not a copy — you publish new versions in your own repo and the official list **never goes stale**); the application flow and the "official ✓" badge live in the official catalog repo's inclusion docs;
260
+ - All sources merge into **one shared pool**: category pages mix every source together; your plugins carry a source badge; the author domain (author card / store front) is a facade on top of the pool and never removes plugins from it.
261
+
262
+ ---
263
+
264
+ ## 11. Versions & compatibility
265
+
266
+ - The schema ships with `@linkdesk/marketplace-kit`; **schema changes always ship** (a yellow lamp watches it automatically);
267
+ - Old catalog files stay readable forever (every new field is optional); old store versions ignore unknown keys;
268
+ - the `$schema` line gives VS Code live completion and squiggles — upgrade the kit to get completion for new fields.
269
+
270
+ ---
271
+
272
+ ## 12. AI collaboration notes (for automation assistants)
273
+
274
+ - For any structural question run `npx marketplace-kit validate` first — **the error output is the spec**: it prints the available lists and allowed keys; fix accordingly, no need to read this guide;
275
+ - When generating scaffolds/author blocks/collection files, follow the kit's JSON Schema (`$schema` references let editors and AI share one contract);
276
+ - License issuing has exactly two commands (`keygen` / `sign-license`); the key format is constrained solely by the shell's verifier — never invent a second signature format;
277
+ - This guide and the kit move together per release: validate's output is fresher than this page (list extensions land in the error text first).
@@ -25,6 +25,7 @@
25
25
  | **做一个主题**(不写代码) | [主题/01-做一个主题插件](主题/01-做一个主题插件.md) | → [主题/02-主题字段速查](主题/02-主题字段速查.md) |
26
26
  | **给我的插件加一条配置项** | [20-我的插件加一条配置项](20-我的插件加一条配置项.md) | → [03-插件contributes规范](03-插件contributes规范.md) |
27
27
  | **让 AI / 快捷键 / 命令面板也能操作我的插件** | [21-插件命令化规范](21-插件命令化规范.md) | → [03-插件contributes规范 §3.1](03-插件contributes规范.md)(`commands` 全字段) |
28
+ | **把我的仓库变成市场源 / 开作者主页 / 策划合集(含付费)** | [23-市场目录与作者主页](23-市场目录与作者主页.md) | → `@linkdesk/marketplace-kit`(`init` / `validate` / `keygen`)· [06-plugin.json规范](06-plugin.json规范.md)(分类声明字段) |
28
29
  | **往某个菜单(右键/齿轮/汉堡)里加一项** | [22-菜单贡献点](22-菜单贡献点.md) | → [21-插件命令化规范](21-插件命令化规范.md)(先把动作做成命令)· §三「载荷」讲共享件弹菜单时 `commandArgs` 与 `context` 怎么分 |
29
30
  | **让用户挑「这个文件用哪只插件打开」(打开方式选择器)** | [21-插件命令化规范 §2.1](21-插件命令化规范.md)(经 `@linkdesk/plugin-sdk` 调**宿主命令**) | → [19-组件速查](19-组件速查.md)(`OpenWithPicker`:⛔ 别自己实现面板)· [06-plugin.json规范 `fileAssociations`](06-plugin.json规范.md)(先声明你能开的类型) |
30
31
  | **让几个区域联动**(侧栏选中 → 主区切换 → 状态栏更新) | [18-区域间互动](18-区域间互动.md) | → [07-插件间通信](07-插件间通信.md) |
@@ -182,6 +183,7 @@ npm run publish # 发布到你自己的 GitHub 仓(上
182
183
  | **20** | **[20-我的插件加一条配置项](20-我的插件加一条配置项.md)** | 最小做法:声明一条 → 设置页自动出现 → 代码里读 |
183
184
  | **21** | **[21-插件命令化规范](21-插件命令化规范.md)** | **让 AI/快捷键/命令面板能操作我的插件**——动作做成命令的规范 + 作者检查清单;§2.1 讲调**宿主命令**(`SHELL_COMMANDS` / helper)而不硬编码其 id |
184
185
  | **22** | **[22-菜单贡献点](22-菜单贡献点.md)** | **把一个动作放进宿主的菜单**——14 个槽位清单 + `group`/`when` 约定 + 公共 context key 表 + **菜单载荷律**(`commandArgs` vs `context`) |
186
+ | **23** | **[23-市场目录与作者主页](23-市场目录与作者主页.md)** | **市场数据作者面**——单插件仓/多插件仓/独立市场仓三形态 · 分类封闭名单全表 · `marketplace.json`/作者块/合集两读字段表 · 首页菜谱 · kit 使用 · 付费签发与官方收录 |
185
187
  | **T1** | **[主题/01-做一个主题插件](主题/01-做一个主题插件.md)** | 做主题的动线(零代码) |
186
188
  | **T2** | **[主题/02-主题字段速查](主题/02-主题字段速查.md)** | 配方字段与 CSS 变量的对照索引 |
187
189
 
@@ -29,7 +29,7 @@
29
29
 
30
30
  | 事实 | 说明 |
31
31
  |------|------|
32
- | **契约 47 命名空间** | 池注入 45(壳侧独有面 `bridge`、`storage` 不进池);壳注入 26;mock 注入 13——**以 `check-namespace-matrix` 门禁的活读数为准**(本行已由它机械对账,⛔ 别照 `surfaces.ts` 里的注释抄,那份也在漂) |
32
+ | **契约 49 命名空间** | 池注入 47(壳侧独有面 `bridge`、`storage` 不进池);壳注入 27;mock 注入 13——**以 `check-namespace-matrix` 门禁的活读数为准**(本行已由它机械对账,⛔ 别照 `surfaces.ts` 里的注释抄,那份也在漂) |
33
33
  | **池 = 插件运行时真相源** | 插件运行在池(pool)preload——池注入的命名空间为 **required**;`bridge` 真壳独有 |
34
34
  | **「仅壳」≠ 插件不可调** | `window.*`/`shell.*`/`hotExit.*`/`getFilePath` 池**实有注入**——旧版把这几面标 ❌ 仅壳是错的 |
35
35
  | **契约必选面漂移已清零** | `env.get(pluginId)` 转发、`clipboard.readText` 壳补、`dialog.openFile` 壳补——三项都已补齐实现,无 `?` 降级 |
@@ -44,7 +44,7 @@
44
44
 
45
45
  **`window.linkdesk.*` 的全部方法签名、入参、返回、载荷类型 = [contracts/linkdesk.d.ts](https://github.com/Encaron/linkdesk/blob/electron/contracts/linkdesk.d.ts)**(自动生成,勿手改)。
46
46
 
47
- - **生成源:** `src/core/api/linkdesk-api.ts` + `linkdesk-api/`(16 域接口)+ `src/core/types/ipc/*` + `src/core/types/pool/*`(wire 载荷类型)
47
+ - **生成源:** `src/core/api/linkdesk-api.ts` + `linkdesk-api/`(17 域接口)+ `src/core/types/ipc/*` + `src/core/types/pool/*`(wire 载荷类型)
48
48
  - **生成器:** `scripts/generate-contract.mjs`(Route C——契约类型文件为源,纯类型打包单文件)
49
49
  - **机械门禁:** preload 双端 `satisfies` 契约面类型 → tsc 漂移门禁;`npm run check` 内 `contracts:check` hash 字节比对
50
50
  - **覆盖矩阵:** 每个命名空间 × 池/壳/mock 四面覆盖 → [命名空间矩阵 §2](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/归一化基建/契约生成/命名空间矩阵.md#2-命名空间--四面覆盖矩阵)
@@ -351,7 +351,7 @@ const file = await window.linkdesk.dialog.openFile({
351
351
  > ⚠️ **通知不是「自动消失的浮卡」**(通知面归一 +更正):右下角窄 toast 链路已整删,**唯一通知面 = 状态栏铃铛宽面板**。作者要知道的三件事:
352
352
  > 1. **通知不弹卡、不抢焦点、不挡操作**——它进铃铛(未读计数 +1),用户点开才看见。别把通知当「必须被看见」的通道:要用户当场决定 → 用 `dialog.confirm`(模态、抢焦点)。
353
353
  > 2. **同来源常驻有配额**——按 `options.source` 分组,每组常驻最多 5 条,超出顶掉同来源最老的。刷屏不会堆成墙,但**也别指望靠通知留长期记录**。
354
- > 3. **键盘可达是「面板可达」,不是「通知可达」**——铃铛可用键盘聚焦打开、面板内可 Tab 走遍、`Esc` 关;但面板**没有焦点陷阱**(非模态,焦点可自由离开)。**别写「按 Tab 就能到我的通知按钮」这种假设**——用户可能根本不开面板;**也别指望有第二呈现面**——通知只有铃铛这一个面(2026-10-01 用户指令重申:右下角「自动消失小卡」这类第二面长过两次、两次都被删)。
354
+ > 3. **键盘可达是「面板可达」,不是「通知可达」**——铃铛可用键盘聚焦打开、面板内可 Tab 走遍、`Esc` 关;但面板**没有焦点陷阱**(非模态,焦点可自由离开)。**别写「按 Tab 就能到我的通知按钮」这种假设**——用户可能根本不开面板。**轻反馈 ≠ 通知**:2026-11-19 用户授权改判后另有轻 Toast 通道(见下节)——短、轻、一句话的回执走 `toasts.show`,需要留存 / 决策 / 进度的仍走通知。
355
355
 
356
356
  **通知主动作按钮(`notifications.show` 的 `actions`):** 失败 / 需要用户行动的通知可带 `actions` 按钮数组——点击走**命令系统**执行(对标 VS Code `showErrorMessage(msg, { title, command })` 动作)。命令 handler 由插件自注册(`commands.registerCommand`):
357
357
 
@@ -403,6 +403,21 @@ await window.linkdesk.notifications.show("同步失败", { source: "myplugin" })
403
403
 
404
404
  > 完整的**行为契约**(不是签名,签名看 `contracts/linkdesk.d.ts`)在 [`01-插件API契约.md`](01-插件API契约.md) §3.2 的 `notifications` 行——本节只给写法,语义以那里为准。
405
405
 
406
+ **轻 Toast(`toasts.show`)——短、轻、一句话的回执(2026-11-19 用户授权恢复):** 「已复制 / 检查完成 / 已刷新」这类**不需要回看**的轻反馈走这条;底部居中、缺省 3s 自动消失、最多 1 个动作。**与通知的分工一句话:Toast 是「路过」,面板是「留存」**——错误 / 需要决策 / 进度 / 长文本仍然走 `notifications.show`:
407
+
408
+ ```tsx
409
+ // 轻提示——底部居中,3s 自动消失;同 key 更新原条目(不叠卡)
410
+ await window.linkdesk.toasts.show({ message: "已复制链接", key: "copy-done" });
411
+ await window.linkdesk.toasts.show({
412
+ message: "检查完成——发现 3 个可用更新",
413
+ severity: "success", // info | success | warning(error 自动转面板)
414
+ key: "check-updates",
415
+ action: { title: "查看", command: "myplugin.openUpdates" },
416
+ });
417
+ ```
418
+
419
+ **降级路由在壳自动判,调用方不预判**:error 级 / 多于 1 个动作 / 文本超两行视觉宽度(中文记 2)/ `ttl ≥ 8000ms` 的条目自动转面板——你只表达意图,落面由壳定,句柄的 `presentation` 字段如实回告实际落在了哪个面。⛔ 不要为「确保它弹出来」而预判后改走别的面(那是第二把尺);⛔ 不要自绘底部提示浮层(所有插件共用同一条通道)。完整契约见 `contracts/linkdesk.d.ts`(`toasts`)。
420
+
406
421
  **富内容确认框(`dialog.confirmContent`):** 要确认框里放**不止一行字**(表单 / 列表 / 截图 / 自定义排版)时用这条——**对话框是壳(居中、遮罩、Esc、焦点锁、点遮罩取消),内容由你的视图自画**(对标 VS Code「对话框是壳、内容插件定」):
407
422
 
408
423
  ```tsx
@@ -595,6 +610,7 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
595
610
  | `ldk-view-skeleton-breath` | 内容加载骨架的呼吸 |
596
611
  | `ldk-welcome-skeleton-breath` | 欢迎页最近列表加载骨架的呼吸 |
597
612
  | `ldk-welcome-in` | 欢迎页入场 fade-up(全页唯一一处入场) |
613
+ | `ldk-tt-in` | 宿主轻 Toast(TransientToast)条目入场位移+淡入 |
598
614
 
599
615
  **引用的名字必须在架子上**——纪律 2 说的是「改名时同笔改引用」;这条是它的另一半,而且**机器会查**:
600
616
  你 `animation` / `animation-name` 里写的名字,要么是**本仓 CSS 里 `@keyframes` 定义过的**,要么是
@@ -0,0 +1,277 @@
1
+ # 23 — 市场目录与作者主页(marketplace.json / 作者块 / 合集)
2
+
3
+ > **一句话**:把你的仓库变成 LinkDesk 插件市场里的一个「源」——最简单什么都不用做(只放 plugin.json),想上架多只插件、开作者主页、策划合集时才需要本文。
4
+ > 本文是**市场数据作者**的规范 + 菜谱:`marketplace.json`(目录)、`authors/<id>.json`(作者块)、`collections/`(合集)三件东西怎么写、怎么自检、怎么发布。
5
+ > 字段级权威 = `@linkdesk/marketplace-kit` 自带的 JSON Schema(编辑器 `$schema` 补全与红波浪线);本地自检 = `npx marketplace-kit validate`。
6
+
7
+ ---
8
+
9
+ ## 一、三种作者形态(先选形态,再动手)
10
+
11
+ | 形态 | 仓库里有什么 | 你要做什么 | 用户看到什么 |
12
+ |:--:|:--|:--|:--|
13
+ | **单插件仓(零配置)** | 只有 `plugin.json` | **什么都不用做** | 仓库地址被加为市场源 → 自动出现你这 1 只插件 |
14
+ | **多插件仓** | `plugin.json`×N + 根 `marketplace.json` | `npx marketplace-kit init` 生成骨架 → 填条目 | 一个源,多只插件 |
15
+ | **独立市场仓** | `marketplace.json` + `authors/<id>.json`(+ `collections/`) | `npx marketplace-kit init --author <你的GitHub用户名>` | 一个源+作者卡+作者主页(多仓聚合) |
16
+
17
+ **选择指引**:
18
+ - 只有一只插件 → **单插件仓,到此为止**(本文其余部分都可以不读)。
19
+ - 多只插件想被一个源带出来 → 多插件仓。
20
+ - 想要**作者卡**(头像/简介/仓库数)与**作者主页**(自己排首页板块)→ 独立市场仓(或多插件仓加作者块);把你所有仓库都声明同一个 `authorId`,市场会自动把它们聚合成一个作者域。
21
+
22
+ ⚠️ **单插件仓不要手写根 `marketplace.json`**——市场读到它(哪怕内容是空的)就不再回落读 `plugin.json`,你的插件会从商店里消失。单插件仓想要作者主页:`init --author` 只补 `authors/<id>.json`,不动根目录文件。
23
+
24
+ ---
25
+
26
+ ## 二、分类声明(主分类 + 小分类,全是「选」不是「创作」)
27
+
28
+ 插件在**自己的 plugin.json** 顶层声明分类(英文 slug):
29
+
30
+ ```json
31
+ {
32
+ "pluginId": "demo-plugin",
33
+ "category": "development",
34
+ "categories": ["code-editing"]
35
+ }
36
+ ```
37
+
38
+ - `category`(单值)= 主分类,决定你在商店分类抽屉里住哪个桶;
39
+ - `categories`(多值,选填)= 小分类副标签,喂商店里的小类筛选 chips 与搜索。
40
+
41
+ ### 2.1 可用清单(只能从这里选,不能自创 slug)
42
+
43
+ | 主分类 | 中文 | 可选小分类 |
44
+ |:--|:--|:--|
45
+ | `development` | 开发 | `code-editing` 代码编辑 · `terminal` 终端 · `vcs` 版本控制 · `runtime` 运行时 · `i18n` 本地化 · `debug` 调试诊断 · `snippets` 代码片段 |
46
+ | `documents` | 文档 | `viewer` 阅读器 · `convert` 格式转换 · `markdown` Markdown · `files` 文件管理 · `office-doc` 办公文档 · `notebook` 笔记本 |
47
+ | `hardware` | 硬件 | `serial` 串口 · `flash` 烧录 · `probe` 设备探针 · `smart-control` 智能控制 · `home-automation` 智能家居 · `sensor` 传感器 · `iot` 物联网 · `can-bus` 总线调试 |
48
+ | `network` | 网络 | `browser` 浏览器 · `chat` 聊天 · `cloud` 网盘 · `download` 下载传输 · `packet-capture` 抓包 · `proxy` 代理 · `remote` 远程连接 |
49
+ | `productivity` | 效率 | `clipboard` 剪贴板 · `notes` 便签 · `ai` AI 助手 · `color` 取色 · `todo` 待办清单 · `timer` 计时专注 · `launcher` 快速启动 · `calculator` 计算器 |
50
+ | `themes` | 主题 | `color-scheme` 配色 · `icon-pack` 图标包 · `font-pack` 字体包 · `wallpaper` 壁纸 · `cursor-set` 光标 · `sound-pack` 音效 |
51
+ | `entertainment` | 娱乐 | `player` 播放器 · `game` 游戏 · `music` 音乐电台 · `comic` 漫画 · `novel` 小说 · `stream` 直播 |
52
+
53
+ ### 2.2 怎么选
54
+
55
+ - 主分类**单选**,从上表 7 桶里挑「装得下你这只插件」的那个;
56
+ - 小分类**选填**,从主分类对应的名单里挑(可以多个);不选也完全合法——你的插件照常显示,只是不参与小类 chips;
57
+ - 实在想不出主分类 → 不声明,插件会进「其他」桶,永远可见(不丢、不报错)。
58
+
59
+ ### 2.3 写了名单外的值会怎样
60
+
61
+ - **不会崩、不会消失**:插件照常上架,落「其他」桶(或小类归「未标注」兜底 chip);
62
+ - **会有提示**:`npx marketplace-kit validate` 会警告,商店来源页也会记一条「声明提示」;
63
+ - 警告信息**直接列出当前可用清单**——照着报错改就行,不用翻文档。
64
+
65
+ ### 2.4 名单会扩充吗
66
+
67
+ 会——由市场运营按需扩(纯数据操作,不需要任何人发版)。**作者要做的只有一件事:以 `marketplace-kit validate` 报错里列出的清单为准**,它永远是最新的。
68
+
69
+ ---
70
+
71
+ ## 三、`marketplace.json` 字段全表(多插件仓 / 独立市场仓的根文件)
72
+
73
+ ```json
74
+ {
75
+ "$schema": "https://unpkg.com/@linkdesk/marketplace-kit/schemas/marketplace.schema.json",
76
+ "plugins": [ "……条目,见下……" ],
77
+ "collections": [ "……可选,见 §五……" ],
78
+ "categoryRail": { "order": ["development", "documents"], "icons": { "development": "lucide:code" } }
79
+ }
80
+ ```
81
+
82
+ **条目字段(`plugins[]`)**——发布(`publish`)会自动维护你工程产出的条目;手填时照下表:
83
+
84
+ | 字段 | 必填 | 说明 |
85
+ |:--|:--:|:--|
86
+ | `id` / `name` / `version` | ✅ | 身份三件(`id` 建议与 pluginId 一致) |
87
+ | `downloadUrl` | ✅ | `.linkdesk-plugin` 分发件直链(GitHub Release 资产) |
88
+ | `versions[]` | ✅ | 版本历史,**最新在前**;每条 `{version, downloadUrl, publishedAt, changelog?}`。目录保留全史——商店详情页只展示最近几版,旧历史不影响显示 |
89
+ | `description` / `license` / `repository` | 选 | 展示与详情页 |
90
+ | `author` / `authorId` | 选 | `author` 显示名(`{name, url}` 或字符串);`authorId` 是**聚合键**(推荐 GitHub 用户名)——同名即聚合作者域,也是「官方 ✓」认证的判定输入 |
91
+ | `icon` / `marketIcon` | 选 | **绝对 URL**(未安装状态也要能打开);`marketIcon` 优先作为商店行图 |
92
+ | `screenshots[]` | 选 | 字符串 = 图片直链;至多 1 个视频项且必须排第一:`{"type":"video","url":"…","poster":"…"}`(不自动播放) |
93
+ | `category` / `categories[]` | 选 | 见 §二 |
94
+ | `pricing` | 选 | 付费声明,见 §八 |
95
+ | `minAppVersion` | 选 | 需要的最低壳版本 |
96
+ | `publishedAt` / `readmeUrl` / `size` | 选 | 发布时间(`versions[]` 任一有即可)/ README 直链 / 字节数 |
97
+
98
+ **根级字段**:`version`/`updatedAt`(发布工具维护);`sources[]` 只有官方目录仓用(已审核第三方源清单,作者不写);`collections`(§五);`categoryRail`(分类展示顺序——slug 顺序数据,写了自己仓的顺序偏好;只官方目录的 rail 生效)。
99
+
100
+ 兼容纪律:**只加字段、不改语义**。旧版市场插件读新目录,认不得的字段自动忽略,永不崩。
101
+
102
+ ---
103
+
104
+ ## 四、首页布置菜谱(作者主页 `homepage.sections`,可复制片段)
105
+
106
+ 作者主页的板块全部声明驱动(`authors/<id>.json` 的 `homepage.sections[]`,按声明顺序渲染)。
107
+ **「按分类浏览」不用声明**——它永远排在最后,作者删不掉。
108
+
109
+ ```jsonc
110
+ // 大屏轮播:3–5 张,自己挑上大屏的插件
111
+ { "type": "hero", "title": "编辑精选", "hint": "店主推荐",
112
+ "slides": [ { "plugin": "demo-plugin", "tag": "主打" } ] }
113
+
114
+ // 合集板块:引用一个合集 id(合集在哪声明见 §五)
115
+ { "type": "collection", "collection": "must-have", "layout": "duo",
116
+ "hint": "大家都在装", "glow": false,
117
+ "more": { "label": "看全部", "target": "category:hardware" } }
118
+
119
+ // 全量网格
120
+ { "type": "grid", "title": "全部插件" }
121
+
122
+ // 榜单:按下载量换排序键的计算位
123
+ { "type": "rank", "top": 6, "scope": "self",
124
+ "more": { "label": "完整榜单", "target": "rank" } }
125
+ ```
126
+
127
+ **板块通用字段**:`title`(板块标题,完全归作者)· `hint`(副题说明字,不声明不渲染)· `glow`(环境光晕,缺省开,`false` 回落中性阴影,⛔ 自定颜色)· `more`(标题旁跳转字:`label` 随意,`target` 封闭集合——`category:<slug>` / `rank` / `repo:<id>`,⛔ 任意网页地址)。
128
+
129
+ 边界:hero 轮播一个店只认第一个(多个会警告,其余就地渲染);`type` 只认 `hero/collection/grid/rank` 四件;声明里引用不存在的合集 → 板块空转并有声明提示。
130
+
131
+ ---
132
+
133
+ ## 五、合集的两种写法(两读并存,选一种)
134
+
135
+ **写法 A(inline,直接写在根文件里)**——适合 1–3 个合集:
136
+
137
+ ```json
138
+ "collections": [
139
+ { "id": "must-have", "title": "装机必备", "layout": "strip",
140
+ "hint": "由店主编排", "items": ["demo-plugin", "demo-tool"], "order": 1 }
141
+ ]
142
+ ```
143
+
144
+ **写法 B(拆分文件夹)**——合集多、或想让首页数据独立维护时:
145
+ 根 `marketplace.json` 的 `collections` 写**字符串 id 引用**,完整声明放 `collections/<id>.json`:
146
+
147
+ ```json
148
+ "collections": ["must-have", "themes-picks"]
149
+ ```
150
+
151
+ ```json
152
+ // collections/must-have.json —— 内容与写法 A 的对象完全一致
153
+ { "id": "must-have", "title": "装机必备", "layout": "strip", "items": ["demo-plugin"], "glow": false, "more": { "label": "看全部", "target": "category:hardware" } }
154
+ ```
155
+
156
+ 规则:
157
+ - 市场看到**字符串引用才去拉对应文件**——什么都不写就零请求(旧目录零负担);
158
+ - 同一个 id 两种写法都出现 → **根文件里的 inline 对象生效**,文件夹那份被忽略并有声明提示(别两边都写);
159
+ - 文件里的声明形状与 inline 完全一致(`id/title/items` 必填,`subtitle/hint/cover/layout/glow/more/order` 选填);
160
+ - 合集 `items` 引用的插件 id 不存在 → 该成员静默跳过(防御语义,商店不炸)。
161
+
162
+ ---
163
+
164
+ ## 六、作者块(`authors/<authorId>.json`)
165
+
166
+ ```json
167
+ {
168
+ "$schema": "https://unpkg.com/@linkdesk/marketplace-kit/schemas/authors.schema.json",
169
+ "authorId": "your-github-username",
170
+ "name": "你的显示名",
171
+ "intro": "一句话介绍(GitHub 能取到头像与名字,这里是非 GitHub 兜底)",
172
+ "storeTitle": "某某的插件商店",
173
+ "publicKey": "……(付费作者才需要,见 §八)",
174
+ "repos": [
175
+ { "id": "main", "name": "主仓", "sourceUrl": "https://raw.githubusercontent.com/you/your-marketplace/HEAD/marketplace.json" }
176
+ ],
177
+ "homepage": { "sections": [ "……§四的菜谱片段……" ] }
178
+ }
179
+ ```
180
+
181
+ - **聚合**:同一个 `authorId` 出现在你每个仓的源根 → 市场自动聚合成一个作者域(头像/名字以 GitHub 为正典);
182
+ - **repos[]**:你的每个市场仓一段(`sourceUrl` = 该仓 marketplace.json 直链)——作者店里的「仓切换卡」由此来;
183
+ - 位置:独立市场仓放仓库根 `authors/` 夹;单插件仓/多插件仓想让插件挂作者域,也可以在自己的仓库根放同名文件(市场按源根寻找)。
184
+
185
+ ---
186
+
187
+ ## 七、marketplace-kit 使用(本地自检与骨架)
188
+
189
+ ```bash
190
+ npm i -D @linkdesk/marketplace-kit
191
+
192
+ npx marketplace-kit init # 生成骨架(自动识别仓形态;不覆盖已有文件)
193
+ npx marketplace-kit init --author your-github-username # 补作者块
194
+ npx marketplace-kit validate ./ # 校验整个目录(含跨文件合集引用)
195
+ npx marketplace-kit validate ./marketplace.json # 校验单文件
196
+
197
+ # 付费作者(见 §八):
198
+ npx marketplace-kit keygen --author your-github-username
199
+ npx marketplace-kit sign-license --key your-github-username.private.key --plugin demo-plugin --exp 30d
200
+ ```
201
+
202
+ - `validate` 的**错误**(结构/未知字段/封闭集合拼错)退出码 1,**警告**(分类名单外、合集引用等声明提示)退出码 0——警告码与商店来源页「声明提示」是同一套词汇,商店里看到什么这里就是什么;
203
+ - 未知字段直接报错并列出可用键(市场解析会静默丢弃认不得的键——拼错了等于没写,宁可发布前拦住)。
204
+
205
+ ---
206
+
207
+ ## 八、付费插件(声明、公钥、签发)
208
+
209
+ 1. **声明定价**(条目级,只展示不裁决):
210
+
211
+ ```json
212
+ "pricing": { "model": "paid", "price": 9.9, "currency": "USD",
213
+ "licenseUrl": "https://你的销售页", "refundUrl": "https://你的退款说明", "trialDays": 14 }
214
+ ```
215
+
216
+ 收钱发生在你自己的销售页(LinkDesk 不代收、不抽成);`trialDays` 只是展示(真试用逻辑在你插件代码里做)。
217
+
218
+ 2. **生成密钥对**:`npx marketplace-kit keygen --author your-github-username` → 私钥文件(**别提交进 git、别外传;丢了换钥 = 旧密钥全部失效**)+ 公钥(一行 base64)。
219
+
220
+ 3. **放置公钥**:粘进 `marketplace.config.json` 的 `publicKey`(发布时会写进作者块)或直接粘进 `authors/<id>.json` 的 `publicKey` 字段。
221
+
222
+ 4. **签发许可**:买家付款后,用其机器指纹签发——
223
+
224
+ ```bash
225
+ npx marketplace-kit sign-license --key your-github-username.private.key \
226
+ --plugin demo-plugin --machine <买家的machineFingerprint> --exp 2027-12-31
227
+ ```
228
+
229
+ `--exp` 支持 `30d`/`12w`/`6m`/`1y` 或具体日期;`--machine` 给了就是一机一码(买家在壳「本机信息」里查指纹)。把输出的 `v1.…` 密钥发给买家,其在商店「我有密钥」粘贴即完成**离线验签**(壳本地完成,无服务器)。
230
+
231
+ 5. **退款 / 换钥**:退款走你的销售渠道;换钥 = 重新 keygen + 更新公钥 + 重发旧买家的许可(旧公钥签发的密钥随即失效)。
232
+
233
+ ---
234
+
235
+ ## 九、发布流程(多插件仓 / 独立市场仓)
236
+
237
+ ```bash
238
+ npm run build # 产出 <id>.linkdesk-plugin(每只插件各自工程)
239
+ npm run publish # linkdesk-plugin-sdk publish:建 GitHub Release → 传分发件 → 更新本仓 marketplace.json
240
+ ```
241
+
242
+ 工程根放了 `marketplace.config.json`(`init` 生成)时,`publish` 会**同笔维护作者面文件**:
243
+
244
+ | 文件 | 谁写 | 内容 |
245
+ |:--|:--|:--|
246
+ | `marketplace.json` | publish | 你的插件条目(`versions[]` 历史、README 直链、版本日志) |
247
+ | `authors/<authorId>.json` | publish(以 config 为准) | 身份/店名/公钥/主页板块声明 + 本仓的 repos 段 |
248
+ | `collections/<id>.json` + 根级字符串引用 | publish | config 里声明的合集(拆分写法) |
249
+
250
+ - 同版本重跑会被拦(Release tag 已存在 → 先 bump 再发);新版本自动追加历史;
251
+ - `--dry-run` 先看将执行的动作;`--yes` 给 CI;
252
+ - publish 更新的是**远端**仓库文件,收尾提示会提醒你 `git pull` 同步本地。
253
+
254
+ ---
255
+
256
+ ## 十、别人怎么用你的仓
257
+
258
+ - 把仓库地址(或 raw `marketplace.json` 直链)粘进 LinkDesk 市场「添加市场源」;
259
+ - 官方收录 = 在官方目录仓提交 PR 把你的源加进 `sources[]`(收录是信任背书,不复制你的条目——你发新版官方那份**永不过期**);认证流程与「官方 ✓」徽标见官方目录仓的收录说明;
260
+ - 所有源合并进**同一个池**:分类页混合展示所有来源;你的插件带来源徽标;作者域(作者卡/作者主页)是池之上的门面,不抽走任何插件。
261
+
262
+ ---
263
+
264
+ ## 十一、版本与兼容
265
+
266
+ - Schema 随 `@linkdesk/marketplace-kit` 发版;**动 schema 必发版**(黄灯自动盯);
267
+ - 旧目录文件永远可读(新字段全部可选);旧版市场插件读新目录,认不得的键自动忽略;
268
+ - `$schema` 一行让 VS Code 即时补全与报错——升级 kit 版本即可拿到新字段的补全。
269
+
270
+ ---
271
+
272
+ ## 十二、AI 协作面(给自动化助手)
273
+
274
+ - 一切结构问题先跑 `npx marketplace-kit validate`——**报错即规范**:错误信息直接列出可用清单与可用键,照着改即可,不需要翻本文档;
275
+ - 生成骨架/作者块/合集文件时以 kit 的 JSON Schema 为准(`$schema` 引用让编辑器与 AI 共用同一份契约);
276
+ - 许可签发只有两条命令(`keygen` / `sign-license`),密钥格式由壳的验签实现唯一约束——不要自己发明第二套签名格式;
277
+ - 本文档与 kit 随版本同步:validate 的输出比本文更“新”(名单扩充时先反映在报错里)。
@@ -88,6 +88,16 @@
88
88
  "type": "string",
89
89
  "description": "Author name"
90
90
  },
91
+ "category": {
92
+ "type": "string",
93
+ "description": "Primary marketplace category slug — the single value that decides which category drawer the plugin files under in the Plugin Store (Marketplace-Store v2). Closed whitelist (2026-11-20: declaring outside it is a declaration warning, not an error; the store files such an entry under its Other bucket): development · documents · hardware · network · productivity · themes · entertainment. Category is data, not code: the display name lives in the marketplace's i18n value table, so declare a lowercase slug only. Omitted → the store's Other bucket. Mirrors the catalog entry `category` (copied into marketplace.json by publish).",
94
+ "pattern": "^[a-z][a-z0-9-]*$"
95
+ },
96
+ "categories": {
97
+ "type": "array",
98
+ "description": "Secondary category slugs (sub-category chips/tags) — feed search and sub-category chips; the primary drawer is decided by `category` alone so an entry never appears twice in the grid. Closed whitelist per primary category (2026-11-20; unknown slugs are declaration warnings, not errors): development: code-editing · terminal · vcs · runtime · i18n · debug · snippets; documents: viewer · convert · markdown · files · office-doc · notebook; hardware: serial · flash · probe · smart-control · home-automation · sensor · iot · can-bus; network: browser · chat · cloud · download · packet-capture · proxy · remote; productivity: clipboard · notes · ai · color · todo · timer · launcher · calculator; themes: color-scheme · icon-pack · font-pack · wallpaper · cursor-set · sound-pack; entertainment: player · game · music · comic · novel · stream. Omitted → no chips; the plugin stays in the All list.",
99
+ "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" }
100
+ },
91
101
  "entry": {
92
102
  "type": "string",
93
103
  "description": "Entry file path, relative to the plugin directory. Required for view/card/protocol."
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.77",
3
+ "version": "0.1.78",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [