@linkdesk/plugin-docs 0.1.5 → 0.1.7

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.
@@ -31,8 +31,8 @@ A few key points (a summary of Matrix §2; the matrix wins on details):
31
31
  |------|------|
32
32
  | **The contract has 40 namespaces** | The pool injects 39 (the only missing one is `bridge`); the shell injects 22; mock injects 12 |
33
33
  | **Pool = the plugin runtime source of truth** | Plugins run in the pool preload — namespaces injected by the pool are **required**; `bridge` is real-shell-only |
34
- | **"Shell-only" ≠ plugins can't call it** | `window.*`/`shell.*`/`hotExit.*`/`getFilePath` **are actually injected in the pool** (N1 superset note) — the older version's ❌ shell-only marking for those surfaces was wrong |
35
- | **Contract required-surface drift is now zero** | D1 `env.get(pluginId)` forwarding, D2 `clipboard.readText` shell completion, D3 `dialog.openFile` shell completion — all three are implemented, with no `?` degradation |
34
+ | **"Shell-only" ≠ plugins can't call it** | `window.*`/`shell.*`/`hotExit.*`/`getFilePath` **are actually injected in the pool** — the older version's ❌ shell-only marking for those surfaces was wrong |
35
+ | **Contract required-surface drift is now zero** | `env.get(pluginId)` forwarding, `clipboard.readText` shell completion, `dialog.openFile` shell completion — all three are implemented, with no `?` degradation |
36
36
 
37
37
  ---
38
38
 
@@ -81,10 +81,10 @@ async function list(): Promise<FileEntry[]> {
81
81
  | **decorations** | **Synchronous contract**: `provideDecoration` returns `FileDecoration \| null \| undefined` and **must not return a Promise** (async providers are skipped); a repeated `registerProvider` for the same pluginId idempotently overwrites; unregister/register automatically fires a full refresh notification `onDidChange([])`; if a provider throws, that entry is self-healed away |
82
82
  | **filesystem** | Plugin permissions: read/write its own data directory, read the workspace directory, **other plugins' directories are off-limits** |
83
83
  | **configuration** | Config key naming rule `<pluginId>.<property>` (e.g. `editor.fontSize`, `serial-monitor.baudRate`) |
84
- | **serial** | **Multi-port routing:** the `portName` of the open/close/action-targeting interfaces is **optional** — omitted = the single open port (0 ports throws "serial port not open"; ≥2 ports throws "multiple serial ports open, please specify portName"; **failures are visible, never silent**). The three streaming channels (`onData`/`onStats`/`onSystem`) carry **object** payloads with a `portName` routing key (`SerialDataPayload`/`SerialStatsPayload`/`SerialSystemPayload`) — subscribers filter by **their session's port** (key=portName is the generic routing-key pattern: whoever consumes filters; the shell does not collect on their behalf). Each tab is still single-port (D3), and the session-to-port binding lives on the plugin side |
84
+ | **serial** | **Multi-port routing:** the `portName` of the open/close/action-targeting interfaces is **optional** — omitted = the single open port (0 ports throws "serial port not open"; ≥2 ports throws "multiple serial ports open, please specify portName"; **failures are visible, never silent**). The three streaming channels (`onData`/`onStats`/`onSystem`) carry **object** payloads with a `portName` routing key (`SerialDataPayload`/`SerialStatsPayload`/`SerialSystemPayload`) — subscribers filter by **their session's port** (key=portName is the generic routing-key pattern: whoever consumes filters; the shell does not collect on their behalf). Each tab is still single-port, and the session-to-port binding lives on the plugin side |
85
85
  | **panel** | `panel.reveal(viewId)` focuses a Bottom Panel view through declarative addressing — panel hidden → expand it and switch to that view (the same mechanism as Ctrl+J); already shown → switch and focus; **viewId not in the panel container → no-op** (no error). **`panel.moveToEditor` has been removed** (deprecated content migration — moving position is the job of the layout command). `panel.revealFloating(viewId)` pops a view out as an in-shell Floating Panel (type B) — declared addressing. Declarative addressing = the ViewContainerService global view index (`contributes.views` registers a view in **any container**, not just panel — plugins declare `contributes.floatingPanel.viewId` to reference it). **Identity toggle key**: no panel → open; same view → close (toggle); another panel → replace; **viewId undeclared / declaring plugin not installed → no-op** (no crash). Default panel actions = "Open in main window" (appears only when the declaring plugin can open as a tab) + maximize toggle + close |
86
86
  | **hotExit** | Crash recovery only — dirty content is written to disk at `%APPDATA%/linkdesk/hot-exit/` (a single-source path convention owned by the main process; plugins never write there directly); after saving/closing a tab, call `clear` to delete the backup |
87
- | **shell** | Shell-level OS actions: `showItemInFolder(p)` highlights a single file in Explorer / `openInTerminal(dirPath, terminalExe?, customCommand?)` opens an external terminal / `startDrag(filePath, iconPath?)` drags out to the desktop. **`pluginLocation(pluginId)` / `openPluginFolder(pluginId, kind)` are the plugin-disk-location pair** — the former returns `{ installDir, dataDir } | null` (**it hands over identity, not the right to assemble paths**: the main process resolves paths and the plugin takes the result; not found on disk → `null`; `dataDir` is non-`null` only once the plugin has **actually written to disk**, and empty/absent means that row shouldn't be drawn); the latter's `kind: "install" \| "data"` opens the directory **contents** in Explorer (the same feel as `appearance.revealStorage`, not `showItemInFolder`'s single-file highlight) — the `install` directory not being on disk throws, while `data` creates an empty directory first, then opens. **(G4): `relaunch` genuinely restarts the app** (quits and relaunches the process) — ⚠️ **injected by the shell preload only (the contract marks it `?` optional)**, so pool-side callers must check existence first (`window.linkdesk.shell.relaunch?.`). The difference from `window.location.reload` is **whether the pool survives**: the pool is a separate `WebContentsView` that a shell reload does not rebuild, so after updating a view-type plugin a reload only shows the old bundle; after `relaunch` the current process terminates immediately, so **don't rely on its return value** (the Promise never settles) |
87
+ | **shell** | Shell-level OS actions: `showItemInFolder(p)` highlights a single file in Explorer / `openInTerminal(dirPath, terminalExe?, customCommand?)` opens an external terminal / `startDrag(filePath, iconPath?)` drags out to the desktop. **`pluginLocation(pluginId)` / `openPluginFolder(pluginId, kind)` are the plugin-disk-location pair** — the former returns `{ installDir, dataDir } | null` (**it hands over identity, not the right to assemble paths**: the main process resolves paths and the plugin takes the result; not found on disk → `null`; `dataDir` is non-`null` only once the plugin has **actually written to disk**, and empty/absent means that row shouldn't be drawn); the latter's `kind: "install" \| "data"` opens the directory **contents** in Explorer (the same feel as `appearance.revealStorage`, not `showItemInFolder`'s single-file highlight) — the `install` directory not being on disk throws, while `data` creates an empty directory first, then opens. **`relaunch` genuinely restarts the app** (quits and relaunches the process) — ⚠️ **injected by the shell preload only (the contract marks it `?` optional)**, so pool-side callers must check existence first (`window.linkdesk.shell.relaunch?.`). The difference from `window.location.reload` is **whether the pool survives**: the pool is a separate `WebContentsView` that a shell reload does not rebuild, so after updating a view-type plugin a reload only shows the old bundle; after `relaunch` the current process terminates immediately, so **don't rely on its return value** (the Promise never settles) |
88
88
  | **appearance** | `revealStorage` opens the appearance storage directory (`userData/appearance`) — the main process resolves the path and uses `shell.openPath` to open the Explorer **contents** (not `showItemInFolder`'s single-file highlight); a missing directory is created as well (opening it shows the storage location, and an empty directory is legal), while an `openPath` failure throws and fails loud. Returns `Promise<void>` |
89
89
  | **app** | `app.getVersion` = the host software version (`Promise<string>`, read-only) — the only runtime source = Electron `app.getVersion` (a single point in `package.json`, 02 §2.3); **the entry point for comparing the main software version** (consumed by marketplace minAppVersion and the update check). The shell also has a private `getProductInfo` extension (the data source for the about page's 8 fields — not in the contract, so pool plugins can't call it) |
90
90
  | **tabs** | **Cross-window resource event wiring:** `updateLabelBySourceId(sourceId, label)` / `closeBySourceId(sourceId)` = **whole-window broadcast semantics** — the resource holder's tab updates/closes in the main window and in every detached window; `sourceId` is the globally unique resource identity (file path/session id), and a change to it is a global fact (the wiring **does not require the caller to be in the same window as the tab** — a detached window's tab updates the moment the sidebar renames or deletes the resource, matching VS Code). `focusBySourceId(sourceId)` = **routed by originating window** (a view action that focuses one specific window, not a global fact). **No new APIs** — it reuses existing surfaces; this behavior contract is guaranteed by the whole-window broadcast |
@@ -51,7 +51,7 @@ 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 (D1), and the only source of truth for their source |
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
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) |
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
 
@@ -163,7 +163,7 @@ Author-side notes on install/uninstall/update/reinstall are in [02 plugin lifecy
163
163
  | `core: true` plugins can't be uninstalled (accidental-deletion guard) | `builtin/` built-in extensions |
164
164
  | Uninstall = delete directory + settle the ledger (really deleted); only source-tree app plugins move to `.disabled/` | Uninstall = delete files (not recoverable) |
165
165
  | `env.get(id).pluginDataDir` | `ExtensionContext.storagePath` |
166
- | `core: true` plugin shipping = `bundled-plugins/*.linkdesk-plugin` (**a first-launch seed**: boot only fills in what's missing and **never refreshes installed copies**; but **the box itself does refresh with the shell version**—before packaging, `sync:bundled` pulls each plugin's "latest released version", D3) | Ships with app updates (built into the installer) |
166
+ | `core: true` plugin shipping = `bundled-plugins/*.linkdesk-plugin` (**a first-launch seed**: boot only fills in what's missing and **never refreshes installed copies**; but **the box itself does refresh with the shell version**—before packaging, `sync:bundled` pulls each plugin's "latest released version") | Ships with app updates (built into the installer) |
167
167
  | `requires` **runtime** dependency orchestration ([02 §4](02-plugin-lifecycle.md)) | `extensionDependencies` resolved at install time |
168
168
 
169
169
  ---
@@ -1,7 +1,7 @@
1
1
  # Plugin UI Authoring Conventions
2
2
 
3
3
  > **In one line: the core already provides the standard components and registries—don't hand-roll wheels. Hand-rolling = inconsistent style + something to tear out at the next normalization.**
4
- > Skim this before writing a plugin, to avoid B62-style rework.
4
+ > Skim this before writing a plugin, to avoid the same kind of rework.
5
5
  > **Reconciled against the implementation on 2026-09-06**: flatten-to-single-root (no plugins/{builtin,user}) · shared controls go through @linkdesk/ui · distribution = `.linkdesk-plugin` zip. References to the corresponding mechanisms have been cleaned out of this page.
6
6
 
7
7
  ---
@@ -36,7 +36,7 @@ window.linkdesk.menu.registerItems("editorContext", "myPlugin", [
36
36
  <ContextMenu menuId="editorContext" />
37
37
  ```
38
38
 
39
- **Rationale:** `<ContextMenu>` brings its own backdrop + four blur paths (Escape / backdrop click / window blur / option click) + keyboard navigation + when-condition filtering. You can't hand-roll those four blur paths—B62 lesson.
39
+ **Rationale:** `<ContextMenu>` brings its own backdrop + four blur paths (Escape / backdrop click / window blur / option click) + keyboard navigation + when-condition filtering. You can't hand-roll those four blur paths.
40
40
 
41
41
  **MenuId is an open string (`src/core/registry/commands/MenuRegistry.ts` `export type MenuId = string`)—a plugin declaring any string at all is the contract; no shell code change is needed.** Shell built-in registration points (the MENU_SLOTS constant table):
42
42
 
@@ -75,7 +75,7 @@ return createPortal(
75
75
  );
76
76
  ```
77
77
 
78
- **Rationale:** under the keep-alive architecture inactive tabs are `display: none`, and children aren't visible even with `position: fixed` (B54 lesson). Only rendering into `document.body` escapes the component-tree constraint.
78
+ **Rationale:** under the keep-alive architecture inactive tabs are `display: none`, and children aren't visible even with `position: fixed`. Only rendering into `document.body` escapes the component-tree constraint.
79
79
 
80
80
  ---
81
81
 
@@ -317,7 +317,7 @@ const file = await window.linkdesk.dialog.openFile({
317
317
  });
318
318
  ```
319
319
 
320
- **Rationale:** all three are rendered uniformly by the in-pool host (QuickPickHost / **the bell wide notification panel** / DialogHost)—styles match the shell and scale with the theme and font size. Hand-rolled overlays = inconsistent style + `position: fixed` breaking under keep-alive (B54). Full signatures are in `contracts/linkdesk.d.ts`.
320
+ **Rationale:** all three are rendered uniformly by the in-pool host (QuickPickHost / **the bell wide notification panel** / DialogHost)—styles match the shell and scale with the theme and font size. Hand-rolled overlays = inconsistent style + `position: fixed` breaking under keep-alive. Full signatures are in `contracts/linkdesk.d.ts`.
321
321
 
322
322
  > ⚠️ **Notifications are not "auto-vanishing floating cards"** (notification-surface unification and correction): the bottom-right narrow toast pipeline has been deleted entirely, and **the only notification surface = the status bar bell wide panel**. Three things authors need to know:
323
323
  > 1. **Notifications don't pop a card, don't steal focus, and don't block interaction**—they go into the bell (unread count +1), and the user only sees them after opening it. Don't treat notifications as a "must be seen" channel: if the user has to decide on the spot → use `dialog.confirm` (modal, steals focus).
@@ -549,8 +549,8 @@ both stylesheets land on the same element.
549
549
 
550
550
  | Source | Reserved names | Notes |
551
551
  |---|---|---|
552
- | Host global utility classes | `.input` | Input-box utility—**just use it** (it exists for your inputs) |
553
- | Shared component classes + host container classes | **the whole `ldk-` namespace**—today: `ldk-badge`, `ldk-button`, `ldk-combobox`, `ldk-mdv`, `ldk-selectbox`, `ldk-sle`, `ldk-slider`, `ldk-toggle` (shared components), plus the host's own container classes such as `ldk-titlebar` | Class names of the badge / button / combobox / Markdown container / select / string-list editor / slider / toggle components in `@linkdesk/ui`. **You don't have to memorize them**—remember one thing: **anything starting with `ldk-` belongs to the host itself (shared components + host UI containers), so don't put it on your own elements** |
552
+ | The input-box utility the host **gives you** | `.ldk-input` | Input-box utility—**just use it** (it exists for your inputs). ⚠️ It is the **one** name in the whole `ldk-` family you're encouraged to **consume** (every other `ldk-` name means "hands off"; this one means "take it") |
553
+ | Shared component classes + host container classes | **the whole `ldk-` namespace**—today: `ldk-badge`, `ldk-button`, `ldk-combobox`, `ldk-mdv`, `ldk-selectbox`, `ldk-sle`, `ldk-slider`, `ldk-toggle` (shared components), plus the host's own container classes such as `ldk-titlebar`, `ldk-input`, `ldk-setting-group` | Class names of the badge / button / combobox / Markdown container / select / string-list editor / slider / toggle components in `@linkdesk/ui`. **You don't have to memorize them**—remember one thing: **anything starting with `ldk-` belongs to the host itself (shared components + host UI containers), so don't put it on your own elements** (the one exception is `.ldk-input` on the row above: that one is **for you**) |
554
554
 
555
555
  **`@keyframes` names work the same way**—the host already uses the animation names below, so avoid them when naming your own animations. A collision has the same consequence as a class name (the later definition wins, the earlier one is dropped), and it is equally **silent**: one of the two animations simply stops playing, with nothing in the console.
556
556
 
@@ -636,6 +636,15 @@ component. **Nothing to do before you upgrade; when you upgrade, it's one prefix
636
636
 
637
637
  > Want to see whether your project has bare names right now? Run `npm run verify` in the project root.
638
638
 
639
+ ### 12.3 The host's input-box utility was renamed: `.input` → `.ldk-input` (2026-09-16)
640
+
641
+ **In one line: if your plugin wrote `className="input"`, change it to `className="ldk-input"`—the styling is identical, only the name changed.**
642
+
643
+ - **What changed**: the host used to call its input-box utility **`.input`** (no prefix—the only host public name without `ldk-`). That conflicted with rule 1 above ("every cross-party name carries a namespace") ⇒ it is now **`.ldk-input`**. The host's **setting-group card**, `.setting-group`, was renamed to **`.ldk-setting-group`** at the same time.
644
+ - **Who is affected**: **any plugin that wrote `className="input"` in its own JSX/TSX**—among the official plugins, `settings` and `serial-monitor` used it and were updated in the same release batch. **The fix is one place**: `className="input"` → `className="ldk-input"`; the same for concatenated forms (`"input my-input"` → `"ldk-input my-input"`). **Zero styling change**—same rule, same CSS variables, only the name.
645
+ - **What happens if you don't**: the input doesn't error; it simply **loses the host-provided appearance** (background / border / radius / padding) and looks like a browser-native input.
646
+ - **When you must change it**: as soon as you run on the **new shell**. The new shell version is **`0.2.0`**, and both official plugins now declare `minAppVersion: "0.2.0"` in `plugin.json`—declare the same value in your plugin and users on an older shell get a clear "requires app version ≥0.2.0" message instead of an unstyled input (see [04-distribution-format §minAppVersion](04-distribution-format.md) for the semantics).
647
+
639
648
  ---
640
649
 
641
650
  ## Quick Reference
@@ -111,9 +111,9 @@ The `entry` field → the loader automatically recognizes this as a view plugin.
111
111
  | `contributes.configuration` | — | registered into ConfigurationRegistry → rendered automatically by the Settings Editor |
112
112
  | `contributes.menus` | — | registered into MenuService → context menus generated dynamically |
113
113
  | `contributes.keybindings` | — | registered into KeybindingRegistry → global keyboard listening |
114
- | `contributes.themes` | theme (P6) | registered into ThemeRegistry → theme browser |
115
- | `contributes.languages` | language (P6) | registered into LanguageRegistry |
116
- | `contributes.fileAssociations` | — (P6) | registered into FileAssociationService → double-clicking a file opens it automatically |
114
+ | `contributes.themes` | theme | registered into ThemeRegistry → theme browser |
115
+ | `contributes.languages` | language | registered into LanguageRegistry |
116
+ | `contributes.fileAssociations` | — | registered into FileAssociationService → double-clicking a file opens it automatically |
117
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 |
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.
@@ -35,16 +35,16 @@ E:\linkdesk-plugins\
35
35
 
36
36
  ---
37
37
 
38
- ## 3. Repository names are completely free (D5/N2)
38
+ ## 3. Repository names are completely free
39
39
 
40
40
  **Repository names are not forced to carry any prefix; third parties have zero constraints.** This has been settled by the maintainer: naming your own plugin (repo) is a legitimate right of the author and can't be dictated.
41
41
 
42
- - **A recommended but non-mandatory convention**: official plugin repos uniformly use `linkdesk-plugin-<id>` (N3 pending the user's sign-off; once signed off, the text lives in [plugin-source-externalization/09-naming-conventions.md §5](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md) — maintained in that one place only); third parties may do as they please.
42
+ - **A recommended but non-mandatory convention**: official plugin repos uniformly use `linkdesk-plugin-<id>` (the text lives in [plugin-source-externalization/09-naming-conventions.md §5](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md) — maintained in that one place only); third parties may do as they please.
43
43
  - **The cost of renaming a repo**: published catalog entries have `owner/repo` embedded in `downloadUrl` / `readmeUrl`, so **renaming breaks the download and README links of already-published plugins** (the source itself is unaffected). Republishing one new entry after the rename heals it, but old version entries still point at the old links — **if you can avoid changing it, don't; if you must, do it early.**
44
44
 
45
45
  ---
46
46
 
47
- ## 4. Identity vs. display name vs. repository name (D5)
47
+ ## 4. Identity vs. display name vs. repository name
48
48
 
49
49
  Three "names" that have nothing to do with one another; conflating them is the root of every naming problem:
50
50
 
@@ -1,7 +1,7 @@
1
1
  # Naming Conventions — Seven Names, One Identity
2
2
 
3
3
  > 2026-09-14 · **Reader = plugin author.** After reading, you can answer four questions: **how do I choose an id? can it be changed? how do I change the display name? what should the repo be called?**
4
- > The decision rationale (N1-N6) and the VS Code empirical evidence live in [plugin-source-externalization/09-naming-conventions.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md) — this document is the author-facing landing point, and of the two there is **only one place to maintain**: change the rule here first and point back; don't create a second copy.
4
+ > The decision rationale and the VS Code empirical evidence live in [plugin-source-externalization/09-naming-conventions.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md) — this document is the author-facing landing point, and of the two there is **only one place to maintain**: change the rule here first and point back; don't create a second copy.
5
5
 
6
6
  ---
7
7
 
@@ -31,8 +31,8 @@
31
31
  |------|------|
32
32
  | **契约 40 命名空间** | 池注入 39(唯一缺 `bridge`);壳注入 22;mock 注入 12 |
33
33
  | **池 = 插件运行时真相源** | 插件运行在池(pool)preload——池注入的命名空间为 **required**;`bridge` 真壳独有 |
34
- | **「仅壳」≠ 插件不可调** | `window.*`/`shell.*`/`hotExit.*`/`getFilePath` 池**实有注入**(N1 超集注记)——旧版把这几面标 ❌ 仅壳是错的 |
35
- | **契约必选面漂移已清零** | D1 `env.get(pluginId)` 转发、D2 `clipboard.readText` 壳补、D3 `dialog.openFile` 壳补——三项都已补齐实现,无 `?` 降级 |
34
+ | **「仅壳」≠ 插件不可调** | `window.*`/`shell.*`/`hotExit.*`/`getFilePath` 池**实有注入**——旧版把这几面标 ❌ 仅壳是错的 |
35
+ | **契约必选面漂移已清零** | `env.get(pluginId)` 转发、`clipboard.readText` 壳补、`dialog.openFile` 壳补——三项都已补齐实现,无 `?` 降级 |
36
36
 
37
37
  ---
38
38
 
@@ -81,10 +81,10 @@ async function list(): Promise<FileEntry[]> {
81
81
  | **decorations** | **同步契约**:`provideDecoration` 返回 `FileDecoration \| null \| undefined`,**不得返回 Promise**(异步提供方被跳过);同 pluginId 重复 `registerProvider` 幂等覆盖;注销/注册自动全量刷新通知 `onDidChange([])`;provider 抛异常自愈剔除该条目 |
82
82
  | **filesystem** | 插件权限:插件数据目录读写、workspace 目录读、**其他插件目录禁止** |
83
83
  | **configuration** | 配置 key 命名规则 `<pluginId>.<property>`(如 `editor.fontSize`、`serial-monitor.baudRate`) |
84
- | **serial** | **多口路由:** 打开/关闭/动作定向接口的 `portName` **可选**——缺省 = 唯一打开口(0 口抛「串口未打开」;≥2 口抛「多串口已打开,请指定 portName」;**失败可见,不静默**)。三推流通道(`onData`/`onStats`/`onSystem`)载荷**对象化**带 `portName` 路由键(`SerialDataPayload`/`SerialStatsPayload`/`SerialSystemPayload`)——订阅方按**会话口**过滤(key=portName 是通用路由键模式:谁消费谁过滤,壳不代收)。每标签页仍单口(D3),会话-端口绑定在插件侧 |
84
+ | **serial** | **多口路由:** 打开/关闭/动作定向接口的 `portName` **可选**——缺省 = 唯一打开口(0 口抛「串口未打开」;≥2 口抛「多串口已打开,请指定 portName」;**失败可见,不静默**)。三推流通道(`onData`/`onStats`/`onSystem`)载荷**对象化**带 `portName` 路由键(`SerialDataPayload`/`SerialStatsPayload`/`SerialSystemPayload`)——订阅方按**会话口**过滤(key=portName 是通用路由键模式:谁消费谁过滤,壳不代收)。每标签页仍单口,会话-端口绑定在插件侧 |
85
85
  | **panel** | `panel.reveal(viewId)` 声明寻址聚焦底部面板视图——面板隐藏 → 展开并切到该视图(Ctrl+J 同机制);已显示 → 切换聚焦;**viewId 不在 panel 容器 → no-op**(不报错)。**`panel.moveToEditor` 已移除**(弃内容迁移——位置移动是布局命令的事)。 `panel.revealFloating(viewId)` 壳内悬浮面板(类型 B)——按声明弹出某视图为悬浮面板。声明寻址 = ViewContainerService 全局视图索引(`contributes.views` 已注册**任意容器**视图,不限 panel——插件声明 `contributes.floatingPanel.viewId` 引用之)。**身份开关键**:无面板 → 开;同视图 → 关(toggle);他面板 → 替换;**viewId 未声明/声明插件未装 → no-op**(不崩)。面板默认动作 =「在主窗口中打开」(仅声明插件可开成标签页时出现)+ 最大化 toggle + 关闭 |
86
86
  | **hotExit** | 崩溃恢复专用——脏内容落盘 `%APPDATA%/linkdesk/hot-exit/`(主进程路径约定单源,插件零直写);保存/关闭标签页后调 `clear` 删备份 |
87
- | **shell** | 壳级 OS 动作:`showItemInFolder(p)` 资源管理器高亮单文件 / `openInTerminal(dirPath, terminalExe?, customCommand?)` 外部终端打开 / `startDrag(filePath, iconPath?)` 拖出到桌面。**`pluginLocation(pluginId)` / `openPluginFolder(pluginId, kind)` 插件磁盘位置两件套**——前者返回 `{ installDir, dataDir } | null`(**给身份不给路径拼装权**:路径由主进程解析,插件侧拿结果;盘上找不到 → `null`;`dataDir` 只在插件**真落过盘**时非 `null`,空/无 = 那行不该画);后者 `kind: "install" \| "data"` 用资源管理器开目录**内容**(同 `appearance.revealStorage` 手感,非 `showItemInFolder` 高亮单文件),`install` 目录不在盘上抛错,`data` 先建空目录再开。**(G4):`relaunch` 真重启应用**(退出并重新启动进程)——⚠️ **仅壳 preload 注入(契约 `?` 可选)**,池侧调用前必须判存在(`window.linkdesk.shell.relaunch?.`)。与 `window.location.reload` 的区别是**池在不在**:池是独立 `WebContentsView`,壳 reload 不重建它,更新视图类插件后 reload 只会看到旧 bundle;`relaunch` 调用后本进程随即终止,**不要依赖它的返回值**(Promise 永不落地) |
87
+ | **shell** | 壳级 OS 动作:`showItemInFolder(p)` 资源管理器高亮单文件 / `openInTerminal(dirPath, terminalExe?, customCommand?)` 外部终端打开 / `startDrag(filePath, iconPath?)` 拖出到桌面。**`pluginLocation(pluginId)` / `openPluginFolder(pluginId, kind)` 插件磁盘位置两件套**——前者返回 `{ installDir, dataDir } | null`(**给身份不给路径拼装权**:路径由主进程解析,插件侧拿结果;盘上找不到 → `null`;`dataDir` 只在插件**真落过盘**时非 `null`,空/无 = 那行不该画);后者 `kind: "install" \| "data"` 用资源管理器开目录**内容**(同 `appearance.revealStorage` 手感,非 `showItemInFolder` 高亮单文件),`install` 目录不在盘上抛错,`data` 先建空目录再开。**`relaunch` 真重启应用**(退出并重新启动进程)——⚠️ **仅壳 preload 注入(契约 `?` 可选)**,池侧调用前必须判存在(`window.linkdesk.shell.relaunch?.`)。与 `window.location.reload` 的区别是**池在不在**:池是独立 `WebContentsView`,壳 reload 不重建它,更新视图类插件后 reload 只会看到旧 bundle;`relaunch` 调用后本进程随即终止,**不要依赖它的返回值**(Promise 永不落地) |
88
88
  | **appearance** | `revealStorage` 打开外观存储目录(`userData/appearance`)——主进程解析路径并 `shell.openPath` 开资源管理器**内容**(非 `showItemInFolder` 高亮单文件);目录缺省也建(打开即见存储位置,空目录合法),`openPath` 失败抛错 fail-loud。返回 `Promise<void>` |
89
89
  | **app** | `app.getVersion` = 宿主软件版本号(`Promise<string>`,只读)——唯一运行时来源 = Electron `app.getVersion`(`package.json` 单点,02 §2.3);**主软件版本比对入口**(市场 minAppVersion 与更新检查都消费它)。壳内另有 `getProductInfo` 私有扩展(关于页 8 字段数据源,不在契约——池插件不可调) |
90
90
  | **tabs** | **跨窗资源事件联动:** `updateLabelBySourceId(sourceId, label)` / `closeBySourceId(sourceId)` = **全窗广播语义**——资源持有者在主窗与全部脱出窗的标签页同步更新/关闭;`sourceId` 为全局唯一资源身份(文件路径/会话 id),变更即全局事实(联动**不依赖调用方与标签页同窗**——脱出窗标签随侧栏改名/删除即时联动,对标 VS Code)。`focusBySourceId(sourceId)` = **按来源窗路由**(视图动作,聚焦到具体某窗,非全局事实)。**无新 API**——复用既有面,此行为契约由全窗广播保证 |
@@ -155,11 +155,11 @@ async function list(): Promise<FileEntry[]> {
155
155
  | 层 | 设备示例 | 通道 | 作者状态 |
156
156
  |:--|:--|:--|:--|
157
157
  | **串口系**(最大头) | USB-CAN 适配器(CH340/CP210x 虚拟串口)、GPS 模块(NMEA)、USB-TTL、便宜逻辑分析仪 | `linkdesk.serial.*`(Phase 6 通用化后) | ✅ **立即可写,零壳依赖**;多口/多插件并存成立 |
158
- | **自定义 USB** | 专业逻辑分析仪(Saleae 类,自定义 USB 端点) | 未来 `usb` 通道 | ⏳ E6 后版本化演进加一条通用通道(一次性,同 serial 同构);**加完前这类设备要等** |
158
+ | **自定义 USB** | 专业逻辑分析仪(Saleae 类,自定义 USB 端点) | 未来 `usb` 通道 | ⏳ 后续版本加一条通用通道(一次性,同 serial 同构);**加完前这类设备要等** |
159
159
  | **厂商私有 DLL** | 高端设备(只有厂商 SDK/DLL) | 原生通道 | ⚠️ 独立架构课题(渲染沙箱无 Node 权限);不在当前范围 |
160
160
 
161
161
  **平台责任边界(作者可放心依赖):**
162
- - **通道正确性 + API 稳定承诺**——平台作者负责通道(打开 → 流式读写 → 关闭/错误/多实例/资源回收);E6 上架后改 API = 版本化演进(`engines` 声明),加了不违约、不加不影响存量插件。
162
+ - **通道正确性 + API 稳定承诺**——平台作者负责通道(打开 → 流式读写 → 关闭/错误/多实例/资源回收);插件生态上线后改 API = 版本化演进(`engines` 声明),加了不违约、不加不影响存量插件。
163
163
  - **设备协议正确性作者自持**——CAN 帧/NMEA/采样解析全归插件,壳不认识任何设备。
164
164
  - **同一物理口仅单消费方**——OS 驱动排他(`serial-monitor` 打开的口,其他插件/标签页不能同时打开;多插件并存 = 各开各的口)。
165
165
 
@@ -41,7 +41,7 @@ markLoadStarted(PENDING → LOADING)
41
41
 
42
42
  ### 2.1 旧格式归一化 + 角色派生
43
43
 
44
- - **`normalizeManifest`(纯函数,不 mutate 只读 manifest):** E3 时代的顶层 `themes` / `languages` / `file` 字段 → 自动折成 `contributes.themes` / `contributes.languages`。新插件直接写 `contributes`,不用管这层。
44
+ - **`normalizeManifest`(纯函数,不 mutate 只读 manifest):** 旧的顶层 `themes` / `languages` / `file` 字段 → 自动折成 `contributes.themes` / `contributes.languages`。新插件直接写 `contributes`,不用管这层。
45
45
  - **角色派生:** `pluginRole` 显式声明;未声明时自动推导——`!manifest.entry && 有 contributes` → `"data"`(纯数据插件:主题/语言包,无 React 组件,跳过组件加载)。`pluginRole: "data"` 的插件不加载 JS 入口。
46
46
 
47
47
  ### 2.2 entryless 插件——没有入口也能有视图
@@ -261,9 +261,9 @@ unloadPlugin(pluginId, reason, displayName)
261
261
 
262
262
  ## 九、生命周期操作——安装 / 启用 / 禁用 / 卸载 / 重装
263
263
 
264
- ### 9.1 安装 `installPlugin(sourcePath)`(E6 zip 分发路由)
264
+ ### 9.1 安装 `installPlugin(sourcePath)`(zip 分发路由)
265
265
 
266
- `sourcePath` 三态自适应(`isPackageSource`):目录路径 / `http(s)://` URL / 磁盘 `.linkdesk-plugin` zip。**分发主路 = zip / URL 包源**(E6 zip 单文件);目录源仅 dev 便捷用。
266
+ `sourcePath` 三态自适应(`isPackageSource`):目录路径 / `http(s)://` URL / 磁盘 `.linkdesk-plugin` zip。**分发主路 = zip / URL 包源**(zip 单文件);目录源仅 dev 便捷用。
267
267
 
268
268
  ```
269
269
  validating → 包源:主进程 plugins:download / plugins:extract → 解压前校验
@@ -51,7 +51,7 @@ 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 只发货插件全部**——一只一个仓(D1),源码真相源只此一处 |
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
55
  | **壳仓夹具** | `<壳仓>/plugins/<id>/`(`env.appPluginsDir`) | 源码 + Vite 即时编译 | ✅(`npm run dev` 热更) | 只剩两只**开发夹具**:`panel-demo` / `floating-panel-demo`(不发货、不进 zip) |
56
56
  | **安装态** | `{userData}/plugins/<id>/` | zip 解出的预构建 bundle | ❌(改包需重 build + 重装/重物化) | 用户机器上所有已装插件 |
57
57
 
@@ -163,7 +163,7 @@ my-plugin/
163
163
  | `core: true` 插件不可卸(防误删旗标) | `builtin/` 内置扩展 |
164
164
  | 卸载 = 删目录 + 销账(真删);源码树 app 插件才移 `.disabled/` | 卸载 = 删文件(不可恢复) |
165
165
  | `env.get(id).pluginDataDir` | `ExtensionContext.storagePath` |
166
- | `core: true` 插件发货 = `bundled-plugins/*.linkdesk-plugin`(**首启种子**:boot 只补缺失、**永不刷新已装副本**;但**箱子本身会随壳版本刷新**——打包前由 `sync:bundled` 拉各插件「最新已发布版」,D3) | 随应用更新(安装包内置) |
166
+ | `core: true` 插件发货 = `bundled-plugins/*.linkdesk-plugin`(**首启种子**:boot 只补缺失、**永不刷新已装副本**;但**箱子本身会随壳版本刷新**——打包前由 `sync:bundled` 拉各插件「最新已发布版」) | 随应用更新(安装包内置) |
167
167
  | `requires` **运行期**依赖编排([02 §四](02-插件生命周期.md)) | `extensionDependencies` 安装期解析 |
168
168
 
169
169
  ---
@@ -1,7 +1,7 @@
1
1
  # 插件 UI 写法规约
2
2
 
3
3
  > **一句话:核心已提供标准组件和注册表——不要手写轮子。手写 = 风格不一致 + 以后归一化时要拆。**
4
- > 写插件前扫一眼,避免 B62 式返工。
4
+ > 写插件前扫一眼,避免同类返工。
5
5
  > **2026-09-06 与实现对齐核对**(对账):塌平单根(无 plugins/{builtin,user})· 共享控件走 @linkdesk/ui · 分发 = .linkdesk-plugin zip。本页对应机制引用已清。
6
6
 
7
7
  ---
@@ -36,7 +36,7 @@ window.linkdesk.menu.registerItems("editorContext", "myPlugin", [
36
36
  <ContextMenu menuId="editorContext" />
37
37
  ```
38
38
 
39
- **理由:** `<ContextMenu>` 自带 backdrop + 四种失焦(Escape / click backdrop / window blur / 选项 click)+ 键盘导航 + when 条件过滤。手写做不到这四种失焦——B62 教训。
39
+ **理由:** `<ContextMenu>` 自带 backdrop + 四种失焦(Escape / click backdrop / window blur / 选项 click)+ 键盘导航 + when 条件过滤。手写做不到这四种失焦。
40
40
 
41
41
  **MenuId 是开放 string(`src/core/registry/commands/MenuRegistry.ts` `export type MenuId = string`)——插件声明任意字符串即契约,无需壳加代码。** 壳内置注册点(MENU_SLOTS 常量表):
42
42
 
@@ -75,7 +75,7 @@ return createPortal(
75
75
  );
76
76
  ```
77
77
 
78
- **理由:** keep-alive 架构下非活跃标签页 `display: none`,子元素用 `position: fixed` 也看不见(B54 教训)。render 到 `document.body` 才能突破组件树限制。
78
+ **理由:** keep-alive 架构下非活跃标签页 `display: none`,子元素用 `position: fixed` 也看不见。render 到 `document.body` 才能突破组件树限制。
79
79
 
80
80
  ---
81
81
 
@@ -317,7 +317,7 @@ const file = await window.linkdesk.dialog.openFile({
317
317
  });
318
318
  ```
319
319
 
320
- **理由:** 三者都是池内宿主统一渲染(QuickPickHost / **铃铛宽通知面板** / DialogHost)——样式与壳一致、随主题与字号缩放走。手写浮层 = 风格不一致 + keep-alive 下 `position: fixed` 失效(B54)。完整签名见 `contracts/linkdesk.d.ts`。
320
+ **理由:** 三者都是池内宿主统一渲染(QuickPickHost / **铃铛宽通知面板** / DialogHost)——样式与壳一致、随主题与字号缩放走。手写浮层 = 风格不一致 + keep-alive 下 `position: fixed` 失效。完整签名见 `contracts/linkdesk.d.ts`。
321
321
 
322
322
  > ⚠️ **通知不是「自动消失的浮卡」**(通知面归一 +更正):右下角窄 toast 链路已整删,**唯一通知面 = 状态栏铃铛宽面板**。作者要知道的三件事:
323
323
  > 1. **通知不弹卡、不抢焦点、不挡操作**——它进铃铛(未读计数 +1),用户点开才看见。别把通知当「必须被看见」的通道:要用户当场决定 → 用 `dialog.confirm`(模态、抢焦点)。
@@ -544,8 +544,8 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
544
544
 
545
545
  | 来源 | 保留名 | 说明 |
546
546
  |---|---|---|
547
- | 宿主全局工具类 | `.input` | 输入框工具类——**直接用即可**(它本来就是给你的输入框用的) |
548
- | 共享组件类名 + 宿主容器类名 | **整个 `ldk-` 命名空间**——今天有 `ldk-badge`、`ldk-button`、`ldk-combobox`、`ldk-mdv`、`ldk-selectbox`、`ldk-sle`、`ldk-slider`、`ldk-toggle` 八个(共享组件),另含宿主自己的容器类(如 `ldk-titlebar`) | 分别是 `@linkdesk/ui` 里徽标 / 按钮 / 组合输入 / Markdown 容器 / 下拉 / 数组编辑器 / 滑杆 / 开关的类名。**你不用记这些名字**——记一条就够:**凡 `ldk-` 开头都是宿主自己的(共享组件 + 宿主界面容器),不要拿给自己的元素用** |
547
+ | 宿主**给你的**输入框工具类 | `.ldk-input` | 输入框工具类——**直接用即可**(它本来就是给你的输入框用的)。⚠️ 它是整个 `ldk-` 家族里**唯一**鼓励你**消费**的一个(其余的 `ldk-` 名是「别碰」,它是「拿去用」) |
548
+ | 共享组件类名 + 宿主容器类名 | **整个 `ldk-` 命名空间**——今天有 `ldk-badge`、`ldk-button`、`ldk-combobox`、`ldk-mdv`、`ldk-selectbox`、`ldk-sle`、`ldk-slider`、`ldk-toggle` 八个(共享组件),另含宿主自己的容器类(如 `ldk-titlebar`、`ldk-input`、`ldk-setting-group`) | 分别是 `@linkdesk/ui` 里徽标 / 按钮 / 组合输入 / Markdown 容器 / 下拉 / 数组编辑器 / 滑杆 / 开关的类名。**你不用记这些名字**——记一条就够:**凡 `ldk-` 开头都是宿主自己的(共享组件 + 宿主界面容器),不要拿给自己的元素用**(唯一的例外是上一行的 `.ldk-input`:那个是**给你用的**) |
549
549
 
550
550
  **`@keyframes` 的名字同理**——宿主自己也用着下面这些动画名,给你的动画起名时避开它们。重名的后果和类名一样(后加载的那份顶掉先加载的),而且同样是**静默**的:你的动画或宿主的动画有一个不播了,控制台没有任何报错。
551
551
 
@@ -620,6 +620,15 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
620
620
 
621
621
  > 现在就想看看自己的工程有没有裸名?在工程根跑 `npm run verify`。
622
622
 
623
+ ### 12.3 宿主的输入框工具类改名了:`.input` → `.ldk-input`(2026-09-16)
624
+
625
+ **一句话:如果你的插件写过 `className="input"`,改成 `className="ldk-input"` 就行——样式一模一样,只是名字换了。**
626
+
627
+ - **改了什么**:宿主原来把一个输入框工具类叫 **`.input`**(不带前缀,是唯一一个不带 `ldk-` 的宿主公共名)。它和本条纪律 1「跨方的名字都带命名空间」冲突 ⇒ 现在统一叫 **`.ldk-input`**。同时宿主的**设置分组卡片** `.setting-group` 也改名为 **`.ldk-setting-group`**。
628
+ - **谁受影响**:**在你自己插件的 JSX/TSX 里写过 `className="input"` 的插件**——官方插件里 `settings` 与 `serial-monitor` 两家用过,已在同一批发版改好。**改法就一处**:`className="input"` → `className="ldk-input"`;拼接写法同理(`"input my-input"` → `"ldk-input my-input"`)。**样式零变化**——同一条规则、同一批 CSS 变量,只换了名字。
629
+ - **不改会怎样**:输入框**不报错**,只是**失去宿主给的外观**(底色 / 边框 / 圆角 / 内边距),看起来像浏览器原生输入框。
630
+ - **什么时候必须改**:在**新壳**上跑就要改。新壳的版本号是 **`0.2.0`**,官方两只插件都已在 `plugin.json` 里声明 `minAppVersion: "0.2.0"`——你也给自己的插件声明同一个值,旧壳上的用户就会收到一句清楚的「需要应用版本 ≥0.2.0」提示,而不是看到一个没样式的输入框(`minAppVersion` 的语义见 [04-插件分发格式 §minAppVersion](04-插件分发格式.md))。
631
+
623
632
  ---
624
633
 
625
634
  ## 速查
@@ -111,9 +111,9 @@ my-plugin/
111
111
  | `contributes.configuration` | — | 注册到 ConfigurationRegistry → Settings Editor 自动渲染 |
112
112
  | `contributes.menus` | — | 注册到 MenuService → 右键菜单动态生成 |
113
113
  | `contributes.keybindings` | — | 注册到 KeybindingRegistry → 全局键盘监听 |
114
- | `contributes.themes` | theme (P6) | 注册到 ThemeRegistry → 主题浏览器 |
115
- | `contributes.languages` | language (P6) | 注册到 LanguageRegistry |
116
- | `contributes.fileAssociations` | — (P6) | 注册到 FileAssociationService → 双击文件自动打开 |
114
+ | `contributes.themes` | theme | 注册到 ThemeRegistry → 主题浏览器 |
115
+ | `contributes.languages` | language | 注册到 LanguageRegistry |
116
+ | `contributes.fileAssociations` | — | 注册到 FileAssociationService → 双击文件自动打开 |
117
117
  | `contributes.floatingPanel` | — | 声明视图可在壳内悬浮面板显示——viewId 引用已注册视图;未声明则无「在悬浮面板中打开」右键 |
118
118
 
119
119
  **插件可同时声明多种贡献。** 比如一个视图插件可以有 `entry` + `sidebar` + `statusBar` + `contributes.configuration` + `contributes.commands`——全部独立注册,互不影响。
@@ -255,7 +255,7 @@ my-plugin/
255
255
 
256
256
  说明与更新日志**以文件为准**——插件根目录的 `README.md` / `CHANGELOG.md`(位置、格式、与详情页的对应关系见 [09-插件目录规范](09-插件目录规范.md))。
257
257
 
258
- 这两个字段在 E6 开发期曾存在,但**从无读取方**(读取方按**固定文件名**读包内文件,不看任何声明字段),**2026-09-11 已删除**。
258
+ 这两个字段曾存在,但**从无读取方**(读取方按**固定文件名**读包内文件,不看任何声明字段),**2026-09-11 已删除**。
259
259
 
260
260
  > **写进 `plugin.json` 不会生效,只会被忽略**(顶层是宽松校验,写了不报错——所以它骗人)。**若你从旧教程 / 旧提交抄到了这两个字段 → 删掉,改写成文件。**
261
261
 
@@ -266,7 +266,7 @@ my-plugin/
266
266
  **对标 VS Code `extensionDependencies`**:同族机制,本字段是其归一化收口(见下「命名边界」)。
267
267
 
268
268
  **语义:**
269
- - 值 = 依赖插件的 `pluginId` 数组(无版本约束——激活顺序不承载版本语义,版本匹配属 E6 市场范畴)
269
+ - 值 = 依赖插件的 `pluginId` 数组(无版本约束——激活顺序不承载版本语义,版本匹配属插件市场范畴)
270
270
  - loader 按拓扑序加载:`requires` 里的插件先激活,本插件再激活——扫描顺序不再影响激活顺序
271
271
  - 依赖缺失 → 本插件挂起(PENDING),依赖装好/启用后自动加载
272
272
  - 依赖被卸载/禁用 → 本插件连带卸载(消费者优先,逆拓扑序)
@@ -107,7 +107,7 @@ SDK `publish` 要从它**切段**填目录条目,所以**段标题格式有约
107
107
  2. **壳仓 `bundled-plugins/<id>.linkdesk-plugin` 的语义 = 出厂发货用的种子快照**,其版本由 `bundled-plugins.lock.json` 记账(第 7.4 轮产出)。它**不是源码的第二份拷贝**——源码改了必须回插件仓改,改完走发布链路刷新种子。
108
108
  3. **从源码到用户桌面的链路**:插件仓 → `npm run build` → `<id>.linkdesk-plugin`(zip)→ GitHub Release asset → catalog 条目 → 用户安装。**没有一步经过壳仓。**
109
109
  4. **插件身份(id)永不可变**;显示名(`name`)可改;仓库名可改——三分规则与全部命名判据 → [16-命名规范](16-命名规范.md)。
110
- 5. **插件内有且只有一处版本号真源 = `plugin.json.version`**。`package.json.version` 不是真源,但必须与它相等(版本号「四处同源」,N6——见 [16-命名规范 §5.1](16-命名规范.md))。
110
+ 5. **插件内有且只有一处版本号真源 = `plugin.json.version`**。`package.json.version` 不是真源,但必须与它相等(版本号「四处同源」——见 [16-命名规范 §5.1](16-命名规范.md))。
111
111
 
112
112
  **与 `publish` 实现的对账**(规范不许与工具相反):发布目标仓库 = 工程 git remote `origin`(`packages/plugin-sdk/src/publish.ts` 的 `getCurrentRepoRemote`,非 git / 无 origin 直接报错);catalog 写到**仓库根 `marketplace.json`**(Contents API 读改写);`readmeUrl` / `versions[].changelog` 由 publish 从工程根 `README.md` / `CHANGELOG.md` 自动填写。
113
113
 
@@ -35,16 +35,16 @@ E:\linkdesk-plugins\
35
35
 
36
36
  ---
37
37
 
38
- ## 三、仓库名完全自由(D5/N2)
38
+ ## 三、仓库名完全自由
39
39
 
40
40
  **仓库名不强制任何前缀,第三方零约束。** 这是拍过板的:作者给自己的插件(仓库)取名是正当权利,不能定死。
41
41
 
42
- - **建议但非强制的惯例**:官方插件仓统一 `linkdesk-plugin-<id>`(N3 待用户拍板,拍板后条文住 [插件源码外移层/09-命名规范.md §五](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md)——只此一处维护);第三方随意。
42
+ - **建议但非强制的惯例**:官方插件仓统一 `linkdesk-plugin-<id>`(条文住 [插件源码外移层/09-命名规范.md §五](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md)——只此一处维护);第三方随意。
43
43
  - **改仓库名的代价**:已发布 catalog 条目里的 `downloadUrl` / `readmeUrl` 内嵌 `owner/repo`,**改名会断已发布插件的下载与 README 链接**(源码本身不受影响)。改名后重发一版新条目即可自愈,但旧版本条目仍指旧链——**能不改就不改,要改趁早**。
44
44
 
45
45
  ---
46
46
 
47
- ## 四、身份 vs 显示名 vs 仓库名(D5)
47
+ ## 四、身份 vs 显示名 vs 仓库名
48
48
 
49
49
  三个「名字」互不相干,混为一谈是一切命名问题的根源:
50
50
 
@@ -1,7 +1,7 @@
1
1
  # 命名规范——七种名字,一条身份
2
2
 
3
3
  > 2026-09-14 ·。**读者 = 插件作者。** 读完能回答四问:**id 怎么起?能不能改?显示名怎么改?仓库叫什么?**
4
- > 决策论证(N1-N6)与 VS Code 实测依据住 [插件源码外移层/09-命名规范.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md)——本篇是作者面落点,两处**只维护一处**:改规则先改本篇并回指,别造第二份。
4
+ > 决策论证与 VS Code 实测依据住 [插件源码外移层/09-命名规范.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md)——本篇是作者面落点,两处**只维护一处**:改规则先改本篇并回指,别造第二份。
5
5
 
6
6
  ---
7
7
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.5",
3
+ "version": "0.1.7",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——`docs/03-插件制造` 的发布产物:从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [