@linkdesk/plugin-docs 0.1.3 → 0.1.5

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.
@@ -32,7 +32,7 @@ A few key points (a summary of Matrix §2; the matrix wins on details):
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
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 — #20 implemented all of them, with no `?` degradation |
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 |
36
36
 
37
37
  ---
38
38
 
@@ -44,7 +44,7 @@ A few key points (a summary of Matrix §2; the matrix wins on details):
44
44
 
45
45
  - **Generation sources:** `src/core/api/linkdesk-api.ts` + `linkdesk-api/` (14 domain interfaces) + `src/core/types/ipc/*` + `src/core/types/pool/*` (wire payload types)
46
46
  - **Generator:** `scripts/generate-contract.mjs` (Route C — the contract type file is the source; pure types bundled into a single file)
47
- - **Mechanical gate:** the preload on both sides `satisfies` the contract surface types → tsc drift gate; `contracts:check` byte-compares hashes inside `npm run check` (#21)
47
+ - **Mechanical gate:** the preload on both sides `satisfies` the contract surface types → tsc drift gate; `contracts:check` byte-compares hashes inside `npm run check`
48
48
  - **Coverage matrix:** every namespace × pool/shell/mock coverage → [Namespace Matrix §2](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/契约生成/命名空间矩阵.md#2-命名空间--四面覆盖矩阵)
49
49
 
50
50
  ### 3.1 How Plugins Consume It
@@ -61,9 +61,9 @@ async function list(): Promise<FileEntry[]> {
61
61
  }
62
62
  ```
63
63
 
64
- **Path B — standalone npm package (third-party plugins, #22.6):** after `npm i -D @linkdesk/contracts`, use the same `import type { ... } from "@linkdesk/contracts"`.
64
+ **Path B — standalone npm package (third-party plugins):** after `npm i -D @linkdesk/contracts`, use the same `import type { ... } from "@linkdesk/contracts"`.
65
65
 
66
- > **Package shape (built):** `contracts/` is the npm package root (`@linkdesk/contracts`, its `types` entry points straight at `linkdesk.d.ts`, zero build, and the `files` allowlist contains only the d.ts). **Independent version axis (decoupled 2026-09-06, reversing the 22.6 version linkage):** the package version **no longer follows the shell** — a software upgrade (the user axis) ≠ a contract upgrade (the author axis); the version only bumps and publishes when the `window.linkdesk.*` API surface changes. **Content detection is not withdrawn**: d.ts/runtime-shapes are compared byte-for-byte against the shell source, and any drift turns `contracts:check` red (change the API and forget to regenerate = your commit is stuck); **shelf cadence = the check-npm-release yellow light gate** (author-facing content changed + version untouched → a reminder to bump+publish). **Consumption-shape acceptance:** `contracts-example/` at the repo root — a standalone tsconfig + local `file:../contracts` reference, `npx tsc --noEmit` reporting zero errors, and zero `@src/core` throughout (`npm pack` produces a tarball → the real npm package path passes too). **Release state:** ✅ genuinely published `@linkdesk/contracts@0.1.0` (2026-09-04) + `@linkdesk/contracts@0.1.1` (2026-09-06, the first independent-axis version after decoupling) + `@linkdesk/contracts@0.1.2` (same day, 2026-09-06; 0.1.1 shipped with the stale "version linkage" README → README fixed and republished, d.ts unchanged) — third parties can `npm i -D @linkdesk/contracts` to install the real package straight from the registry; real-package tsc acceptance has passed. plugin-sdk and `@linkdesk/ui` were genuinely published in the same period.
66
+ > **Package shape (built):** `contracts/` is the npm package root (`@linkdesk/contracts`, its `types` entry points straight at `linkdesk.d.ts`, zero build, and the `files` allowlist contains only the d.ts). **Independent version axis (decoupled 2026-09-06; the version no longer follows the shell):** the package version **no longer follows the shell** — a software upgrade (the user axis) ≠ a contract upgrade (the author axis); the version only bumps and publishes when the `window.linkdesk.*` API surface changes. **Content detection is not withdrawn**: d.ts/runtime-shapes are compared byte-for-byte against the shell source, and any drift turns `contracts:check` red (change the API and forget to regenerate = your commit is stuck); **shelf cadence = the check-npm-release yellow light gate** (author-facing content changed + version untouched → a reminder to bump+publish). **Consumption-shape acceptance:** `contracts-example/` at the repo root — a standalone tsconfig + local `file:../contracts` reference, `npx tsc --noEmit` reporting zero errors, and zero `@src/core` throughout (`npm pack` produces a tarball → the real npm package path passes too). **Release state:** ✅ genuinely published `@linkdesk/contracts@0.1.0` (2026-09-04) + `@linkdesk/contracts@0.1.1` (2026-09-06, the first independent-axis version after decoupling) + `@linkdesk/contracts@0.1.2` (same day, 2026-09-06; 0.1.1 shipped with the stale "version linkage" README → README fixed and republished, d.ts unchanged) — third parties can `npm i -D @linkdesk/contracts` to install the real package straight from the registry; real-package tsc acceptance has passed. plugin-sdk and `@linkdesk/ui` were genuinely published in the same period.
67
67
 
68
68
  **Path C — copy the file:** copy `contracts/linkdesk.d.ts` into your plugin project and reference it from tsconfig. The contract file is self-contained (94 declarations, zero import dependencies), so copying just works.
69
69
 
@@ -82,11 +82,11 @@ async function list(): Promise<FileEntry[]> {
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
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 |
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 (I8-2)**: 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 |
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
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) |
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
- | **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, #57.5). The shell also has a private `getProductInfo` extension (the data source for the about page's 8 fields, #57.14 — not in the contract, so pool plugins can't call it) |
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 |
91
91
  | **notifications** | **The only notification surface is the wide status bar bell panel** (the narrow bottom-right toast path was deleted wholesale) — no cards popping up, no focus stealing, no blocking; the unread count increments and the user only sees it after clicking. **Don't treat it as a "must be seen" channel**: when the user has to decide right now → `dialog.confirm`. **`show` always returns a handle** (`{ update, finish, cancel }` — **and not only when `progress:true`**); **a notification can only be updated/removed by the handle that created it**, and a `show` with the same text elsewhere = a different notification. `progress:true` turns on a real progress bar: `update(msg, percent?)` gives a determinate 0-100 bar, while omitting percent = an indeterminate animation; `finish(msg?)` closes it and optionally adds a completion notification; `cancel` just closes it with nothing added. `persistent:true` = stays put and doesn't auto-dismiss (for error diagnostics), waiting for the user to click ×. **The persistent quota is bucketed by `source`, 5 each**; overflow evicts the oldest from that same source and shows a summary hint (persistent ≠ archived — write your own file if you want a record). `source` = **the machine-read attribution key, containing no human copy** (the shell resolves the human-readable name) — ⚠️ **it cannot be injected automatically**: the pool is a single-process shared realm and all plugins share one `window.linkdesk`, so the preload has no way to know which plugin's tree issued this `show` ⇒ **only the author can explicitly report their own plugin id** (the shell's own domains use `app.<domain>`); **omit it → everything lands in the "Other" group**. `actions` clicks go through the shell's `executeCommand(command, args)`, with the handler self-registered by the plugin |
92
92
  | **dialog** | `confirm`/`alert`/`open`/`openFile` = shell-rendered modal dialogs (they take focus, with a focus lock). **`confirmContent(options)`** = **rich-content confirmation** — the dialog is still the shell (centered/scrim/Esc/focus lock/click-scrim-to-cancel) while **the content = a plugin-drawn view** (`pluginId` + `viewId` declarative addressing + an opaque `payload`, matching VS Code's "the dialog is the shell, the content is the plugin's"). **How the content side reads it**: once the view mounts, get data through `dialogHost.current?.content?.payload` (`open !== true` → `null`, defensive so you don't get a blank screen); **there are only two settlement paths, `dialogHost.confirm` / `dialogHost.cancel`** (don't close the dialog yourself — the shell won't recognize it). **The fallback is hard**: if `viewId` can't be resolved (undeclared / declaring plugin not installed) → the shell **falls back to a plain text confirmation** (using `title`/`message`); the dialog still appears and never dies silently ⇒ so don't omit `title`/`message`. `payload` crosses IPC by structured clone ⇒ only cloneable data can go in it |
@@ -105,7 +105,7 @@ async function list(): Promise<FileEntry[]> {
105
105
 
106
106
  The old §3.x per-namespace method list has been deleted (= a hand-written second source of truth, guaranteed to drift). The generated contract resolved several places where **the old docs disagreed with the implementation**:
107
107
 
108
- | Point | Old hand-written version | Contract/implementation reality (after #20) |
108
+ | Point | Old hand-written version | Contract/implementation reality |
109
109
  |------|------|------|
110
110
  | `serial.listPorts()` | Written as `getPorts()` | The contract says `listPorts()` — the implementation always used that name; the old doc had a typo |
111
111
  | `serial.onData/onStats/onSystem` | `cb: (d: any)` / string | **Object payloads**: `onData(p: SerialDataPayload)` / `onStats(p: SerialStatsPayload)` / `onSystem(p: SerialSystemPayload)` — all three channels carry a `portName` routing key (`SerialStats` was deleted; no dead type tail) |
@@ -133,7 +133,7 @@ The old §3.x per-namespace method list has been deleted (= a hand-written secon
133
133
  | `import { getWorkspaceFolders } from "@src/core/WorkspaceService"` | `lk.workspace.getFolders()` |
134
134
  | `import type { FileEntry } from "@src/core/types/fileEntry"` | `import type { FileEntry } from "@linkdesk/contracts"` |
135
135
 
136
- **ESLint `error` (`noCoreImportInPlugin`, tightened by #20-d):** `import { ... } from "@src/core/..."` **and** `import type { ... } from "@src/core/..."` → 🚫 compile failure. Test files are no longer exempt (the vitest single-process rationale no longer holds).
136
+ **ESLint `error` (`noCoreImportInPlugin`, tightened to include `import type`):** `import { ... } from "@src/core/..."` **and** `import type { ... } from "@src/core/..."` → 🚫 compile failure. Test files are no longer exempt (the vitest single-process rationale no longer holds).
137
137
 
138
138
  **Allowed imports (shared controls come from the `@linkdesk/ui` npm package; the full `@src/core` exception allowlist lives in `eslint-local-rules.js` PLUGIN_IMPORT_WHITELIST):**
139
139
  - `@linkdesk/contracts` **types** (`import type`, zero runtime coupling) — the real registry package (see §3.1)
@@ -148,7 +148,7 @@ unload plugin A
148
148
 
149
149
  > 🔴 **Retired 2026-09-09: the `activationEvents` field has been removed entirely** (the shell-side deferred activation track is fully retired — activation.ts / loader defer / `activatePlugin` / the CommandRegistry pre-activation hook are all deleted, and the field is gone from the three copies of the schema). **The shell always registers the full metadata set at startup** (`loadPlugin(pluginId, "startup")`, zero JS imports); plugin **JS is lazily loaded by the pool per URL**. There is no field to write and nothing to declare — only the two on-demand tracks below remain.
150
150
 
151
- **Metadata is registered at startup:** `initPluginLoader` discovers every plugin → the shell registers manifest/contributes (command display names/menus/config schemas/icon bar metadata are all visible) — **without importing any plugin JS** (hard constraint #17d: zero plugin source in the shell bundle).
151
+ **Metadata is registered at startup:** `initPluginLoader` discovers every plugin → the shell registers manifest/contributes (command display names/menus/config schemas/icon bar metadata are all visible) — **without importing any plugin JS** (zero plugin source in the shell bundle).
152
152
 
153
153
  **JS loading = the pool's two on-demand tracks (the plugin author's contract):**
154
154
 
@@ -333,7 +333,7 @@ For source-tree app plugins: copy from `plugins/.disabled/<id>/` back to `plugin
333
333
  | Dimension | VS Code | LinkDesk |
334
334
  |------|---------|----------|
335
335
  | Activation timing | many `activationEvents` (onLanguage/onCommand/workspaceContains…) | **no event field** (retired) — the full metadata set is registered at startup; JS is loaded by the pool on demand |
336
- | Lazy loading | extension JS imported on demand | zero JS imports at shell startup (#17d); the pool is the only JS executor — a surface mount lazily loads the URL / a command miss imports the entry (on-command activation, §5) |
336
+ | Lazy loading | extension JS imported on demand | zero JS imports at shell startup; the pool is the only JS executor — a surface mount lazily loads the URL / a command miss imports the entry (on-command activation, §5) |
337
337
  | Load scanning | scan `extensions/` at startup | single-source discovery, `plugins:listAll`, scanning directly in the main process (same surface in dev/prod) + 2s polling for hot-plug |
338
338
  | Dependencies | `extensionDependencies` | `requires` (string array) + suspend to PENDING / cycle fails / cascade unload |
339
339
  | Uninstall | Disable / Uninstall | installed state = really delete the directory + settle the account (a removed marker, boot does not revive it); repo source-tree app plugins = move to `.disabled/` as a **same-session** undo (orphans surviving a restart are cleaned automatically at boot) |
@@ -42,7 +42,7 @@ my-plugin/
42
42
  | **User install** | `pluginManager.install(url \| zip on disk \| directory)` | same as above | Download/extract/verify → write to disk; a directory source is a dev convenience only—the main distribution path is the zip |
43
43
 
44
44
  **Install-time verification (intercepted before extraction, so no half-installed directory is produced):**
45
- - Locate `plugin.json` at the zip top level (basename match, tolerating one wrapper directory)—JSONC parse (#55)
45
+ - Locate `plugin.json` at the zip top level (basename match, tolerating one wrapper directory)—JSONC parse
46
46
  - `pluginId` resolution: manifest first, zip file basename as the fallback, cross-checked between the two sources; must pass the safe character set (no path separators/relative segments)
47
47
  - zip-slip protection—entry paths that escape the extraction target are rejected
48
48
  - Same version already installed → skip (user install deletes the source); different version → leave it alone (upgrading is the update flow's job; boot never overwrites)
@@ -93,7 +93,7 @@ Wording discipline (hard constraint 11): don't frame it as two categories "built
93
93
 
94
94
  `version` follows semver (`major.minor.patch`). **boot never refreshes an installed plugin** (the bundled folder is a first-launch offline seed, not an update channel)—there is only one way for an installed user to get new content = **the update flow**: `pluginManager.checkUpdates` (fetch catalog + semver comparison) → `update` (stage to tmp → atomic replace → roll back to the old version on failure). Real marketplace entries discover updates by version.
95
95
 
96
- ### 🔥 Any content change must bump the plugin's own version (decided 2026-09-06, #15n)
96
+ ### 🔥 Any content change must bump the plugin's own version (decided 2026-09-06)
97
97
 
98
98
  **For a plugin that has been distributed, any content change (code / resources / README / CHANGELOG) must bump `plugin.json.version`.** An installed user's copy is **frozen per version**—boot only fills in what's missing and never refreshes what's installed; the only way for a user to get new content = **the version number**. Changing content without bumping = installed users stay stuck on the old content forever (confirmed empirically on 2026-09-06: a bundled shipping zip gained pyright without a bump → the installed copy's LSP broke entirely).
99
99
 
@@ -455,7 +455,7 @@ function MyConfirmContent() {
455
455
  | **Font size** | `--font-size-2xs … 4xl` + `--ui-scale` (the scaling axis for `app.uiFontScale`; the scale table is in §10) | `font-size: var(--font-size-md)` / em/rem | `check-font-scale` (the check leg—a bare px font size is red) |
456
456
  | **Font family** | `--font-ui` / `--font-mono` | `font-family: var(--font-ui)` | contract guidance (authors may legitimately choose their own font) |
457
457
 
458
- `var(--*)` = theme/glass/global scaling follow automatically, with zero plugin awareness—**this is exactly why the @linkdesk/ui control layer can be "follow without thinking"** (54b/54c: controls are all tokens, and a plugin that does `npm i @linkdesk/ui` and consumes them follows along). Control reuse always imports from `@linkdesk/ui` (see §Quick Reference)—don't hand-roll wheels.
458
+ `var(--*)` = theme/glass/global scaling follow automatically, with zero plugin awareness—**this is exactly why the @linkdesk/ui control layer can be "follow without thinking"**—the controls are written entirely on tokens, so a plugin that does `npm i @linkdesk/ui` and consumes them follows along. Control reuse always imports from `@linkdesk/ui` (see §Quick Reference)—don't hand-roll wheels.
459
459
 
460
460
  ### 11.2 Honest boundaries / knowing bypasses—content and brand colors can have their own sky
461
461
 
@@ -522,7 +522,7 @@ When authors build their own settings UI or manage their own saves (without goin
522
522
  | **Don't hardcode other plugins' IDs** (differential behavior goes through plugin.json declaration fields, consumed via the Registry pattern) | `03-contributes-spec.md` |
523
523
  | Configuration keys **must have a default** | `06-plugin-json-spec.md` |
524
524
  | **Use only documented API namespaces** (don't casually hang undocumented `linkdesk.xxx` off the API) | `01-plugin-api-contract.md` |
525
- | Controls always come from `@linkdesk/ui` (since 54c built-in controls are imported from the npm package; `@src/components/shared/*` is forbidden) | §Quick Reference of this file |
525
+ | Controls always come from `@linkdesk/ui` (built-in controls are imported from the npm package; `@src/components/shared/*` is forbidden) | §Quick Reference of this file |
526
526
 
527
527
  ---
528
528
 
@@ -533,19 +533,51 @@ host's styles, the shared components' (`@linkdesk/ui`) styles, and **every loade
533
533
  **class names are global identifiers**. Writing a class name claims that name; if someone else uses it too,
534
534
  both stylesheets land on the same element.
535
535
 
536
- **Two rules:**
537
-
538
- 1. **Give your own elements prefixed class names**—that's what the official plugins do (`settings-*`, `ms-*`,
539
- `mpd-*`). Use your plugin name or an abbreviation as the prefix, not something obviously generic like
540
- `.active-panel`.
541
- 2. **These names are reserved by the host—don't use them for your own elements** (if you do, the host's
536
+ **Three rules:**
537
+
538
+ 1. **Class names you give your own elements must start with your `pluginId` plus a hyphen**—
539
+ `settings-*`, `editor-*`, `file-tree-*` … (`pluginId` is the id you declare in `plugin.json`; every
540
+ official plugin does this). **Don't use abbreviations**: the `ms-` / `mpd-` shorthand style is **retired**—
541
+ an abbreviation guarantees nothing, and two plugins that each abbreviate to `ms-` collide. `pluginId` is
542
+ unique by construction (immutable once published), so deriving the prefix from it is free collision
543
+ protection.
544
+ 2. **`@keyframes` names take the prefix too** (`file-tree-fadeIn`), and **rename the `animation:` reference in
545
+ the same edit**—a keyframe name is a global identifier exactly like a class name: on a collision the later
546
+ definition wins and the earlier animation silently stops.
547
+ 3. **These names are reserved by the host—don't use them for your own elements** (if you do, the host's
542
548
  styles will hit you):
543
549
 
544
550
  | Source | Reserved names | Notes |
545
551
  |---|---|---|
546
552
  | Host global utility classes | `.input` | Input-box utility—**just use it** (it exists for your inputs) |
547
- | Host global utility classes | `.titlebar`, `.divider`, `.about`, `.rn`, `.vta` | The host UI's own container names; don't reuse them |
548
- | Shared component public classes | `.badge`, `.button`, `.combobox`, `.mdv`, `.selectbox`, `.sle`, `.slider`, `.toggle` | Class names of the badge / button / combobox / Markdown container / select / string-list editor / slider / toggle components in `@linkdesk/ui` |
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** |
554
+
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
+
557
+ | Reserved keyframe names | Notes |
558
+ |---|---|
559
+ | `selectbox-in` | the shared select dropdown's entrance animation |
560
+ | `drop-zone-in` | the drop zone's entrance animation |
561
+ | `dropdown-card-in` | the dropdown card's entrance animation |
562
+ | `floating-panel-in` | the floating panel's entrance animation |
563
+ | `group-tab-enter` | the group tab's entrance animation |
564
+ | `group-tab-exit` | the group tab's exit animation |
565
+ | `notif-icon-spin` | the notification icon's spin |
566
+ | `notif-progress-scan` | the notification progress scan |
567
+
568
+ > 🔧 **Maintainer note (authors can skip this)**—the **Reserved names** and **Reserved keyframe names** columns in the two tables above are **machine-read**: the gate
569
+ > in `npm run check` (`scripts/check-reserved-names-doc-sync.mjs`) cross-checks them **both ways** against the
570
+ > registry `packages/plugin-sdk/schemas/reserved-class-names.json`—every registry name must appear here, and
571
+ > every name here must either be registered (bare names) or a real `ldk-` name present in the host source.
572
+ > The keyframe table is cross-checked **both ways** against the registry's `keyframes` array in the same way.
573
+ > ⇒ **Editing these two columns is a public-surface change**: add/remove a name in **three places in one commit**—
574
+ > the registry plus these two tables in both language trees. Both columns hold **names only**; put prose in
575
+ > the "Notes" column.
576
+
577
+ **One more namespace rule**: your `pluginId` **must not start with `ldk-`**—the whole `ldk-` namespace belongs
578
+ to the host, so a plugin called `ldk-tools` would derive its prefix (`ldk-tools-*`) **straight into host
579
+ territory**, which also makes rule 1 meaningless. This constraint lives in the `plugin.json` schema, so your
580
+ editor flags it immediately.
549
581
 
550
582
  **Want their look? Use their component**—`import { Button } from "@linkdesk/ui"`, don't hand-write its class
551
583
  name (hand-writing bypasses the component, and you fall behind the moment it changes).
@@ -557,6 +589,53 @@ name (hand-writing bypasses the component, and you fall behind the moment it cha
557
589
  painted the background and the text the same color, so the text was swallowed by its own background — the UI
558
590
  just looked like "a solid block". **No error**, just wrong, and hard to trace.
559
591
 
592
+ ### 12.1 Upgrading from an older `@linkdesk/ui`—the one thing you have to change yourself
593
+
594
+ Shared component class names now carry an `ldk-` prefix (as of `@linkdesk/ui` **0.2.0**). This affects exactly
595
+ one kind of code: rules in **your own plugin's CSS** that use a descendant selector to fine-tune a shared
596
+ component. **Nothing to do before you upgrade; when you upgrade, it's one prefix.**
597
+
598
+ - **When it hits you**: after `@linkdesk/ui` moves to **0.2.0**—**not before**. In older versions these
599
+ components' class names were bare (`.badge`), and the CSS shipped inside the package is consistent with the
600
+ components, so **if you don't upgrade, nothing breaks**. (A `^0.1.x` range will not cross over to `0.2.0` by
601
+ itself, so this only comes up on the upgrade you perform deliberately.)
602
+ - **What is affected**: descendant selectors in **your own plugin CSS** such as
603
+ `.control-bar .combobox { … }`, `.settings-slider-control .slider { … }`, `.changelog .mdv { … }`.
604
+ **The components' own styles are unaffected, and your own class names don't change.**
605
+ - **How to fix it**: add the `ldk-` prefix to **the part of the selector that points at the shared component**—
606
+ `.combobox` → `.ldk-combobox`, `.slider` → `.ldk-slider`, `.mdv` → `.ldk-mdv`, `.badge` → `.ldk-badge`,
607
+ `.selectbox-trigger` → `.ldk-selectbox-trigger`, `.combobox-field` → `.ldk-combobox-field`. **Family names
608
+ (suffixes like `-trigger` / `-field` / `-input`) take the prefix too.** Your own prefixes (`.control-bar`,
609
+ `.settings-*`) stay as they are. **After upgrading, grep your CSS for the eight old base names
610
+ `.badge`, `.button`, `.combobox`, `.mdv`, `.selectbox`, `.sle`, `.slider`, `.toggle`**: add the prefix where
611
+ the rule tunes a shared component, leave the rest alone.
612
+ - **Why it isn't automatically compatible**: this kind of mismatch **raises no error**—a selector that no
613
+ longer matches simply stops applying, so the UI looks "roughly right, just a bit off". Because it is silent,
614
+ we moved the names under the `ldk-` prefix and wrote this section.
615
+
616
+ ### 12.2 The prefix rules (§12 rules 1 and 2) are live—what about existing code?
617
+
618
+ **In one line: it keeps working unchanged, but the next time you touch that file is when you fix it.**
619
+
620
+ - **The official plugins have already been cleaned up under the new rules**—four plugins were renamed:
621
+ `file-tree` (v1.0.9), `settings` (v1.0.11), `serial-monitor` (v1.0.12) and `marketplace` (v1.0.33); their
622
+ bare class names and keyframe names now carry the `<pluginId>-` prefix. The remaining official plugin repos
623
+ had no bare definitions to begin with (their class names either already carry a prefix or they define none).
624
+ Measured against the official catalog, the audit reads **18/18 compliant**.
625
+ - **Third-party authors have no repository to change**: this rule governs only **the class and keyframe names
626
+ you write yourself**—it doesn't touch repo layout, your `pluginId`, or anyone else's code. You do **not**
627
+ need to cut a release for it.
628
+ - **Old unprefixed class names raise no error and don't stop working**—they work fine today. The cost is that
629
+ **the collision risk is still there**: if another plugin defines the same class name, both stylesheets land
630
+ on the same element (no error, just wrong-looking, and hard to trace).
631
+ - **Compliance is judged by the check that ships with your project**: a scaffolded project carries a strict
632
+ check leg (`npm run verify`) that scans your CSS for class names **bare-defined on your own elements** and
633
+ for `@keyframes` names, and fails them when they don't start with `<pluginId>-`. So the real action is
634
+ **rename them the next time you open that file**: `.panel {}` → `.myplugin-panel {}`, changing the CSS and
635
+ the JSX that uses it together (identifiers only—don't touch style values).
636
+
637
+ > Want to see whether your project has bare names right now? Run `npm run verify` in the project root.
638
+
560
639
  ---
561
640
 
562
641
  ## Quick Reference
@@ -573,7 +652,7 @@ just looked like "a solid block". **No error**, just wrong, and hard to trace.
573
652
  | Shortcuts (non-text keys) | `plugin.json contributes.keybindings` | — (putting text keys here = swallowing the whole pool, see §4.1) |
574
653
  | Shortcuts (text keys / focus-bound keys) | container `onKeyDown` + `tabIndex` | pool-side self-handling, see §4.2 (document/window keydown is forbidden) |
575
654
  | Colors | CSS variables | `var(--xxx)`, list in `src/index.css` |
576
- | Font sizes | CSS variables | `var(--font-size-*)` + `--ui-scale`, bare px forbidden (#180 gate, see §10) |
655
+ | Font sizes | CSS variables | `var(--font-size-*)` + `--ui-scale`, bare px forbidden (gate, see §10) |
577
656
  | Six-domain token overview | see the §11.1 matrix | color/surface/radius/glass/font size/font family—`var(--*)` follows theme+glass+scaling automatically; full list in `src/index.css` |
578
657
  | UI discipline gate | `linkdesk-plugin-sdk lint` | all 15 items are WARNs that never fail; a knowing bypass = a standard eslint-disable declaration (see §11.2) |
579
658
  | Text | `t()` | `useTranslation()` from `react-i18next` |
@@ -1,6 +1,6 @@
1
1
  # README Description-Area Media Contract
2
2
 
3
- > 2026-09-09 · Documented (the author contract was added after all four 70a–d forms shipped). **Written for third-party plugin authors.**
3
+ > 2026-09-09 · Documented (the author contract was added after all four forms shipped). **Written for third-party plugin authors.**
4
4
  > This document answers one question: **your README gets displayed by the plugin details page inside the LinkDesk app — if you want images / animated images / demo videos in it, how should you write them, and what are the rules?** Benchmarked against the open display canvas of VS Code's update page / extension READMEs.
5
5
  > Nature = **interface contract** — it only defines "how an author writes it correctly + how it will be displayed"; it contains no implementation code (the implementation surface = the shell's shared MarkdownView + the marketplace DetailView). Authors don't need to know how the app renders — just get the points below right.
6
6
 
@@ -32,7 +32,7 @@
32
32
  | **契约 40 命名空间** | 池注入 39(唯一缺 `bridge`);壳注入 22;mock 注入 12 |
33
33
  | **池 = 插件运行时真相源** | 插件运行在池(pool)preload——池注入的命名空间为 **required**;`bridge` 真壳独有 |
34
34
  | **「仅壳」≠ 插件不可调** | `window.*`/`shell.*`/`hotExit.*`/`getFilePath` 池**实有注入**(N1 超集注记)——旧版把这几面标 ❌ 仅壳是错的 |
35
- | **契约必选面漂移已清零** | D1 `env.get(pluginId)` 转发、D2 `clipboard.readText` 壳补、D3 `dialog.openFile` 壳补——#20 全补实现,无 `?` 降级 |
35
+ | **契约必选面漂移已清零** | D1 `env.get(pluginId)` 转发、D2 `clipboard.readText` 壳补、D3 `dialog.openFile` 壳补——三项都已补齐实现,无 `?` 降级 |
36
36
 
37
37
  ---
38
38
 
@@ -44,7 +44,7 @@
44
44
 
45
45
  - **生成源:** `src/core/api/linkdesk-api.ts` + `linkdesk-api/`(14 域接口)+ `src/core/types/ipc/*` + `src/core/types/pool/*`(wire 载荷类型)
46
46
  - **生成器:** `scripts/generate-contract.mjs`(Route C——契约类型文件为源,纯类型打包单文件)
47
- - **机械门禁:** preload 双端 `satisfies` 契约面类型 → tsc 漂移门禁;`npm run check` 内 `contracts:check` hash 字节比对(#21)
47
+ - **机械门禁:** preload 双端 `satisfies` 契约面类型 → tsc 漂移门禁;`npm run check` 内 `contracts:check` hash 字节比对
48
48
  - **覆盖矩阵:** 每个命名空间 × 池/壳/mock 四面覆盖 → [命名空间矩阵 §2](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/契约生成/命名空间矩阵.md#2-命名空间--四面覆盖矩阵)
49
49
 
50
50
  ### 3.1 插件侧怎么消费
@@ -61,9 +61,9 @@ async function list(): Promise<FileEntry[]> {
61
61
  }
62
62
  ```
63
63
 
64
- **路径 B——独立 npm 包(第三方插件,#22.6):** `npm i -D @linkdesk/contracts` 后同款 `import type { ... } from "@linkdesk/contracts"`。
64
+ **路径 B——独立 npm 包(第三方插件):** `npm i -D @linkdesk/contracts` 后同款 `import type { ... } from "@linkdesk/contracts"`。
65
65
 
66
- > **包形态(建):** `contracts/` 即 npm 包根(`@linkdesk/contracts`,`types` 入口直指 `linkdesk.d.ts`,零构建,`files` 白名单只 d.ts)。**版本轴独立(2026-09-06 拆焊,反向 22.6 版本联动):** 包版本**不再随壳**——软件升级(用户轴)≠ 契约升级(作者轴);只有当 `window.linkdesk.*` API 面变了才升版发布。**内容检测不撤**:d.ts/runtime-shapes 逐字节比对壳源码,漂移即 `contracts:check` 红(改 API 忘重生成 = commit 卡死);**货架节奏 = check-npm-release 黄灯闸**(作者面内容变 + 版本没动 → 提醒 bump+publish)。**消费形态验收:** 仓库根 `contracts-example/`——独立 tsconfig + `file:../contracts` 本地引用,`npx tsc --noEmit` 零错误,全程零 `@src/core`(`npm pack` 出 tarball → 装真实 npm 包路径同样通过)。**发布态:** ✅ 已真发 `@linkdesk/contracts@0.1.0`(2026-09-04)+ `@linkdesk/contracts@0.1.1`(2026-09-06,拆焊后首个独立轴版本)+ `@linkdesk/contracts@0.1.2`(2026-09-06 同日,0.1.1 带旧「版本联动」README 出包 → README 修正重发,d.ts 未变)——第三方 `npm i -D @linkdesk/contracts` 直装 registry 真包;真实包 tsc 验收已通过(真实包 tsc 验收)。plugin-sdk 与 `@linkdesk/ui` 同期已真发。
66
+ > **包形态(建):** `contracts/` 即 npm 包根(`@linkdesk/contracts`,`types` 入口直指 `linkdesk.d.ts`,零构建,`files` 白名单只 d.ts)。**版本轴独立(2026-09-06 拆焊,版本不再与壳联动):** 包版本**不再随壳**——软件升级(用户轴)≠ 契约升级(作者轴);只有当 `window.linkdesk.*` API 面变了才升版发布。**内容检测不撤**:d.ts/runtime-shapes 逐字节比对壳源码,漂移即 `contracts:check` 红(改 API 忘重生成 = commit 卡死);**货架节奏 = check-npm-release 黄灯闸**(作者面内容变 + 版本没动 → 提醒 bump+publish)。**消费形态验收:** 仓库根 `contracts-example/`——独立 tsconfig + `file:../contracts` 本地引用,`npx tsc --noEmit` 零错误,全程零 `@src/core`(`npm pack` 出 tarball → 装真实 npm 包路径同样通过)。**发布态:** ✅ 已真发 `@linkdesk/contracts@0.1.0`(2026-09-04)+ `@linkdesk/contracts@0.1.1`(2026-09-06,拆焊后首个独立轴版本)+ `@linkdesk/contracts@0.1.2`(2026-09-06 同日,0.1.1 带旧「版本联动」README 出包 → README 修正重发,d.ts 未变)——第三方 `npm i -D @linkdesk/contracts` 直装 registry 真包;真实包 tsc 验收已通过(真实包 tsc 验收)。plugin-sdk 与 `@linkdesk/ui` 同期已真发。
67
67
 
68
68
  **路径 C——拷贝文件:** 直接把 `contracts/linkdesk.d.ts` 拷进插件项目 + tsconfig 引用。契约文件单文件自包含(94 声明,零 import 依赖),拷贝即用。
69
69
 
@@ -82,11 +82,11 @@ async function list(): Promise<FileEntry[]> {
82
82
  | **filesystem** | 插件权限:插件数据目录读写、workspace 目录读、**其他插件目录禁止** |
83
83
  | **configuration** | 配置 key 命名规则 `<pluginId>.<property>`(如 `editor.fontSize`、`serial-monitor.baudRate`) |
84
84
  | **serial** | **多口路由:** 打开/关闭/动作定向接口的 `portName` **可选**——缺省 = 唯一打开口(0 口抛「串口未打开」;≥2 口抛「多串口已打开,请指定 portName」;**失败可见,不静默**)。三推流通道(`onData`/`onStats`/`onSystem`)载荷**对象化**带 `portName` 路由键(`SerialDataPayload`/`SerialStatsPayload`/`SerialSystemPayload`)——订阅方按**会话口**过滤(key=portName 是通用路由键模式:谁消费谁过滤,壳不代收)。每标签页仍单口(D3),会话-端口绑定在插件侧 |
85
- | **panel** | `panel.reveal(viewId)` 声明寻址聚焦底部面板视图——面板隐藏 → 展开并切到该视图(Ctrl+J 同机制);已显示 → 切换聚焦;**viewId 不在 panel 容器 → no-op**(不报错)。**`panel.moveToEditor` 已移除**(弃内容迁移——位置移动是布局命令的事)。 `panel.revealFloating(viewId)` 壳内悬浮面板(类型 B)——按声明弹出某视图为悬浮面板。声明寻址 = ViewContainerService 全局视图索引(`contributes.views` 已注册**任意容器**视图,不限 panel——插件声明 `contributes.floatingPanel.viewId` 引用之)。**身份开关键(I8-2)**:无面板 → 开;同视图 → 关(toggle);他面板 → 替换;**viewId 未声明/声明插件未装 → no-op**(不崩)。面板默认动作 =「在主窗口中打开」(仅声明插件可开成标签页时出现)+ 最大化 toggle + 关闭 |
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
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 永不落地) |
88
88
  | **appearance** | `revealStorage` 打开外观存储目录(`userData/appearance`)——主进程解析路径并 `shell.openPath` 开资源管理器**内容**(非 `showItemInFolder` 高亮单文件);目录缺省也建(打开即见存储位置,空目录合法),`openPath` 失败抛错 fail-loud。返回 `Promise<void>` |
89
- | **app** | `app.getVersion` = 宿主软件版本号(`Promise<string>`,只读)——唯一运行时来源 = Electron `app.getVersion`(`package.json` 单点,02 §2.3);**主软件版本比对入口**(市场 minAppVersion、更新检查 #57.5 消费)。壳内另有 `getProductInfo` 私有扩展(关于页 8 字段数据源 #57.14,不在契约——池插件不可调) |
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**——复用既有面,此行为契约由全窗广播保证 |
91
91
  | **notifications** | **唯一通知面 = 状态栏铃铛宽面板**(右下窄 toast 链路已整删)——不弹卡、不抢焦点、不挡操作;未读计数 +1,用户点开才看见。**别把它当「必须被看见」的通道**:要用户当场决定 → `dialog.confirm`。**`show` 一律返回句柄**(`{ update, finish, cancel }`,——**不是只有 `progress:true` 才有**);**一条通知只能被创建它的那个句柄更新/删除**,别处同文案 `show` = 另一条。`progress:true` 开真进度条:`update(msg, percent?)` 给 0-100 确定条、不传 percent = 不定态动画;`finish(msg?)` 关掉并可选补完成通知;`cancel` 直接关掉不补。`persistent:true` = 长驻不自动消失(错误诊断类),等用户点 ×。**常驻配额按 `source` 分桶各 5 条**,超出顶掉同来源最老的并给汇总提示(长驻 ≠ 留档,要留档写自己的文件)。`source` = **机器读的归属键、不含人类文案**(人类可读名壳解析)——⚠️ **做不到自动注入**:池是单进程共享 realm,所有插件共用一个 `window.linkdesk`,preload 无从知道这次 `show` 是哪个插件的树发的 ⇒ **只能作者显式报自己的插件 id**(壳自身域用 `app.<域>`);**不传 → 全落「其他」组**。`actions` 点击走壳 `executeCommand(command, args)`,handler 插件自注册 |
92
92
  | **dialog** | `confirm`/`alert`/`open`/`openFile` = 壳渲染的模态框(抢焦点、有焦点锁)。**`confirmContent(options)`** = **富内容确认**——对话框仍是壳(居中/遮罩/Esc/焦点锁/点遮罩取消),**内容 = 插件自绘视图**(`pluginId` + `viewId` 声明寻址 + 不透明 `payload`,对标 VS Code「对话框是壳、内容插件定」)。**内容侧读法**:视图挂载后经 `dialogHost.current?.content?.payload` 取数(`open !== true` → `null`,防御不白屏);**结算只有 `dialogHost.confirm` / `dialogHost.cancel` 两条路**(别自己关弹窗,壳不认)。**兜底是硬的**:`viewId` 解析不出(未声明/声明插件没装)→ 壳**回落纯文字确认框**(用 `title`/`message`),弹窗照出、不静默死 ⇒ `title`/`message` 别省。`payload` 过 IPC 结构化克隆 ⇒ 只能放可克隆数据 |
@@ -105,7 +105,7 @@ async function list(): Promise<FileEntry[]> {
105
105
 
106
106
  旧版 §3.x 逐命名空间方法清单已删除(= 手写第二份真相源,必然漂移)。生成的契约解决了几处**旧文档与实现不符**的漂移:
107
107
 
108
- | 点 | 旧手写版 | 契约/实现实况(#20 后) |
108
+ | 点 | 旧手写版 | 契约/实现实况 |
109
109
  |------|------|------|
110
110
  | `serial.listPorts()` | 写成 `getPorts()` | 契约 `listPorts()`——实现一直叫这个,旧文档笔误 |
111
111
  | `serial.onData/onStats/onSystem` | `cb: (d: any)` / string | **载荷对象化**:`onData(p: SerialDataPayload)` / `onStats(p: SerialStatsPayload)` / `onSystem(p: SerialSystemPayload)`——三通道均带 `portName` 路由键(`SerialStats` 已删除,无死类型尾巴) |
@@ -133,7 +133,7 @@ async function list(): Promise<FileEntry[]> {
133
133
  | `import { getWorkspaceFolders } from "@src/core/WorkspaceService"` | `lk.workspace.getFolders()` |
134
134
  | `import type { FileEntry } from "@src/core/types/fileEntry"` | `import type { FileEntry } from "@linkdesk/contracts"` |
135
135
 
136
- **ESLint `error`(`noCoreImportInPlugin`,#20-d 收紧):** `import { ... } from "@src/core/..."` **和** `import type { ... } from "@src/core/..."` → 🚫 编译失败。测试文件不再豁免(vitest 单进程理由不成立)。
136
+ **ESLint `error`(`noCoreImportInPlugin`,收紧到 `import type` 也在内):** `import { ... } from "@src/core/..."` **和** `import type { ... } from "@src/core/..."` → 🚫 编译失败。测试文件不再豁免(vitest 单进程理由不成立)。
137
137
 
138
138
  **允许的 import(共享控件走 `@linkdesk/ui` npm 包;`@src/core` 例外白名单全表见 `eslint-local-rules.js` PLUGIN_IMPORT_WHITELIST):**
139
139
  - `@linkdesk/contracts` **类型**(`import type`,零运行时耦合)——registry 真包(见 §三 3.1)
@@ -148,7 +148,7 @@ markLoadStarted(PENDING → LOADING)
148
148
 
149
149
  > 🔴 **2026-09-09 退役:`activationEvents` 字段已整体删除**(壳侧延迟激活轨已全退役——activation.ts / loader defer / `activatePlugin` / CommandRegistry 预激活钩全删,schema 三副本去字段)。**壳启动一律注册全量元数据**(`loadPlugin(pluginId, "startup")`,零 JS import);插件 **JS 由池按 URL 懒加载**。无字段可写、无需声明——加载模型只剩下面两种按需轨。
150
150
 
151
- **启动即注册元数据:** 启动 `initPluginLoader` 发现全部插件 → 壳注册 manifest/contributes(命令显示名/菜单/配置 schema/图标栏元数据全可见)——**不 import 任何插件 JS**(硬约束 #17d:壳 bundle 零插件源码)。
151
+ **启动即注册元数据:** 启动 `initPluginLoader` 发现全部插件 → 壳注册 manifest/contributes(命令显示名/菜单/配置 schema/图标栏元数据全可见)——**不 import 任何插件 JS**(壳 bundle 零插件源码)。
152
152
 
153
153
  **JS 加载 = 池的两种按需轨(插件作者契约):**
154
154
 
@@ -267,7 +267,7 @@ unloadPlugin(pluginId, reason, displayName)
267
267
 
268
268
  ```
269
269
  validating → 包源:主进程 plugins:download / plugins:extract → 解压前校验
270
- (zip 顶层 plugin.json 定位 + JSONC 解析(#55)+ pluginId 裁决 + zip-slip 防护——不留半装目录)
270
+ (zip 顶层 plugin.json 定位 + JSONC 解析 + pluginId 裁决 + zip-slip 防护——不留半装目录)
271
271
  → 目录源:plugin.json 存在 + JSON.parse 合法
272
272
  → pluginId 裁决(**manifest.pluginId 优先**;缺省 zip 基名/源目录名兜底——**兜底只为兼容存量第三方
273
273
  插件**,新插件一律显式声明,见 [16-命名规范](16-命名规范.md);须过安全字符集);version 必填
@@ -333,7 +333,7 @@ loading → loadPlugin(pluginId, "install")(安装态 bundle 路径即时加
333
333
  | 维度 | VS Code | LinkDesk |
334
334
  |------|---------|----------|
335
335
  | 激活时机 | `activationEvents` 多事件(onLanguage/onCommand/workspaceContains…) | **无事件字段**(已退役)——启动全量注册元数据;JS 由池按需加载 |
336
- | 延迟加载 | 扩展 JS 按需 import | 壳启动零 JS import(#17d);JS 唯一执行者 = 池——表面挂载 URL 懒加载 / 命令 miss 时 import entry(on-command 激活、§五) |
336
+ | 延迟加载 | 扩展 JS 按需 import | 壳启动零 JS import;JS 唯一执行者 = 池——表面挂载 URL 懒加载 / 命令 miss 时 import entry(on-command 激活、§五) |
337
337
  | 加载扫描 | 启动 scan `extensions/` | 发现单源 `plugins:listAll` 主进程直扫(dev/prod 同面)+ 2s 轮询热插拔 |
338
338
  | 依赖 | `extensionDependencies` | `requires`(string 数组)+ 挂起 PENDING / 环 fail / 连带卸载 |
339
339
  | 卸载 | Disable / Uninstall | 安装态 = 真删目录 + 销账(removed 标记,boot 不复活);repo 源码树 app 插件 = 移 `.disabled/` 作**同会话** undo(跨重启孤儿 boot 自动清) |
@@ -33,7 +33,7 @@
33
33
  | `titleBar` | ✅ | 顶栏左右槽位按钮 | MenuRegistry |
34
34
  | `viewsContainers` | ✅ | 声明侧栏/面板容器 | ViewContainerService |
35
35
  | `views` | ✅ | 往容器注册视图——任何插件可往任意容器注册 | ViewContainerService |
36
- | `floatingPanel` | ✅ | 声明某视图可在壳内悬浮面板显示(类型 B)——viewId 引用已注册视图;未声明则无「在悬浮面板中打开」右键(I8-3) | 声明寻址 → FloatingPanelService |
36
+ | `floatingPanel` | ✅ | 声明某视图可在壳内悬浮面板显示(类型 B)——viewId 引用已注册视图;未声明则无「在悬浮面板中打开」右键 | 声明寻址 → FloatingPanelService |
37
37
  | `i18n` | ✅ | 插件自带翻译文件 | i18nResources(i18next 命名空间) |
38
38
 
39
39
  ### 主进程消费(2 个)
@@ -665,9 +665,9 @@ useEffect(() => {
665
665
 
666
666
  | 声明后效果 | 机制 |
667
667
  |------|------|
668
- | 标签页右键出现「在悬浮面板中打开」 | I8-3——未声明不出现(按声明过滤) |
669
- | 打开后面板内三动作(在主窗口中打开 / 最大化 / 关闭) | I8-4/I8-9——「在主窗口中打开」落点 = 当前活动 group 尾部(复用文件树打开落点规则) |
670
- | `linkdesk.panel.revealFloating(viewId)` 可编程弹面板 | I8-2 面板身份开关键——无面板→开;同视图→关;他面板→替换 |
668
+ | 标签页右键出现「在悬浮面板中打开」 | 未声明不出现(按声明过滤) |
669
+ | 打开后面板内三动作(在主窗口中打开 / 最大化 / 关闭) | 「在主窗口中打开」落点 = 当前活动 group 尾部(复用文件树打开落点规则) |
670
+ | `linkdesk.panel.revealFloating(viewId)` 可编程弹面板 | 面板身份开关键——无面板→开;同视图→关;他面板→替换 |
671
671
  | 卸载声明插件 → 右键条目消失 + revealFloating no-op 不崩 | 声明随插件生命周期卸载 |
672
672
 
673
673
  **首批声明者 = settings**(`core.openSettings` Ctrl+, 弹面板);**第二声明者验证载体 = `floating-panel-demo`** 测试插件(标签页型视图,端到端验证替换 + 右键回程 + 卸载 no-op)。
@@ -42,7 +42,7 @@ my-plugin/
42
42
  | **用户安装** | `pluginManager.install(url \| 磁盘 zip \| 目录)` | 同上 | 下载/解压/校验 → 落盘;目录源仅 dev 便捷用,分发主路是 zip |
43
43
 
44
44
  **安装期校验(解压前拦截,不产生半装目录):**
45
- - zip 顶层定位 `plugin.json`(basename 匹配,容忍单层 wrapper 目录)——JSONC 解析(#55)
45
+ - zip 顶层定位 `plugin.json`(basename 匹配,容忍单层 wrapper 目录)——JSONC 解析
46
46
  - `pluginId` 裁决:manifest 优先、zip 文件基名兜底,双源互验;必须过安全字符集(无路径分隔符/相对段)
47
47
  - zip-slip 防护——条目路径拒绝逃逸解压目标
48
48
  - 目标已装同版本 → 跳过(用户安装删源);异版本 → 不动(升级是更新流职责,boot 不覆盖)
@@ -93,7 +93,7 @@ my-plugin/
93
93
 
94
94
  `version` 遵循 semver(`major.minor.patch`)。**boot 永不刷新已装插件**(bundled 夹 = 首启离线种子,非更新通道)——已装用户拿新内容只有一条路 = **更新流**:`pluginManager.checkUpdates`(fetch catalog + semver 对比)→ `update`(stage 到 tmp → 原子替换 → 失败退旧版)。市场真实条目按版本发现更新。
95
95
 
96
- ### 🔥 内容变更必 bump 自身 version(2026-09-06 #15n 定案)
96
+ ### 🔥 内容变更必 bump 自身 version(2026-09-06 定案)
97
97
 
98
98
  **分发过的插件,任何内容变更(代码 / 资源 / README / CHANGELOG)都必须 bump `plugin.json.version`。** 已装用户的副本是**按版本固化**的——boot 只补缺失、永不刷新已装;用户拿到新内容的唯一路 = **版本号**。改内容不 bump = 已装用户永远滞留在旧内容(2026-09-06 实证:bundled 发货 zip 加了 pyright 没 bump → 已装副本 LSP 全挂)。
99
99
 
@@ -455,7 +455,7 @@ function MyConfirmContent() {
455
455
  | **字号** | `--font-size-2xs … 4xl` + `--ui-scale`(`app.uiFontScale` 缩放轴,档位表见 §10) | `font-size: var(--font-size-md)` / em/rem | `check-font-scale`(check 腿——字号裸 px 即红) |
456
456
  | **字体族** | `--font-ui` / `--font-mono` | `font-family: var(--font-ui)` | 契约引导(作者合法自选字体) |
457
457
 
458
- `var(--*)` = 换主题/玻璃/全局缩放自动跟随,零插件感知——**这正是 @linkdesk/ui 控件层「零思考跟随」的底层原因**(54b/54c:控件全 token,插件 `npm i @linkdesk/ui` 消费即跟)。控件复用统一从 `@linkdesk/ui` import(见 §速查),不手写轮子。
458
+ `var(--*)` = 换主题/玻璃/全局缩放自动跟随,零插件感知——**这正是 @linkdesk/ui 控件层「零思考跟随」的底层原因**——控件全部写在 token 上,插件 `npm i @linkdesk/ui` 消费即跟随。控件复用统一从 `@linkdesk/ui` import(见 §速查),不手写轮子。
459
459
 
460
460
  ### 11.2 诚实边界 / 知情绕行——内容与品牌色可以有自己天空
461
461
 
@@ -522,7 +522,7 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
522
522
  | **不写死其他插件 ID**(差异性行为走 plugin.json 声明字段,Registry 模式消费) | `03-插件contributes规范.md` |
523
523
  | 配置键**必给 default** | `06-plugin.json规范.md` |
524
524
  | **只用文档化 API 命名空间**(禁 linkdesk.xxx 未文档化随手挂) | `01-插件API契约.md` |
525
- | 控件统一走 `@linkdesk/ui`(54c 起内置控件从 npm 包 import,禁止 `@src/components/shared/*`) | 本文件 §速查 |
525
+ | 控件统一走 `@linkdesk/ui`(内置控件从 npm 包 import,禁止 `@src/components/shared/*`) | 本文件 §速查 |
526
526
 
527
527
  ---
528
528
 
@@ -532,17 +532,45 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
532
532
  (`@linkdesk/ui`)的样式、以及**所有已加载插件**的样式——**类名是全局标识符**。你写下一个类名,
533
533
  就等于占用了这个名字;别人也用这个名字,两边的样式就会落到同一个元素上。
534
534
 
535
- **两条纪律:**
535
+ **三条纪律:**
536
536
 
537
- 1. **给自己的元素起带前缀的类名**——官方插件就是这么做的(`settings-*`、`ms-*`、`mpd-*`)。
538
- 前缀用你自己的插件名或简写,别用 `.active-panel` 这种一看就通用的名字。
539
- 2. **下面这些名字属于宿主保留名,不要拿来给自己的元素命名**(用了就会被宿主的样式命中):
537
+ 1. **给自己的元素起的类名,必须以 `pluginId` 加连字符开头**——`settings-*`、`editor-*`、`file-tree-*`……
538
+ `pluginId` 就是你 `plugin.json` 里声明的那个 id(官方插件统统这么做)。**别用缩写**:`ms-`、
539
+ `mpd-` 这类简写写法**已经废弃**——缩写不保证唯一,两个插件各自缩写成 `ms-` 就撞在一起了;
540
+ 而 `pluginId` 的唯一性由发布流程保证(发布后不可变),拿它当前缀是免费的防撞。
541
+ 2. **`@keyframes` 的名字一样要带前缀**(`file-tree-fadeIn`),并且**改名字时同笔改 `animation:` 的引用**——
542
+ 关键帧名与类名一样是全局标识符,重名时后加载的那份会把前一份的动画顶掉。
543
+ 3. **下面这些名字属于宿主保留名,不要拿来给自己的元素命名**(用了就会被宿主的样式命中):
540
544
 
541
545
  | 来源 | 保留名 | 说明 |
542
546
  |---|---|---|
543
547
  | 宿主全局工具类 | `.input` | 输入框工具类——**直接用即可**(它本来就是给你的输入框用的) |
544
- | 宿主全局工具类 | `.titlebar`、`.divider`、`.about`、`.rn`、`.vta` | 宿主界面自己的容器名,不要复用 |
545
- | 共享组件公共类名 | `.badge`、`.button`、`.combobox`、`.mdv`、`.selectbox`、`.sle`、`.slider`、`.toggle` | 分别是 `@linkdesk/ui` 里徽标 / 按钮 / 组合输入 / Markdown 容器 / 下拉 / 数组编辑器 / 滑杆 / 开关的类名 |
548
+ | 共享组件类名 + 宿主容器类名 | **整个 `ldk-` 命名空间**——今天有 `ldk-badge`、`ldk-button`、`ldk-combobox`、`ldk-mdv`、`ldk-selectbox`、`ldk-sle`、`ldk-slider`、`ldk-toggle` 八个(共享组件),另含宿主自己的容器类(如 `ldk-titlebar`) | 分别是 `@linkdesk/ui` 里徽标 / 按钮 / 组合输入 / Markdown 容器 / 下拉 / 数组编辑器 / 滑杆 / 开关的类名。**你不用记这些名字**——记一条就够:**凡 `ldk-` 开头都是宿主自己的(共享组件 + 宿主界面容器),不要拿给自己的元素用** |
549
+
550
+ **`@keyframes` 的名字同理**——宿主自己也用着下面这些动画名,给你的动画起名时避开它们。重名的后果和类名一样(后加载的那份顶掉先加载的),而且同样是**静默**的:你的动画或宿主的动画有一个不播了,控制台没有任何报错。
551
+
552
+ | 保留的关键帧名 | 说明 |
553
+ |---|---|
554
+ | `selectbox-in` | 共享组件下拉框的入场动画 |
555
+ | `drop-zone-in` | 拖放区的入场动画 |
556
+ | `dropdown-card-in` | 下拉卡片的入场动画 |
557
+ | `floating-panel-in` | 浮动面板的入场动画 |
558
+ | `group-tab-enter` | 分组标签的入场动画 |
559
+ | `group-tab-exit` | 分组标签的退场动画 |
560
+ | `notif-icon-spin` | 通知图标的旋转 |
561
+ | `notif-progress-scan` | 通知的进度扫描 |
562
+
563
+ > 🔧 **维护者注(作者可跳过)**:上面两张表的「**保留名**」「**保留的关键帧名**」两列都是**机器读的**——`npm run check` 里的门禁
564
+ > (`scripts/check-reserved-names-doc-sync.mjs`)把它们与登记表
565
+ > `packages/plugin-sdk/schemas/reserved-class-names.json` **双向核对**:登记表里的名字必须在这里出现,
566
+ > 这里出现的名字必须在登记表里登记(裸名)、或在宿主源码里真实存在(`ldk-` 名);关键帧表与登记表的
567
+ > `keyframes` 段同样**双向**。
568
+ > ⇒ **改这两列 = 改公共面**:加/删一个名字要**同笔改三处**——登记表 + 中英两棵树的这两张表。
569
+ > 两列**只放名字**,解释写「说明」列。
570
+
571
+ **还有一条跟命名空间有关的**:你的 `pluginId` **不得以 `ldk-` 开头**——整个 `ldk-` 命名空间是宿主的,
572
+ 一个叫 `ldk-tools` 的插件用纪律 1 派生出来的前缀(`ldk-tools-*`)会**由构造落进宿主空间**,纪律 1
573
+ 也就跟着失效了。这条约束写在 `plugin.json` 的 schema 里,编辑器会当场提示。
546
574
 
547
575
  **要它们的样子,就用它们的组件**——`import { Button } from "@linkdesk/ui"`,不要手写它的类名
548
576
  (手写等于绕过组件,组件升级你就掉队)。
@@ -553,6 +581,45 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
553
581
  **反例(真实踩过)**:把宿主保留名当成「随手可用的样式名」套到自己的元素上,结果底色和文字被涂成
554
582
  同一个颜色、文字被背景吞掉,界面上看着就是「一块纯色」——**不报错**,只是长得不对,很难查。
555
583
 
584
+ ### 12.1 从旧版 `@linkdesk/ui` 升上来——一件要你自己改的事
585
+
586
+ 共享组件的类名带上了 `ldk-` 前缀(`@linkdesk/ui` **0.2.0** 起)。这件事**只影响一种写法**:
587
+ 你写在**插件自己 CSS 里**、用后代选择器去微调共享组件外观的那些规则。**升级前不用动,升级时改一处前缀即可。**
588
+
589
+ - **什么时候受影响**:把 `@linkdesk/ui` 升到 **0.2.0 之后**——**不是立刻**。旧版本里这些组件的类名是
590
+ `.badge` 这样的裸名,包里带的 CSS 与组件自洽,**你不升级就不会坏**。(依赖写 `^0.1.x` 时不会自动
591
+ 跨到 `0.2.0`,所以只有你主动升级的那一下才需要动。)
592
+ - **什么会受影响**:你**插件自己 CSS** 里的这类后代选择器——
593
+ `.control-bar .combobox { … }`、`.settings-slider-control .slider { … }`、`.changelog .mdv { … }`
594
+ 等等。**组件自己的样式不受影响,你自己的类名也不用改。**
595
+ - **怎么改**:把选择器里**指向共享组件的那一段**加上 `ldk-` 前缀——`.combobox` → `.ldk-combobox`、
596
+ `.slider` → `.ldk-slider`、`.mdv` → `.ldk-mdv`、`.badge` → `.ldk-badge`、`.selectbox-trigger` →
597
+ `.ldk-selectbox-trigger`、`.combobox-field` → `.ldk-combobox-field`——**族里的名字(`-trigger` / `-field` /
598
+ `-input` 这类后缀)一样带前缀**。你自己的前缀(`.control-bar`、`.settings-*`)照旧。
599
+ **升级后拿这八个旧基名 `.badge`、`.button`、`.combobox`、`.mdv`、`.selectbox`、`.sle`、`.slider`、`.toggle`
600
+ grep 一遍自己的 CSS**:在调共享组件的就加上前缀,其余别动。
601
+ - **为什么不自动兼容**:这类失配**不报错**——选择器匹配不上,只是那几条规则悄悄不再生效,界面看着
602
+ 「大致还对、就是不太对」。正因为它是静默的,我们才把名字收进 `ldk-` 前缀,并把这段写进文档。
603
+
604
+ ### 12.2 前缀规则(§12 纪律 1/2)上线——既有代码要不要动
605
+
606
+ **一句话:不改也照常跑,但下次动那个文件就是该改的时候。**
607
+
608
+ - **官方插件已经按新规则清过账**——本次改名涉及四只:`file-tree`(v1.0.9)、`settings`(v1.0.11)、
609
+ `serial-monitor`(v1.0.12)、`marketplace`(v1.0.33),裸类名与关键帧名都补上了 `<pluginId>-` 前缀;
610
+ 其余官方插件仓本来就没有裸定义(它们的类名不是自带前缀,就是根本没定义类名)。以官方插件清单为口径
611
+ 的审计读数是 **18/18 合规**。
612
+ - **第三方作者没有仓要改**:这条规则只管**你自己写的类名与关键帧名**——不动仓库结构、不动 `pluginId`、
613
+ 也不影响别人的代码。你既有插件**不用为它单独发版**。
614
+ - **旧的无前缀类名不会报错、也不会失效**——今天照常工作。代价是**撞名的风险仍然在**:另一个插件写了
615
+ 同名类名,两边样式就会落到同一个元素上(不报错,只是长得不对,很难查)。
616
+ - **合规由工程自带的检查判**:脚手架建出来的工程带着一条严格检查腿(`npm run verify`),它扫你自己 CSS
617
+ 里**给自有元素裸定义**的类名和 `@keyframes` 名,不带 `<pluginId>-` 前缀就判红。所以真正的动作是
618
+ **下一次动那个文件时顺手把名字改掉**:`.panel {}` → `.myplugin-panel {}`,CSS 与用到它的 JSX 两侧一起改
619
+ (只改标识符,不动样式值)。
620
+
621
+ > 现在就想看看自己的工程有没有裸名?在工程根跑 `npm run verify`。
622
+
556
623
  ---
557
624
 
558
625
  ## 速查
@@ -569,7 +636,7 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
569
636
  | 快捷键(非文本键) | `plugin.json contributes.keybindings` | —(文本键写这里 = 吞全池,见 §4.1) |
570
637
  | 快捷键(文本键/焦点绑定键) | 容器 `onKeyDown` + `tabIndex` | 池侧自处理,见 §4.2(禁止 document/window keydown) |
571
638
  | 颜色 | CSS 变量 | `var(--xxx)`,列表见 `src/index.css` |
572
- | 字号 | CSS 变量 | `var(--font-size-*)` + `--ui-scale`,禁止裸 px(#180 门禁,见 §10) |
639
+ | 字号 | CSS 变量 | `var(--font-size-*)` + `--ui-scale`,禁止裸 px(门禁见 §10) |
573
640
  | 六域 token 总览 | 见 §11.1 矩阵 | 颜色/表面/圆角/玻璃/字号/字体族——`var(--*)` 自动跟随主题+玻璃+缩放;完整清单 `src/index.css` |
574
641
  | UI 纪律门禁 | `linkdesk-plugin-sdk lint` | 15 项全 WARN 永不 fail;知情绕行 = 标准 eslint-disable 声明(见 §11.2) |
575
642
  | 文字 | `t()` | `useTranslation()` from `react-i18next` |
@@ -114,7 +114,7 @@ my-plugin/
114
114
  | `contributes.themes` | theme (P6) | 注册到 ThemeRegistry → 主题浏览器 |
115
115
  | `contributes.languages` | language (P6) | 注册到 LanguageRegistry |
116
116
  | `contributes.fileAssociations` | — (P6) | 注册到 FileAssociationService → 双击文件自动打开 |
117
- | `contributes.floatingPanel` | — | 声明视图可在壳内悬浮面板显示——viewId 引用已注册视图;未声明则无「在悬浮面板中打开」右键(I8-3) |
117
+ | `contributes.floatingPanel` | — | 声明视图可在壳内悬浮面板显示——viewId 引用已注册视图;未声明则无「在悬浮面板中打开」右键 |
118
118
 
119
119
  **插件可同时声明多种贡献。** 比如一个视图插件可以有 `entry` + `sidebar` + `statusBar` + `contributes.configuration` + `contributes.commands`——全部独立注册,互不影响。
120
120
 
@@ -177,7 +177,7 @@ const off = await window.linkdesk.filesystem.watch('/workspace', (e) => {
177
177
 
178
178
  ---
179
179
 
180
- ## 七、终端——第一个交出数据的插件(E3j #77-#79,历史参考)
180
+ ## 七、终端——第一个交出数据的插件(历史参考)
181
181
 
182
182
  > 2026-08-21 注:本节是 E3 时代的历史记录,**终端插件的当前实现已与下述任务有出入**(数据源已归一化到数据管道)。保留作为"第一个数据源插件怎么做"的模式参考。
183
183
 
@@ -185,9 +185,9 @@ const off = await window.linkdesk.filesystem.watch('/workspace', (e) => {
185
185
 
186
186
  | # | 做什么 | 用哪个 API | 谁受益 |
187
187
  |---|--------|-----------|--------|
188
- | #77 | 推原始串口数据 | `events.emit('serial:rawData', data)` | 协议插件订阅后解析 |
189
- | #78 | 广播连接状态 | `events.emit('serial:connected', {...})` | 状态栏/其他插件 |
190
- | #79 | 接收发送命令 | `registerCommand('serial-monitor.send', handler)` | 工作台卡片发数据回 MCU |
188
+ | 1 | 推原始串口数据 | `events.emit('serial:rawData', data)` | 协议插件订阅后解析 |
189
+ | 2 | 广播连接状态 | `events.emit('serial:connected', {...})` | 状态栏/其他插件 |
190
+ | 3 | 接收发送命令 | `registerCommand('serial-monitor.send', handler)` | 工作台卡片发数据回 MCU |
191
191
 
192
192
  **终端没有建任何 API。** 它只调了核心已有的函数:`events.emit`、`registerCommand`。今天的终端走 `serial.onData/onStats/onSystem` 数据管道(§六)+ 命令(§五)——同一原则的进化版。
193
193
 
@@ -1,6 +1,6 @@
1
1
  # README 说明区媒体契约
2
2
 
3
- > 2026-09-09 ·文档化(70a-d 四形态实现全闭后补作者契约)。**写给第三方插件作者。**
3
+ > 2026-09-09 ·文档化(四种形态全部实现后补上的作者契约)。**写给第三方插件作者。**
4
4
  > 这份文档回答一个问题:**你的 README 在 LinkDesk 软件里会被插件详情页展示——里面想放图 / 动图 / 演示视频,怎么写才对、有什么规矩。** 对标 VS Code 更新页 / 扩展 README 的开放展示画布。
5
5
  > 性质 = **接口契约**——只定义「作者怎么写得对 + 会显示成什么样」,不写实现代码(实现面 = 壳共享 MarkdownView + 市场 DetailView)。作者不需要知道 App 怎么渲染,把下面几条写对即可。
6
6
 
@@ -13,8 +13,8 @@
13
13
  },
14
14
  "pluginId": {
15
15
  "type": "string",
16
- "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$",
17
- "description": "🔴 Plugin identity — immutable once published (mirrors VS Code's publisher.name). Everything keys off it: install directory {userData}/plugins/<pluginId>/, distribution file name <pluginId>.linkdesk-plugin, marketplace dedup key, uninstall tombstone key, and update reconciliation. Strongly recommended to declare it explicitly: when omitted it falls back to the project directory name, but repository names and local directory names are free-form — rename the directory and the identity changes with it, and none of the five consequences (two install directories side by side / tombstone mismatch / duplicate marketplace entries / silently broken update chain / plugin data appearing lost) reports an error. Character set: letters, digits, `.`, `_`, `-`; the first character must be a letter or a digit."
16
+ "pattern": "^(?!ldk-)[A-Za-z0-9][A-Za-z0-9._-]*$",
17
+ "description": "🔴 Plugin identity — immutable once published (mirrors VS Code's publisher.name). Everything keys off it: install directory {userData}/plugins/<pluginId>/, distribution file name <pluginId>.linkdesk-plugin, marketplace dedup key, uninstall tombstone key, and update reconciliation. Strongly recommended to declare it explicitly: when omitted it falls back to the project directory name, but repository names and local directory names are free-form — rename the directory and the identity changes with it, and none of the five consequences (two install directories side by side / tombstone mismatch / duplicate marketplace entries / silently broken update chain / plugin data appearing lost) reports an error. Character set: letters, digits, `.`, `_`, `-`; the first character must be a letter or a digit. It must not start with `ldk-`: that whole namespace belongs to the host and its shared components, and since your CSS class prefix is derived from this id (`<pluginId>-your-class`), an `ldk-` id would land in host territory by construction and void the plugin-prefix rule (SDK check-css-namespace leg)."
18
18
  },
19
19
  "type": {
20
20
  "type": "string",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.3",
3
+ "version": "0.1.5",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——`docs/03-插件制造` 的发布产物:从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [