@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
|
@@ -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`)与**文档档案**,不是源码。
|