@linkdesk/plugin-docs 0.1.11 → 0.1.14

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.
@@ -322,6 +322,29 @@ The declaration is metadata-only; theme color data is fetched asynchronously at
322
322
 
323
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) §②).
324
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
+
325
348
  ### 3.7 `contributes.iconThemes` — icon themes
326
349
 
327
350
  ```json
@@ -391,6 +414,12 @@ No `font` section → zero custom fonts (codicon fallback / a pure image-asset t
391
414
 
392
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.
393
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
+
394
423
  ### 3.8 `contributes.icons` — shared icons
395
424
 
396
425
  ```json
@@ -408,7 +437,10 @@ No `font` section → zero custom fonts (codicon fallback / a pure image-asset t
408
437
 
409
438
  Plugin A contributes, plugin B references (`"icon": "stm32-chip"` + `"iconSource": "shared"`).
410
439
 
411
- ### 3.9 `contributes.languages` — UI language packs + `contributes.i18n` — plugin-bundled translations
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
412
444
 
413
445
  **Two translation pipelines — don't mix them:**
414
446
 
@@ -433,6 +465,26 @@ Plugin A contributes, plugin B references (`"icon": "stm32-chip"` + `"iconSource
433
465
  - Translation files are loaded through `fetchPluginDataFile` (bypassing the Vite glob cache — JSON in a newly installed plugin directory is discovered in real time).
434
466
  - The plugin text iron rule: **all UI text goes through `t()`**, and the i18n key is the original Chinese text (`05 §6`).
435
467
 
468
+ #### Bucket-key naming advice — **give your keys an owner** (advice, not a requirement)
469
+
470
+ Your translation file is **one flat layer of keys**, and everyone writes into the same table: every plugin's keys, the shell's own keys, and the `lang-defaults` language pack's keys **live in one dictionary**. Within a language, the later registrant overwrites the earlier one — **and until now there was no notice at all**.
471
+
472
+ **Advice**: give your keys an owner-bearing name, e.g. `serial-monitor.打开端口` instead of `打开端口`. Then even an accidental name clash is nobody else's business.
473
+
474
+ 🔴 **Why this is advice and not a requirement**: **an i18n key may legitimately live in the app-level dictionary**. The official `settings` plugin has 254 `t()` call sites and **not a single key of its own in its repo** — they all live in `lang-defaults`' `zh.json` / `en.json`. Inside your plugin repo there is only your own `i18n/*.json` — **you cannot see the shell's dictionary, nor any other plugin** — so "your key collided with someone" is **never decidable from your own repo**. Making it a blocker means guaranteed false positives, and false positives invalidate the rules that should really block. ⇒ **It is a yellow light, not a red one.**
475
+
476
+ **How much overlap actually exists today** (told plainly, not exaggerated): the keys declared by the 18 official plugins (414 of them) overlap the `lang-defaults` keys in **65 places**, and **3 of those already have divergent translations** — for example `命令`, where the shell says `Command` while `serial-monitor` says `Commands`. **When both are written into the same dictionary, which one the user actually sees depends on plugin load order.**
477
+
478
+ ⚠️ **Runtime behaviour**: when an overwrite happens the shell emits a `console.warn` naming the **key + language + writer**:
479
+
480
+ ```
481
+ [i18nResources] 键 "命令"(zh)被 serial-monitor 覆盖——已有同键,来源未知;值以后注册者为准
482
+ ```
483
+
484
+ **It is a notice, not a blocker** — the value is still written (the later registrant wins, exactly as today); the collision merely becomes traceable. The wording says only "already has this key, source unknown": the shell **can report who overwrote, but cannot report who owned it originally**, and it does not claim what it cannot do.
485
+
486
+ 🔴 **When NOT prefixing is legitimate**: **extensions** such as `.py` / `.ts`, and **language codes** such as `zh` / `en` — they are not "unowned", they **should never have an owner**, and prefixing them would be a semantic error.
487
+
436
488
  ### 3.10 `contributes.titleBar` — top bar buttons
437
489
 
438
490
  ```json
@@ -663,7 +663,7 @@ pluginId "app" is the host's own identity (the host uses it to register configur
663
663
  a plugin using it ⇒ collision detection never fires, and unregistration removes the host's entry.
664
664
  ```
665
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.
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.
667
667
 
668
668
  > The complete directory structure (what goes in `resources/` / `src/utils/` / `__tests__/`, naming conventions) is in `09-plugin-directory-layout.md`.
669
669
 
@@ -77,6 +77,53 @@ useEffect(() => {
77
77
 
78
78
  > **This is "zero-code wiring"**: Title Bar buttons, context menu items, keybindings, and sidebar views can all use the same `when` condition — you `set` it in one place and the shell reads it in N places. The `when` syntax (`&&` / `||` / `==` / `in` / `!` / `()`) and the shell's built-in key table → [03-Contributes Spec §4](03-contributes-spec.md).
79
79
 
80
+ #### 🔴 Flag reservation table — **read this before naming a key** (shell 1.38+)
81
+
82
+ Flags are **keys in a global registry**: the name you `set` is **visible to the whole pool**, and the shell's built-in commands/menus read `when` against that same table. So names are not free-form — there are **two segments**, with different rules:
83
+
84
+ **① Host-only flags (🔴 plugins must not set)** — state maintained by the host kernel/shell itself. Taking one over rewrites the show/hide conditions of host menus and the command palette, and **neither side reports an error** — the user just sees "a menu item mysteriously vanished":
85
+
86
+ | Flag | What it controls (host side) |
87
+ |:--|:--|
88
+ | `activeEditor` | Current editor type (commands/menus gate on it) |
89
+ | `editorCount` | Number of open editors |
90
+ | `editorHasSelection` | Whether the current editor has a selection |
91
+ | `inputFocus` | Whether an input is focused (🔴 the measured case: on F2 rename, **keybindings must yield**) |
92
+ | `sidebarPosition` | Sidebar dock position |
93
+ | `updateActionable` | Whether an installable update exists |
94
+ | `updateButtonLabel` | The update button's text |
95
+
96
+ **② Host public-convention flags (🟠 settable, but only the host should set them)** — the host `when` **reads** these; the writer is meant to be the host itself:
97
+
98
+ | Flag | Convention | Who may set it |
99
+ |:--|:--|:--|
100
+ | `settingKey` | Settings row gear menu — **the current item's key** | Only the `settingItemGear` gear menu should |
101
+ | `settingValue` | Same — current value | Same |
102
+ | `settingType` | Same — control type | Same |
103
+ | `settingScope` | Same — scope | Same |
104
+
105
+ These four are **in practice** "anyone can set, anyone can read" (`MenuId` is an open string ⇒ a third party **can** add entries to the `settingItemGear` slot) — which is why setting them is **not** judged red. But **the one legitimate write site is the gear menu**: if you overwrite them from anywhere else, the gear menu opens against **the wrong row**. ⇒ **Don't set them** unless you are implementing that slot's menu.
106
+
107
+ **Machine-readable source of truth** (ships with the SDK package — don't guess):
108
+
109
+ ```
110
+ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
111
+ → "contextKeysHostOnly": ["activeEditor", "editorCount", ...] ← segment ① do not set
112
+ "contextKeysPublic": ["settingKey", "settingValue", ...] ← segment ② don't set (except the gear menu)
113
+ ```
114
+
115
+ **Two-level judgement** (same shape as config keys and appearance ids — don't conflate them):
116
+
117
+ | Criterion | Grade | Judged by | What happens |
118
+ |:--|:--:|:--|:--|
119
+ | The `set` name ∈ **segment ① host-only** | 🔴 **red** | SDK leg `linkdesk/no-unowned-context-key` | Your lint reports red by name; the **runtime second net** adds a `console.error` at the `contextKey:set` bridge — but 🔴 **the value is still written, not rejected** (see below) |
120
+ | **New** flag's first segment isn't your `pluginId` | 🟡 yellow (advisory) | SDK leg | Reported with `suggested` = the same name with only the first segment swapped (`zzzFlag` → `my-plugin.zzzFlag`). 23 flags across the 18 official repos break this rule; the shell migrates them centrally — **write new ones by the rule** |
121
+ | The `set` name ∈ **segment ② convention face** | 🟠 **not judged** | Registered only | Legal, but see above: that's the gear menu's spot — don't overwrite it |
122
+
123
+ > **Why "taking a host-only flag" is red while "missing your prefix" is only yellow**: taking a host-only flag does **real harm** (it replaces host state, and neither side errors); whereas "missing the prefix" has 23 counterexamples in existing code, so a blanket rule would break shipped plugins on the spot. Different grades = different tolerance, not "the more important rule is written stricter".
124
+
125
+ > 🔴 **Why the runtime only speaks up and never rejects** (unlike config keys / appearance ids, which **refuse registration**): a flag is a **state write**, not a **registration** — `contextKey.set(name, value)` just writes a value into a table, and two parties writing the same name in sequence with the later one winning is **normal runtime behaviour**. "Refusing" would require the runtime to know **who came first**, but `contextKey:set` crosses IPC carrying **only `[key, value]` and no writer identity** ⇒ "first writer wins" is **structurally impossible** on this face. ⇒ The only honest action is to speak up by name and write the value anyway. **The real protection lives in your lint** (it has your identity and reports at compile time); the runtime layer is just a second net.
126
+
80
127
  ### Recipe C — One region changes, UI scattered across several places refreshes together
81
128
 
82
129
  Say "the serial port disconnected" has to affect the sidebar's connection row, a button in the Main Area, and the Status Bar's counter at the same time. **Publish one event and let each place subscribe on its own:**
@@ -322,6 +322,29 @@ useEffect(() => {
322
322
 
323
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) §②)。
324
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
+
325
348
  ### 3.7 `contributes.iconThemes`——图标主题
326
349
 
327
350
  ```json
@@ -391,6 +414,12 @@ useEffect(() => {
391
414
 
392
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。
393
416
 
417
+ **id 命名规则:** 图标主题 id 只判**一条**——**不得**用宿主兜底 id `default`(判红:该 id 注册不上 + 一条 `console.error`)。**不判**"带不带本仓前缀":图标主题 id 会**原样显示在设置页**(选择器直接渲染 id 文本),给它改名 = 用户可见文字变化 ⇒ 本轮不动。想让它在下拉里好看,改的是 `label`(显示名),不是 id。
418
+
419
+ ```
420
+ → "appearanceIconThemeIds": ["default"] ← 图标主题栏(只有这一条)
421
+ ```
422
+
394
423
  ### 3.8 `contributes.icons`——共享图标
395
424
 
396
425
  ```json
@@ -408,7 +437,10 @@ useEffect(() => {
408
437
 
409
438
  插件 A 贡献、插件 B 引用(`"icon": "stm32-chip"` + `"iconSource": "shared"`)。
410
439
 
411
- ### 3.9 `contributes.languages`——UI 语言包 + `contributes.i18n`——插件自带翻译
440
+ **id 命名规则:** 这里的**键**就是共享图标 id(插件 A 贡献、插件 B 引用)⇒ 建议带上本仓归属 `<pluginId>.<名字>`(🟡 建议,SDK 腿报点)。宿主没有兜底共享图标 ⇒ 这一族**没有红**;但两个插件声明**同一个键**时,后注册者**注册不上** + 一条 `console.error` 点名双方(与配方/配色同一条仲裁)。
441
+
442
+ ### 3.9 `contributes.languages`——UI 语言包
443
+ + `contributes.i18n`——插件自带翻译
412
444
 
413
445
  **两条翻译管道,别混:**
414
446
 
@@ -433,6 +465,26 @@ useEffect(() => {
433
465
  - 翻译文件经 `fetchPluginDataFile` 加载(绕开 Vite glob 缓存——新装插件目录的 JSON 实时发现)。
434
466
  - 插件文字铁律:**所有 UI 文字走 `t()`**,i18n key = 中文原文(`05 §6`)。
435
467
 
468
+ #### 桶键命名建议——**给键加上归属**(建议,不是强制)
469
+
470
+ 你的翻译文件是**平铺的一层键**,谁都往同一张表里写:所有插件的键、宿主自己的键、`lang-defaults` 语言包的键,**住在同一本字典里**。同一语言下后注册者覆盖先者,**且此前没有任何提示**。
471
+
472
+ **建议**:给自己的键起带归属的名字,例如 `serial-monitor.打开端口` 而不是 `打开端口`。这样即使名字碰巧相同也与别人无关。
473
+
474
+ 🔴 **为什么这是建议而不是强制**:**i18n 键可以合法住在应用级字典**。官方 `settings` 插件的 254 处 `t()` 调用,**一个键都不在它自己的仓里**(全住 `lang-defaults` 的 `zh.json` / `en.json`)。插件仓里只有你自己的 `i18n/*.json`——**看不到宿主的字典,也看不到其余插件**,所以「你的键撞了别人」在你自己仓里**永远判不出来**。把它做成拦截 = 必然误报,而误报会让真正该拦的规则失效。⇒ **它是黄灯,不是红灯。**
475
+
476
+ **今天真实存在多少重合**(如实告诉你,不夸大):官方 18 个插件声明的键(414 个)与 `lang-defaults` 的键有 **65 条重合**,其中 **3 条译文已经不一致**——例如 `命令`,宿主给的是 `Command`,而 `serial-monitor` 给的是 `Commands`。**两条都写进同一本字典时,用户看到的究竟是哪一条,取决于插件加载顺序。**
477
+
478
+ ⚠️ **运行时行为**:发生覆盖时宿主会 `console.warn` 出声,点明**键名 + 语言 + 写入者**:
479
+
480
+ ```
481
+ [i18nResources] 键 "命令"(zh)被 serial-monitor 覆盖——已有同键,来源未知;值以后注册者为准
482
+ ```
483
+
484
+ **它是提示,不是拦截**——值照常写入(后注册者胜,语义与今天完全一致),只是这条碰撞从此可查。措辞只称「已有同键,来源未知」:**宿主报得出「谁覆盖了」,报不出「原本属于谁」**,不宣称做不到的事。
485
+
486
+ 🔴 **不加前缀的合法情形**:`.py` / `.ts` 这类**扩展名**、`zh` / `en` 这类**语言码**——它们不是「没主」,是**本就不该有主**,加前缀反而语义错误。
487
+
436
488
  ### 3.10 `contributes.titleBar`——顶栏按钮
437
489
 
438
490
  ```json
@@ -659,7 +659,7 @@ plugins/<pluginId>/ ← repo 源码树(塌平单根;目录名 =
659
659
  pluginId "app" 是宿主自己的身份(宿主用它注册配置/外观/更新),插件用它 ⇒ 冲突检测永不响、注销会摘掉宿主条目。
660
660
  ```
661
661
 
662
- > ⚠️ **身份与键名是两件事**:`pluginId` 决定"你是谁",`contributes.configuration` 的**键名**决定"这个键归谁"(那份规矩见 [03-插件contributes规范 §3.4](03-插件contributes规范.md))。两者都不许碰宿主的保留面,但判据与报点各自独立。
662
+ > ⚠️ **身份、键名、外观 id 是三件事**:`pluginId` 决定"你是谁";`contributes.configuration` 的**键名**决定"这个键归谁"([03-插件contributes规范 §3.4](03-插件contributes规范.md));`contributes.themes` / `iconThemes` / `icons` 里的 **id**(配方 / 配色变体 / 图标主题 / 共享图标)决定"这个外观名归谁"(同篇 §3.6–3.8)。三者都是**全局名册的键**、都不许碰宿主的保留面,但**三本不同的账**、判据与报点各自独立——认准你改的是哪一个。
663
663
 
664
664
  > 完整目录结构(`resources/` / `src/utils/` / `__tests__/` 放什么、命名约定)见 `09-插件目录规范.md`。
665
665
 
@@ -77,6 +77,53 @@ useEffect(() => {
77
77
 
78
78
  > **这是"零代码联动"**:标题栏按钮、右键菜单项、快捷键、侧栏视图都能用同一个 `when` 条件——你在一个地方 `set`,壳在 N 个地方读。`when` 的语法(`&&` / `||` / `==` / `in` / `!` / `()`)与壳自带的 key 表 → [03-插件contributes规范 §四](03-插件contributes规范.md)。
79
79
 
80
+ #### 🔴 旗子保留表——**先看这张表再起名**(壳 1.38 起)
81
+
82
+ 旗子是**全局名册的键**:你 `set` 的名字**全池可见**,宿主的内置命令/菜单也用同一张表读 `when`。所以名字不能乱起——分**两段**,各段规矩不同:
83
+
84
+ **① 宿主专用旗子(🔴 插件禁设)**——宿主内核/壳自己维护的状态。占用它 = 改写宿主菜单/命令面板的显隐条件,**两侧都不报错**,用户只看到"菜单项莫名其妙不见了":
85
+
86
+ | 旗子名 | 它在管什么(宿主侧) |
87
+ |:--|:--|
88
+ | `activeEditor` | 当前编辑器类型(命令/菜单按它显隐) |
89
+ | `editorCount` | 打开的编辑器数量 |
90
+ | `editorHasSelection` | 当前编辑器是否有选中 |
91
+ | `inputFocus` | 输入框是否获焦(🔴 实测点:F2 重命名时**快捷键要让位**) |
92
+ | `sidebarPosition` | 侧栏停靠位置 |
93
+ | `updateActionable` | 是否有可安装的更新 |
94
+ | `updateButtonLabel` | 更新按钮的文字 |
95
+
96
+ **② 宿主公开约定旗子(🟠 可设,但只有宿主该设)**——宿主 `when` **读**、**写的人本该是宿主自己**:
97
+
98
+ | 旗子名 | 约定用途 | 谁能设 |
99
+ |:--|:--|:--|
100
+ | `settingKey` | 设置项右键齿轮菜单——**当前项的键名** | 只有 `settingItemGear` 齿轮菜单该设 |
101
+ | `settingValue` | 同上——当前值 | 同上 |
102
+ | `settingType` | 同上——控件类型 | 同上 |
103
+ | `settingScope` | 同上——作用域 | 同上 |
104
+
105
+ 这四条**事实上**是"谁都能设、谁都能读"的(`MenuId` 是开放字符串 ⇒ 第三方**可以**往 `settingItemGear` 槽加项)——所以设它们**不判红**。但**写点本该只有齿轮菜单一处**:你从别处覆盖它,齿轮菜单就会对着**错误的项**开合。⇒ **别设它们**,除非你正是在实现那个槽的菜单。
106
+
107
+ **机器可读的真源**(随 SDK 包下发,别靠猜):
108
+
109
+ ```
110
+ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
111
+ → "contextKeysHostOnly": ["activeEditor", "editorCount", ...] ← 段① 禁设
112
+ "contextKeysPublic": ["settingKey", "settingValue", ...] ← 段② 别设(除齿轮菜单)
113
+ ```
114
+
115
+ **两级判定**(与设置键、外观 id 同形,别混着记):
116
+
117
+ | 判据 | 分级 | 谁判 | 会发生什么 |
118
+ |:--|:--:|:--|:--|
119
+ | `set` 的名字 ∈ **段① 宿主专用** | 🔴 **红** | SDK 腿 `linkdesk/no-unowned-context-key` | 作者仓里 lint 报红点名;**运行时第二道网**在 `contextKey:set` 过桥处补一条 `console.error`,但 🔴 **值照写、不拒绝**(见下) |
120
+ | **新**旗子第一段不是本仓 `pluginId` | 🟡 黄(建议) | SDK 腿 | 报点带 `suggested` = 只换第一段的新名(`zzzFlag` → `my-plugin.zzzFlag`)。存量官方 18 仓有 23 个旗子不合此规,迁移由壳侧统一执行——**新旗子请照规矩写** |
121
+ | `set` 的名字 ∈ **段② 约定面** | 🟠 **不判** | 只登记 | 合法,但见上:那是齿轮菜单的位置,别去覆盖 |
122
+
123
+ > **为什么"占宿主专用"是红、"没带自己前缀"只是黄**:占专用旗子有**真害**(顶替宿主状态,两侧都不报错);而"没带前缀"在存量里有 23 个反例,一刀切会把既有插件当场弄坏。分级不同 = 容忍度不同。
124
+
125
+ > 🔴 **运行时为什么"只出声、不拒绝"**(与设置键/外观 id 的"拒登"**不同**):旗子是**状态写**不是**注册**——`contextKey.set(name, value)` 只是往一张表里写值,同名被两方先后写、后者覆盖前者是**正常运行时行为**;而"拒谁"要求运行时知道"谁是先者",可 `contextKey:set` 过 IPC 时**只带 `[key, value]` 两个值、不带写入者身份** ⇒ 「先者保留」在这个面上**结构上做不到**。⇒ 唯一诚实的动作 = 出声点名 + 值照写。**真正的保护在你那边的 lint 里**(带身份、编译期报点),运行时那道只是第二张网。
126
+
80
127
  ### 配方 C —— 一个区域变了,分散在几处的 UI 一起刷新
81
128
 
82
129
  比如"串口断开"要同时影响:侧栏的连接行、主区的按钮、状态栏的计数。**发布一个事件,各处自己订阅:**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.11",
3
+ "version": "0.1.14",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——`docs/03-插件制造` 的发布产物:从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [