@linkdesk/plugin-docs 0.1.10 → 0.1.12
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 +55 -2
- package/docs/06-plugin-json-spec.md +20 -1
- package/docs/zh/03-/346/217/222/344/273/266contributes/350/247/204/350/214/203.md +55 -2
- package/docs/zh/06-plugin.json/350/247/204/350/214/203.md +19 -1
- package/docs/zh/plugin.schema.json +2 -2
- package/package.json +1 -1
|
@@ -250,7 +250,22 @@ useEffect(() => {
|
|
|
250
250
|
|
|
251
251
|
**Effect after installation:** the Settings Editor's left navigation tree automatically gains a "CAD Viewer" group → the form is rendered automatically on the right — no hand-written settings UI needed.
|
|
252
252
|
|
|
253
|
-
**Key naming rule:** `<pluginId>.<property
|
|
253
|
+
**Key naming rule:** `<pluginId>.<property>` (**replace the first segment only, leave the stem untouched** — the first segment must be this repo's identity), e.g. `cad.gridSize`, `terminal.baudRate`. The rule is judged at **two levels** — don't conflate them:
|
|
254
|
+
|
|
255
|
+
| Criterion | Severity | Judged by | What happens |
|
|
256
|
+
|:--|:--:|:--|:--|
|
|
257
|
+
| A key must **not** fall inside the **host's reserved key ledger** | 🔴 **red (rejected)** | the shell runtime `ConfigurationRegistry` + the SDK leg `linkdesk/no-unowned-config-key` | The declaration **does not take effect** (the key is never registered, never shows up in the settings page) and one `console.error` is emitted. Your plugin **still installs** — what's rejected is this one key, not your plugin |
|
|
258
|
+
| A **new** key's first segment must be this repo's `pluginId` | 🟡 yellow (advisory) | the SDK leg (**the runtime does not enforce it**) | The report carries a `suggested` name with only the first segment replaced. 19 legacy keys break this rule (e.g. `files.exclude`); the shell renames and migrates those on its own schedule — **write new keys by the rule** |
|
|
259
|
+
|
|
260
|
+
The **host reserved key ledger** (`configKeys`) is a **generated** list that ships inside the SDK package ⇒ machine-readable, never guess it:
|
|
261
|
+
|
|
262
|
+
```
|
|
263
|
+
node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json → "configKeys": [ "app.theme", ... ]
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
Every `app.*` key belongs to the host (its settings, appearance and update surfaces). The ledger **also contains retired keys** — names the host once used and then deleted (e.g. `app.themeColorMode`) **do not free up**: an old `settings.json` may still hold a value under that name, and the host's upgrade-time migration still reads it ⇒ taking it over means overwriting the host's **historical data**.
|
|
267
|
+
|
|
268
|
+
> **Why "taking a host key" is red while "missing your prefix" is only yellow**: taking a host key does **real harm** (it overwrites the host's effective value and can poison internal flag keys such as `app.schemaVersion` — with neither side reporting anything, so what the user sees diverges from how the host actually behaves); whereas "missing the prefix" has 19 counter-examples in the existing corpus, and a hard rule would break those plugins on the spot. Different severity = different tolerance, not "the more important rule is written more strictly".
|
|
254
269
|
|
|
255
270
|
**Reading settings from a plugin (the plugin communication iron rule — only through `window.linkdesk.configuration`):**
|
|
256
271
|
```typescript
|
|
@@ -278,6 +293,12 @@ useEffect(() => {
|
|
|
278
293
|
|
|
279
294
|
The difference from `configuration`: `configuration` defines **your own** settings. `configurationDefaults` suggests values for **someone else's** settings. A value set by the user wins — a weak default only applies when the user has never set that key.
|
|
280
295
|
|
|
296
|
+
**Key ownership:** weak-default keys go through the **same ledger** (`host-reserved.json`'s `configKeys`) —
|
|
297
|
+
|
|
298
|
+
- **You may not suggest a value for a host key** (every `app.*` key is one): the key is rejected and one `console.error` is emitted. Same reasoning as above — that is the host's own settings surface, and dictating its default changes host behaviour.
|
|
299
|
+
- Suggesting values for **your own** keys or for **another plugin's** keys is **legitimate** — that is exactly what this mechanism is for (which is also why it does **not** require your prefix: the prefix criterion applies only to the keys in `contributes.configuration`).
|
|
300
|
+
- **Two plugins suggesting the same key** ⇒ **not rejected**: both stay on record, the merge takes the **last writer** in registration order, and one `console.warn` names the earlier plugin. That is the only legitimate "one key, several authors" shape — and a value the user set by hand in the settings page always outranks any weak default.
|
|
301
|
+
|
|
281
302
|
### 3.6 `contributes.themes` — themes
|
|
282
303
|
|
|
283
304
|
```json
|
|
@@ -301,6 +322,29 @@ The declaration is metadata-only; theme color data is fetched asynchronously at
|
|
|
301
322
|
|
|
302
323
|
> **🔥 Recipe JSON contract (now folded into plugin-sdk)**: the recipe file that `path` points to is validated against `theme.schema.json` — inside the repo that is `public/schemas/theme.schema.json` (`npm run check` chains `check-theme-schema.mjs`, and a format error turns the light red with exit 1 on the spot instead of staying silent); for npm authors it is the `schemas/theme.schema.json` shipped with `@linkdesk/plugin-sdk` plus the SDK's `validateThemeJson` (the same schema file, so the rules never drift). At runtime, a `parseThemeRecipe` toast is the second line of defense. Theme files should begin with `"$schema"` pointing at the schema to get editor IntelliSense (for the npm path see [11-authoring-themes](11-authoring-themes.md) §②).
|
|
303
324
|
|
|
325
|
+
**id naming rule:** the target shape is `<pluginId>.<name>` (**replace the first segment only, leave the stem untouched**), e.g. `theme-pill.pill-bubble`. **One rule covers three ids** — `themes[].id` (recipe), the top-level `id` inside the recipe JSON that `path` points to (recipe), and `colorways[].id` (colorway variant). The severities mirror the key rule above:
|
|
326
|
+
|
|
327
|
+
| Criterion | Severity | Judged by | What happens |
|
|
328
|
+
|:--|:--:|:--|:--|
|
|
329
|
+
| An id must **not** fall inside the **host fallback-id ledger**'s **own space** column | 🔴 **red (rejected)** | the shell runtime `ThemeRegistry` + the SDK leg `linkdesk/appearance-ownership` | The id **is not registered** (the recipe/colorway is simply absent, so users never see it in the picker) and one `console.error` names the fallback id it collided with. Your plugin **still installs** — what is rejected is this one id, not your plugin |
|
|
330
|
+
| A **new** id's first segment should be this repo's `pluginId` | 🟡 yellow (advisory) | the SDK leg (**the runtime does not enforce it**) | The report carries a `suggested` name with only the first segment replaced. The official theme repos still declare 25 ids that break this rule (`mint-soda`, `kraft`, …); the shell renames and migrates those on its own schedule — **write new ids by the rule** |
|
|
331
|
+
| Two recipes of the **same** plugin sharing one **colorway** id | 🟡 yellow + logged | the SDK leg | The shell's contract is that a **colorway id is globally unique** — a cross-recipe duplicate shows up as duplicate entries in the colorway dropdown |
|
|
332
|
+
|
|
333
|
+
The **host fallback-id ledger** ships inside the SDK package and is **split by space** (recipes and colorways are **two namespaces**: `mint-soda` can be both, so the comparison stays **inside the column**, never across):
|
|
334
|
+
|
|
335
|
+
```
|
|
336
|
+
node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
|
|
337
|
+
→ "appearanceRecipeIds": ["dark", "light"] ← recipe column
|
|
338
|
+
"appearanceColorwayIds": ["dark-fallback", "light"] ← colorway column (note: the colorway fallback is dark-fallback, not dark)
|
|
339
|
+
"appearanceIdGrants": { "light": ["theme-defaults"] } ← the exception: who holds that id by grant
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
A fallback id is the layer that keeps **the app rendering after every theme plugin is uninstalled**, so taking one over means taking over the host's fallback surface. **`appearanceIdGrants` is not an allowlist** — it records, **per id**, who holds it: `light` carries a grant because the official theme repo is the *implementer* of the host's light fallback; your plugin is not in that table (and cannot add itself — it is a shell-side public-surface decision) ⇒ it is always judged red.
|
|
343
|
+
|
|
344
|
+
> **Why "taking a fallback id" is red while "missing your prefix" is only yellow**: taking a fallback id does **real harm** (it takes over the host's fallback surface, so themes break once the plugins are uninstalled); whereas "missing the prefix" has 25 counter-examples in the existing corpus, and a hard rule would break those theme repos on the spot. Different severity = different tolerance, not "the more important rule is written more strictly".
|
|
345
|
+
|
|
346
|
+
**Two plugins declaring the same id:** the shell keeps the **first registrant** — the later id **cannot be registered** and one `console.error` names both sides (who arrived first, who was rejected). This is not the same as taking a fallback id: neither side touched the host's names, but **one name has room for one owner only**, so prefixing your own name is what keeps that day from arriving.
|
|
347
|
+
|
|
304
348
|
### 3.7 `contributes.iconThemes` — icon themes
|
|
305
349
|
|
|
306
350
|
```json
|
|
@@ -370,6 +414,12 @@ No `font` section → zero custom fonts (codicon fallback / a pure image-asset t
|
|
|
370
414
|
|
|
371
415
|
> **🔥 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.
|
|
372
416
|
|
|
417
|
+
**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 **shown verbatim in the settings page** (the picker renders the id text), so renaming it would change user-visible text ⇒ it stays as it is. If you want it to read better in the dropdown, change the `label` (display name), not the id.
|
|
418
|
+
|
|
419
|
+
```
|
|
420
|
+
→ "appearanceIconThemeIds": ["default"] ← icon-theme column (this is its only entry)
|
|
421
|
+
```
|
|
422
|
+
|
|
373
423
|
### 3.8 `contributes.icons` — shared icons
|
|
374
424
|
|
|
375
425
|
```json
|
|
@@ -387,7 +437,10 @@ No `font` section → zero custom fonts (codicon fallback / a pure image-asset t
|
|
|
387
437
|
|
|
388
438
|
Plugin A contributes, plugin B references (`"icon": "stm32-chip"` + `"iconSource": "shared"`).
|
|
389
439
|
|
|
390
|
-
|
|
440
|
+
**id naming rule:** the **keys** here *are* the shared icon ids (plugin A contributes, plugin B references) ⇒ prefix them with your repo identity: `<pluginId>.<name>` (🟡 advisory, reported by the SDK leg). The host has no fallback shared icons ⇒ this family has **no red**; but when two plugins declare the **same key**, the later one **cannot be registered** and one `console.error` names both sides (the same arbitration as recipes and colorways).
|
|
441
|
+
|
|
442
|
+
### 3.9 `contributes.languages` — UI language packs
|
|
443
|
+
+ `contributes.i18n` — plugin-bundled translations
|
|
391
444
|
|
|
392
445
|
**Two translation pipelines — don't mix them:**
|
|
393
446
|
|
|
@@ -223,7 +223,7 @@ Multi-theme package:
|
|
|
223
223
|
| Field | Type | Description |
|
|
224
224
|
|---|---|---|
|
|
225
225
|
| `$schema` | `string` | JSON Schema reference path |
|
|
226
|
-
| `pluginId` | `string` | 🔴 **The plugin's identity — forever immutable after publication** (VS Code's `publisher.name` is the counterpart). The install directory `{userData}/plugins/<pluginId>/`, the distribution file name `<pluginId>.linkdesk-plugin`, the marketplace catalog dedupe key, the uninstall tombstone key and update reconciliation all key off it. **Declaring it explicitly is strongly recommended**: without a declaration it falls back to the "project directory name", and repo names and local directory names are free-form — rename the directory and the identity changes with it, with **nothing ever reporting an error**. Charset `^[A-Za-z0-9][A-Za-z0-9._-]
|
|
226
|
+
| `pluginId` | `string` | 🔴 **The plugin's identity — forever immutable after publication** (VS Code's `publisher.name` is the counterpart). The install directory `{userData}/plugins/<pluginId>/`, the distribution file name `<pluginId>.linkdesk-plugin`, the marketplace catalog dedupe key, the uninstall tombstone key and update reconciliation all key off it. **Declaring it explicitly is strongly recommended**: without a declaration it falls back to the "project directory name", and repo names and local directory names are free-form — rename the directory and the identity changes with it, with **nothing ever reporting an error**. Charset `^[A-Za-z0-9][A-Za-z0-9._-]*$`, **plus three banned names** (see "The three identity bans" below). Rules and the empirical evidence behind them are in [16-naming-conventions](16-naming-conventions.md) |
|
|
227
227
|
| `core` | `boolean` | `true` = **UI accidental-uninstall guard flag** (matching the newer wording in the field table above) — the uninstall button on the detail page is hidden/disabled; **no behavioral privileges and not a category**: the API/command layers can still uninstall and disable it, and uninstalling writes a `removed` tombstone. Defaults to `false` |
|
|
228
228
|
| `distribution` | `string` | ⚠️ **Legacy field** (since the single-root flattening on 2026-09-05 it no longer maps to any directory; the install side always normalizes it to `user`; already marked deprecated in the schema). **Third parties must not fill this in** |
|
|
229
229
|
| `factoryRole` | `string` | System slot role: `"settings"` \| `"marketplace"`. **Filling it in = form 2 (replace / switch into the slot); omitting it = form 1 (coexist as an ordinary view plugin)** — see "The `factoryRole` field in depth" below |
|
|
@@ -645,6 +645,25 @@ plugins/<pluginId>/ ← repo source tree (flat single root; directory
|
|
|
645
645
|
`<pluginId>` = folder name = the plugin's unique identifier (the only source of identity — the loader derives pluginId from the directory name; the schema has no top-level pluginId field). Naming rules:
|
|
646
646
|
- lowercase English + hyphens: `gps-map`, `protocol-sbq`, `theme-dracula`
|
|
647
647
|
- no app name, no version number: `terminal`, not `v3-terminal`
|
|
648
|
+
- **never one of the three banned names below**
|
|
649
|
+
|
|
650
|
+
#### The three identity bans
|
|
651
|
+
|
|
652
|
+
| Banned | Why |
|
|
653
|
+
|:--|:--|
|
|
654
|
+
| `app` · `appearance` · `update` | **These three are the host's own identities**: the shell registers its general settings under `app`, its appearance settings under `appearance`, and its update settings under `update`. A plugin using one of them ⇒ **collision detection can never fire** (the host itself holds that identity, so it is always the first registrant), and **uninstalling removes the host's own entry** (unregistration keys off identity) — uninstall your plugin and the host's settings group disappears with it |
|
|
655
|
+
| the `ldk-` prefix | Reserved for the shell / SDK's **internal names** (everything starting with `ldk-` is kept for the product line itself). A third party taking it ⇒ a future shell plugin of the same name is guaranteed to collide, and the user pays for the collision (install fails / update reconciliation goes wrong) |
|
|
656
|
+
|
|
657
|
+
**Where it is blocked (all three sites):** ① the negative assertion in `plugin.schema.json`'s `pluginId` pattern (your editor and IDE flag it on the spot) — the schema ships in your project at `node_modules/@linkdesk/plugin-sdk/schemas/plugin.schema.json`; ② the SDK's `validate` / `lint` (reported from your own repo); ③ the shell's install-time `validateInstallManifest` (the install fails, with the same reasoning).
|
|
658
|
+
|
|
659
|
+
**What the error looks like** (all three sites share one wording: it names the offender and gives the reason, never a bare "invalid"):
|
|
660
|
+
|
|
661
|
+
```
|
|
662
|
+
pluginId "app" is the host's own identity (the host uses it to register configuration/appearance/update):
|
|
663
|
+
a plugin using it ⇒ collision detection never fires, and unregistration removes the host's entry.
|
|
664
|
+
```
|
|
665
|
+
|
|
666
|
+
> ⚠️ **Identity, key names and appearance ids are three different things**: `pluginId` decides *who you are*; the **key names** in `contributes.configuration` decide *who a key belongs to* ([03-contributes-spec §3.4](03-contributes-spec.md)); and the **ids** inside `contributes.themes` / `iconThemes` / `icons` (recipe / colorway variant / icon theme / shared icon) decide *who an appearance name belongs to* (same file, §3.6–3.8). All three are **keys of a global registry** and none may touch the host's reserved surface — but they are **three separate ledgers** with separate criteria and separate reports, so be sure which one you are changing.
|
|
648
667
|
|
|
649
668
|
> The complete directory structure (what goes in `resources/` / `src/utils/` / `__tests__/`, naming conventions) is in `09-plugin-directory-layout.md`.
|
|
650
669
|
|
|
@@ -250,7 +250,22 @@ useEffect(() => {
|
|
|
250
250
|
|
|
251
251
|
**安装后效果:** Settings Editor 左侧导航树自动出现 "CAD 查看器" 分组 → 右侧自动渲染表单——不需要手写设置界面。
|
|
252
252
|
|
|
253
|
-
**Key 命名规则:** `<pluginId>.<property
|
|
253
|
+
**Key 命名规则:** `<pluginId>.<property>`(**只换第一段、词干零变化**——第一段必须是本仓身份),如 `cad.gridSize`、`terminal.baudRate`。这条规则有**两级判定**,别混着记:
|
|
254
|
+
|
|
255
|
+
| 判据 | 分级 | 谁判 | 会发生什么 |
|
|
256
|
+
|:--|:--:|:--|:--|
|
|
257
|
+
| 键**不得**落在**宿主保留键账**内 | 🔴 **红(拒登)** | 壳运行时 `ConfigurationRegistry` + SDK 腿 `linkdesk/no-unowned-config-key` | 声明**不生效**(该键不注册、不进设置页),并给一条 `console.error`。插件**照常装上**——拒的是这一个键,不是你的插件 |
|
|
258
|
+
| **新**键第一段必须是本仓 `pluginId` | 🟡 黄(建议) | SDK 腿(**运行时不管**) | 报点带 `suggested` = 只换第一段的新名。存量里有 19 个历史键不合此规(如 `files.exclude`),它们的改名与迁移由壳侧统一执行——**新键请照规矩写** |
|
|
259
|
+
|
|
260
|
+
**宿主保留键账**(`configKeys`)是**生成式**清单,随 SDK 包下发 ⇒ 机器可读、别靠猜:
|
|
261
|
+
|
|
262
|
+
```
|
|
263
|
+
node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json → "configKeys": [ "app.theme", ... ]
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
`app.*` 全部都是宿主的(宿主的设置面、外观面、更新面)。**里面还含"退役键"**——宿主用过又删掉的名字(如 `app.themeColorMode`)**不腾位**:老 `settings.json` 里可能还留着值,宿主升级时的迁移代码仍会读它 ⇒ 占它 = 顶掉的是宿主的**历史数据**。
|
|
267
|
+
|
|
268
|
+
> **为什么"占宿主键"是红、"没带自己前缀"只是黄**:占宿主键有**真害**(顶替宿主的生效值、污染内部标志键如 `app.schemaVersion`——两侧都不报错,用户看到的值和宿主实际行为不一致);而"没带前缀"在存量里有 19 个反例,一刀切会把既有插件当场弄坏。分级不同 = 容忍度不同,不是"更重要的规矩写法更严"。
|
|
254
269
|
|
|
255
270
|
**插件读设置(插件通信铁律——只走 `window.linkdesk.configuration`):**
|
|
256
271
|
```typescript
|
|
@@ -278,6 +293,12 @@ useEffect(() => {
|
|
|
278
293
|
|
|
279
294
|
和 `configuration` 的区别:`configuration` 定义了**自己的**设置项。`configurationDefaults` 给**别人的**设置项提供建议值。用户手动设置优先——弱默认只在用户从未设置过该 key 时生效。
|
|
280
295
|
|
|
296
|
+
**Key 归属:** 弱默认值的键走**同一本账**(`host-reserved.json` 的 `configKeys`)——
|
|
297
|
+
|
|
298
|
+
- **宿主的键不许建议**(`app.*` 一律在内):该键被拒登 + 一条 `console.error`。理由同上:那是宿主自己的设置面,替它定默认值 = 改宿主行为。
|
|
299
|
+
- 给**自己**的键、给**别的插件**的键建议都**合法**——这正是本机制的设计用途(所以它**不要求**键带本仓前缀,前缀判据只对 `contributes.configuration` 的键判)。
|
|
300
|
+
- **两个插件建议同一个键** ⇒ **不拒**:两边都在册,合并时按注册顺序**后写者胜出**,同时给一条 `console.warn` 点名先到者。这是唯一的"同键多人"合法形态——用户在设置页手动设过的值永远优先于任何弱默认值。
|
|
301
|
+
|
|
281
302
|
### 3.6 `contributes.themes`——主题
|
|
282
303
|
|
|
283
304
|
```json
|
|
@@ -301,6 +322,29 @@ useEffect(() => {
|
|
|
301
322
|
|
|
302
323
|
> **🔥 配方 JSON 契约(已随 plugin-sdk 收编)**:`path` 指向的配方文件按 `theme.schema.json` 校验——repo 内 = `public/schemas/theme.schema.json`(`npm run check` 链 `check-theme-schema.mjs`,格式错当场红灯 exit 1 不静默);npm 作者 = 随 `@linkdesk/plugin-sdk` 分发的 `schemas/theme.schema.json` + SDK `validateThemeJson`(同一 schema 文件,规则永不漂移)。运行时 `parseThemeRecipe` toast 是第二道防线。主题文件建议首行 `"$schema"` 引 schema 拿编辑器 IntelliSense(npm 路径见 [11-主题制作](11-主题制作.md) §②)。
|
|
303
324
|
|
|
325
|
+
**id 命名规则:** 目标形态 = `<pluginId>.<名字>`(**只换第一段、词干零变化**),如 `theme-pill.pill-bubble`。**一条规则管三个 id**——`themes[].id`(配方)、`path` 指向的配方 JSON 里的顶层 `id`(配方),以及 `colorways[].id`(配色变体)。分级与设置键同形,别混着记:
|
|
326
|
+
|
|
327
|
+
| 判据 | 分级 | 谁判 | 会发生什么 |
|
|
328
|
+
|:--|:--:|:--|:--|
|
|
329
|
+
| id **不得**落在**宿主兜底 id 账**的**本空间**那一栏 | 🔴 **红(拒注册)** | 壳运行时 `ThemeRegistry` + SDK 腿 `linkdesk/appearance-ownership` | 该 id **注册不上**(配方/配色当即缺席,用户在选择器里看不到它)+ 一条 `console.error` 点名撞上的是哪条兜底 id。插件**照常装上**——拒的是这一个 id,不是你的插件 |
|
|
330
|
+
| **新** id 第一段应是本仓 `pluginId` | 🟡 黄(建议) | SDK 腿(**运行时不管**) | 报点带 `suggested` = 只换第一段的新名。存量官方主题仓还有 25 条 id 不合此规(`mint-soda`、`kraft` …),改名与迁移由壳侧统一执行——**新 id 请照规矩写** |
|
|
331
|
+
| 同一插件的**两个配方**用同一个**配色** id | 🟡 黄 + 登记 | SDK 腿 | 壳的契约是「配色变体 id **全局唯一**」——跨配方重复会让配色下拉出现重复项 |
|
|
332
|
+
|
|
333
|
+
**宿主兜底 id 账**随 SDK 包下发,**按空间分栏**(配方与配色是**两个名字空间**:`mint-soda` 可以同时是两者,所以只比**本栏**,绝不跨栏):
|
|
334
|
+
|
|
335
|
+
```
|
|
336
|
+
node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
|
|
337
|
+
→ "appearanceRecipeIds": ["dark", "light"] ← 配方栏
|
|
338
|
+
"appearanceColorwayIds": ["dark-fallback", "light"] ← 配色栏(注意:配色兜底叫 dark-fallback,不叫 dark)
|
|
339
|
+
"appearanceIdGrants": { "light": ["theme-defaults"] } ← 例外:为该 id 记了证照的持有者
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
兜底 id 是「**全部主题插件卸光后仍能渲染**」的那一层,占它 = 顶替宿主的保底面。**`appearanceIdGrants` 不是白名单**——它**按 id 记**谁持有:`light` 有证照,因为官方主题仓正是宿主亮色兜底的**实现者**;你的插件不在表里(那是壳侧的公共面决策,作者加不进去)⇒ 一律判红。
|
|
343
|
+
|
|
344
|
+
> **为什么"占兜底 id"是红、"没带自己前缀"只是黄**:占兜底 id 有**真害**(顶替宿主保底面,插件全卸光后主题跟着坏);而"没带前缀"在存量里有 25 个反例,一刀切会把既有主题仓当场弄坏。分级不同 = 容忍度不同,不是"更重要的规矩写法更严"。
|
|
345
|
+
|
|
346
|
+
**跨插件撞名(同一个 id 两个插件都声明):** 壳**先者保留**——后注册的那个 id **注册不上**,并给一条 `console.error` 点名双方(谁先到、谁被拒)。它不是"占兜底 id":两边都没碰宿主的名字,但**一个名字只有一份**,所以把自己的名字带上,才不会等到这一天。
|
|
347
|
+
|
|
304
348
|
### 3.7 `contributes.iconThemes`——图标主题
|
|
305
349
|
|
|
306
350
|
```json
|
|
@@ -370,6 +414,12 @@ useEffect(() => {
|
|
|
370
414
|
|
|
371
415
|
> **🔥 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。
|
|
372
416
|
|
|
417
|
+
**id 命名规则:** 图标主题 id 只判**一条**——**不得**用宿主兜底 id `default`(判红:该 id 注册不上 + 一条 `console.error`)。**不判**"带不带本仓前缀":图标主题 id 会**原样显示在设置页**(选择器直接渲染 id 文本),给它改名 = 用户可见文字变化 ⇒ 本轮不动。想让它在下拉里好看,改的是 `label`(显示名),不是 id。
|
|
418
|
+
|
|
419
|
+
```
|
|
420
|
+
→ "appearanceIconThemeIds": ["default"] ← 图标主题栏(只有这一条)
|
|
421
|
+
```
|
|
422
|
+
|
|
373
423
|
### 3.8 `contributes.icons`——共享图标
|
|
374
424
|
|
|
375
425
|
```json
|
|
@@ -387,7 +437,10 @@ useEffect(() => {
|
|
|
387
437
|
|
|
388
438
|
插件 A 贡献、插件 B 引用(`"icon": "stm32-chip"` + `"iconSource": "shared"`)。
|
|
389
439
|
|
|
390
|
-
|
|
440
|
+
**id 命名规则:** 这里的**键**就是共享图标 id(插件 A 贡献、插件 B 引用)⇒ 建议带上本仓归属 `<pluginId>.<名字>`(🟡 建议,SDK 腿报点)。宿主没有兜底共享图标 ⇒ 这一族**没有红**;但两个插件声明**同一个键**时,后注册者**注册不上** + 一条 `console.error` 点名双方(与配方/配色同一条仲裁)。
|
|
441
|
+
|
|
442
|
+
### 3.9 `contributes.languages`——UI 语言包
|
|
443
|
+
+ `contributes.i18n`——插件自带翻译
|
|
391
444
|
|
|
392
445
|
**两条翻译管道,别混:**
|
|
393
446
|
|
|
@@ -223,7 +223,7 @@ my-plugin/
|
|
|
223
223
|
| 字段 | 类型 | 说明 |
|
|
224
224
|
|---|---|---|
|
|
225
225
|
| `$schema` | `string` | JSON Schema 引用路径 |
|
|
226
|
-
| `pluginId` | `string` | 🔴 **插件身份——发布后永不可变**(对标 VS Code 的 `publisher.name`)。安装目录 `{userData}/plugins/<pluginId>/`、分发件名 `<pluginId>.linkdesk-plugin`、市场目录去重键、卸载墓碑键、更新对账全部以它为准。**强烈建议显式声明**:不声明时退回「项目目录名」兜底,而仓库名与本地目录名是自由的——目录名一改身份就跟着改,且**没有一条会报错**。字符集 `^[A-Za-z0-9][A-Za-z0-9._-]
|
|
226
|
+
| `pluginId` | `string` | 🔴 **插件身份——发布后永不可变**(对标 VS Code 的 `publisher.name`)。安装目录 `{userData}/plugins/<pluginId>/`、分发件名 `<pluginId>.linkdesk-plugin`、市场目录去重键、卸载墓碑键、更新对账全部以它为准。**强烈建议显式声明**:不声明时退回「项目目录名」兜底,而仓库名与本地目录名是自由的——目录名一改身份就跟着改,且**没有一条会报错**。字符集 `^[A-Za-z0-9][A-Za-z0-9._-]*$`,**外加三个禁用**(见下方「身份的三个禁用」)。规则与实测依据见 [16-命名规范](16-命名规范.md) |
|
|
227
227
|
| `core` | `boolean` | `true` = **UI 防误删旗标**(对齐上文字段表 :44 新版措辞)——详情页卸载按钮不显示/禁用;**无行为特权、非类别**:API/命令层可卸可禁,卸走写 removed 墓碑。默认 `false` |
|
|
228
228
|
| `distribution` | `string` | ⚠️ **遗留字段**(2026-09-05 塌平单根后不再对应任何目录,安装侧恒归一化为 `user`;schema 已标废弃)。**第三方请勿填写** |
|
|
229
229
|
| `factoryRole` | `string` | 系统插槽角色:`"settings"` \| `"marketplace"`。**填 = 形态二(替换/进槽位切换);不填 = 形态一(普通视图插件并存)**——详见下方「`factoryRole` 字段详解」 |
|
|
@@ -642,6 +642,24 @@ plugins/<pluginId>/ ← repo 源码树(塌平单根;目录名 =
|
|
|
642
642
|
`<pluginId>` = 文件夹名 = 插件唯一标识(身份唯一来源——loader 以目录名定 pluginId,schema 无顶层 pluginId 字段)。命名规则:
|
|
643
643
|
- 小写英文 + 连字符:`gps-map`、`protocol-sbq`、`theme-dracula`
|
|
644
644
|
- 不带软件名、不带版本号:`terminal` 不是 `v3-terminal`
|
|
645
|
+
- **不许占下面三个禁用名**
|
|
646
|
+
|
|
647
|
+
#### 身份的三个禁用
|
|
648
|
+
|
|
649
|
+
| 禁用 | 为什么 |
|
|
650
|
+
|:--|:--|
|
|
651
|
+
| `app` · `appearance` · `update` | **这三个是宿主自己的身份**:壳用 `app` 注册通用设置、用 `appearance` 注册外观设置、用 `update` 注册更新设置。插件拿它当 pluginId ⇒ **冲突检测永不响**(宿主自己就是这个身份,先注册的永远是它),而且**卸载会摘掉宿主自己的条目**(注销按身份摘)——你的插件一卸,宿主的设置组跟着消失 |
|
|
652
|
+
| `ldk-` 前缀 | 壳 / SDK 的**内部保留前缀**(`ldk-` 开头的名字留给产品线自己用)。第三方占用它 ⇒ 日后壳发一个同名插件必然相撞,而相撞的代价落在用户身上(装不上 / 更新对账错乱) |
|
|
653
|
+
|
|
654
|
+
**拦在哪(三处,都拦):** ① `plugin.schema.json` 的 `pluginId` pattern 负向断言(编辑器和 IDE 当场标红)——schema 就在你的工程里:`node_modules/@linkdesk/plugin-sdk/schemas/plugin.schema.json`;② SDK `validate` / `lint`(作者仓自检报点);③ 壳的安装校验 `validateInstallManifest`(装不上,给的是同一条理由)。
|
|
655
|
+
|
|
656
|
+
**报错形态**(三处文案同源,都点名 + 给理由,不是一句"不合法"):
|
|
657
|
+
|
|
658
|
+
```
|
|
659
|
+
pluginId "app" 是宿主自己的身份(宿主用它注册配置/外观/更新),插件用它 ⇒ 冲突检测永不响、注销会摘掉宿主条目。
|
|
660
|
+
```
|
|
661
|
+
|
|
662
|
+
> ⚠️ **身份、键名、外观 id 是三件事**:`pluginId` 决定"你是谁";`contributes.configuration` 的**键名**决定"这个键归谁"([03-插件contributes规范 §3.4](03-插件contributes规范.md));`contributes.themes` / `iconThemes` / `icons` 里的 **id**(配方 / 配色变体 / 图标主题 / 共享图标)决定"这个外观名归谁"(同篇 §3.6–3.8)。三者都是**全局名册的键**、都不许碰宿主的保留面,但**三本不同的账**、判据与报点各自独立——认准你改的是哪一个。
|
|
645
663
|
|
|
646
664
|
> 完整目录结构(`resources/` / `src/utils/` / `__tests__/` 放什么、命名约定)见 `09-插件目录规范.md`。
|
|
647
665
|
|
|
@@ -13,8 +13,8 @@
|
|
|
13
13
|
},
|
|
14
14
|
"pluginId": {
|
|
15
15
|
"type": "string",
|
|
16
|
-
"pattern": "^(?!ldk
|
|
17
|
-
"description": "🔴 Plugin identity — immutable once published (mirrors VS Code's publisher.name). Everything keys off it: install directory {userData}/plugins/<pluginId>/, distribution file name <pluginId>.linkdesk-plugin, marketplace dedup key, uninstall tombstone key, and update reconciliation. Strongly recommended to declare it explicitly: when omitted it falls back to the project directory name, but repository names and local directory names are free-form — rename the directory and the identity changes with it, and none of the five consequences (two install directories side by side / tombstone mismatch / duplicate marketplace entries / silently broken update chain / plugin data appearing lost) reports an error. Character set: letters, digits, `.`, `_`, `-`; the first character must be a letter or a digit. It must not start with `ldk-`: that whole namespace belongs to the host and its shared components, and since your CSS class prefix is derived from this id (`<pluginId>-your-class`), an `ldk-` id would land in host territory by construction and void the plugin-prefix rule (SDK check-css-namespace leg)."
|
|
16
|
+
"pattern": "^(?!(ldk-|app$|appearance$|update$))[A-Za-z0-9][A-Za-z0-9._-]*$",
|
|
17
|
+
"description": "🔴 Plugin identity — immutable once published (mirrors VS Code's publisher.name). Everything keys off it: install directory {userData}/plugins/<pluginId>/, distribution file name <pluginId>.linkdesk-plugin, marketplace dedup key, uninstall tombstone key, and update reconciliation. Strongly recommended to declare it explicitly: when omitted it falls back to the project directory name, but repository names and local directory names are free-form — rename the directory and the identity changes with it, and none of the five consequences (two install directories side by side / tombstone mismatch / duplicate marketplace entries / silently broken update chain / plugin data appearing lost) reports an error. Character set: letters, digits, `.`, `_`, `-`; the first character must be a letter or a digit. It must not start with `ldk-`: that whole namespace belongs to the host and its shared components, and since your CSS class prefix is derived from this id (`<pluginId>-your-class`), an `ldk-` id would land in host territory by construction and void the plugin-prefix rule (SDK check-css-namespace leg). It must also not be exactly `app`, `appearance`, or `update`: those three are the **host's own registration identities** (the shell registers its general / appearance / update configuration under them). A plugin using one of them would never trip the cross-plugin key-ownership check (the host already owns that identity) and its uninstall disposer would remove the host's own entries — the runtime rejects such registrations, and this pattern makes the manifest fail validation first."
|
|
18
18
|
},
|
|
19
19
|
"type": {
|
|
20
20
|
"type": "string",
|