@linkdesk/plugin-docs 0.1.56 → 0.1.57
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/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/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 +4 -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 +1 -1
|
@@ -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.
|
|
@@ -34,7 +34,7 @@
|
|
|
34
34
|
└────────────────────────────────────────┘
|
|
35
35
|
```
|
|
36
36
|
|
|
37
|
-
- **ViewContainer** = one "channel" of the sidebar/panel. Click the icon in the icon bar to switch. Examples: `explorer` / `marketplace` / `serial-monitor
|
|
37
|
+
- **ViewContainer** = one "channel" of the sidebar/panel. Click the icon in the icon bar to switch. Examples: `explorer` / `marketplace` / `serial-monitor`, or your own `<pluginId>`.
|
|
38
38
|
- **View** = one collapsible section inside a container. Examples: `folders` / `sessions` / `settings`.
|
|
39
39
|
- **Any plugin** can register views into someone else's container. The container's owner neither knows nor cares.
|
|
40
40
|
- **Where it renders is decided by `location`**: `"sidebar"` → the left sidebar SidebarZone; `"panel"` → the bottom panel PanelZone (the tab bar switches views); `"auxiliarybar"` → the right auxiliary sidebar RightSidebarZone — ⚠ **not wired up in the shell today (it does not render; the region is dormant)**: declaring an auxiliarybar container/view = no surface, nothing visible. For third-party sidebar/panel needs use `"sidebar"`/`"panel"`. Every region renders views with the same `PoolSectionStack` (SidebarSection is wrapped automatically).
|
|
@@ -81,7 +81,7 @@
|
|
|
81
81
|
| `hideIfEmpty` | ❌ | boolean | Hide automatically when there are no active views. Defaults to `false` |
|
|
82
82
|
| `order` | ❌ | number | Ordering among containers in the same location. Smaller values come first |
|
|
83
83
|
| `icon` | ❌ | string | Container icon — overrides the plugin's own icon |
|
|
84
|
-
| `mergeHeaderWhenSingle` | ❌ | boolean | When the container holds only one view, hide the view's collapse header — the title merges into the container header. Aligned with VS Code's `mergeViewWithContainerWhenSingleView` (
|
|
84
|
+
| `mergeHeaderWhenSingle` | ❌ | boolean | When the container holds only one view, hide the view's collapse header — the title merges into the container header. Aligned with VS Code's `mergeViewWithContainerWhenSingleView` (a sidebar container holding a single view uses exactly this mode) |
|
|
85
85
|
|
|
86
86
|
### views fields (full table)
|
|
87
87
|
|
|
@@ -121,7 +121,7 @@
|
|
|
121
121
|
|
|
122
122
|
**Widget fields:** `id` (unique), `command` (the command ID executed on click), `args` (optional — passed through as the single positional argument of `executeCommand(command, args)`), `icon` (a codicon class name, e.g. `"codicon-add"`), `title` (tooltip/aria-label/text when there is no icon), `items` (the alternative entries of a dropdown/split: `{ label, command, args }`).
|
|
123
123
|
|
|
124
|
-
### A
|
|
124
|
+
### A worked example — a panel view with titleActions
|
|
125
125
|
|
|
126
126
|
```json
|
|
127
127
|
{
|
|
@@ -133,20 +133,20 @@
|
|
|
133
133
|
{
|
|
134
134
|
"type": "split",
|
|
135
135
|
"id": "add-log",
|
|
136
|
-
"command": "
|
|
136
|
+
"command": "demo-plugin.addLog",
|
|
137
137
|
"icon": "codicon-add",
|
|
138
138
|
"title": "Add a demo log",
|
|
139
139
|
"args": { "level": "info", "text": "The primary button — add an info log" },
|
|
140
140
|
"items": [
|
|
141
|
-
{ "label": "Add info", "command": "
|
|
142
|
-
{ "label": "Add warning", "command": "
|
|
143
|
-
{ "label": "Add error", "command": "
|
|
141
|
+
{ "label": "Add info", "command": "demo-plugin.addLog", "args": { "level": "info" } },
|
|
142
|
+
{ "label": "Add warning", "command": "demo-plugin.addLog", "args": { "level": "warn" } },
|
|
143
|
+
{ "label": "Add error", "command": "demo-plugin.addLog", "args": { "level": "error" } }
|
|
144
144
|
]
|
|
145
145
|
},
|
|
146
146
|
{
|
|
147
147
|
"type": "icon",
|
|
148
148
|
"id": "clear-log",
|
|
149
|
-
"command": "
|
|
149
|
+
"command": "demo-plugin.clearLog",
|
|
150
150
|
"icon": "codicon-clear-all",
|
|
151
151
|
"title": "Clear output"
|
|
152
152
|
}
|
|
@@ -159,18 +159,18 @@
|
|
|
159
159
|
The source of truth for executing a `command` declared in `titleActions` = **the pool-side command registry** (`executeCommand` prefers the pool side, with shell IPC as fallback). Command handlers are registered inside the view component:
|
|
160
160
|
|
|
161
161
|
```tsx
|
|
162
|
-
// DemoOutputView.tsx
|
|
162
|
+
// DemoOutputView.tsx
|
|
163
163
|
useEffect(() => {
|
|
164
164
|
const api = window.linkdesk?.commands;
|
|
165
165
|
api?.registerCommand?.(
|
|
166
|
-
"
|
|
166
|
+
"demo-plugin.addLog",
|
|
167
167
|
(args?: { level?: LogLevel; text?: string }) => {
|
|
168
168
|
addLine(args?.level ?? "info", args?.text ?? "");
|
|
169
169
|
},
|
|
170
170
|
// Registered through the pool-side registerCommand — `when` is left to the declaration system;
|
|
171
171
|
// when:"false" = a purely programmatic command that does not enter the command palette (titleActions-only)
|
|
172
172
|
);
|
|
173
|
-
api?.registerCommand?.("
|
|
173
|
+
api?.registerCommand?.("demo-plugin.clearLog", () => clearLines());
|
|
174
174
|
}, []);
|
|
175
175
|
```
|
|
176
176
|
|
|
@@ -248,21 +248,21 @@ await window.linkdesk.panel.reveal("demo-output"); // focus the demo-output vie
|
|
|
248
248
|
- Panel already shown → switch focus
|
|
249
249
|
- `viewId` not in a panel container → **no-op** (no error)
|
|
250
250
|
|
|
251
|
-
**Complete panel container example — panel
|
|
251
|
+
**Complete panel container example — one plugin declaring both a panel and a sidebar container:**
|
|
252
252
|
|
|
253
253
|
```json
|
|
254
254
|
{
|
|
255
255
|
"contributes": {
|
|
256
256
|
"viewsContainers": {
|
|
257
|
-
"
|
|
258
|
-
"
|
|
257
|
+
"demo-plugin": { "title": "Panel Demo", "location": "panel" },
|
|
258
|
+
"demo-plugin-sidebar": { "title": "Panel Demo", "location": "sidebar" }
|
|
259
259
|
},
|
|
260
260
|
"views": {
|
|
261
|
-
"
|
|
261
|
+
"demo-plugin": [
|
|
262
262
|
{ "id": "demo-output", "title": "Output", "render": "src/views/DemoOutputView.tsx", "order": 0, "titleActions": [/* §3 */] },
|
|
263
263
|
{ "id": "demo-todo", "title": "To-do", "render": "src/views/DemoTodoView.tsx", "order": 1 }
|
|
264
264
|
],
|
|
265
|
-
"
|
|
265
|
+
"demo-plugin-sidebar": [
|
|
266
266
|
{ "id": "demo-sidebar", "title": "Sidebar Demo", "render": "src/views/DemoSidebarView.tsx", "order": 0, "titleActions": [/* §3 */] }
|
|
267
267
|
]
|
|
268
268
|
}
|
|
@@ -103,7 +103,7 @@ Changing the contents of `README.md` / `CHANGELOG.md` **= a content change = you
|
|
|
103
103
|
|
|
104
104
|
> 🔥 **2026-09-14**. This section answers a question that had never been written down before: **which repo does the plugin source live in?** How to lay out the local directory and how to create the repo → [15-multi-repo-and-local-workspace](15-multi-repo-and-local-workspace.md).
|
|
105
105
|
|
|
106
|
-
1. **The source of truth for source code = the plugin's own repo** (`github.com/<owner>/<repo>`), **not the shell repo**. The shell repo's `plugins/` allows only two kinds of things: **fixtures** (demos that don't ship
|
|
106
|
+
1. **The source of truth for source code = the plugin's own repo** (`github.com/<owner>/<repo>`), **not the shell repo**. The shell repo's `plugins/` allows only two kinds of things: **fixtures** (scratch demos that don't ship) and **build artifacts** (`bundled-plugins/<id>.linkdesk-plugin`).
|
|
107
107
|
2. **The semantics of `bundled-plugins/<id>.linkdesk-plugin` in the shell repo = the seed snapshot used for factory shipping**, with its version accounted for by `bundled-plugins.lock.json`. It is **not a second copy of the source** — if the source changes you must change it back in the plugin repo, then run the publish chain to refresh the seed.
|
|
108
108
|
3. **The chain from source to a user's desktop**: plugin repo → `npm run build` → `<id>.linkdesk-plugin` (zip) → GitHub Release asset → catalog entry → user install. **Not one step passes through the shell repo.**
|
|
109
109
|
4. **Plugin identity (id) is immutable forever**; the display name (`name`) can change; the repo name can change — the three-way rule and all naming criteria → [16-naming-conventions](16-naming-conventions.md).
|
|
@@ -111,11 +111,12 @@ The table below is **reconciled name by name** against it (gate `scripts/check-r
|
|
|
111
111
|
| Host config key | `app.language` | UI language |
|
|
112
112
|
| Host config key | `app.osIntegration.dirMenu`、`app.osIntegration.fileAssoc`、`app.osIntegration.fileMenu` | OS integration (context menu, file associations) |
|
|
113
113
|
| Host config key | `app.update.mode`、`app.update.showReleaseNotes` | Update channel |
|
|
114
|
+
| Host config key | `app.storage.cacheDir`、`app.storage.openCacheDir` | Cache folder — the two rows under Settings → General → Storage (open-cache-folder button / read-only path) |
|
|
114
115
|
| Host recipe id | `dark`、`light` | The **fallback values** of `app.theme`. ⚠️ `light` also carries a **grant**: the official `theme-defaults` plugin is the official implementer of the host's light fallback, so only it may declare that id |
|
|
115
116
|
| Host colorway id | `dark-fallback`、`light` | Fallback values of `app.themeColor` and of the colorway source space |
|
|
116
117
|
| Host icon theme id | `default` | The fallback value of `app.iconTheme` |
|
|
117
118
|
| Host appearance sentinel | `followTheme` | The "follow the theme" sentinel of a mix source — **it is not an id**, so don't try to shadow it with a plugin id |
|
|
118
|
-
| Host-only context key (plugins **must not** set) | `activeEditor`、`editorCount`、`editorHasSelection`、`inputFocus`、`settingsSlotFilled`、`sidebarPosition`、`updateActionable`、`updateButtonLabel` | Set one of these at runtime over IPC and the host logs a `console.error` **naming you** (the value is still written: these are state, not registrations, so the runtime cannot tell who came first) |
|
|
119
|
+
| Host-only context key (plugins **must not** set) | `activeEditor`、`editorCount`、`editorHasSelection`、`inputFocus`、`settingsActiveIsBuiltin`、`settingsSlotFilled`、`sidebarPosition`、`updateActionable`、`updateButtonLabel` | Set one of these at runtime over IPC and the host logs a `console.error` **naming you** (the value is still written: these are state, not registrations, so the runtime cannot tell who came first) |
|
|
119
120
|
| Shared-contract context key (plugins **may** set) | `settingKey`、`settingFollowTheme`、`settingModified`、`settingResetsToDefault` | These four are a **public contract**: the official `settings` plugin writes them, host commands read them in `when` clauses — use them as specified, don't change their meaning |
|
|
120
121
|
|
|
121
122
|
**How to check yourself** (from your own repo): once `@linkdesk/plugin-sdk` is installed, your repo's `verify` runs four ownership legs (command ids / config keys / appearance ids / context keys); whichever one you violate is reported with its location plus the suggested fix, **"should start with `<pluginId>.`"**.
|
|
@@ -29,7 +29,7 @@
|
|
|
29
29
|
|
|
30
30
|
| 事实 | 说明 |
|
|
31
31
|
|------|------|
|
|
32
|
-
| **契约
|
|
32
|
+
| **契约 47 命名空间** | 池注入 45(壳侧独有面 `bridge`、`storage` 不进池);壳注入 26;mock 注入 13——**以 `check-namespace-matrix` 门禁的活读数为准**(本行已由它机械对账,⛔ 别照 `surfaces.ts` 里的注释抄,那份也在漂) |
|
|
33
33
|
| **池 = 插件运行时真相源** | 插件运行在池(pool)preload——池注入的命名空间为 **required**;`bridge` 真壳独有 |
|
|
34
34
|
| **「仅壳」≠ 插件不可调** | `window.*`/`shell.*`/`hotExit.*`/`getFilePath` 池**实有注入**——旧版把这几面标 ❌ 仅壳是错的 |
|
|
35
35
|
| **契约必选面漂移已清零** | `env.get(pluginId)` 转发、`clipboard.readText` 壳补、`dialog.openFile` 壳补——三项都已补齐实现,无 `?` 降级 |
|
|
@@ -44,7 +44,7 @@
|
|
|
44
44
|
|
|
45
45
|
**`window.linkdesk.*` 的全部方法签名、入参、返回、载荷类型 = [contracts/linkdesk.d.ts](https://github.com/Encaron/linkdesk/blob/electron/contracts/linkdesk.d.ts)**(自动生成,勿手改)。
|
|
46
46
|
|
|
47
|
-
- **生成源:** `src/core/api/linkdesk-api.ts` + `linkdesk-api/`(
|
|
47
|
+
- **生成源:** `src/core/api/linkdesk-api.ts` + `linkdesk-api/`(16 域接口)+ `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
50
|
- **覆盖矩阵:** 每个命名空间 × 池/壳/mock 四面覆盖 → [命名空间矩阵 §2](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/归一化基建/契约生成/命名空间矩阵.md#2-命名空间--四面覆盖矩阵)
|
|
@@ -696,16 +696,16 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
|
|
|
696
696
|
{
|
|
697
697
|
"type": "split",
|
|
698
698
|
"id": "add-log",
|
|
699
|
-
"command": "
|
|
699
|
+
"command": "demo-plugin.addLog",
|
|
700
700
|
"icon": "codicon-add",
|
|
701
701
|
"title": "添加演示日志",
|
|
702
702
|
"args": { "level": "info" },
|
|
703
703
|
"items": [
|
|
704
|
-
{ "label": "添加信息", "command": "
|
|
705
|
-
{ "label": "添加警告", "command": "
|
|
704
|
+
{ "label": "添加信息", "command": "demo-plugin.addLog", "args": { "level": "info" } },
|
|
705
|
+
{ "label": "添加警告", "command": "demo-plugin.addLog", "args": { "level": "warn" } }
|
|
706
706
|
]
|
|
707
707
|
},
|
|
708
|
-
{ "type": "icon", "id": "clear-log", "command": "
|
|
708
|
+
{ "type": "icon", "id": "clear-log", "command": "demo-plugin.clearLog", "icon": "codicon-clear-all", "title": "清空输出" }
|
|
709
709
|
]
|
|
710
710
|
}
|
|
711
711
|
```
|
|
@@ -713,7 +713,7 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
|
|
|
713
713
|
**命令注册(titleActions 的 command 执行真相源 = 池侧命令注册表):**
|
|
714
714
|
```typescript
|
|
715
715
|
useEffect(() => {
|
|
716
|
-
window.linkdesk.commands.registerCommand("
|
|
716
|
+
window.linkdesk.commands.registerCommand("demo-plugin.addLog", (args) => { addLine(args.level, args.text); });
|
|
717
717
|
}, []);
|
|
718
718
|
```
|
|
719
719
|
> **`when: "false"` = 纯程序化命令不进命令面板**——titleActions 专属命令都这样声明,防止在 Ctrl+Shift+P 里刷屏。壳统一渲染器 `ViewTitleActions.tsx` 两处消费:面板标签栏(活动视图)+ 侧栏 section 折叠头。真实示例见 `08 §三`。
|
package/docs/zh/04-/346/217/222/344/273/266/345/210/206/345/217/221/346/240/274/345/274/217.md
CHANGED
|
@@ -53,7 +53,7 @@ my-plugin/
|
|
|
53
53
|
| 代码根 | 位置 | 形态 | HMR | 谁住这里 |
|
|
54
54
|
|------|------|------|:--:|------|
|
|
55
55
|
| **插件自己的仓** | GitHub `Encaron/linkdesk-plugin-<id>`(克隆到你喜欢的任意本地目录即可) | 源码 + SDK build(`npm run build` → `<id>.linkdesk-plugin`) | ✅(`linkdesk-plugin-sdk dev`) | **全部发货插件**——一只一个仓,源码真相源只此一处 |
|
|
56
|
-
| **壳仓夹具** | `<壳仓>/plugins/<id>/`(`env.appPluginsDir`) | 源码 + Vite 即时编译 | ✅(`npm run dev` 热更) |
|
|
56
|
+
| **壳仓夹具** | `<壳仓>/plugins/<id>/`(`env.appPluginsDir`) | 源码 + Vite 即时编译 | ✅(`npm run dev` 热更) | 今日**为空**——插件源码全在各自独立仓;开发期可随手丢一只临时夹具(不发货、不进 zip) |
|
|
57
57
|
| **安装态** | `{userData}/plugins/<id>/` | zip 解出的预构建 bundle | ❌(改包需重 build + 重装/重物化) | 用户机器上所有已装插件 |
|
|
58
58
|
|
|
59
59
|
> 🔴 **为什么发货插件的源码不能两边都留一份**:一旦壳仓与插件仓各有一份,改了这头那头不变,而**没有任何门禁能发现分叉**(内容指纹门禁只管 zip 内容,不管源码)⇒ 真相源必须唯一。壳仓留下的两样是**产物**(`bundled-plugins/*.linkdesk-plugin`)与**文档档案**,不是源码。
|
|
@@ -34,7 +34,7 @@
|
|
|
34
34
|
└──────────────────────────────────────┘
|
|
35
35
|
```
|
|
36
36
|
|
|
37
|
-
- **ViewContainer** = 侧栏/面板的一个"频道"。点图标栏切换。如 `explorer` / `marketplace` / `serial-monitor
|
|
37
|
+
- **ViewContainer** = 侧栏/面板的一个"频道"。点图标栏切换。如 `explorer` / `marketplace` / `serial-monitor`,或你自己的 `<pluginId>`。
|
|
38
38
|
- **View** = 容器里的一个可折叠 section。如 `folders` / `sessions` / `settings`。
|
|
39
39
|
- **任何插件** 都可以往别人的容器里注册 view。容器的主人不知道、不关心。
|
|
40
40
|
- **渲染位置由 `location` 决定**:`"sidebar"` → 左侧栏 SidebarZone;`"panel"` → 底部面板 PanelZone(标签栏切换视图);`"auxiliarybar"` → 右侧辅助侧栏 RightSidebarZone——⚠ **壳当前未接线(不渲染,区域 dormant)**:声明 auxiliarybar 容器/视图 = 无表面不可见。第三方侧栏/面板需求请用 `"sidebar"`/`"panel"`。所有区都用同一个 `PoolSectionStack` 渲染 view(SidebarSection 自动包裹)。
|
|
@@ -81,7 +81,7 @@
|
|
|
81
81
|
| `hideIfEmpty` | ❌ | boolean | 无活跃 view 时自动隐藏。默认 `false` |
|
|
82
82
|
| `order` | ❌ | number | 同位置容器排序。小值靠前 |
|
|
83
83
|
| `icon` | ❌ | string | 容器图标——覆盖插件自身图标 |
|
|
84
|
-
| `mergeHeaderWhenSingle` | ❌ | boolean | 容器内只有一个 view 时,隐藏 view 折叠头——标题合并到容器 header。对标 VS Code `mergeViewWithContainerWhenSingleView
|
|
84
|
+
| `mergeHeaderWhenSingle` | ❌ | boolean | 容器内只有一个 view 时,隐藏 view 折叠头——标题合并到容器 header。对标 VS Code `mergeViewWithContainerWhenSingleView`(只装一个 view 的侧栏容器即用此模式) |
|
|
85
85
|
|
|
86
86
|
### views 字段(全表)
|
|
87
87
|
|
|
@@ -121,7 +121,7 @@
|
|
|
121
121
|
|
|
122
122
|
**widget 字段:** `id`(唯一)、`command`(点击执行的命令 ID)、`args`(可选——`executeCommand(command, args)` 单个位置参数透传)、`icon`(codicon 类名,如 `"codicon-add"`)、`title`(tooltip/aria-label/无 icon 时的文本)、`items`(dropdown/split 的备选条目 `{ label, command, args }`)。
|
|
123
123
|
|
|
124
|
-
###
|
|
124
|
+
### 实例——声明 titleActions 的面板视图
|
|
125
125
|
|
|
126
126
|
```json
|
|
127
127
|
{
|
|
@@ -133,20 +133,20 @@
|
|
|
133
133
|
{
|
|
134
134
|
"type": "split",
|
|
135
135
|
"id": "add-log",
|
|
136
|
-
"command": "
|
|
136
|
+
"command": "demo-plugin.addLog",
|
|
137
137
|
"icon": "codicon-add",
|
|
138
138
|
"title": "添加演示日志",
|
|
139
139
|
"args": { "level": "info", "text": "主按钮——添加信息日志" },
|
|
140
140
|
"items": [
|
|
141
|
-
{ "label": "添加信息", "command": "
|
|
142
|
-
{ "label": "添加警告", "command": "
|
|
143
|
-
{ "label": "添加错误", "command": "
|
|
141
|
+
{ "label": "添加信息", "command": "demo-plugin.addLog", "args": { "level": "info" } },
|
|
142
|
+
{ "label": "添加警告", "command": "demo-plugin.addLog", "args": { "level": "warn" } },
|
|
143
|
+
{ "label": "添加错误", "command": "demo-plugin.addLog", "args": { "level": "error" } }
|
|
144
144
|
]
|
|
145
145
|
},
|
|
146
146
|
{
|
|
147
147
|
"type": "icon",
|
|
148
148
|
"id": "clear-log",
|
|
149
|
-
"command": "
|
|
149
|
+
"command": "demo-plugin.clearLog",
|
|
150
150
|
"icon": "codicon-clear-all",
|
|
151
151
|
"title": "清空输出"
|
|
152
152
|
}
|
|
@@ -159,17 +159,17 @@
|
|
|
159
159
|
`titleActions` 声明的 `command` 执行真相源 = **池侧命令注册表**(`executeCommand` 池侧优先、壳 IPC fallback)。命令 handler 在 view 组件里注册:
|
|
160
160
|
|
|
161
161
|
```tsx
|
|
162
|
-
// DemoOutputView.tsx
|
|
162
|
+
// DemoOutputView.tsx
|
|
163
163
|
useEffect(() => {
|
|
164
164
|
const api = window.linkdesk?.commands;
|
|
165
165
|
api?.registerCommand?.(
|
|
166
|
-
"
|
|
166
|
+
"demo-plugin.addLog",
|
|
167
167
|
(args?: { level?: LogLevel; text?: string }) => {
|
|
168
168
|
addLine(args?.level ?? "info", args?.text ?? "");
|
|
169
169
|
},
|
|
170
170
|
// 池侧 registerCommand 注册——when 交给声明制;when:"false" = 纯程序化命令不进命令面板(titleActions 专属)
|
|
171
171
|
);
|
|
172
|
-
api?.registerCommand?.("
|
|
172
|
+
api?.registerCommand?.("demo-plugin.clearLog", () => clearLines());
|
|
173
173
|
}, []);
|
|
174
174
|
```
|
|
175
175
|
|
|
@@ -246,21 +246,21 @@ await window.linkdesk.panel.reveal("demo-output"); // 聚焦底部面板的 dem
|
|
|
246
246
|
- 面板已显示 → 切换聚焦
|
|
247
247
|
- `viewId` 不在 panel 容器 → **no-op**(不报错)
|
|
248
248
|
|
|
249
|
-
|
|
249
|
+
**完整面板容器示例——同一个插件同时声明面板容器与侧栏容器:**
|
|
250
250
|
|
|
251
251
|
```json
|
|
252
252
|
{
|
|
253
253
|
"contributes": {
|
|
254
254
|
"viewsContainers": {
|
|
255
|
-
"
|
|
256
|
-
"
|
|
255
|
+
"demo-plugin": { "title": "面板演示", "location": "panel" },
|
|
256
|
+
"demo-plugin-sidebar": { "title": "面板演示", "location": "sidebar" }
|
|
257
257
|
},
|
|
258
258
|
"views": {
|
|
259
|
-
"
|
|
259
|
+
"demo-plugin": [
|
|
260
260
|
{ "id": "demo-output", "title": "输出", "render": "src/views/DemoOutputView.tsx", "order": 0, "titleActions": [/* §三 */] },
|
|
261
261
|
{ "id": "demo-todo", "title": "待办", "render": "src/views/DemoTodoView.tsx", "order": 1 }
|
|
262
262
|
],
|
|
263
|
-
"
|
|
263
|
+
"demo-plugin-sidebar": [
|
|
264
264
|
{ "id": "demo-sidebar", "title": "侧栏演示", "render": "src/views/DemoSidebarView.tsx", "order": 0, "titleActions": [/* §三 */] }
|
|
265
265
|
]
|
|
266
266
|
}
|
package/docs/zh/09-/346/217/222/344/273/266/347/233/256/345/275/225/350/247/204/350/214/203.md
CHANGED
|
@@ -103,7 +103,7 @@ SDK `publish` 要从它**切段**填目录条目,所以**段标题格式有约
|
|
|
103
103
|
|
|
104
104
|
> 🔥 **2026-09-14**。本节回答一个此前从没被写下来的问题:**插件源码住在哪个仓库?** 本地目录怎么摆、仓库怎么建 → [15-多仓开发与本地工作区](15-多仓开发与本地工作区.md)。
|
|
105
105
|
|
|
106
|
-
1. **源码真相源 = 插件自己的仓库**(`github.com/<owner>/<repo>`),**不是壳仓**。壳仓内的 `plugins/`
|
|
106
|
+
1. **源码真相源 = 插件自己的仓库**(`github.com/<owner>/<repo>`),**不是壳仓**。壳仓内的 `plugins/` 只允许两类东西:**夹具**(不发货的临时 demo)与**构建产物**(`bundled-plugins/<id>.linkdesk-plugin`)。
|
|
107
107
|
2. **壳仓 `bundled-plugins/<id>.linkdesk-plugin` 的语义 = 出厂发货用的种子快照**,其版本由 `bundled-plugins.lock.json` 记账(第 7.4 轮产出)。它**不是源码的第二份拷贝**——源码改了必须回插件仓改,改完走发布链路刷新种子。
|
|
108
108
|
3. **从源码到用户桌面的链路**:插件仓 → `npm run build` → `<id>.linkdesk-plugin`(zip)→ GitHub Release asset → catalog 条目 → 用户安装。**没有一步经过壳仓。**
|
|
109
109
|
4. **插件身份(id)永不可变**;显示名(`name`)可改;仓库名可改——三分规则与全部命名判据 → [16-命名规范](16-命名规范.md)。
|
|
@@ -113,11 +113,12 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
|
|
|
113
113
|
| 宿主配置键 | `app.language` | 界面语言 |
|
|
114
114
|
| 宿主配置键 | `app.osIntegration.dirMenu`、`app.osIntegration.fileAssoc`、`app.osIntegration.fileMenu` | 系统集成(右键菜单、文件关联) |
|
|
115
115
|
| 宿主配置键 | `app.update.mode`、`app.update.showReleaseNotes` | 更新通道 |
|
|
116
|
+
| 宿主配置键 | `app.storage.cacheDir`、`app.storage.openCacheDir` | 缓存目录——设置「通用 → 存储」**一行**(打开缓存目录按钮 + 右侧同排只读路径)。⚠️ `cacheDir` 已退役、**不再声明**(设置行案 D3 合并),名字照旧保留(不腾位),登记见 `scripts/host-reserved.json` 的 `retired[]` |
|
|
116
117
|
| 宿主配方 id | `dark`、`light` | `app.theme` 的**兜底取值**。⚠️ `light` 另有一张**证照**:官方 `theme-defaults` 是宿主亮兜底的官方实现者,只有它有权声明这个 id |
|
|
117
118
|
| 宿主配色 id | `dark-fallback`、`light` | `app.themeColor` 与配色来源空间的兜底取值 |
|
|
118
119
|
| 宿主图标主题 id | `default` | `app.iconTheme` 的保底取值 |
|
|
119
120
|
| 宿主外观哨兵值 | `followTheme` | 混搭来源的「跟随主题」哨兵——**它不是 id**,别拿一个插件 id 去顶它 |
|
|
120
|
-
| 宿主专用旗子(插件**禁设**) | `activeEditor`、`editorCount`、`editorHasSelection`、`inputFocus`、`settingsSlotFilled`、`sidebarPosition`、`updateActionable`、`updateButtonLabel` | 你在运行时经 IPC 设它,宿主会 `console.error` **点名你**(值照写:旗子是状态不是注册,运行时拿不到「谁是先者」) |
|
|
121
|
+
| 宿主专用旗子(插件**禁设**) | `activeEditor`、`editorCount`、`editorHasSelection`、`inputFocus`、`settingsActiveIsBuiltin`、`settingsSlotFilled`、`sidebarPosition`、`updateActionable`、`updateButtonLabel` | 你在运行时经 IPC 设它,宿主会 `console.error` **点名你**(值照写:旗子是状态不是注册,运行时拿不到「谁是先者」) |
|
|
121
122
|
| 宿主公开约定旗子(插件**可设**) | `settingKey`、`settingFollowTheme`、`settingModified`、`settingResetsToDefault` | 这 4 个是**公开约定面**:官方 `settings` 插件写、宿主命令的 `when` 读——照约定用,别改语义 |
|
|
122
123
|
|
|
123
124
|
**怎么自查**(你自己的仓里就能跑):装上 `@linkdesk/plugin-sdk` 后,你仓里的 `verify` 会跑四条归属腿
|
|
@@ -371,11 +371,11 @@
|
|
|
371
371
|
"enum": { "type": "array" },
|
|
372
372
|
"enumDescriptions": { "type": "object", "description": "enum value → display name mapping" },
|
|
373
373
|
"description": { "type": "string" },
|
|
374
|
-
"uiHint": { "type": "string", "description": "Settings editor rendering hint
|
|
375
|
-
"renderHint": { "type": "string", "description": "Rendering hint for special rows — \"action\" renders a button (its text comes from description, clicking runs actionCommand); \"readonly\" renders a read-only status line whose value comes from executing statusCommand.
|
|
376
|
-
"actionCommand": { "type": "string", "description": "Command executed when an \"action\" button is clicked — a shell command id or one of your own (resolved when clicked)" },
|
|
374
|
+
"uiHint": { "type": "string", "description": "Settings editor rendering hint — SettingsView picks the control from the hint. Known hints: slider, fontSize, color, fontFamily, file, directory, image, segmented, fontTone, accentSource, themePicker, select, stringList. A hint the installed renderer does not know is shown read-only — the current value plus a tooltip saying the declared control is unsupported (no editable fallback control, no error thrown). The value is an open string, so third parties may declare new hint names." },
|
|
375
|
+
"renderHint": { "type": "string", "description": "Rendering hint for special rows — \"action\" renders a button (its text comes from description, clicking runs actionCommand); \"readonly\" renders a read-only status line whose value comes from executing statusCommand; \"color\" renders a read-only color row (swatch + value). \"readonly\"/\"action\" are shorthands meaning the row's primary control IS the status line/button: statusCommand and actionCommand may also be declared alongside any primary control, rendering as companions to its right ([primary control][companion button][companion readonly]). Known hints: readonly, action, color. An unknown hint is shown read-only (current value + explanatory tooltip). Open string." },
|
|
376
|
+
"actionCommand": { "type": "string", "description": "Command executed when an \"action\" button is clicked — a shell command id or one of your own (resolved when clicked). May be declared alongside any primary control: it then renders as a companion button to the right of that control, with its text taken from description." },
|
|
377
377
|
"actionDisabledAll": { "type": "array", "description": "Disable the \"action\" button while every entry matches the current configuration value (omit the field entirely — or pass an empty list — to keep the button always enabled)", "items": { "type": "object", "required": ["key", "value"], "properties": { "key": { "type": "string" }, "value": {} }, "additionalProperties": false } },
|
|
378
|
-
"statusCommand": { "type": "string", "description": "Command whose return value (a string) is shown by a \"readonly\" status line — the value comes from the command, not from configuration storage, so a status row can show live runtime state. Shell command id or one of your own." },
|
|
378
|
+
"statusCommand": { "type": "string", "description": "Command whose return value (a string) is shown by a \"readonly\" status line — the value comes from the command, not from configuration storage, so a status row can show live runtime state. The settings view polls it (every 3s by default; polling pauses while the window is hidden). Shell command id or one of your own. The command must be cheap, idempotent and side-effect free — it may be called repeatedly in the background. May be declared alongside any primary control: it then renders as a companion read-only line to the right of that control. Without a primary control, declare renderHint \"readonly\" so the status line becomes the row's main control." },
|
|
379
379
|
"monoOnly": { "type": "boolean", "description": "Monospace only — meaningful only with uiHint \"fontFamily\". true/omitted = list monospace families only (editor fonts); false = all families (UI fonts)." },
|
|
380
380
|
"minimum": { "type": "number", "description": "Numeric lower bound — applies when type is number (range of the slider/numeric control)" },
|
|
381
381
|
"maximum": { "type": "number", "description": "Numeric upper bound — applies when type is number (range of the slider/numeric control)" },
|
|
@@ -59,6 +59,8 @@
|
|
|
59
59
|
| `texture` / `textureOpacity` | (写入 per-surface 背景族) | 可平铺纹理图资产路径与不透明度 | 不写 |
|
|
60
60
|
|
|
61
61
|
> ⚠️ **大面积 `blur` 是 GPU 负担**——用得越克制越流畅。
|
|
62
|
+
>
|
|
63
|
+
> 🔴 **两个「玻璃不透明度」不是一个旋钮**(作者最容易撞的一处):本域的 `opacity`(→ `--glass-opacity`)是**这只主题自带的玻璃材质**有多厚;**用户在设置里**调的「玻璃不透明度」(`app.glassOpacity` → `--glass-surface-alpha`)是**玻璃表面的合成比例**(`color-mix(… calc(var(--glass-surface-alpha) * 100%) …)`)。两者相乘、各自生效——想调「玻璃感」先看清自己在调哪一个。
|
|
62
64
|
|
|
63
65
|
### `font` —— 字体
|
|
64
66
|
|
|
@@ -80,6 +82,8 @@
|
|
|
80
82
|
> 🔴 **`mask` 是数字(0–1),不是颜色字符串**——要指定遮罩颜色用 `maskColor`。
|
|
81
83
|
> ([11-主题制作](https://github.com/Encaron/linkdesk/blob/electron/docs/11-主题制作.md) 的满配示例里曾把它写成 `rgba(...)`,与 schema 不符,已订正。)
|
|
82
84
|
|
|
85
|
+
> 🔴 **背景面这一组键建议写全**:`--bg-window` · `--bg-card` · `--bg-input` · `--bg-titlebar` · `--bg-toolbar` · `--bg-side-panel` · `--bg-icon-bar` · `--bg-selection`(各色面/栏的底色)。玻璃化的表面由引擎按**锚点**派生一份 `*-solid` 兜底色——**缺哪个键就按锚点算**,观感未必是你要的(「顶栏当一块独立岛」这类配方尤其明显)。只想改一两处没问题,但别在没看清派生规则时整组漏掉。
|
|
86
|
+
|
|
83
87
|
---
|
|
84
88
|
|
|
85
89
|
## 三、`colorways[].colors` —— 颜色 token 怎么起名
|
|
@@ -103,6 +107,14 @@
|
|
|
103
107
|
**全集在哪**:壳的默认主题 token 全表 = 仓库 `src/index.css` 的 `:root`(近百个)。
|
|
104
108
|
**只想改几个就写几个**——没写的继承基线(浅色主题继承浅底、深色继承深底)。
|
|
105
109
|
|
|
110
|
+
🔴 **图标色是壳算的,主题给不了**:`icon-active` **不是有效键**——壳从不读它,写了既不报错也不生效(图标墨色由壳按当前主题的**文字色**自动派生,深浅与用户「文字极性」都会跟着翻;想影响图标,改文字色/极性)。
|
|
111
|
+
|
|
112
|
+
> `icon-inactive` 是**有效**的,但语义只有一处:**欢迎页「非激活图标」的用色**。图标栏不读它。
|
|
113
|
+
|
|
114
|
+
🔴 **挂了背景照片,标题栏/状态栏文字的可读性归你**(2026-10-03 拍板):标题栏菜单与状态栏的文字读的是 **`--text-secondary`**,**壳不会替你自动调它**——因为这两处是作者正式在用的色,引擎不夺作者的最终发言权。实测把照片挂上后,这两处对比度只有 **1.90 / 2.67**(无障碍标准线 3:1)——**偏暗的照片上深色次要文字会糊掉**。⇒ 用 `background.image` 的主题**自己**保证这两处看得清:抬高 `text-secondary` 的明度,或加大 `mask`。**图标栏不在此列**(那里的墨色由壳接管,见上一条)。
|
|
115
|
+
|
|
116
|
+
⚠️ **键名写错不报错、也不生效**:colorway 的键是**逐键直通**的(壳把 `"bg-window"` 原样写成 `--bg-window`,**没有白名单校验**)——`icon-actve` 这种手误既不会红、也不会有任何作用,只会在真机上「怎么没变化」。**新加或改动键之前**先查壳的变量契约:[02-变量契约](https://github.com/Encaron/linkdesk/blob/electron/02-Electron架构/归一化基建/外观主题化/02-变量契约.md)(或仓库 `src/index.css` 的 `:root`)。
|
|
117
|
+
|
|
106
118
|
> ⚠️ **别指望改 `--accent` 就完事**:有些控件故意读自己的 token(例如开关的 `--toggle-on-bg`)而不是 `--accent`——设计上就是让它们可以不同步。要精确控制就去读那个控件实际用的变量。
|
|
107
119
|
|
|
108
120
|
---
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@linkdesk/plugin-docs",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.57",
|
|
4
4
|
"description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"files": [
|