@linkdesk/plugin-docs 0.1.12 → 0.1.15

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.
@@ -465,6 +465,26 @@ Plugin A contributes, plugin B references (`"icon": "stm32-chip"` + `"iconSource
465
465
  - Translation files are loaded through `fetchPluginDataFile` (bypassing the Vite glob cache — JSON in a newly installed plugin directory is discovered in real time).
466
466
  - The plugin text iron rule: **all UI text goes through `t()`**, and the i18n key is the original Chinese text (`05 §6`).
467
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
+
468
488
  ### 3.10 `contributes.titleBar` — top bar buttons
469
489
 
470
490
  ```json
@@ -74,4 +74,78 @@ The version number has **four landing points that must share one source**; chang
74
74
 
75
75
  ---
76
76
 
77
+ ## 7. Names the host reserves—don't take them, and don't count on "borrowing"
78
+
79
+ **The one-sentence rule (memorise this instead of the table): names the host reserves are off limits; every name you invent must carry your `<pluginId>` prefix.**
80
+
81
+ Both halves guard the same failure: a **public roster** — one global name table that **anyone can write into, where nobody checks ownership, and where a collision reports nothing**, so one side ends up **silently ineffective**. Per family, the damage looks like this:
82
+
83
+ - **Command ids**: one command declared by two parties — which one wins depends on registration order.
84
+ - **Config keys**: your value overwrites a host setting (the user reads that as "my settings changed on their own / got lost").
85
+ - **Appearance ids** (recipes / colorways / icon themes): the theme dropdown shows two entries with the same id and the selection state looks wrong.
86
+ - **Context keys**: someone else's `when` expression evaluates against your state (menus and shortcuts flicker in and out).
87
+
88
+ ### 7.1 Where the list lives, and who owns it
89
+
90
+ The list is **generated**: the shell scans its own source and emits `scripts/host-reserved.json`, then ships a **byte-identical** copy inside `@linkdesk/plugin-sdk`. So **you already have it locally**:
91
+
92
+ ```
93
+ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
94
+ ```
95
+
96
+ The table below is **reconciled name by name** against it (gate `scripts/check-reserved-names-doc-sync.mjs`, wired into `npm run check`):
97
+
98
+ | Family | Reserved name | What happens if you take it |
99
+ |:--|:--|:--|
100
+ | Host command prefix | `app.`、`core.`、`theme.`、`update.`、`view.`、`workbench.` | Your command id lands in the host's own segment — in the command palette and the keybindings page it looks like a host feature |
101
+ | Host protocol id | `bracket` | Same name as the host's bracket-matching protocol handler ⇒ one of the two never runs, with no error |
102
+ | Host pseudo plugin id | `app`、`appearance`、`update` | The host registers as a "plugin" too (shell core / appearance / updater) ⇒ these ids read as the host itself |
103
+ | Host config key | `app.schemaVersion` | The config **internal version marker** (invisible in the settings UI, never registered) — taking it derails migration bookkeeping and the user's data looks lost |
104
+ | Host config key | `app.theme`、`app.themeColor`、`app.themeColorMode`、`app.iconTheme` | Theme and colours — taking it overwrites the theme the user is currently using |
105
+ | Host config key | `app.appearanceMode`、`app.accentColor`、`app.accentMode`、`app.accentSource`、`app.menuStyle` | Light/dark mode, accent colour, menu style |
106
+ | Host config key | `app.backgroundImage`、`app.backgroundMask`、`app.backgroundOpacity`、`app.zoneBackgroundImage` | Background and per-zone backgrounds |
107
+ | Host config key | `app.glassBlur`、`app.glassOpacity`、`app.glassSaturate`、`app.glassTint` | The four glass parameters |
108
+ | Host config key | `app.surfaceRadius`、`app.zoneRadius`、`app.zoneRadiusScale` | Corner radii |
109
+ | Host config key | `app.fontFamily`、`app.fontFamilyMono`、`app.fontTone`、`app.uiFontScale` | Fonts and text scaling |
110
+ | Host config key | `app.mixMode`、`app.mixFont`、`app.mixBackground`、`app.mixReset` | Mix-and-match sources |
111
+ | Host config key | `app.language` | UI language |
112
+ | Host config key | `app.osIntegration.dirMenu`、`app.osIntegration.fileAssoc`、`app.osIntegration.fileMenu` | OS integration (context menu, file associations) |
113
+ | Host config key | `app.update.mode`、`app.update.showReleaseNotes` | Update channel |
114
+ | Host recipe id | `dark`、`light` | The **fallback values** of `app.theme`. ⚠️ `light` also carries a **grant**: the official `theme-defaults` plugin is the official implementer of the host's light fallback, so only it may declare that id |
115
+ | Host colorway id | `dark-fallback`、`light` | Fallback values of `app.themeColor` and of the colorway source space |
116
+ | Host icon theme id | `default` | The fallback value of `app.iconTheme` |
117
+ | Host appearance sentinel | `followTheme` | The "follow the theme" sentinel of a mix source — **it is not an id**, so don't try to shadow it with a plugin id |
118
+ | Host-only context key (plugins **must not** set) | `activeEditor`、`editorCount`、`editorHasSelection`、`inputFocus`、`sidebarPosition`、`updateActionable`、`updateButtonLabel` | Set one of these at runtime over IPC and the host logs a `console.error` **naming you** (the value is still written: these are state, not registrations, so the runtime cannot tell who came first) |
119
+ | Shared-contract context key (plugins **may** set) | `settingKey`、`settingFollowTheme`、`settingModified`、`settingResetsToDefault` | These four are a **public contract**: the official `settings` plugin writes them, host commands read them in `when` clauses — use them as specified, don't change their meaning |
120
+
121
+ **How to check yourself** (from your own repo): once `@linkdesk/plugin-sdk` is installed, your repo's `verify` runs four ownership legs (command ids / config keys / appearance ids / context keys); whichever one you violate is reported with its location plus the suggested fix, **"should start with `<pluginId>.`"**.
122
+
123
+ ### 7.2 Why three kinds of global concept names need no prefix
124
+
125
+ Three kinds of names look ownerless but **should never have an owner** — prefixing them is a **semantic error**, not normalisation:
126
+
127
+ | Name | Examples | Why a prefix would be wrong |
128
+ |:--|:--|:--|
129
+ | **File-association extensions** | `.md`, `.json`, `.ts` | They refer to a **filesystem/OS** concept — a prefix means the system no longer recognises the file type |
130
+ | **Language-definition extensions** | `langDefs[].extensions` | Same: the field has to line up with external tools and editors for the same language |
131
+ | **Language-pack language codes** | `zh` / `en` / `ja` (`langDefs[].id`, the keys of `contributes.i18n`) | They are **BCP 47 language tags** — the world writes them exactly like this; `my-plugin.zh` is not a language |
132
+
133
+ ⇒ By design these are **permanently out of scope** for the criteria (neither flagged nor registered): not an oversight, but a deliberate carve-out.
134
+
135
+ ### 7.3 i18n dictionary keys—**recommended** to carry ownership, not required
136
+
137
+ Translation files are **one flat key layer**: every plugin's keys and the host's keys live in the same dictionary. We **recommend** writing your keys as `<pluginId>.<原文>` (e.g. `serial-monitor.打开端口`), but this is a **recommendation, not a rule** — the reasoning and today's real overlap numbers live in [03-contributes-spec §3.9 桶键命名建议](03-contributes-spec.md) (**that is the single source**; this document doesn't repeat it).
138
+
139
+ ### 7.4 Migration notes—renamed names never lose your values
140
+
141
+ Renames on the host side **all come with migrations**, so users don't reconfigure anything and you don't have to compensate for them:
142
+
143
+ - **Appearance ids** (recipes / colorways / icon themes): today they all have the `<pluginId>.<stem>` shape (e.g. `theme-aurora-glass.aurora-glass`). Older values in the user's `settings.json` are carried over by the **shell-side migration v12** (five keys: `app.theme` / `app.themeColor` / `app.mixFont` / `app.mixBackground` / `app.iconTheme`).
144
+ - **Command ids / config keys / user keybindings**: the rename rounds carry migrations too (keys move, keybinding ids move with them).
145
+ - ⚠️ **A migration can only carry a value once the new name exists**: for appearance ids, the plugin must **register the new name first** before the shell can tell where the old name should map. That is exactly why updating the app before the plugins leaves a window — hence the shell runs an extra **reconciliation pass on every startup** (it writes no version marker, so unlike ordinary migrations it doesn't stop after the first run).
146
+
147
+ Your only takeaway as a plugin author: **don't invent compatibility aliases for old host names** — old-name mapping is the shell's job. Just declare names in the **new shape**.
148
+
149
+ ---
150
+
77
151
  > **← Index:** [00-readme](00-readme.md) · **Related:** [15-multi-repo-and-local-workspace](15-multi-repo-and-local-workspace.md) · [06-plugin-json-spec](06-plugin-json-spec.md) · [plugin-source-externalization/09-naming-conventions.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md) (decision rationale)
@@ -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:**
@@ -465,6 +465,26 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
465
465
  - 翻译文件经 `fetchPluginDataFile` 加载(绕开 Vite glob 缓存——新装插件目录的 JSON 实时发现)。
466
466
  - 插件文字铁律:**所有 UI 文字走 `t()`**,i18n key = 中文原文(`05 §6`)。
467
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
+
468
488
  ### 3.10 `contributes.titleBar`——顶栏按钮
469
489
 
470
490
  ```json
@@ -74,4 +74,87 @@
74
74
 
75
75
  ---
76
76
 
77
+ ## 七、宿主保留的名字——不许占,也别指望「借用」
78
+
79
+ **一句话规则(不用查表就能记住):宿主保留的名字不许占;插件自己写的名字必须带 `<pluginId>` 前缀。**
80
+
81
+ 要防的是同一件事:**公共花名册**——一张全局名字表,**谁都能往里写、没有人查归属、撞了不报错**,
82
+ 结果总有一方**静默失效**。落在不同家族上就是不同的坏法:
83
+
84
+ - **命令 id** 撞了 ⇒ 同一条命令有两个人声明,谁生效看注册顺序;
85
+ - **设置键** 撞了 ⇒ 你的值把宿主的设置顶掉(用户会觉得「我的设置自己变了 / 丢了」);
86
+ - **外观 id**(配方 / 配色 / 图标主题)撞了 ⇒ 主题下拉里出现两条同 id 的条目,选中态看着乱;
87
+ - **上下文旗子** 撞了 ⇒ 别人的 `when` 表达式判到你的状态上(菜单/快捷键时隐时现)。
88
+
89
+ ### 7.1 名单在哪、谁说的算
90
+
91
+ 这份名单是**生成式**的:壳仓扫描自己的源码产出 `scripts/host-reserved.json`,
92
+ 并往 `@linkdesk/plugin-sdk` 里发一份**逐字节相同**的副本。⇒ **你本地就有**:
93
+
94
+ ```
95
+ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
96
+ ```
97
+
98
+ 下面这张表与它**逐名对账**(门禁 `scripts/check-reserved-names-doc-sync.mjs`,跑在 `npm run check` 里)——
99
+
100
+ | 家族 | 保留的名字 | 你会撞上什么 |
101
+ |:--|:--|:--|
102
+ | 宿主命令前缀 | `app.`、`core.`、`theme.`、`update.`、`view.`、`workbench.` | 你的命令 id 落进宿主自己的段——命令面板、快捷键设置页里它看起来像宿主的功能 |
103
+ | 宿主协议 id | `bracket` | 与宿主的括号匹配协议处理器同名 ⇒ 有一方不生效(不报错) |
104
+ | 宿主伪 pluginId | `app`、`appearance`、`update` | 宿主自己也以「插件」身份注册(壳通用 / 外观 / 更新)⇒ 用这些 id 会被当成宿主自己 |
105
+ | 宿主配置键 | `app.schemaVersion` | 配置的**内部版本标志**(设置界面里看不到、也没有注册过)——占它会让迁移记账错乱,用户数据看着丢 |
106
+ | 宿主配置键 | `app.theme`、`app.themeColor`、`app.themeColorMode`、`app.iconTheme` | 主题与配色——占它 = 直接顶掉用户当前选的主题 |
107
+ | 宿主配置键 | `app.appearanceMode`、`app.accentColor`、`app.accentMode`、`app.accentSource`、`app.menuStyle` | 亮暗模式、强调色、菜单样式 |
108
+ | 宿主配置键 | `app.backgroundImage`、`app.backgroundMask`、`app.backgroundOpacity`、`app.zoneBackgroundImage` | 背景与区域背景 |
109
+ | 宿主配置键 | `app.glassBlur`、`app.glassOpacity`、`app.glassSaturate`、`app.glassTint` | 玻璃材质四参 |
110
+ | 宿主配置键 | `app.surfaceRadius`、`app.zoneRadius`、`app.zoneRadiusScale` | 圆角 |
111
+ | 宿主配置键 | `app.fontFamily`、`app.fontFamilyMono`、`app.fontTone`、`app.uiFontScale` | 字体与字号 |
112
+ | 宿主配置键 | `app.mixMode`、`app.mixFont`、`app.mixBackground`、`app.mixReset` | 混搭来源 |
113
+ | 宿主配置键 | `app.language` | 界面语言 |
114
+ | 宿主配置键 | `app.osIntegration.dirMenu`、`app.osIntegration.fileAssoc`、`app.osIntegration.fileMenu` | 系统集成(右键菜单、文件关联) |
115
+ | 宿主配置键 | `app.update.mode`、`app.update.showReleaseNotes` | 更新通道 |
116
+ | 宿主配方 id | `dark`、`light` | `app.theme` 的**兜底取值**。⚠️ `light` 另有一张**证照**:官方 `theme-defaults` 是宿主亮兜底的官方实现者,只有它有权声明这个 id |
117
+ | 宿主配色 id | `dark-fallback`、`light` | `app.themeColor` 与配色来源空间的兜底取值 |
118
+ | 宿主图标主题 id | `default` | `app.iconTheme` 的保底取值 |
119
+ | 宿主外观哨兵值 | `followTheme` | 混搭来源的「跟随主题」哨兵——**它不是 id**,别拿一个插件 id 去顶它 |
120
+ | 宿主专用旗子(插件**禁设**) | `activeEditor`、`editorCount`、`editorHasSelection`、`inputFocus`、`sidebarPosition`、`updateActionable`、`updateButtonLabel` | 你在运行时经 IPC 设它,宿主会 `console.error` **点名你**(值照写:旗子是状态不是注册,运行时拿不到「谁是先者」) |
121
+ | 宿主公开约定旗子(插件**可设**) | `settingKey`、`settingFollowTheme`、`settingModified`、`settingResetsToDefault` | 这 4 个是**公开约定面**:官方 `settings` 插件写、宿主命令的 `when` 读——照约定用,别改语义 |
122
+
123
+ **怎么自查**(你自己的仓里就能跑):装上 `@linkdesk/plugin-sdk` 后,你仓里的 `verify` 会跑四条归属腿
124
+ (命令 id / 配置键 / 外观 id / 上下文旗子);哪条犯了会直接报点并给出**「应以 `<pluginId>.` 开头」**的改法。
125
+
126
+ ### 7.2 三类「全局概念名」为什么不需要前缀
127
+
128
+ 有三种名字,看着「没主」,其实**本就不该有主**——给它们加前缀是**语义错误**,不是规范化:
129
+
130
+ | 名字 | 例子 | 为什么不能加前缀 |
131
+ |:--|:--|:--|
132
+ | **文件关联扩展名** | `.md`、`.json`、`.ts` | 它对的是**操作系统与文件系统**的通用概念——加前缀等于让系统认不出这个文件类型 |
133
+ | **语言定义扩展名** | `langDefs[].extensions` | 同上:这个字段要能和外部工具、编辑器对上同一个语言 |
134
+ | **语言包语言码** | `zh` / `en` / `ja`(`langDefs[].id`、`contributes.i18n` 的键) | 它是 **BCP 47 语言标签**,全世界的语言码就这些写法——`my-plugin.zh` 不是一门语言 |
135
+
136
+ ⇒ 判据上它们**恒空转**(既不判红也不登记):不是漏网,是明确划出去。
137
+
138
+ ### 7.3 i18n 字典键——**建议**带归属,但不是强制
139
+
140
+ 翻译文件是**平铺的一层键**,所有插件的键、宿主的键都住在同一本字典里。**建议**你把键写成
141
+ `<pluginId>.<原文>`(如 `serial-monitor.打开端口`);但它是**建议不是规则**——理由与今天真实的重合
142
+ 统计写在 [03-插件contributes规范 §3.9 桶键命名建议](03-插件contributes规范.md)(**那里是唯一落点**,本篇不重复)。
143
+
144
+ ### 7.4 迁移说明——改过名的东西,你的值不会被丢
145
+
146
+ 宿主自己这一侧的改名**都带迁移**,用户不用重调、你也不用替用户兜:
147
+
148
+ - **外观 id**(配方 / 配色 / 图标主题):今天一律是 `<pluginId>.<词干>` 形状(如
149
+ `theme-aurora-glass.aurora-glass`)。用户 `settings.json` 里的旧值由**壳侧迁移 v12** 搬过去
150
+ (五个键:`app.theme` / `app.themeColor` / `app.mixFont` / `app.mixBackground` / `app.iconTheme`);
151
+ - **命令 id / 设置键 / 用户自定义快捷键**:改名轮同样带迁移(键搬家、快捷键 id 跟着搬);
152
+ - ⚠️ **迁移只在「插件已就位」时才搬得动**:外观 id 的新名必须**先由插件注册出来**,壳才认得出旧名该映到哪 ——
153
+ 这正是「先更新软件、后更新插件」会出现空窗的原因,壳侧为此多了一道**每次启动都跑的补跑通道**
154
+ (它不写版本号,所以不会像普通迁移那样「跑过一次就再也不跑」)。
155
+
156
+ 对你(插件作者)的影响只有一条:**别自己发明宿主的旧名做兼容**——旧名映射是壳的事,你声明**新形状**的名字即可。
157
+
158
+ ---
159
+
77
160
  > **← 索引:** [00-README](00-README.md) · **相关:** [15-多仓开发与本地工作区](15-多仓开发与本地工作区.md) · [06-plugin.json规范](06-plugin.json规范.md) · [插件源码外移层/09-命名规范.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md)(决策论证)
@@ -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.12",
3
+ "version": "0.1.15",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——`docs/03-插件制造` 的发布产物:从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [