@linkdesk/plugin-docs 0.1.14 → 0.1.16

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.
@@ -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)
@@ -560,6 +560,14 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
560
560
  | `ldk-notif-icon-spin` | 通知图标的旋转 |
561
561
  | `ldk-notif-progress-scan` | 通知的进度扫描 |
562
562
 
563
+ **引用的名字必须在架子上**——纪律 2 说的是「改名时同笔改引用」;这条是它的另一半,而且**机器会查**:
564
+ 你 `animation` / `animation-name` 里写的名字,要么是**本仓 CSS 里 `@keyframes` 定义过的**,要么是
565
+ **上面那张保留表里的**(引用宿主的动画是**合法消费**,不会判你)。引一个**谁都没定义**的名字,
566
+ 动画**不报错、不警告,只是不动**——症状是「我的动画怎么没生效」,而控制台一片安静(同一个窗口里
567
+ 还有别的插件和宿主在跑,你很难一眼看出是这一条)。`@linkdesk/plugin-sdk` **≥ 0.1.37** 起,插件的
568
+ lint 会把这种**悬空引用**逐条报出来(**文件名 + 行号 + 名字**);确需引用一个门禁看不见的名字
569
+ (例如动画由运行时注入),用标准 `eslint-disable` 注释写明理由。
570
+
563
571
  > 🔧 **维护者注(作者可跳过)**:上面两张表的「**保留名**」「**保留的关键帧名**」两列都是**机器读的**——`npm run check` 里的门禁
564
572
  > (`scripts/check-reserved-names-doc-sync.mjs`)把它们与登记表
565
573
  > `packages/plugin-sdk/schemas/reserved-class-names.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)(决策论证)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.14",
3
+ "version": "0.1.16",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——`docs/03-插件制造` 的发布产物:从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [