@linkdesk/plugin-docs 0.1.46 → 0.1.48

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.
@@ -497,15 +497,55 @@ Plugin A contributes, plugin B references (`"icon": "stm32-chip"` + `"iconSource
497
497
  - Translation files are loaded through `fetchPluginDataFile` (bypassing the Vite glob cache — JSON in a newly installed plugin directory is discovered in real time).
498
498
  - The plugin text iron rule: **all UI text goes through `t()`**, and the i18n key is the original Chinese text (`05 §6`).
499
499
 
500
+ #### 🔴 Whoever declares it translates it — your own text must be translated in your own repo (**a rule, not advice**)
501
+
502
+ **In one line**: **the text you declare is the text you translate.** Anything your plugin declares that is rendered
503
+ as UI text (`name` / `description` in `plugin.json`, view and container titles, command titles, configuration
504
+ **group names / section descriptions / enum display names**, status-bar text, menu and title-bar labels,
505
+ `titleActions` buttons and their dropdown items…), its translation **must live in your own repo's
506
+ `i18n/<lang>.json`** and be declared in `contributes.i18n`.
507
+
508
+ ```jsonc
509
+ // plugin.json
510
+ { "contributes": { "i18n": { "en": "i18n/en.json" } } }
511
+ ```
512
+ ```jsonc
513
+ // i18n/en.json — key = the original Chinese text you declared, value = the translation
514
+ { "设置插件": "Settings", "打开方式": "Opening mode" }
515
+ ```
516
+
517
+ **Why "anywhere is fine" is not fine**: when the declaration lives in your repo and the translation lives in
518
+ **another repo** (for example `lang-defaults` in the shell repo), **the two can never keep up** — you add a
519
+ declaration here and nobody over there knows; cross-repo sync relies on someone remembering, and nobody does.
520
+ (This rule comes from a real miss: the settings plugin's own declaration items stayed Chinese in the English UI.)
521
+
522
+ **Self-check and severity** (leg ⑧ of `npm run verify`; the judge itself lives in the SDK, your repo only calls it):
523
+
524
+ | Object | Severity | Meaning |
525
+ |------|:--:|------|
526
+ | A renderable Chinese string you declared in `plugin.json` has no translation in your own repo | 🔴 **red** | Whoever holds the declaration owns the translation — another repo cannot save it |
527
+ | A key from `t("original Chinese")` in your `src/**` is missing from your own dictionary | ⚠️ **yellow** | The app-level dictionary (`lang-defaults`) is a **legitimate provider**, but ownership is not yours |
528
+
529
+ **⛔ Do not read "it's already in the app-level dictionary" as "nothing to do"** — that means **the UI looks fine
530
+ today**, not that ownership is settled. If that dictionary changes, or your plugin happens to load in a different
531
+ order on someone else's machine, you cannot predict the result. **Adding the pair to your own repo costs one JSON file.**
532
+
533
+ **What does not count** (documented exemptions — don't "fix" them): `description` of commands and params
534
+ (**declaration data** — for contracts and AI, never rendered) · theme/language-pack `label` and `langDefs`
535
+ `aliases` (brand names and language self-names, **proper nouns, never translated**) · every path/ID/context-key
536
+ field (`entry` / `render` / `path` / `when` / `key` / menu-slot `group`…). The **single source of truth** for the
537
+ exemptions is the header of the SDK's `own-dict-coverage` module — **change that when the schema changes**, and
538
+ ⛔ never hand-copy a second list here.
539
+
500
540
  #### Bucket-key naming advice — **give your keys an owner** (advice, not a requirement)
501
541
 
502
542
  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**.
503
543
 
504
544
  **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.
505
545
 
506
- 🔴 **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.**
546
+ 🔴 **Why this is advice and not a requirement**: **a key may legitimately live in the app-level dictionary** (the rule above governs **ownership**, not **reachability**). 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.**
507
547
 
508
- **How much overlap actually exists** (told plainly, not exaggerated — the counts below are a **measurement**, taken when the roster was 18 official plugins, not a live figure): those plugins declared **414 keys**, **65 of which overlap** the `lang-defaults` keys, 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.**
548
+ **How much overlap actually exists** (told plainly, not exaggerated — the counts below are a **measurement**, taken when the roster was 18 official plugins, not a live figure): those plugins declared **414 keys**, **65 of which overlap** the `lang-defaults` keys, 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.** ⚠️ The cleanup for the ownership rule above is **additive** (your own dictionary gets the pair first, the old app-level entries **stay** for now — other plugins and the shell still reference them), so this overlap figure **does not drop to zero just because your repo grew a dictionary**.
509
549
 
510
550
  ⚠️ **Runtime behaviour**: when an overwrite happens the shell emits a `console.warn` naming the **key + language + writer**:
511
551
 
@@ -515,6 +555,8 @@ Your translation file is **one flat layer of keys**, and everyone writes into th
515
555
 
516
556
  **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.
517
557
 
558
+ ⚠️ **Identical values stay silent** (since 2026-09-30): when both sides write the **same pair** (byte-identical value), nothing is reported — there is zero visible difference, and reporting it would drown out real divergence. During the cleanup for the ownership rule above, "own dictionary + app-level dictionary holding the same pair" is the normal state, so only a **differing value** is a real problem.
559
+
518
560
  🔴 **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.
519
561
 
520
562
  ### 3.10 `contributes.titleBar` — top bar buttons
@@ -247,7 +247,7 @@ Multi-theme package:
247
247
  | `minAppVersion` | `string` | Minimum app version requirement |
248
248
  | `docs` | `string` | Bundled documentation path (for resource plugins) |
249
249
  | `cardDocMap` | `object` | Card ID → documentation anchor mapping |
250
- | `i18n` | `object` | Plugin-bundled translations `{ "en": "i18n/en.json", "ja": "i18n/ja.json" }` — key = the plugin UI's source text (the author's native language is recommended). It lives under `contributes.i18n`, not at the top level |
250
+ | `i18n` | `object` | Plugin-bundled translations `{ "en": "i18n/en.json", "ja": "i18n/ja.json" }` — key = the plugin UI's source text (the author's native language is recommended). It lives under `contributes.i18n`, not at the top level. 🔴 **Text your plugin declares must be translated in your own repo** (whoever declares it translates it — see `03 §3.9`) |
251
251
  | `cssVars` | `object` | Plugin-defined CSS variables `{ "--name": { "dark": "#fff", "light": "#000" } }` |
252
252
  | `permissions` | `string[]` | Permission declarations `["serial", "filesystem", "network"]` (enabled in Phase 5+) |
253
253
 
@@ -419,6 +419,8 @@ do not need it (`icon` *is* the identity image).
419
419
 
420
420
  > **opt-IN — without declaring `appearsIn.iconBar` there is no icon of yours in the icon bar.** The old `iconLocation` default of `"top"` (opt-OUT — the editor got squeezed into the icon bar even without declaring anything) has been deprecated; it is now controlled declaratively by `appearsIn.iconBar` (`"top"` = the upper icon group, `"bottom"` = the fixed bottom group).
421
421
 
422
+ > 🔴 **`"bottom"` is a geometric position, not "the gear"** (corrected 2026-09-30): the bottom-left gear is a **shell-owned button** (the icon-bar layout's `owned` field) and has nothing to do with any plugin's declaration. Declaring `"bottom"` merely puts your icon in that bottom group, and clicking it **opens your own tab as usual** — the old "clicking a bottom icon opens the gear menu" behaviour has been removed (background: `docs/04-软件更新/待抉择池/齿轮归属与底部图标位/`).
423
+
422
424
  **Two paths to an icon:**
423
425
 
424
426
  | Path | Prerequisite | Description |
@@ -25,7 +25,7 @@ Follow the official settings plugin (= the `plugin.json` in **the settings plugi
25
25
  // omit core — uninstallable; core: true means the UI has no uninstall button (an anti-mistake-deletion flag, not a category)
26
26
  "factoryRole": "settings", // ① the key — declares you are a member of the "settings set" family
27
27
  "entry": "src/index.tsx", // tab entry (appearsIn.tabBar requires entry)
28
- "appearsIn": { "iconBar": "bottom", "tabBar": true },
28
+ "appearsIn": { "tabBar": true }, // ⛔ don't declare iconBar — the bottom-left gear belongs to the shell (bottom is a position, not the gear)
29
29
  "tabBehavior": { "singleton": true }, // singleton — switching won't open a duplicate if it's already open
30
30
  "contributes": {
31
31
  "viewsContainers": {
@@ -152,6 +152,7 @@ theme-liquid-glass/
152
152
  - Applying: `setRecipe`/`setColorway`, or writing the `app.theme` configuration directly.
153
153
  - Events: `theme:changed` (the payload carries tokens) for live reactions.
154
154
  - Mix-and-match: your theme automatically shows up among the mix-and-match sources in the settings page according to the domains it contributes (`RecipeMeta.domains`), with **zero extra work for the author**.
155
+ - Provenance: the theme card and the command palette mark **who provides** each recipe (shell built-in fallback = "Shell built-in", plugin-contributed = the plugin name) — that line is driven by `RecipeMeta.source`, and the plugin name comes from `plugin.json`'s `name`, with **zero extra work for the author**.
155
156
 
156
157
  ## 5. Migration (existing theme plugins — decision F: zero backward compatibility)
157
158
 
@@ -115,7 +115,7 @@ The table below is **reconciled name by name** against it (gate `scripts/check-r
115
115
  | Host colorway id | `dark-fallback`、`light` | Fallback values of `app.themeColor` and of the colorway source space |
116
116
  | Host icon theme id | `default` | The fallback value of `app.iconTheme` |
117
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) |
118
+ | Host-only context key (plugins **must not** set) | `activeEditor`、`editorCount`、`editorHasSelection`、`inputFocus`、`settingsSlotFilled`、`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
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
120
 
121
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>.`"**.
@@ -495,15 +495,49 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
495
495
  - 翻译文件经 `fetchPluginDataFile` 加载(绕开 Vite glob 缓存——新装插件目录的 JSON 实时发现)。
496
496
  - 插件文字铁律:**所有 UI 文字走 `t()`**,i18n key = 中文原文(`05 §6`)。
497
497
 
498
+ #### 🔴 谁的仓谁译文——自有文案的译名必须住本仓(**规则,不是建议**)
499
+
500
+ **一句话**:**你声明的文案,译名就归你。** 插件自己声明、会被渲染成界面文字的东西(`plugin.json` 的 `name` /
501
+ `description`、视图与容器标题、命令标题、配置**分组名/分节说明/枚举显示名**、状态栏文本、菜单与标题栏标签、
502
+ `titleActions` 按钮与下拉项…),译名**必须写在你自己仓的 `i18n/<lang>.json` 里**并在 `contributes.i18n` 声明。
503
+
504
+ ```jsonc
505
+ // plugin.json
506
+ { "contributes": { "i18n": { "en": "i18n/en.json" } } }
507
+ ```
508
+ ```jsonc
509
+ // i18n/en.json——key = 中文原文(你声明的那些字),value = 译文
510
+ { "设置插件": "Settings", "打开方式": "Opening mode" }
511
+ ```
512
+
513
+ **为什么不是「写哪儿都行」**:声明在本仓、译名住在**另一个仓**(例如壳仓的 `lang-defaults`)时,
514
+ **两边永远追不上**——你在这边加一条声明,那边没有人知道;跨仓同步只能靠人记,人一定记不住。
515
+ (这条规则就来自一次真实漏翻:设置插件在设置页里的声明项,英文界面下一直是中文。)
516
+
517
+ **自检 + 严重度**(`npm run verify` 的 ⑧ 段;判据本体在 SDK,本仓调它):
518
+
519
+ | 对象 | 严重度 | 说明 |
520
+ |------|:--:|------|
521
+ | 你在 `plugin.json` 里声明的可渲染中文串没有本仓译名 | 🔴 **红** | 声明在谁手里译名就归谁——跨仓救不了 |
522
+ | 你 `src/**` 里 `t("中文原文")` 的键不在本仓字典 | ⚠️ **黄** | 应用级字典(`lang-defaults`)是**合法提供方**,只是归属不在你手上 |
523
+
524
+ **⛔ 别把「应用级字典里有」当成「不用补」**——那是**今天界面不错**,不是归属落位;哪天那本字典改了、
525
+ 或者你的插件在别人的机器上碰巧换了加载顺序,你就无从预料。**补进自己仓只多一份 JSON。**
526
+
527
+ **哪些不算**(有据的豁免,别乱补):命令与参数的 `description`(**声明数据**——给契约与 AI 看,不进 UI)·
528
+ 主题/语言包的 `label` 与 `langDefs` 的 `aliases`(品牌名与语言自称,**专名不译**)· 一切路径/ID/上下文键字段
529
+ (`entry` / `render` / `path` / `when` / `key` / 菜单槽位 `group`…)。豁免的**唯一真相源**是 SDK 的
530
+ `own-dict-coverage` 模块头注——**改 schema 时同笔改那里**,⛔ 别在这里手抄第二份清单。
531
+
498
532
  #### 桶键命名建议——**给键加上归属**(建议,不是强制)
499
533
 
500
534
  你的翻译文件是**平铺的一层键**,谁都往同一张表里写:所有插件的键、宿主自己的键、`lang-defaults` 语言包的键,**住在同一本字典里**。同一语言下后注册者覆盖先者,**且此前没有任何提示**。
501
535
 
502
536
  **建议**:给自己的键起带归属的名字,例如 `serial-monitor.打开端口` 而不是 `打开端口`。这样即使名字碰巧相同也与别人无关。
503
537
 
504
- 🔴 **为什么这是建议而不是强制**:**i18n 键可以合法住在应用级字典**。官方 `settings` 插件的 254 处 `t()` 调用,**一个键都不在它自己的仓里**(全住 `lang-defaults` 的 `zh.json` / `en.json`)。插件仓里只有你自己的 `i18n/*.json`——**看不到宿主的字典,也看不到其余插件**,所以「你的键撞了别人」在你自己仓里**永远判不出来**。把它做成拦截 = 必然误报,而误报会让真正该拦的规则失效。⇒ **它是黄灯,不是红灯。**
538
+ 🔴 **为什么这是建议而不是强制**:**键可以合法住在应用级字典**(§3.9 上一条规则管的是**归属**,不是**能不能查得到**)。插件仓里只有你自己的 `i18n/*.json`——**看不到宿主的字典,也看不到其余插件**,所以「你的键撞了别人」在你自己仓里**永远判不出来**。把它做成拦截 = 必然误报,而误报会让真正该拦的规则失效。⇒ **它是黄灯,不是红灯。**
505
539
 
506
- **真实存在多少重合**(如实告诉你,不夸大——下面的数是**一次测量**,取当时官方 18 只的名单,不是活读数):官方插件声明了 **414 个键**,其中与 `lang-defaults` 的键 **65 条重合**,而这 65 条里 **3 条译文已经不一致**——例如 `命令`,宿主给的是 `Command`,而 `serial-monitor` 给的是 `Commands`。**两条都写进同一本字典时,用户看到的究竟是哪一条,取决于插件加载顺序。**
540
+ **真实存在多少重合**(如实告诉你,不夸大——下面的数是**一次测量**,取当时官方 18 只的名单,不是活读数):官方插件声明了 **414 个键**,其中与 `lang-defaults` 的键 **65 条重合**,而这 65 条里 **3 条译文已经不一致**——例如 `命令`,宿主给的是 `Command`,而 `serial-monitor` 给的是 `Commands`。**两条都写进同一本字典时,用户看到的究竟是哪一条,取决于插件加载顺序。** ⚠️ 上面那条归属规则的清扫是**加法**(自有字典先补上,应用级字典里的旧条目**暂留**——别的插件与宿主仍在引用),所以这份重合读数**不会因为你的仓补了字典就立刻归零**。
507
541
 
508
542
  ⚠️ **运行时行为**:发生覆盖时宿主会 `console.warn` 出声,点明**键名 + 语言 + 写入者**:
509
543
 
@@ -513,6 +547,8 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
513
547
 
514
548
  **它是提示,不是拦截**——值照常写入(后注册者胜,语义与今天完全一致),只是这条碰撞从此可查。措辞只称「已有同键,来源未知」:**宿主报得出「谁覆盖了」,报不出「原本属于谁」**,不宣称做不到的事。
515
549
 
550
+ ⚠️ **同值不出声**(2026-09-30 起):两处写的是**同一对映射**(值一模一样)时**不报**——界面零差别,报它只会把真分歧淹掉。上面那条归属规则的清扫期,「自有字典 + 应用级字典并存同一对映射」正是常态,所以只有**值不同**才是真问题。
551
+
516
552
  🔴 **不加前缀的合法情形**:`.py` / `.ts` 这类**扩展名**、`zh` / `en` 这类**语言码**——它们不是「没主」,是**本就不该有主**,加前缀反而语义错误。
517
553
 
518
554
  ### 3.10 `contributes.titleBar`——顶栏按钮
@@ -247,7 +247,7 @@ my-plugin/
247
247
  | `minAppVersion` | `string` | 最低软件版本要求 |
248
248
  | `docs` | `string` | 附带文档路径(资源插件联动) |
249
249
  | `cardDocMap` | `object` | 卡片 ID → 文档锚点映射 |
250
- | `i18n` | `object` | 插件自带翻译 `{ "en": "i18n/en.json", "ja": "i18n/ja.json" }`——key=插件 UI 原文(建议作者母语)。放在 `contributes.i18n` 下,非顶层 |
250
+ | `i18n` | `object` | 插件自带翻译 `{ "en": "i18n/en.json", "ja": "i18n/ja.json" }`——key=插件 UI 原文(建议作者母语)。放在 `contributes.i18n` 下,非顶层。🔴 **本插件自己声明的可渲染文案,译名必须住本仓**(「谁的仓谁译文」——规则与判据见 `03 §3.9`) |
251
251
  | `cssVars` | `object` | 插件自定义 CSS 变量 `{ "--name": { "dark": "#fff", "light": "#000" } }` |
252
252
  | `permissions` | `string[]` | 权限声明 `["serial", "filesystem", "network"]`(Phase 5+ 启用) |
253
253
 
@@ -416,6 +416,8 @@ my-plugin/
416
416
 
417
417
  > **opt-IN——不声明 `appearsIn.iconBar` = 图标栏没有你的图标。** 曾经的 `iconLocation` 默认 `"top"`(opt-OUT——编辑器没声明也挤进图标栏)已被废弃,现在由 `appearsIn.iconBar` 声明式控制(`"top"` = 上部图标组,`"bottom"` = 底部固定组)。
418
418
 
419
+ > 🔴 **`"bottom"` 只是几何位置,不是「齿轮」**(2026-09-30 订正):左下角那颗齿轮是**壳自带按钮**(图标栏布局的 `owned` 字段),与任何插件的声明无关。插件声明 `"bottom"` 只是把自己的图标放进底部那一组,点击**照常开自己的标签页**——旧的「点底部图标弹齿轮菜单」行为已废除(背景见 `docs/04-软件更新/待抉择池/齿轮归属与底部图标位/`)。
420
+
419
421
  **两条路拿到图标:**
420
422
 
421
423
  | 路径 | 前提 | 说明 |
@@ -25,7 +25,7 @@
25
25
  // 不填 core —— 可卸载;core: true 则 UI 无卸载按钮(防误删旗标,非类别)
26
26
  "factoryRole": "settings", // ① 关键——声明自己是"设置套"的一份子
27
27
  "entry": "src/index.tsx", // 标签页入口(appearsIn.tabBar 需要 entry)
28
- "appearsIn": { "iconBar": "bottom", "tabBar": true },
28
+ "appearsIn": { "tabBar": true }, // ⛔ 别声明 iconBar——左下齿轮是壳自带的(bottom 只是位置,不是齿轮)
29
29
  "tabBehavior": { "singleton": true }, // 单例——切换时已开就不重复开
30
30
  "contributes": {
31
31
  "viewsContainers": {
@@ -151,6 +151,7 @@ theme-liquid-glass/
151
151
  - 应用:`setRecipe`/`setColorway` 或直接写 `app.theme` 配置。
152
152
  - 事件:`theme:changed`(payload 带 tokens),做实时联动。
153
153
  - 混搭:你的主题按贡献的域(`RecipeMeta.domains`)自动出现在设置页混搭来源里,**作者零额外工作**。
154
+ - 来源标注:主题卡片与命令面会标出**这条配方是谁提供的**(壳内置兜底 =「壳自带」,插件贡献 = 插件名——数据源就是 `RecipeMeta.source`);插件名自动取 `plugin.json` 的 `name`,**作者零额外工作**。
154
155
 
155
156
  ## 5. 迁移(现有主题插件——决策 F:零向后兼容)
156
157
 
@@ -117,7 +117,7 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
117
117
  | 宿主配色 id | `dark-fallback`、`light` | `app.themeColor` 与配色来源空间的兜底取值 |
118
118
  | 宿主图标主题 id | `default` | `app.iconTheme` 的保底取值 |
119
119
  | 宿主外观哨兵值 | `followTheme` | 混搭来源的「跟随主题」哨兵——**它不是 id**,别拿一个插件 id 去顶它 |
120
- | 宿主专用旗子(插件**禁设**) | `activeEditor`、`editorCount`、`editorHasSelection`、`inputFocus`、`sidebarPosition`、`updateActionable`、`updateButtonLabel` | 你在运行时经 IPC 设它,宿主会 `console.error` **点名你**(值照写:旗子是状态不是注册,运行时拿不到「谁是先者」) |
120
+ | 宿主专用旗子(插件**禁设**) | `activeEditor`、`editorCount`、`editorHasSelection`、`inputFocus`、`settingsSlotFilled`、`sidebarPosition`、`updateActionable`、`updateButtonLabel` | 你在运行时经 IPC 设它,宿主会 `console.error` **点名你**(值照写:旗子是状态不是注册,运行时拿不到「谁是先者」) |
121
121
  | 宿主公开约定旗子(插件**可设**) | `settingKey`、`settingFollowTheme`、`settingModified`、`settingResetsToDefault` | 这 4 个是**公开约定面**:官方 `settings` 插件写、宿主命令的 `when` 读——照约定用,别改语义 |
122
122
 
123
123
  **怎么自查**(你自己的仓里就能跑):装上 `@linkdesk/plugin-sdk` 后,你仓里的 `verify` 会跑四条归属腿
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.46",
3
+ "version": "0.1.48",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [