@linkdesk/plugin-docs 0.1.68 → 0.1.70
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/03-contributes-spec.md +33 -0
- package/docs/04-distribution-format.md +19 -3
- package/docs/06-plugin-json-spec.md +16 -1
- package/docs/19-component-cheatsheet.md +14 -0
- package/docs/22-menu-contribution-points.md +17 -9
- package/docs/zh/03-/346/217/222/344/273/266contributes/350/247/204/350/214/203.md +32 -0
- package/docs/zh/04-/346/217/222/344/273/266/345/210/206/345/217/221/346/240/274/345/274/217.md +19 -3
- package/docs/zh/06-plugin.json/350/247/204/350/214/203.md +16 -1
- package/docs/zh/19-/347/273/204/344/273/266/351/200/237/346/237/245.md +14 -0
- package/docs/zh/22-/350/217/234/345/215/225/350/264/241/347/214/256/347/202/271.md +13 -7
- package/package.json +1 -1
|
@@ -463,6 +463,35 @@ No `font` section → zero custom fonts (codicon fallback / a pure image-asset t
|
|
|
463
463
|
|
|
464
464
|
> **🔥 mappings JSON contract (established — icon-theme.schema.json rewritten to align with the engine's normalizeIconThemeMappings)**: the mappings file that `path` points to is validated against `icon-theme.schema.json` — inside the repo that is `public/schemas/icon-theme.schema.json` (`npm run check` chains `check-theme-schema.mjs`, which also scans `contributes.iconThemes`); for npm authors it is the `schemas/icon-theme.schema.json` shipped with `@linkdesk/plugin-sdk` plus the SDK's `validateIconThemeJson` (the same schema file, so the rules never drift). A runtime parse failure with warn/toast is the second line of defense. Files should begin with `"$schema"` pointing at the schema to get editor IntelliSense.
|
|
465
465
|
|
|
466
|
+
**Starting from an existing icon pack (bulk import)**: a few hundred mappings are not something you write by hand. If you are starting from a VS Code `iconTheme` (Material Icon Theme, vscode-icons, …), the SDK converts it and copies only the assets your mappings really reference:
|
|
467
|
+
|
|
468
|
+
```bash
|
|
469
|
+
npm pack material-icon-theme # any package shipping dist/<x>-icons.json + icons/*.svg
|
|
470
|
+
tar xzf material-icon-theme-*.tgz
|
|
471
|
+
npx @linkdesk/plugin-sdk import-icon-theme package/dist/material-icons.json \
|
|
472
|
+
--name material --out icons/material.json --assets icons/material --list icon-import.json
|
|
473
|
+
```
|
|
474
|
+
|
|
475
|
+
What it does: `iconDefinitions[k].iconPath` → the `imagePath` form; upstream `fileExtensions` keys gain the leading dot (`ts` → `.ts`); the five top-level default icons above are carried over; **only referenced SVGs are copied** (upstream packs carry a thousand or more). Flags: `--name` (theme name; default = the source file's basename), `--out` (default `icons/<name>.json`), `--assets` (default `icons/<name>/`), `--icons-dir` (where the upstream SVGs live; default `<source dir>/../icons`). It prints a ready-to-paste `contributes.iconThemes` snippet, and reminds you to ship the upstream LICENSE.
|
|
476
|
+
|
|
477
|
+
**Your editing decisions stay in your own repo** — `--list` points at a manifest you keep beside your sources, so the artifact can be regenerated byte-identically later:
|
|
478
|
+
|
|
479
|
+
```json
|
|
480
|
+
{
|
|
481
|
+
"extensions": ["ts", "tsx", "rs"],
|
|
482
|
+
"fileNames": ["package.json", "readme.md"],
|
|
483
|
+
"folders": ["src", "docs"],
|
|
484
|
+
"overrides": { "o": "lib" },
|
|
485
|
+
"localIcons": { "uvprojx": "uvprojx" }
|
|
486
|
+
}
|
|
487
|
+
```
|
|
488
|
+
|
|
489
|
+
- `extensions` / `fileNames` / `folders` — which upstream keys you want (omit one = all of them; a key upstream does not have is skipped **and reported**, so a typo is visible instead of silent);
|
|
490
|
+
- `overrides` — send an extension to a different upstream definition (when upstream's own classification does not fit your context);
|
|
491
|
+
- `localIcons` — your own artwork, living at `<assets>/<name>.svg`: written into the mappings, **never copied from upstream**, and a missing file is a hard error (that mapping would 404 at runtime).
|
|
492
|
+
|
|
493
|
+
Leave `--list` off entirely and you get every mapping upstream declares — the zero-setup path when you have no opinion yet.
|
|
494
|
+
|
|
466
495
|
**id naming rule:** an icon-theme id is judged on **one thing only** — it must **not** be the host fallback id `default` (red: the id is not registered, plus one `console.error`). The "carry your repo prefix" criterion is **not applied here**: an icon-theme id is a **registration key** (the value users store in `app.iconTheme`), so renaming it means migrating old values for no gain ⇒ it stays as it is. ⚠️ **Correction, 2026-10-01**: the dropdown **now renders the `label`** (display path wired up — see the exemption note below) — to make it read better in the dropdown, translate the `label` (in your own dictionary), ⛔ not the id.
|
|
467
496
|
|
|
468
497
|
```
|
|
@@ -736,6 +765,10 @@ useEffect(() => {
|
|
|
736
765
|
}, []);
|
|
737
766
|
```
|
|
738
767
|
> **`when: "false"` = a purely programmatic command that stays out of the command palette** — titleActions-only commands are declared this way, which keeps them from cluttering Ctrl+Shift+P. The shell's unified renderer `ViewTitleActions.tsx` has two consumers: the panel tab bar (the active view) + the sidebar section collapse header. For a real example see `08 §3`.
|
|
768
|
+
> ⚠️ The single-parameter `(args)` works here because titleActions hands over **one object** (the `args` field is
|
|
769
|
+
> that object). ⛔ **Do not carry this form over to `ContextMenu` items**: that path **spreads** the payload
|
|
770
|
+
> (`handler(...args)`), so an array payload loses one layer and the menu item silently does nothing. Menu items are
|
|
771
|
+
> always written in **rest form** `(...args)` — see [22, "The menu payload law"](22-menu-contribution-points.md).
|
|
739
772
|
|
|
740
773
|
### 3.12 `contributes.langDefs` — programming language declarations (main process)
|
|
741
774
|
|
|
@@ -102,10 +102,26 @@ Wording discipline (hard constraint 11): don't frame it as two categories "built
|
|
|
102
102
|
|
|
103
103
|
### minAppVersion / requires / permissions
|
|
104
104
|
|
|
105
|
-
All three are declared in the schema (see [03-contributes](03-contributes-spec.md)) and none is enforced at install time—their semantics align with [02 Lifecycle §9](02-plugin-lifecycle.md)
|
|
105
|
+
All three are declared in the schema (see [03-contributes](03-contributes-spec.md)) and none is enforced at install time—their semantics align with [02 Lifecycle §9](02-plugin-lifecycle.md).
|
|
106
|
+
|
|
107
|
+
#### minAppVersion — **the oldest app version your plugin runs on**
|
|
108
|
+
|
|
109
|
+
Below it the **loader refuses to load you** (toast "requires app version ≥X" + `markLoadFailed`). 🔴 What the user gets is **the whole plugin unusable**, not "one feature missing" — so **too low is far more dangerous than too high**.
|
|
110
|
+
|
|
111
|
+
**How you set it: not the shell you tested on, the things you actually use.**
|
|
112
|
+
|
|
113
|
+
- Shared components are **served by the shell** (only the shell's copy exists at runtime, see [19 §2](19-component-cheatsheet.md)); "which shell first shipped this export" is a **fact** — that is exactly [the table in 19 §2.1](19-component-cheatsheet.md) (generated from the shell repo's export-surface ledger, ⛔ not hand-written).
|
|
114
|
+
- You **imported** an export statically ⇒ you need at least the shell that first had it. Take the **maximum** `since` over all imported names — that is your floor.
|
|
115
|
+
- **You never compute it yourself**: `@linkdesk/plugin-sdk` does. `npm run lint` prints the number to use; `npm run verify` turns CI red; `build` / `publish` block **before writing a distribution artifact** (⛔ a dishonest declaration should never be packaged). ⚠️ `lint` is **WARN-level and never fails** — it tells you, it does not stop you; do not read "lint ran clean" as "the declaration is right".
|
|
116
|
+
|
|
117
|
+
**Three things that catch people out:**
|
|
118
|
+
|
|
119
|
+
- 🔴 **A static `import` has no partial downgrade.** Importing an export that an older shell lacks at the top level means **the whole plugin fails to link** (not "that feature does not appear"). If you want users on older shells to keep the rest of your plugin, switch that one to a **dynamic `import()`** or a **runtime guard** — ⚠️ **that is your choice, not a requirement**: when to load is your call, the shell does not make it for you and the gate will not fail you for it.
|
|
120
|
+
- 🔴 **The default `dev` cannot show you this class of problem.** The default `dev` = **mocked host + the `@latest` ui from your `node_modules`** — every component is there and renders fine, so everything stays green. **To expose it you must either `dev --real` against a real shell or install the package into a real shell.**
|
|
121
|
+
- 🔴 **`dev --real` is one-directional**: it answers "**does this run on this shell**", **not** "**what is the oldest shell I can run on**". For the floor, read the gate output above.
|
|
122
|
+
|
|
123
|
+
#### requires / permissions
|
|
106
124
|
|
|
107
|
-
- `minAppVersion` — checked at load time (not satisfied → toast + skip)
|
|
108
|
-
- **Mechanical gate (SDK lint)**: consuming `@linkdesk/ui` at runtime ⇒ `plugin.json` must declare `minAppVersion` ≥ `0.2.13` (the UI re-anchor version — vendor supply of shared components exists only from that shell onward; `import type` is exempt as compile-time-erased). Enforced by `linkdesk-plugin-sdk lint` (`check-ui-min-app-version`), no disable exit
|
|
109
125
|
- `requires` — runtime dependency orchestration applies (missing dependency → suspend as PENDING + cycle fail-loud + cascading uninstall in reverse topological order, see [02 §4](02-plugin-lifecycle.md))
|
|
110
126
|
- **Auto-install at install time (shell-side, opt-in via the request)**: when the install request carries a catalog source URL (the marketplace passes the listing's source), missing `requires` dependencies are installed automatically **inside the same install job** — inline and recursive, no second concurrency slot; a failing dependency fails the parent job (naming the dependency) and rolls back the parent's extracted files so a retry starts clean. Already-installed dependencies are skipped; disabled ones are never auto-enabled. Declaring `requires` is all an author does — no shell changes needed
|
|
111
127
|
- `permissions` — declaring them informs the user; the authorization model is still pending
|
|
@@ -244,7 +244,7 @@ Multi-theme package:
|
|
|
244
244
|
| `suggests` | `array` | Optionally related plugins `[{ plugin: string, reason: string }]` |
|
|
245
245
|
| `requires` | `string[]` | Plugin-level activation dependencies — declared by pluginId; at load time dependencies are loaded before this plugin. No version constraints. See "The `requires` field in depth" below |
|
|
246
246
|
| `screenshots` | `string[]` | Array of screenshot URLs (enabled in Phase 5+) |
|
|
247
|
-
| `minAppVersion` | `string` | Minimum app version requirement |
|
|
247
|
+
| `minAppVersion` | `string` | Minimum app version requirement — **an older shell refuses to load the whole plugin**; gated when you consume `@linkdesk/ui`, see "The `minAppVersion` field in depth" below |
|
|
248
248
|
| `docs` | `string` | Bundled documentation path (for resource plugins) |
|
|
249
249
|
| `cardDocMap` | `object` | Card ID → documentation anchor mapping |
|
|
250
250
|
| `i18n` | `object` | Plugin-bundled translations `{ "en": "i18n/en.json", "ja": "i18n/ja.json" }` — key = the plugin UI's source text (the author's native language is recommended). It lives under `contributes.i18n`, not at the top level. 🔴 **Text your plugin declares must be translated in your own repo** (whoever declares it translates it — see `03 §3.9`) |
|
|
@@ -259,6 +259,21 @@ These two fields did exist during early development, but they **never had a read
|
|
|
259
259
|
|
|
260
260
|
> **Writing them into `plugin.json` has no effect; they are simply ignored** (the top level uses lenient validation, so writing them raises no error — which makes them a lie). **If you copied these two fields from an old tutorial or an old commit → delete them and switch to files.**
|
|
261
261
|
|
|
262
|
+
### The `minAppVersion` field in depth
|
|
263
|
+
|
|
264
|
+
**Semantics**: the **oldest app version your plugin runs on**. Below it the loader **refuses to load the whole plugin** (toast "requires app version ≥X" + `markLoadFailed`) — the user sees a **plugin that does not work**, not "one feature missing". ⇒ **too low is far more dangerous than too high**.
|
|
265
|
+
|
|
266
|
+
**How you set it**: **not the shell you tested on, the things you actually use**. Shared components are served by the shell, and "which shell first shipped this export" is a fact (that is [the table in 19 §2.1](19-component-cheatsheet.md), generated from the shell repo's ledger); take the **maximum** `since` over the exports you **import statically** and that is your floor. **You never compute it yourself** — the tooling does:
|
|
267
|
+
|
|
268
|
+
**This is gated** (leg `check-ui-min-app-version`, shipped inside `@linkdesk/plugin-sdk`):
|
|
269
|
+
|
|
270
|
+
- `npm run lint` prints the number to use (⚠️ WARN-level, **never fails** — it tells you, it does not stop you); `npm run verify` turns your CI red; `build` / `publish` block **before writing the artifact**.
|
|
271
|
+
- The rule: declared ≥ floor (floor = baseline ∪ max `since` over your imported names); importing a name that is not in the ledger ⇒ red (a typo or a private API is not a promised export surface).
|
|
272
|
+
- ⛔ **No disable exit** (a disable comment has no effect) — "knowingly putting older-shell users on a shell that lacks that export" is a semantic error, not a legitimate deviation.
|
|
273
|
+
- A plugin that does not consume `@linkdesk/ui` is out of scope for this leg (`minAppVersion` itself is always optional; how to set it when you only use newer shell commands / IPC is your judgement).
|
|
274
|
+
|
|
275
|
+
Full semantics, the three traps (a static import has no partial downgrade / the default `dev` cannot show it / `dev --real` is one-directional) and how to read the error: [04-distribution-format §minAppVersion](04-distribution-format.md).
|
|
276
|
+
|
|
262
277
|
### The `requires` field in depth
|
|
263
278
|
|
|
264
279
|
Plugin-level activation ordering — declares which plugins must be activated before this one is activated.
|
|
@@ -49,6 +49,20 @@ The version of `@linkdesk/ui` **moves on its own** (patch +1 per publish) and is
|
|
|
49
49
|
- **When you do have to move**: only when a **new component / new prop you want** appears in a higher version — that's a deliberate upgrade on your side, not something you're forced into.
|
|
50
50
|
- **Curious which shell a package was cut from**: check `dist/shell-provenance.json` inside the package (shell version + short commit + date).
|
|
51
51
|
|
|
52
|
+
🔴 **But one number does need a table: `since` — the shell version an export first appeared in.** "The package moves on its own" is about the **package**; `minAppVersion` compares **shell versions**, and those two numbers are not the same thing. The table below is generated from the shell repo's export-surface ledger (⛔ hand-editing it fails `npm run check`):
|
|
53
|
+
|
|
54
|
+
<!-- ui-since:begin ⚠️ do not touch this line or the closing one — the lines in between are generated by `npm run ui-surface:regen` -->
|
|
55
|
+
| Since | Components | Hooks & helpers | Types |
|
|
56
|
+
|:--|:--|:--|:--|
|
|
57
|
+
| **0.2.13** | `Badge`, `Button`, `ColorPicker`, `Combobox`, `ContextMenu`, `DynamicSelect`, `FileIconResolver`, `FilePathInput`, `FontFamilySelect`, `FormRow`, `HintCard`, `InlineInput`, `MarkdownView`, `NumberInput`, `OverlayPortal`, `PluginIcon`, `SegmentedRadio`, `SelectBox`, `Slider`, `StringListEditor`, `ThemePicker`, `Toggle` | `useClickPreview`, `useClipboardKeys`, `useDebouncedInput`, `DEFAULT_PLUGIN_IDENTITY_URI`, `inferSliderStep`, `pickIdentityArt`, `urlSourceKey` | `ContextMenuProps`, `IconDescriptor`, `InlineInputHandle`, `ManifestIconShape`, `ResolvedIcon` |
|
|
58
|
+
| **0.2.20** | `HintTip` | — | `HintTipProps` |
|
|
59
|
+
| **0.2.22** | `ReadOnlyText`, `SectionSubtitle` | — | — |
|
|
60
|
+
| **0.2.40** | `BackgroundImagePicker`, `EffectiveBadge`, `SegmentPreviewSwatch`, `SegmentPreviewText`, `SourceBadge` | `useStatusPolling`, `CONFIG_NONE_SENTINEL`, `MIX_FOLLOW_THEME_SENTINEL`, `SETTINGS_RENDER_HINTS`, `SETTINGS_UI_HINTS`, `formatEffectiveValue`, `isSettingsUiHint`, `splitStringList` | `BackgroundImagePickerProps`, `EffectiveBadgeProps`, `RunStatusCommand`, `SourceBadgeKind`, `SourceBadgeProps`, `SourceBadgeSource` |
|
|
61
|
+
| **0.2.48** | `OpenWithPicker`, `PluginCard` | — | `OpenWithHandler`, `OpenWithPickerProps`, `OpenWithRequest` |
|
|
62
|
+
<!-- ui-since:end -->
|
|
63
|
+
|
|
64
|
+
**How to use it**: look up every export you **import statically** and take the largest `since` — that is your `minAppVersion` floor (below it, the whole plugin **fails to load** on that older shell, it is not "one component missing"). You do not have to compute it yourself: `npm run lint` tells you the number to put in (see [04-distribution-format §minAppVersion](04-distribution-format.md)).
|
|
65
|
+
|
|
52
66
|
### 2.2 Three promises the shell makes to authors (each backed by a mechanical gate)
|
|
53
67
|
|
|
54
68
|
| Promise | What it means | Backstop |
|
|
@@ -119,17 +119,25 @@ than by you:
|
|
|
119
119
|
| `context` | **Shared by the whole menu.** When the menu is opened by a shared component, that component supplies it (it is not yours to set) |
|
|
120
120
|
|
|
121
121
|
**The menu payload law.** `context` is **shared by the whole menu**; each item's identity must travel in
|
|
122
|
-
`MenuItemDescriptor.commandArgs`. The host
|
|
123
|
-
|
|
124
|
-
when you consume a shared component's context menu, your
|
|
125
|
-
`args[0]` **and** the shared component's context **at the end**
|
|
126
|
-
(unless that slot has no shared context at all).
|
|
122
|
+
`MenuItemDescriptor.commandArgs`. The host **spreads** the payload into your handler (`handler(...args)`), so the
|
|
123
|
+
handler receives `args = [...commandArgs, context]`. A shared component (for example `PluginCard`) always sends
|
|
124
|
+
**its own** `context` (`PluginCard` = `{pluginId}`) ⇒ when you consume a shared component's context menu, your
|
|
125
|
+
handler must tolerate **both** its own payload in `args[0]` **and** the shared component's context **at the end**
|
|
126
|
+
— ⛔ never assume `args[0]` is your data (unless that slot has no shared context at all).
|
|
127
|
+
|
|
128
|
+
> 🔴 **Write the handler in rest form `(...args)`** — ⛔ not a single parameter `(args)`. A single parameter
|
|
129
|
+
> receives **only the first** argument (`commandArgs[0]`): an array payload gets **one layer stripped**, the parser
|
|
130
|
+
> finds no target, and the menu item **silently does nothing** — with no error anywhere.
|
|
131
|
+
> This is not hypothetical: on 2026-10-06 both gear menus of the settings file-associations manager turned out to be
|
|
132
|
+
> dead exactly this way, while the unit tests stayed **green** — they handed the whole array in as one argument,
|
|
133
|
+
> which happens to match the parser's expectation. Two mechanical guards pin it: the "spread arguments" cases in
|
|
134
|
+
> `electron/preload-pool/commands.test.ts` (host side) and the "single-parameter shape is always rejected" section in
|
|
135
|
+
> `fileAssociationsGearTarget.test.ts` (plugin side).
|
|
127
136
|
|
|
128
137
|
```ts
|
|
129
|
-
// Consuming PluginCard's gear menu: args = [
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
const mine = args?.[0] as { pluginId?: string } | undefined;
|
|
138
|
+
// Consuming PluginCard's gear menu: the handler receives the SPREAD arguments args = [your payload, shared context]
|
|
139
|
+
linkdesk.commands.registerCommand("my-plugin.onCardGear", (...args) => { // 🔴 rest form, ⛔ not (args)
|
|
140
|
+
const mine = args[0] as { pluginId?: string } | undefined;
|
|
133
141
|
if (!mine?.pluginId) return; // no target ⇒ do nothing (never "act on an empty one")
|
|
134
142
|
/* … */
|
|
135
143
|
});
|
|
@@ -458,6 +458,35 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
|
|
|
458
458
|
|
|
459
459
|
> **🔥 mappings JSON 契约(立——icon-theme.schema.json 重写对齐引擎 normalizeIconThemeMappings)**:`path` 指向的 mappings 文件按 `icon-theme.schema.json` 校验——repo 内 = `public/schemas/icon-theme.schema.json`(`npm run check` 链 `check-theme-schema.mjs` 兼扫 `contributes.iconThemes`);npm 作者 = 随 `@linkdesk/plugin-sdk` 分发的 `schemas/icon-theme.schema.json` + SDK `validateIconThemeJson`(同一 schema 文件,规则永不漂移)。运行时解析失败 warn/toast 是第二道防线。文件建议首行 `"$schema"` 引 schema 拿编辑器 IntelliSense。
|
|
460
460
|
|
|
461
|
+
**从一个现成的图标包起步(批量导入)**:几百条映射不是手写的活。若你手里是一个 VS Code `iconTheme`(Material Icon Theme / vscode-icons …),SDK 负责转换,并且**只拷映射真引用到的资产**:
|
|
462
|
+
|
|
463
|
+
```bash
|
|
464
|
+
npm pack material-icon-theme # 任何「dist/<x>-icons.json + icons/*.svg」形态的包
|
|
465
|
+
tar xzf material-icon-theme-*.tgz
|
|
466
|
+
npx @linkdesk/plugin-sdk import-icon-theme package/dist/material-icons.json \
|
|
467
|
+
--name material --out icons/material.json --assets icons/material --list icon-import.json
|
|
468
|
+
```
|
|
469
|
+
|
|
470
|
+
它干的事:`iconDefinitions[k].iconPath` → `imagePath` 形态;上游 `fileExtensions` 的键补上前导点(`ts` → `.ts`);上面那五枚顶层默认图标原样带过来;**只拷被引用的 SVG**(上游整包上千个)。旗标:`--name`(主题名,缺省 = 源文件主名)、`--out`(缺省 `icons/<名>.json`)、`--assets`(缺省 `icons/<名>/`)、`--icons-dir`(上游 SVG 住哪,缺省 `<源文件目录>/../icons`)。跑完会打印一段**可粘贴的 `contributes.iconThemes` 片段**,并提醒你把上游 LICENSE 一并带上。
|
|
471
|
+
|
|
472
|
+
**选哪些图标——这是你的编辑决定,留在你自己的仓里**:`--list` 指向一份与你源码并排保管的清单 ⇒ 产物日后可**逐字节重跑**:
|
|
473
|
+
|
|
474
|
+
```json
|
|
475
|
+
{
|
|
476
|
+
"extensions": ["ts", "tsx", "rs"],
|
|
477
|
+
"fileNames": ["package.json", "readme.md"],
|
|
478
|
+
"folders": ["src", "docs"],
|
|
479
|
+
"overrides": { "o": "lib" },
|
|
480
|
+
"localIcons": { "uvprojx": "uvprojx" }
|
|
481
|
+
}
|
|
482
|
+
```
|
|
483
|
+
|
|
484
|
+
- `extensions` / `fileNames` / `folders`——你要的上游键(**省略某一项 = 全要**;上游没有的键会被跳过**并如实报出**,所以写错是看得见的,不是静默的);
|
|
485
|
+
- `overrides`——把某个扩展名改指上游另一枚定义(上游自己的归类不合你的语境时用);
|
|
486
|
+
- `localIcons`——你自己的图,放在 `<资产目录>/<名>.svg`:只写进映射、**绝不从上游拷**,缺文件直接判错(那条映射运行时会 404)。
|
|
487
|
+
|
|
488
|
+
**完全不传 `--list`** = 导入上游声明的全部映射——你还没拿定主意时的零配置路径。
|
|
489
|
+
|
|
461
490
|
**id 命名规则:** 图标主题 id 只判**一条**——**不得**用宿主兜底 id `default`(判红:该 id 注册不上 + 一条 `console.error`)。**不判**"带不带本仓前缀":图标主题 id 是**注册键**(用户选中的值存在 `app.iconTheme` 里),改名 = 要迁移盘上旧值,收益只落在 id 本身 ⇒ 本轮不动。⚠️ **2026-10-01 更正**:下拉**已改为渲染 `label`**(显示面打通,见下文豁免段)——想让它在下拉里好看,改的是 `label` 的**译名**(本仓字典),⛔ 不是改 id。
|
|
462
491
|
|
|
463
492
|
```
|
|
@@ -724,6 +753,9 @@ useEffect(() => {
|
|
|
724
753
|
}, []);
|
|
725
754
|
```
|
|
726
755
|
> **`when: "false"` = 纯程序化命令不进命令面板**——titleActions 专属命令都这样声明,防止在 Ctrl+Shift+P 里刷屏。壳统一渲染器 `ViewTitleActions.tsx` 两处消费:面板标签栏(活动视图)+ 侧栏 section 折叠头。真实示例见 `08 §三`。
|
|
756
|
+
> ⚠️ 这里的单参 `(args)` 能吃下,是因为 titleActions 送的就是**一个对象**(`args` 字段即该对象)。
|
|
757
|
+
> ⛔ **别把这个写法搬到 `ContextMenu` 的菜单项上**:那条路壳是**展开**传参(`handler(...args)`),
|
|
758
|
+
> 数组型载荷会被剥掉一层 ⇒ 菜单项静默空转。菜单项一律写 **rest 形式** `(...args)`,见 [22 篇「菜单载荷律」](22-菜单贡献点.md)。
|
|
727
759
|
|
|
728
760
|
### 3.12 `contributes.langDefs`——编程语言声明(主进程)
|
|
729
761
|
|
package/docs/zh/04-/346/217/222/344/273/266/345/210/206/345/217/221/346/240/274/345/274/217.md
CHANGED
|
@@ -102,10 +102,26 @@ my-plugin/
|
|
|
102
102
|
|
|
103
103
|
### minAppVersion / requires / permissions
|
|
104
104
|
|
|
105
|
-
三者 schema 均已声明(见 [03-contributes](03-插件contributes规范.md)),安装期不强制——语义与 [02 生命周期 §九](02-插件生命周期.md)
|
|
105
|
+
三者 schema 均已声明(见 [03-contributes](03-插件contributes规范.md)),安装期不强制——语义与 [02 生命周期 §九](02-插件生命周期.md) 对齐。
|
|
106
|
+
|
|
107
|
+
#### minAppVersion —— **你的插件要求的最低主软件版本**
|
|
108
|
+
|
|
109
|
+
低于它 ⇒ **加载器直接拒载**(toast「需要应用版本 ≥X」+ `markLoadFailed`)。🔴 用户拿到的是**整只插件不可用**,不是「少个功能」——所以**写低比写高危险得多**。
|
|
110
|
+
|
|
111
|
+
**它怎么定:不是你测过的壳,是你实际用到的东西。**
|
|
112
|
+
|
|
113
|
+
- 共享组件由**壳**供给(运行时只有壳那一份,见 [19 §二](19-组件速查.md));「某个导出从哪个壳版本起才有」是**事实**——[19 §2.1 那张表](19-组件速查.md)就是它(由壳仓导出面账本生成,⛔ 不手写)。
|
|
114
|
+
- 你**静态导入**了某个导出 ⇒ 你至少要那个壳版本。把所有导入名的 `since` 取**最大值**,就是你的下限。
|
|
115
|
+
- **不用自己推**:`@linkdesk/plugin-sdk` 会替你算。`npm run lint` 报出该填多少;`npm run verify` 让你的 CI 变红;`build` / `publish` **产包前**也会拦(⛔ 声明不诚实的分发件不该被造出来)。⚠️ `lint` 是 **WARN 级、永不 fail**——它告诉你,但不拦你,别把「lint 跑过了」当成「声明对了」。
|
|
116
|
+
|
|
117
|
+
**三条容易踩的:**
|
|
118
|
+
|
|
119
|
+
- 🔴 **静态 `import` 没有「局部降级」**。顶层导入一个旧壳没有的导出 ⇒ **整只插件链接失败**(不是「那个功能不出现」)。想让老壳用户还能用上你的其余部分,就换成**动态 `import()`** 或**运行时 guard**——⚠️ **这是你的选择,不是要求**:什么时候加载是你的事,壳不替你做这个决定,门禁也不会因此判你红。
|
|
120
|
+
- 🔴 **默认 `dev` 测不出这类问题**。默认 `dev` = **mock 宿主 + 你 `node_modules` 里的 `@latest` ui**——组件全在、渲染正常,怎么点都是绿的。**要暴露必须 `dev --real` 对真壳,或把包装进真壳试**。
|
|
121
|
+
- 🔴 **`dev --real` 是单向的**:它回答「**在这个壳上跑得起来吗**」,**不回答**「**我最老能在哪个壳上跑**」。要拿下限,看上面那条门禁的输出。
|
|
122
|
+
|
|
123
|
+
#### requires / permissions
|
|
106
124
|
|
|
107
|
-
- `minAppVersion` —— 加载期校验(不满足 → toast + 跳过)
|
|
108
|
-
- **机械门禁(SDK lint)**:运行时消费 `@linkdesk/ui` ⇒ `plugin.json` 必须声明 `minAppVersion` ≥ `0.2.13`(重锚号——共享组件的集中供给自这一版才存在;`import type` 编译期擦除、豁免)。由 `linkdesk-plugin-sdk lint` 判红(`check-ui-min-app-version`),无豁免出口
|
|
109
125
|
- `requires` —— 运行期依赖编排生效(缺依赖挂起 PENDING + 环 fail-loud + 连带卸载逆拓扑,见 [02 §四](02-插件生命周期.md))
|
|
110
126
|
- **安装期自动装依赖(壳侧,随请求启用)**:安装请求携带来源市场目录时(市场插件随请求带条目来源 URL),`requires` 里缺失的依赖会在**同一个安装任务内**自动先装——内联递归、不占第二个并发槽;某个依赖失败 ⇒ 父任务失败并指名依赖,且父插件本次解压产物自动回滚、重试干净可用。已装的依赖跳过;禁用的**不自动启用**。作者只需声明 `requires`,无需为壳做任何适配
|
|
111
127
|
- `permissions` —— 声明即用户知情,运行期授权模型尚未定案(声明不会带来额外能力)
|
|
@@ -244,7 +244,7 @@ my-plugin/
|
|
|
244
244
|
| `suggests` | `array` | 可选相关插件 `[{ plugin: string, reason: string }]` |
|
|
245
245
|
| `requires` | `string[]` | 插件级激活依赖——按 pluginId 声明,加载时先加载依赖再加载本插件。无版本约束。详见下方「`requires` 字段详解」 |
|
|
246
246
|
| `screenshots` | `string[]` | 截图 URL 数组(Phase 5+ 启用) |
|
|
247
|
-
| `minAppVersion` | `string` |
|
|
247
|
+
| `minAppVersion` | `string` | 最低主软件版本要求——**低于它的旧壳拒载整只插件**;消费 `@linkdesk/ui` 时被门禁校验,详见下方「`minAppVersion` 字段详解」 |
|
|
248
248
|
| `docs` | `string` | 附带文档路径(资源插件联动) |
|
|
249
249
|
| `cardDocMap` | `object` | 卡片 ID → 文档锚点映射 |
|
|
250
250
|
| `i18n` | `object` | 插件自带翻译 `{ "en": "i18n/en.json", "ja": "i18n/ja.json" }`——key=插件 UI 原文(建议作者母语)。放在 `contributes.i18n` 下,非顶层。🔴 **本插件自己声明的可渲染文案,译名必须住本仓**(「谁的仓谁译文」——规则与判据见 `03 §3.9`) |
|
|
@@ -259,6 +259,21 @@ my-plugin/
|
|
|
259
259
|
|
|
260
260
|
> **写进 `plugin.json` 不会生效,只会被忽略**(顶层是宽松校验,写了不报错——所以它骗人)。**若你从旧教程 / 旧提交抄到了这两个字段 → 删掉,改写成文件。**
|
|
261
261
|
|
|
262
|
+
### `minAppVersion` 字段详解
|
|
263
|
+
|
|
264
|
+
**语义**:你的插件要求的**最低主软件版本**。低于它 ⇒ 加载器**拒载整只插件**(toast「需要应用版本 ≥X」+ `markLoadFailed`)——用户看到的是**插件不可用**,不是「少个功能」。⇒ **写低比写高危险得多**。
|
|
265
|
+
|
|
266
|
+
**它怎么定**:**不是你测过的壳,是你实际用到的东西**。共享组件由壳供给,「某个导出从哪个壳版本起才有」是事实([19 §2.1 的表](19-组件速查.md) 就是它,由壳仓账本生成);把你**静态导入**的导出名的 `since` 取最大值,就是你的下限。**不用自己算**——工具会算:
|
|
267
|
+
|
|
268
|
+
**这是被门禁校验的**(腿名 `check-ui-min-app-version`,随 `@linkdesk/plugin-sdk` 下发):
|
|
269
|
+
|
|
270
|
+
- `npm run lint` 报出该填多少(⚠️ WARN 级、**永不 fail**——它告诉你,但不拦你);`npm run verify` 让你的 CI 变红;`build` / `publish` **产包前**拦。
|
|
271
|
+
- 判据:声明 ≥ 地板(地板 = 基线 ∪ 你导入名的 `since` 的最大值);导入了账本里没有的名字 ⇒ 红(拼错 / 私有 API 都不是许诺的导出面)。
|
|
272
|
+
- ⛔ **无豁免出口**(disable 注释无效)——「知情地把旧壳用户放到没有那个导出的壳上」是语义错误,不是合法偏离。
|
|
273
|
+
- 不消费 `@linkdesk/ui` 的插件本条腿不管(`minAppVersion` 本身始终可选;只用了壳的新命令 / 新 IPC 时该填多少由你自己判断)。
|
|
274
|
+
|
|
275
|
+
完整语义、三条易踩的坑(静态导入无局部降级 / 默认 `dev` 测不出 / `dev --real` 是单向的)、报错怎么读:[04-插件分发格式 §minAppVersion](04-插件分发格式.md)。
|
|
276
|
+
|
|
262
277
|
### `requires` 字段详解
|
|
263
278
|
|
|
264
279
|
插件级激活顺序依赖——声明本插件激活前必须先激活哪些插件。
|
|
@@ -50,6 +50,20 @@ import { Button, Toggle, ContextMenu } from "@linkdesk/ui";
|
|
|
50
50
|
- **什么时候必须动**:只有当你**要用的新组件 / 新 prop** 出现在更高版本时——那是你主动升,不是被迫跟。
|
|
51
51
|
- **想知道手里的包剪自哪个壳**:看包里 `dist/shell-provenance.json`(壳版号 + 短 hash + 日期)。
|
|
52
52
|
|
|
53
|
+
🔴 **但有一个数要查表:`since`——「这个导出从哪个壳版本起才有」。** 「包版本自走」说的是**包**;而 `minAppVersion` 比的是**壳版本**,两个号不是一回事。下表由壳仓导出面账本生成(⛔ 手改会被 `npm run check` 打回):
|
|
54
|
+
|
|
55
|
+
<!-- ui-since:begin ⚠️ 本行与下面那行勿动——中间那几行由 `npm run ui-surface:regen` 生成 -->
|
|
56
|
+
| 起于 | 组件 | Hooks / 工具函数 | 类型 |
|
|
57
|
+
|:--|:--|:--|:--|
|
|
58
|
+
| **0.2.13** | `Badge`、`Button`、`ColorPicker`、`Combobox`、`ContextMenu`、`DynamicSelect`、`FileIconResolver`、`FilePathInput`、`FontFamilySelect`、`FormRow`、`HintCard`、`InlineInput`、`MarkdownView`、`NumberInput`、`OverlayPortal`、`PluginIcon`、`SegmentedRadio`、`SelectBox`、`Slider`、`StringListEditor`、`ThemePicker`、`Toggle` | `useClickPreview`、`useClipboardKeys`、`useDebouncedInput`、`DEFAULT_PLUGIN_IDENTITY_URI`、`inferSliderStep`、`pickIdentityArt`、`urlSourceKey` | `ContextMenuProps`、`IconDescriptor`、`InlineInputHandle`、`ManifestIconShape`、`ResolvedIcon` |
|
|
59
|
+
| **0.2.20** | `HintTip` | — | `HintTipProps` |
|
|
60
|
+
| **0.2.22** | `ReadOnlyText`、`SectionSubtitle` | — | — |
|
|
61
|
+
| **0.2.40** | `BackgroundImagePicker`、`EffectiveBadge`、`SegmentPreviewSwatch`、`SegmentPreviewText`、`SourceBadge` | `useStatusPolling`、`CONFIG_NONE_SENTINEL`、`MIX_FOLLOW_THEME_SENTINEL`、`SETTINGS_RENDER_HINTS`、`SETTINGS_UI_HINTS`、`formatEffectiveValue`、`isSettingsUiHint`、`splitStringList` | `BackgroundImagePickerProps`、`EffectiveBadgeProps`、`RunStatusCommand`、`SourceBadgeKind`、`SourceBadgeProps`、`SourceBadgeSource` |
|
|
62
|
+
| **0.2.48** | `OpenWithPicker`、`PluginCard` | — | `OpenWithHandler`、`OpenWithPickerProps`、`OpenWithRequest` |
|
|
63
|
+
<!-- ui-since:end -->
|
|
64
|
+
|
|
65
|
+
**怎么用**:把你**静态导入**的每个导出查一遍,取最大的那个 `since` ⇒ 就是你的 `minAppVersion` 下限(低了,旧壳上**整只插件加载失败**——不是「那个组件不显示」)。不用自己算:`npm run lint` 会直接告诉你该填多少(见 [04-插件分发格式 §minAppVersion](04-插件分发格式.md))。
|
|
66
|
+
|
|
53
67
|
### 2.2 壳对作者的三条承诺(都有机械兜底)
|
|
54
68
|
|
|
55
69
|
| 承诺 | 意思 | 兜底 |
|
|
@@ -115,15 +115,21 @@
|
|
|
115
115
|
| `context` | **整菜单共享**。菜单由共享件弹出时,由那个共享件供给(轮不到你设) |
|
|
116
116
|
|
|
117
117
|
> **菜单载荷律**:`ContextMenu` 的 `context` 是**整菜单共享**的;每一项的身份必须走 `MenuItemDescriptor.commandArgs`。
|
|
118
|
-
>
|
|
119
|
-
>
|
|
120
|
-
>
|
|
118
|
+
> 壳把载荷**展开**喂给你的 handler(`handler(...args)`)⇒ handler 收到的实参是 `args = [...commandArgs, context]`。
|
|
119
|
+
> 共享件(如 `PluginCard`)会固定送**它自己的** `context`(`PluginCard` = `{pluginId}`)⇒ 消费共享件齿轮的插件,
|
|
120
|
+
> handler 必须同时容忍 `args[0]` 是自己的载荷、**末尾**是共享件的 context——⛔ 不要假设 `args[0]` 一定是你的数据
|
|
121
|
+
> (除非该槽位无共享 context)。
|
|
122
|
+
|
|
123
|
+
> 🔴 **所以 handler 必须写成 rest 形式 `(...args)`**——⛔ 不要写单参 `(args)`:单参只收**第一枚**实参
|
|
124
|
+
> (`commandArgs[0]`),数组型载荷会被**剥掉一层**,解析器于是读不到目标 ⇒ 菜单项点了**静默无反应**、不报错。
|
|
125
|
+
> 这不是理论:2026-10-06 实测设置管理器两处齿轮的三条命令全空转,而单测**全绿**——老单测把整包数组当
|
|
126
|
+
> 一枚实参喂进 handler,恰好与解析器同形。机械判据两处:壳侧 `electron/preload-pool/commands.test.ts` 的
|
|
127
|
+
> 「展开实参」两条 + 插件侧 `fileAssociationsGearTarget.test.ts`「单参形状一律判空」一节。
|
|
121
128
|
|
|
122
129
|
```ts
|
|
123
|
-
// 消费 PluginCard 的齿轮菜单:args = [
|
|
124
|
-
//
|
|
125
|
-
|
|
126
|
-
const mine = args?.[0] as { pluginId?: string } | undefined;
|
|
130
|
+
// 消费 PluginCard 的齿轮菜单:handler 收的是**展开后**的实参 args = [自己的载荷, 共享件的 context]
|
|
131
|
+
linkdesk.commands.registerCommand("my-plugin.onCardGear", (...args) => { // 🔴 rest 形式,⛔ 不是 (args)
|
|
132
|
+
const mine = args[0] as { pluginId?: string } | undefined;
|
|
127
133
|
if (!mine?.pluginId) return; // 没有目标 ⇒ 什么都不做(⛔ 不「清了个空的」)
|
|
128
134
|
/* … */
|
|
129
135
|
});
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@linkdesk/plugin-docs",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.70",
|
|
4
4
|
"description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"files": [
|