@linkdesk/plugin-docs 0.1.9 → 0.1.11

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.
@@ -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>`, e.g. `cad.gridSize`, `terminal.baudRate`
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
@@ -703,7 +703,48 @@ The three rules above govern **names**; this one governs **territory**. For cust
703
703
 
704
704
  **How it is enforced mechanically**: run `npm run lint` in the plugin project root (or `npm run verify` in CI) and each occurrence is reported—🔴 turns CI red, 🟡 only prints. When "it works locally but CI is red", read this section first.
705
705
 
706
- > 🔧 **Maintainer note (authors may skip)**: the rule text (including how the host registers its contract blocks and the floating-layer host exception) lives under `docs/02-Electron架构/E6_插件生态与发布/01-插件独立构建/样式命名空间归一化/`; the shell side is guarded by `scripts/check-css-namespace.mjs`, the plugin side by the SDK's `check-css-namespace` leg (the third criterion of that same leg, sharing one disable-comment id with the class-name and keyframe criteria).
706
+ > 🔧 **Maintainer note (authors may skip)**: the rule text (including how the host registers its contract blocks and the floating-layer host exception) lives under `docs/02-Electron架构/E6_插件生态与发布/01-插件独立构建/样式命名空间归一化/`; the shell side is guarded by `scripts/check-css-namespace.mjs`, the plugin side by the SDK's `check-css-namespace` leg (token scope is the third criterion of that same leg, sharing one disable-comment id with the class-name and keyframe criteria).
707
+
708
+ ### 12.6 The selector itself needs a "landing spot" too—**anchorless selectors are forbidden** (2026-09-16)
709
+
710
+ The five sections above govern **names** (class names / keyframes / custom properties). This one governs the **shape of the selector**—a rule that is even easier to overlook:
711
+
712
+ > **Class names and ids are "name anchors"; element / universal / attribute / pseudo-class / pseudo-element selectors are not.**
713
+ > The latter hit other people's elements **without sharing a single name with anyone.**
714
+
715
+ ```css
716
+ /* ❌ one rule rewrites *every* button in the document—including the host's and other plugins' */
717
+ button { border: none; }
718
+ * { box-sizing: border-box; }
719
+ #some-id { display: none; } /* an id is global and guessable too, and outranks classes */
720
+ :root { outline: none; } /* `:root` is an anchorless selector as well */
721
+
722
+ /* ✅ hang it under your own root class—same intent, landing spot limited to your own subtree */
723
+ .my-plugin-root button { border: none; }
724
+ ```
725
+
726
+ **Two rules** (both are **mechanically red** in `npm run lint` at the plugin project root / `npm run verify` in CI):
727
+
728
+ | Rule | Verdict | Why |
729
+ |---|---|---|
730
+ | **No anchorless selectors** | The selector has **no** `.class` or `#id` subject (element / universal / attribute / pseudo-class / pseudo-element; **top-level *and* qualified, including inside `@media`**) ⇒ 🔴 | It hits "every element of that kind in the document", regardless of who rendered it |
731
+ | **A cross-party hit must carry your own anchor** | The selector mentions an `ldk-*` class (**including a mention inside `:has(…)`**) but does **not** carry a `.<your pluginId>-*` class ⇒ 🔴 | `ldk-` is the host's namespace; **fine-tuning has to happen on your own territory** |
732
+
733
+ ⚠️ **The second rule does not forbid restyling shared components**—that is a **legitimate feature** (scoped tuning). It only requires you to **carry your own prefix as the anchor**:
734
+
735
+ ```css
736
+ /* ❌ targets the host's / shared components' elements with no landing spot of your own ⇒ red */
737
+ .ldk-toggle { transform: scale(1.1); }
738
+
739
+ /* ✅ the same intent, written on your own territory ⇒ compliant */
740
+ .my-plugin-root .ldk-toggle { transform: scale(1.1); }
741
+ ```
742
+
743
+ **Why it is worth remembering**: the host itself has **17** such "anchorless selectors" (`*` resets / `html`·`body` / `[data-theme]` / `*:focus-visible` / the scrollbar family / `input[type="number"]`·`select`)—they are a **deliberate shared baseline** that plugins rely on (and may override). Precisely because they exist, **your anchorless selector will hit them**: write `button { }` and the host's buttons plus every other plugin's buttons change with it.
744
+
745
+ **Migration**: **zero instances today**—a full re-check of the 18 official plugins plus the in-repo fixtures (the "anchorless S2 / cross-party S3" columns of `npm run audit:plugin-prefix -- --all`) is **0** ⇒ **you have nothing to change**; this rule is **preventive**.
746
+
747
+ > 🔧 **Maintainer note (authors may skip)**: the rule text (R0 scope / R1 host baseline / R2 / R3) plus the decision formulas and negative controls live in `docs/02-Electron架构/E6_插件生态与发布/01-插件独立构建/样式命名空间归一化/32-任务-选择器形态轴门禁与落地.md`; the host side is guarded by criteria ⑩⑪ of `scripts/check-css-namespace.mjs` (plus the runtime mirror on axis ④ of the probe), and the plugin side by the **fourth criterion** of the SDK's `check-css-namespace` leg (`checks/selector-form.ts`, S2/S3).
707
748
 
708
749
  ---
709
750
 
@@ -726,6 +767,7 @@ The three rules above govern **names**; this one governs **territory**. For cust
726
767
  | UI discipline gate | `linkdesk-plugin-sdk lint` | all 15 items are WARNs that never fail; a knowing bypass = a standard eslint-disable declaration (see §11.2) |
727
768
  | Text | `t()` | `useTranslation()` from `react-i18next` |
728
769
  | CSS class names / state classes | own prefix + host reserved-name list | see §12 (class names are global—all plugins share the document with the host) |
770
+ | Element / id selectors | must hang under your own root class | see §12.6 (an anchorless selector hits everyone's elements, name or no name) |
729
771
  | Sidebar list selection | `onMouseDown` (not `onClick`) | aligned with VS Code Explorer—prevents lost events when a fast click crosses elements |
730
772
 
731
773
  **Use these facilities when writing plugins; don't hand-roll. Even if you write one, it'll have to be torn out later—better to normalize from day one.**
@@ -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._-]*$`. Rules and the empirical evidence behind them are in [16-naming-conventions](16-naming-conventions.md) |
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 and key names are two different things**: `pluginId` decides *who you are*, while the **key names** in `contributes.configuration` decide *who a key belongs to* (that rule is in [03-contributes-spec §3.4](03-contributes-spec.md)). Neither may touch the host's reserved surface, but the criteria and the reports are separate.
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>`,如 `cad.gridSize`、`terminal.baudRate`
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
@@ -695,7 +695,55 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
695
695
  > 🔧 **维护者注(作者可跳过)**:规则正文(含宿主契约块的登记方式、浮层宿主根那个例外)在
696
696
  > `docs/02-Electron架构/E6_插件生态与发布/01-插件独立构建/样式命名空间归一化/` 下;宿主侧由
697
697
  > `scripts/check-css-namespace.mjs` 守着,插件侧由 SDK 的 `check-css-namespace` 腿守着
698
- > (同一条腿的第三条判据,与类名 / 关键帧共用同一个 disable 注释 id)。
698
+ > (token 作用域是那条腿的第三条判据,与类名 / 关键帧共用同一个 disable 注释 id)。
699
+
700
+ ### 12.6 选择器本身也要有「落点」——**禁写无锚选择器**(2026-09-16)
701
+
702
+ 前五节管的是**名字**(类名 / 关键帧 / 自定义属性)。这一节管**选择器的形态**——一条更容易忽略的规矩:
703
+
704
+ > **类名和 id 是「名字锚」;元素 / 通配 / 属性 / 伪类 / 伪元素不是。**
705
+ > 后者**不需要与任何人同名**就能命中别人的元素。
706
+
707
+ ```css
708
+ /* ❌ 一条规则改掉「这个文档里所有」的按钮——宿主和其他插件的按钮全在内 */
709
+ button { border: none; }
710
+ * { box-sizing: border-box; }
711
+ #some-id { display: none; } /* id 也是全局的、可猜的,优先级还高于类 */
712
+ :root { outline: none; } /* `:root` 同样是无锚选择器 */
713
+
714
+ /* ✅ 挂在自己的根类之下——同一个意图,落点只有你自己的子树 */
715
+ .my-plugin-root button { border: none; }
716
+ ```
717
+
718
+ **两条规则**(都在插件工程根 `npm run lint` / CI `npm run verify` 里**机械判红**):
719
+
720
+ | 规则 | 判定 | 为什么 |
721
+ |---|---|---|
722
+ | **禁无锚选择器** | 选择器**没有**任何 `.类` 或 `#id` 主体(元素 / 通配 / 属性 / 伪类 / 伪元素;**顶层或限定一律禁,`@media` 内也算**)⇒ 🔴 | 它命中「该文档里所有那一类元素」,与谁渲染无关 |
723
+ | **跨方命中必须自带自有锚** | 选择器里出现 `ldk-*` 类(**含 `:has(…)` 内的提及**)却**不带** `.<你的 pluginId>-*` 类 ⇒ 🔴 | `ldk-` 是宿主命名空间;**调优必须发生在自己的地盘里** |
724
+
725
+ ⚠️ **第二条不影响「改共享组件外观」这件事本身**——那是**合法特性**(scoped 调优)。它只要求你**带着自家前缀作锚**:
726
+
727
+ ```css
728
+ /* ❌ 改的是宿主/共享组件的元素,自己却一点落点都没有 ⇒ 判红 */
729
+ .ldk-toggle { transform: scale(1.1); }
730
+
731
+ /* ✅ 同一个意图,写在自己的地盘里 ⇒ 合规 */
732
+ .my-plugin-root .ldk-toggle { transform: scale(1.1); }
733
+ ```
734
+
735
+ **为什么值得专门记住**:宿主自己就有 **17 处**这样的「无锚选择器」(`*` 重置 / `html`·`body` /
736
+ `[data-theme]` / `*:focus-visible` / 滚动条一族 / `input[type="number"]`·`select`)——它们**是有意的
737
+ 共享基线**,插件一直在依赖它们(也可以覆写)。正因为它们存在,**你的无锚选择器一定会命中它们**:
738
+ 你写 `button { }`,宿主的按钮、其他插件的按钮,全都会跟着变。
739
+
740
+ **迁移**:**今天 0 存量**——官方 18 只插件 + 壳内夹具全量复核(`npm run audit:plugin-prefix -- --all`
741
+ 的「无锚 S2 / 跨方 S3」两列)都是 **0** ⇒ **你不需要改任何东西**;这条规矩是**预防性**的。
742
+
743
+ > 🔧 **维护者注(作者可跳过)**:规则正文(R0 口径 / R1 宿主基线 / R2 / R3)与判定式、负控见
744
+ > `docs/02-Electron架构/E6_插件生态与发布/01-插件独立构建/样式命名空间归一化/32-任务-选择器形态轴门禁与落地.md`;
745
+ > 宿主侧由 `scripts/check-css-namespace.mjs` 的判据⑩⑪(+ 探针轴 ④ 的运行时镜像)守着,
746
+ > 插件侧由 SDK 的 `check-css-namespace` 腿的**第四条判据**守着(`checks/selector-form.ts`,S2/S3)。
699
747
 
700
748
  ---
701
749
 
@@ -718,6 +766,7 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
718
766
  | UI 纪律门禁 | `linkdesk-plugin-sdk lint` | 15 项全 WARN 永不 fail;知情绕行 = 标准 eslint-disable 声明(见 §11.2) |
719
767
  | 文字 | `t()` | `useTranslation()` from `react-i18next` |
720
768
  | CSS 类名 / 状态类 | 自有前缀 + 宿主保留名清单 | 见 §12(类名是全局的——所有插件与宿主同表) |
769
+ | 元素 / id 选择器 | 必须挂在自己的根类之下 | 见 §12.6(无锚选择器不需要同名就能命中所有人的元素) |
721
770
  | 侧栏列表选中 | `onMouseDown`(非 `onClick`) | 对标 VS Code Explorer——防止快速点击跨元素丢事件 |
722
771
 
723
772
  **写插件时用这些设施,别手写。写了以后也得拆——不如从第一天就归一。**
@@ -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._-]*$`。规则与实测依据见 [16-命名规范](16-命名规范.md) |
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
+ > ⚠️ **身份与键名是两件事**:`pluginId` 决定"你是谁",`contributes.configuration` 的**键名**决定"这个键归谁"(那份规矩见 [03-插件contributes规范 §3.4](03-插件contributes规范.md))。两者都不许碰宿主的保留面,但判据与报点各自独立。
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-)[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)."
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",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.9",
3
+ "version": "0.1.11",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——`docs/03-插件制造` 的发布产物:从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [