@linkdesk/plugin-docs 0.1.33 → 0.1.35

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.
@@ -33,7 +33,7 @@
33
33
  | `titleBar` | ✅ | top bar left/right slot buttons | MenuRegistry |
34
34
  | `viewsContainers` | ✅ | declare sidebar/panel containers | ViewContainerService |
35
35
  | `views` | ✅ | register views in a container — any plugin can register in any container | ViewContainerService |
36
- | `floatingPanel` | ✅ | declare that a view can be shown in a shell-internal floating panel (type B) — `viewId` references an already-registered view; without the declaration there is no "Open in Floating Panel" context menu item | declaration addressing → FloatingPanelService |
36
+ | `floatingPanel` | ✅ | declare that a view can be shown in a shell-internal floating panel (type B) — `viewId` references an already-registered view; without the declaration there is no "Open in Floating Panel" context menu item; optional `defaultForm`/`formKey` fix or offer the **first-open form** (§3.15) | declaration addressing → FloatingPanelService |
37
37
  | `i18n` | ✅ | plugin-bundled translation files | i18nResources (i18next namespace) |
38
38
 
39
39
  ### Main-process consumers (2)
@@ -473,7 +473,7 @@ Your translation file is **one flat layer of keys**, and everyone writes into th
473
473
 
474
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
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.**
476
+ **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.**
477
477
 
478
478
  ⚠️ **Runtime behaviour**: when an overwrite happens the shell emits a `console.warn` naming the **key + language + writer**:
479
479
 
@@ -733,6 +733,8 @@ useEffect(() => {
733
733
  | Field | Required | Description |
734
734
  |------|:--:|------|
735
735
  | `viewId` | ✅ | **a view ID already registered in contributes.views** — declaration addressing resolves the plugin/renderPath/title |
736
+ | `defaultForm` | ❌ | the form used the **first time** the view is opened, fixed by the author (the user gets no entry point): `"floatingPanel"` (floating panel) \| `"tab"` (tab) |
737
+ | `formKey` | ❌ | the **first-open** form is **left to the user**: a configuration key name (you declare that key in `contributes.configuration`; its `default` is your default form) |
736
738
 
737
739
  **Declaring is consuming — four things appear automatically:**
738
740
 
@@ -743,7 +745,43 @@ useEffect(() => {
743
745
  | `linkdesk.panel.revealFloating(viewId)` opens the panel programmatically | panel identity toggle semantics — no panel → open; same view → close; another panel → replace |
744
746
  | Uninstalling the declaring plugin → the menu item disappears + revealFloating no-ops without crashing | the declaration unloads with the plugin lifecycle |
745
747
 
746
- **The first declarer = settings** (`core.openSettings`, Ctrl+, opens the panel); **the second declarer, used as a validation vehicle = the `floating-panel-demo` test plugin** (a tab-style view; end-to-end validation of replacement + the right-click return path + unload no-op).
748
+ #### Configurable first-open form (`defaultForm` / `formKey`) — authors who just want the panel to pop out add nothing
749
+
750
+ **Division of labour: the plugin only declares which form it wants; the shell decides and executes** — the plugin has zero execution power and the shell has zero plugin knowledge (the shell hard-codes no plugin ID, so any future declarer works without shell changes).
751
+
752
+ | What the author wants | How to write it | What the user sees in the Settings editor |
753
+ |:--|:--|:--|
754
+ | Fix the form, no user override | `"defaultForm": "tab"` | Nothing (no Settings item appears at all) |
755
+ | Let the user choose | `"formKey": "<plugin-id>.openForm"` plus declaring that key yourself in `contributes.configuration` | The control for that key (toggle/dropdown, rendered from your `type`) |
756
+
757
+ ```json
758
+ {
759
+ "contributes": {
760
+ "floatingPanel": { "viewId": "settings", "formKey": "settings.openForm" },
761
+ "configuration": {
762
+ "title": "Settings plugin",
763
+ "properties": {
764
+ "settings.openForm": {
765
+ "type": "string",
766
+ "enum": ["floatingPanel", "tab"],
767
+ "default": "floatingPanel",
768
+ "description": "Form when opening Settings — floatingPanel / tab"
769
+ }
770
+ }
771
+ }
772
+ }
773
+ }
774
+ ```
775
+
776
+ **The shell's decision chain** (first match wins; executed by "first open" entry points — today that is `core.openSettings`):
777
+
778
+ 1. `formKey` is present and that key **is registered** → read its value: `"floatingPanel"` / `"tab"` is used as-is (**the value *is* the form — no mapping layer**);
779
+ 2. otherwise `defaultForm` (only legal values are accepted);
780
+ 3. neither → **previous behaviour** (a declaring plugin opens as a floating panel — today's settings default).
781
+
782
+ **Four boundaries**: ① it only governs the **first open** — an existing tab is still focused and an already-open panel still toggles shut; changing the form afterwards keeps using the two old paths ("Open in main window" / "Open in Floating Panel"); ② `formKey` and `defaultForm` are **mutually exclusive** (both declared ⇒ schema validation fails — one form from two sources); ③ a typo'd `formKey` / a key that was never registered ⇒ falls back to `defaultForm` (neither = previous behaviour) plus one warning — it **never fails silently**; ④ declaring `"defaultForm": "tab"` on a plugin with no tab form (`appearsIn.tabBar` + `entry`) falls back to the floating panel rather than silently doing nothing.
783
+
784
+ **Currently the only declarer = settings** (`core.openSettings`, Ctrl+, opens the panel, and `settings.openForm` lets the user change it inside the "Settings plugin" group). The mechanism itself is generic and is validated end-to-end (replacement + the right-click return path + unload no-op) — nothing stops you from becoming the second declarer.
747
785
 
748
786
  ---
749
787
 
@@ -51,8 +51,8 @@ my-plugin/
51
51
 
52
52
  | Source root | Location | Form | HMR | Who lives here |
53
53
  |------|------|------|:--:|------|
54
- | **The plugin's own repo** | GitHub `Encaron/linkdesk-plugin-<id>` (local clones land under `E:\linkdesk-plugins\official\<id>\`) | source + SDK build (`npm run build` → `<id>.linkdesk-plugin`) | ✅ (`linkdesk-plugin-sdk dev`) | **all 18 shipped plugins**—one repo each, and the only source of truth for their source |
55
- | **Shell repo fixtures** | `<shell repo>/plugins/<id>/` (`env.appPluginsDir`) | source + Vite on-the-fly compilation | ✅ (`npm run dev` hot reload) | only the two remaining **dev fixtures**: `panel-demo` / `floating-panel-demo` (not shipped, not in the zip) |
54
+ | **The plugin's own repo** | GitHub `Encaron/linkdesk-plugin-<id>` (local clones land under `E:\linkdesk-plugins\official\<id>\`) | source + SDK build (`npm run build` → `<id>.linkdesk-plugin`) | ✅ (`linkdesk-plugin-sdk dev`) | **every shipped plugin** (16 today)—one repo each, and the only source of truth for their source |
55
+ | **Shell repo fixtures** | `<shell repo>/plugins/<id>/` (`env.appPluginsDir`) | source + Vite on-the-fly compilation | ✅ (`npm run dev` hot reload) | only the remaining **dev fixture**: `panel-demo` (not shipped, not in the zip) |
56
56
  | **Installed state** | `{userData}/plugins/<id>/` | pre-built bundle unpacked from the zip | ❌ (changing the package means rebuild + reinstall/rematerialize) | every plugin installed on the user's machine |
57
57
 
58
58
  > 🔴 **Why a shipped plugin's source can't be kept in both places**: as soon as the shell repo and the plugin repo each hold a copy, changing one leaves the other stale, and **no gate can detect the divergence** (the content-fingerprint gate only covers zip contents, not source) ⇒ the source of truth must be unique. What the shell repo keeps are **artifacts** (`bundled-plugins/*.linkdesk-plugin`) and **documentation archives**, not source.
@@ -60,7 +60,7 @@ my-plugin/
60
60
  > **Real-device loop exception (author dev):** in the installed state, changing a package requires "rebuild + reinstall/rematerialize", which in **every author real-device verification** scenario means the one-shot-cycle pain of WPF v2. The real-device loop automates it—an SDK rebuild in seconds + a **direct write** into `{userData}/plugins/<id>` (same-disk overwrite semantics, effective on reload) becomes the cycle, and the author still never touches the shell. The distribution zip's "don't modify your own bundle" discipline is unchanged (that is the package for end users). Design archive → [author real-device debugging loop](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/04-作者真机调试环.md).
61
61
 
62
62
  > **Uninstall semantics (after 2026-09-05):** uninstalling an installed plugin = **delete the `{userData}/plugins/<id>/` directory + settle the ledger entry** (no longer a move into `.disabled/`); only app plugins uninstalled from a repo source tree get moved to the `plugins/.disabled/` graveyard (recoverable via reinstall). The sole owner of the ledger `installed-plugins.json` = the renderer-side PluginInstallService; boot only reads its `removed` marker to avoid accidental restoration.
63
- > 🔵 **Cross-check conclusion (does the `.disabled/` graveyard still have consumers):** **the mechanism remains, with no object at present**. The consumers are alive—`src/pluginLoader/loader.ts` reads it (`reinstallPlugin` / the uninstall toast's "undo" / cross-restart orphan cleanup all treat `env.appPluginsDir/.disabled` as the single authoritative surface). But `env.appPluginsDir` = the shell repo's `plugins/`, and the 18 shipped plugins have moved out ⇒ only the two fixtures remain there, and **there is no longer any "app plugin uninstalled from a repo source tree"**. ⇒ The mechanism is **retained** (it is part of the in-repo plugin dev path; removing it would touch three places in the loader plus the main-process scan surface, so risk outweighs benefit), but **don't** treat it as a revocable-uninstall channel for shipped plugins anymore.
63
+ > 🔵 **Cross-check conclusion (does the `.disabled/` graveyard still have consumers):** **the mechanism remains, with no object at present**. The consumers are alive—`src/pluginLoader/loader.ts` reads it (`reinstallPlugin` / the uninstall toast's "undo" / cross-restart orphan cleanup all treat `env.appPluginsDir/.disabled` as the single authoritative surface). But `env.appPluginsDir` = the shell repo's `plugins/`, and the shipped plugins have moved out ⇒ only the one fixture remains there, and **there is no longer any "app plugin uninstalled from a repo source tree"**. ⇒ The mechanism is **retained** (it is part of the in-repo plugin dev path; removing it would touch three places in the loader plus the main-process scan surface, so risk outweighs benefit), but **don't** treat it as a revocable-uninstall channel for shipped plugins anymore.
64
64
 
65
65
  ---
66
66
 
@@ -757,7 +757,7 @@ button { border: none; }
757
757
 
758
758
  **Why it is worth remembering**: the host itself has **17** such "anchorless selectors" (`*` resets / `html`·`body` / `[data-theme]` / `*:focus-visible` / the scrollbar family / `input[type="number"]`·`select`)—they are a **deliberate shared baseline** that plugins rely on (and may override). Precisely because they exist, **your anchorless selector will hit them**: write `button { }` and the host's buttons plus every other plugin's buttons change with it.
759
759
 
760
- **Migration**: **zero instances today**—a full re-check of the 18 official plugins plus the in-repo fixtures (the "anchorless S2 / cross-party S3" columns of `npm run audit:plugin-prefix -- --all`) is **0** ⇒ **you have nothing to change**; this rule is **preventive**.
760
+ **Migration**: **zero instances today**—a full re-check of the official plugins plus the in-repo fixture (the "anchorless S2 / cross-party S3" columns of `npm run audit:plugin-prefix -- --all`) is **0** ⇒ **you have nothing to change**; this rule is **preventive**.
761
761
 
762
762
  > 🔧 **Maintainer note (authors may skip)**: the rule text (R0 scope / R1 host baseline / R2 / R3) plus the decision formulas and negative controls live in `docs/02-Electron架构/E6_插件生态与发布/01-插件独立构建/样式命名空间归一化/32-任务-选择器形态轴门禁与落地.md`; the host side is guarded by criteria ⑩⑪ of `scripts/check-css-namespace.mjs` (plus the runtime mirror on axis ④ of the probe), and the plugin side by the **fourth and fifth criteria** of the SDK's `check-css-namespace` leg (`checks/selector-form.ts` for S2/S3, and `checks/keyframe-refs.ts` for dangling keyframe references—the latter in place since **2026-09-18**, SDK `≥ 0.1.37`).
763
763
 
@@ -114,7 +114,7 @@ The `entry` field → the loader automatically recognizes this as a view plugin.
114
114
  | `contributes.themes` | theme | registered into ThemeRegistry → theme browser |
115
115
  | `contributes.languages` | language | registered into LanguageRegistry |
116
116
  | `contributes.fileAssociations` | — | registered into FileAssociationService → double-clicking a file opens it automatically |
117
- | `contributes.floatingPanel` | — | Declares that the view can be displayed in a floating panel inside the shell — viewId references an already-registered view; without the declaration there is no "Open in Floating Panel" context-menu item |
117
+ | `contributes.floatingPanel` | — | Declares that the view can be displayed in a floating panel inside the shell — viewId references an already-registered view; without the declaration there is no "Open in Floating Panel" context-menu item; optional `defaultForm`/`formKey` fix or offer the **first-open form** |
118
118
 
119
119
  **A plugin can declare several contributions at once.** A view plugin, for example, can have `entry` + `sidebar` + `statusBar` + `contributes.configuration` + `contributes.commands` — each is registered independently and does not affect the others.
120
120
 
@@ -329,7 +329,7 @@ Plugin-level activation ordering — declares which plugins must be activated be
329
329
 
330
330
  - **③ Switch entry point = a role group on the settings page (appearing dynamically)**: when the settings UI opens it enumerates `listRoles()` → for every **non-settings-plugin role** it calls `list(role)` → **a group is created only when there are ≥2 candidates** (a single candidate makes switching meaningless). Group shape = the switch button on top (listing every candidate for that role, the active one highlighted) + the active set's own configuration below; it reuses a group of the same name where possible (finding the active candidate's own configuration group by pluginId), and only creates a new one otherwise; if the active set has no settings, it shows an empty state. Switching = `setActive` → refetch data → the configuration follows the active set. Switching your settings plugin's **own role** (settings) = the button in the generic area at the top (see `10-building-a-settings-plugin.md`).
331
331
  - **④ Icon bar slot occupancy**: for plugins that declare `factoryRole` (form 2), the icon bar **renders only the active set's icon** and hides inactive ones — "swap the official one out for yours"; form 1 plugins that do not declare it still all show up side by side as before.
332
- - **⑤ Routing seam**: opening settings (`Ctrl+,` / the gear) = `factorySlots.getActive("settings")` → if a tab is already open, focus it / if `floatingPanel` is declared → the floating panel (the payload carries pluginId for composite addressing) / if nothing is declared → open a tab. After switching the active set, all subsequent opens go through the new set, consistently on both ends.
332
+ - **⑤ Routing seam**: opening settings (`Ctrl+,` / the gear) = `factorySlots.getActive("settings")` → if a tab is already open, focus it / **the first-open form comes from the declaration** (`formKey` value → `defaultForm` → previous behaviour): `tab` → open a tab; `floatingPanel` → the floating panel (the payload carries pluginId for composite addressing); with no `floatingPanel` declaration this entry point does nothing (previous behaviour). After switching the active set, all subsequent opens go through the new set, consistently on both ends. **The first-open form only governs the first open** — converting between the panel and a tab afterwards keeps using the old paths (criteria and boundaries → `03-contributes-spec.md` §3.15).
333
333
  - **⑥ Switching sets on the plugin side** (the switch button's click, zero shell changes): `setActive` → tab form = close this set's tab → open the target set (singleton dedupe focuses it if it already exists); floating panel form = `panel.revealFloating(viewId, pluginId?)` **replacing the panel content in place with composite addressing** (no leftover tab popping up behind; if the target set declares no floatingPanel → fall back to opening a tab). Deleting any set → `onPluginLifecycleChange` → refetch → the button disappears on its own.
334
334
 
335
335
  **Two-scenario example (official + third-party plugin marketplace):**
@@ -36,13 +36,29 @@ Follow the official settings plugin (= the `plugin.json` in **the settings plugi
36
36
  { "id": "settings", "title": "Settings", "render": "src/views/SettingsView.tsx", "order": 0 }
37
37
  ]
38
38
  },
39
- "floatingPanel": { "viewId": "settings" } // ③ floating panel form (optional)
39
+ "floatingPanel": { "viewId": "settings", "formKey": "settings.openForm" } // ③ floating panel form (optional) — formKey hands the first-open form to the user
40
40
  }
41
41
  }
42
42
  ```
43
43
 
44
44
  All three key declarations are required: **`factoryRole: "settings"`** (puts you in the shared-area candidate list) + **`contributes.views`** (the actual render component) + **`floatingPanel`** (the `Ctrl+,` fallback form).
45
45
 
46
+ **The first-open form is configurable (optional; write nothing and it opens as a floating panel)**: to let the user choose (floating panel / tab), add `"formKey": "<plugin-id>.openForm"` to `floatingPanel` and declare that key yourself — the key's `default` is your default form:
47
+
48
+ ```json
49
+ "configuration": {
50
+ "title": "Settings plugin",
51
+ "properties": {
52
+ "settings.openForm": {
53
+ "type": "string", "enum": ["floatingPanel", "tab"], "default": "floatingPanel",
54
+ "description": "Form when opening Settings — floatingPanel / tab"
55
+ }
56
+ }
57
+ }
58
+ ```
59
+
60
+ To fix the form with no user override, write `"defaultForm": "tab"` instead (no configuration key ⇒ no Settings item appears at all). The two are **mutually exclusive** (declaring both fails schema validation); the decision chain, the boundaries and the "the shell decides, the plugin only declares" split → [`03-contributes-spec.md` §3.15](03-contributes-spec.md).
61
+
46
62
  ## Data API shape — everything goes through `window.linkdesk.*`
47
63
 
48
64
  Settings plugins are **forbidden from `import @src/core/...`** (the plugin communication iron rule + ESLint `noCoreImportInPlugin`). All data is in the public API:
@@ -62,7 +62,7 @@ The `README.md` in the plugin root directory is displayed in the **"Details" tab
62
62
 
63
63
  ## 6. Live exemplars (copy them and you can't go wrong)
64
64
 
65
- - The READMEs of the 8 official plugins that already embed scene covers are ready-made models: `editor` / `file-tree` / `serial-monitor` / `settings` / `python` / `theme-terminal` / `theme-aurora-glass` / `lang-defaults` (plus the first real third-party plugin, `hello-linkdesk`). The `![…](resources/cover.svg)` at the top of their READMEs is the standard way to write a cover.
65
+ - The READMEs of the 8 official plugins that already embed scene covers are ready-made models: `editor` / `file-tree` / `serial-monitor` / `settings` / `python` / `theme-terminal` / `theme-aurora-glass` / `lang-defaults`. The `![…](resources/cover.svg)` at the top of their READMEs is the standard way to write a cover.
66
66
  - In-page `<video>` / cover link-out examples: the serial-monitor README's git history commits `2f9a52c6b` (real in-page playback) and `8c9d71551` (fullscreen fix) each carry a complete `<video>` / `<a><img></a>` example from the manual testing of that moment, reverted once verified — look at those two commits if you want to copy a complete example.
67
67
 
68
68
  ---
@@ -11,7 +11,7 @@
11
11
 
12
12
  ```
13
13
  E:\linkdesk-plugins\
14
- ├─ official\ ← your own plugins (the 18 official ones + later new plugins)
14
+ ├─ official\ ← your own plugins (the official ones + later new plugins)
15
15
  │ ├─ file-tree\
16
16
  │ └─ settings\
17
17
  └─ third-party\ ← other people's plugins (cloned to study / fork)
@@ -62,7 +62,7 @@ Benchmarked against the empirically verified VS Code position (`ms-vscode.cpptoo
62
62
 
63
63
  **Where you clone a plugin project and what the directory is called have no effect on plugin identity** — a plugin repo is self-contained, and the shell only recognizes the Release URL and the catalog; it **does not recognize local paths at all**. ⇒ The local directory structure can be rearranged at any time, with zero risk.
64
64
 
65
- Live evidence: the source repos of the two plugins `hello-linkdesk` and `first-run-setup` sit flat outside the container and still build, publish, get listed, and install/uninstall normally in the installed app. All 18 official plugins are the same way today (each in its own independent repo).
65
+ Live evidence: all 16 official plugins work this way today — each source repo sits flat outside the container (one independent repo per plugin) and still builds, publishes, gets listed, and installs/uninstalls normally in the installed app.
66
66
 
67
67
  ✅ **So "renaming a directory" is already safe today**: plugin identity = the top-level `pluginId` field (which must be declared explicitly and cannot be changed after publication), **and it has nothing to do with the directory name**.
68
68
 
@@ -117,7 +117,7 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
117
117
  | Criterion | Grade | Judged by | What happens |
118
118
  |:--|:--:|:--|:--|
119
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** |
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 official repos break this rule; the shell migrates them centrally — **write new ones by the rule** |
121
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
122
 
123
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".
@@ -33,7 +33,7 @@
33
33
  | `titleBar` | ✅ | 顶栏左右槽位按钮 | MenuRegistry |
34
34
  | `viewsContainers` | ✅ | 声明侧栏/面板容器 | ViewContainerService |
35
35
  | `views` | ✅ | 往容器注册视图——任何插件可往任意容器注册 | ViewContainerService |
36
- | `floatingPanel` | ✅ | 声明某视图可在壳内悬浮面板显示(类型 B)——viewId 引用已注册视图;未声明则无「在悬浮面板中打开」右键 | 声明寻址 → FloatingPanelService |
36
+ | `floatingPanel` | ✅ | 声明某视图可在壳内悬浮面板显示(类型 B)——viewId 引用已注册视图;未声明则无「在悬浮面板中打开」右键;可选 `defaultForm`/`formKey` 定/选**首开形态**(§3.15) | 声明寻址 → FloatingPanelService |
37
37
  | `i18n` | ✅ | 插件自带翻译文件 | i18nResources(i18next 命名空间) |
38
38
 
39
39
  ### 主进程消费(2 个)
@@ -473,7 +473,7 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
473
473
 
474
474
  🔴 **为什么这是建议而不是强制**:**i18n 键可以合法住在应用级字典**。官方 `settings` 插件的 254 处 `t()` 调用,**一个键都不在它自己的仓里**(全住 `lang-defaults` 的 `zh.json` / `en.json`)。插件仓里只有你自己的 `i18n/*.json`——**看不到宿主的字典,也看不到其余插件**,所以「你的键撞了别人」在你自己仓里**永远判不出来**。把它做成拦截 = 必然误报,而误报会让真正该拦的规则失效。⇒ **它是黄灯,不是红灯。**
475
475
 
476
- **今天真实存在多少重合**(如实告诉你,不夸大):官方 18 个插件声明的键(414 个)与 `lang-defaults` 的键有 **65 条重合**,其中 **3 条译文已经不一致**——例如 `命令`,宿主给的是 `Command`,而 `serial-monitor` 给的是 `Commands`。**两条都写进同一本字典时,用户看到的究竟是哪一条,取决于插件加载顺序。**
476
+ **真实存在多少重合**(如实告诉你,不夸大——下面的数是**一次测量**,取当时官方 18 只的名单,不是活读数):官方插件声明了 **414 个键**,其中与 `lang-defaults` 的键 **65 条重合**,而这 65 条里 **3 条译文已经不一致**——例如 `命令`,宿主给的是 `Command`,而 `serial-monitor` 给的是 `Commands`。**两条都写进同一本字典时,用户看到的究竟是哪一条,取决于插件加载顺序。**
477
477
 
478
478
  ⚠️ **运行时行为**:发生覆盖时宿主会 `console.warn` 出声,点明**键名 + 语言 + 写入者**:
479
479
 
@@ -733,6 +733,8 @@ useEffect(() => {
733
733
  | 字段 | 必需 | 说明 |
734
734
  |------|:--:|------|
735
735
  | `viewId` | ✅ | **contributes.views 中已注册的视图 ID**——声明寻址解析出插件/renderPath/title |
736
+ | `defaultForm` | ❌ | **首次打开**用哪种形态,作者定死(用户没入口):`"floatingPanel"`(悬浮面板)\| `"tab"`(标签页) |
737
+ | `formKey` | ❌ | **首次打开**形态**交给用户选**:填一个配置键名(键由你在 `contributes.configuration` 里声明,键的 `default` 即作者默认形态) |
736
738
 
737
739
  **声明即消费,四件事自动出现:**
738
740
 
@@ -743,7 +745,43 @@ useEffect(() => {
743
745
  | `linkdesk.panel.revealFloating(viewId)` 可编程弹面板 | 面板身份开关键——无面板→开;同视图→关;他面板→替换 |
744
746
  | 卸载声明插件 → 右键条目消失 + revealFloating no-op 不崩 | 声明随插件生命周期卸载 |
745
747
 
746
- **首批声明者 = settings**(`core.openSettings` Ctrl+, 弹面板);**第二声明者验证载体 = `floating-panel-demo`** 测试插件(标签页型视图,端到端验证替换 + 右键回程 + 卸载 no-op)。
748
+ #### 首开形态可配(`defaultForm` / `formKey`)——只想要面板能弹出来的作者一个字都不用加
749
+
750
+ **分工:插件只声明想要哪种,壳决定并执行**——插件零执行权、壳零插件知识(壳侧不认任何插件 ID,换一只声明者自动生效,不必改壳)。
751
+
752
+ | 作者想要 | 写法 | 用户在设置页的入口 |
753
+ |:--|:--|:--|
754
+ | 定死形态,不给用户改 | `"defaultForm": "tab"` | 无(设置页不出现任何项) |
755
+ | 让用户自己选 | `"formKey": "<插件id>.openForm"` + 自己在 `contributes.configuration` 里声明这个键 | 该键的控件(布尔/下拉按你的 `type` 渲染) |
756
+
757
+ ```json
758
+ {
759
+ "contributes": {
760
+ "floatingPanel": { "viewId": "settings", "formKey": "settings.openForm" },
761
+ "configuration": {
762
+ "title": "设置插件",
763
+ "properties": {
764
+ "settings.openForm": {
765
+ "type": "string",
766
+ "enum": ["floatingPanel", "tab"],
767
+ "default": "floatingPanel",
768
+ "description": "打开设置时的形态——floatingPanel 悬浮面板 / tab 标签页"
769
+ }
770
+ }
771
+ }
772
+ }
773
+ }
774
+ ```
775
+
776
+ **壳的判定链**(第一命中即定;由「第一次打开」这一类入口执行——今天 = `core.openSettings`):
777
+
778
+ 1. `formKey` 有、且那个键**已注册** → 读它的值:`"floatingPanel"` / `"tab"` 直接用(**值即形态,无映射层**);
779
+ 2. 否则看 `defaultForm`(合法值才认);
780
+ 3. 都没有 → **原行为**(声明了面板即面板——今天设置插件的默认)。
781
+
782
+ **四条边界**:① 只管**第一次打开**——已有标签页仍聚焦、面板开着再点仍按开关键关掉,打开之后想换形态照旧走「在主窗口中打开」/「在悬浮面板中打开」两条老路;② `formKey` 与 `defaultForm` **互斥**(同时写 ⇒ schema 校验红:一个形态两个来源);③ `formKey` 写错字 / 没注册那个键 ⇒ 降级 `defaultForm`(都没有 = 原行为)+ 出声一条 warn——**不静默失效**;④ 声明 `"defaultForm": "tab"` 但插件没有标签页形态(`appearsIn.tabBar` + `entry`)⇒ 落回悬浮面板,不静默无动作。
783
+
784
+ **当前唯一声明者 = settings**(`core.openSettings` Ctrl+, 弹面板,`settings.openForm` 在「设置插件」组里让用户改)。机制本身是通用的,且已端到端验证过(替换 + 右键回程 + 卸载 no-op)——你随时可以成为第二个声明者。
747
785
 
748
786
  ---
749
787
 
@@ -51,8 +51,8 @@ my-plugin/
51
51
 
52
52
  | 代码根 | 位置 | 形态 | HMR | 谁住这里 |
53
53
  |------|------|------|:--:|------|
54
- | **插件自己的仓** | GitHub `Encaron/linkdesk-plugin-<id>`(本地克隆落在容器目录 `E:\linkdesk-plugins\official\<id>\`) | 源码 + SDK build(`npm run build` → `<id>.linkdesk-plugin`) | ✅(`linkdesk-plugin-sdk dev`) | **18 只发货插件全部**——一只一个仓,源码真相源只此一处 |
55
- | **壳仓夹具** | `<壳仓>/plugins/<id>/`(`env.appPluginsDir`) | 源码 + Vite 即时编译 | ✅(`npm run dev` 热更) | 只剩两只**开发夹具**:`panel-demo` / `floating-panel-demo`(不发货、不进 zip) |
54
+ | **插件自己的仓** | GitHub `Encaron/linkdesk-plugin-<id>`(本地克隆落在容器目录 `E:\linkdesk-plugins\official\<id>\`) | 源码 + SDK build(`npm run build` → `<id>.linkdesk-plugin`) | ✅(`linkdesk-plugin-sdk dev`) | **全部发货插件**(今天 16 只)——一只一个仓,源码真相源只此一处 |
55
+ | **壳仓夹具** | `<壳仓>/plugins/<id>/`(`env.appPluginsDir`) | 源码 + Vite 即时编译 | ✅(`npm run dev` 热更) | 只剩一只**开发夹具**:`panel-demo`(不发货、不进 zip) |
56
56
  | **安装态** | `{userData}/plugins/<id>/` | zip 解出的预构建 bundle | ❌(改包需重 build + 重装/重物化) | 用户机器上所有已装插件 |
57
57
 
58
58
  > 🔴 **为什么发货插件的源码不能两边都留一份**:一旦壳仓与插件仓各有一份,改了这头那头不变,而**没有任何门禁能发现分叉**(内容指纹门禁只管 zip 内容,不管源码)⇒ 真相源必须唯一。壳仓留下的两样是**产物**(`bundled-plugins/*.linkdesk-plugin`)与**文档档案**,不是源码。
@@ -60,7 +60,7 @@ my-plugin/
60
60
  > **真机环例外(作者 dev):** 安装态改包需「重 build + 重装/重物化」在**作者每次真机验证**场景 = WPF v2 一次性循环痛苦。真机环自动化它——SDK 秒级重建 + **直写** `{userData}/plugins/<id>`(同盘覆盖语义,reload 即生效)成循环,作者仍不碰壳。分发 zip 的「不自改 bundle」纪律不变(那是给终用户的包)。设计档案 → [04-作者真机调试环.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/04-作者真机调试环.md)。
61
61
 
62
62
  > **卸载语义(2026-09-05 后):** 安装态插件卸载 = **删 `{userData}/plugins/<id>/` 目录 + 账本销账**(不再是 `.disabled/` 移入);只有 repo 源码树里的 app 插件卸载才移 `plugins/.disabled/` 坟场(可 reinstall 恢复)。账本 `installed-plugins.json` 唯一 owner = 渲染进程 PluginInstallService,boot 只读它的 `removed` 标记防误恢复。
63
- > 🔵 **核对结论(`.disabled/` 坟场还有没有消费者)**:**机制仍在、当前无对象**。消费者是活的——`src/pluginLoader/loader.ts` 读它(`reinstallPlugin` / 卸载 toast 的「撤销」/ 跨重启孤儿清理都以 `env.appPluginsDir/.disabled` 为唯一权威面)。但 `env.appPluginsDir` = 壳仓 `plugins/`,而 18 只发货插件已外移 ⇒ 那里只剩两只夹具,**没有「在 repo 源码树里被卸载的 app 插件」了**。⇒ 机制**保留**(它是仓内插件 dev 路径的一部分,删它要动 loader 三处 + 主进程扫描面,风险大于收益),但**不要**再把它当成发货插件的可撤销卸载通道。
63
+ > 🔵 **核对结论(`.disabled/` 坟场还有没有消费者)**:**机制仍在、当前无对象**。消费者是活的——`src/pluginLoader/loader.ts` 读它(`reinstallPlugin` / 卸载 toast 的「撤销」/ 跨重启孤儿清理都以 `env.appPluginsDir/.disabled` 为唯一权威面)。但 `env.appPluginsDir` = 壳仓 `plugins/`,而发货插件已外移 ⇒ 那里只剩一只夹具,**没有「在 repo 源码树里被卸载的 app 插件」了**。⇒ 机制**保留**(它是仓内插件 dev 路径的一部分,删它要动 loader 三处 + 主进程扫描面,风险大于收益),但**不要**再把它当成发货插件的可撤销卸载通道。
64
64
 
65
65
  ---
66
66
 
@@ -759,7 +759,7 @@ button { border: none; }
759
759
  共享基线**,插件一直在依赖它们(也可以覆写)。正因为它们存在,**你的无锚选择器一定会命中它们**:
760
760
  你写 `button { }`,宿主的按钮、其他插件的按钮,全都会跟着变。
761
761
 
762
- **迁移**:**今天 0 存量**——官方 18 只插件 + 壳内夹具全量复核(`npm run audit:plugin-prefix -- --all`
762
+ **迁移**:**今天 0 存量**——官方插件 + 壳内夹具全量复核(`npm run audit:plugin-prefix -- --all`
763
763
  的「无锚 S2 / 跨方 S3」两列)都是 **0** ⇒ **你不需要改任何东西**;这条规矩是**预防性**的。
764
764
 
765
765
  > 🔧 **维护者注(作者可跳过)**:规则正文(R0 口径 / R1 宿主基线 / R2 / R3)与判定式、负控见
@@ -114,7 +114,7 @@ my-plugin/
114
114
  | `contributes.themes` | theme | 注册到 ThemeRegistry → 主题浏览器 |
115
115
  | `contributes.languages` | language | 注册到 LanguageRegistry |
116
116
  | `contributes.fileAssociations` | — | 注册到 FileAssociationService → 双击文件自动打开 |
117
- | `contributes.floatingPanel` | — | 声明视图可在壳内悬浮面板显示——viewId 引用已注册视图;未声明则无「在悬浮面板中打开」右键 |
117
+ | `contributes.floatingPanel` | — | 声明视图可在壳内悬浮面板显示——viewId 引用已注册视图;未声明则无「在悬浮面板中打开」右键;可选 `defaultForm`/`formKey` 定/选**首开形态** |
118
118
 
119
119
  **插件可同时声明多种贡献。** 比如一个视图插件可以有 `entry` + `sidebar` + `statusBar` + `contributes.configuration` + `contributes.commands`——全部独立注册,互不影响。
120
120
 
@@ -329,7 +329,7 @@ my-plugin/
329
329
 
330
330
  - **③ 切换入口 = 设置页角色分组(动态出现)**:设置 UI 打开时枚举 `listRoles()` → 对每个**非设置插件角色** `list(role)` → **候选 ≥2 才建组**(单候选无切换意义)。组形态 = 切换按钮在顶(列出该角色全部候选,激活高亮)+ 激活套自己的配置在下方;复用同名组优先(按 pluginId 找激活候选自己的配置组)、没有才新建;激活套无配置项 → 空状态。切换 = `setActive` → 重拉数据 → 配置随激活套换。你的设置插件**自身角色**(settings)的切换 = 顶部通用区按钮(见 `10-如何造一个设置插件.md`)。
331
331
  - **④ 图标栏占槽**:声明 `factoryRole` 的插件(形态二),图标栏**只渲染激活套图标**、非激活套隐藏——"把官方的剔除换成你的";不声明的形态一照旧全出并排。
332
- - **⑤ 路由接缝**:打开设置(`Ctrl+,` / 齿轮)= `factorySlots.getActive("settings")` → 已开标签页聚焦 / 声明了 `floatingPanel` → 悬浮面板(载荷带 pluginId 复合寻址)/ 无声明 → 开标签页。切换激活套后,后续打开全走新套,两端一致。
332
+ - **⑤ 路由接缝**:打开设置(`Ctrl+,` / 齿轮)= `factorySlots.getActive("settings")` → 已开标签页聚焦 / **按声明定首开形态**(`formKey` 键值 → `defaultForm` → 原行为):`tab` → 开标签页;`floatingPanel` → 悬浮面板(载荷带 pluginId 复合寻址);无 `floatingPanel` 声明 → 本入口不动(原行为)。切换激活套后,后续打开全走新套,两端一致。**首开形态只管「第一次打开」**——打开之后的面板↔标签页互转仍各走原路(判据与边界 → `03-插件contributes规范.md` §3.15)。
333
333
  - **⑥ 全插件侧换套**(切换按钮点击,零壳改动):`setActive` → 标签页形态 = 关本套 tab → 开目标套(singleton 去重已存在则聚焦);悬浮面板形态 = `panel.revealFloating(viewId, pluginId?)` **原地复合替换**面板内容(不背后弹残留 tab;目标套无 floatingPanel 声明 → 退回开标签页)。删任意套 → `onPluginLifecycleChange` → 重拉 → 按钮自动消失。
334
334
 
335
335
  **双场景示例(官方 + 第三方 插件市场):**
@@ -36,13 +36,29 @@
36
36
  { "id": "settings", "title": "设置", "render": "src/views/SettingsView.tsx", "order": 0 }
37
37
  ]
38
38
  },
39
- "floatingPanel": { "viewId": "settings" } // ③ 悬浮面板形态(可选)
39
+ "floatingPanel": { "viewId": "settings", "formKey": "settings.openForm" } // ③ 悬浮面板形态(可选)——formKey 把首开形态交给用户
40
40
  }
41
41
  }
42
42
  ```
43
43
 
44
44
  三个关键声明缺一不可:**`factoryRole: "settings"`**(进通用区候选列表)+ **`contributes.views`**(真实渲染组件)+ **`floatingPanel`**(`Ctrl+,` 兜底形态)。
45
45
 
46
+ **首开形态可配(可选,一个字不写 = 打开即悬浮面板)**:想让用户自己选(悬浮面板 / 标签页),就给 `floatingPanel` 加 `"formKey": "<插件id>.openForm"` 并自己声明那个键——键的 `default` 即你的默认形态:
47
+
48
+ ```json
49
+ "configuration": {
50
+ "title": "设置插件",
51
+ "properties": {
52
+ "settings.openForm": {
53
+ "type": "string", "enum": ["floatingPanel", "tab"], "default": "floatingPanel",
54
+ "description": "打开设置时的形态——floatingPanel 悬浮面板 / tab 标签页"
55
+ }
56
+ }
57
+ }
58
+ ```
59
+
60
+ 定死不让用户改则写 `"defaultForm": "tab"`(不给配置项,设置页就不出现任何项)。两者**互斥**(同时写 = schema 校验红);判定链、边界与「壳决定并执行、插件只声明」的分工 → [`03-插件contributes规范.md` §3.15](03-插件contributes规范.md)。
61
+
46
62
  ## 数据 API 形状——全走 `window.linkdesk.*`
47
63
 
48
64
  设置插件**禁止 `import @src/core/...`**(插件通信铁律 + ESLint `noCoreImportInPlugin`)。数据全在公开 API:
@@ -62,7 +62,7 @@
62
62
 
63
63
  ## 六、活的样板(照抄不会错)
64
64
 
65
- - 官方 8 只已嵌场景封面的插件 README = 现成范本:`editor` / `file-tree` / `serial-monitor` / `settings` / `python` / `theme-terminal` / `theme-aurora-glass` / `lang-defaults`(另有首个第三方真插件 `hello-linkdesk`)。看它们 README 顶部那张 `![…](resources/cover.svg)` 就是封面标准写法。
65
+ - 官方 8 只已嵌场景封面的插件 README = 现成范本:`editor` / `file-tree` / `serial-monitor` / `settings` / `python` / `theme-terminal` / `theme-aurora-glass` / `lang-defaults`。看它们 README 顶部那张 `![…](resources/cover.svg)` 就是封面标准写法。
66
66
  - 页内 `<video>` / 封面外链写法:串口监视器 README 的 git 历史 commit `2f9a52c6b`(页内真播)与 `8c9d71551`(全屏修复)各带一段当时手测用的完整 `<video>` / `<a><img></a>` 示例,验完即撤——要抄完整写法可看那两次提交。
67
67
 
68
68
  ---
@@ -11,7 +11,7 @@
11
11
 
12
12
  ```
13
13
  E:\linkdesk-plugins\
14
- ├─ official\ ← 你自己的插件(官方 18 只 + 后续新插件)
14
+ ├─ official\ ← 你自己的插件(官方那些 + 后续新插件)
15
15
  │ ├─ file-tree\
16
16
  │ └─ settings\
17
17
  └─ third-party\ ← 别人的插件(clone 下来学习/二开的)
@@ -62,7 +62,7 @@ E:\linkdesk-plugins\
62
62
 
63
63
  **插件工程 clone 到哪、目录叫什么,都不影响插件身份**——插件仓是自足的,壳只认 Release URL 与 catalog,**不认本地路径**。⇒ 本地目录结构随时可重排,零风险。
64
64
 
65
- 活证据:`hello-linkdesk` 与 `first-run-setup` 两只插件的源码仓平铺在容器外,照样构建、发布、上架、被安装版正常装卸。官方 18 只现在也全是这样(各自独立一仓)。
65
+ 活证据:官方 16 只现在全是这样——每只的源码仓平铺在容器外(各自独立一仓),照样构建、发布、上架、被安装版正常装卸。
66
66
 
67
67
  ✅ **所以「改目录名」这件事今天已经安全**:插件身份 = 顶层 `pluginId` 字段(必须显式声明,发布后不可改),**与目录名无关**。
68
68
 
@@ -117,7 +117,7 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
117
117
  | 判据 | 分级 | 谁判 | 会发生什么 |
118
118
  |:--|:--:|:--|:--|
119
119
  | `set` 的名字 ∈ **段① 宿主专用** | 🔴 **红** | SDK 腿 `linkdesk/no-unowned-context-key` | 作者仓里 lint 报红点名;**运行时第二道网**在 `contextKey:set` 过桥处补一条 `console.error`,但 🔴 **值照写、不拒绝**(见下) |
120
- | **新**旗子第一段不是本仓 `pluginId` | 🟡 黄(建议) | SDK 腿 | 报点带 `suggested` = 只换第一段的新名(`zzzFlag` → `my-plugin.zzzFlag`)。存量官方 18 仓有 23 个旗子不合此规,迁移由壳侧统一执行——**新旗子请照规矩写** |
120
+ | **新**旗子第一段不是本仓 `pluginId` | 🟡 黄(建议) | SDK 腿 | 报点带 `suggested` = 只换第一段的新名(`zzzFlag` → `my-plugin.zzzFlag`)。存量官方仓有 23 个旗子不合此规,迁移由壳侧统一执行——**新旗子请照规矩写** |
121
121
  | `set` 的名字 ∈ **段② 约定面** | 🟠 **不判** | 只登记 | 合法,但见上:那是齿轮菜单的位置,别去覆盖 |
122
122
 
123
123
  > **为什么"占宿主专用"是红、"没带自己前缀"只是黄**:占专用旗子有**真害**(顶替宿主状态,两侧都不报错);而"没带前缀"在存量里有 23 个反例,一刀切会把既有插件当场弄坏。分级不同 = 容忍度不同。
@@ -620,9 +620,12 @@
620
620
  "description": "Floating Panel declaration — declares that a view in contributes.views can be shown in a Floating Panel inside the shell. viewId must reference an already registered view: the declaration is resolved into pluginId/renderPath/title. Without it there is no 'Open in Floating Panel' context menu entry. The first declarer is settings (Ctrl+, opens the panel).",
621
621
  "required": ["viewId"],
622
622
  "properties": {
623
- "viewId": { "type": "string", "description": "View ID — a view registered in contributes.views" }
623
+ "viewId": { "type": "string", "description": "View ID — a view registered in contributes.views" },
624
+ "defaultForm": { "enum": ["floatingPanel", "tab"], "description": "Form used the FIRST time this view is opened — 'floatingPanel' (Floating Panel inside the shell) or 'tab'. Author-fixed: the user gets no Settings entry. Omit to keep the previous behaviour (a declaring plugin opens as a Floating Panel). Mutually exclusive with formKey." },
625
+ "formKey": { "type": "string", "description": "Configuration key that lets the USER choose the first-open form. Must be declared in this same plugin's contributes.configuration: its default is the author's default form, and its value must be 'floatingPanel' or 'tab' (any other value falls back to the author-fixed form). Declaring it makes the item appear in the Settings editor. Mutually exclusive with defaultForm." }
624
626
  },
625
- "additionalProperties": false
627
+ "additionalProperties": false,
628
+ "not": { "required": ["defaultForm", "formKey"] }
626
629
  },
627
630
  "i18n": {
628
631
  "type": "object",
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.33",
4
- "description": "LinkDesk 插件作者文档(离线包)——`docs/03-插件制造` 的发布产物:从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
3
+ "version": "0.1.35",
4
+ "description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [
7
7
  "docs",