@linkdesk/plugin-docs 0.1.34 → 0.1.36
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 +38 -3
- package/docs/03-contributes-spec.md +21 -3
- package/docs/04-distribution-format.md +3 -3
- package/docs/05-ui-conventions.md +1 -1
- package/docs/12-readme-media-contract.md +1 -1
- package/docs/15-multi-repo-and-local-workspace.md +2 -2
- package/docs/16-naming-conventions.md +1 -1
- package/docs/18-cross-region-wiring.md +1 -1
- package/docs/zh/01-/346/217/222/344/273/266API/345/245/221/347/272/246.md +38 -3
- package/docs/zh/03-/346/217/222/344/273/266contributes/350/247/204/350/214/203.md +22 -4
- package/docs/zh/04-/346/217/222/344/273/266/345/210/206/345/217/221/346/240/274/345/274/217.md +3 -3
- package/docs/zh/05-/346/217/222/344/273/266UI/345/206/231/346/263/225/350/247/204/347/272/246.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 +2 -2
- package/docs/zh/16-/345/221/275/345/220/215/350/247/204/350/214/203.md +1 -1
- package/docs/zh/18-/345/214/272/345/237/237/351/227/264/344/272/222/345/212/250.md +1 -1
- package/docs/zh/plugin.schema.json +20 -1
- package/package.json +2 -2
|
@@ -29,11 +29,13 @@ A few key points (a summary of Matrix §2; the matrix wins on details):
|
|
|
29
29
|
|
|
30
30
|
| Fact | Explanation |
|
|
31
31
|
|------|------|
|
|
32
|
-
| **The contract has
|
|
32
|
+
| **The contract has 46 namespaces** | The pool injects 45 (the only missing one is `bridge`); the shell injects 25; mock injects 13 — **the live readings of the `check-namespace-matrix` gate are authoritative** (this row is mechanically reconciled by it; ⛔ do not copy the comment in `surfaces.ts` — that one drifts too) |
|
|
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** — the older version's ❌ shell-only marking for those surfaces was wrong |
|
|
35
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
|
+
> **That table only says which surfaces are callable — not what can be read.** Read surfaces (reading "what is open right now / what is waiting on the user") get their own section — see §3.3: **an API with an operation surface but no read surface is half-finished** (you can open a tab, yet you cannot read which tabs are open).
|
|
38
|
+
|
|
37
39
|
---
|
|
38
40
|
|
|
39
41
|
## 3. Complete API Definition → Pointer
|
|
@@ -42,7 +44,7 @@ A few key points (a summary of Matrix §2; the matrix wins on details):
|
|
|
42
44
|
|
|
43
45
|
**Every method signature, parameter, return value, and payload type for `window.linkdesk.*` = [contracts/linkdesk.d.ts](https://github.com/Encaron/linkdesk/blob/electron/contracts/linkdesk.d.ts)** (auto-generated; do not hand-edit).
|
|
44
46
|
|
|
45
|
-
- **Generation sources:** `src/core/api/linkdesk-api.ts` + `linkdesk-api/` (
|
|
47
|
+
- **Generation sources:** `src/core/api/linkdesk-api.ts` + `linkdesk-api/` (15 domain interfaces) + `src/core/types/ipc/*` + `src/core/types/pool/*` (wire payload types)
|
|
46
48
|
- **Generator:** `scripts/generate-contract.mjs` (Route C — the contract type file is the source; pure types bundled into a single file)
|
|
47
49
|
- **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
50
|
- **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-命名空间--四面覆盖矩阵)
|
|
@@ -101,7 +103,40 @@ async function list(): Promise<FileEntry[]> {
|
|
|
101
103
|
| `workspace:changed` | `{ rootPath }` | The user opens/switches a folder |
|
|
102
104
|
| `plugin:installJobs` | `{ jobs: InstallJob[] }` (**a full snapshot, not a delta**) | The shell-side install/uninstall queue changes (added: stage and percent; added: `kind`·`cancellable`). `InstallJob` = `{ jobId, pluginId, origin: "user"\|"dependency", kind: "install"\|"uninstall", cancellable: boolean, displayName, state: "queued"\|"running"\|"settled", terminal?: "success"\|"failed"\|"parked", error?, stage?, percent?, message? }` — **every broadcast is the whole table**, so consumers **replace their local mirror outright** instead of merging deltas. **Late subscribers get the latest full table**: the pool preload caches one at the top level and replays it synchronously on subscribe (a remounted view never gets stuck on an old snapshot). ⚠️ This is a **public event surface**, not a marketplace-private pipe — any plugin can subscribe and build its own progress UI; ⚠️ **`stage`/`percent`/`message`/`kind`/`cancellable` are additive-only fields**, so older consumers can simply ignore them. ⚠️ `origin: "dependency"` = a dependency some plugin dragged in, nested inside the row that initiated it (`origin: "user"`) |
|
|
103
105
|
|
|
104
|
-
### 3.3
|
|
106
|
+
### 3.3 Read Surfaces — the machine-readable outlet for "what is open / what is waiting"
|
|
107
|
+
|
|
108
|
+
§3.1/§3.2 describe the **operation surfaces** (what a plugin can do); this section describes the **read surfaces** (what a plugin/AI can **read**).
|
|
109
|
+
|
|
110
|
+
**Why it gets its own section:** a complete operation surface does not add up to automation. If you can open tabs and raise notifications but cannot read "which tabs are open / what is stacked in the notification panel / whether a dialog is waiting on the user", an external driver (AI, scripts, remote control) can only guess — and **a guessed state that disagrees with the screen becomes a false source of truth**, which is worse than having no read surface at all.
|
|
111
|
+
|
|
112
|
+
| Read surface | Method | What you get |
|
|
113
|
+
|:--|:--|:--|
|
|
114
|
+
| **Notifications** | `notifications.list()` | The state of the bell's wide notification panel — count, unread count, each entry's text and buttons, wake and persistence criteria. The return value **is the panel's own DTO** (`NotifLayout`, produced by the same `buildNotif` as `pool.onLayout`'s `statusBar.notif`) |
|
|
115
|
+
| **Notification changes** | `notifications.subscribe(cb)` | A "**it changed just now**" signal (added/updated/dismissed/acknowledged, panel opened/closed). 🔴 **The callback carries no payload** — call `list()` again for the answer (the same "state push + pull on demand" split as `events.on`) |
|
|
116
|
+
| **Tabs** | `tabs.list()` | The tab listing for **all** windows (`TabsSnapshot`: `windowId`/`mode`/`ready`/`activeGroupId`/`root`/`groups`, each group carrying `activeTabId`). Produced by the **same `serializeGroups`** as the layout tree pushed to the pool ⇒ the listing's `label`/`icon` necessarily match the tab drawn on screen |
|
|
117
|
+
| **Layout** | `pool.getLayout()` | The snapshot body of the **most recent** `onLayout` in this window (tree `root` + groups `groups`). No push has arrived yet → `null` (⛔ never invent an empty layout) |
|
|
118
|
+
| **Dialogs in flight** | `dialogHost.pending()` | The confirm/alert currently on screen waiting for the user (`options` verbatim + `kind` + button labels + rich-content view identity). An empty array = nothing is open right now |
|
|
119
|
+
| **Command metadata** | `commands.getCommands()` | Every command's `id`/`title`/`category`/**`description`**/**`params`** (the latter two exist since M1; `params[i]` corresponds positionally to the handler's argument) — the command list itself is a structure you can **feed straight to a large model as a tool list (function calling)** |
|
|
120
|
+
|
|
121
|
+
> Method signatures follow [contracts/linkdesk.d.ts](https://github.com/Encaron/linkdesk/blob/electron/contracts/linkdesk.d.ts); the table above only answers "which ones exist and what they read".
|
|
122
|
+
|
|
123
|
+
**Three rules for read surfaces (for implementers and consumers alike):**
|
|
124
|
+
|
|
125
|
+
1. **A read surface ≡ the screen, one single ruler.** It must return **the DTO that the screen is drawn from**, ⛔ never a separately computed summary — two rulers inevitably disagree: if the grouping/unread count/text you read differs from what is painted, the read surface has become a false source of truth.
|
|
126
|
+
2. **Signals and answers are separate.** A subscription only answers "**it changed**" (no payload); answers always come from `list()`. Put data in the signal and someone will stop asking the authority, and a second ruler grows back.
|
|
127
|
+
3. **Text is already resolved — display it as-is.** Text fields such as `bellTitle`/`panelTitle`/group labels/`timeLabel` are **already resolved by the shell with `t()` in the current language** (the display-text rule) — display them verbatim; do not run i18n again.
|
|
128
|
+
|
|
129
|
+
**Boundaries (all of them "honestly report not knowing", not defects):**
|
|
130
|
+
|
|
131
|
+
- In a **detached window**, `pool.getLayout()` returns a strategy subset (`WINDOW_MODE_STRATEGIES`: `detached` = `titleBar`+`groups`; `drift` = `titleBar`+`panel`) — `statusBar`/`sidebar`/`iconBar` do not exist there. To see the whole picture across windows, use `tabs.list()` (ask the shell).
|
|
132
|
+
- `tabs.list()` returns **all windows in one shot**: the shell has no "current window" source of truth ⇒ filter by `windowId` yourself (⛔ do not expect the shell to guess which window you mean).
|
|
133
|
+
- `notifications.list()` asks the **shell** via `plugins:call` (the shell holds the full state) — so it **also works in a detached window** (reading this window's layout subset would answer "no notifications").
|
|
134
|
+
- In `dialogHost.pending()`, `buttons` is **in declaration order** (`[confirm, cancel]`), **not the left/right positions on screen** (measured: the screen paints cancel on the left and confirm on the right). To act, call `dialogHost.confirm()`/`cancel()` by index, ⛔ never by visual position.
|
|
135
|
+
- **Pool-side only, not implemented in the shell:** `tabs.list()` / `pool.getLayout()` **do not exist** in `preload-shell` (the shell already holds that state in hand and will not ask itself over IPC). Shell views that need them should go through the shell's own services.
|
|
136
|
+
|
|
137
|
+
**Adding a read surface later:** the criterion is one sentence — **"if it is on screen, the machine must be able to read it."** Before adding one, ask three questions: ① does it return the DTO the screen is drawn from? ② does it spawn a second piece of state / a second ruler? ③ does a consumer have a workaround that does not need it (if not ⇒ it is a gap, not an optional extra)?
|
|
138
|
+
|
|
139
|
+
### 3.4 Differences from the Old Hand-Written Version (note for readers)
|
|
105
140
|
|
|
106
141
|
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
142
|
|
|
@@ -76,7 +76,12 @@
|
|
|
76
76
|
"id": "cad.importDxf",
|
|
77
77
|
"title": "Import DXF…",
|
|
78
78
|
"category": "CAD",
|
|
79
|
-
"when": "activeEditor == 'cad'"
|
|
79
|
+
"when": "activeEditor == 'cad'",
|
|
80
|
+
"description": "Import CAD geometry from a DXF file into the current project",
|
|
81
|
+
"params": [
|
|
82
|
+
{ "name": "layerFilter", "type": "string", "description": "Import only this layer (omit for all)" },
|
|
83
|
+
{ "name": "explodeBlocks", "type": "boolean", "description": "Explode blocks into primitive entities" }
|
|
84
|
+
]
|
|
80
85
|
}
|
|
81
86
|
]
|
|
82
87
|
}
|
|
@@ -89,6 +94,19 @@
|
|
|
89
94
|
| `title` | ✅ | display name (an i18n key — the original Chinese text) |
|
|
90
95
|
| `category` | ❌ | command palette grouping — "CAD" / "Terminal" / "File" |
|
|
91
96
|
| `when` | ❌ | context key when condition. Without `when` the command is visible in any context |
|
|
97
|
+
| `description` | ❌ | **what this command does** — the intent from the user/AI perspective (an i18n key, same rule as `title`). ⛔ Do not restate the `id`. Omitted = no description |
|
|
98
|
+
| `params` | ❌ | **parameter structure** — an array corresponding positionally to the handler's arguments. Omitted = a command without parameters |
|
|
99
|
+
|
|
100
|
+
**`params` item fields (positionally matching the handler's arguments):**
|
|
101
|
+
|
|
102
|
+
| Field | Required | Description |
|
|
103
|
+
|------|:--:|------|
|
|
104
|
+
| `name` | ✅ | parameter name — **use the handler's own parameter name** (e.g. `tabId` / `settingKey` / `groupId`) |
|
|
105
|
+
| `type` | ✅ | one of four values: `"string"` \| `"number"` \| `"boolean"` \| `"object"` (`object` = a structured payload; document its fields in `description`) |
|
|
106
|
+
| `required` | ❌ | whether the parameter is required. Defaults to `false` (optional) |
|
|
107
|
+
| `description` | ❌ | one sentence on what this parameter is (omit when the name speaks for itself) |
|
|
108
|
+
|
|
109
|
+
> **`description` / `params` travel through `getCommands()` into the contract** (`LinkDeskCommand.description` / `LinkDeskCommand.params`) — consumers (the command palette, automation, AI) can build `executeCommand(id, ...params)` straight from `params` **instead of reading source code to guess the arguments**. The same optional fields exist on **runtime registration** (`registerCommand(id, handler, meta)`); the two are synonymous (declaring them once is enough — a runtime registration usually does not repeat them).
|
|
92
110
|
|
|
93
111
|
**Declaring registers metadata (a placeholder):** `contributes.commands` only registers command metadata (id/title/category/when); **the real handler is registered on the pool side** (pool-side `_poolCommands` wins). A command whose handler was never registered is a no-op when invoked (with a diagnostic warn).
|
|
94
112
|
|
|
@@ -473,7 +491,7 @@ Your translation file is **one flat layer of keys**, and everyone writes into th
|
|
|
473
491
|
|
|
474
492
|
🔴 **Why this is advice and not a requirement**: **an i18n key may legitimately live in the app-level dictionary**. The official `settings` plugin has 254 `t()` call sites and **not a single key of its own in its repo** — they all live in `lang-defaults`' `zh.json` / `en.json`. Inside your plugin repo there is only your own `i18n/*.json` — **you cannot see the shell's dictionary, nor any other plugin** — so "your key collided with someone" is **never decidable from your own repo**. Making it a blocker means guaranteed false positives, and false positives invalidate the rules that should really block. ⇒ **It is a yellow light, not a red one.**
|
|
475
493
|
|
|
476
|
-
**How much overlap actually exists
|
|
494
|
+
**How much overlap actually exists** (told plainly, not exaggerated — the counts below are a **measurement**, taken when the roster was 18 official plugins, not a live figure): those plugins declared **414 keys**, **65 of which overlap** the `lang-defaults` keys, and **3 of those already have divergent translations** — for example `命令`, where the shell says `Command` while `serial-monitor` says `Commands`. **When both are written into the same dictionary, which one the user actually sees depends on plugin load order.**
|
|
477
495
|
|
|
478
496
|
⚠️ **Runtime behaviour**: when an overwrite happens the shell emits a `console.warn` naming the **key + language + writer**:
|
|
479
497
|
|
|
@@ -781,7 +799,7 @@ useEffect(() => {
|
|
|
781
799
|
|
|
782
800
|
**Four boundaries**: ① it only governs the **first open** — an existing tab is still focused and an already-open panel still toggles shut; changing the form afterwards keeps using the two old paths ("Open in main window" / "Open in Floating Panel"); ② `formKey` and `defaultForm` are **mutually exclusive** (both declared ⇒ schema validation fails — one form from two sources); ③ a typo'd `formKey` / a key that was never registered ⇒ falls back to `defaultForm` (neither = previous behaviour) plus one warning — it **never fails silently**; ④ declaring `"defaultForm": "tab"` on a plugin with no tab form (`appearsIn.tabBar` + `entry`) falls back to the floating panel rather than silently doing nothing.
|
|
783
801
|
|
|
784
|
-
**
|
|
802
|
+
**Currently the only declarer = settings** (`core.openSettings`, Ctrl+, opens the panel, and `settings.openForm` lets the user change it inside the "Settings plugin" group). The mechanism itself is generic and is validated end-to-end (replacement + the right-click return path + unload no-op) — nothing stops you from becoming the second declarer.
|
|
785
803
|
|
|
786
804
|
---
|
|
787
805
|
|
|
@@ -51,8 +51,8 @@ my-plugin/
|
|
|
51
51
|
|
|
52
52
|
| Source root | Location | Form | HMR | Who lives here |
|
|
53
53
|
|------|------|------|:--:|------|
|
|
54
|
-
| **The plugin's own repo** | GitHub `Encaron/linkdesk-plugin-<id>` (local clones land under `E:\linkdesk-plugins\official\<id>\`) | source + SDK build (`npm run build` → `<id>.linkdesk-plugin`) | ✅ (`linkdesk-plugin-sdk dev`) | **
|
|
55
|
-
| **Shell repo fixtures** | `<shell repo>/plugins/<id>/` (`env.appPluginsDir`) | source + Vite on-the-fly compilation | ✅ (`npm run dev` hot reload) | only the
|
|
54
|
+
| **The plugin's own repo** | GitHub `Encaron/linkdesk-plugin-<id>` (local clones land under `E:\linkdesk-plugins\official\<id>\`) | source + SDK build (`npm run build` → `<id>.linkdesk-plugin`) | ✅ (`linkdesk-plugin-sdk dev`) | **every shipped plugin** (16 today)—one repo each, and the only source of truth for their source |
|
|
55
|
+
| **Shell repo fixtures** | `<shell repo>/plugins/<id>/` (`env.appPluginsDir`) | source + Vite on-the-fly compilation | ✅ (`npm run dev` hot reload) | only the remaining **dev fixture**: `panel-demo` (not shipped, not in the zip) |
|
|
56
56
|
| **Installed state** | `{userData}/plugins/<id>/` | pre-built bundle unpacked from the zip | ❌ (changing the package means rebuild + reinstall/rematerialize) | every plugin installed on the user's machine |
|
|
57
57
|
|
|
58
58
|
> 🔴 **Why a shipped plugin's source can't be kept in both places**: as soon as the shell repo and the plugin repo each hold a copy, changing one leaves the other stale, and **no gate can detect the divergence** (the content-fingerprint gate only covers zip contents, not source) ⇒ the source of truth must be unique. What the shell repo keeps are **artifacts** (`bundled-plugins/*.linkdesk-plugin`) and **documentation archives**, not source.
|
|
@@ -60,7 +60,7 @@ my-plugin/
|
|
|
60
60
|
> **Real-device loop exception (author dev):** in the installed state, changing a package requires "rebuild + reinstall/rematerialize", which in **every author real-device verification** scenario means the one-shot-cycle pain of WPF v2. The real-device loop automates it—an SDK rebuild in seconds + a **direct write** into `{userData}/plugins/<id>` (same-disk overwrite semantics, effective on reload) becomes the cycle, and the author still never touches the shell. The distribution zip's "don't modify your own bundle" discipline is unchanged (that is the package for end users). Design archive → [author real-device debugging loop](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/04-作者真机调试环.md).
|
|
61
61
|
|
|
62
62
|
> **Uninstall semantics (after 2026-09-05):** uninstalling an installed plugin = **delete the `{userData}/plugins/<id>/` directory + settle the ledger entry** (no longer a move into `.disabled/`); only app plugins uninstalled from a repo source tree get moved to the `plugins/.disabled/` graveyard (recoverable via reinstall). The sole owner of the ledger `installed-plugins.json` = the renderer-side PluginInstallService; boot only reads its `removed` marker to avoid accidental restoration.
|
|
63
|
-
> 🔵 **Cross-check conclusion (does the `.disabled/` graveyard still have consumers):** **the mechanism remains, with no object at present**. The consumers are alive—`src/pluginLoader/loader.ts` reads it (`reinstallPlugin` / the uninstall toast's "undo" / cross-restart orphan cleanup all treat `env.appPluginsDir/.disabled` as the single authoritative surface). But `env.appPluginsDir` = the shell repo's `plugins/`, and the
|
|
63
|
+
> 🔵 **Cross-check conclusion (does the `.disabled/` graveyard still have consumers):** **the mechanism remains, with no object at present**. The consumers are alive—`src/pluginLoader/loader.ts` reads it (`reinstallPlugin` / the uninstall toast's "undo" / cross-restart orphan cleanup all treat `env.appPluginsDir/.disabled` as the single authoritative surface). But `env.appPluginsDir` = the shell repo's `plugins/`, and the shipped plugins have moved out ⇒ only the one fixture remains there, and **there is no longer any "app plugin uninstalled from a repo source tree"**. ⇒ The mechanism is **retained** (it is part of the in-repo plugin dev path; removing it would touch three places in the loader plus the main-process scan surface, so risk outweighs benefit), but **don't** treat it as a revocable-uninstall channel for shipped plugins anymore.
|
|
64
64
|
|
|
65
65
|
---
|
|
66
66
|
|
|
@@ -757,7 +757,7 @@ button { border: none; }
|
|
|
757
757
|
|
|
758
758
|
**Why it is worth remembering**: the host itself has **17** such "anchorless selectors" (`*` resets / `html`·`body` / `[data-theme]` / `*:focus-visible` / the scrollbar family / `input[type="number"]`·`select`)—they are a **deliberate shared baseline** that plugins rely on (and may override). Precisely because they exist, **your anchorless selector will hit them**: write `button { }` and the host's buttons plus every other plugin's buttons change with it.
|
|
759
759
|
|
|
760
|
-
**Migration**: **zero instances today**—a full re-check of the
|
|
760
|
+
**Migration**: **zero instances today**—a full re-check of the official plugins plus the in-repo fixture (the "anchorless S2 / cross-party S3" columns of `npm run audit:plugin-prefix -- --all`) is **0** ⇒ **you have nothing to change**; this rule is **preventive**.
|
|
761
761
|
|
|
762
762
|
> 🔧 **Maintainer note (authors may skip)**: the rule text (R0 scope / R1 host baseline / R2 / R3) plus the decision formulas and negative controls live in `docs/02-Electron架构/E6_插件生态与发布/01-插件独立构建/样式命名空间归一化/32-任务-选择器形态轴门禁与落地.md`; the host side is guarded by criteria ⑩⑪ of `scripts/check-css-namespace.mjs` (plus the runtime mirror on axis ④ of the probe), and the plugin side by the **fourth and fifth criteria** of the SDK's `check-css-namespace` leg (`checks/selector-form.ts` for S2/S3, and `checks/keyframe-refs.ts` for dangling keyframe references—the latter in place since **2026-09-18**, SDK `≥ 0.1.37`).
|
|
763
763
|
|
|
@@ -62,7 +62,7 @@ The `README.md` in the plugin root directory is displayed in the **"Details" tab
|
|
|
62
62
|
|
|
63
63
|
## 6. Live exemplars (copy them and you can't go wrong)
|
|
64
64
|
|
|
65
|
-
- The READMEs of the 8 official plugins that already embed scene covers are ready-made models: `editor` / `file-tree` / `serial-monitor` / `settings` / `python` / `theme-terminal` / `theme-aurora-glass` / `lang-defaults
|
|
65
|
+
- The READMEs of the 8 official plugins that already embed scene covers are ready-made models: `editor` / `file-tree` / `serial-monitor` / `settings` / `python` / `theme-terminal` / `theme-aurora-glass` / `lang-defaults`. The `` at the top of their READMEs is the standard way to write a cover.
|
|
66
66
|
- In-page `<video>` / cover link-out examples: the serial-monitor README's git history commits `2f9a52c6b` (real in-page playback) and `8c9d71551` (fullscreen fix) each carry a complete `<video>` / `<a><img></a>` example from the manual testing of that moment, reverted once verified — look at those two commits if you want to copy a complete example.
|
|
67
67
|
|
|
68
68
|
---
|
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
|
|
12
12
|
```
|
|
13
13
|
E:\linkdesk-plugins\
|
|
14
|
-
├─ official\ ← your own plugins (the
|
|
14
|
+
├─ official\ ← your own plugins (the official ones + later new plugins)
|
|
15
15
|
│ ├─ file-tree\
|
|
16
16
|
│ └─ settings\
|
|
17
17
|
└─ third-party\ ← other people's plugins (cloned to study / fork)
|
|
@@ -62,7 +62,7 @@ Benchmarked against the empirically verified VS Code position (`ms-vscode.cpptoo
|
|
|
62
62
|
|
|
63
63
|
**Where you clone a plugin project and what the directory is called have no effect on plugin identity** — a plugin repo is self-contained, and the shell only recognizes the Release URL and the catalog; it **does not recognize local paths at all**. ⇒ The local directory structure can be rearranged at any time, with zero risk.
|
|
64
64
|
|
|
65
|
-
Live evidence:
|
|
65
|
+
Live evidence: all 16 official plugins work this way today — each source repo sits flat outside the container (one independent repo per plugin) and still builds, publishes, gets listed, and installs/uninstalls normally in the installed app.
|
|
66
66
|
|
|
67
67
|
✅ **So "renaming a directory" is already safe today**: plugin identity = the top-level `pluginId` field (which must be declared explicitly and cannot be changed after publication), **and it has nothing to do with the directory name**.
|
|
68
68
|
|
|
@@ -99,7 +99,7 @@ The table below is **reconciled name by name** against it (gate `scripts/check-r
|
|
|
99
99
|
|:--|:--|:--|
|
|
100
100
|
| Host command prefix | `app.`、`core.`、`theme.`、`update.`、`view.`、`workbench.` | Your command id lands in the host's own segment — in the command palette and the keybindings page it looks like a host feature |
|
|
101
101
|
| Host protocol id | `bracket` | Same name as the host's bracket-matching protocol handler ⇒ one of the two never runs, with no error |
|
|
102
|
-
| Host pseudo plugin id | `app`、`appearance` | The host registers as a "plugin" too (shell core / appearance; the former "update" group merged into General on 2026-09-26 — `update` is retired & logged) ⇒ these ids read as the host itself |
|
|
102
|
+
| Host pseudo plugin id | `app`、`appearance`、`ai-bridge` | The host registers as a "plugin" too (shell core / appearance / AI integration section; the former "update" group merged into General on 2026-09-26 — `update` is retired & logged) ⇒ these ids read as the host itself; its config keys (`ai.*`) are under the same protected-zone rules |
|
|
103
103
|
| Host config key | `app.schemaVersion` | The config **internal version marker** (invisible in the settings UI, never registered) — taking it derails migration bookkeeping and the user's data looks lost |
|
|
104
104
|
| Host config key | `app.theme`、`app.themeColor`、`app.themeColorMode`、`app.iconTheme` | Theme and colours — taking it overwrites the theme the user is currently using |
|
|
105
105
|
| Host config key | `app.appearanceMode`、`app.accentColor`、`app.accentMode`、`app.accentSource`、`app.menuStyle`、`app.hint.enabled` | Light/dark mode, accent colour, menu style, hover hints |
|
|
@@ -117,7 +117,7 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
|
|
|
117
117
|
| Criterion | Grade | Judged by | What happens |
|
|
118
118
|
|:--|:--:|:--|:--|
|
|
119
119
|
| The `set` name ∈ **segment ① host-only** | 🔴 **red** | SDK leg `linkdesk/no-unowned-context-key` | Your lint reports red by name; the **runtime second net** adds a `console.error` at the `contextKey:set` bridge — but 🔴 **the value is still written, not rejected** (see below) |
|
|
120
|
-
| **New** flag's first segment isn't your `pluginId` | 🟡 yellow (advisory) | SDK leg | Reported with `suggested` = the same name with only the first segment swapped (`zzzFlag` → `my-plugin.zzzFlag`). 23 flags across the
|
|
120
|
+
| **New** flag's first segment isn't your `pluginId` | 🟡 yellow (advisory) | SDK leg | Reported with `suggested` = the same name with only the first segment swapped (`zzzFlag` → `my-plugin.zzzFlag`). 23 flags across the official repos break this rule; the shell migrates them centrally — **write new ones by the rule** |
|
|
121
121
|
| The `set` name ∈ **segment ② convention face** | 🟠 **not judged** | Registered only | Legal, but see above: that's the gear menu's spot — don't overwrite it |
|
|
122
122
|
|
|
123
123
|
> **Why "taking a host-only flag" is red while "missing your prefix" is only yellow**: taking a host-only flag does **real harm** (it replaces host state, and neither side errors); whereas "missing the prefix" has 23 counterexamples in existing code, so a blanket rule would break shipped plugins on the spot. Different grades = different tolerance, not "the more important rule is written stricter".
|
|
@@ -29,11 +29,13 @@
|
|
|
29
29
|
|
|
30
30
|
| 事实 | 说明 |
|
|
31
31
|
|------|------|
|
|
32
|
-
| **契约
|
|
32
|
+
| **契约 46 命名空间** | 池注入 45(唯一缺 `bridge`);壳注入 25;mock 注入 13——**以 `check-namespace-matrix` 门禁的活读数为准**(本行已由它机械对账,⛔ 别照 `surfaces.ts` 里的注释抄,那份也在漂) |
|
|
33
33
|
| **池 = 插件运行时真相源** | 插件运行在池(pool)preload——池注入的命名空间为 **required**;`bridge` 真壳独有 |
|
|
34
34
|
| **「仅壳」≠ 插件不可调** | `window.*`/`shell.*`/`hotExit.*`/`getFilePath` 池**实有注入**——旧版把这几面标 ❌ 仅壳是错的 |
|
|
35
35
|
| **契约必选面漂移已清零** | `env.get(pluginId)` 转发、`clipboard.readText` 壳补、`dialog.openFile` 壳补——三项都已补齐实现,无 `?` 降级 |
|
|
36
36
|
|
|
37
|
+
> **上面这张表只说「哪面能调」,不说「能读到什么」。** 读取面(插件/AI 读「现在有什么、在等什么」)单列一章——见 §3.3:**只有操作面、没有读取面的 API 是半成品**(能开标签页,却读不到现在开了哪些)。
|
|
38
|
+
|
|
37
39
|
---
|
|
38
40
|
|
|
39
41
|
## 三、完整 API 定义 → 指针
|
|
@@ -42,7 +44,7 @@
|
|
|
42
44
|
|
|
43
45
|
**`window.linkdesk.*` 的全部方法签名、入参、返回、载荷类型 = [contracts/linkdesk.d.ts](https://github.com/Encaron/linkdesk/blob/electron/contracts/linkdesk.d.ts)**(自动生成,勿手改)。
|
|
44
46
|
|
|
45
|
-
- **生成源:** `src/core/api/linkdesk-api.ts` + `linkdesk-api/`(
|
|
47
|
+
- **生成源:** `src/core/api/linkdesk-api.ts` + `linkdesk-api/`(15 域接口)+ `src/core/types/ipc/*` + `src/core/types/pool/*`(wire 载荷类型)
|
|
46
48
|
- **生成器:** `scripts/generate-contract.mjs`(Route C——契约类型文件为源,纯类型打包单文件)
|
|
47
49
|
- **机械门禁:** preload 双端 `satisfies` 契约面类型 → tsc 漂移门禁;`npm run check` 内 `contracts:check` hash 字节比对
|
|
48
50
|
- **覆盖矩阵:** 每个命名空间 × 池/壳/mock 四面覆盖 → [命名空间矩阵 §2](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/契约生成/命名空间矩阵.md#2-命名空间--四面覆盖矩阵)
|
|
@@ -101,7 +103,40 @@ async function list(): Promise<FileEntry[]> {
|
|
|
101
103
|
| `workspace:changed` | `{ rootPath }` | 用户打开/切换文件夹 |
|
|
102
104
|
| `plugin:installJobs` | `{ jobs: InstallJob[] }`(**全量快照,非增量**) | 壳侧安装/卸载队列变化(建 /补阶段与百分比 /补 `kind`·`cancellable`)。`InstallJob` = `{ jobId, pluginId, origin: "user"\|"dependency", kind: "install"\|"uninstall", cancellable: boolean, displayName, state: "queued"\|"running"\|"settled", terminal?: "success"\|"failed"\|"parked", error?, stage?, percent?, message? }`——**每次广播都是整表**,消费方**直接替换本地镜像**,别做增量合并。**晚订阅者拿到最新整表**:池 preload 顶层缓存一份、订阅时同步回放(视图重挂不会停在旧快照)。⚠️ 这是**公开事件面**,不是市场私有管道——任何插件可订阅做自己的进度面;⚠️ **`stage`/`percent`/`message`/`kind`/`cancellable` 均为只增不改的增补字段**,旧消费方忽略即可。⚠️ `origin: "dependency"` = 某插件自己拖来的依赖,藏在发起它的那一行(`origin: "user"`)里面 |
|
|
103
105
|
|
|
104
|
-
### 3.3
|
|
106
|
+
### 3.3 读取面——「现在有什么 / 在等什么」的机器出口
|
|
107
|
+
|
|
108
|
+
§3.1/§3.2 讲的是**操作面**(插件能做什么);本节讲**读取面**(插件/AI 能**读到**什么)。
|
|
109
|
+
|
|
110
|
+
**为什么单列一章:** 操作面齐全 ≠ 自动化可行。能开标签页、能弹通知,却没有「现在开了哪些标签 / 面板里堆着什么通知 / 有没有弹窗在等用户」的读法,外部驱动方(AI、脚本、远程控制)就只能靠猜——**猜出来的状态与屏幕一不符,就成了假信息源**,比没有读取面更坏。
|
|
111
|
+
|
|
112
|
+
| 读取面 | 方法 | 读到什么 |
|
|
113
|
+
|:--|:--|:--|
|
|
114
|
+
| **通知** | `notifications.list()` | 铃铛宽通知面板现状——条数、未读计数、每条文案与按钮、唤醒与存活判据。返回 = **面板的 DTO 本体**(`NotifLayout`,与 `pool.onLayout` 的 `statusBar.notif` 同一个 `buildNotif` 产出) |
|
|
115
|
+
| **通知变更** | `notifications.subscribe(cb)` | 「**现在变了**」信号(新增/更新/收掉/认账/面板开合)。🔴 **回调不带载荷**——要答案请再 `list()`(「状态推流 + 按需拉」分工,同 `events.on` 那套) |
|
|
116
|
+
| **标签** | `tabs.list()` | 全部窗口的标签清单(`TabsSnapshot`:`windowId`/`mode`/`ready`/`activeGroupId`/`root`/`groups`,每组含 `activeTabId`)。与推给池的布局树**同一个 `serializeGroups`** ⇒ 清单里的 `label`/`icon` 与屏幕上那一条必然一致 |
|
|
117
|
+
| **布局** | `pool.getLayout()` | 本窗**最近一次** `onLayout` 的快照本体(树 `root` + 分组 `groups`)。未收到过任何推送 → `null`(⛔ 不编一份空布局) |
|
|
118
|
+
| **在途弹窗** | `dialogHost.pending()` | 此刻正弹着、等用户决定的 confirm/alert(`options` 原形 + `kind` + 按钮文案 + 富内容视图身份)。空数组 = 此刻没有弹窗 |
|
|
119
|
+
| **命令元数据** | `commands.getCommands()` | 全部命令的 `id`/`title`/`category`/**`description`**/**`params`**(后两者 M1 起有;`params[i]` 与 handler 实参**逐位对应**)——命令清单本身就是一份**可直接喂给大模型当工具清单(function calling)**的结构 |
|
|
120
|
+
|
|
121
|
+
> 方法签名以 [contracts/linkdesk.d.ts](https://github.com/Encaron/linkdesk/blob/electron/contracts/linkdesk.d.ts) 为准;上表只回答「哪几件、读什么」。
|
|
122
|
+
|
|
123
|
+
**三条读取面规矩(写给实现者,也写给消费方):**
|
|
124
|
+
|
|
125
|
+
1. **读取面 ≡ 屏幕,同一把尺。** 返回的必须是**屏幕上那份 DTO 本体**,⛔ 不许另算一份摘要——两把尺子必然打架:读到的分组/未读/文案若与屏幕上画的不同,读取面就成了假信息源。
|
|
126
|
+
2. **信号与答案分家。** 订阅只回答「**变了**」(无载荷),答案一律问 `list()`。信号里带了数据,就会有人不去问权威,于是又长出第二把尺。
|
|
127
|
+
3. **文案已解析,原样显示。** `bellTitle`/`panelTitle`/分组 label/`timeLabel` 等文案类字段**已由壳按当前语言 `t()` 解析**(显示文本铁律)——调用方原样显示,不要再查一次 i18n。
|
|
128
|
+
|
|
129
|
+
**边界(都是「如实报不知道」,不是缺陷):**
|
|
130
|
+
|
|
131
|
+
- `pool.getLayout()` 在**脱出窗**拿到的是策略子集(`WINDOW_MODE_STRATEGIES`:`detached` = `titleBar`+`groups`;`drift` = `titleBar`+`panel`)——那些窗里 `statusBar`/`sidebar`/`iconBar` 不存在。要跨窗看全貌用 `tabs.list()`(问壳)。
|
|
132
|
+
- `tabs.list()` **全窗一次性给全**:壳侧没有「当前窗」这个真相源 ⇒ 调用方自己按 `windowId` 筛(⛔ 别指望壳猜你想看哪一窗)。
|
|
133
|
+
- `notifications.list()` 经 `plugins:call` 问**壳**(壳持全量状态)——所以**脱出窗也拿得到**(只读本窗布局子集会答「没有通知」)。
|
|
134
|
+
- `dialogHost.pending()` 的 `buttons` **序 = 声明序**(`[确认, 取消]`),**不是屏幕上的左右位**(实测:屏幕上取消画左、确认画右)。想动手就按序号调 `dialogHost.confirm()`/`cancel()`,⛔ 别拿视觉位置对号入座。
|
|
135
|
+
- **池侧读、壳侧不实现**:`tabs.list()` / `pool.getLayout()` 在 `preload-shell` 里**不存在**(壳自己手上就是那份 state,不绕 IPC 问自己)。壳内视图要用请走壳自己的 service。
|
|
136
|
+
|
|
137
|
+
**将来要加读取面:** 判据一句话——**「屏幕上有的,机器就得读得到」**。加一件前先问三句:① 返回的是不是屏幕那份 DTO 本体?② 有没有因此长出第二份状态/第二把尺?③ 消费方有没有不靠它的替代路径(没有 ⇒ 这是缺口,不是可选项)。
|
|
138
|
+
|
|
139
|
+
### 3.4 与旧手写版的差异(读者注意)
|
|
105
140
|
|
|
106
141
|
旧版 §3.x 逐命名空间方法清单已删除(= 手写第二份真相源,必然漂移)。生成的契约解决了几处**旧文档与实现不符**的漂移:
|
|
107
142
|
|
|
@@ -76,7 +76,12 @@
|
|
|
76
76
|
"id": "cad.importDxf",
|
|
77
77
|
"title": "导入 DXF…",
|
|
78
78
|
"category": "CAD",
|
|
79
|
-
"when": "activeEditor == 'cad'"
|
|
79
|
+
"when": "activeEditor == 'cad'",
|
|
80
|
+
"description": "从 DXF 文件导入图形到当前工程",
|
|
81
|
+
"params": [
|
|
82
|
+
{ "name": "layerFilter", "type": "string", "description": "只导入该图层(省略 = 全部)" },
|
|
83
|
+
{ "name": "explodeBlocks", "type": "boolean", "description": "块是否炸开为基本图元" }
|
|
84
|
+
]
|
|
80
85
|
}
|
|
81
86
|
]
|
|
82
87
|
}
|
|
@@ -89,8 +94,21 @@
|
|
|
89
94
|
| `title` | ✅ | 显示名称(i18n key——中文原文) |
|
|
90
95
|
| `category` | ❌ | 命令面板分组——"CAD" / "终端" / "文件" |
|
|
91
96
|
| `when` | ❌ | context key when 条件。不加 `when` = 任何上下文可见 |
|
|
97
|
+
| `description` | ❌ | **这条命令干什么**——用户/AI 视角的意图(i18n key,同 `title` 规矩)。⛔ 不复述 `id`。缺省 = 无说明 |
|
|
98
|
+
| `params` | ❌ | **参数结构**——数组,逐位对应 handler 实参。缺省 = 无参数命令 |
|
|
92
99
|
|
|
93
|
-
|
|
100
|
+
**`params` 条目字段(逐位对应 handler 实参):**
|
|
101
|
+
|
|
102
|
+
| 字段 | 必需 | 说明 |
|
|
103
|
+
|------|:--:|------|
|
|
104
|
+
| `name` | ✅ | 参数名——**照 handler 实参名写**(如 `tabId` / `settingKey` / `groupId`) |
|
|
105
|
+
| `type` | ✅ | 四值收敛:`"string"` \| `"number"` \| `"boolean"` \| `"object"`(`object` = 结构化载荷,字段明细写在 `description`) |
|
|
106
|
+
| `required` | ❌ | 是否必填。缺省 `false`(可选) |
|
|
107
|
+
| `description` | ❌ | 一句话说明这个参数是什么(省略 = 名字已自明) |
|
|
108
|
+
|
|
109
|
+
> **`description` / `params` 随 `getCommands()` 出契约**(`LinkDeskCommand.description` / `LinkDeskCommand.params`)——消费方(命令面板、自动化、AI)照 `params` 拼 `executeCommand(id, ...params)` 即可,**不必读源码猜参数**。同名字段在**运行时注册**(`registerCommand(id, handler, meta)`)上同样可选,两处同义(声明面写一次即可,运行时注册通常不必重复)。
|
|
110
|
+
|
|
111
|
+
**声明即注册元数据(placeholder):** `contributes.commands` 只注册命令元数据(id/title/category/when/description/params),**真实 handler 在池侧注册**(池侧 `_poolCommands` 优先)。不注册 handler 的命令被调用 → no-op(诊断 warn)。
|
|
94
112
|
|
|
95
113
|
```typescript
|
|
96
114
|
// 池侧注册真实 handler(组件 mount 时)
|
|
@@ -473,7 +491,7 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
|
|
|
473
491
|
|
|
474
492
|
🔴 **为什么这是建议而不是强制**:**i18n 键可以合法住在应用级字典**。官方 `settings` 插件的 254 处 `t()` 调用,**一个键都不在它自己的仓里**(全住 `lang-defaults` 的 `zh.json` / `en.json`)。插件仓里只有你自己的 `i18n/*.json`——**看不到宿主的字典,也看不到其余插件**,所以「你的键撞了别人」在你自己仓里**永远判不出来**。把它做成拦截 = 必然误报,而误报会让真正该拦的规则失效。⇒ **它是黄灯,不是红灯。**
|
|
475
493
|
|
|
476
|
-
|
|
494
|
+
**真实存在多少重合**(如实告诉你,不夸大——下面的数是**一次测量**,取当时官方 18 只的名单,不是活读数):官方插件声明了 **414 个键**,其中与 `lang-defaults` 的键 **65 条重合**,而这 65 条里 **3 条译文已经不一致**——例如 `命令`,宿主给的是 `Command`,而 `serial-monitor` 给的是 `Commands`。**两条都写进同一本字典时,用户看到的究竟是哪一条,取决于插件加载顺序。**
|
|
477
495
|
|
|
478
496
|
⚠️ **运行时行为**:发生覆盖时宿主会 `console.warn` 出声,点明**键名 + 语言 + 写入者**:
|
|
479
497
|
|
|
@@ -781,7 +799,7 @@ useEffect(() => {
|
|
|
781
799
|
|
|
782
800
|
**四条边界**:① 只管**第一次打开**——已有标签页仍聚焦、面板开着再点仍按开关键关掉,打开之后想换形态照旧走「在主窗口中打开」/「在悬浮面板中打开」两条老路;② `formKey` 与 `defaultForm` **互斥**(同时写 ⇒ schema 校验红:一个形态两个来源);③ `formKey` 写错字 / 没注册那个键 ⇒ 降级 `defaultForm`(都没有 = 原行为)+ 出声一条 warn——**不静默失效**;④ 声明 `"defaultForm": "tab"` 但插件没有标签页形态(`appearsIn.tabBar` + `entry`)⇒ 落回悬浮面板,不静默无动作。
|
|
783
801
|
|
|
784
|
-
|
|
802
|
+
**当前唯一声明者 = settings**(`core.openSettings` Ctrl+, 弹面板,`settings.openForm` 在「设置插件」组里让用户改)。机制本身是通用的,且已端到端验证过(替换 + 右键回程 + 卸载 no-op)——你随时可以成为第二个声明者。
|
|
785
803
|
|
|
786
804
|
---
|
|
787
805
|
|
package/docs/zh/04-/346/217/222/344/273/266/345/210/206/345/217/221/346/240/274/345/274/217.md
CHANGED
|
@@ -51,8 +51,8 @@ my-plugin/
|
|
|
51
51
|
|
|
52
52
|
| 代码根 | 位置 | 形态 | HMR | 谁住这里 |
|
|
53
53
|
|------|------|------|:--:|------|
|
|
54
|
-
| **插件自己的仓** | GitHub `Encaron/linkdesk-plugin-<id>`(本地克隆落在容器目录 `E:\linkdesk-plugins\official\<id>\`) | 源码 + SDK build(`npm run build` → `<id>.linkdesk-plugin`) | ✅(`linkdesk-plugin-sdk dev`) |
|
|
55
|
-
| **壳仓夹具** | `<壳仓>/plugins/<id>/`(`env.appPluginsDir`) | 源码 + Vite 即时编译 | ✅(`npm run dev` 热更) |
|
|
54
|
+
| **插件自己的仓** | GitHub `Encaron/linkdesk-plugin-<id>`(本地克隆落在容器目录 `E:\linkdesk-plugins\official\<id>\`) | 源码 + SDK build(`npm run build` → `<id>.linkdesk-plugin`) | ✅(`linkdesk-plugin-sdk dev`) | **全部发货插件**(今天 16 只)——一只一个仓,源码真相源只此一处 |
|
|
55
|
+
| **壳仓夹具** | `<壳仓>/plugins/<id>/`(`env.appPluginsDir`) | 源码 + Vite 即时编译 | ✅(`npm run dev` 热更) | 只剩一只**开发夹具**:`panel-demo`(不发货、不进 zip) |
|
|
56
56
|
| **安装态** | `{userData}/plugins/<id>/` | zip 解出的预构建 bundle | ❌(改包需重 build + 重装/重物化) | 用户机器上所有已装插件 |
|
|
57
57
|
|
|
58
58
|
> 🔴 **为什么发货插件的源码不能两边都留一份**:一旦壳仓与插件仓各有一份,改了这头那头不变,而**没有任何门禁能发现分叉**(内容指纹门禁只管 zip 内容,不管源码)⇒ 真相源必须唯一。壳仓留下的两样是**产物**(`bundled-plugins/*.linkdesk-plugin`)与**文档档案**,不是源码。
|
|
@@ -60,7 +60,7 @@ my-plugin/
|
|
|
60
60
|
> **真机环例外(作者 dev):** 安装态改包需「重 build + 重装/重物化」在**作者每次真机验证**场景 = WPF v2 一次性循环痛苦。真机环自动化它——SDK 秒级重建 + **直写** `{userData}/plugins/<id>`(同盘覆盖语义,reload 即生效)成循环,作者仍不碰壳。分发 zip 的「不自改 bundle」纪律不变(那是给终用户的包)。设计档案 → [04-作者真机调试环.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/04-作者真机调试环.md)。
|
|
61
61
|
|
|
62
62
|
> **卸载语义(2026-09-05 后):** 安装态插件卸载 = **删 `{userData}/plugins/<id>/` 目录 + 账本销账**(不再是 `.disabled/` 移入);只有 repo 源码树里的 app 插件卸载才移 `plugins/.disabled/` 坟场(可 reinstall 恢复)。账本 `installed-plugins.json` 唯一 owner = 渲染进程 PluginInstallService,boot 只读它的 `removed` 标记防误恢复。
|
|
63
|
-
> 🔵 **核对结论(`.disabled/` 坟场还有没有消费者)**:**机制仍在、当前无对象**。消费者是活的——`src/pluginLoader/loader.ts` 读它(`reinstallPlugin` / 卸载 toast 的「撤销」/ 跨重启孤儿清理都以 `env.appPluginsDir/.disabled` 为唯一权威面)。但 `env.appPluginsDir` = 壳仓 `plugins
|
|
63
|
+
> 🔵 **核对结论(`.disabled/` 坟场还有没有消费者)**:**机制仍在、当前无对象**。消费者是活的——`src/pluginLoader/loader.ts` 读它(`reinstallPlugin` / 卸载 toast 的「撤销」/ 跨重启孤儿清理都以 `env.appPluginsDir/.disabled` 为唯一权威面)。但 `env.appPluginsDir` = 壳仓 `plugins/`,而发货插件已外移 ⇒ 那里只剩一只夹具,**没有「在 repo 源码树里被卸载的 app 插件」了**。⇒ 机制**保留**(它是仓内插件 dev 路径的一部分,删它要动 loader 三处 + 主进程扫描面,风险大于收益),但**不要**再把它当成发货插件的可撤销卸载通道。
|
|
64
64
|
|
|
65
65
|
---
|
|
66
66
|
|
package/docs/zh/05-/346/217/222/344/273/266UI/345/206/231/346/263/225/350/247/204/347/272/246.md
CHANGED
|
@@ -759,7 +759,7 @@ button { border: none; }
|
|
|
759
759
|
共享基线**,插件一直在依赖它们(也可以覆写)。正因为它们存在,**你的无锚选择器一定会命中它们**:
|
|
760
760
|
你写 `button { }`,宿主的按钮、其他插件的按钮,全都会跟着变。
|
|
761
761
|
|
|
762
|
-
**迁移**:**今天 0
|
|
762
|
+
**迁移**:**今天 0 存量**——官方插件 + 壳内夹具全量复核(`npm run audit:plugin-prefix -- --all`
|
|
763
763
|
的「无锚 S2 / 跨方 S3」两列)都是 **0** ⇒ **你不需要改任何东西**;这条规矩是**预防性**的。
|
|
764
764
|
|
|
765
765
|
> 🔧 **维护者注(作者可跳过)**:规则正文(R0 口径 / R1 宿主基线 / R2 / R3)与判定式、负控见
|
|
@@ -62,7 +62,7 @@
|
|
|
62
62
|
|
|
63
63
|
## 六、活的样板(照抄不会错)
|
|
64
64
|
|
|
65
|
-
- 官方 8 只已嵌场景封面的插件 README = 现成范本:`editor` / `file-tree` / `serial-monitor` / `settings` / `python` / `theme-terminal` / `theme-aurora-glass` / `lang-defaults
|
|
65
|
+
- 官方 8 只已嵌场景封面的插件 README = 现成范本:`editor` / `file-tree` / `serial-monitor` / `settings` / `python` / `theme-terminal` / `theme-aurora-glass` / `lang-defaults`。看它们 README 顶部那张 `` 就是封面标准写法。
|
|
66
66
|
- 页内 `<video>` / 封面外链写法:串口监视器 README 的 git 历史 commit `2f9a52c6b`(页内真播)与 `8c9d71551`(全屏修复)各带一段当时手测用的完整 `<video>` / `<a><img></a>` 示例,验完即撤——要抄完整写法可看那两次提交。
|
|
67
67
|
|
|
68
68
|
---
|
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
|
|
12
12
|
```
|
|
13
13
|
E:\linkdesk-plugins\
|
|
14
|
-
├─ official\ ←
|
|
14
|
+
├─ official\ ← 你自己的插件(官方那些 + 后续新插件)
|
|
15
15
|
│ ├─ file-tree\
|
|
16
16
|
│ └─ settings\
|
|
17
17
|
└─ third-party\ ← 别人的插件(clone 下来学习/二开的)
|
|
@@ -62,7 +62,7 @@ E:\linkdesk-plugins\
|
|
|
62
62
|
|
|
63
63
|
**插件工程 clone 到哪、目录叫什么,都不影响插件身份**——插件仓是自足的,壳只认 Release URL 与 catalog,**不认本地路径**。⇒ 本地目录结构随时可重排,零风险。
|
|
64
64
|
|
|
65
|
-
|
|
65
|
+
活证据:官方 16 只现在全是这样——每只的源码仓平铺在容器外(各自独立一仓),照样构建、发布、上架、被安装版正常装卸。
|
|
66
66
|
|
|
67
67
|
✅ **所以「改目录名」这件事今天已经安全**:插件身份 = 顶层 `pluginId` 字段(必须显式声明,发布后不可改),**与目录名无关**。
|
|
68
68
|
|
|
@@ -101,7 +101,7 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
|
|
|
101
101
|
|:--|:--|:--|
|
|
102
102
|
| 宿主命令前缀 | `app.`、`core.`、`theme.`、`update.`、`view.`、`workbench.` | 你的命令 id 落进宿主自己的段——命令面板、快捷键设置页里它看起来像宿主的功能 |
|
|
103
103
|
| 宿主协议 id | `bracket` | 与宿主的括号匹配协议处理器同名 ⇒ 有一方不生效(不报错) |
|
|
104
|
-
| 宿主伪 pluginId | `app`、`appearance` | 宿主自己也以「插件」身份注册(壳通用 /
|
|
104
|
+
| 宿主伪 pluginId | `app`、`appearance`、`ai-bridge` | 宿主自己也以「插件」身份注册(壳通用 / 外观 / AI 接入分区;原「更新」组 2026-09-26 并入「通用」,`update` 已退役登记)⇒ 用这些 id 会被当成宿主自己;其名下配置键(`ai.*`)同样受保护区管辖 |
|
|
105
105
|
| 宿主配置键 | `app.schemaVersion` | 配置的**内部版本标志**(设置界面里看不到、也没有注册过)——占它会让迁移记账错乱,用户数据看着丢 |
|
|
106
106
|
| 宿主配置键 | `app.theme`、`app.themeColor`、`app.themeColorMode`、`app.iconTheme` | 主题与配色——占它 = 直接顶掉用户当前选的主题 |
|
|
107
107
|
| 宿主配置键 | `app.appearanceMode`、`app.accentColor`、`app.accentMode`、`app.accentSource`、`app.menuStyle`、`app.hint.enabled` | 亮暗模式、强调色、菜单样式、悬停提示 |
|
|
@@ -117,7 +117,7 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
|
|
|
117
117
|
| 判据 | 分级 | 谁判 | 会发生什么 |
|
|
118
118
|
|:--|:--:|:--|:--|
|
|
119
119
|
| `set` 的名字 ∈ **段① 宿主专用** | 🔴 **红** | SDK 腿 `linkdesk/no-unowned-context-key` | 作者仓里 lint 报红点名;**运行时第二道网**在 `contextKey:set` 过桥处补一条 `console.error`,但 🔴 **值照写、不拒绝**(见下) |
|
|
120
|
-
| **新**旗子第一段不是本仓 `pluginId` | 🟡 黄(建议) | SDK 腿 | 报点带 `suggested` = 只换第一段的新名(`zzzFlag` → `my-plugin.zzzFlag
|
|
120
|
+
| **新**旗子第一段不是本仓 `pluginId` | 🟡 黄(建议) | SDK 腿 | 报点带 `suggested` = 只换第一段的新名(`zzzFlag` → `my-plugin.zzzFlag`)。存量官方仓有 23 个旗子不合此规,迁移由壳侧统一执行——**新旗子请照规矩写** |
|
|
121
121
|
| `set` 的名字 ∈ **段② 约定面** | 🟠 **不判** | 只登记 | 合法,但见上:那是齿轮菜单的位置,别去覆盖 |
|
|
122
122
|
|
|
123
123
|
> **为什么"占宿主专用"是红、"没带自己前缀"只是黄**:占专用旗子有**真害**(顶替宿主状态,两侧都不报错);而"没带前缀"在存量里有 23 个反例,一刀切会把既有插件当场弄坏。分级不同 = 容忍度不同。
|
|
@@ -299,7 +299,26 @@
|
|
|
299
299
|
"id": { "type": "string", "description": "Command ID — e.g. terminal.clear" },
|
|
300
300
|
"title": { "type": "string", "description": "Display name" },
|
|
301
301
|
"category": { "type": "string", "description": "Command palette group" },
|
|
302
|
-
"when": { "type": "string", "description": "context key when condition — e.g. activeEditor == 'terminal'" }
|
|
302
|
+
"when": { "type": "string", "description": "context key when condition — e.g. activeEditor == 'terminal'" },
|
|
303
|
+
"description": {
|
|
304
|
+
"type": "string",
|
|
305
|
+
"description": "What this command does — the intent from the user/AI perspective. Do not restate the command id."
|
|
306
|
+
},
|
|
307
|
+
"params": {
|
|
308
|
+
"type": "array",
|
|
309
|
+
"description": "Parameter structure — items correspond positionally to the handler's arguments.",
|
|
310
|
+
"items": {
|
|
311
|
+
"type": "object",
|
|
312
|
+
"required": ["name", "type"],
|
|
313
|
+
"properties": {
|
|
314
|
+
"name": { "type": "string", "description": "Parameter name — must match the handler's parameter name (e.g. tabId / settingKey / groupId)" },
|
|
315
|
+
"type": { "type": "string", "enum": ["string", "number", "boolean", "object"], "description": "Parameter type — object = structured payload (document its fields in description)" },
|
|
316
|
+
"required": { "type": "boolean", "description": "Whether the parameter is required. Defaults to false." },
|
|
317
|
+
"description": { "type": "string", "description": "One sentence on what this parameter is" }
|
|
318
|
+
},
|
|
319
|
+
"additionalProperties": false
|
|
320
|
+
}
|
|
321
|
+
}
|
|
303
322
|
},
|
|
304
323
|
"additionalProperties": false
|
|
305
324
|
}
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@linkdesk/plugin-docs",
|
|
3
|
-
"version": "0.1.
|
|
4
|
-
"description": "LinkDesk
|
|
3
|
+
"version": "0.1.36",
|
|
4
|
+
"description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"files": [
|
|
7
7
|
"docs",
|