@linkdesk/plugin-docs 0.1.4 → 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
 
@@ -552,13 +552,27 @@ both stylesheets land on the same element.
552
552
  | Host global utility classes | `.input` | Input-box utility—**just use it** (it exists for your inputs) |
553
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
554
 
555
- > 🔧 **Maintainer note (authors can skip this)**—the **Reserved names** column is **machine-read**: the gate
556
- > in `npm run check` (`scripts/check-reserved-names-doc-sync.mjs`) cross-checks it **both ways** against the
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
557
570
  > registry `packages/plugin-sdk/schemas/reserved-class-names.json`—every registry name must appear here, and
558
571
  > every name here must either be registered (bare names) or a real `ldk-` name present in the host source.
559
- > ⇒ **Editing this column is a public-surface change**: add/remove a name in **three places in one commit**—
560
- > the registry plus this table in both language trees. This column holds **class names only**; put prose in
561
- > the third column.
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.
562
576
 
563
577
  **One more namespace rule**: your `pluginId` **must not start with `ldk-`**—the whole `ldk-` namespace belongs
564
578
  to the host, so a plugin called `ldk-tools` would derive its prefix (`ldk-tools-*`) **straight into host
@@ -638,7 +652,7 @@ component. **Nothing to do before you upgrade; when you upgrade, it's one prefix
638
652
  | Shortcuts (non-text keys) | `plugin.json contributes.keybindings` | — (putting text keys here = swallowing the whole pool, see §4.1) |
639
653
  | Shortcuts (text keys / focus-bound keys) | container `onKeyDown` + `tabIndex` | pool-side self-handling, see §4.2 (document/window keydown is forbidden) |
640
654
  | Colors | CSS variables | `var(--xxx)`, list in `src/index.css` |
641
- | 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) |
642
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` |
643
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) |
644
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
 
@@ -547,12 +547,26 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
547
547
  | 宿主全局工具类 | `.input` | 输入框工具类——**直接用即可**(它本来就是给你的输入框用的) |
548
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
549
 
550
- > 🔧 **维护者注(作者可跳过)**:「**保留名**」这一列是**机器读的**——`npm run check` 里的门禁
551
- > (`scripts/check-reserved-names-doc-sync.mjs`)把它与登记表
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`)把它们与登记表
552
565
  > `packages/plugin-sdk/schemas/reserved-class-names.json` **双向核对**:登记表里的名字必须在这里出现,
553
- > 这里出现的名字必须在登记表里登记(裸名)、或在宿主源码里真实存在(`ldk-` 名)。
554
- > ⇒ **改这一列 = 改公共面**:加/删一个名字要**同笔改三处**——登记表 + 中英两棵树的这张表。
555
- > 这一列**只放类名**,解释写第三列。
566
+ > 这里出现的名字必须在登记表里登记(裸名)、或在宿主源码里真实存在(`ldk-` 名);关键帧表与登记表的
567
+ > `keyframes` 段同样**双向**。
568
+ > ⇒ **改这两列 = 改公共面**:加/删一个名字要**同笔改三处**——登记表 + 中英两棵树的这两张表。
569
+ > 两列**只放名字**,解释写「说明」列。
556
570
 
557
571
  **还有一条跟命名空间有关的**:你的 `pluginId` **不得以 `ldk-` 开头**——整个 `ldk-` 命名空间是宿主的,
558
572
  一个叫 `ldk-tools` 的插件用纪律 1 派生出来的前缀(`ldk-tools-*`)会**由构造落进宿主空间**,纪律 1
@@ -622,7 +636,7 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
622
636
  | 快捷键(非文本键) | `plugin.json contributes.keybindings` | —(文本键写这里 = 吞全池,见 §4.1) |
623
637
  | 快捷键(文本键/焦点绑定键) | 容器 `onKeyDown` + `tabIndex` | 池侧自处理,见 §4.2(禁止 document/window keydown) |
624
638
  | 颜色 | CSS 变量 | `var(--xxx)`,列表见 `src/index.css` |
625
- | 字号 | CSS 变量 | `var(--font-size-*)` + `--ui-scale`,禁止裸 px(#180 门禁,见 §10) |
639
+ | 字号 | CSS 变量 | `var(--font-size-*)` + `--ui-scale`,禁止裸 px(门禁见 §10) |
626
640
  | 六域 token 总览 | 见 §11.1 矩阵 | 颜色/表面/圆角/玻璃/字号/字体族——`var(--*)` 自动跟随主题+玻璃+缩放;完整清单 `src/index.css` |
627
641
  | UI 纪律门禁 | `linkdesk-plugin-sdk lint` | 15 项全 WARN 永不 fail;知情绕行 = 标准 eslint-disable 声明(见 §11.2) |
628
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
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.4",
3
+ "version": "0.1.5",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——`docs/03-插件制造` 的发布产物:从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [