@linkdesk/plugin-docs 0.1.4 → 0.1.6
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.
- package/docs/01-plugin-api-contract.md +11 -11
- package/docs/02-plugin-lifecycle.md +2 -2
- package/docs/04-distribution-format.md +4 -4
- package/docs/05-ui-conventions.md +26 -12
- package/docs/06-plugin-json-spec.md +3 -3
- package/docs/12-readme-media-contract.md +1 -1
- package/docs/15-multi-repo-and-local-workspace.md +3 -3
- package/docs/16-naming-conventions.md +1 -1
- package/docs/zh/01-/346/217/222/344/273/266API/345/245/221/347/272/246.md +13 -13
- package/docs/zh/02-/346/217/222/344/273/266/347/224/237/345/221/275/345/221/250/346/234/237.md +6 -6
- package/docs/zh/03-/346/217/222/344/273/266contributes/350/247/204/350/214/203.md +4 -4
- package/docs/zh/04-/346/217/222/344/273/266/345/210/206/345/217/221/346/240/274/345/274/217.md +4 -4
- package/docs/zh/05-/346/217/222/344/273/266UI/345/206/231/346/263/225/350/247/204/347/272/246.md +26 -12
- package/docs/zh/06-plugin.json/350/247/204/350/214/203.md +6 -6
- package/docs/zh/07-/346/217/222/344/273/266/351/227/264/351/200/232/344/277/241.md +4 -4
- package/docs/zh/09-/346/217/222/344/273/266/347/233/256/345/275/225/350/247/204/350/214/203.md +1 -1
- package/docs/zh/12-README/350/257/264/346/230/216/345/214/272/345/252/222/344/275/223/345/245/221/347/272/246.md +1 -1
- package/docs/zh/15-/345/244/232/344/273/223/345/274/200/345/217/221/344/270/216/346/234/254/345/234/260/345/267/245/344/275/234/345/214/272.md +3 -3
- package/docs/zh/16-/345/221/275/345/220/215/350/247/204/350/214/203.md +1 -1
- package/package.json +1 -1
|
@@ -31,8 +31,8 @@ A few key points (a summary of Matrix §2; the matrix wins on details):
|
|
|
31
31
|
|------|------|
|
|
32
32
|
| **The contract has 40 namespaces** | The pool injects 39 (the only missing one is `bridge`); the shell injects 22; mock injects 12 |
|
|
33
33
|
| **Pool = the plugin runtime source of truth** | Plugins run in the pool preload — namespaces injected by the pool are **required**; `bridge` is real-shell-only |
|
|
34
|
-
| **"Shell-only" ≠ plugins can't call it** | `window.*`/`shell.*`/`hotExit.*`/`getFilePath` **are actually injected in the pool**
|
|
35
|
-
| **Contract required-surface drift is now zero** |
|
|
34
|
+
| **"Shell-only" ≠ plugins can't call it** | `window.*`/`shell.*`/`hotExit.*`/`getFilePath` **are actually injected in the pool** — the older version's ❌ shell-only marking for those surfaces was wrong |
|
|
35
|
+
| **Contract required-surface drift is now zero** | `env.get(pluginId)` forwarding, `clipboard.readText` shell completion, `dialog.openFile` shell completion — all three are implemented, with no `?` degradation |
|
|
36
36
|
|
|
37
37
|
---
|
|
38
38
|
|
|
@@ -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`
|
|
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
|
|
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
|
|
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
|
|
|
@@ -81,12 +81,12 @@ async function list(): Promise<FileEntry[]> {
|
|
|
81
81
|
| **decorations** | **Synchronous contract**: `provideDecoration` returns `FileDecoration \| null \| undefined` and **must not return a Promise** (async providers are skipped); a repeated `registerProvider` for the same pluginId idempotently overwrites; unregister/register automatically fires a full refresh notification `onDidChange([])`; if a provider throws, that entry is self-healed away |
|
|
82
82
|
| **filesystem** | Plugin permissions: read/write its own data directory, read the workspace directory, **other plugins' directories are off-limits** |
|
|
83
83
|
| **configuration** | Config key naming rule `<pluginId>.<property>` (e.g. `editor.fontSize`, `serial-monitor.baudRate`) |
|
|
84
|
-
| **serial** | **Multi-port routing:** the `portName` of the open/close/action-targeting interfaces is **optional** — omitted = the single open port (0 ports throws "serial port not open"; ≥2 ports throws "multiple serial ports open, please specify portName"; **failures are visible, never silent**). The three streaming channels (`onData`/`onStats`/`onSystem`) carry **object** payloads with a `portName` routing key (`SerialDataPayload`/`SerialStatsPayload`/`SerialSystemPayload`) — subscribers filter by **their session's port** (key=portName is the generic routing-key pattern: whoever consumes filters; the shell does not collect on their behalf). Each tab is still single-port
|
|
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
|
|
84
|
+
| **serial** | **Multi-port routing:** the `portName` of the open/close/action-targeting interfaces is **optional** — omitted = the single open port (0 ports throws "serial port not open"; ≥2 ports throws "multiple serial ports open, please specify portName"; **failures are visible, never silent**). The three streaming channels (`onData`/`onStats`/`onSystem`) carry **object** payloads with a `portName` routing key (`SerialDataPayload`/`SerialStatsPayload`/`SerialSystemPayload`) — subscribers filter by **their session's port** (key=portName is the generic routing-key pattern: whoever consumes filters; the shell does not collect on their behalf). Each tab is still single-port, and the session-to-port binding lives on the plugin side |
|
|
85
|
+
| **panel** | `panel.reveal(viewId)` focuses a Bottom Panel view through declarative addressing — panel hidden → expand it and switch to that view (the same mechanism as Ctrl+J); already shown → switch and focus; **viewId not in the panel container → no-op** (no error). **`panel.moveToEditor` has been removed** (deprecated content migration — moving position is the job of the layout command). `panel.revealFloating(viewId)` pops a view out as an in-shell Floating Panel (type B) — declared addressing. Declarative addressing = the ViewContainerService global view index (`contributes.views` registers a view in **any container**, not just panel — plugins declare `contributes.floatingPanel.viewId` to reference it). **Identity toggle key**: no panel → open; same view → close (toggle); another panel → replace; **viewId undeclared / declaring plugin not installed → no-op** (no crash). Default panel actions = "Open in main window" (appears only when the declaring plugin can open as a tab) + maximize toggle + close |
|
|
86
86
|
| **hotExit** | Crash recovery only — dirty content is written to disk at `%APPDATA%/linkdesk/hot-exit/` (a single-source path convention owned by the main process; plugins never write there directly); after saving/closing a tab, call `clear` to delete the backup |
|
|
87
|
-
| **shell** | Shell-level OS actions: `showItemInFolder(p)` highlights a single file in Explorer / `openInTerminal(dirPath, terminalExe?, customCommand?)` opens an external terminal / `startDrag(filePath, iconPath?)` drags out to the desktop. **`pluginLocation(pluginId)` / `openPluginFolder(pluginId, kind)` are the plugin-disk-location pair** — the former returns `{ installDir, dataDir } | null` (**it hands over identity, not the right to assemble paths**: the main process resolves paths and the plugin takes the result; not found on disk → `null`; `dataDir` is non-`null` only once the plugin has **actually written to disk**, and empty/absent means that row shouldn't be drawn); the latter's `kind: "install" \| "data"` opens the directory **contents** in Explorer (the same feel as `appearance.revealStorage`, not `showItemInFolder`'s single-file highlight) — the `install` directory not being on disk throws, while `data` creates an empty directory first, then opens.
|
|
87
|
+
| **shell** | Shell-level OS actions: `showItemInFolder(p)` highlights a single file in Explorer / `openInTerminal(dirPath, terminalExe?, customCommand?)` opens an external terminal / `startDrag(filePath, iconPath?)` drags out to the desktop. **`pluginLocation(pluginId)` / `openPluginFolder(pluginId, kind)` are the plugin-disk-location pair** — the former returns `{ installDir, dataDir } | null` (**it hands over identity, not the right to assemble paths**: the main process resolves paths and the plugin takes the result; not found on disk → `null`; `dataDir` is non-`null` only once the plugin has **actually written to disk**, and empty/absent means that row shouldn't be drawn); the latter's `kind: "install" \| "data"` opens the directory **contents** in Explorer (the same feel as `appearance.revealStorage`, not `showItemInFolder`'s single-file highlight) — the `install` directory not being on disk throws, while `data` creates an empty directory first, then opens. **`relaunch` genuinely restarts the app** (quits and relaunches the process) — ⚠️ **injected by the shell preload only (the contract marks it `?` optional)**, so pool-side callers must check existence first (`window.linkdesk.shell.relaunch?.`). The difference from `window.location.reload` is **whether the pool survives**: the pool is a separate `WebContentsView` that a shell reload does not rebuild, so after updating a view-type plugin a reload only shows the old bundle; after `relaunch` the current process terminates immediately, so **don't rely on its return value** (the Promise never settles) |
|
|
88
88
|
| **appearance** | `revealStorage` opens the appearance storage directory (`userData/appearance`) — the main process resolves the path and uses `shell.openPath` to open the Explorer **contents** (not `showItemInFolder`'s single-file highlight); a missing directory is created as well (opening it shows the storage location, and an empty directory is legal), while an `openPath` failure throws and fails loud. Returns `Promise<void>` |
|
|
89
|
-
| **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
|
|
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
|
|
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
|
|
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** (
|
|
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
|
|
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
|
|
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)
|
|
@@ -51,7 +51,7 @@ my-plugin/
|
|
|
51
51
|
|
|
52
52
|
| Source root | Location | Form | HMR | Who lives here |
|
|
53
53
|
|------|------|------|:--:|------|
|
|
54
|
-
| **The plugin's own repo** | GitHub `Encaron/linkdesk-plugin-<id>` (local clones land under `E:\linkdesk-plugins\official\<id>\`) | source + SDK build (`npm run build` → `<id>.linkdesk-plugin`) | ✅ (`linkdesk-plugin-sdk dev`) | **all 18 shipped plugins**—one repo each
|
|
54
|
+
| **The plugin's own repo** | GitHub `Encaron/linkdesk-plugin-<id>` (local clones land under `E:\linkdesk-plugins\official\<id>\`) | source + SDK build (`npm run build` → `<id>.linkdesk-plugin`) | ✅ (`linkdesk-plugin-sdk dev`) | **all 18 shipped plugins**—one repo each, and the only source of truth for their source |
|
|
55
55
|
| **Shell repo fixtures** | `<shell repo>/plugins/<id>/` (`env.appPluginsDir`) | source + Vite on-the-fly compilation | ✅ (`npm run dev` hot reload) | only the two remaining **dev fixtures**: `panel-demo` / `floating-panel-demo` (not shipped, not in the zip) |
|
|
56
56
|
| **Installed state** | `{userData}/plugins/<id>/` | pre-built bundle unpacked from the zip | ❌ (changing the package means rebuild + reinstall/rematerialize) | every plugin installed on the user's machine |
|
|
57
57
|
|
|
@@ -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
|
|
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
|
|
|
@@ -163,7 +163,7 @@ Author-side notes on install/uninstall/update/reinstall are in [02 plugin lifecy
|
|
|
163
163
|
| `core: true` plugins can't be uninstalled (accidental-deletion guard) | `builtin/` built-in extensions |
|
|
164
164
|
| Uninstall = delete directory + settle the ledger (really deleted); only source-tree app plugins move to `.disabled/` | Uninstall = delete files (not recoverable) |
|
|
165
165
|
| `env.get(id).pluginDataDir` | `ExtensionContext.storagePath` |
|
|
166
|
-
| `core: true` plugin shipping = `bundled-plugins/*.linkdesk-plugin` (**a first-launch seed**: boot only fills in what's missing and **never refreshes installed copies**; but **the box itself does refresh with the shell version**—before packaging, `sync:bundled` pulls each plugin's "latest released version"
|
|
166
|
+
| `core: true` plugin shipping = `bundled-plugins/*.linkdesk-plugin` (**a first-launch seed**: boot only fills in what's missing and **never refreshes installed copies**; but **the box itself does refresh with the shell version**—before packaging, `sync:bundled` pulls each plugin's "latest released version") | Ships with app updates (built into the installer) |
|
|
167
167
|
| `requires` **runtime** dependency orchestration ([02 §4](02-plugin-lifecycle.md)) | `extensionDependencies` resolved at install time |
|
|
168
168
|
|
|
169
169
|
---
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Plugin UI Authoring Conventions
|
|
2
2
|
|
|
3
3
|
> **In one line: the core already provides the standard components and registries—don't hand-roll wheels. Hand-rolling = inconsistent style + something to tear out at the next normalization.**
|
|
4
|
-
> Skim this before writing a plugin, to avoid
|
|
4
|
+
> Skim this before writing a plugin, to avoid the same kind of rework.
|
|
5
5
|
> **Reconciled against the implementation on 2026-09-06**: flatten-to-single-root (no plugins/{builtin,user}) · shared controls go through @linkdesk/ui · distribution = `.linkdesk-plugin` zip. References to the corresponding mechanisms have been cleaned out of this page.
|
|
6
6
|
|
|
7
7
|
---
|
|
@@ -36,7 +36,7 @@ window.linkdesk.menu.registerItems("editorContext", "myPlugin", [
|
|
|
36
36
|
<ContextMenu menuId="editorContext" />
|
|
37
37
|
```
|
|
38
38
|
|
|
39
|
-
**Rationale:** `<ContextMenu>` brings its own backdrop + four blur paths (Escape / backdrop click / window blur / option click) + keyboard navigation + when-condition filtering. You can't hand-roll those four blur paths
|
|
39
|
+
**Rationale:** `<ContextMenu>` brings its own backdrop + four blur paths (Escape / backdrop click / window blur / option click) + keyboard navigation + when-condition filtering. You can't hand-roll those four blur paths.
|
|
40
40
|
|
|
41
41
|
**MenuId is an open string (`src/core/registry/commands/MenuRegistry.ts` `export type MenuId = string`)—a plugin declaring any string at all is the contract; no shell code change is needed.** Shell built-in registration points (the MENU_SLOTS constant table):
|
|
42
42
|
|
|
@@ -75,7 +75,7 @@ return createPortal(
|
|
|
75
75
|
);
|
|
76
76
|
```
|
|
77
77
|
|
|
78
|
-
**Rationale:** under the keep-alive architecture inactive tabs are `display: none`, and children aren't visible even with `position: fixed
|
|
78
|
+
**Rationale:** under the keep-alive architecture inactive tabs are `display: none`, and children aren't visible even with `position: fixed`. Only rendering into `document.body` escapes the component-tree constraint.
|
|
79
79
|
|
|
80
80
|
---
|
|
81
81
|
|
|
@@ -317,7 +317,7 @@ const file = await window.linkdesk.dialog.openFile({
|
|
|
317
317
|
});
|
|
318
318
|
```
|
|
319
319
|
|
|
320
|
-
**Rationale:** all three are rendered uniformly by the in-pool host (QuickPickHost / **the bell wide notification panel** / DialogHost)—styles match the shell and scale with the theme and font size. Hand-rolled overlays = inconsistent style + `position: fixed` breaking under keep-alive
|
|
320
|
+
**Rationale:** all three are rendered uniformly by the in-pool host (QuickPickHost / **the bell wide notification panel** / DialogHost)—styles match the shell and scale with the theme and font size. Hand-rolled overlays = inconsistent style + `position: fixed` breaking under keep-alive. Full signatures are in `contracts/linkdesk.d.ts`.
|
|
321
321
|
|
|
322
322
|
> ⚠️ **Notifications are not "auto-vanishing floating cards"** (notification-surface unification and correction): the bottom-right narrow toast pipeline has been deleted entirely, and **the only notification surface = the status bar bell wide panel**. Three things authors need to know:
|
|
323
323
|
> 1. **Notifications don't pop a card, don't steal focus, and don't block interaction**—they go into the bell (unread count +1), and the user only sees them after opening it. Don't treat notifications as a "must be seen" channel: if the user has to decide on the spot → use `dialog.confirm` (modal, steals focus).
|
|
@@ -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"
|
|
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` (
|
|
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
|
-
|
|
556
|
-
|
|
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
|
-
>
|
|
560
|
-
>
|
|
561
|
-
> the
|
|
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 (
|
|
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` |
|
|
@@ -111,9 +111,9 @@ The `entry` field → the loader automatically recognizes this as a view plugin.
|
|
|
111
111
|
| `contributes.configuration` | — | registered into ConfigurationRegistry → rendered automatically by the Settings Editor |
|
|
112
112
|
| `contributes.menus` | — | registered into MenuService → context menus generated dynamically |
|
|
113
113
|
| `contributes.keybindings` | — | registered into KeybindingRegistry → global keyboard listening |
|
|
114
|
-
| `contributes.themes` | theme
|
|
115
|
-
| `contributes.languages` | language
|
|
116
|
-
| `contributes.fileAssociations` | —
|
|
114
|
+
| `contributes.themes` | theme | registered into ThemeRegistry → theme browser |
|
|
115
|
+
| `contributes.languages` | language | registered into LanguageRegistry |
|
|
116
|
+
| `contributes.fileAssociations` | — | registered into FileAssociationService → double-clicking a file opens it automatically |
|
|
117
117
|
| `contributes.floatingPanel` | — | Declares that the view can be displayed in a floating panel inside the shell — viewId references an already-registered view; without the declaration there is no "Open in Floating Panel" context-menu item |
|
|
118
118
|
|
|
119
119
|
**A plugin can declare several contributions at once.** A view plugin, for example, can have `entry` + `sidebar` + `statusBar` + `contributes.configuration` + `contributes.commands` — each is registered independently and does not affect the others.
|
|
@@ -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
|
|
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
|
|
|
@@ -35,16 +35,16 @@ E:\linkdesk-plugins\
|
|
|
35
35
|
|
|
36
36
|
---
|
|
37
37
|
|
|
38
|
-
## 3. Repository names are completely free
|
|
38
|
+
## 3. Repository names are completely free
|
|
39
39
|
|
|
40
40
|
**Repository names are not forced to carry any prefix; third parties have zero constraints.** This has been settled by the maintainer: naming your own plugin (repo) is a legitimate right of the author and can't be dictated.
|
|
41
41
|
|
|
42
|
-
- **A recommended but non-mandatory convention**: official plugin repos uniformly use `linkdesk-plugin-<id>` (
|
|
42
|
+
- **A recommended but non-mandatory convention**: official plugin repos uniformly use `linkdesk-plugin-<id>` (the text lives in [plugin-source-externalization/09-naming-conventions.md §5](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md) — maintained in that one place only); third parties may do as they please.
|
|
43
43
|
- **The cost of renaming a repo**: published catalog entries have `owner/repo` embedded in `downloadUrl` / `readmeUrl`, so **renaming breaks the download and README links of already-published plugins** (the source itself is unaffected). Republishing one new entry after the rename heals it, but old version entries still point at the old links — **if you can avoid changing it, don't; if you must, do it early.**
|
|
44
44
|
|
|
45
45
|
---
|
|
46
46
|
|
|
47
|
-
## 4. Identity vs. display name vs. repository name
|
|
47
|
+
## 4. Identity vs. display name vs. repository name
|
|
48
48
|
|
|
49
49
|
Three "names" that have nothing to do with one another; conflating them is the root of every naming problem:
|
|
50
50
|
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Naming Conventions — Seven Names, One Identity
|
|
2
2
|
|
|
3
3
|
> 2026-09-14 · **Reader = plugin author.** After reading, you can answer four questions: **how do I choose an id? can it be changed? how do I change the display name? what should the repo be called?**
|
|
4
|
-
> The decision rationale
|
|
4
|
+
> The decision rationale and the VS Code empirical evidence live in [plugin-source-externalization/09-naming-conventions.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md) — this document is the author-facing landing point, and of the two there is **only one place to maintain**: change the rule here first and point back; don't create a second copy.
|
|
5
5
|
|
|
6
6
|
---
|
|
7
7
|
|
|
@@ -31,8 +31,8 @@
|
|
|
31
31
|
|------|------|
|
|
32
32
|
| **契约 40 命名空间** | 池注入 39(唯一缺 `bridge`);壳注入 22;mock 注入 12 |
|
|
33
33
|
| **池 = 插件运行时真相源** | 插件运行在池(pool)preload——池注入的命名空间为 **required**;`bridge` 真壳独有 |
|
|
34
|
-
| **「仅壳」≠ 插件不可调** | `window.*`/`shell.*`/`hotExit.*`/`getFilePath`
|
|
35
|
-
| **契约必选面漂移已清零** |
|
|
34
|
+
| **「仅壳」≠ 插件不可调** | `window.*`/`shell.*`/`hotExit.*`/`getFilePath` 池**实有注入**——旧版把这几面标 ❌ 仅壳是错的 |
|
|
35
|
+
| **契约必选面漂移已清零** | `env.get(pluginId)` 转发、`clipboard.readText` 壳补、`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
|
|
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
|
|
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
|
|
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
|
|
|
@@ -81,12 +81,12 @@ async function list(): Promise<FileEntry[]> {
|
|
|
81
81
|
| **decorations** | **同步契约**:`provideDecoration` 返回 `FileDecoration \| null \| undefined`,**不得返回 Promise**(异步提供方被跳过);同 pluginId 重复 `registerProvider` 幂等覆盖;注销/注册自动全量刷新通知 `onDidChange([])`;provider 抛异常自愈剔除该条目 |
|
|
82
82
|
| **filesystem** | 插件权限:插件数据目录读写、workspace 目录读、**其他插件目录禁止** |
|
|
83
83
|
| **configuration** | 配置 key 命名规则 `<pluginId>.<property>`(如 `editor.fontSize`、`serial-monitor.baudRate`) |
|
|
84
|
-
| **serial** | **多口路由:** 打开/关闭/动作定向接口的 `portName` **可选**——缺省 = 唯一打开口(0 口抛「串口未打开」;≥2 口抛「多串口已打开,请指定 portName」;**失败可见,不静默**)。三推流通道(`onData`/`onStats`/`onSystem`)载荷**对象化**带 `portName` 路由键(`SerialDataPayload`/`SerialStatsPayload`/`SerialSystemPayload`)——订阅方按**会话口**过滤(key=portName
|
|
85
|
-
| **panel** | `panel.reveal(viewId)` 声明寻址聚焦底部面板视图——面板隐藏 → 展开并切到该视图(Ctrl+J 同机制);已显示 → 切换聚焦;**viewId 不在 panel 容器 → no-op**(不报错)。**`panel.moveToEditor` 已移除**(弃内容迁移——位置移动是布局命令的事)。 `panel.revealFloating(viewId)` 壳内悬浮面板(类型 B)——按声明弹出某视图为悬浮面板。声明寻址 = ViewContainerService 全局视图索引(`contributes.views` 已注册**任意容器**视图,不限 panel——插件声明 `contributes.floatingPanel.viewId`
|
|
84
|
+
| **serial** | **多口路由:** 打开/关闭/动作定向接口的 `portName` **可选**——缺省 = 唯一打开口(0 口抛「串口未打开」;≥2 口抛「多串口已打开,请指定 portName」;**失败可见,不静默**)。三推流通道(`onData`/`onStats`/`onSystem`)载荷**对象化**带 `portName` 路由键(`SerialDataPayload`/`SerialStatsPayload`/`SerialSystemPayload`)——订阅方按**会话口**过滤(key=portName 是通用路由键模式:谁消费谁过滤,壳不代收)。每标签页仍单口,会话-端口绑定在插件侧 |
|
|
85
|
+
| **panel** | `panel.reveal(viewId)` 声明寻址聚焦底部面板视图——面板隐藏 → 展开并切到该视图(Ctrl+J 同机制);已显示 → 切换聚焦;**viewId 不在 panel 容器 → no-op**(不报错)。**`panel.moveToEditor` 已移除**(弃内容迁移——位置移动是布局命令的事)。 `panel.revealFloating(viewId)` 壳内悬浮面板(类型 B)——按声明弹出某视图为悬浮面板。声明寻址 = ViewContainerService 全局视图索引(`contributes.views` 已注册**任意容器**视图,不限 panel——插件声明 `contributes.floatingPanel.viewId` 引用之)。**身份开关键**:无面板 → 开;同视图 → 关(toggle);他面板 → 替换;**viewId 未声明/声明插件未装 → no-op**(不崩)。面板默认动作 =「在主窗口中打开」(仅声明插件可开成标签页时出现)+ 最大化 toggle + 关闭 |
|
|
86
86
|
| **hotExit** | 崩溃恢复专用——脏内容落盘 `%APPDATA%/linkdesk/hot-exit/`(主进程路径约定单源,插件零直写);保存/关闭标签页后调 `clear` 删备份 |
|
|
87
|
-
| **shell** | 壳级 OS 动作:`showItemInFolder(p)` 资源管理器高亮单文件 / `openInTerminal(dirPath, terminalExe?, customCommand?)` 外部终端打开 / `startDrag(filePath, iconPath?)` 拖出到桌面。**`pluginLocation(pluginId)` / `openPluginFolder(pluginId, kind)` 插件磁盘位置两件套**——前者返回 `{ installDir, dataDir } | null`(**给身份不给路径拼装权**:路径由主进程解析,插件侧拿结果;盘上找不到 → `null`;`dataDir` 只在插件**真落过盘**时非 `null`,空/无 = 那行不该画);后者 `kind: "install" \| "data"` 用资源管理器开目录**内容**(同 `appearance.revealStorage` 手感,非 `showItemInFolder` 高亮单文件),`install` 目录不在盘上抛错,`data`
|
|
87
|
+
| **shell** | 壳级 OS 动作:`showItemInFolder(p)` 资源管理器高亮单文件 / `openInTerminal(dirPath, terminalExe?, customCommand?)` 外部终端打开 / `startDrag(filePath, iconPath?)` 拖出到桌面。**`pluginLocation(pluginId)` / `openPluginFolder(pluginId, kind)` 插件磁盘位置两件套**——前者返回 `{ installDir, dataDir } | null`(**给身份不给路径拼装权**:路径由主进程解析,插件侧拿结果;盘上找不到 → `null`;`dataDir` 只在插件**真落过盘**时非 `null`,空/无 = 那行不该画);后者 `kind: "install" \| "data"` 用资源管理器开目录**内容**(同 `appearance.revealStorage` 手感,非 `showItemInFolder` 高亮单文件),`install` 目录不在盘上抛错,`data` 先建空目录再开。**`relaunch` 真重启应用**(退出并重新启动进程)——⚠️ **仅壳 preload 注入(契约 `?` 可选)**,池侧调用前必须判存在(`window.linkdesk.shell.relaunch?.`)。与 `window.location.reload` 的区别是**池在不在**:池是独立 `WebContentsView`,壳 reload 不重建它,更新视图类插件后 reload 只会看到旧 bundle;`relaunch` 调用后本进程随即终止,**不要依赖它的返回值**(Promise 永不落地) |
|
|
88
88
|
| **appearance** | `revealStorage` 打开外观存储目录(`userData/appearance`)——主进程解析路径并 `shell.openPath` 开资源管理器**内容**(非 `showItemInFolder` 高亮单文件);目录缺省也建(打开即见存储位置,空目录合法),`openPath` 失败抛错 fail-loud。返回 `Promise<void>` |
|
|
89
|
-
| **app** | `app.getVersion` = 宿主软件版本号(`Promise<string>`,只读)——唯一运行时来源 = Electron `app.getVersion`(`package.json` 单点,02 §2.3);**主软件版本比对入口**(市场 minAppVersion
|
|
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
|
-
| 点 | 旧手写版 |
|
|
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
|
|
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)
|
|
@@ -155,11 +155,11 @@ async function list(): Promise<FileEntry[]> {
|
|
|
155
155
|
| 层 | 设备示例 | 通道 | 作者状态 |
|
|
156
156
|
|:--|:--|:--|:--|
|
|
157
157
|
| **串口系**(最大头) | USB-CAN 适配器(CH340/CP210x 虚拟串口)、GPS 模块(NMEA)、USB-TTL、便宜逻辑分析仪 | `linkdesk.serial.*`(Phase 6 通用化后) | ✅ **立即可写,零壳依赖**;多口/多插件并存成立 |
|
|
158
|
-
| **自定义 USB** | 专业逻辑分析仪(Saleae 类,自定义 USB 端点) | 未来 `usb` 通道 | ⏳
|
|
158
|
+
| **自定义 USB** | 专业逻辑分析仪(Saleae 类,自定义 USB 端点) | 未来 `usb` 通道 | ⏳ 后续版本加一条通用通道(一次性,同 serial 同构);**加完前这类设备要等** |
|
|
159
159
|
| **厂商私有 DLL** | 高端设备(只有厂商 SDK/DLL) | 原生通道 | ⚠️ 独立架构课题(渲染沙箱无 Node 权限);不在当前范围 |
|
|
160
160
|
|
|
161
161
|
**平台责任边界(作者可放心依赖):**
|
|
162
|
-
- **通道正确性 + API 稳定承诺**——平台作者负责通道(打开 → 流式读写 →
|
|
162
|
+
- **通道正确性 + API 稳定承诺**——平台作者负责通道(打开 → 流式读写 → 关闭/错误/多实例/资源回收);插件生态上线后改 API = 版本化演进(`engines` 声明),加了不违约、不加不影响存量插件。
|
|
163
163
|
- **设备协议正确性作者自持**——CAN 帧/NMEA/采样解析全归插件,壳不认识任何设备。
|
|
164
164
|
- **同一物理口仅单消费方**——OS 驱动排他(`serial-monitor` 打开的口,其他插件/标签页不能同时打开;多插件并存 = 各开各的口)。
|
|
165
165
|
|
package/docs/zh/02-/346/217/222/344/273/266/347/224/237/345/221/275/345/221/250/346/234/237.md
CHANGED
|
@@ -41,7 +41,7 @@ markLoadStarted(PENDING → LOADING)
|
|
|
41
41
|
|
|
42
42
|
### 2.1 旧格式归一化 + 角色派生
|
|
43
43
|
|
|
44
|
-
- **`normalizeManifest`(纯函数,不 mutate 只读 manifest):**
|
|
44
|
+
- **`normalizeManifest`(纯函数,不 mutate 只读 manifest):** 旧的顶层 `themes` / `languages` / `file` 字段 → 自动折成 `contributes.themes` / `contributes.languages`。新插件直接写 `contributes`,不用管这层。
|
|
45
45
|
- **角色派生:** `pluginRole` 显式声明;未声明时自动推导——`!manifest.entry && 有 contributes` → `"data"`(纯数据插件:主题/语言包,无 React 组件,跳过组件加载)。`pluginRole: "data"` 的插件不加载 JS 入口。
|
|
46
46
|
|
|
47
47
|
### 2.2 entryless 插件——没有入口也能有视图
|
|
@@ -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
|
|
151
|
+
**启动即注册元数据:** 启动 `initPluginLoader` 发现全部插件 → 壳注册 manifest/contributes(命令显示名/菜单/配置 schema/图标栏元数据全可见)——**不 import 任何插件 JS**(壳 bundle 零插件源码)。
|
|
152
152
|
|
|
153
153
|
**JS 加载 = 池的两种按需轨(插件作者契约):**
|
|
154
154
|
|
|
@@ -261,13 +261,13 @@ unloadPlugin(pluginId, reason, displayName)
|
|
|
261
261
|
|
|
262
262
|
## 九、生命周期操作——安装 / 启用 / 禁用 / 卸载 / 重装
|
|
263
263
|
|
|
264
|
-
### 9.1 安装 `installPlugin(sourcePath)`(
|
|
264
|
+
### 9.1 安装 `installPlugin(sourcePath)`(zip 分发路由)
|
|
265
265
|
|
|
266
|
-
`sourcePath` 三态自适应(`isPackageSource`):目录路径 / `http(s)://` URL / 磁盘 `.linkdesk-plugin` zip。**分发主路 = zip / URL 包源**(
|
|
266
|
+
`sourcePath` 三态自适应(`isPackageSource`):目录路径 / `http(s)://` URL / 磁盘 `.linkdesk-plugin` zip。**分发主路 = zip / URL 包源**(zip 单文件);目录源仅 dev 便捷用。
|
|
267
267
|
|
|
268
268
|
```
|
|
269
269
|
validating → 包源:主进程 plugins:download / plugins:extract → 解压前校验
|
|
270
|
-
(zip 顶层 plugin.json 定位 + JSONC
|
|
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
|
|
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
|
|
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
|
-
| 标签页右键出现「在悬浮面板中打开」 |
|
|
669
|
-
| 打开后面板内三动作(在主窗口中打开 / 最大化 / 关闭) |
|
|
670
|
-
| `linkdesk.panel.revealFloating(viewId)` 可编程弹面板 |
|
|
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)。
|
package/docs/zh/04-/346/217/222/344/273/266/345/210/206/345/217/221/346/240/274/345/274/217.md
CHANGED
|
@@ -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
|
|
45
|
+
- zip 顶层定位 `plugin.json`(basename 匹配,容忍单层 wrapper 目录)——JSONC 解析
|
|
46
46
|
- `pluginId` 裁决:manifest 优先、zip 文件基名兜底,双源互验;必须过安全字符集(无路径分隔符/相对段)
|
|
47
47
|
- zip-slip 防护——条目路径拒绝逃逸解压目标
|
|
48
48
|
- 目标已装同版本 → 跳过(用户安装删源);异版本 → 不动(升级是更新流职责,boot 不覆盖)
|
|
@@ -51,7 +51,7 @@ my-plugin/
|
|
|
51
51
|
|
|
52
52
|
| 代码根 | 位置 | 形态 | HMR | 谁住这里 |
|
|
53
53
|
|------|------|------|:--:|------|
|
|
54
|
-
| **插件自己的仓** | GitHub `Encaron/linkdesk-plugin-<id>`(本地克隆落在容器目录 `E:\linkdesk-plugins\official\<id>\`) | 源码 + SDK build(`npm run build` → `<id>.linkdesk-plugin`) | ✅(`linkdesk-plugin-sdk dev`) | **18
|
|
54
|
+
| **插件自己的仓** | GitHub `Encaron/linkdesk-plugin-<id>`(本地克隆落在容器目录 `E:\linkdesk-plugins\official\<id>\`) | 源码 + SDK build(`npm run build` → `<id>.linkdesk-plugin`) | ✅(`linkdesk-plugin-sdk dev`) | **18 只发货插件全部**——一只一个仓,源码真相源只此一处 |
|
|
55
55
|
| **壳仓夹具** | `<壳仓>/plugins/<id>/`(`env.appPluginsDir`) | 源码 + Vite 即时编译 | ✅(`npm run dev` 热更) | 只剩两只**开发夹具**:`panel-demo` / `floating-panel-demo`(不发货、不进 zip) |
|
|
56
56
|
| **安装态** | `{userData}/plugins/<id>/` | zip 解出的预构建 bundle | ❌(改包需重 build + 重装/重物化) | 用户机器上所有已装插件 |
|
|
57
57
|
|
|
@@ -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
|
|
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
|
|
|
@@ -163,7 +163,7 @@ my-plugin/
|
|
|
163
163
|
| `core: true` 插件不可卸(防误删旗标) | `builtin/` 内置扩展 |
|
|
164
164
|
| 卸载 = 删目录 + 销账(真删);源码树 app 插件才移 `.disabled/` | 卸载 = 删文件(不可恢复) |
|
|
165
165
|
| `env.get(id).pluginDataDir` | `ExtensionContext.storagePath` |
|
|
166
|
-
| `core: true` 插件发货 = `bundled-plugins/*.linkdesk-plugin`(**首启种子**:boot 只补缺失、**永不刷新已装副本**;但**箱子本身会随壳版本刷新**——打包前由 `sync:bundled`
|
|
166
|
+
| `core: true` 插件发货 = `bundled-plugins/*.linkdesk-plugin`(**首启种子**:boot 只补缺失、**永不刷新已装副本**;但**箱子本身会随壳版本刷新**——打包前由 `sync:bundled` 拉各插件「最新已发布版」) | 随应用更新(安装包内置) |
|
|
167
167
|
| `requires` **运行期**依赖编排([02 §四](02-插件生命周期.md)) | `extensionDependencies` 安装期解析 |
|
|
168
168
|
|
|
169
169
|
---
|
package/docs/zh/05-/346/217/222/344/273/266UI/345/206/231/346/263/225/350/247/204/347/272/246.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# 插件 UI 写法规约
|
|
2
2
|
|
|
3
3
|
> **一句话:核心已提供标准组件和注册表——不要手写轮子。手写 = 风格不一致 + 以后归一化时要拆。**
|
|
4
|
-
>
|
|
4
|
+
> 写插件前扫一眼,避免同类返工。
|
|
5
5
|
> **2026-09-06 与实现对齐核对**(对账):塌平单根(无 plugins/{builtin,user})· 共享控件走 @linkdesk/ui · 分发 = .linkdesk-plugin zip。本页对应机制引用已清。
|
|
6
6
|
|
|
7
7
|
---
|
|
@@ -36,7 +36,7 @@ window.linkdesk.menu.registerItems("editorContext", "myPlugin", [
|
|
|
36
36
|
<ContextMenu menuId="editorContext" />
|
|
37
37
|
```
|
|
38
38
|
|
|
39
|
-
**理由:** `<ContextMenu>` 自带 backdrop + 四种失焦(Escape / click backdrop / window blur / 选项 click)+ 键盘导航 + when
|
|
39
|
+
**理由:** `<ContextMenu>` 自带 backdrop + 四种失焦(Escape / click backdrop / window blur / 选项 click)+ 键盘导航 + when 条件过滤。手写做不到这四种失焦。
|
|
40
40
|
|
|
41
41
|
**MenuId 是开放 string(`src/core/registry/commands/MenuRegistry.ts` `export type MenuId = string`)——插件声明任意字符串即契约,无需壳加代码。** 壳内置注册点(MENU_SLOTS 常量表):
|
|
42
42
|
|
|
@@ -75,7 +75,7 @@ return createPortal(
|
|
|
75
75
|
);
|
|
76
76
|
```
|
|
77
77
|
|
|
78
|
-
**理由:** keep-alive 架构下非活跃标签页 `display: none`,子元素用 `position: fixed`
|
|
78
|
+
**理由:** keep-alive 架构下非活跃标签页 `display: none`,子元素用 `position: fixed` 也看不见。render 到 `document.body` 才能突破组件树限制。
|
|
79
79
|
|
|
80
80
|
---
|
|
81
81
|
|
|
@@ -317,7 +317,7 @@ const file = await window.linkdesk.dialog.openFile({
|
|
|
317
317
|
});
|
|
318
318
|
```
|
|
319
319
|
|
|
320
|
-
**理由:** 三者都是池内宿主统一渲染(QuickPickHost / **铃铛宽通知面板** / DialogHost)——样式与壳一致、随主题与字号缩放走。手写浮层 = 风格不一致 + keep-alive 下 `position: fixed`
|
|
320
|
+
**理由:** 三者都是池内宿主统一渲染(QuickPickHost / **铃铛宽通知面板** / DialogHost)——样式与壳一致、随主题与字号缩放走。手写浮层 = 风格不一致 + keep-alive 下 `position: fixed` 失效。完整签名见 `contracts/linkdesk.d.ts`。
|
|
321
321
|
|
|
322
322
|
> ⚠️ **通知不是「自动消失的浮卡」**(通知面归一 +更正):右下角窄 toast 链路已整删,**唯一通知面 = 状态栏铃铛宽面板**。作者要知道的三件事:
|
|
323
323
|
> 1. **通知不弹卡、不抢焦点、不挡操作**——它进铃铛(未读计数 +1),用户点开才看见。别把通知当「必须被看见」的通道:要用户当场决定 → 用 `dialog.confirm`(模态、抢焦点)。
|
|
@@ -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
|
|
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
|
|
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
|
-
|
|
551
|
-
|
|
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
|
|
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` |
|
|
@@ -111,10 +111,10 @@ my-plugin/
|
|
|
111
111
|
| `contributes.configuration` | — | 注册到 ConfigurationRegistry → Settings Editor 自动渲染 |
|
|
112
112
|
| `contributes.menus` | — | 注册到 MenuService → 右键菜单动态生成 |
|
|
113
113
|
| `contributes.keybindings` | — | 注册到 KeybindingRegistry → 全局键盘监听 |
|
|
114
|
-
| `contributes.themes` | theme
|
|
115
|
-
| `contributes.languages` | language
|
|
116
|
-
| `contributes.fileAssociations` | —
|
|
117
|
-
| `contributes.floatingPanel` | — | 声明视图可在壳内悬浮面板显示——viewId
|
|
114
|
+
| `contributes.themes` | theme | 注册到 ThemeRegistry → 主题浏览器 |
|
|
115
|
+
| `contributes.languages` | language | 注册到 LanguageRegistry |
|
|
116
|
+
| `contributes.fileAssociations` | — | 注册到 FileAssociationService → 双击文件自动打开 |
|
|
117
|
+
| `contributes.floatingPanel` | — | 声明视图可在壳内悬浮面板显示——viewId 引用已注册视图;未声明则无「在悬浮面板中打开」右键 |
|
|
118
118
|
|
|
119
119
|
**插件可同时声明多种贡献。** 比如一个视图插件可以有 `entry` + `sidebar` + `statusBar` + `contributes.configuration` + `contributes.commands`——全部独立注册,互不影响。
|
|
120
120
|
|
|
@@ -255,7 +255,7 @@ my-plugin/
|
|
|
255
255
|
|
|
256
256
|
说明与更新日志**以文件为准**——插件根目录的 `README.md` / `CHANGELOG.md`(位置、格式、与详情页的对应关系见 [09-插件目录规范](09-插件目录规范.md))。
|
|
257
257
|
|
|
258
|
-
|
|
258
|
+
这两个字段曾存在,但**从无读取方**(读取方按**固定文件名**读包内文件,不看任何声明字段),**2026-09-11 已删除**。
|
|
259
259
|
|
|
260
260
|
> **写进 `plugin.json` 不会生效,只会被忽略**(顶层是宽松校验,写了不报错——所以它骗人)。**若你从旧教程 / 旧提交抄到了这两个字段 → 删掉,改写成文件。**
|
|
261
261
|
|
|
@@ -266,7 +266,7 @@ my-plugin/
|
|
|
266
266
|
**对标 VS Code `extensionDependencies`**:同族机制,本字段是其归一化收口(见下「命名边界」)。
|
|
267
267
|
|
|
268
268
|
**语义:**
|
|
269
|
-
- 值 = 依赖插件的 `pluginId`
|
|
269
|
+
- 值 = 依赖插件的 `pluginId` 数组(无版本约束——激活顺序不承载版本语义,版本匹配属插件市场范畴)
|
|
270
270
|
- loader 按拓扑序加载:`requires` 里的插件先激活,本插件再激活——扫描顺序不再影响激活顺序
|
|
271
271
|
- 依赖缺失 → 本插件挂起(PENDING),依赖装好/启用后自动加载
|
|
272
272
|
- 依赖被卸载/禁用 → 本插件连带卸载(消费者优先,逆拓扑序)
|
|
@@ -177,7 +177,7 @@ const off = await window.linkdesk.filesystem.watch('/workspace', (e) => {
|
|
|
177
177
|
|
|
178
178
|
---
|
|
179
179
|
|
|
180
|
-
##
|
|
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
|
-
|
|
|
189
|
-
|
|
|
190
|
-
|
|
|
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
|
|
package/docs/zh/09-/346/217/222/344/273/266/347/233/256/345/275/225/350/247/204/350/214/203.md
CHANGED
|
@@ -107,7 +107,7 @@ SDK `publish` 要从它**切段**填目录条目,所以**段标题格式有约
|
|
|
107
107
|
2. **壳仓 `bundled-plugins/<id>.linkdesk-plugin` 的语义 = 出厂发货用的种子快照**,其版本由 `bundled-plugins.lock.json` 记账(第 7.4 轮产出)。它**不是源码的第二份拷贝**——源码改了必须回插件仓改,改完走发布链路刷新种子。
|
|
108
108
|
3. **从源码到用户桌面的链路**:插件仓 → `npm run build` → `<id>.linkdesk-plugin`(zip)→ GitHub Release asset → catalog 条目 → 用户安装。**没有一步经过壳仓。**
|
|
109
109
|
4. **插件身份(id)永不可变**;显示名(`name`)可改;仓库名可改——三分规则与全部命名判据 → [16-命名规范](16-命名规范.md)。
|
|
110
|
-
5. **插件内有且只有一处版本号真源 = `plugin.json.version`**。`package.json.version`
|
|
110
|
+
5. **插件内有且只有一处版本号真源 = `plugin.json.version`**。`package.json.version` 不是真源,但必须与它相等(版本号「四处同源」——见 [16-命名规范 §5.1](16-命名规范.md))。
|
|
111
111
|
|
|
112
112
|
**与 `publish` 实现的对账**(规范不许与工具相反):发布目标仓库 = 工程 git remote `origin`(`packages/plugin-sdk/src/publish.ts` 的 `getCurrentRepoRemote`,非 git / 无 origin 直接报错);catalog 写到**仓库根 `marketplace.json`**(Contents API 读改写);`readmeUrl` / `versions[].changelog` 由 publish 从工程根 `README.md` / `CHANGELOG.md` 自动填写。
|
|
113
113
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# README 说明区媒体契约
|
|
2
2
|
|
|
3
|
-
> 2026-09-09
|
|
3
|
+
> 2026-09-09 ·文档化(四种形态全部实现后补上的作者契约)。**写给第三方插件作者。**
|
|
4
4
|
> 这份文档回答一个问题:**你的 README 在 LinkDesk 软件里会被插件详情页展示——里面想放图 / 动图 / 演示视频,怎么写才对、有什么规矩。** 对标 VS Code 更新页 / 扩展 README 的开放展示画布。
|
|
5
5
|
> 性质 = **接口契约**——只定义「作者怎么写得对 + 会显示成什么样」,不写实现代码(实现面 = 壳共享 MarkdownView + 市场 DetailView)。作者不需要知道 App 怎么渲染,把下面几条写对即可。
|
|
6
6
|
|
|
@@ -35,16 +35,16 @@ E:\linkdesk-plugins\
|
|
|
35
35
|
|
|
36
36
|
---
|
|
37
37
|
|
|
38
|
-
##
|
|
38
|
+
## 三、仓库名完全自由
|
|
39
39
|
|
|
40
40
|
**仓库名不强制任何前缀,第三方零约束。** 这是拍过板的:作者给自己的插件(仓库)取名是正当权利,不能定死。
|
|
41
41
|
|
|
42
|
-
- **建议但非强制的惯例**:官方插件仓统一 `linkdesk-plugin-<id
|
|
42
|
+
- **建议但非强制的惯例**:官方插件仓统一 `linkdesk-plugin-<id>`(条文住 [插件源码外移层/09-命名规范.md §五](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md)——只此一处维护);第三方随意。
|
|
43
43
|
- **改仓库名的代价**:已发布 catalog 条目里的 `downloadUrl` / `readmeUrl` 内嵌 `owner/repo`,**改名会断已发布插件的下载与 README 链接**(源码本身不受影响)。改名后重发一版新条目即可自愈,但旧版本条目仍指旧链——**能不改就不改,要改趁早**。
|
|
44
44
|
|
|
45
45
|
---
|
|
46
46
|
|
|
47
|
-
## 四、身份 vs 显示名 vs
|
|
47
|
+
## 四、身份 vs 显示名 vs 仓库名
|
|
48
48
|
|
|
49
49
|
三个「名字」互不相干,混为一谈是一切命名问题的根源:
|
|
50
50
|
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# 命名规范——七种名字,一条身份
|
|
2
2
|
|
|
3
3
|
> 2026-09-14 ·。**读者 = 插件作者。** 读完能回答四问:**id 怎么起?能不能改?显示名怎么改?仓库叫什么?**
|
|
4
|
-
>
|
|
4
|
+
> 决策论证与 VS Code 实测依据住 [插件源码外移层/09-命名规范.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md)——本篇是作者面落点,两处**只维护一处**:改规则先改本篇并回指,别造第二份。
|
|
5
5
|
|
|
6
6
|
---
|
|
7
7
|
|