@linkdesk/plugin-docs 0.1.43 → 0.1.44

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.
Files changed (27) hide show
  1. package/docs/00-readme.md +1 -1
  2. package/docs/01-plugin-api-contract.md +5 -2
  3. package/docs/04-distribution-format.md +5 -5
  4. package/docs/05-ui-conventions.md +3 -3
  5. package/docs/06-plugin-json-spec.md +1 -1
  6. package/docs/08-view-container-api.md +1 -1
  7. package/docs/11-authoring-themes.md +14 -14
  8. package/docs/13-development-guide.md +8 -8
  9. package/docs/14-data-pipeline-command-conventions.md +1 -1
  10. package/docs/15-multi-repo-and-local-workspace.md +2 -2
  11. package/docs/16-naming-conventions.md +3 -3
  12. package/docs/themes/02-theme-field-index.md +3 -3
  13. package/docs/zh/00-README.md +1 -1
  14. package/docs/zh/01-/346/217/222/344/273/266API/345/245/221/347/272/246.md +5 -2
  15. package/docs/zh/02-/346/217/222/344/273/266/347/224/237/345/221/275/345/221/250/346/234/237.md +1 -1
  16. package/docs/zh/04-/346/217/222/344/273/266/345/210/206/345/217/221/346/240/274/345/274/217.md +6 -6
  17. package/docs/zh/05-/346/217/222/344/273/266UI/345/206/231/346/263/225/350/247/204/347/272/246.md +3 -3
  18. package/docs/zh/06-plugin.json/350/247/204/350/214/203.md +2 -2
  19. package/docs/zh/07-/346/217/222/344/273/266/351/227/264/351/200/232/344/277/241.md +1 -1
  20. package/docs/zh/08-ViewContainer-/350/247/206/345/233/276/345/256/271/345/231/250API.md +1 -1
  21. package/docs/zh/11-/344/270/273/351/242/230/345/210/266/344/275/234.md +14 -14
  22. package/docs/zh/13-/346/217/222/344/273/266/345/274/200/345/217/221/346/214/207/345/215/227.md +8 -8
  23. package/docs/zh/14-/346/225/260/346/215/256/347/256/241/351/201/223/345/221/275/344/273/244/347/272/246/345/256/232.md +1 -1
  24. 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
  25. package/docs/zh/16-/345/221/275/345/220/215/350/247/204/350/214/203.md +3 -3
  26. package/docs/zh//344/270/273/351/242/230/02-/344/270/273/351/242/230/345/255/227/346/256/265/351/200/237/346/237/245.md +3 -3
  27. package/package.json +1 -1
package/docs/00-readme.md CHANGED
@@ -189,5 +189,5 @@ Full story → [04-distribution-format §Listing Is Two Steps](04-distribution-f
189
189
  ## Related
190
190
 
191
191
  - Contract type source of truth: `linkdesk.d.ts` inside the `@linkdesk/contracts` package (arrives with the SDK)
192
- - Theme system design doc (**the shell's why**; authors need not read it): repo `docs/02-Electron架构/E5.8_归一化基建/外观主题化/`
192
+ - Theme system design doc (**the shell's why**; authors need not read it): repo `docs/02-Electron架构/归一化基建/外观主题化/`
193
193
  - Legacy Tauri-era docs: `docs/01-Tauri_P1至P5.5/` (historical reference only)
@@ -23,7 +23,7 @@
23
23
 
24
24
  ## 2. Shell vs Plugin — API Differences
25
25
 
26
- Plugins and the shell run in the same renderer process, but the injected namespace surfaces differ. **Which process each surface is available in, and how the pool/shell/mock coverage works — the single source of truth is [Namespace Matrix §2 coverage table](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/契约生成/命名空间矩阵.md#2-命名空间--四面覆盖矩阵)**; no second list is hand-written here.
26
+ Plugins and the shell run in the same renderer process, but the injected namespace surfaces differ. **Which process each surface is available in, and how the pool/shell/mock coverage works — the single source of truth is [Namespace Matrix §2 coverage table](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/归一化基建/契约生成/命名空间矩阵.md#2-命名空间--四面覆盖矩阵)**; no second list is hand-written here.
27
27
 
28
28
  A few key points (a summary of Matrix §2; the matrix wins on details):
29
29
 
@@ -47,7 +47,7 @@ A few key points (a summary of Matrix §2; the matrix wins on details):
47
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)
48
48
  - **Generator:** `scripts/generate-contract.mjs` (Route C — the contract type file is the source; pure types bundled into a single file)
49
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`
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-命名空间--四面覆盖矩阵)
50
+ - **Coverage matrix:** every namespace × pool/shell/mock coverage → [Namespace Matrix §2](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/归一化基建/契约生成/命名空间矩阵.md#2-命名空间--四面覆盖矩阵)
51
51
 
52
52
  ### 3.1 How Plugins Consume It
53
53
 
@@ -93,6 +93,9 @@ async function list(): Promise<FileEntry[]> {
93
93
  | **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 |
94
94
  | **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 |
95
95
  | **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 |
96
+ | **search** | Full-text search/replace — `searchFiles(opts)` is a single call-and-response executed by the shell/main process over IPC (zero local scanning on the plugin side); the request/result shapes follow the contract's `SearchWireOptions`/`SearchWireResult` |
97
+ | **encoding** | The encoding detect/convert trio (handled by the main process EncodingService): `detect(buffer)` guesses the encoding name / `decode(buffer, encoding)` bytes→text / `encode(text, encoding)` text→bytes — `Uint8Array` in and out |
98
+ | **update** | **Read-only update state**: `getState()` returns the host's full update state-machine snapshot (a nine-state discriminated union — `uninitialized`/`disabled`/`idle`/`checking`/`available`/`downloading`/`downloaded`/`updating`/`ready`; the payloads follow the contract's `UpdateState`); it **never throws** (the service always has a state). For "About"-style plugins to display version/update progress — **read-only**: triggering download/install is the shell's own business (the host's `update.*` command segment; plugins don't add commands to it) |
96
99
 
97
100
  **Shell broadcast events (plugins can subscribe via `events.on`):**
98
101
 
@@ -2,7 +2,7 @@
2
2
 
3
3
  > 2026-07-24 · updated 2026-08-21 · **full rewrite 2026-09-06 (flatten to single root + single-file zip distribution)**.
4
4
  > **How plugins are delivered, how they are installed, and the version-compatibility rules.** Modeled after VS Code's `.vsix`—LinkDesk distributes via a **single-file `.linkdesk-plugin` zip**.
5
- > The source of truth for packaging-format details = [linkdesk-plugin format spec](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/01-插件独立构建/02-linkdesk-plugin格式规范.md) (this page only covers the author-side delivery/install/version story).
5
+ > The source of truth for packaging-format details = [linkdesk-plugin format spec](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/01-插件独立构建/02-linkdesk-plugin格式规范.md) (this page only covers the author-side delivery/install/version story).
6
6
 
7
7
  ---
8
8
 
@@ -22,7 +22,7 @@ my-plugin/
22
22
  └── src/ … ← author source (does not go into the zip)
23
23
  ```
24
24
 
25
- **Who produces the zip:** [plugin-sdk](https://github.com/Encaron/linkdesk/tree/electron/packages/plugin-sdk) (`npm run publish` goes through the [author journey](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/05-文档与发布/00-第三方作者旅程.md)) emits `<id>.linkdesk-plugin` + the unpacked directory `dist/<id>.linkdesk-plugin/` at **the project root**. All JS inside the zip is pre-built and self-contained (react-family packages are external, provided by the shell)—**there is no source compilation in the installed state**.
25
+ **Who produces the zip:** [plugin-sdk](https://github.com/Encaron/linkdesk/tree/electron/packages/plugin-sdk) (`npm run publish` goes through the [author journey](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/05-文档与发布/00-第三方作者旅程.md)) emits `<id>.linkdesk-plugin` + the unpacked directory `dist/<id>.linkdesk-plugin/` at **the project root**. All JS inside the zip is pre-built and self-contained (react-family packages are external, provided by the shell)—**there is no source compilation in the installed state**.
26
26
 
27
27
  **Why a single file:** the shell loader only accepts pre-built bundles for installed plugins—`plugin-file-service` sees that `index.bundle.js` exists and overwrites the entry to point at it (`resolveEntry`; the bundle entry is always `index.bundle.js`). The zip is "one plugin = one file that can be downloaded, verified, and atomically replaced", and both install/uninstall and marketplace downloads work against it.
28
28
 
@@ -51,13 +51,13 @@ 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`) | **every shipped plugin** (16 today)—one repo each, and the only source of truth for their source |
54
+ | **The plugin's own repo** | GitHub `Encaron/linkdesk-plugin-<id>` (clone it into any local directory you like) | source + SDK build (`npm run build` → `<id>.linkdesk-plugin`) | ✅ (`linkdesk-plugin-sdk dev`) | **every shipped plugin**—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 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.
59
59
 
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).
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架构/插件生态与发布/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
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.
@@ -173,4 +173,4 @@ Author-side notes on install/uninstall/update/reinstall are in [02 plugin lifecy
173
173
  ---
174
174
 
175
175
  > **← Previous:** `03-contributes-spec.md`
176
- > **→ Related:** `02-plugin-lifecycle.md` (install/uninstall/update) · `09-plugin-directory-layout.md` (source directory) · [linkdesk-plugin format spec](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/01-插件独立构建/02-linkdesk-plugin格式规范.md) (the source of truth for the zip format)
176
+ > **→ Related:** `02-plugin-lifecycle.md` (install/uninstall/update) · `09-plugin-directory-layout.md` (source directory) · [linkdesk-plugin format spec](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/01-插件独立构建/02-linkdesk-plugin格式规范.md) (the source of truth for the zip format)
@@ -678,7 +678,7 @@ component. **Nothing to do before you upgrade; when you upgrade, it's one prefix
678
678
 
679
679
  - **Who is affected**: again **only your own CSS**'s descendant selectors that point at those components (e.g. `.settings-row:has(.theme-picker)`). **The components' own styling does not change, and your own class names stay as they are.** The whole point is that the shared components' names now all live in the `ldk-` namespace, whose rule you already know: **anything starting with `ldk-` belongs to the host—don't put it on your own elements** (the one exception is `.ldk-input`, the utility that is **for you**).
680
680
  - **What happens if you don't**: exactly the silent failure described in 12.1—the selector just stops matching and those few rules quietly stop applying. **No error.**
681
- - 🔴 **When the host renames a shared name or restyles a component, there is no code and no CSS for you to change** — components and styles are supplied by the shell pool (L9 centralized supply, see [19-Component Cheatsheet §2](19-component-cheatsheet.md)): the same implementation follows the shell upgrade, so your UI stays consistent. The one thing to maintain is that your `@linkdesk/ui` dependency **stays on the current version line** (it decides what your local dev and types resolve to).
681
+ - 🔴 **When the host renames a shared name or restyles a component, there is no code and no CSS for you to change** — components and styles are supplied by the shell pool (centralized supply, see [19-Component Cheatsheet §2](19-component-cheatsheet.md)): the same implementation follows the shell upgrade, so your UI stays consistent. The one thing to maintain is that your `@linkdesk/ui` dependency **stays on the current version line** (it decides what your local dev and types resolve to).
682
682
  - ⛔ **Component styles never come from your source either**: a line like `import "@linkdesk/ui/index.css"` (or its dist / `@import` form) is failed by the SDK lint leg `linkdesk/no-ui-css-import`, with **no exemption exit** — baking the styles into your plugin means "the shell restyles once, the whole ecosystem follows" stops being true for you.
683
683
  - **When you must change it**: when the shell you support moves to a version that contains this rename (how to read the version line: [19-Component Cheatsheet §2.1](19-component-cheatsheet.md) — ui version = shell version, one line). After upgrading, **grep your own CSS for the old families** in the table above: an official plugin (`settings`) had exactly one such spot and it was fixed in the same release batch.
684
684
  - **You get the same ruler** (`@linkdesk/plugin-sdk` 0.1.40 onward): your repo's lint ships with a dangling-name check—when the host renames a shared name and you didn't follow, **your own CI calls it out** (usage and fixes in [16-naming-conventions §7.6](16-naming-conventions.md)).
@@ -718,7 +718,7 @@ The three rules above govern **names**; this one governs **territory**. For cust
718
718
 
719
719
  **How it is enforced mechanically**: run `npm run lint` in the plugin project root (or `npm run verify` in CI) and each occurrence is reported—🔴 turns CI red, 🟡 only prints. When "it works locally but CI is red", read this section first.
720
720
 
721
- > 🔧 **Maintainer note (authors may skip)**: the rule text (including how the host registers its contract blocks and the floating-layer host exception) lives under `docs/02-Electron架构/E6_插件生态与发布/01-插件独立构建/样式命名空间归一化/`; the shell side is guarded by `scripts/check-css-namespace.mjs`, the plugin side by the SDK's `check-css-namespace` leg (token scope is the third criterion of that same leg, sharing one disable-comment id with the class-name and keyframe criteria).
721
+ > 🔧 **Maintainer note (authors may skip)**: the rule text (including how the host registers its contract blocks and the floating-layer host exception) lives under `docs/02-Electron架构/插件生态与发布/01-插件独立构建/样式命名空间归一化/`; the shell side is guarded by `scripts/check-css-namespace.mjs`, the plugin side by the SDK's `check-css-namespace` leg (token scope is the third criterion of that same leg, sharing one disable-comment id with the class-name and keyframe criteria).
722
722
 
723
723
  ### 12.6 The selector itself needs a "landing spot" too—**anchorless selectors are forbidden** (2026-09-16)
724
724
 
@@ -759,7 +759,7 @@ button { border: none; }
759
759
 
760
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
- > 🔧 **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`).
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架构/插件生态与发布/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
 
764
764
  ---
765
765
 
@@ -693,5 +693,5 @@ A plugin that fails any validation does not block other plugins from loading.
693
693
 
694
694
  - `04-distribution-format.md` — distribution/installation/version compatibility
695
695
  - `09-plugin-directory-layout.md` — source directory structure and naming conventions
696
- - [Third-party author journey](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/05-文档与发布/00-第三方作者旅程.md) — the complete path from zero to publication
696
+ - [Third-party author journey](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/05-文档与发布/00-第三方作者旅程.md) — the complete path from zero to publication
697
697
  - `plugin.schema.json` — the JSON Schema file in the same directory (the authoritative version, one of the three-copy gate)
@@ -192,7 +192,7 @@ useEffect(() => {
192
192
  ```typescript
193
193
  // Query — returns a DTO (serializable public fields; render/actions are stripped)
194
194
  const views = await window.linkdesk.viewContainer.getViews("explorer"); // ViewDto[]
195
- const view = await window.linkdesk.viewContainer.getView("folders"); // ViewDto | undefined
195
+ const view = await window.linkdesk.viewContainer.getView("file-tree", "folders"); // composite addressing (pluginId, viewId) — collision-proof; ViewDto | undefined
196
196
  const container = await window.linkdesk.viewContainer.getViewContainer("explorer");
197
197
 
198
198
  // Update metadata — the title follows the data (aligned with VS Code's registerViews update)
@@ -1,6 +1,6 @@
1
1
  # 11-Authoring Themes (third-party theme plugin author guide)
2
2
 
3
- > **Status:** final (2026-08-23) — the schema is frozen ([05](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/05-主题数据模型.md) decisions A-F).
3
+ > **Status:** final (2026-08-23) — the schema is frozen; `colorways[]` is the only way to write it.
4
4
  > **In one line:** a theme = a kind of plugin — one recipe json (style domain + colorway variants) + optional assets; a "domain contributor" inherits the default for any domain it leaves out, so the less you write the more stable it is.
5
5
  > **AI-friendliness:** the readers of this doc = **humans + AI** — an AI reading it can produce valid theme files, and an AI reading an example theme (such as the migrated mint-soda) can imitate equivalents. Every schema concept has exactly one way to be written (decision F: always `colorways[]`).
6
6
  > **2026-09-06 reconciliation with the implementation** (audit): flattened single root (no plugins/{builtin,user}) · shared controls via @linkdesk/ui · distribution = .linkdesk-plugin zip. References to the corresponding mechanisms have been removed from this page.
@@ -9,8 +9,8 @@
9
9
 
10
10
  - A theme is a **plugin** (hard constraint 10: the shell hard-codes no plugin id; themes also go through a plugin.json declaration).
11
11
  - One theme plugin = 1 recipe json (`appearance` style domain + `colorways[]` colorway variants). It may also contain multiple recipe json files.
12
- - **Domain contributor**: write only the domains you own; the rest inherit the shell defaults ([03 Domain Contributors](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/03-域贡献者与混搭.md)) — a pure-color theme = colors only; a glass theme = glass + colors.
13
- - **Style vs. colorway separation**: if you want "1 style base + N colorways" → put `colorways[]` in one recipe ([05 §2](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/05-主题数据模型.md) for the complete schema).
12
+ - **Domain contributor**: write only the domains you own; the rest inherit the shell defaults (sparse override detailed in [themes/02-theme-field-index §5](themes/02-theme-field-index.md)) — a pure-color theme = colors only; a glass theme = glass + colors.
13
+ - **Style vs. colorway separation**: if you want "1 style base + N colorways" → put `colorways[]` in one recipe (the full field table is in [themes/02-theme-field-index](themes/02-theme-field-index.md); the machine-readable authority is the `theme.schema.json` that ships with the SDK).
14
14
 
15
15
  ## 2. Writing a theme (create the directories first → three steps)
16
16
 
@@ -65,7 +65,7 @@ theme-myglass/
65
65
  // live in their own repos with the same project shape as third parties; the in-repo
66
66
  // "../../../public/schemas/…" relative form **became void when the source moved out**.
67
67
  // Malformed-input interception: editor IntelliSense + the SDK's validateThemeJson (the same channel for npm projects and the official plugin repo)
68
- // Full schema in [05 §2](../02-Electron架构/E5.8_归一化基建/外观主题化/05-主题数据模型.md); the runtime parseThemeRecipe toast is the second line of defense
68
+ // Full field table in "themes/02-theme-field-index" and the SDK's theme.schema.json; the runtime parseThemeRecipe toast is the second line of defense
69
69
  {
70
70
  "id": "myglass", "name": "My Glass", "type": "dark",
71
71
  "appearance": {
@@ -127,8 +127,8 @@ theme-liquid-glass/
127
127
 
128
128
  | Domain | How to write it | Notes |
129
129
  |:--|:--|:--|
130
- | radius | six size steps | `--radius-pill`/`--radius-full` form values are not written here (excluded from the scale, [08 §3](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/08-持久化与配置.md)) |
131
- | glass | material keys + floating form | specular/morph = liquid glass's "specular highlight / response" ([02 §2.3](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/02-变量契约.md) material positioning); radius/shadow = floating corner radius / drop shadow (merged into glass after the surface domain was removed; inset is host-derived and border is not a field) |
130
+ | radius | six size steps | `--radius-pill`/`--radius-full` form values are not written here (excluded from the scale domain) |
131
+ | glass | material keys + floating form | specular/morph = liquid glass's "specular highlight / response"; radius/shadow = floating corner radius / drop shadow (inset is host-derived and border is not a field) |
132
132
  | font | ui asset path + mono system family name | asset fonts take two steps: first register the family name with @font-face → then write `--font-ui` |
133
133
  | background | image asset + opacity + mask | relative path → getPluginAssetPath (hard constraint 12) |
134
134
  | colorways | style base + N colorways | 3-4 is recommended; a single colorway is still an array with 1 item (decision F) |
@@ -143,19 +143,19 @@ theme-liquid-glass/
143
143
  | Writing a top-level `colors` (no `colorways`) | **The old format is deprecated** (decision F) — the engine reads only `colorways[]`; even a single colorway goes in an array with 1 item |
144
144
  | Writing absolute paths | Everything blows up under packaged `file://` — always relative paths + getPluginAssetPath |
145
145
  | Repeating every color | Sparse override = write only the differing keys; unwritten ones inherit `:root`, which is more stable |
146
- | Wanting to break free of the accent color | Use **your own token** (e.g. `--toggle-on-bg`) instead of reading `--accent` ([04 §6](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/04-两层调节与设置页.md)) |
147
- | Large blur values | `--glass-blur` has a performance ceiling (large-area backdrop-filter is a GPU burden) — the contract will spell out the number ([02 §2.3](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/02-变量契约.md) pending decision) |
146
+ | Wanting to break free of the accent color | Use **your own token** (e.g. `--toggle-on-bg`) instead of reading `--accent` — a self-held token doesn't shift when the shell's accent changes |
147
+ | Large blur values | `--glass-blur` has a performance ceiling (large-area backdrop-filter is a GPU burden) — don't max it out |
148
148
 
149
149
  ## 4. What theme authors get
150
150
 
151
- - Data: `window.linkdesk.theme.listRecipes()` (including colorways/preview colors) — third-party UIs can consume it too ([06 §6](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/06-主题API契约.md) pending decision 3: prefer reusing the general API).
151
+ - Data: `window.linkdesk.theme.listRecipes()` (including colorways/preview colors) — third-party UIs can consume it too.
152
152
  - Applying: `setRecipe`/`setColorway`, or writing the `app.theme` configuration directly.
153
153
  - Events: `theme:changed` (the payload carries tokens) for live reactions.
154
- - Mix-and-match: your theme automatically shows up among the mix-and-match sources in the settings page according to the domains it contributes (`RecipeMeta.domains`), with **zero extra work for the author** ([10 §2](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/10-混搭设计.md)).
154
+ - Mix-and-match: your theme automatically shows up among the mix-and-match sources in the settings page according to the domains it contributes (`RecipeMeta.domains`), with **zero extra work for the author**.
155
155
 
156
156
  ## 5. Migration (existing theme plugins — decision F: zero backward compatibility)
157
157
 
158
- The engine **reads only the new format** (`colorways[]`); the old flat format is no longer read ([05 §5](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/05-主题数据模型.md)). Converting existing theme plugins:
158
+ The engine **reads only the new format** (`colorways[]`); the old flat format is no longer read. Converting existing theme plugins:
159
159
 
160
160
  | Plugin | Current state | After migration |
161
161
  |:--|:--|:--|
@@ -167,7 +167,7 @@ Conversion = **pure data editing** (wrapping `colors` in a `colorways[]` array),
167
167
 
168
168
  ## 6. Related
169
169
 
170
- - Authoritative schema: [05-Theme Data Model](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/05-主题数据模型.md)
171
- - Authoritative API: [06-Theme API Contract](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/06-主题API契约.md)
172
- - Theme appearance doc set: [Appearance Theming README](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/README.md)
170
+ - Field authority (author-facing): [themes/02-theme-field-index](themes/02-theme-field-index.md) — domain→CSS variable mapping, color token naming, sparse override
171
+ - Schema authority (machine-readable): `schemas/theme.schema.json` shipped with `@linkdesk/plugin-sdk` (same source as `$schema` injection and the SDK's `validateThemeJson`)
172
+ - API authority: [01-plugin-api-contract](01-plugin-api-contract.md), the `theme` domain (`listRecipes`/`setRecipe`/`setColorway`)
173
173
  - General plugin specs: [06-plugin-json-spec](06-plugin-json-spec.md) / [03-contributes-spec](03-contributes-spec.md)
@@ -42,7 +42,7 @@ Running `npm create linkdesk-plugin@latest` with no arguments asks for the plugi
42
42
  A new directory shows `plugin.json` + `src/index.tsx`, and placeholders like `{{pluginName}}` in `plugin.json` have **been replaced with your real plugin name** (`pluginId` / `name` / `description` / `author` are filled in too, with `author` defaulting to `git config user.name`). The CLI prints a line telling you **whether a git repo was created**: if it was, `git log` has one "initial skeleton" commit and the branch is called `main`.
43
43
 
44
44
  **Which doc has the details**
45
- [02-plugin-dev-toolchain/01-create-linkdesk-plugin-scaffold.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/01-create-linkdesk-plugin脚手架.md) — the **file-by-file contract** for the generated output (why each file exists, the placeholder rules, the roles of the 16 template files). **Don't look for the project structure here**; that doc is the single source of truth.
45
+ [02-plugin-dev-toolchain/01-create-linkdesk-plugin-scaffold.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/02-插件开发工具链/01-create-linkdesk-plugin脚手架.md) — the **file-by-file contract** for the generated output (why each file exists, the placeholder rules, the roles of the 16 template files). **Don't look for the project structure here**; that doc is the single source of truth.
46
46
 
47
47
  > ✅ **Repo creation (shipped 2026-09-14)**: the scaffold **creates the git repo for you** — following the three `cargo new` semantics, **not "always `git init`"**:
48
48
  > - the project directory is **not inside any git repo** ⇒ `git init -b main` automatically + **one initial commit** (the template ships a `.gitignore`, so your first step isn't a screenful of untracked files);
@@ -67,7 +67,7 @@ npm run dev # = linkdesk-plugin-sdk dev
67
67
  A browser opens the dev host page automatically, showing the template's built-in **"Plugin is running ✨"**. Now edit the text in `src/index.tsx` and save — **the page updates instantly** (HMR, no restart).
68
68
 
69
69
  **Which doc has the details**
70
- [02-local-preview-environment.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/02-本地预览环境.md) — what the dev host is, why the author side needs zero configuration, and HMR's boundaries. This step **does not start the LinkDesk app**; it only runs the plugin's own preview host.
70
+ [02-local-preview-environment.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/02-插件开发工具链/02-本地预览环境.md) — what the dev host is, why the author side needs zero configuration, and HMR's boundaries. This step **does not start the LinkDesk app**; it only runs the plugin's own preview host.
71
71
 
72
72
  ---
73
73
 
@@ -168,7 +168,7 @@ npm run dev:real # = linkdesk-plugin-sdk dev --real
168
168
  You can see your plugin in the LinkDesk app, behaving the same as in the preview. **One boundary to note**: an installed plugin runs the **prebuilt bundle**, so any source change requires a rebuild to take effect — that's not a bug, it's distribution discipline.
169
169
 
170
170
  **Which doc has the details**
171
- [04-author-real-machine-debug-loop.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/04-作者真机调试环.md) — how the real-machine loop automates "rebuild + write directly", and why changing the bundle of an installed plugin doesn't count as a hot update.
171
+ [04-author-real-machine-debug-loop.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/02-插件开发工具链/04-作者真机调试环.md) — how the real-machine loop automates "rebuild + write directly", and why changing the bundle of an installed plugin doesn't count as a hot update.
172
172
 
173
173
  ---
174
174
 
@@ -187,7 +187,7 @@ npm run build
187
187
 
188
188
  **Which docs have the details**
189
189
  - Distribution format and install flow → [04-distribution-format](04-distribution-format.md)
190
- - The byte-level format spec inside the zip → [01-plugin-standalone-build/02-linkdesk-plugin-format-spec.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/01-插件独立构建/02-linkdesk-plugin格式规范.md)
190
+ - The byte-level format spec inside the zip → [01-plugin-standalone-build/02-linkdesk-plugin-format-spec.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/01-插件独立构建/02-linkdesk-plugin格式规范.md)
191
191
  - Rules for images/GIFs/videos in a README → [12-readme-media-contract](12-readme-media-contract.md)
192
192
 
193
193
  ---
@@ -249,8 +249,8 @@ env:
249
249
  Step one: your `.linkdesk-plugin` asset shows up on the GitHub Release. Step two: once your entry is in the official catalog, **on a clean machine (default configuration, no marketplace sources added)** it can be found in the marketplace, installed, and updated — that's the criterion for "listing complete".
250
250
 
251
251
  **Which docs have the details**
252
- - The full chain (local → GitHub → the user's machine) → [03-plugin-release-pipeline.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/03-插件发布流水线.md)
253
- - The end-to-end journey from an author's perspective → [05-docs-and-release/00-third-party-author-journey.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/05-文档与发布/00-第三方作者旅程.md)
252
+ - The full chain (local → GitHub → the user's machine) → [03-plugin-release-pipeline.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/02-插件开发工具链/03-插件发布流水线.md)
253
+ - The end-to-end journey from an author's perspective → [05-docs-and-release/00-third-party-author-journey.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/05-文档与发布/00-第三方作者旅程.md)
254
254
 
255
255
  ---
256
256
 
@@ -260,7 +260,7 @@ Nothing to set up — but "should I test this?" deserves a straight answer.
260
260
 
261
261
  - **The toolchain is preinstalled.** `vitest` / `jsdom` / `@testing-library/react` are already in `devDependencies` — write `src/__tests__/<same-name>.test.ts` and run `npm run test`.
262
262
  - **The shared test ground comes from the SDK.** The minimal `window.linkdesk` mock lives in `@linkdesk/plugin-sdk/vitest-setup`, and your `vitest.setup.ts` is a **one-line pointer** to it. ⛔ **Do not paste a second copy into your repo** — a copied mock silently drifts from the shared one.
263
- - **Pure logic is what pays off.** A unit under `src/**/*.ts` that touches neither React nor `window.linkdesk` should get a test. Views and interactions are worth testing **when it pays off** — nothing measures that today.
263
+ - **Pure logic is what pays off.** A unit under `src/**/*.ts` that touches neither React nor `window.linkdesk` should get a test. Views and interactions are worth testing **when it pays off**. ⚠️ **Zero tests get flagged**: the scaffold's built-in CI runs `@linkdesk/plugin-sdk/test-audit` in its section ⑥ — a pure-logic unit with no test turns the build red (criteria in the next bullet; declarative plugins are exempt).
264
264
  - **What counts as "covered" — two criteria, both mechanical.** A unit is covered when a test file shares its basename (`Foo.ts` ↔ `Foo.test.ts`) **or** any test file references it (a direct import or through a barrel). Grep is enough to self-check: `grep -rl "Foo" src/__tests__/`. Watch out for the false alarm: a unit exercised only *through* another tested module (the same-basename criterion cannot see cross-file coverage) is not "untested" — read what your tests actually cover before adding more.
265
265
  - **Views: smoke-test when it pays off.** The cheap, honest pattern is two assertions — the component **renders without crashing** and **one key interaction works** (click → the expected callback fires). Stub `react-i18next` with a fake `t` that echoes the key, stub the slice of `window.linkdesk` your view reads in your own test file (minimal surface), and keep fixtures fictional. Nobody is expected to chase deep UI coverage.
266
266
  - **Plugin-specific stubs stay in your own test files.** Does your code call something the shared mock does not cover (say `window.linkdesk.serial`)? Stub it with `vi.fn()` in the test that needs it — do not expect the shared mock to grow a branch for your plugin.
@@ -281,7 +281,7 @@ npm run test # vitest run — an empty suite passes on purpose (passWithNoTe
281
281
  |---|---|---|
282
282
  | When the theme switches, my UI colors don't follow | Hardcoded hex | Iron rule 2 · [00-readme](00-readme.md#hard-constraints--before-you-write-any-plugin-code) |
283
283
  | Switch away from a tab and back: state is lost / content is empty | You conditionally rendered on `isActive` — under keep-alive it shouldn't unmount | [05-ui-conventions](05-ui-conventions.md) |
284
- | After `npm run build` the installed plugin still behaves the old way | Installed plugins run the prebuilt bundle; source changes need a rebuild | Step 7 · [04-author-real-machine-debug-loop.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/04-作者真机调试环.md) |
284
+ | After `npm run build` the installed plugin still behaves the old way | Installed plugins run the prebuilt bundle; source changes need a rebuild | Step 7 · [04-author-real-machine-debug-loop.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/02-插件开发工具链/04-作者真机调试环.md) |
285
285
  | The details page says "No changelog provided for this version" | The version went +1 but `CHANGELOG.md` didn't get a new section | Step 8 |
286
286
  | The plugin details page description area is empty | The description comes from the `README.md` file, and **`plugin.json` has no `readme` field** | [09-plugin-directory-layout](09-plugin-directory-layout.md) · [06-plugin-json-spec](06-plugin-json-spec.md) |
287
287
  | My context menu's styling doesn't match the shell | You hand-wrote the context menu | Step 6 · [05-ui-conventions](05-ui-conventions.md) |
@@ -35,7 +35,7 @@ Three roles: **data source** (terminal/serial/network) → **protocol** (encode/
35
35
  | Protocol | `<pluginId>.decode` | `modbus.decode` |
36
36
 
37
37
  **Rules:**
38
- - Prefix = plugin ID (the `id` field in `plugin.json`)
38
+ - Prefix = the plugin identity (the `pluginId` field in `plugin.json` — not the per-entry `id`)
39
39
  - Action name = a verb (`sendBytes` / `encode` / `parse` / `decode`)
40
40
  - A data source is not named `send` — too vague. Byte-level push is `sendBytes`
41
41
  - `onData` is an event (Emitter), not a command — it goes through CoreEvents rather than the CommandRegistry. It is listed here only for naming consistency
@@ -39,7 +39,7 @@ E:\linkdesk-plugins\
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>` (the text lives in [plugin-source-externalization/09-naming-conventions.md §5](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md) — maintained in that one place only); third parties may do as they please.
42
+ - **A recommended but non-mandatory convention**: official plugin repos uniformly use `linkdesk-plugin-<id>` (the text lives in [plugin-source-externalization/09-naming-conventions.md §5](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/插件源码外移层/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
  ---
@@ -54,7 +54,7 @@ Three "names" that have nothing to do with one another; conflating them is the r
54
54
  | **Display name** (`plugin.json`'s `name`) | What people see in the UI and on marketplace cards | ✅ **Change freely** (bump and republish when done) |
55
55
  | **Repository name** | The project repo on GitHub | ✅ Free (costs as per the previous section) |
56
56
 
57
- Benchmarked against the empirically verified VS Code position (`ms-vscode.cpptools`: identity = `publisher.name`, immutable; `displayName` = freely changeable; repository name unrelated to identity) → full measurement and reasoning → [plugin-source-externalization/09-naming-conventions.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md); the author-facing rule text → [16-naming-conventions](16-naming-conventions.md).
57
+ Benchmarked against the empirically verified VS Code position (`ms-vscode.cpptools`: identity = `publisher.name`, immutable; `displayName` = freely changeable; repository name unrelated to identity) → full measurement and reasoning → [plugin-source-externalization/09-naming-conventions.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/插件源码外移层/09-命名规范.md); the author-facing rule text → [16-naming-conventions](16-naming-conventions.md).
58
58
 
59
59
  ---
60
60
 
@@ -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 and the VS Code empirical evidence live in [plugin-source-externalization/09-naming-conventions.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md) — this document is the author-facing landing point, and of the two there is **only one place to maintain**: change the rule here first and point back; don't create a second copy.
4
+ > The decision rationale and the VS Code empirical evidence live in [plugin-source-externalization/09-naming-conventions.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/插件源码外移层/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
 
@@ -39,7 +39,7 @@
39
39
  - **How do I choose an id?** Character set per the table above; **immutable once published** — it = install directory name + uninstall record key + update reconciliation key, so swapping the id is swapping in a different plugin (old data appears lost, the update chain breaks silently). **Write `"pluginId"` explicitly in `plugin.json`**; don't rely on the directory-name fallback.
40
40
  - **Can I change the id?** No. If you want a different name, change the display name.
41
41
  - **How do I change the display name?** `plugin.json`'s `name` can be changed freely; when done, **bump the version and republish** (an installed user's copy is frozen per version, so others won't see the new name otherwise).
42
- - **What should the repo be called?** Completely free; no prefix is enforced. Official plugins are recommended to uniformly use `linkdesk-plugin-<id>` (the convention 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 only there once settled); third parties may do as they please.
42
+ - **What should the repo be called?** Completely free; no prefix is enforced. Official plugins are recommended to uniformly use `linkdesk-plugin-<id>` (the convention text lives in [plugin-source-externalization/09-naming-conventions.md §5](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/插件源码外移层/09-命名规范.md), maintained only there once settled); third parties may do as they please.
43
43
 
44
44
  ---
45
45
 
@@ -221,4 +221,4 @@ menu items **never appear**—silently, on both the declarative and the imperati
221
221
 
222
222
  ---
223
223
 
224
- > **← Index:** [00-readme](00-readme.md) · **Related:** [15-multi-repo-and-local-workspace](15-multi-repo-and-local-workspace.md) · [06-plugin-json-spec](06-plugin-json-spec.md) · [plugin-source-externalization/09-naming-conventions.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md) (decision rationale)
224
+ > **← Index:** [00-readme](00-readme.md) · **Related:** [15-multi-repo-and-local-workspace](15-multi-repo-and-local-workspace.md) · [06-plugin-json-spec](06-plugin-json-spec.md) · [plugin-source-externalization/09-naming-conventions.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/插件源码外移层/09-命名规范.md) (decision rationale)
@@ -137,9 +137,9 @@ appearance.<domain>.<key> write only the keys you want to change → unwritt
137
137
  | What you're looking up | Where to go |
138
138
  |:--|:--|
139
139
  | The type/enum/description of every recipe field | `theme.schema.json` · `schemas/theme.schema.json` inside the SDK package |
140
- | What variables mean and their defaults (font/radius/glass/background/shadow) | repo `docs/02-Electron架构/E5.8_归一化基建/外观主题化/02-变量契约.md` |
141
- | The data model (the three concepts: recipe / colorway variant / domain) | repo `docs/02-Electron架构/E5.8_归一化基建/外观主题化/05-主题数据模型.md` |
142
- | The theme API and events (`setRecipe` / `theme:changed`) | repo `docs/02-Electron架构/E5.8_归一化基建/外观主题化/06-主题API契约.md` |
140
+ | What variables mean and their defaults (font/radius/glass/background/shadow) | §2 of this doc (domain→variable mapping) + the shell's default `:root` on the next row |
141
+ | The data model (the three concepts: recipe / colorway variant / domain) | §1 (recipe top level) / §2 (domains) / §5 (sparse inheritance) of this doc |
142
+ | The theme API and events (`setRecipe` / `theme:changed`) | [01-plugin-api-contract](https://github.com/Encaron/linkdesk/blob/electron/docs/01-plugin-api-contract.md), the `theme` domain + the `theme:changed` row of the §3.2 broadcast-events table |
143
143
  | The full table of the shell's default tokens | `:root` in the repo's `src/index.css` |
144
144
 
145
145
  > All of the above are reachable on GitHub; **inside your plugin project, the only one within arm's reach is `theme.schema.json` in the SDK package** — point `$schema` at it to get editor completion and validation errors.
@@ -189,5 +189,5 @@ npm run publish # 发布到你自己的 GitHub 仓(上
189
189
  ## 相关
190
190
 
191
191
  - 契约类型真相源:`@linkdesk/contracts` 包内 `linkdesk.d.ts`(随 SDK 到达)
192
- - 主题系统设计文档(**壳的为什么**,作者不必读):仓库 `docs/02-Electron架构/E5.8_归一化基建/外观主题化/`
192
+ - 主题系统设计文档(**壳的为什么**,作者不必读):仓库 `docs/02-Electron架构/归一化基建/外观主题化/`
193
193
  - Tauri 时代旧版文档:`docs/01-Tauri_P1至P5.5/`(仅历史参考)
@@ -23,7 +23,7 @@
23
23
 
24
24
  ## 二、壳 vs 插件——API 差异
25
25
 
26
- 插件与壳在同一个渲染进程中运行,但注入的命名空间面不同。**每一面在哪个进程可用、池/壳/mock 四面覆盖如何——唯一真相源是[命名空间矩阵 §2 覆盖表](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/契约生成/命名空间矩阵.md#2-命名空间--四面覆盖矩阵)**,这里不再手写第二份清单。
26
+ 插件与壳在同一个渲染进程中运行,但注入的命名空间面不同。**每一面在哪个进程可用、池/壳/mock 四面覆盖如何——唯一真相源是[命名空间矩阵 §2 覆盖表](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/归一化基建/契约生成/命名空间矩阵.md#2-命名空间--四面覆盖矩阵)**,这里不再手写第二份清单。
27
27
 
28
28
  几个要点(矩阵 §2 的摘要,细节以矩阵为准):
29
29
 
@@ -47,7 +47,7 @@
47
47
  - **生成源:** `src/core/api/linkdesk-api.ts` + `linkdesk-api/`(15 域接口)+ `src/core/types/ipc/*` + `src/core/types/pool/*`(wire 载荷类型)
48
48
  - **生成器:** `scripts/generate-contract.mjs`(Route C——契约类型文件为源,纯类型打包单文件)
49
49
  - **机械门禁:** preload 双端 `satisfies` 契约面类型 → tsc 漂移门禁;`npm run check` 内 `contracts:check` hash 字节比对
50
- - **覆盖矩阵:** 每个命名空间 × 池/壳/mock 四面覆盖 → [命名空间矩阵 §2](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/契约生成/命名空间矩阵.md#2-命名空间--四面覆盖矩阵)
50
+ - **覆盖矩阵:** 每个命名空间 × 池/壳/mock 四面覆盖 → [命名空间矩阵 §2](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/归一化基建/契约生成/命名空间矩阵.md#2-命名空间--四面覆盖矩阵)
51
51
 
52
52
  ### 3.1 插件侧怎么消费
53
53
 
@@ -93,6 +93,9 @@ async function list(): Promise<FileEntry[]> {
93
93
  | **tabs** | **跨窗资源事件联动:** `updateLabelBySourceId(sourceId, label)` / `closeBySourceId(sourceId)` = **全窗广播语义**——资源持有者在主窗与全部脱出窗的标签页同步更新/关闭;`sourceId` 为全局唯一资源身份(文件路径/会话 id),变更即全局事实(联动**不依赖调用方与标签页同窗**——脱出窗标签随侧栏改名/删除即时联动,对标 VS Code)。`focusBySourceId(sourceId)` = **按来源窗路由**(视图动作,聚焦到具体某窗,非全局事实)。**无新 API**——复用既有面,此行为契约由全窗广播保证 |
94
94
  | **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 插件自注册 |
95
95
  | **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 结构化克隆 ⇒ 只能放可克隆数据 |
96
+ | **search** | 全文搜索/替换——`searchFiles(opts)` 一发一收,经 IPC 由壳/主进程执行(插件侧零本地扫描);请求/结果形状以契约 `SearchWireOptions`/`SearchWireResult` 为准 |
97
+ | **encoding** | 编码检测/转换三件套(主进程 EncodingService 代办):`detect(buffer)` 猜编码名 / `decode(buffer, encoding)` 字节→文本 / `encode(text, encoding)` 文本→字节——`Uint8Array` 进出 |
98
+ | **update** | **只读更新态**:`getState()` 返回宿主更新状态机全量快照(`uninitialized`/`disabled`/`idle`/`checking`/`available`/`downloading`/`downloaded`/`updating`/`ready` 九态判别联合,载荷以契约 `UpdateState` 为准);**永不抛**(服务必然有态)。供「关于」类插件展示版本/更新进度——**只读**:触发下载/安装是壳自己的事(宿主 `update.*` 命令段,插件不补命令) |
96
99
 
97
100
  **壳广播事件(插件可订阅,走 `events.on`):**
98
101
 
@@ -8,7 +8,7 @@
8
8
 
9
9
  ## 一、两条加载路径——repo 源码树(HMR)与安装态(bundle)
10
10
 
11
- 启动扫描与文件监听都能发现插件,**统一走 `loadPlugin(pluginId, reason)` 唯一入口**(E5 归一化——调用方不再自己判断"该走哪条路"):
11
+ 启动扫描与文件监听都能发现插件,**统一走 `loadPlugin(pluginId, reason)` 唯一入口**(壳已归一化——调用方不再自己判断"该走哪条路"):
12
12
 
13
13
  | 路径 | 来源 | manifest 怎么读 | JS 入口怎么加载 |
14
14
  |------|------|----------------|----------------|
@@ -2,7 +2,7 @@
2
2
 
3
3
  > 2026-07-24 · 2026-08-21 更新 · **2026-09-06 全量重写(塌平单根 + zip 单文件分发)**。
4
4
  > **插件怎么交付、怎么安装、版本兼容规则。** 对标 VS Code 的 `.vsix`——LinkDesk 用 **`.linkdesk-plugin` 单文件 zip** 分发。
5
- > 打包格式细节的真相源 = [01-插件独立构建/02-linkdesk-plugin格式规范.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/01-插件独立构建/02-linkdesk-plugin格式规范.md)(本页只讲作者侧的交付/安装/版本故事)。
5
+ > 打包格式细节的真相源 = [01-插件独立构建/02-linkdesk-plugin格式规范.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/01-插件独立构建/02-linkdesk-plugin格式规范.md)(本页只讲作者侧的交付/安装/版本故事)。
6
6
 
7
7
  ---
8
8
 
@@ -22,7 +22,7 @@ my-plugin/
22
22
  └── src/ … ← 作者源码(不进 zip)
23
23
  ```
24
24
 
25
- **谁产 zip:** [plugin-sdk](https://github.com/Encaron/linkdesk/tree/electron/packages/plugin-sdk)(`npm run publish` 走 [E6 作者旅程](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/05-文档与发布/00-第三方作者旅程.md))在**项目根**产 `<id>.linkdesk-plugin` + 解包目录 `dist/<id>.linkdesk-plugin/`。zip 内 JS 全部预构建自包含(react 系 external,壳提供)——**安装态没有源码编译**。
25
+ **谁产 zip:** [plugin-sdk](https://github.com/Encaron/linkdesk/tree/electron/packages/plugin-sdk)(`npm run publish` 走 [作者旅程](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/05-文档与发布/00-第三方作者旅程.md))在**项目根**产 `<id>.linkdesk-plugin` + 解包目录 `dist/<id>.linkdesk-plugin/`。zip 内 JS 全部预构建自包含(react 系 external,壳提供)——**安装态没有源码编译**。
26
26
 
27
27
  **为什么是单文件:** 壳 loader 对安装态插件只认预构建 bundle——`plugin-file-service` 检测到 `index.bundle.js` 存在即覆盖 entry 指向它(`resolveEntry`,bundle 入口恒 `index.bundle.js`)。zip 是「一个插件 = 一个可下载/可校验/可原子替换的文件」,装卸与市场下载都对着它。
28
28
 
@@ -51,13 +51,13 @@ 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`) | **全部发货插件**(今天 16 只)——一只一个仓,源码真相源只此一处 |
54
+ | **插件自己的仓** | GitHub `Encaron/linkdesk-plugin-<id>`(克隆到你喜欢的任意本地目录即可) | 源码 + SDK build(`npm run build` → `<id>.linkdesk-plugin`) | ✅(`linkdesk-plugin-sdk dev`) | **全部发货插件**——一只一个仓,源码真相源只此一处 |
55
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`)与**文档档案**,不是源码。
59
59
 
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)。
60
+ > **真机环例外(作者 dev):** 安装态改包需「重 build + 重装/重物化」在**作者每次真机验证**场景 = WPF v2 一次性循环痛苦。真机环自动化它——SDK 秒级重建 + **直写** `{userData}/plugins/<id>`(同盘覆盖语义,reload 即生效)成循环,作者仍不碰壳。分发 zip 的「不自改 bundle」纪律不变(那是给终用户的包)。设计档案 → [04-作者真机调试环.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/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
63
  > 🔵 **核对结论(`.disabled/` 坟场还有没有消费者)**:**机制仍在、当前无对象**。消费者是活的——`src/pluginLoader/loader.ts` 读它(`reinstallPlugin` / 卸载 toast 的「撤销」/ 跨重启孤儿清理都以 `env.appPluginsDir/.disabled` 为唯一权威面)。但 `env.appPluginsDir` = 壳仓 `plugins/`,而发货插件已外移 ⇒ 那里只剩一只夹具,**没有「在 repo 源码树里被卸载的 app 插件」了**。⇒ 机制**保留**(它是仓内插件 dev 路径的一部分,删它要动 loader 三处 + 主进程扫描面,风险大于收益),但**不要**再把它当成发货插件的可撤销卸载通道。
@@ -107,7 +107,7 @@ my-plugin/
107
107
  - **机械门禁(SDK lint)**:运行时消费 `@linkdesk/ui` ⇒ `plugin.json` 必须声明 `minAppVersion` ≥ `0.2.13`(重锚号——共享组件的集中供给自这一版才存在;`import type` 编译期擦除、豁免)。由 `linkdesk-plugin-sdk lint` 判红(`check-ui-min-app-version`),无豁免出口
108
108
  - `requires` —— 运行期依赖编排生效(缺依赖挂起 PENDING + 环 fail-loud + 连带卸载逆拓扑,见 [02 §四](02-插件生命周期.md))
109
109
  - **安装期自动装依赖(壳侧,随请求启用)**:安装请求携带来源市场目录时(市场插件随请求带条目来源 URL),`requires` 里缺失的依赖会在**同一个安装任务内**自动先装——内联递归、不占第二个并发槽;某个依赖失败 ⇒ 父任务失败并指名依赖,且父插件本次解压产物自动回滚、重试干净可用。已装的依赖跳过;禁用的**不自动启用**。作者只需声明 `requires`,无需为壳做任何适配
110
- - `permissions` —— 声明即用户知情,授权模型待 E6
110
+ - `permissions` —— 声明即用户知情,运行期授权模型尚未定案(声明不会带来额外能力)
111
111
 
112
112
  ---
113
113
 
@@ -173,4 +173,4 @@ my-plugin/
173
173
  ---
174
174
 
175
175
  > **← 上一份:** `03-插件contributes规范.md`
176
- > **→ 相关:** `02-插件生命周期.md`(安装/卸载/更新)· `09-插件目录规范.md`(源码目录)· [01-插件独立构建/02-linkdesk-plugin格式规范.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/01-插件独立构建/02-linkdesk-plugin格式规范.md)(zip 格式真相源)
176
+ > **→ 相关:** `02-插件生命周期.md`(安装/卸载/更新)· `09-插件目录规范.md`(源码目录)· [01-插件独立构建/02-linkdesk-plugin格式规范.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/01-插件独立构建/02-linkdesk-plugin格式规范.md)(zip 格式真相源)
@@ -669,7 +669,7 @@ lint 会把这种**悬空引用**逐条报出来(**文件名 + 行号 +
669
669
 
670
670
  - **谁受影响**:还是**只有你自己 CSS 里**指向这些组件的后代选择器(例如 `.settings-row:has(.theme-picker)`)。**组件自己的样式不受影响,你自己的类名也不用改。** 这件事的意义是共享组件的名字现在全在 `ldk-` 命名空间里——而那条纪律你已经知道:**凡 `ldk-` 开头都是宿主的,别拿给自己的元素用**(唯一例外是 `.ldk-input`,那个是**给你用的**工具类)。
671
671
  - **不改会怎样**:与 12.1 完全相同——选择器匹配不上,那几条规则悄悄不再生效。**不报错。**
672
- - 🔴 **宿主以后改共享名 / 改样式,你这边不必改代码、也不必改 CSS**——组件与样式**由壳池统一供给**(L9 集中供给,见 [19-组件速查 §二](19-组件速查.md)):壳升级后同一份实现跟着壳走,界面自然一致。你唯一要维持的是 `@linkdesk/ui` 依赖**别掉出当前版本线**(它决定你本地 dev 与类型解析到的那一份)。
672
+ - 🔴 **宿主以后改共享名 / 改样式,你这边不必改代码、也不必改 CSS**——组件与样式**由壳池统一供给**(壳池集中供给,见 [19-组件速查 §二](19-组件速查.md)):壳升级后同一份实现跟着壳走,界面自然一致。你唯一要维持的是 `@linkdesk/ui` 依赖**别掉出当前版本线**(它决定你本地 dev 与类型解析到的那一份)。
673
673
  - ⛔ **组件样式同样不从你的源码里来**:源码里出现 `import "@linkdesk/ui/index.css"`(或其 dist / `@import` 形态)会被 SDK 的 lint 腿 `linkdesk/no-ui-css-import` 判红——**没有豁免出口**。把样式烤进插件,等于「壳改样式、全生态跟随」对你失效。
674
674
  - **什么时候必须改**:当你要支持的壳升到含这次改名的版本时(版本线怎么读见 [19-组件速查 §2.1](19-组件速查.md)——ui 版本 = 壳版本,一条线)。升级后**拿上表里的旧族名 grep 一遍自己的 CSS**:官方插件里只有 `settings` 有 1 处,已在同一批发版改好。
675
675
  - **这把尺子你也有**(`@linkdesk/plugin-sdk` 0.1.40 起):你仓里的 lint 自带「悬空名」判据——宿主改了共享名、你没跟上时,**你自己的 CI 会替你喊**(用法与修法见 [16-命名规范 §7.6](16-命名规范.md))。
@@ -715,7 +715,7 @@ lint 会把这种**悬空引用**逐条报出来(**文件名 + 行号 +
715
715
  ——🔴 会让 CI 红,🟡 只提示不拦。「我的插件本地好好的、CI 却红」时先看这一段。
716
716
 
717
717
  > 🔧 **维护者注(作者可跳过)**:规则正文(含宿主契约块的登记方式、浮层宿主根那个例外)在
718
- > `docs/02-Electron架构/E6_插件生态与发布/01-插件独立构建/样式命名空间归一化/` 下;宿主侧由
718
+ > `docs/02-Electron架构/插件生态与发布/01-插件独立构建/样式命名空间归一化/` 下;宿主侧由
719
719
  > `scripts/check-css-namespace.mjs` 守着,插件侧由 SDK 的 `check-css-namespace` 腿守着
720
720
  > (token 作用域是那条腿的第三条判据,与类名 / 关键帧共用同一个 disable 注释 id)。
721
721
 
@@ -763,7 +763,7 @@ button { border: none; }
763
763
  的「无锚 S2 / 跨方 S3」两列)都是 **0** ⇒ **你不需要改任何东西**;这条规矩是**预防性**的。
764
764
 
765
765
  > 🔧 **维护者注(作者可跳过)**:规则正文(R0 口径 / R1 宿主基线 / R2 / R3)与判定式、负控见
766
- > `docs/02-Electron架构/E6_插件生态与发布/01-插件独立构建/样式命名空间归一化/32-任务-选择器形态轴门禁与落地.md`;
766
+ > `docs/02-Electron架构/插件生态与发布/01-插件独立构建/样式命名空间归一化/32-任务-选择器形态轴门禁与落地.md`;
767
767
  > 宿主侧由 `scripts/check-css-namespace.mjs` 的判据⑩⑪(+ 探针轴 ④ 的运行时镜像)守着,
768
768
  > 插件侧由 SDK 的 `check-css-namespace` 腿的**第四、第五条判据**守着(`checks/selector-form.ts` 的 S2/S3,
769
769
  > 与 `checks/keyframe-refs.ts` 的关键帧引用悬空 —— 后者 **2026-09-18 起**在位,SDK `≥ 0.1.37`)。
@@ -216,7 +216,7 @@ my-plugin/
216
216
  | `entry` | `string` | 入口文件路径,相对插件目录。**仅视图/标签页插件需要**——不是 schema 级必需(entryless 侧栏插件零 entry,见「图标栏出现规则」) |
217
217
  | `icon` | `string` | 图标标识——codicon/Lucide 名称或 SVG 路径(可选,缺省用默认图标) |
218
218
 
219
- > **`type` 字段已废弃**(E5.7 起不再必需,也不在 schema 必需列表)——loader 从 `entry`/`themes`/`languages`/`mode`/`resources`/`contributes` 等声明字段自动检测贡献类型。
219
+ > **`type` 字段已废弃**(不再必需,也不在 schema 必需列表)——loader 从 `entry`/`themes`/`languages`/`mode`/`resources`/`contributes` 等声明字段自动检测贡献类型。
220
220
 
221
221
  ### 可选字段
222
222
 
@@ -689,5 +689,5 @@ pluginId "app" 是宿主自己的身份(宿主用它注册配置/外观/更新
689
689
 
690
690
  - `04-插件分发格式.md` — 分发/安装/版本兼容
691
691
  - `09-插件目录规范.md` — 源码目录结构与命名约定
692
- - [E6 第三方作者旅程](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/05-文档与发布/00-第三方作者旅程.md) — 从零到发布的完整路径
692
+ - [第三方作者旅程](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/05-文档与发布/00-第三方作者旅程.md) — 从零到发布的完整路径
693
693
  - `plugin.schema.json` — 同目录 JSON Schema 文件(权威版本,三拷贝 gate 之一)
@@ -179,7 +179,7 @@ const off = await window.linkdesk.filesystem.watch('/workspace', (e) => {
179
179
 
180
180
  ## 七、终端——第一个交出数据的插件(历史参考)
181
181
 
182
- > 2026-08-21 注:本节是 E3 时代的历史记录,**终端插件的当前实现已与下述任务有出入**(数据源已归一化到数据管道)。保留作为"第一个数据源插件怎么做"的模式参考。
182
+ > 2026-08-21 注:本节是早期版本的历史记录,**终端插件的当前实现已与下述任务有出入**(数据源已归一化到数据管道)。保留作为"第一个数据源插件怎么做"的模式参考。
183
183
 
184
184
  终端插件当初把三样东西交到大厅:
185
185
 
@@ -191,7 +191,7 @@ useEffect(() => {
191
191
  ```typescript
192
192
  // 查询——返回 DTO(可序列化公开字段,render/actions 已剥)
193
193
  const views = await window.linkdesk.viewContainer.getViews("explorer"); // ViewDto[]
194
- const view = await window.linkdesk.viewContainer.getView("folders"); // ViewDto | undefined
194
+ const view = await window.linkdesk.viewContainer.getView("file-tree", "folders"); // 复合寻址 (pluginId, viewId)——精确防碰撞;ViewDto | undefined
195
195
  const container = await window.linkdesk.viewContainer.getViewContainer("explorer");
196
196
 
197
197
  // 更新元数据——标题随数据变化(对标 VS Code registerViews 更新)
@@ -1,6 +1,6 @@
1
1
  # 11-主题制作(第三方主题插件作者指南)
2
2
 
3
- > **状态:** 定稿(2026-08-23)——schema 已冻结([05](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/05-主题数据模型.md) 决策 A-F)。
3
+ > **状态:** 定稿(2026-08-23)——schema 已冻结,`colorways[]` 是唯一写法。
4
4
  > **一句话:** 主题 = 插件的一种——一个配方 json(风格域 + 配色变体)+ 可选资产;「域贡献者」缺的域继承默认,写得越少越稳。
5
5
  > **ai化 = AI 友好度:** 本文读者 = **人类 + AI**——AI 读本文能产出合法主题文件,AI 读示例主题(如迁移后的 mint-soda)能仿造同类。schema 每个概念只有一种写法(决策 F:一律 `colorways[]`)。
6
6
  > **2026-09-06 与实现对齐核对**(对账):塌平单根(无 plugins/{builtin,user})· 共享控件走 @linkdesk/ui · 分发 = .linkdesk-plugin zip。本页对应机制引用已清。
@@ -9,8 +9,8 @@
9
9
 
10
10
  - 主题是**插件**(硬约束 10:壳不写死任何插件 id,主题也走 plugin.json 声明)。
11
11
  - 一个主题插件 = 1 个配方 json(`appearance` 风格域 + `colorways[]` 配色变体)。也可包含多个配方 json。
12
- - **域贡献者**:只写你拥有的域,缺的继承壳默认([03 域贡献者](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/03-域贡献者与混搭.md))——纯配色主题 = 只写颜色;玻璃主题 = 写玻璃 + 颜色。
13
- - **风格 vs 配色分离**:想要「1 个风格基座 + N 个配色」→ 一个配方里放 `colorways[]`([05 §2](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/05-主题数据模型.md) 完整 schema)。
12
+ - **域贡献者**:只写你拥有的域,缺的继承壳默认(稀疏覆盖详见 [主题/02-主题字段速查 §五](主题/02-主题字段速查.md))——纯配色主题 = 只写颜色;玻璃主题 = 写玻璃 + 颜色。
13
+ - **风格 vs 配色分离**:想要「1 个风格基座 + N 个配色」→ 一个配方里放 `colorways[]`(字段全表见 [主题/02-主题字段速查](主题/02-主题字段速查.md);机器可读权威 = 随 SDK 分发的 `theme.schema.json`)。
14
14
 
15
15
  ## 2. 写一个主题(先建目录 → 三步)
16
16
 
@@ -64,7 +64,7 @@ theme-myglass/
64
64
  // ↑ 只有这一种写法(相对**插件自己的工程根**)。官方主题插件也住在自己的仓里,
65
65
  // 与第三方同款工程形态;仓库内那份 "../../../public/schemas/…" 的相对写法**已随源码外移作废**。
66
66
  // 格式错拦截:编辑器 IntelliSense + SDK validateThemeJson(npm 工程与官方插件仓同一条通道)
67
- // 全量 schema 见 [05 §2](../02-Electron架构/E5.8_归一化基建/外观主题化/05-主题数据模型.md);运行时 parseThemeRecipe toast 是第二道防线
67
+ // 全量字段见「主题/02-主题字段速查」与随 SDK 的 theme.schema.json;运行时 parseThemeRecipe toast 是第二道防线
68
68
  {
69
69
  "id": "myglass", "name": "My Glass", "type": "dark",
70
70
  "appearance": {
@@ -126,8 +126,8 @@ theme-liquid-glass/
126
126
 
127
127
  | 域 | 写法 | 备注 |
128
128
  |:--|:--|:--|
129
- | radius | 六档尺寸 | `--radius-pill`/`--radius-full` 形态值不在此写(scale 排除,[08 §3](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/08-持久化与配置.md)) |
130
- | glass | 材质键 + 悬浮形态 | specular/morph = 液态玻璃「反光/响应」([02 §2.3](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/02-变量契约.md) 材质定位);radius/shadow = 悬浮圆角/投影(surface 域删后并入 glass;inset 宿主派生、border 非字段) |
129
+ | radius | 六档尺寸 | `--radius-pill`/`--radius-full` 形态值不在此写(scale 域排除) |
130
+ | glass | 材质键 + 悬浮形态 | specular/morph = 液态玻璃「反光/响应」;radius/shadow = 悬浮圆角/投影(inset 宿主派生、border 非字段) |
131
131
  | font | ui 资产路径 + mono 系统族名 | 资产字体两步:先 @font-face 注册族名→写 `--font-ui` |
132
132
  | background | image 资产 + opacity + mask | 相对路径 → getPluginAssetPath(硬约束 12) |
133
133
  | colorways | 风格基座 + N 配色 | 3-4 个 = 推荐;单配色也写数组 1 项(决策 F) |
@@ -142,19 +142,19 @@ theme-liquid-glass/
142
142
  | 写顶层 `colors`(无 `colorways`) | **旧格式已弃**(决策 F)——引擎只读 `colorways[]`;单配色也写数组 1 项 |
143
143
  | 写绝对路径 | 打包后 `file://` 全炸——一律相对路径 + getPluginAssetPath |
144
144
  | 重复写全部颜色 | 稀疏覆盖 = 只写差异键,未写继承 `:root`,更稳 |
145
- | 想摆脱强调色 | 用**自己的 token**(如 `--toggle-on-bg`),不读 `--accent`([04 §6](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/04-两层调节与设置页.md)) |
146
- | 大 blur 值 | `--glass-blur` 有性能上限(大面积 backdrop-filter 是 GPU 负担)——契约会写明数值([02 §2.3](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/02-变量契约.md) 待拍板) |
145
+ | 想摆脱强调色 | 用**自己的 token**(如 `--toggle-on-bg`),不读 `--accent`——自持 token 才不受壳强调色变化影响 |
146
+ | 大 blur 值 | `--glass-blur` 有性能上限(大面积 backdrop-filter 是 GPU 负担),别拉满 |
147
147
 
148
148
  ## 4. 主题制作者能拿到什么
149
149
 
150
- - 数据:`window.linkdesk.theme.listRecipes()`(含配色/预览色)——第三方 UI 也可以消费([06 §6](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/06-主题API契约.md) 待拍板 3:通用 API 优先复用)。
150
+ - 数据:`window.linkdesk.theme.listRecipes()`(含配色/预览色)——第三方 UI 也可以消费。
151
151
  - 应用:`setRecipe`/`setColorway` 或直接写 `app.theme` 配置。
152
152
  - 事件:`theme:changed`(payload 带 tokens),做实时联动。
153
- - 混搭:你的主题按贡献的域(`RecipeMeta.domains`)自动出现在设置页混搭来源里,**作者零额外工作**([10 §2](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/10-混搭设计.md))。
153
+ - 混搭:你的主题按贡献的域(`RecipeMeta.domains`)自动出现在设置页混搭来源里,**作者零额外工作**。
154
154
 
155
155
  ## 5. 迁移(现有主题插件——决策 F:零向后兼容)
156
156
 
157
- 引擎**只读新格式**(`colorways[]`),旧格式平铺不再兼容读([05 §5](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/05-主题数据模型.md))。现有主题插件改造:
157
+ 引擎**只读新格式**(`colorways[]`),旧格式平铺不再兼容读。现有主题插件改造:
158
158
 
159
159
  | 插件 | 现状 | 迁移后 |
160
160
  |:--|:--|:--|
@@ -166,7 +166,7 @@ theme-liquid-glass/
166
166
 
167
167
  ## 6. 关联
168
168
 
169
- - schema 权威:[05-主题数据模型](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/05-主题数据模型.md)
170
- - API 权威:[06-主题API契约](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/06-主题API契约.md)
171
- - 主题外观文档包:[外观主题化 README](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/README.md)
169
+ - 字段权威(作者面):[主题/02-主题字段速查](主题/02-主题字段速查.md)——域→CSS 变量对照、颜色 token 命名、稀疏覆盖
170
+ - schema 权威(机器可读):随 `@linkdesk/plugin-sdk` 分发的 `schemas/theme.schema.json`(`$schema` 注入与 SDK `validateThemeJson` 同一源)
171
+ - API 权威:[01-插件API契约](01-插件API契约.md) `theme` 域(`listRecipes`/`setRecipe`/`setColorway`)
172
172
  - 插件一般规范:[06-plugin.json规范](06-plugin.json规范.md) / [03-插件contributes规范](03-插件contributes规范.md)
@@ -42,7 +42,7 @@ npm install
42
42
  新目录里出现 `plugin.json` + `src/index.tsx`,且 `plugin.json` 里的 `{{pluginName}}` 之类占位符**已替换成你的真实插件名**(还有 `pluginId` / `name` / `description` / `author` 已填好,`author` 默认取 `git config user.name`)。CLI 会打印一行告诉你**建没建 git 仓**:建了的话 `git log` 里有一笔「初始骨架」提交、分支叫 `main`。
43
43
 
44
44
  **细节点哪一篇**
45
- [02-插件开发工具链/01-create-linkdesk-plugin脚手架.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/01-create-linkdesk-plugin脚手架.md)——生成产物的**逐文件契约**(每个文件为什么存在、占位符规则、16 个模板文件的角色)。**项目结构不要在这里找**,那篇是唯一真相源。
45
+ [02-插件开发工具链/01-create-linkdesk-plugin脚手架.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/02-插件开发工具链/01-create-linkdesk-plugin脚手架.md)——生成产物的**逐文件契约**(每个文件为什么存在、占位符规则、16 个模板文件的角色)。**项目结构不要在这里找**,那篇是唯一真相源。
46
46
 
47
47
  > ✅ **建仓(2026-09-14 已落地)**:脚手架**代建 git 仓**——照 `cargo new` 的三条语义,**不是「一律 `git init`」**:
48
48
  > - 工程目录**不在任何 git 仓里** ⇒ 自动 `git init -b main` + **一次初始提交**(模板自带 `.gitignore`,所以你第一步看到的不是满屏 untracked);
@@ -67,7 +67,7 @@ npm run dev # = linkdesk-plugin-sdk dev
67
67
  浏览器自动打开 dev 宿主页,页面上是模板自带的 **「插件跑起来了 ✨」**。此时改 `src/index.tsx` 里的文字并保存,**页面即时变**(HMR,不用重启)。
68
68
 
69
69
  **细节点哪一篇**
70
- [02-本地预览环境.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/02-本地预览环境.md)——dev 宿主是什么、作者侧为什么零配置、HMR 边界。这一步**不开 LinkDesk 主程序**,只跑插件自己的预览宿主。
70
+ [02-本地预览环境.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/02-插件开发工具链/02-本地预览环境.md)——dev 宿主是什么、作者侧为什么零配置、HMR 边界。这一步**不开 LinkDesk 主程序**,只跑插件自己的预览宿主。
71
71
 
72
72
  ---
73
73
 
@@ -168,7 +168,7 @@ npm run dev:real # = linkdesk-plugin-sdk dev --real
168
168
  LinkDesk 主程序里能看到你的插件、行为与预览一致。**注意一个边界**:安装态插件跑的是**预构建 bundle**,改了源码必须重 build 才生效——这不是 bug,是分发纪律。
169
169
 
170
170
  **细节点哪一篇**
171
- [04-作者真机调试环.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/04-作者真机调试环.md)——真机环怎么自动化「重 build + 直写」,以及为什么安装态改 bundle 不算热更。
171
+ [04-作者真机调试环.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/02-插件开发工具链/04-作者真机调试环.md)——真机环怎么自动化「重 build + 直写」,以及为什么安装态改 bundle 不算热更。
172
172
 
173
173
  ---
174
174
 
@@ -187,7 +187,7 @@ npm run build
187
187
 
188
188
  **细节点哪几篇**
189
189
  - 分发格式与安装流程 → [04-插件分发格式](04-插件分发格式.md)
190
- - zip 内部的字节级格式规范 → [01-插件独立构建/02-linkdesk-plugin格式规范.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/01-插件独立构建/02-linkdesk-plugin格式规范.md)
190
+ - zip 内部的字节级格式规范 → [01-插件独立构建/02-linkdesk-plugin格式规范.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/01-插件独立构建/02-linkdesk-plugin格式规范.md)
191
191
  - README 里放图/动图/视频的规则 → [12-README说明区媒体契约](12-README说明区媒体契约.md)
192
192
 
193
193
  ---
@@ -249,8 +249,8 @@ env:
249
249
  第一步:GitHub Release 上出现你的 `.linkdesk-plugin` 资产;第二步:官方目录出现你的条目后,**在一台干净机器(默认配置、不加任何市场源)**上市场里搜得到、能装、能更新——这才是「上架完成」的判据。
250
250
 
251
251
  **细节点哪几篇**
252
- - 完整链路(本地 → GitHub → 用户电脑)→ [03-插件发布流水线.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/03-插件发布流水线.md)
253
- - 作者视角的端到端旅程 → [05-文档与发布/00-第三方作者旅程.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/05-文档与发布/00-第三方作者旅程.md)
252
+ - 完整链路(本地 → GitHub → 用户电脑)→ [03-插件发布流水线.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/02-插件开发工具链/03-插件发布流水线.md)
253
+ - 作者视角的端到端旅程 → [05-文档与发布/00-第三方作者旅程.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/05-文档与发布/00-第三方作者旅程.md)
254
254
 
255
255
  ---
256
256
 
@@ -260,7 +260,7 @@ env:
260
260
 
261
261
  - **工具链已预装**:`vitest` / `jsdom` / `@testing-library/react` 都在 `devDependencies` 里,写 `src/__tests__/<同名>.test.ts`,然后 `npm run test`。
262
262
  - **共享测试地基由 SDK 提供**:`window.linkdesk` 的最小 mock 住在 `@linkdesk/plugin-sdk/vitest-setup`,你仓里的 `vitest.setup.ts` 是指向它的**一行指针**。⛔ **不要在自己仓里再抄一份**——抄来的那份会与共享版**无声漂移**。
263
- - **纯逻辑最值得测**:`src/**/*.ts` 里既不碰 React、也不碰 `window.linkdesk` 的单元,应该配上测试。视图与交互**划得来时再测**——今天没有任何东西在量它。
263
+ - **纯逻辑最值得测**:`src/**/*.ts` 里既不碰 React、也不碰 `window.linkdesk` 的单元,应该配上测试。视图与交互**划得来时再测**。⚠️ **零测会被拦**:脚手架自带 CI 的第⑥段用 `@linkdesk/plugin-sdk/test-audit` 机械审计,纯逻辑单元零测试即判红(判据见下一条;声明式插件豁免)——「今天没有任何东西在量它」已成过去。
264
264
  - **「算覆盖」的判据有两条,都是机械的**:单元被覆盖 = 有**同名测试文件**(`Foo.ts` ↔ `Foo.test.ts`)**或**被任一测试文件引用到(直接 import 或经 barrel)。自查用 grep 就够:`grep -rl "Foo" src/__tests__/`。当心**假红**:某个单元只**经过**另一个被测模块间接跑到(同名判据看不见跨文件覆盖),不等于「没测」——先读你的测试实际覆盖了什么,再决定补不补。
265
265
  - **视图层:划得来时做冒烟**:便宜而诚实的样板就两条断言——组件**渲染不炸** + **一个关键交互走通**(点一下 ⇒ 预期回调被调)。替身面:`react-i18next` 用回 key 的假 `t`,视图读到的 `window.linkdesk` 那一片在**你自己的测试文件**里就地桩住(最小面),夹具全用虚构名。深度 UI 覆盖率不要求任何人追。
266
266
  - **插件专属桩住本仓**:你的代码调了共享 mock 没覆盖的东西(比如 `window.linkdesk.serial`)?在需要它的那个测试文件里用 `vi.fn()` 补上——别指望共享 mock 为你的插件长一条分支。
@@ -281,7 +281,7 @@ npm run test # vitest run——空测试集**故意**判过(passWithNoTest
281
281
  |---|---|---|
282
282
  | 主题一换,我的界面颜色不跟随 | 硬编码了 hex | 铁律 2 · [00-README](00-README.md#硬约束写任何一行插件代码前) |
283
283
  | 切走标签页再切回来,状态丢了/内容空了 | 用 `isActive` 条件渲染了——keep-alive 下不该卸载 | [05-插件UI写法规约](05-插件UI写法规约.md) |
284
- | `npm run build` 后装上去还是旧行为 | 安装态跑预构建 bundle,改源码要重 build | 第 7 步 · [04-作者真机调试环.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/04-作者真机调试环.md) |
284
+ | `npm run build` 后装上去还是旧行为 | 安装态跑预构建 bundle,改源码要重 build | 第 7 步 · [04-作者真机调试环.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/02-插件开发工具链/04-作者真机调试环.md) |
285
285
  | 详情页说「此版本未提供变更说明」 | 版本 +1 了但 `CHANGELOG.md` 没补新段 | 第 8 步 |
286
286
  | 插件详情页说明区不显示 | 说明以 `README.md` 文件为准,**`plugin.json` 里没有 `readme` 字段** | [09-插件目录规范](09-插件目录规范.md) · [06-plugin.json规范](06-plugin.json规范.md) |
287
287
  | 右键菜单样式跟壳对不上 | 手写了右键菜单 | 第 6 步 · [05-插件UI写法规约](05-插件UI写法规约.md) |
@@ -35,7 +35,7 @@
35
35
  | 协议 | `<pluginId>.decode` | `modbus.decode` |
36
36
 
37
37
  **规则:**
38
- - 前缀 = 插件 ID(`plugin.json` 的 `id` 字段)
38
+ - 前缀 = 插件身份(`plugin.json` 的 `pluginId` 字段——不是各命令条目里的 `id`)
39
39
  - 动作名 = 动词(`sendBytes` / `encode` / `parse` / `decode`)
40
40
  - 数据源不叫 `send`——太模糊。字节级推送叫 `sendBytes`
41
41
  - `onData` 是事件(Emitter),不是命令——走 CoreEvents 而非 CommandRegistry。此处列出只为命名一致性
@@ -39,7 +39,7 @@ E:\linkdesk-plugins\
39
39
 
40
40
  **仓库名不强制任何前缀,第三方零约束。** 这是拍过板的:作者给自己的插件(仓库)取名是正当权利,不能定死。
41
41
 
42
- - **建议但非强制的惯例**:官方插件仓统一 `linkdesk-plugin-<id>`(条文住 [插件源码外移层/09-命名规范.md §五](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md)——只此一处维护);第三方随意。
42
+ - **建议但非强制的惯例**:官方插件仓统一 `linkdesk-plugin-<id>`(条文住 [插件源码外移层/09-命名规范.md §五](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/插件源码外移层/09-命名规范.md)——只此一处维护);第三方随意。
43
43
  - **改仓库名的代价**:已发布 catalog 条目里的 `downloadUrl` / `readmeUrl` 内嵌 `owner/repo`,**改名会断已发布插件的下载与 README 链接**(源码本身不受影响)。改名后重发一版新条目即可自愈,但旧版本条目仍指旧链——**能不改就不改,要改趁早**。
44
44
 
45
45
  ---
@@ -54,7 +54,7 @@ E:\linkdesk-plugins\
54
54
  | **显示名**(`plugin.json` 的 `name`) | 界面、市场卡片上给人看的 | ✅ **随便改**(改完 bump 重发一版) |
55
55
  | **仓库名** | GitHub 上的工程仓 | ✅ 自由(代价见上节) |
56
56
 
57
- 对标 VS Code 的实测口径(`ms-vscode.cpptools`:身份 = `publisher.name` 永不可变,`displayName` = 随便改,仓库名与身份无关)→ 完整实测与论证 → [插件源码外移层/09-命名规范.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md);作者面规则条文 → [16-命名规范](16-命名规范.md)。
57
+ 对标 VS Code 的实测口径(`ms-vscode.cpptools`:身份 = `publisher.name` 永不可变,`displayName` = 随便改,仓库名与身份无关)→ 完整实测与论证 → [插件源码外移层/09-命名规范.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/插件源码外移层/09-命名规范.md);作者面规则条文 → [16-命名规范](16-命名规范.md)。
58
58
 
59
59
  ---
60
60
 
@@ -1,7 +1,7 @@
1
1
  # 命名规范——七种名字,一条身份
2
2
 
3
3
  > 2026-09-14 ·。**读者 = 插件作者。** 读完能回答四问:**id 怎么起?能不能改?显示名怎么改?仓库叫什么?**
4
- > 决策论证与 VS Code 实测依据住 [插件源码外移层/09-命名规范.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md)——本篇是作者面落点,两处**只维护一处**:改规则先改本篇并回指,别造第二份。
4
+ > 决策论证与 VS Code 实测依据住 [插件源码外移层/09-命名规范.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/插件源码外移层/09-命名规范.md)——本篇是作者面落点,两处**只维护一处**:改规则先改本篇并回指,别造第二份。
5
5
 
6
6
  ---
7
7
 
@@ -39,7 +39,7 @@
39
39
  - **id 怎么起?** 字符集见上表;**发布后永不可变**——它 = 安装目录名 + 卸载记录键 + 更新对账键,换了 id 等于换了一只插件(旧数据看似丢失、更新链静默断)。**在 `plugin.json` 里显式写 `"pluginId"`**,别依赖目录名兜底。
40
40
  - **能不能改 id?** 不能。想换名字改的是显示名。
41
41
  - **显示名怎么改?** `plugin.json` 的 `name` 随便改,改完 **bump 版本重发一版**(已装用户副本按版本固化,不重发别人看不到新名)。
42
- - **仓库叫什么?** 完全自由,不强制前缀。官方插件建议统一 `linkdesk-plugin-<id>`(惯例条文住 [插件源码外移层/09-命名规范.md §五](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md),拍板后只那处维护);第三方随意。
42
+ - **仓库叫什么?** 完全自由,不强制前缀。官方插件建议统一 `linkdesk-plugin-<id>`(惯例条文住 [插件源码外移层/09-命名规范.md §五](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/插件源码外移层/09-命名规范.md),拍板后只那处维护);第三方随意。
43
43
 
44
44
  ---
45
45
 
@@ -214,4 +214,4 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
214
214
 
215
215
  ---
216
216
 
217
- > **← 索引:** [00-README](00-README.md) · **相关:** [15-多仓开发与本地工作区](15-多仓开发与本地工作区.md) · [06-plugin.json规范](06-plugin.json规范.md) · [插件源码外移层/09-命名规范.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md)(决策论证)
217
+ > **← 索引:** [00-README](00-README.md) · **相关:** [15-多仓开发与本地工作区](15-多仓开发与本地工作区.md) · [06-plugin.json规范](06-plugin.json规范.md) · [插件源码外移层/09-命名规范.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/插件生态与发布/插件源码外移层/09-命名规范.md)(决策论证)
@@ -137,9 +137,9 @@ appearance.域.键 只写你要改的键 → 没写的键继承壳默认
137
137
  | 要查什么 | 去哪 |
138
138
  |:--|:--|
139
139
  | 配方所有字段的类型/枚举/描述 | `theme.schema.json` · SDK 包内 `schemas/theme.schema.json` |
140
- | 变量的语义与默认值(字体/圆角/玻璃/背景/阴影) | 仓库 `docs/02-Electron架构/E5.8_归一化基建/外观主题化/02-变量契约.md` |
141
- | 数据模型(配方 / 配色变体 / 域 三个概念) | 仓库 `docs/02-Electron架构/E5.8_归一化基建/外观主题化/05-主题数据模型.md` |
142
- | 主题 API 与事件(`setRecipe` / `theme:changed`) | 仓库 `docs/02-Electron架构/E5.8_归一化基建/外观主题化/06-主题API契约.md` |
140
+ | 变量的语义与默认值(字体/圆角/玻璃/背景/阴影) | 本篇 §二(域→变量对照)+ 下一行的壳默认 `:root` |
141
+ | 数据模型(配方 / 配色变体 / 域 三个概念) | 本篇 §一(配方顶层)/ §二(域)/ §五(稀疏继承) |
142
+ | 主题 API 与事件(`setRecipe` / `theme:changed`) | [01-插件API契约](https://github.com/Encaron/linkdesk/blob/electron/docs/01-插件API契约.md) `theme` 域 + §3.2 壳广播事件表 `theme:changed` 行 |
143
143
  | 壳的默认 token 全表 | 仓库 `src/index.css` 的 `:root` |
144
144
 
145
145
  > 上面这几份在 GitHub 上都可访问;**在你的插件工程里,唯一随手可及的是 SDK 包内的 `theme.schema.json`**——`$schema` 指向它即可获得编辑器补全与报错。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.43",
3
+ "version": "0.1.44",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [