@linkdesk/plugin-docs 0.1.0

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 (49) hide show
  1. package/README.md +58 -0
  2. package/docs/00-readme.md +189 -0
  3. package/docs/01-plugin-api-contract.md +171 -0
  4. package/docs/02-plugin-lifecycle.md +348 -0
  5. package/docs/03-contributes-spec.md +800 -0
  6. package/docs/04-distribution-format.md +172 -0
  7. package/docs/05-ui-conventions.md +549 -0
  8. package/docs/06-plugin-json-spec.md +640 -0
  9. package/docs/07-plugin-to-plugin-communication.md +299 -0
  10. package/docs/08-view-container-api.md +405 -0
  11. package/docs/09-plugin-directory-layout.md +301 -0
  12. package/docs/10-building-a-settings-plugin.md +164 -0
  13. package/docs/11-authoring-themes.md +173 -0
  14. package/docs/12-readme-media-contract.md +74 -0
  15. package/docs/13-development-guide.md +259 -0
  16. package/docs/14-data-pipeline-command-conventions.md +173 -0
  17. package/docs/15-multi-repo-and-local-workspace.md +86 -0
  18. package/docs/16-naming-conventions.md +77 -0
  19. package/docs/17-region-map.md +225 -0
  20. package/docs/18-cross-region-wiring.md +192 -0
  21. package/docs/19-component-cheatsheet.md +108 -0
  22. package/docs/20-adding-a-setting.md +159 -0
  23. package/docs/themes/01-build-a-theme-plugin.md +150 -0
  24. package/docs/themes/02-theme-field-index.md +145 -0
  25. package/docs/zh/00-README.md +189 -0
  26. package/docs/zh/01-/346/217/222/344/273/266API/345/245/221/347/272/246.md +171 -0
  27. package/docs/zh/02-/346/217/222/344/273/266/347/224/237/345/221/275/345/221/250/346/234/237.md +348 -0
  28. package/docs/zh/03-/346/217/222/344/273/266contributes/350/247/204/350/214/203.md +800 -0
  29. package/docs/zh/04-/346/217/222/344/273/266/345/210/206/345/217/221/346/240/274/345/274/217.md +172 -0
  30. package/docs/zh/05-/346/217/222/344/273/266UI/345/206/231/346/263/225/350/247/204/347/272/246.md +549 -0
  31. package/docs/zh/06-plugin.json/350/247/204/350/214/203.md +640 -0
  32. package/docs/zh/07-/346/217/222/344/273/266/351/227/264/351/200/232/344/277/241.md +299 -0
  33. package/docs/zh/08-ViewContainer-/350/247/206/345/233/276/345/256/271/345/231/250API.md +403 -0
  34. package/docs/zh/09-/346/217/222/344/273/266/347/233/256/345/275/225/350/247/204/350/214/203.md +301 -0
  35. package/docs/zh/10-/345/246/202/344/275/225/351/200/240/344/270/200/344/270/252/350/256/276/347/275/256/346/217/222/344/273/266.md +164 -0
  36. package/docs/zh/11-/344/270/273/351/242/230/345/210/266/344/275/234.md +172 -0
  37. 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 +74 -0
  38. package/docs/zh/13-/346/217/222/344/273/266/345/274/200/345/217/221/346/214/207/345/215/227.md +259 -0
  39. 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 +173 -0
  40. 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 +86 -0
  41. package/docs/zh/16-/345/221/275/345/220/215/350/247/204/350/214/203.md +77 -0
  42. package/docs/zh/17-/345/214/272/345/237/237/345/234/260/345/233/276.md +225 -0
  43. package/docs/zh/18-/345/214/272/345/237/237/351/227/264/344/272/222/345/212/250.md +192 -0
  44. package/docs/zh/19-/347/273/204/344/273/266/351/200/237/346/237/245.md +108 -0
  45. package/docs/zh/20-/346/210/221/347/232/204/346/217/222/344/273/266/345/212/240/344/270/200/346/235/241/351/205/215/347/275/256/351/241/271.md +159 -0
  46. package/docs/zh/plugin.schema.json +687 -0
  47. package/docs/zh//344/270/273/351/242/230/01-/345/201/232/344/270/200/344/270/252/344/270/273/351/242/230/346/217/222/344/273/266.md +150 -0
  48. 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 +145 -0
  49. package/package.json +20 -0
@@ -0,0 +1,172 @@
1
+ # 04 — Plugin Distribution Format
2
+
3
+ > 2026-07-24 · updated 2026-08-21 · **full rewrite 2026-09-06 (flatten to single root + single-file zip distribution)**.
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).
6
+
7
+ ---
8
+
9
+ ## 1. Distribution Format—One Single-File `.linkdesk-plugin` Zip
10
+
11
+ **A LinkDesk plugin's delivery form = one single `.linkdesk-plugin` file** (a zip package, the SDK build output). Plugin source is an ordinary directory ([09-plugin-directory-layout.md](09-plugin-directory-layout.md)), but **what gets handed to users / published to the marketplace is always that zip**—the era of directory distribution, where copying a whole directory was the install, is over (flatten-to-single-root decision, 2026-09-05).
12
+
13
+ ```
14
+ my-plugin/
15
+ ├── <id>.linkdesk-plugin ← the sole carrier for distribution/install/marketplace (zip)
16
+ │ ├── plugin.json ← rewritten clone (contributes.views[].render → views/<View>.bundle.js)
17
+ │ ├── index.bundle.js ← main entry bundle (whenever the loader sees it, it becomes the runtime entry)
18
+ │ ├── index.bundle.css ← aggregated styles
19
+ │ ├── views/<View>.bundle.js ← one independent build per contributes.views[].render
20
+ │ ├── resources/ icon.svg etc. ← resources ship inside the package
21
+ │ └── (themes/ assets/ i18n/ node_modules/ …) depending on plugin content
22
+ └── src/ … ← author source (does not go into the zip)
23
+ ```
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**.
26
+
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
+
29
+ > **The source directory and the distribution file are two different things:** development uses a directory (dev source tree with HMR), distribution uses a zip (pre-built output). Don't use a source directory as an install carrier, and don't edit a bundle inside the zip as a hot update—changed source requires a **rebuild + republish** (see §2, version discipline).
30
+
31
+ ---
32
+
33
+ ## 2. Install Flow—zip → `{userData}/plugins/<id>/`
34
+
35
+ **The install target is always `{userData}/plugins/<pluginId>/`** (`env.userPluginsDir`, where {userData} = Electron's `app.getPath('userData')`, on Windows `%APPDATA%/LinkDesk`). The installed state **has no builtin/user two-tier split**—plugins shipped with the shell and third-party plugins installed by the user lie **flat side by side in the same tree**; the only remaining difference is manifest fields (see §3).
36
+
37
+ **Two arrival paths (the same landing path):**
38
+
39
+ | Path | Who | Landing point | Semantics |
40
+ |------|------|------|------|
41
+ | **boot auto-install (one-time first-launch seed)** | `bundled-plugins/*.linkdesk-plugin` shipped with the shell (in prod, `resources/bundled-plugins`) | `{userData}/plugins/<id>/` | Decision order: ① directory exists → skip (never overwrite, same or different version) ② ledger says `removed` → skip (respect it) ③ **no record at all + directory missing → lay down the seed** (first launch / a new bundled item's first appearance on update) ④ live record + directory missing → skip, do not lay down (no resurrection—tombstoning is the renderer's reconciliation job via a ledger stamp). Corrupt-directory repair (integrity repair, ≠ resurrecting a deleted plugin) is retained |
42
+ | **User install** | `pluginManager.install(url \| zip on disk \| directory)` | same as above | Download/extract/verify → write to disk; a directory source is a dev convenience only—the main distribution path is the zip |
43
+
44
+ **Install-time verification (intercepted before extraction, so no half-installed directory is produced):**
45
+ - Locate `plugin.json` at the zip top level (basename match, tolerating one wrapper directory)—JSONC parse (#55)
46
+ - `pluginId` resolution: manifest first, zip file basename as the fallback, cross-checked between the two sources; must pass the safe character set (no path separators/relative segments)
47
+ - zip-slip protection—entry paths that escape the extraction target are rejected
48
+ - Same version already installed → skip (user install deletes the source); different version → leave it alone (upgrading is the update flow's job; boot never overwrites)
49
+
50
+ **There are three source roots—don't mix them up** (🔴 Note: **shipped plugins' source is not in the shell repo**):
51
+
52
+ | Source root | Location | Form | HMR | Who lives here |
53
+ |------|------|------|:--:|------|
54
+ | **The plugin's own repo** | GitHub `Encaron/linkdesk-plugin-<id>` (local clones land under `E:\linkdesk-plugins\official\<id>\`) | source + SDK build (`npm run build` → `<id>.linkdesk-plugin`) | ✅ (`linkdesk-plugin-sdk dev`) | **all 18 shipped plugins**—one repo each (D1), 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 two remaining **dev fixtures**: `panel-demo` / `floating-panel-demo` (not shipped, not in the zip) |
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
+
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
+
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
+
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 18 shipped plugins have moved out ⇒ only the two fixtures remain 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
+
65
+ ---
66
+
67
+ ## 3. Directory Taxonomy—No "builtin/user" Categories, Only Fields
68
+
69
+ **There is exactly one kind of plugin.** The installed state lies flat under `{userData}/plugins/<id>/`, and every identity difference lives in plugin.json declaration fields, not in the directory:
70
+
71
+ | Field | Meaning (the only source of truth) |
72
+ |------|------|
73
+ | `core: true` | **A UI guard against accidental deletion**—the uninstall button is hidden/disabled (the shell relies on it for basic interactions such as the settings page and the marketplace; delete it and the shell is crippled). **It is not a category and grants no behavioral privilege**—loading and install/uninstall take the same path |
74
+ | `distribution` | ⚠️ **Legacy field** (already annotated in the schema)—after flattening it no longer maps to any directory, and the install side always normalizes it to `user`. **Third-party plugins should not set it** |
75
+
76
+ Wording discipline (hard constraint 11): don't frame it as two categories "builtin plugins vs. third-party plugins"—say "**plugins with core:true**" (purely a UI button-hiding mechanism against accidental deletion; at the API/command layer they can still be uninstalled or disabled) and "**plugins shipped with the shell**" (the bundled zip ones). **Current state in the repo:** only the two dev fixtures remain under the shell repo's `plugins/`; the 4 core:true plugins (`editor` `file-tree` `marketplace` `settings`) keep their source in **their own repos**; **shipped with the shell = the 6 zips in `bundled-plugins/`** (settings / plugin marketplace / language / base theme / file tree / editor)—the version ledger is `bundled-plugins.lock.json`. "Which ones are core:true" is not a list inside shell code; it is declared only by the zip and lock data (hard constraint 10).
77
+
78
+ **Plugin data directories (independent of the code roots):**
79
+
80
+ | Path | Purpose |
81
+ |------|------|
82
+ | `{userData}/linkdesk/plugins/<id>/data/` | plugin persistent data—the only writable directory |
83
+ | `.../data/cache/` | cache (safe to delete) |
84
+ | `.../data/exports/` | exported files (user-visible) |
85
+
86
+ > 🔥 **Don't mix up the two "plugins" roots:** `{userData}/plugins` = the code root (where the zip is extracted, `userPluginsDir`); `{userData}/linkdesk/plugins` = the data root (`pluginsRootDir`). Uninstall + reinstall **does not clear data**—data lives in a separate data root. Authors get `pluginDataDir` via `window.linkdesk.env.get("<id>")` (returned only when pluginId is included); the shell creates the directory automatically, so the plugin doesn't need to.
87
+
88
+ ---
89
+
90
+ ## 4. Version Compatibility
91
+
92
+ ### Semantic Versioning + the Update Path
93
+
94
+ `version` follows semver (`major.minor.patch`). **boot never refreshes an installed plugin** (the bundled folder is a first-launch offline seed, not an update channel)—there is only one way for an installed user to get new content = **the update flow**: `pluginManager.checkUpdates` (fetch catalog + semver comparison) → `update` (stage to tmp → atomic replace → roll back to the old version on failure). Real marketplace entries discover updates by version.
95
+
96
+ ### 🔥 Any content change must bump the plugin's own version (decided 2026-09-06, #15n)
97
+
98
+ **For a plugin that has been distributed, any content change (code / resources / README / CHANGELOG) must bump `plugin.json.version`.** An installed user's copy is **frozen per version**—boot only fills in what's missing and never refreshes what's installed; the only way for a user to get new content = **the version number**. Changing content without bumping = installed users stay stuck on the old content forever (confirmed empirically on 2026-09-06: a bundled shipping zip gained pyright without a bump → the installed copy's LSP broke entirely).
99
+
100
+ **The same holds for bundled zips shipped with the shell**: repacking a zip with content changes requires a bump—the packaging gate in `npm run check` fails red on "same version, different content" (`scripts/check-bundled-version-bump.mjs`). For an installed user to get a bundled content fix = discovery/update through a real marketplace entry by version; **boot does not reach in**.
101
+
102
+ ### minAppVersion / requires / permissions
103
+
104
+ All three are declared in the schema (see [03-contributes](03-contributes-spec.md)) and none is enforced at install time—their semantics align with [02 Lifecycle §9](02-plugin-lifecycle.md):
105
+
106
+ - `minAppVersion` — checked at load time (not satisfied → toast + skip)
107
+ - `requires` — runtime dependency orchestration applies (missing dependency → suspend as PENDING + cycle fail-loud + cascading uninstall in reverse topological order, see [02 §4](02-plugin-lifecycle.md))
108
+ - `permissions` — declaring them informs the user; the authorization model is still pending
109
+
110
+ ---
111
+
112
+ ## 5. Resource Paths—Relative to the Plugin Directory, Resolved by the Shell (Hard Constraint 12)
113
+
114
+ **🔥 Hardcoding absolute paths is forbidden.** References to in-plugin resources (icons/images/fonts/any asset) = **declarative paths relative to the plugin directory**, which the shell resolves at load time into an absolute URL under the current protocol (icons go through `resolvePluginIcon`; `contributes.views[].render` / assets go through `getPluginAssetPath`)—compatible with both dev `http://localhost:1420` and packaged `file://`. **Authors don't import path utilities and don't hand-build URLs.**
115
+
116
+ ```jsonc
117
+ // ✅ Right—declare a relative path, the shell resolves it (works in dev and in packaged builds)
118
+ { "icon": "resources/logo.png" }
119
+ // Same for contributes.views[].render: { "render": "src/views/MainView.tsx" }
120
+
121
+ // ❌ Wrong—an absolute path literal; it blows up under file:// after packaging
122
+ // { "icon": "/assets/logo.png" }
123
+ ```
124
+
125
+ > **Working in dev is a coincidence** (the http server catches absolute paths); it only shows up under `file://` after packaging. When you need self-rendered resources, use a declared path and let the shell resolve it—see [09 §Static Assets](09-plugin-directory-layout.md) and [01-Plugin API Contract](01-plugin-api-contract.md).
126
+
127
+ ---
128
+
129
+ ## 6. Post-Install Lifecycle Operations
130
+
131
+ Author-side notes on install/uninstall/update/reinstall are in [02 plugin lifecycle §9](02-plugin-lifecycle.md). The author API surface (install/installWithProgress/uninstall/update/checkUpdates/reinstall) is in the `pluginManager` section of [01-Plugin API Contract](01-plugin-api-contract.md).
132
+
133
+ ---
134
+
135
+ ## 7. Full Development → Distribution Flow
136
+
137
+ ```
138
+ 1. Develop (your own project, or repo plugins/<id>)
139
+ Write plugin.json + src/ → run in the source tree → instant HMR
140
+
141
+ 2. Build (before a third-party release)
142
+ Use plugin-sdk → produces <id>.linkdesk-plugin (full author-side flow → the third-party author journey)
143
+
144
+ 3. Distribute
145
+ Deliver the <id>.linkdesk-plugin single file → user installs it / publish to the marketplace
146
+
147
+ 4. Install
148
+ pluginManager.install(url | zip on disk) → verify → extract to {userData}/plugins/<id>/
149
+ → restart or load immediately → the icon appears
150
+
151
+ 5. Update
152
+ Content changes require a version bump → rebuild and republish → user runs checkUpdates/update
153
+ ```
154
+
155
+ ---
156
+
157
+ ## 8. Comparison with VS Code
158
+
159
+ | LinkDesk | VS Code |
160
+ |------|------|
161
+ | `.linkdesk-plugin` single-file zip (downloaded/extracted to `{userData}/plugins/<id>/`) | `.vsix` single file (downloaded/extracted to `~/.vscode/extensions/<id>/`) |
162
+ | `{userData}/plugins/<id>/` install directory (flat, single root) | `~/.vscode/extensions/<id>/` |
163
+ | `core: true` plugins can't be uninstalled (accidental-deletion guard) | `builtin/` built-in extensions |
164
+ | Uninstall = delete directory + settle the ledger (really deleted); only source-tree app plugins move to `.disabled/` | Uninstall = delete files (not recoverable) |
165
+ | `env.get(id).pluginDataDir` | `ExtensionContext.storagePath` |
166
+ | `core: true` plugin shipping = `bundled-plugins/*.linkdesk-plugin` (**a first-launch seed**: boot only fills in what's missing and **never refreshes installed copies**; but **the box itself does refresh with the shell version**—before packaging, `sync:bundled` pulls each plugin's "latest released version", D3) | Ships with app updates (built into the installer) |
167
+ | `requires` **runtime** dependency orchestration ([02 §4](02-plugin-lifecycle.md)) | `extensionDependencies` resolved at install time |
168
+
169
+ ---
170
+
171
+ > **← Previous:** `03-contributes-spec.md`
172
+ > **→ 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)