@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.
- package/README.md +58 -0
- package/docs/00-readme.md +189 -0
- package/docs/01-plugin-api-contract.md +171 -0
- package/docs/02-plugin-lifecycle.md +348 -0
- package/docs/03-contributes-spec.md +800 -0
- package/docs/04-distribution-format.md +172 -0
- package/docs/05-ui-conventions.md +549 -0
- package/docs/06-plugin-json-spec.md +640 -0
- package/docs/07-plugin-to-plugin-communication.md +299 -0
- package/docs/08-view-container-api.md +405 -0
- package/docs/09-plugin-directory-layout.md +301 -0
- package/docs/10-building-a-settings-plugin.md +164 -0
- package/docs/11-authoring-themes.md +173 -0
- package/docs/12-readme-media-contract.md +74 -0
- package/docs/13-development-guide.md +259 -0
- package/docs/14-data-pipeline-command-conventions.md +173 -0
- package/docs/15-multi-repo-and-local-workspace.md +86 -0
- package/docs/16-naming-conventions.md +77 -0
- package/docs/17-region-map.md +225 -0
- package/docs/18-cross-region-wiring.md +192 -0
- package/docs/19-component-cheatsheet.md +108 -0
- package/docs/20-adding-a-setting.md +159 -0
- package/docs/themes/01-build-a-theme-plugin.md +150 -0
- package/docs/themes/02-theme-field-index.md +145 -0
- package/docs/zh/00-README.md +189 -0
- package/docs/zh/01-/346/217/222/344/273/266API/345/245/221/347/272/246.md +171 -0
- 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
- package/docs/zh/03-/346/217/222/344/273/266contributes/350/247/204/350/214/203.md +800 -0
- 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
- 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
- package/docs/zh/06-plugin.json/350/247/204/350/214/203.md +640 -0
- package/docs/zh/07-/346/217/222/344/273/266/351/227/264/351/200/232/344/277/241.md +299 -0
- package/docs/zh/08-ViewContainer-/350/247/206/345/233/276/345/256/271/345/231/250API.md +403 -0
- 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
- 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
- package/docs/zh/11-/344/270/273/351/242/230/345/210/266/344/275/234.md +172 -0
- 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
- 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
- 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
- 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
- package/docs/zh/16-/345/221/275/345/220/215/350/247/204/350/214/203.md +77 -0
- package/docs/zh/17-/345/214/272/345/237/237/345/234/260/345/233/276.md +225 -0
- package/docs/zh/18-/345/214/272/345/237/237/351/227/264/344/272/222/345/212/250.md +192 -0
- package/docs/zh/19-/347/273/204/344/273/266/351/200/237/346/237/245.md +108 -0
- 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
- package/docs/zh/plugin.schema.json +687 -0
- 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
- 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
- package/package.json +20 -0
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
# Theme Field Index — Where Fields Live, What the Variables Are Called
|
|
2
|
+
|
|
3
|
+
> **This page does exactly two things: ① it tells you where each field's authoritative definition lives; ② it gives you a "domain → CSS variable" cross-reference.**
|
|
4
|
+
> 🔴 **There is exactly one place with authoritative field definitions: `theme.schema.json`** (`schemas/theme.schema.json` inside the SDK package). This page **does not copy the schema** — copies drift.
|
|
5
|
+
|
|
6
|
+
| | |
|
|
7
|
+
|---|---|
|
|
8
|
+
| Audience | People already writing recipes who need to look up "what is this key called and which variable does it map to" |
|
|
9
|
+
| Form | An index (look it up in a table → jump to the real source) |
|
|
10
|
+
| Not | A tutorial (→ [01-Build a Theme Plugin](01-build-a-theme-plugin.md)) · the recipe syntax deep reference (→ [11-Authoring Themes](https://github.com/Encaron/linkdesk/blob/electron/docs/11-authoring-themes.md)) |
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## 1. Top-Level Recipe Fields
|
|
15
|
+
|
|
16
|
+
| Field | Required | Meaning |
|
|
17
|
+
|:--|:--:|:--|
|
|
18
|
+
| `id` | ✅ | Recipe id (globally unique; matches `contributes.themes[].id` in `plugin.json`) |
|
|
19
|
+
| `name` | ✅ | Display name (the theme picker's title) |
|
|
20
|
+
| `type` | ✅ | `"dark"` \| `"light"` — the dark/light baseline |
|
|
21
|
+
| `colorways` | ✅ | **The colorway variant array** (a single colorway still goes in as 1 item) — each item is `{ id, name, colors }` |
|
|
22
|
+
| `appearance` | ❌ | The style domain (single value, sparse) — missing domains/keys inherit the shell default |
|
|
23
|
+
|
|
24
|
+
> These are the only 5 top-level fields. The type/enum/description of each field is defined by `theme.schema.json`.
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
## 2. The Four `appearance` Domains → CSS Variable Cross-Reference
|
|
29
|
+
|
|
30
|
+
### `radius` — eight radius tiers
|
|
31
|
+
|
|
32
|
+
| Recipe key | CSS variable | Meaning |
|
|
33
|
+
|:--|:--|:--|
|
|
34
|
+
| `xs` | `--radius-xs` | Scrollbars / toggles / drag indicators |
|
|
35
|
+
| `sm` | `--radius-sm` | Inputs / buttons / small badges (**the most used by far**) |
|
|
36
|
+
| `md` | `--radius-md` | Settings groups / cards |
|
|
37
|
+
| `lg` | `--radius-lg` | Dialogs / floating panels / menus |
|
|
38
|
+
| `xl` | `--radius-xl` | Large glassy panels (an engine-scale tier; few shell surfaces consume it today) |
|
|
39
|
+
| `2xl` | `--radius-2xl` | The largest panels / background containers |
|
|
40
|
+
| `pill` | `--radius-pill` | Pill (`999`) |
|
|
41
|
+
| `full` | `--radius-full` | Circle (`50`) |
|
|
42
|
+
|
|
43
|
+
> Write only the tiers you want to change, e.g. `"radius": { "md": 10, "lg": 16 }`.
|
|
44
|
+
|
|
45
|
+
### `glass` — glass and floating materials
|
|
46
|
+
|
|
47
|
+
| Recipe key | CSS variable | Meaning | What to write to turn it off |
|
|
48
|
+
|:--|:--|:--|:--|
|
|
49
|
+
| `type` | — | The glass recipe (the enum has only `"glass"`); **absent = no glass** | omit the `glass` domain |
|
|
50
|
+
| `blur` | `--glass-blur` | backdrop blur in px | `0` |
|
|
51
|
+
| `saturate` | `--glass-saturate` | Saturation boost | `1` |
|
|
52
|
+
| `tint` | `--glass-tint` | Color laid over the glass surface | `"transparent"` |
|
|
53
|
+
| `opacity` | `--glass-opacity` | Opacity of the glass surface (1 = opaque) | `1` |
|
|
54
|
+
| `specular` | `--glass-specular` | Top highlight strength (the "sheen" of liquid glass) | `0` |
|
|
55
|
+
| `specularColor` | — | Base color of the highlight (white by default; alpha still comes from `specular`) | — |
|
|
56
|
+
| `morph` | `--glass-morph` | Morph transition in ms ("responsiveness") | `0` |
|
|
57
|
+
| `radius` | — | Floating panel corner radius in px (0 = square, flush to the edge) | `0` |
|
|
58
|
+
| `shadow` | (maps to `--shadow-lift`) | Floating shadow on/off | `false` |
|
|
59
|
+
| `texture` / `textureOpacity` | (written into the per-surface background family) | Path to a tileable texture asset, and its opacity | omit |
|
|
60
|
+
|
|
61
|
+
> ⚠️ **Large areas of `blur` are a GPU cost** — the more sparing you are, the smoother things run.
|
|
62
|
+
|
|
63
|
+
### `font` — fonts
|
|
64
|
+
|
|
65
|
+
| Recipe key | CSS variable | Value |
|
|
66
|
+
|:--|:--|:--|
|
|
67
|
+
| `ui` | `--font-ui` | **A system font family name string** (one already present on the user's machine), **or** a relative asset path (`assets/xxx.woff2` — the shell registers an `@font-face` and then uses the family name) |
|
|
68
|
+
| `mono` | `--font-mono` | Same as above (monospace font for code/panels) |
|
|
69
|
+
|
|
70
|
+
### `background` — image backgrounds
|
|
71
|
+
|
|
72
|
+
| Recipe key | CSS variable | Meaning |
|
|
73
|
+
|:--|:--|:--|
|
|
74
|
+
| `image` | `--bg-image` | Image path (**relative**; the shell wraps it in `url()`) |
|
|
75
|
+
| `opacity` | `--bg-opacity` | Opacity of the image layer |
|
|
76
|
+
| `mask` | `--bg-mask` | Mask **lightness coefficient (a number 0–1; 0 = no mask)** |
|
|
77
|
+
| `maskColor` | (same as above) | Base color of the mask (black by default) |
|
|
78
|
+
| `mode` | — | `"panorama"` (default, one image spread across everything) \| `"zones"` (the same image sliced continuously across window regions) |
|
|
79
|
+
|
|
80
|
+
> 🔴 **`mask` is a number (0–1), not a color string** — to specify the mask color, use `maskColor`.
|
|
81
|
+
> (The fully-specified example in [11-Authoring Themes](https://github.com/Encaron/linkdesk/blob/electron/docs/11-authoring-themes.md) once wrote it as `rgba(...)`, which contradicts the schema; that has been corrected.)
|
|
82
|
+
|
|
83
|
+
---
|
|
84
|
+
|
|
85
|
+
## 3. `colorways[].colors` — How to Name Color Tokens
|
|
86
|
+
|
|
87
|
+
**The rule in one sentence: key = CSS variable name with the `--` prefix stripped.** Write `"bg-window"` in the recipe and the shell writes it into `--bg-window`.
|
|
88
|
+
|
|
89
|
+
**The batch authors change most often** (not the full set):
|
|
90
|
+
|
|
91
|
+
| Category | Token names |
|
|
92
|
+
|:--|:--|
|
|
93
|
+
| Background surfaces | `bg-window` · `bg-card` · `bg-input` |
|
|
94
|
+
| Text | `text-primary` · `text-secondary` · `text-muted` · `tone-surface-deep` / `tone-ink-on-deep` · `tone-surface-light` / `tone-ink-on-light` |
|
|
95
|
+
| Accent | `accent` · `accent-hover` |
|
|
96
|
+
| Dividers and borders | `border` · `separator` |
|
|
97
|
+
| Icons | `icon-inactive` |
|
|
98
|
+
| Status | `status-connected` · `status-disconnected` · `error` · `warning` · `success` |
|
|
99
|
+
| Scrollbars | `scrollbar-thumb` · `scrollbar-thumb-hover` |
|
|
100
|
+
| Badges | `badge-background` · `badge-foreground` · `badge-text` |
|
|
101
|
+
| Overlays | `scrim-dialog` · `scrim-overlay` · `floating-panel-backdrop` · `context-menu-shadow` |
|
|
102
|
+
|
|
103
|
+
**Where the full set is**: the complete table of the shell's default theme tokens = `:root` in the repo's `src/index.css` (close to a hundred of them).
|
|
104
|
+
**Change only a few and write only a few** — anything unwritten inherits the baseline (a light theme inherits the light backing, a dark theme the dark backing).
|
|
105
|
+
|
|
106
|
+
> ⚠️ **Don't count on changing `--accent` and being done**: some controls deliberately read their own token (a toggle's `--toggle-on-bg`, for example) instead of `--accent` — by design, so they can be decoupled. For precise control, go read the variable that control actually uses.
|
|
107
|
+
|
|
108
|
+
---
|
|
109
|
+
|
|
110
|
+
## 4. Assets and Paths
|
|
111
|
+
|
|
112
|
+
| Kind | Where it goes | How to write it in the recipe |
|
|
113
|
+
|:--|:--|:--|
|
|
114
|
+
| Fonts | `assets/xxx.woff2` / `.ttf` | `"font": { "ui": "assets/MyFont.woff2" }` |
|
|
115
|
+
| Background images | `assets/xxx.png` / `.jpg` / `.webp` | `"background": { "image": "assets/bg.png" }` |
|
|
116
|
+
| Textures | `assets/xxx.png` (tileable) | `"glass": { "texture": "assets/paper.png" }` |
|
|
117
|
+
| Plugin icon | `resources/icon.svg` | the `icon` field in `plugin.json` |
|
|
118
|
+
|
|
119
|
+
🔴 **Always relative paths** (relative to the plugin project root). Absolute paths (`/assets/...`) break once packaged — the shell uses one shared asset resolver to turn relative paths into accessible URLs.
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
## 5. Sparse Overrides and Inheritance (this one rule is enough)
|
|
124
|
+
|
|
125
|
+
```
|
|
126
|
+
colorways[].colors write only the color keys you want to change → unwritten keys inherit the baseline
|
|
127
|
+
appearance.<domain> write only the domains you want to change → unwritten domains inherit wholesale
|
|
128
|
+
appearance.<domain>.<key> write only the keys you want to change → unwritten keys inherit the shell default
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
**The less you write, the more stable it is.** When the shell later adjusts default appearance, themes that wrote little improve automatically; themes that wrote a lot get "stuck on old values".
|
|
132
|
+
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
## 6. Source-of-Truth List (when they disagree, these win)
|
|
136
|
+
|
|
137
|
+
| What you're looking up | Where to go |
|
|
138
|
+
|:--|:--|
|
|
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` |
|
|
143
|
+
| The full table of the shell's default tokens | `:root` in the repo's `src/index.css` |
|
|
144
|
+
|
|
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.
|
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
# 插件开发——从这里开始
|
|
2
|
+
|
|
3
|
+
> 🌐 **English version(作者面主显)→ [../03-plugin-authoring/00-readme.md](https://github.com/Encaron/linkdesk/blob/electron/docs/03-plugin-authoring/00-readme.md)**——本中文树是**维护者面**;两棵树**篇篇对应**,改了一边必须同步另一边(门禁 `check-author-docs-bilingual` 盯着)。
|
|
4
|
+
|
|
5
|
+
> **这个目录只为一件事件存在:让插件作者(和作者的 AI)从零开始快速学会做一个插件。**
|
|
6
|
+
> LinkDesk 核心是空壳,万物皆插件。**本页是导览**——按"我要做什么"或"我是哪一档"选入口,不用从头读到尾。
|
|
7
|
+
|
|
8
|
+
| | |
|
|
9
|
+
|---|---|
|
|
10
|
+
| 目标读者 | 插件开发者(不是核心开发者) |
|
|
11
|
+
| 怎么用 | 先在本页选入口 → 走 [13-插件开发指南](13-插件开发指南.md) 的动线 → 需要细节时按链接跳 |
|
|
12
|
+
| 别的 | 本页底部的 [文档索引](#文档索引) 是这一目录的全部篇目——找不到东西时看那里 |
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## 一、从哪开始
|
|
17
|
+
|
|
18
|
+
### 按「我要做什么」选
|
|
19
|
+
|
|
20
|
+
| 我要做什么 | 先读 | 然后 |
|
|
21
|
+
|:--|:--|:--|
|
|
22
|
+
| **做一个最小插件**(10 分钟档) | [13-插件开发指南](13-插件开发指南.md) 的「三档入口」 | 跑起来就行——`npm create` → `npm run dev` |
|
|
23
|
+
| **做一个视图插件**(30 分钟档:进区域、声明贡献点、用共享组件) | [17-区域地图](17-区域地图.md) | → [13 的 30 分钟档](13-插件开发指南.md) → [19-组件速查](19-组件速查.md) |
|
|
24
|
+
| **做一个高难度插件**(1 天档:数据管道 / 跨插件 / Canvas / LSP) | [13 的 1 天档](13-插件开发指南.md) | → [07-插件间通信](07-插件间通信.md) · [14-数据管道命令约定](14-数据管道命令约定.md) |
|
|
25
|
+
| **做一个主题**(不写代码) | [主题/01-做一个主题插件](主题/01-做一个主题插件.md) | → [主题/02-主题字段速查](主题/02-主题字段速查.md) |
|
|
26
|
+
| **给我的插件加一条配置项** | [20-我的插件加一条配置项](20-我的插件加一条配置项.md) | → [03-插件contributes规范](03-插件contributes规范.md) |
|
|
27
|
+
| **让几个区域联动**(侧栏选中 → 主区切换 → 状态栏更新) | [18-区域间互动](18-区域间互动.md) | → [07-插件间通信](07-插件间通信.md) |
|
|
28
|
+
| **查 API**(能调什么) | [01-插件API契约 §三](01-插件API契约.md)(三处 API 面的入口表) | → SDK 包内 README 速查表 / `linkdesk.d.ts` |
|
|
29
|
+
| **用壳提供的 UI 零件** | [19-组件速查](19-组件速查.md) | → [05-插件UI写法规约](05-插件UI写法规约.md) |
|
|
30
|
+
| **查某个字段** | [06-plugin.json规范](06-plugin.json规范.md) | → `plugin.schema.json`(IDE 补全) |
|
|
31
|
+
| **打包 / 给别人装 / 上架** | [04-插件分发格式](04-插件分发格式.md) | → [13 第 8–9 步](13-插件开发指南.md) |
|
|
32
|
+
| **工程放哪、仓怎么起名** | [15-多仓开发与本地工作区](15-多仓开发与本地工作区.md) | → [16-命名规范](16-命名规范.md) |
|
|
33
|
+
|
|
34
|
+
### 按「我是哪一档」选
|
|
35
|
+
|
|
36
|
+
**同一句话的可测版:** 陌生作者(或他的 AI)**不问任何人**,只拿脚手架产物:
|
|
37
|
+
|
|
38
|
+
| 档 | 目标 | 动线入口 |
|
|
39
|
+
|:--:|:--|:--|
|
|
40
|
+
| ⏱ **10 分钟** | 做出**最小可跑插件** | [13-插件开发指南](13-插件开发指南.md) 第 1–3 步 |
|
|
41
|
+
| ⏱ **30 分钟** | 做出**视图插件**(进得了区域、声明得了贡献点、用得上共享组件) | + 第 4–6 步 + [17-区域地图](17-区域地图.md) |
|
|
42
|
+
| ⏱ **1 天** | 做出**高难度插件**(数据管道 / 跨插件 / Canvas / LSP 级) | + 第 7–9 步 + [07](07-插件间通信.md) · [14](14-数据管道命令约定.md) · [18](18-区域间互动.md) |
|
|
43
|
+
|
|
44
|
+
> 🔴 **写作时的诚实提醒**:这三档是本目录的**验收标准**,不是营销口号。**如果哪一档走不通,卡住的那一步就是缺篇清单**——请把它反馈给我们。
|
|
45
|
+
|
|
46
|
+
---
|
|
47
|
+
|
|
48
|
+
## 二、插件能做什么
|
|
49
|
+
|
|
50
|
+
**没有 API 白名单。** 插件在渲染进程里运行(所有插件共用同一个渲染进程,互相之间靠壳中转),能 `import` 任何 JS 库、调用任何 Web API——Canvas、WebGL、WebAssembly、WebRTC、Web Audio……Web 平台的一切,不加限制。
|
|
51
|
+
|
|
52
|
+
系统级能力(串口、文件系统、配置、对话框)通过 `window.linkdesk.*` 暴露——插件走壳中转,不能直接调 Node.js 原始能力,也不能 `import` 壳内部源码。
|
|
53
|
+
|
|
54
|
+
| 你想做的 | 怎么做 | 例子 |
|
|
55
|
+
|------|------|------|
|
|
56
|
+
| GPS 地图 | `import` Leaflet / 高德 SDK → React 组件 | 高德地图插件 |
|
|
57
|
+
| 串口数据解析 | `window.linkdesk.protocol.*`(主进程协议注册表)+ `window.linkdesk.serial.onData` 数据管道 | SBQ 协议插件 |
|
|
58
|
+
| 卡片可视化 | 卡片工作台是插件——`contributes.views` 往卡片容器注册视图 | 温度计/波形图卡片 |
|
|
59
|
+
| 代码编辑器 | `import monaco-editor` → React 组件 | Monaco 编辑器插件 |
|
|
60
|
+
| CAD 查看器 | `import` Three.js → Canvas/WebGL | CAD 插件 |
|
|
61
|
+
| 文档阅读器 | `import markdown-it` / `<iframe>` | Markdown/HTML 阅读器 |
|
|
62
|
+
| 逻辑分析仪 | Canvas 2D + `window.linkdesk.serial` | 时序波形分析仪 |
|
|
63
|
+
| 3D 模型查看 | `import` Three.js / Babylon.js | STL/STEP 查看器 |
|
|
64
|
+
| 代码智能补全 | 接 LSP 协议 或 AI API | clangd / Copilot 插件 |
|
|
65
|
+
| 图标/按钮 | codicon 图标集 + CSS 变量 | 任何插件 |
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
## 三、插件贡献类型(声明什么 = 出现在哪里)
|
|
70
|
+
|
|
71
|
+
> `plugin.json` 的 `type` 字段**已废弃**——loader 从 `entry` / `mode` / `themes` / `languages` / `resources` / `contributes` 等声明字段自动检测贡献类型。**一个插件可同时贡献多种能力**(终端 = 视图 + 协议;CAD = 视图 + 主题)。
|
|
72
|
+
|
|
73
|
+
| 能力 | 声明方式 | 出现在哪 | 例子 |
|
|
74
|
+
|------|------|------|------|
|
|
75
|
+
| **视图**(标签页) | `entry` + `appearsIn.tabBar` | 主区标签页 | 终端/地图/CAD/编辑器 |
|
|
76
|
+
| **侧栏 / 底部面板** | `contributes.viewsContainers` + `contributes.views` | 侧栏 / 底部面板 | 文件树/输出/待办 |
|
|
77
|
+
| **状态栏条目** | 顶层 `statusBar[]` | 状态栏 | 连接状态/流量计数 |
|
|
78
|
+
| **标题栏按钮** | `contributes.titleBar` | 标题栏 | 一键运行 |
|
|
79
|
+
| **命令 / 菜单 / 快捷键** | `contributes.commands` / `menus` / `keybindings` | 命令面板 / 右键菜单 / 快捷键 | — |
|
|
80
|
+
| **设置项** | `contributes.configuration` | 设置页自动渲染一个分组 | → [20](20-我的插件加一条配置项.md) |
|
|
81
|
+
| **设置 UI**(整套替代品) | `factoryRole: "settings"` + `contributes.views` | 多套并存,用户切换 | → [10-如何造一个设置插件](10-如何造一个设置插件.md) |
|
|
82
|
+
| **主题** | `contributes.themes` | 主题选择器 | → [主题/01](主题/01-做一个主题插件.md) |
|
|
83
|
+
| **语言包**(UI 翻译) | `contributes.languages` | 语言列表 | 日本語 / English |
|
|
84
|
+
| **协议解析** | `mode` 字段 + `window.linkdesk.protocol.*` | 主进程协议注册表 | SBQ 心率协议 |
|
|
85
|
+
| **静态资源** | 插件目录 `resources/` 声明相对路径 | 随插件分发 | STM32 参考手册 HTML |
|
|
86
|
+
|
|
87
|
+
**每一块区域是什么、彼此什么关系、声明片段怎么抄** → [17-区域地图](17-区域地图.md)。
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
## 四、作者工具链四包
|
|
92
|
+
|
|
93
|
+
> 第三方作者在**自己的工程根**写插件,不碰壳仓库——从零到 `.linkdesk-plugin` 全走 npm。
|
|
94
|
+
|
|
95
|
+
| 包 | 干什么 | 作者何时装 |
|
|
96
|
+
|:--|:--|:--|
|
|
97
|
+
| `create-linkdesk-plugin` | 一行生成插件工程骨架(对标 yo code)——**还会替你建好 git 仓** | 建新插件时 `npm create`,一次性、不进项目 |
|
|
98
|
+
| `@linkdesk/plugin-sdk` | 作者工具链四命令:`dev`(dev 宿主+HMR)/ `build`(→ `.linkdesk-plugin`)/ `validate` / `lint`;随包 `plugin.schema.json` + `theme.schema.json` + dev 宿主页 | 每个插件工程 devDependencies |
|
|
99
|
+
| `@linkdesk/contracts` | `window.linkdesk.*` 全量 TS 类型(契约生成产物——单一真相源) | **不用主动装**——SDK 依赖它并全量转发 |
|
|
100
|
+
| `@linkdesk/ui` | 共享 UI 零件(按钮/下拉/开关/取色器/右键菜单…) | **可选**——想让界面跟内置同款(自动跟随主题/玻璃)时装 → [19-组件速查](19-组件速查.md) |
|
|
101
|
+
|
|
102
|
+
**关系一句话**:`create` 生成工程 → 工程装 `sdk` → `sdk` 带 `contracts`(类型随来)→ `ui` 独立、按需装。
|
|
103
|
+
> 版本号不写死在本页——**装的时候不带版本号即可拿到最新**。
|
|
104
|
+
|
|
105
|
+
**作者真正敲的命令**:
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
npm create linkdesk-plugin my-plugin # ① 建工程(每建一个用一次;自动 git init + 初始提交)
|
|
109
|
+
cd my-plugin && npm install # ② 装 SDK(类型自动进 TS program)
|
|
110
|
+
npm run dev # 预览:浏览器 dev 宿主 → 改码 HMR
|
|
111
|
+
npm run dev:real # 真机环:在已装 LinkDesk 里秒级真机调试(真 IPC 插件用)
|
|
112
|
+
npm run validate # 校验 plugin.json / 主题配方
|
|
113
|
+
npm run build # 交活:my-plugin.linkdesk-plugin(装进 LinkDesk / 发布)
|
|
114
|
+
npm run publish # 发布到你自己的 GitHub 仓(上架第一步)
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
---
|
|
118
|
+
|
|
119
|
+
## 五、从零到上线——最短路径
|
|
120
|
+
|
|
121
|
+
```
|
|
122
|
+
1. npm create linkdesk-plugin my-plugin → 生成工程(pluginId / name / author 已填好,git 仓已建)
|
|
123
|
+
2. 写 plugin.json + src/index.tsx → 声明你的插件、写第一段 UI
|
|
124
|
+
3. npm run dev → 浏览器预览宿主里看见它
|
|
125
|
+
4. npm run build → 产出 my-plugin.linkdesk-plugin(单文件 zip)
|
|
126
|
+
5. 装上 / 发布 → 给别人:一个文件搞定;上架:见下(两步)
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
**上架是两步,别只做第一步:**
|
|
130
|
+
|
|
131
|
+
| 步 | 做什么 | 做完之后谁看得见 |
|
|
132
|
+
|:--:|------|------|
|
|
133
|
+
| ① | `npm run publish`——发布到**你自己**的 GitHub 仓(Release 资产 + 仓库根 `marketplace.json`) | 只有手动把你的仓库加进"市场源"的人 |
|
|
134
|
+
| ② | **把你的插件收录进官方目录** | **所有默认配置的用户** ← 这一步才是真正的"上架" |
|
|
135
|
+
|
|
136
|
+
完整口径 → [04-插件分发格式 §上架是两步](04-插件分发格式.md) · 端到端旅程 → [13-插件开发指南](13-插件开发指南.md) 第 9 步。
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
## 硬约束——写任何一行插件代码前
|
|
141
|
+
|
|
142
|
+
1. **所有颜色走 CSS 变量 `var(--xxx)`**,禁止硬编码 hex
|
|
143
|
+
2. **所有 UI 文字走 `t()`**,禁止绕过 `t()` 硬编码显示字符串(i18n key = 插件 UI 原文,建议作者母语——中文插件用中文 key,英文/法文插件用自己的语言 key)
|
|
144
|
+
3. **右键菜单走声明式**——`plugin.json` `contributes.menus` 声明 + `<ContextMenu>` 消费(或 `window.linkdesk.menu.registerItems`),禁止手写右键菜单
|
|
145
|
+
4. **弹窗用 `createPortal` render 到 `document.body`**
|
|
146
|
+
5. **持久化走 `window.linkdesk.configuration.get/set/onChange`**,禁止 `localStorage.setItem()`
|
|
147
|
+
6. **插件只走 `window.linkdesk.*` API,禁止 `import @src/core/...`**(ESLint `noCoreImportInPlugin` error 级拦截——`.tsx`/`.ts` 都拦)
|
|
148
|
+
7. **不要条件渲染隐藏内容**——keep-alive 架构下所有标签页始终挂载
|
|
149
|
+
8. **壳不知道你的插件是干什么的**——不要依赖壳的特殊判断
|
|
150
|
+
|
|
151
|
+
---
|
|
152
|
+
|
|
153
|
+
## 文档索引
|
|
154
|
+
|
|
155
|
+
| # | 文档 | 什么时候读 |
|
|
156
|
+
|:--:|------|------|
|
|
157
|
+
| ★ | [13-插件开发指南](13-插件开发指南.md) | **第一次写插件从这里开始**——从 `npm create` 到上架的九步动线 + 三档入口 |
|
|
158
|
+
| 1 | [01-插件API契约](01-插件API契约.md) | 写第一行代码前——知道能调什么 API(**三处 API 面的总入口**) |
|
|
159
|
+
| 2 | [02-插件生命周期](02-插件生命周期.md) | 理解注册→激活→运行→卸载全过程 |
|
|
160
|
+
| 3 | [03-插件contributes规范](03-插件contributes规范.md) | 注册命令/菜单/快捷键/配置项/视图/主题/i18n/顶栏按钮 |
|
|
161
|
+
| 4 | [04-插件分发格式](04-插件分发格式.md) | 安装分发——让别人能装你的插件(含**上架两步**口径) |
|
|
162
|
+
| 5 | [05-插件UI写法规约](05-插件UI写法规约.md) | 右键菜单/浮层/持久化/快捷键两轨道/剪贴板三通道——必须走共享设施 |
|
|
163
|
+
| 6 | [06-plugin.json规范](06-plugin.json规范.md) | plugin.json 全部字段参考——**注意:这里没有 `readme` / `changelog` 字段**,说明与更新日志以文件为准 |
|
|
164
|
+
| 7 | [07-插件间通信](07-插件间通信.md) | 插件之间怎么传数据——**三通信机制**:事件广播 / 命令调用 / 数据管道 |
|
|
165
|
+
| 8 | [08-ViewContainer-视图容器API](08-ViewContainer-视图容器API.md) | 视图容器全字段:注册侧栏/面板视图、往别人容器里加内容、titleActions |
|
|
166
|
+
| 9 | [09-插件目录规范](09-插件目录规范.md) | 插件目录结构——文件放哪、命名约定 + **`README.md` / `CHANGELOG.md` 的权威判据** |
|
|
167
|
+
| 10 | [10-如何造一个设置插件](10-如何造一个设置插件.md) | **整套设置 UI 替代品**(≠ 给自己加一条配置项,那条见 20) |
|
|
168
|
+
| 11 | [11-主题制作](11-主题制作.md) | 配方写法深度参考(目录规范 / 满配示例 / 迁移与避坑) |
|
|
169
|
+
| 12 | [12-README说明区媒体契约](12-README说明区媒体契约.md) | README 放图/动图/封面外链视频/页内视频怎么写 |
|
|
170
|
+
| 13 | [13-插件开发指南](13-插件开发指南.md) | **动线**(同首行) |
|
|
171
|
+
| 14 | [14-数据管道命令约定](14-数据管道命令约定.md) | 数据管道命令的命名与注册约定 |
|
|
172
|
+
| 15 | [15-多仓开发与本地工作区](15-多仓开发与本地工作区.md) | 插件工程放哪、仓库名怎么起、**容器绝不建仓**红线 |
|
|
173
|
+
| 16 | [16-命名规范](16-命名规范.md) | **七种名字一条身份**——id 怎么起/能不能改、仓库叫什么、版本号四处同源 |
|
|
174
|
+
| **17** | **[17-区域地图](17-区域地图.md)** | **我的插件出现在哪一块**——图标栏/侧栏/主区/底部面板/状态栏逐区怎么声明 |
|
|
175
|
+
| **18** | **[18-区域间互动](18-区域间互动.md)** | **区域之间怎么联动**——侧栏选中 → 主区切换 → 状态栏更新(配方集) |
|
|
176
|
+
| **19** | **[19-组件速查](19-组件速查.md)** | **壳提供了哪些 UI 零件**、什么时候用哪个 |
|
|
177
|
+
| **20** | **[20-我的插件加一条配置项](20-我的插件加一条配置项.md)** | 最小做法:声明一条 → 设置页自动出现 → 代码里读 |
|
|
178
|
+
| **T1** | **[主题/01-做一个主题插件](主题/01-做一个主题插件.md)** | 做主题的动线(零代码) |
|
|
179
|
+
| **T2** | **[主题/02-主题字段速查](主题/02-主题字段速查.md)** | 配方字段与 CSS 变量的对照索引 |
|
|
180
|
+
|
|
181
|
+
**JSON Schema:** `plugin.schema.json`——IDE 自动补全 | 主题配方:SDK 包内 `schemas/theme.schema.json`
|
|
182
|
+
|
|
183
|
+
---
|
|
184
|
+
|
|
185
|
+
## 相关
|
|
186
|
+
|
|
187
|
+
- 契约类型真相源:`@linkdesk/contracts` 包内 `linkdesk.d.ts`(随 SDK 到达)
|
|
188
|
+
- 主题系统设计文档(**壳的为什么**,作者不必读):仓库 `docs/02-Electron架构/E5.8_归一化基建/外观主题化/`
|
|
189
|
+
- Tauri 时代旧版文档:`docs/01-Tauri_P1至P5.5/`(仅历史参考)
|
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
# 01 — 插件 API 契约
|
|
2
|
+
|
|
3
|
+
> 2026-08-04。**`window.linkdesk.*`——插件开发者能调用的全部系统级能力。** Web 平台能力(Canvas/WebGL/WebRTC/fetch 等)不限——只有系统级能力走此 API。
|
|
4
|
+
>
|
|
5
|
+
> **更新:** 单 WebView 回退后,`linkdesk.*` API 是插件访问壳的唯一正路。ESLint `error` 级拦截直接 import `ConfigurationService/FileService/pathUtils`。
|
|
6
|
+
>
|
|
7
|
+
> **更新:** 本文档从「手写命名空间表(第二份真相源)」改为**指针**——方法明细不再手写,唯一真相源 = **生成的契约文件** `contracts/linkdesk.d.ts`(见 §三)。原则/导航保留。
|
|
8
|
+
>
|
|
9
|
+
> **对标 VS Code:** `vscode` 命名空间。
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## 一、设计原则
|
|
14
|
+
|
|
15
|
+
| 原则 | 如何体现 |
|
|
16
|
+
|------|------|
|
|
17
|
+
| **核心无知** | 壳不认识任何插件的 pluginId |
|
|
18
|
+
| **合同优先** | 插件走 `window.linkdesk.*`,不走 `import @src/core` |
|
|
19
|
+
| **同步优先** | 能同步的 API 不同步封装(`path` 纯函数不走 IPC) |
|
|
20
|
+
| **安全** | 插件 preload 比壳窄——**唯一缺 `bridge` 命名空间**(壳主控专用:插件 IPC 请求经主进程转发到壳侧服务的信封);且 preload 沙箱零 Node 能力(不暴露 require/fs/child_process) |
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## 二、壳 vs 插件——API 差异
|
|
25
|
+
|
|
26
|
+
插件与壳在同一个渲染进程中运行,但注入的命名空间面不同。**每一面在哪个进程可用、池/壳/mock 四面覆盖如何——唯一真相源是[命名空间矩阵 §2 覆盖表](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/契约生成/命名空间矩阵.md#2-命名空间--四面覆盖矩阵)**,这里不再手写第二份清单。
|
|
27
|
+
|
|
28
|
+
几个要点(矩阵 §2 的摘要,细节以矩阵为准):
|
|
29
|
+
|
|
30
|
+
| 事实 | 说明 |
|
|
31
|
+
|------|------|
|
|
32
|
+
| **契约 40 命名空间** | 池注入 39(唯一缺 `bridge`);壳注入 22;mock 注入 12 |
|
|
33
|
+
| **池 = 插件运行时真相源** | 插件运行在池(pool)preload——池注入的命名空间为 **required**;`bridge` 真壳独有 |
|
|
34
|
+
| **「仅壳」≠ 插件不可调** | `window.*`/`shell.*`/`hotExit.*`/`getFilePath` 池**实有注入**(N1 超集注记)——旧版把这几面标 ❌ 仅壳是错的 |
|
|
35
|
+
| **契约必选面漂移已清零** | D1 `env.get(pluginId)` 转发、D2 `clipboard.readText` 壳补、D3 `dialog.openFile` 壳补——#20 全补实现,无 `?` 降级 |
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## 三、完整 API 定义 → 指针
|
|
40
|
+
|
|
41
|
+
### 3.0 唯一真相源
|
|
42
|
+
|
|
43
|
+
**`window.linkdesk.*` 的全部方法签名、入参、返回、载荷类型 = [contracts/linkdesk.d.ts](https://github.com/Encaron/linkdesk/blob/electron/contracts/linkdesk.d.ts)**(自动生成,勿手改)。
|
|
44
|
+
|
|
45
|
+
- **生成源:** `src/core/api/linkdesk-api.ts` + `linkdesk-api/`(14 域接口)+ `src/core/types/ipc/*` + `src/core/types/pool/*`(wire 载荷类型)
|
|
46
|
+
- **生成器:** `scripts/generate-contract.mjs`(Route C——契约类型文件为源,纯类型打包单文件)
|
|
47
|
+
- **机械门禁:** preload 双端 `satisfies` 契约面类型 → tsc 漂移门禁;`npm run check` 内 `contracts:check` hash 字节比对(#21)
|
|
48
|
+
- **覆盖矩阵:** 每个命名空间 × 池/壳/mock 四面覆盖 → [命名空间矩阵 §2](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/契约生成/命名空间矩阵.md#2-命名空间--四面覆盖矩阵)
|
|
49
|
+
|
|
50
|
+
### 3.1 插件侧怎么消费
|
|
51
|
+
|
|
52
|
+
**路径 A——仓库 tsconfig 别名(本仓库内插件):** 根 `tsconfig.json` 已配 `"@linkdesk/contracts": ["./contracts/linkdesk.d.ts"]`,类型 import 直走契约文件:
|
|
53
|
+
|
|
54
|
+
```typescript
|
|
55
|
+
// 类型——契约文件里命名的面接口(`import type`,零运行时耦合)
|
|
56
|
+
import type { FileEntry, PluginStateChangedPayload } from "@linkdesk/contracts";
|
|
57
|
+
|
|
58
|
+
// 运行时——ambient 类型直出(文件内 `declare global Window.linkdesk`,无需 import)
|
|
59
|
+
async function list(): Promise<FileEntry[]> {
|
|
60
|
+
return window.linkdesk.filesystem.listDir("/workspace");
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
**路径 B——独立 npm 包(第三方插件,#22.6):** `npm i -D @linkdesk/contracts` 后同款 `import type { ... } from "@linkdesk/contracts"`。
|
|
65
|
+
|
|
66
|
+
> **包形态(建):** `contracts/` 即 npm 包根(`@linkdesk/contracts`,`types` 入口直指 `linkdesk.d.ts`,零构建,`files` 白名单只 d.ts)。**版本轴独立(2026-09-06 拆焊,反向 22.6 版本联动):** 包版本**不再随壳**——软件升级(用户轴)≠ 契约升级(作者轴);只有当 `window.linkdesk.*` API 面变了才升版发布。**内容检测不撤**:d.ts/runtime-shapes 逐字节比对壳源码,漂移即 `contracts:check` 红(改 API 忘重生成 = commit 卡死);**货架节奏 = check-npm-release 黄灯闸**(作者面内容变 + 版本没动 → 提醒 bump+publish)。**消费形态验收:** 仓库根 `contracts-example/`——独立 tsconfig + `file:../contracts` 本地引用,`npx tsc --noEmit` 零错误,全程零 `@src/core`(`npm pack` 出 tarball → 装真实 npm 包路径同样通过)。**发布态:** ✅ 已真发 `@linkdesk/contracts@0.1.0`(2026-09-04)+ `@linkdesk/contracts@0.1.1`(2026-09-06,拆焊后首个独立轴版本)+ `@linkdesk/contracts@0.1.2`(2026-09-06 同日,0.1.1 带旧「版本联动」README 出包 → README 修正重发,d.ts 未变)——第三方 `npm i -D @linkdesk/contracts` 直装 registry 真包;真实包 tsc 验收已通过(真实包 tsc 验收)。plugin-sdk 与 `@linkdesk/ui` 同期已真发。
|
|
67
|
+
|
|
68
|
+
**路径 C——拷贝文件:** 直接把 `contracts/linkdesk.d.ts` 拷进插件项目 + tsconfig 引用。契约文件单文件自包含(94 声明,零 import 依赖),拷贝即用。
|
|
69
|
+
|
|
70
|
+
> **三个路径任选其一,禁止 `import type { ... } from "@src/core"`**——那是偷壳源码类型(见 §五)。
|
|
71
|
+
|
|
72
|
+
### 3.2 运行时语义约定(d.ts 表达不了的,在这里)
|
|
73
|
+
|
|
74
|
+
> 方法签名以契约文件为准;以下是不进类型的**行为契约**——插件侧必须按此写。
|
|
75
|
+
|
|
76
|
+
| 命名空间 | 运行时约定 |
|
|
77
|
+
|------|------|
|
|
78
|
+
| **events** | 频道命名 `<插件id>:<数据名>`(如 `serial:rawData`、`sbq-protocol:parsed`)。壳广播事件表见下 |
|
|
79
|
+
| **quickPick** | Promise resolve **结构化副本**(contextBridge 跨世界结构化克隆,`===` 原对象不可行);Escape/点遮罩/失焦/被新 `show()` 顶掉 → resolve `undefined`(last-wins);`opts.items` 非数组 → reject。壳浮层优先级更高。**调用放组件 effect 内**——壳侧执行半程调 `show` 因无此 API 而 no-op |
|
|
80
|
+
| **viewContainer** | **元数据单向流**:视图注册以 plugin.json `contributes.views` 为准;`registerView` 更新既有视图只覆盖元数据、`render` 保留原组件;`descriptor` 传 `render`/`actions`/`pinnedContent` 池侧白名单剥掉(不可跨 IPC);查询不存在的容器/视图 → `undefined`/`[]` |
|
|
81
|
+
| **decorations** | **同步契约**:`provideDecoration` 返回 `FileDecoration \| null \| undefined`,**不得返回 Promise**(异步提供方被跳过);同 pluginId 重复 `registerProvider` 幂等覆盖;注销/注册自动全量刷新通知 `onDidChange([])`;provider 抛异常自愈剔除该条目 |
|
|
82
|
+
| **filesystem** | 插件权限:插件数据目录读写、workspace 目录读、**其他插件目录禁止** |
|
|
83
|
+
| **configuration** | 配置 key 命名规则 `<pluginId>.<property>`(如 `editor.fontSize`、`serial-monitor.baudRate`) |
|
|
84
|
+
| **serial** | **多口路由:** 打开/关闭/动作定向接口的 `portName` **可选**——缺省 = 唯一打开口(0 口抛「串口未打开」;≥2 口抛「多串口已打开,请指定 portName」;**失败可见,不静默**)。三推流通道(`onData`/`onStats`/`onSystem`)载荷**对象化**带 `portName` 路由键(`SerialDataPayload`/`SerialStatsPayload`/`SerialSystemPayload`)——订阅方按**会话口**过滤(key=portName 是通用路由键模式:谁消费谁过滤,壳不代收)。每标签页仍单口(D3),会话-端口绑定在插件侧 |
|
|
85
|
+
| **panel** | `panel.reveal(viewId)` 声明寻址聚焦底部面板视图——面板隐藏 → 展开并切到该视图(Ctrl+J 同机制);已显示 → 切换聚焦;**viewId 不在 panel 容器 → no-op**(不报错)。**`panel.moveToEditor` 已移除**(弃内容迁移——位置移动是布局命令的事)。 `panel.revealFloating(viewId)` 壳内悬浮面板(类型 B)——按声明弹出某视图为悬浮面板。声明寻址 = ViewContainerService 全局视图索引(`contributes.views` 已注册**任意容器**视图,不限 panel——插件声明 `contributes.floatingPanel.viewId` 引用之)。**身份开关键(I8-2)**:无面板 → 开;同视图 → 关(toggle);他面板 → 替换;**viewId 未声明/声明插件未装 → no-op**(不崩)。面板默认动作 =「在主窗口中打开」(仅声明插件可开成标签页时出现)+ 最大化 toggle + 关闭 |
|
|
86
|
+
| **hotExit** | 崩溃恢复专用——脏内容落盘 `%APPDATA%/linkdesk/hot-exit/`(主进程路径约定单源,插件零直写);保存/关闭标签页后调 `clear` 删备份 |
|
|
87
|
+
| **shell** | 壳级 OS 动作:`showItemInFolder(p)` 资源管理器高亮单文件 / `openInTerminal(dirPath, terminalExe?, customCommand?)` 外部终端打开 / `startDrag(filePath, iconPath?)` 拖出到桌面。**`pluginLocation(pluginId)` / `openPluginFolder(pluginId, kind)` 插件磁盘位置两件套**——前者返回 `{ installDir, dataDir } | null`(**给身份不给路径拼装权**:路径由主进程解析,插件侧拿结果;盘上找不到 → `null`;`dataDir` 只在插件**真落过盘**时非 `null`,空/无 = 那行不该画);后者 `kind: "install" \| "data"` 用资源管理器开目录**内容**(同 `appearance.revealStorage` 手感,非 `showItemInFolder` 高亮单文件),`install` 目录不在盘上抛错,`data` 先建空目录再开。**(G4):`relaunch` 真重启应用**(退出并重新启动进程)——⚠️ **仅壳 preload 注入(契约 `?` 可选)**,池侧调用前必须判存在(`window.linkdesk.shell.relaunch?.`)。与 `window.location.reload` 的区别是**池在不在**:池是独立 `WebContentsView`,壳 reload 不重建它,更新视图类插件后 reload 只会看到旧 bundle;`relaunch` 调用后本进程随即终止,**不要依赖它的返回值**(Promise 永不落地) |
|
|
88
|
+
| **appearance** | `revealStorage` 打开外观存储目录(`userData/appearance`)——主进程解析路径并 `shell.openPath` 开资源管理器**内容**(非 `showItemInFolder` 高亮单文件);目录缺省也建(打开即见存储位置,空目录合法),`openPath` 失败抛错 fail-loud。返回 `Promise<void>` |
|
|
89
|
+
| **app** | `app.getVersion` = 宿主软件版本号(`Promise<string>`,只读)——唯一运行时来源 = Electron `app.getVersion`(`package.json` 单点,02 §2.3);**主软件版本比对入口**(市场 minAppVersion、更新检查 #57.5 消费)。壳内另有 `getProductInfo` 私有扩展(关于页 8 字段数据源 #57.14,不在契约——池插件不可调) |
|
|
90
|
+
| **tabs** | **跨窗资源事件联动:** `updateLabelBySourceId(sourceId, label)` / `closeBySourceId(sourceId)` = **全窗广播语义**——资源持有者在主窗与全部脱出窗的标签页同步更新/关闭;`sourceId` 为全局唯一资源身份(文件路径/会话 id),变更即全局事实(联动**不依赖调用方与标签页同窗**——脱出窗标签随侧栏改名/删除即时联动,对标 VS Code)。`focusBySourceId(sourceId)` = **按来源窗路由**(视图动作,聚焦到具体某窗,非全局事实)。**无新 API**——复用既有面,此行为契约由全窗广播保证 |
|
|
91
|
+
| **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 插件自注册 |
|
|
92
|
+
| **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 结构化克隆 ⇒ 只能放可克隆数据 |
|
|
93
|
+
|
|
94
|
+
**壳广播事件(插件可订阅,走 `events.on`):**
|
|
95
|
+
|
|
96
|
+
| 频道 | payload | 触发时机 |
|
|
97
|
+
|------|------|------|
|
|
98
|
+
| `theme:changed` | `{ themeId, themeType, variables }` | 用户切换主题(CSS 变量自动注入,无需手动订阅)。**载荷 `variables` 含字号变量 `--font-size-*` + `--ui-scale`**(全局字号缩放走既有主题通道,**无新事件**;插件字号消费 token 见 05-UI写法规约 §10) |
|
|
99
|
+
| `iconTheme:changed` | `{ iconThemeId, mappings, fontFaces?, glyphCss? }` | 用户切换图标主题(设置 `app.iconTheme`)。`iconThemeId` = 选择的图标主题 id;`mappings` = 该主题的映射表(`IconThemeMappings` 形状,图像资产已解析为 `linkdesk://` 绝对 URL)或 `"default"` 时为 `undefined`(消费方回退 codicon 保底)。 `fontFaces`/`glyphCss` = 主题声明了自定义字体时(mappings JSON 顶层 `font` 段)的 @font-face 规格与 glyph 类 CSS 原文——池 preload 已自动注入池文档(自定义图标字体渲染,消费方无需处理);无 font 段/`"default"` 时缺省。 `mappings` 顶层可声明 5 个默认图标 `file`/`folder`/`folderExpanded`/`rootFolder`/`rootFolderExpanded`(单条目,对齐 VS Code iconTheme 顶层键)——未命中匹配表(普通文件夹/新建文件/根文件夹)时消费方用主题默认图标而非 codicon;缺省 = codicon 保底。**不自动生效的仅是映射本身——需要自定义文件图标视觉的插件手动订阅**(如文件树按 `mappings` 换图标,对标 VS Code `onDidChangeProductIconTheme`) |
|
|
100
|
+
| `lang:changed` | `{ lang, resources }` | 用户切换语言 |
|
|
101
|
+
| `workspace:changed` | `{ rootPath }` | 用户打开/切换文件夹 |
|
|
102
|
+
| `plugin:installJobs` | `{ jobs: InstallJob[] }`(**全量快照,非增量**) | 壳侧安装/卸载队列变化(建 /补阶段与百分比 /补 `kind`·`cancellable`)。`InstallJob` = `{ jobId, pluginId, origin: "user"\|"dependency", kind: "install"\|"uninstall", cancellable: boolean, displayName, state: "queued"\|"running"\|"settled", terminal?: "success"\|"failed"\|"parked", error?, stage?, percent?, message? }`——**每次广播都是整表**,消费方**直接替换本地镜像**,别做增量合并。**晚订阅者拿到最新整表**:池 preload 顶层缓存一份、订阅时同步回放(视图重挂不会停在旧快照)。⚠️ 这是**公开事件面**,不是市场私有管道——任何插件可订阅做自己的进度面;⚠️ **`stage`/`percent`/`message`/`kind`/`cancellable` 均为只增不改的增补字段**,旧消费方忽略即可。⚠️ `origin: "dependency"` = 某插件自己拖来的依赖,藏在发起它的那一行(`origin: "user"`)里面 |
|
|
103
|
+
|
|
104
|
+
### 3.3 与旧手写版的差异(读者注意)
|
|
105
|
+
|
|
106
|
+
旧版 §3.x 逐命名空间方法清单已删除(= 手写第二份真相源,必然漂移)。生成的契约解决了几处**旧文档与实现不符**的漂移:
|
|
107
|
+
|
|
108
|
+
| 点 | 旧手写版 | 契约/实现实况(#20 后) |
|
|
109
|
+
|------|------|------|
|
|
110
|
+
| `serial.listPorts()` | 写成 `getPorts()` | 契约 `listPorts()`——实现一直叫这个,旧文档笔误 |
|
|
111
|
+
| `serial.onData/onStats/onSystem` | `cb: (d: any)` / string | **载荷对象化**:`onData(p: SerialDataPayload)` / `onStats(p: SerialStatsPayload)` / `onSystem(p: SerialSystemPayload)`——三通道均带 `portName` 路由键(`SerialStats` 已删除,无死类型尾巴) |
|
|
112
|
+
| `decorations.provideDecoration` | 写可返回 `Promise<FileDecoration>` | 契约**同步 only**(返回 Promise 的提供方被跳过) |
|
|
113
|
+
| `pluginState.onChange` | 注释「未来多 WebView 恢复后可用」 | 池已注入 onChange——订阅可用;通配键名订阅走 `events.on("plugin-state:changed")`(补导出 `PluginStateChangedPayload`) |
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
## 四、IPC 可靠性约定
|
|
118
|
+
|
|
119
|
+
1. **每个 invoke 有 10s 超时。** 超时 throw `Error`
|
|
120
|
+
2. **返回值有 falsy 可能。** `""`/`0`/`false` 是合法值。用 `isNaN(n) ? default : n` 而非 `n || default`
|
|
121
|
+
3. **IPC 回调里用到 React state → 用 ref 桥接**
|
|
122
|
+
4. **`onChange` 回调模式**(configuration/language)——返回 unsubscribe 函数,组件 unmount 时调用清理
|
|
123
|
+
|
|
124
|
+
---
|
|
125
|
+
|
|
126
|
+
## 五、禁止事项
|
|
127
|
+
|
|
128
|
+
| ❌ | ✅ 替代 |
|
|
129
|
+
|---|---|
|
|
130
|
+
| `import { normalizePath } from "@src/core/pathUtils"` | `lk.path.normalize(p)` |
|
|
131
|
+
| `import { getConfigurationValue } from "@src/core/ConfigurationService"` | `lk.configuration.get(key)` |
|
|
132
|
+
| `import { listDir } from "@src/core/FileService"` | `lk.filesystem.listDir(p)` |
|
|
133
|
+
| `import { getWorkspaceFolders } from "@src/core/WorkspaceService"` | `lk.workspace.getFolders()` |
|
|
134
|
+
| `import type { FileEntry } from "@src/core/types/fileEntry"` | `import type { FileEntry } from "@linkdesk/contracts"` |
|
|
135
|
+
|
|
136
|
+
**ESLint `error`(`noCoreImportInPlugin`,#20-d 收紧):** `import { ... } from "@src/core/..."` **和** `import type { ... } from "@src/core/..."` → 🚫 编译失败。测试文件不再豁免(vitest 单进程理由不成立)。
|
|
137
|
+
|
|
138
|
+
**允许的 import(共享控件走 `@linkdesk/ui` npm 包;`@src/core` 例外白名单全表见 `eslint-local-rules.js` PLUGIN_IMPORT_WHITELIST):**
|
|
139
|
+
- `@linkdesk/contracts` **类型**(`import type`,零运行时耦合)——registry 真包(见 §三 3.1)
|
|
140
|
+
- `@linkdesk/ui` **共享控件 / 共享 hooks**(ContextMenu / InlineInput / SelectBox / Toggle / ColorPicker / FormRow / ThemePicker 等,收归)——**在你自己工程的 `dependencies` 里显式声明**(`"@linkdesk/ui": "^0.1.4"`),构建走货架。🔴后**官方插件与第三方是同一款工程形态**(官方 6 只在已补上显式声明);唯一例外是壳仓内那两只**开发夹具**(仍靠根 workspaces 提升)。**一律不从 `@src/components/shared/*` import**(后共享控件第二入口已删)
|
|
141
|
+
- **纯工具白名单(`@src/core` 例外)**:`@src/core/pipeline/*`(DataConverter / DataDispatch / RingBuffer / ProtocolParser)+ `@src/core/utils/CancellationToken` + `@src/core/registry/commands/MenuRegistry`(仅 MenuId 类型/枚举)等——全表只以 eslint-local-rules.js 为准,不在此抄第二份
|
|
142
|
+
- 🔴 **复核结论**:这条白名单**实际只剩壳仓夹具在用**——官方插件搬出壳仓后,它们的源码里 `@src` 早已零命中(运行时全走 `window.linkdesk.*`,已实测)。白名单**保留**(夹具仍在 `plugins/` 内、仍由同一条 eslint 规则守着),但**第三方作者请当作它不存在**:你能用的只有 `@linkdesk/contracts` / `@linkdesk/ui` / `window.linkdesk.*` 三样
|
|
143
|
+
- **例外登记**:白名单外的 import 必须登记在案再放行(插件独立铁律审计项)
|
|
144
|
+
|
|
145
|
+
> **`useConfiguration` / `useSendData` / `ViewContainerService` 等壳 hooks/服务禁止 import**(有模块级状态 → 调用方的修改壳进程看不到)——插件读配置走 `window.linkdesk.configuration`,状态同步走 `window.linkdesk.events`(订阅广播)/ `serial.onData` 等数据管道(见 `07-插件间通信.md`)。
|
|
146
|
+
|
|
147
|
+
---
|
|
148
|
+
|
|
149
|
+
## 六、设备通道边界
|
|
150
|
+
|
|
151
|
+
> 接「二、壳 vs 插件」——**设备插件作者能独立做到哪一步、平台承诺到哪里。** 依据 = 一条壳边界纪律:**壳只提供通用通道,不内置设备业务**。
|
|
152
|
+
|
|
153
|
+
**一句话:解析归你、通道现成——不需要找壳作者、不需要等壳发版。** 通道类型收敛归壳(可枚举),设备无限归插件。
|
|
154
|
+
|
|
155
|
+
| 层 | 设备示例 | 通道 | 作者状态 |
|
|
156
|
+
|:--|:--|:--|:--|
|
|
157
|
+
| **串口系**(最大头) | USB-CAN 适配器(CH340/CP210x 虚拟串口)、GPS 模块(NMEA)、USB-TTL、便宜逻辑分析仪 | `linkdesk.serial.*`(Phase 6 通用化后) | ✅ **立即可写,零壳依赖**;多口/多插件并存成立 |
|
|
158
|
+
| **自定义 USB** | 专业逻辑分析仪(Saleae 类,自定义 USB 端点) | 未来 `usb` 通道 | ⏳ E6 后版本化演进加一条通用通道(一次性,同 serial 同构);**加完前这类设备要等** |
|
|
159
|
+
| **厂商私有 DLL** | 高端设备(只有厂商 SDK/DLL) | 原生通道 | ⚠️ 独立架构课题(渲染沙箱无 Node 权限);不在当前范围 |
|
|
160
|
+
|
|
161
|
+
**平台责任边界(作者可放心依赖):**
|
|
162
|
+
- **通道正确性 + API 稳定承诺**——平台作者负责通道(打开 → 流式读写 → 关闭/错误/多实例/资源回收);E6 上架后改 API = 版本化演进(`engines` 声明),加了不违约、不加不影响存量插件。
|
|
163
|
+
- **设备协议正确性作者自持**——CAN 帧/NMEA/采样解析全归插件,壳不认识任何设备。
|
|
164
|
+
- **同一物理口仅单消费方**——OS 驱动排他(`serial-monitor` 打开的口,其他插件/标签页不能同时打开;多插件并存 = 各开各的口)。
|
|
165
|
+
|
|
166
|
+
> 确认 `linkdesk.serial.*` 现成能力 → [contracts/linkdesk.d.ts](https://github.com/Encaron/linkdesk/blob/electron/contracts/linkdesk.d.ts) `Serial` 域。要自定义 USB/原生通道 → 提给平台作者——这是「加通道」范畴(收敛、可枚举、一次性),不是给某插件打工。
|
|
167
|
+
|
|
168
|
+
---
|
|
169
|
+
|
|
170
|
+
> **下一份:** `02-插件生命周期.md`
|
|
171
|
+
> **索引:** `00-README.md`
|