@linkdesk/plugin-docs 0.1.56 → 0.1.58
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/docs/01-plugin-api-contract.md +3 -3
- package/docs/03-contributes-spec.md +5 -5
- package/docs/04-distribution-format.md +1 -1
- package/docs/05-ui-conventions.md +849 -849
- package/docs/08-view-container-api.md +16 -16
- package/docs/09-plugin-directory-layout.md +1 -1
- package/docs/16-naming-conventions.md +2 -1
- package/docs/zh/01-/346/217/222/344/273/266API/345/245/221/347/272/246.md +2 -2
- package/docs/zh/03-/346/217/222/344/273/266contributes/350/247/204/350/214/203.md +5 -5
- package/docs/zh/04-/346/217/222/344/273/266/345/210/206/345/217/221/346/240/274/345/274/217.md +1 -1
- package/docs/zh/05-/346/217/222/344/273/266UI/345/206/231/346/263/225/350/247/204/347/272/246.md +850 -850
- package/docs/zh/08-ViewContainer-/350/247/206/345/233/276/345/256/271/345/231/250API.md +16 -16
- package/docs/zh/09-/346/217/222/344/273/266/347/233/256/345/275/225/350/247/204/350/214/203.md +1 -1
- package/docs/zh/16-/345/221/275/345/220/215/350/247/204/350/214/203.md +2 -1
- package/docs/zh/plugin.schema.json +5 -4
- 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 +12 -0
- package/package.json +20 -20
|
@@ -17,7 +17,7 @@
|
|
|
17
17
|
| **Core knows nothing** | The shell doesn't recognize any plugin's pluginId |
|
|
18
18
|
| **Contract first** | Plugins go through `window.linkdesk.*`, not `import @src/core` |
|
|
19
19
|
| **Sync first** | APIs that can be synchronous aren't wrapped asynchronously (`path` is pure functions, no IPC) |
|
|
20
|
-
| **Security** | The plugin preload is narrower than the shell's — **the only missing
|
|
20
|
+
| **Security** | The plugin preload is narrower than the shell's — **the only missing namespaces are `bridge` and `storage`** (shell-main-control only: the envelope for plugin IPC requests that the main process forwards to shell-side services); and the preload sandbox has zero Node capability (no `require`/`fs`/`child_process`) |
|
|
21
21
|
|
|
22
22
|
---
|
|
23
23
|
|
|
@@ -29,7 +29,7 @@ A few key points (a summary of Matrix §2; the matrix wins on details):
|
|
|
29
29
|
|
|
30
30
|
| Fact | Explanation |
|
|
31
31
|
|------|------|
|
|
32
|
-
| **The contract has
|
|
32
|
+
| **The contract has 47 namespaces** | The pool injects 45 (shell-only faces `bridge` and `storage` are not injected into the pool); the shell injects 26; mock injects 13 — **the live readings of the `check-namespace-matrix` gate are authoritative** (this row is mechanically reconciled by it; ⛔ do not copy the comment in `surfaces.ts` — that one drifts too) |
|
|
33
33
|
| **Pool = the plugin runtime source of truth** | Plugins run in the pool preload — namespaces injected by the pool are **required**; `bridge` is real-shell-only |
|
|
34
34
|
| **"Shell-only" ≠ plugins can't call it** | `window.*`/`shell.*`/`hotExit.*`/`getFilePath` **are actually injected in the pool** — the older version's ❌ shell-only marking for those surfaces was wrong |
|
|
35
35
|
| **Contract required-surface drift is now zero** | `env.get(pluginId)` forwarding, `clipboard.readText` shell completion, `dialog.openFile` shell completion — all three are implemented, with no `?` degradation |
|
|
@@ -44,7 +44,7 @@ A few key points (a summary of Matrix §2; the matrix wins on details):
|
|
|
44
44
|
|
|
45
45
|
**Every method signature, parameter, return value, and payload type for `window.linkdesk.*` = [contracts/linkdesk.d.ts](https://github.com/Encaron/linkdesk/blob/electron/contracts/linkdesk.d.ts)** (auto-generated; do not hand-edit).
|
|
46
46
|
|
|
47
|
-
- **Generation sources:** `src/core/api/linkdesk-api.ts` + `linkdesk-api/` (
|
|
47
|
+
- **Generation sources:** `src/core/api/linkdesk-api.ts` + `linkdesk-api/` (16 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
50
|
- **Coverage matrix:** every namespace × pool/shell/mock coverage → [Namespace Matrix §2](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/归一化基建/契约生成/命名空间矩阵.md#2-命名空间--四面覆盖矩阵)
|
|
@@ -708,16 +708,16 @@ The file-tree plugin needs zero changes.
|
|
|
708
708
|
{
|
|
709
709
|
"type": "split",
|
|
710
710
|
"id": "add-log",
|
|
711
|
-
"command": "
|
|
711
|
+
"command": "demo-plugin.addLog",
|
|
712
712
|
"icon": "codicon-add",
|
|
713
713
|
"title": "Add demo log",
|
|
714
714
|
"args": { "level": "info" },
|
|
715
715
|
"items": [
|
|
716
|
-
{ "label": "Add info", "command": "
|
|
717
|
-
{ "label": "Add warning", "command": "
|
|
716
|
+
{ "label": "Add info", "command": "demo-plugin.addLog", "args": { "level": "info" } },
|
|
717
|
+
{ "label": "Add warning", "command": "demo-plugin.addLog", "args": { "level": "warn" } }
|
|
718
718
|
]
|
|
719
719
|
},
|
|
720
|
-
{ "type": "icon", "id": "clear-log", "command": "
|
|
720
|
+
{ "type": "icon", "id": "clear-log", "command": "demo-plugin.clearLog", "icon": "codicon-clear-all", "title": "Clear output" }
|
|
721
721
|
]
|
|
722
722
|
}
|
|
723
723
|
```
|
|
@@ -725,7 +725,7 @@ The file-tree plugin needs zero changes.
|
|
|
725
725
|
**Command registration (the source of truth for executing a titleActions command = the pool-side command registry):**
|
|
726
726
|
```typescript
|
|
727
727
|
useEffect(() => {
|
|
728
|
-
window.linkdesk.commands.registerCommand("
|
|
728
|
+
window.linkdesk.commands.registerCommand("demo-plugin.addLog", (args) => { addLine(args.level, args.text); });
|
|
729
729
|
}, []);
|
|
730
730
|
```
|
|
731
731
|
> **`when: "false"` = a purely programmatic command that stays out of the command palette** — titleActions-only commands are declared this way, which keeps them from cluttering Ctrl+Shift+P. The shell's unified renderer `ViewTitleActions.tsx` has two consumers: the panel tab bar (the active view) + the sidebar section collapse header. For a real example see `08 §3`.
|
|
@@ -53,7 +53,7 @@ my-plugin/
|
|
|
53
53
|
| Source root | Location | Form | HMR | Who lives here |
|
|
54
54
|
|------|------|------|:--:|------|
|
|
55
55
|
| **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 |
|
|
56
|
-
| **Shell repo fixtures** | `<shell repo>/plugins/<id>/` (`env.appPluginsDir`) | source + Vite on-the-fly compilation | ✅ (`npm run dev` hot reload) |
|
|
56
|
+
| **Shell repo fixtures** | `<shell repo>/plugins/<id>/` (`env.appPluginsDir`) | source + Vite on-the-fly compilation | ✅ (`npm run dev` hot reload) | currently **empty**—every plugin's source lives in its own repo; a scratch fixture may be dropped here during development (never shipped, never in the zip) |
|
|
57
57
|
| **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 |
|
|
58
58
|
|
|
59
59
|
> 🔴 **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.
|