@linkdesk/plugin-docs 0.1.12 → 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.
@@ -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
@@ -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
@@ -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.14",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——`docs/03-插件制造` 的发布产物:从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [