@linkdesk/plugin-docs 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/README.md +58 -0
  2. package/docs/00-readme.md +189 -0
  3. package/docs/01-plugin-api-contract.md +171 -0
  4. package/docs/02-plugin-lifecycle.md +348 -0
  5. package/docs/03-contributes-spec.md +800 -0
  6. package/docs/04-distribution-format.md +172 -0
  7. package/docs/05-ui-conventions.md +549 -0
  8. package/docs/06-plugin-json-spec.md +640 -0
  9. package/docs/07-plugin-to-plugin-communication.md +299 -0
  10. package/docs/08-view-container-api.md +405 -0
  11. package/docs/09-plugin-directory-layout.md +301 -0
  12. package/docs/10-building-a-settings-plugin.md +164 -0
  13. package/docs/11-authoring-themes.md +173 -0
  14. package/docs/12-readme-media-contract.md +74 -0
  15. package/docs/13-development-guide.md +259 -0
  16. package/docs/14-data-pipeline-command-conventions.md +173 -0
  17. package/docs/15-multi-repo-and-local-workspace.md +86 -0
  18. package/docs/16-naming-conventions.md +77 -0
  19. package/docs/17-region-map.md +225 -0
  20. package/docs/18-cross-region-wiring.md +192 -0
  21. package/docs/19-component-cheatsheet.md +108 -0
  22. package/docs/20-adding-a-setting.md +159 -0
  23. package/docs/themes/01-build-a-theme-plugin.md +150 -0
  24. package/docs/themes/02-theme-field-index.md +145 -0
  25. package/docs/zh/00-README.md +189 -0
  26. package/docs/zh/01-/346/217/222/344/273/266API/345/245/221/347/272/246.md +171 -0
  27. package/docs/zh/02-/346/217/222/344/273/266/347/224/237/345/221/275/345/221/250/346/234/237.md +348 -0
  28. package/docs/zh/03-/346/217/222/344/273/266contributes/350/247/204/350/214/203.md +800 -0
  29. package/docs/zh/04-/346/217/222/344/273/266/345/210/206/345/217/221/346/240/274/345/274/217.md +172 -0
  30. package/docs/zh/05-/346/217/222/344/273/266UI/345/206/231/346/263/225/350/247/204/347/272/246.md +549 -0
  31. package/docs/zh/06-plugin.json/350/247/204/350/214/203.md +640 -0
  32. package/docs/zh/07-/346/217/222/344/273/266/351/227/264/351/200/232/344/277/241.md +299 -0
  33. package/docs/zh/08-ViewContainer-/350/247/206/345/233/276/345/256/271/345/231/250API.md +403 -0
  34. package/docs/zh/09-/346/217/222/344/273/266/347/233/256/345/275/225/350/247/204/350/214/203.md +301 -0
  35. package/docs/zh/10-/345/246/202/344/275/225/351/200/240/344/270/200/344/270/252/350/256/276/347/275/256/346/217/222/344/273/266.md +164 -0
  36. package/docs/zh/11-/344/270/273/351/242/230/345/210/266/344/275/234.md +172 -0
  37. package/docs/zh/12-README/350/257/264/346/230/216/345/214/272/345/252/222/344/275/223/345/245/221/347/272/246.md +74 -0
  38. package/docs/zh/13-/346/217/222/344/273/266/345/274/200/345/217/221/346/214/207/345/215/227.md +259 -0
  39. package/docs/zh/14-/346/225/260/346/215/256/347/256/241/351/201/223/345/221/275/344/273/244/347/272/246/345/256/232.md +173 -0
  40. package/docs/zh/15-/345/244/232/344/273/223/345/274/200/345/217/221/344/270/216/346/234/254/345/234/260/345/267/245/344/275/234/345/214/272.md +86 -0
  41. package/docs/zh/16-/345/221/275/345/220/215/350/247/204/350/214/203.md +77 -0
  42. package/docs/zh/17-/345/214/272/345/237/237/345/234/260/345/233/276.md +225 -0
  43. package/docs/zh/18-/345/214/272/345/237/237/351/227/264/344/272/222/345/212/250.md +192 -0
  44. package/docs/zh/19-/347/273/204/344/273/266/351/200/237/346/237/245.md +108 -0
  45. package/docs/zh/20-/346/210/221/347/232/204/346/217/222/344/273/266/345/212/240/344/270/200/346/235/241/351/205/215/347/275/256/351/241/271.md +159 -0
  46. package/docs/zh/plugin.schema.json +687 -0
  47. package/docs/zh//344/270/273/351/242/230/01-/345/201/232/344/270/200/344/270/252/344/270/273/351/242/230/346/217/222/344/273/266.md +150 -0
  48. package/docs/zh//344/270/273/351/242/230/02-/344/270/273/351/242/230/345/255/227/346/256/265/351/200/237/346/237/245.md +145 -0
  49. package/package.json +20 -0
@@ -0,0 +1,549 @@
1
+ # 插件 UI 写法规约
2
+
3
+ > **一句话:核心已提供标准组件和注册表——不要手写轮子。手写 = 风格不一致 + 以后归一化时要拆。**
4
+ > 写插件前扫一眼,避免 B62 式返工。
5
+ > **2026-09-06 与实现对齐核对**(对账):塌平单根(无 plugins/{builtin,user})· 共享控件走 @linkdesk/ui · 分发 = .linkdesk-plugin zip。本页对应机制引用已清。
6
+
7
+ ---
8
+
9
+ ## 1. 右键菜单 → `<ContextMenu>` + MenuRegistry
10
+
11
+ **❌ 禁止:** 手写 `<div className="my-menu">` + `useState` + click-outside listener。
12
+
13
+ **✅ 正确:**
14
+ ```json
15
+ // ① 声明菜单项——plugin.json contributes.menus(首选,声明式)
16
+ {
17
+ "contributes": {
18
+ "menus": {
19
+ "editorContext": [
20
+ { "command": "myPlugin.copy", "group": "navigation" },
21
+ { "command": "myPlugin.clear", "group": "edit" }
22
+ ]
23
+ }
24
+ }
25
+ }
26
+ ```
27
+
28
+ ```tsx
29
+ // 运行时动态注册(等价)——window.linkdesk.menu.registerItems(menuId, pluginId, items)
30
+ window.linkdesk.menu.registerItems("editorContext", "myPlugin", [
31
+ { command: "myPlugin.copy", group: "navigation" },
32
+ { command: "myPlugin.clear", group: "edit" },
33
+ ]);
34
+
35
+ // ② 使用统一组件——MenuId 是开放 string,直接写字符串字面量
36
+ <ContextMenu menuId="editorContext" />
37
+ ```
38
+
39
+ **理由:** `<ContextMenu>` 自带 backdrop + 四种失焦(Escape / click backdrop / window blur / 选项 click)+ 键盘导航 + when 条件过滤。手写做不到这四种失焦——B62 教训。
40
+
41
+ **MenuId 是开放 string(`src/core/registry/commands/MenuRegistry.ts` `export type MenuId = string`)——插件声明任意字符串即契约,无需壳加代码。** 壳内置注册点(MENU_SLOTS 常量表):
42
+
43
+ | MenuId(字符串字面量) | 场景 |
44
+ |---|---|
45
+ | `commandPalette` | Ctrl+Shift+P 命令面板 |
46
+ | `tabContext` | 标签栏标签右键 |
47
+ | `panelViewContext` | 面板标签栏右键(位置/对齐子菜单 + 视图显隐列表) |
48
+ | `editorContext` | 标签页主内容区右键 |
49
+ | `extensionGear` | 底部齿轮菜单(设置/命令面板/主题选择器) |
50
+ | `marketplaceItemGear` | 插件市场条目齿轮(启用/禁用/卸载) |
51
+ | `menuBar` | ☰ 汉堡菜单栏 |
52
+ | `panel` | 菜单栏「面板」菜单 |
53
+ | `fileContext` | 文件树右键 |
54
+ | `cardContext` | 卡片右键 |
55
+ | `quickSendContext` | 快捷发送药丸右键 |
56
+ | `iconBar` | 图标栏右键 |
57
+ | `settingItemGear` | 设置项齿轮(Settings Editor 行 hover) |
58
+ | `viewTitleContext` | 侧栏视图 title 右键(折叠/重置位置/视图同组) |
59
+
60
+ 新增右键场景 → MenuId 开放 string 直接声明即可(如 `"myMenu"`):`contributes.menus.myMenu` 声明 + `<ContextMenu menuId="myMenu" />` 消费——**零壳改动**(插件独立铁律)。壳若要在此场景提供统一渲染点才需在 MENU_SLOTS 加条目。
61
+
62
+ ---
63
+
64
+ ## 2. 浮层 / 弹窗 → `createPortal`
65
+
66
+ **❌ 禁止:** 弹窗嵌在组件树的深层 div 里。
67
+
68
+ **✅ 正确:**
69
+ ```tsx
70
+ import { createPortal } from "react-dom";
71
+
72
+ return createPortal(
73
+ <div className="my-dialog">{/* ... */}</div>,
74
+ document.body // ← 关键:渲染到 body
75
+ );
76
+ ```
77
+
78
+ **理由:** keep-alive 架构下非活跃标签页 `display: none`,子元素用 `position: fixed` 也看不见(B54 教训)。render 到 `document.body` 才能突破组件树限制。
79
+
80
+ ---
81
+
82
+ ## 3. 持久化 → `window.linkdesk.configuration`(plugin.json contributes.configuration 声明)
83
+
84
+ **❌ 禁止:** `localStorage.setItem()` / `PreferenceService.loadPrefs()` / 手写文件读写 / `import ... from "@src/core/..."`。
85
+
86
+ **✅ 正确——走 `window.linkdesk.configuration`(插件通信铁律:只走 window.linkdesk.*,禁止 import @src/core):**
87
+ ```tsx
88
+ // 读配置(Promise——值运行时动态)
89
+ useEffect(() => {
90
+ window.linkdesk.configuration.get<boolean>("myPlugin.showLineNumbers").then((v) => {
91
+ setShowLineNumbers(v);
92
+ });
93
+ }, []);
94
+
95
+ // 写配置
96
+ await window.linkdesk.configuration.set("myPlugin.showLineNumbers", true);
97
+
98
+ // 订阅变更——返回 unsubscribe,unmount 调用
99
+ useEffect(() => {
100
+ return window.linkdesk.configuration.onChange<boolean>("myPlugin.showLineNumbers", (v) => {
101
+ setShowLineNumbers(v);
102
+ });
103
+ }, []);
104
+ ```
105
+
106
+ **plugin.json 声明配置项:**
107
+ ```json
108
+ {
109
+ "contributes": {
110
+ "configuration": {
111
+ "title": "My Plugin",
112
+ "properties": {
113
+ "myPlugin.showLineNumbers": {
114
+ "type": "boolean",
115
+ "default": true,
116
+ "description": "显示行号"
117
+ }
118
+ }
119
+ }
120
+ }
121
+ }
122
+ ```
123
+
124
+ **理由:** 壳自动持久化 + 重启恢复 + Settings Editor 自动渲染。手写 localStorage → 丢掉 Settings Editor 集成 + 下一个持久化 bug。
125
+
126
+ ---
127
+
128
+ ## 4. 快捷键 → 两轨道:声明式(非文本键)+ 池侧自处理(文本键/焦点绑定键)
129
+
130
+ 快捷键有**两条轨道**,选哪条取决于键的性质。**选错轨道 = 键死或劫持全池**(教训)。
131
+
132
+ ### 4.1 轨道一:`contributes.keybindings`(设置面板可见)——**仅限非文本键**
133
+
134
+ **❌ 禁止:** 把 `ctrl+c` / `ctrl+v` / `ctrl+x` / `ctrl+a` / `f2` 等**文本编辑键**写进 `contributes.keybindings`。
135
+
136
+ **✅ 正确:**(非文本键——如 `ctrl+k` / `ctrl+shift+e` / `f5`)
137
+ ```json
138
+ {
139
+ "contributes": {
140
+ "keybindings": [
141
+ {
142
+ "key": "ctrl+k",
143
+ "command": "myPlugin.clear",
144
+ "when": "activeEditor == 'myPlugin'"
145
+ }
146
+ ]
147
+ }
148
+ }
149
+ ```
150
+
151
+ **理由(为什么文本键是雷):** 声明/注册的键会同步进主进程 keyCache → `before-input-event` 命中即**无条件吞键**(不认 when、不认可编辑状态、不认 handler 是否存在)。壳注册一个 `ctrl+c` 就吞掉全池所有输入框/Monaco 的原生 `ctrl+c`。文本键正解 = 轨道二。
152
+
153
+ ### 4.2 轨道二:池侧自处理(容器 onKeyDown)——文本键 + 焦点绑定键正解
154
+
155
+ **✅ 正确:** 组件自己的键盘交互在自己的**容器 `onKeyDown`** 里处理:
156
+
157
+ ```tsx
158
+ <div
159
+ tabIndex={0} // 让容器可聚焦——点击子项时浏览器把焦点给最近可聚焦祖先
160
+ onKeyDown={(e) => {
161
+ if (e.key === "F2") { e.preventDefault(); startRename(); }
162
+ }}
163
+ >
164
+ {items}
165
+ </div>
166
+ ```
167
+
168
+ **为什么是正解:** 池内所有插件共用一个 document——**DOM 焦点天然分区**。容器聚焦才收键,Monaco 聚焦收不到,多插件各干各的 `ctrl+c` 互不打扰。不需要 when、不需要冲突检测。文件树剪贴板键 = 共享 `useClipboardKeys` hook + 命令链同款。剪贴板相关键可复用 `src/pool/hooks/useClipboardKeys`(`onCopy`/`onCut`/`onPaste` 声明式回调,机制一处实现一处修)。
169
+
170
+ **❌ 反模式(红字):** `document.addEventListener("keydown", ...)` / `window.addEventListener("keydown", ...)` = **全局劫持**——绕过分区前提,插件有活动会话时劫持全池同键(串口 F2 曾劫持文件树 F2)。**`tabIndex` + 容器 `onKeyDown` 才是焦点分区正解**;非焦点元素不触发,可加 `tabIndex={0}` 承接。
171
+
172
+ **注意:** 轨道二键**不进快捷键设置面板**——面板只显示 KeybindingRegistry 绑定(轨道一)。这是设计取舍(注册即吞池,见 4.1),不是 bug。
173
+
174
+ ### 4.3 剪贴板三选一通道表
175
+
176
+ | 你想复制的 | 通道 | 例子 |
177
+ |---|---|---|
178
+ | 可编辑元素内文本(input/textarea/Monaco) | **浏览器原生**——什么都不用写 | 输入框内 Ctrl+C/V |
179
+ | 任意文本 | `window.linkdesk.clipboard.writeText` | 复制选中文本到系统剪贴板 |
180
+ | 文件/路径列表 | `window.linkdesk.clipboard.writeFileList` | 文件树复制 → 资源管理器可粘贴(CF_HDROP) |
181
+
182
+ **注意:** 可编辑元素走浏览器原生,**不要**声明快捷键也不要拦截——Electron/Chromium 自动接系统剪贴板。
183
+
184
+ ---
185
+
186
+ ## 5. 颜色 → CSS 变量 `var(--xxx)`
187
+
188
+ **❌ 禁止:** 硬编码 `#0078d4` / `#1e1e1e` / `#ffffff`。
189
+
190
+ **✅ 正确:**
191
+ ```css
192
+ .my-element {
193
+ color: var(--text-primary);
194
+ background: var(--bg-input);
195
+ border: 1px solid var(--border);
196
+ }
197
+ ```
198
+
199
+ **理由:** 换主题后硬编码颜色不变 → 暗色主题下白字白底不可见。见 `src/index.css` 查看所有可用 CSS 变量。
200
+
201
+ ---
202
+
203
+ ## 6. 文字 → `t()` 国际化
204
+
205
+ **❌ 禁止:** 绕过 `t()` 硬编码显示字符串(`<button>发送</button>` / `<button>Send</button>`)。
206
+
207
+ **✅ 正确:**
208
+ ```tsx
209
+ import { useTranslation } from "react-i18next";
210
+ const { t } = useTranslation();
211
+ <button>{t("发送")}</button> // i18n key = 插件 UI 原文(中文插件用中文,英文/法文插件用自己的语言)
212
+ ```
213
+
214
+ ---
215
+
216
+ ## 7. 侧栏列表选中条目 → `onMouseDown`(不是 `onClick`)
217
+
218
+ **❌ 禁止:** 侧栏垂直列表中选中条目用 `onClick`。
219
+
220
+ **✅ 正确:**
221
+ ```tsx
222
+ <div
223
+ className={`my-list-item${isActive ? " active" : ""}`}
224
+ onMouseDown={() => onSelect(item.id)}
225
+ >
226
+ <span>{item.label}</span>
227
+ </div>
228
+ ```
229
+
230
+ **理由:** 侧栏条目垂直紧邻——快速点击时 mousedown 在条目 A、mouseup 滑到条目 B。浏览器 `click` 事件规范:mousedown 和 mouseup 落在不同元素 → click 投递到两者的共同祖先 → React 在祖先上找不到 handler → 静默丢失。`onMouseDown` 只关注按下位置,不要求释放在同一元素——消除快速点击丢事件。
231
+
232
+ **对标 VS Code:** Explorer 文件树选文件用 `onMouseDown`,不是 `onClick`。这是经过千万用户验证的模式,不要自己设计。
233
+
234
+ **适用场景:** 侧栏中任何垂直排列、条目间距小的可点击列表——会话列表、文件树、数据库连接、MQTT 主题、设备列表等。
235
+
236
+ **子元素的处理:** 条目内的操作按钮/输入框需要加 `onMouseDown={(e) => e.stopPropagation()}` 防止误触父条目的选中:
237
+ ```tsx
238
+ <button
239
+ onMouseDown={(e) => e.stopPropagation()}
240
+ onClick={(e) => { e.stopPropagation(); handleDelete(); }}
241
+ >
242
+ ✕
243
+ </button>
244
+ ```
245
+
246
+ ---
247
+
248
+ ## 8. 插件自有数据模型 → `Emitter` 响应式模式
249
+
250
+ **❌ 禁止:** command handler 里改 model 后手动调 `rerender()` / `setVersion()` / 传 `treeVersion` prop。
251
+
252
+ **✅ 正确——Web 标准 `EventTarget`(零核心 import,插件自有类直接继承):**
253
+ ```typescript
254
+ class MyModel extends EventTarget {
255
+ private _items: Item[] = [];
256
+
257
+ add(item: Item): void {
258
+ this._items.push(item);
259
+ this.dispatchEvent(new CustomEvent("change")); // ← 每个改状态的方法末尾 dispatch
260
+ }
261
+
262
+ remove(id: string): void {
263
+ this._items = this._items.filter(i => i.id !== id);
264
+ this.dispatchEvent(new CustomEvent("change"));
265
+ }
266
+ }
267
+ ```
268
+
269
+ ```tsx
270
+ // 组件 mount 时订阅,unmount 清理
271
+ function MyView({ model }: { model: MyModel }) {
272
+ const [version, setVersion] = useState(0);
273
+
274
+ useEffect(() => {
275
+ const onChange = () => setVersion(v => v + 1);
276
+ model.addEventListener("change", onChange);
277
+ return () => model.removeEventListener("change", onChange); // unmount 自动注销
278
+ }, [model]);
279
+
280
+ const items = useMemo(() => computeItems(model), [model, version]);
281
+ // ...
282
+ }
283
+ ```
284
+
285
+ **理由:** 三次时序 bug(badge 0 / when 失效 / 刷新不更新树)根因都是 module 级 command handler 改了 mutable model,React 感知不到。model 自己通知变更(`EventTarget`/`CustomEvent` 是 Web 标准,不需要壳的 `Emitter`)——handler 只改 model,不碰 React。
286
+
287
+ **适用场景:** 插件有 module 级 command handler 需要改数据后触发 UI 刷新。
288
+
289
+ **⚠️ 插件禁止 `import { Emitter } from "@src/core/CoreEvents"`——那是壳内部实现(插件通信铁律 + ESLint `noCoreImportInPlugin` error 级拦截)。插件自有 model 用 Web 标准 `EventTarget`;插件与插件/壳之间的事件走 `window.linkdesk.events`(见 `07-插件间通信.md`)。**
290
+
291
+ ---
292
+
293
+ ## 9. 系统 UI 浮层 → linkdesk API(quickPick / notifications / dialog)
294
+
295
+ **❌ 禁止:** 手写选择器弹层 / `window.alert()` / `window.confirm()` / `import ... from "@src/core/..."`。
296
+
297
+ **✅ 正确:**
298
+ ```tsx
299
+ // 选择器——window.linkdesk.quickPick.show({ items, placeholder, prefix })
300
+ const picked = await window.linkdesk.quickPick.show({
301
+ placeholder: "选择目标会话",
302
+ items: [
303
+ { label: "会话 A", description: "/dev/ttyUSB0" },
304
+ { label: "会话 B", description: "/dev/ttyUSB1" },
305
+ ],
306
+ });
307
+
308
+ // 通知——window.linkdesk.notifications.show(message, { type })
309
+ await window.linkdesk.notifications.show("已连接", { type: "info" });
310
+ await window.linkdesk.notifications.show("校验失败", { type: "error" });
311
+
312
+ // 确认 / 提示 / 文件选择——window.linkdesk.dialog
313
+ const ok = await window.linkdesk.dialog.confirm("确定删除该会话?");
314
+ await window.linkdesk.dialog.alert("版本冲突,已跳过");
315
+ const file = await window.linkdesk.dialog.openFile({
316
+ filters: [{ name: "DXF 文件", extensions: ["dxf"] }],
317
+ });
318
+ ```
319
+
320
+ **理由:** 三者都是池内宿主统一渲染(QuickPickHost / **铃铛宽通知面板** / DialogHost)——样式与壳一致、随主题与字号缩放走。手写浮层 = 风格不一致 + keep-alive 下 `position: fixed` 失效(B54)。完整签名见 `contracts/linkdesk.d.ts`。
321
+
322
+ > ⚠️ **通知不是「自动消失的浮卡」**(通知面归一 +更正):右下角窄 toast 链路已整删,**唯一通知面 = 状态栏铃铛宽面板**。作者要知道的三件事:
323
+ > 1. **通知不弹卡、不抢焦点、不挡操作**——它进铃铛(未读计数 +1),用户点开才看见。别把通知当「必须被看见」的通道:要用户当场决定 → 用 `dialog.confirm`(模态、抢焦点)。
324
+ > 2. **同来源常驻有配额**——按 `options.source` 分组,每组常驻最多 5 条,超出顶掉同来源最老的。刷屏不会堆成墙,但**也别指望靠通知留长期记录**。
325
+ > 3. **键盘可达是「面板可达」,不是「通知可达」**——铃铛可用键盘聚焦打开、面板内可 Tab 走遍、`Esc` 关;但面板**没有焦点陷阱**(非模态,焦点可自由离开)。**别写「按 Tab 就能到我的通知按钮」这种假设**——用户可能根本不开面板。
326
+
327
+ **通知主动作按钮(`notifications.show` 的 `actions`):** 失败 / 需要用户行动的通知可带 `actions` 按钮数组——点击走**命令系统**执行(对标 VS Code `showErrorMessage(msg, { title, command })` 动作)。命令 handler 由插件自注册(`commands.registerCommand`):
328
+
329
+ ```tsx
330
+ // 失败 toast + [重试]/[查看依赖]——command = 插件自注册命令
331
+ await window.linkdesk.notifications.show("安装失败:无法连接源", {
332
+ type: "error", // error 类 toast 停留 8s(够读诊断);info/warning 停留 6s
333
+ actions: [
334
+ { id: "retry", label: "重试", isPrimary: true, command: "myplugin.retryInstall" },
335
+ { id: "deps", label: "查看依赖", command: "myplugin.openDeps" },
336
+ ],
337
+ });
338
+ // 命令可带参——点击执行 command(...args)
339
+ await window.linkdesk.notifications.show("保存冲突", {
340
+ type: "warning",
341
+ actions: [{ label: "强制保存", command: "myplugin.saveForce", args: [filePath] }],
342
+ });
343
+ ```
344
+
345
+ 按钮文案 = 最终显示文本(壳不二次翻译);`isPrimary: true` = 主按钮(accent),不设 = 次级文本按钮。**不传 `actions` = 现状无按钮,零行为变化**。完整类型见 `contracts/linkdesk.d.ts`(`notifications.show` options 的 `actions`)。
346
+
347
+ **进度通知 + 长驻通知 + 来源身份:** `show` **一律返回句柄**(不是只有进度条才有)。三条最容易踩空的写法:
348
+
349
+ ```tsx
350
+ // ① 进度通知——句柄驱动同一条通知(不会刷出 N 条)
351
+ const h = await window.linkdesk.notifications.show("正在下载…", {
352
+ progress: true, // 开真进度条;不传 percent = 不定态动画
353
+ source: "myplugin", // 见 ③
354
+ });
355
+ await h.update("正在下载…", 42); // 0-100;只传 message = 保持不定态
356
+ await h.finish("下载完成"); // 关闭进度条,可选补一条完成通知
357
+ // 或 await h.cancel(); // 直接关掉,不补完成通知
358
+
359
+ // ② 长驻通知——不自动消失,等用户点 ×(错误诊断类用)
360
+ await window.linkdesk.notifications.show("端口被占用,请关闭其他程序", {
361
+ type: "error",
362
+ persistent: true,
363
+ });
364
+
365
+ // ③ 来源身份——面板按它分组,每组常驻各 5 条配额
366
+ await window.linkdesk.notifications.show("同步失败", { source: "myplugin" });
367
+ ```
368
+
369
+ **三个必须知道的点:**
370
+
371
+ 1. **句柄是唯一钥匙**:一条通知**只能被创建它的那个句柄**更新/删除。别处 `show` 同文案 = 另一条通知,撤不掉对方。撤长驻通知(如失败的 `persistent`)就用它自己的句柄或让用户点 ×。
372
+ 2. **`source` 必须自己报**:池是单进程共享 realm,所有插件共用同一个 `window.linkdesk`,preload **无法**知道这次 `show` 是哪个插件发的 ⇒ 只能作者显式传。**不传 → 全落「其他」组**;插件传自己的插件 id,壳自身域用 `app.<域>`。
373
+ 3. **`persistent` 有配额**:每组(按 `source`)常驻最多 5 条,超出顶掉同来源最老的并给汇总提示。**长驻 ≠ 无限留档**——要留档写自己的文件。
374
+
375
+ > 完整的**行为契约**(不是签名,签名看 `contracts/linkdesk.d.ts`)在 [`01-插件API契约.md`](01-插件API契约.md) §3.2 的 `notifications` 行——本节只给写法,语义以那里为准。
376
+
377
+ **富内容确认框(`dialog.confirmContent`):** 要确认框里放**不止一行字**(表单 / 列表 / 截图 / 自定义排版)时用这条——**对话框是壳(居中、遮罩、Esc、焦点锁、点遮罩取消),内容由你的视图自画**(对标 VS Code「对话框是壳、内容插件定」):
378
+
379
+ ```tsx
380
+ // 1) plugin.json 先声明这个内容的视图(contributes.views 的任意容器均可)
381
+ // 2) 代码里按「声明 id」寻址打开它
382
+ const ok = await window.linkdesk.dialog.confirmContent({
383
+ pluginId: "myplugin", // 内容归属插件(壳据此复合寻址)
384
+ viewId: "myplugin.confirmImport", // 内容视图声明 id
385
+ title: "导入确认", // 兜底标题——content 视图解析失败时壳回落纯文字确认
386
+ message: "将覆盖 3 个条目", // 兜底正文
387
+ payload: { files: ["a.ts", "b.ts"] }, // 不透明载荷:壳不解释,你的视图自己读
388
+ });
389
+ if (ok) { /* 用户确认 */ } // false = 取消 / 关闭
390
+ ```
391
+
392
+ 内容视图那一半(**同一份代码里的另一个视图**,读载荷 + 表态):
393
+
394
+ ```tsx
395
+ // 你的内容视图组件里——挂载即打开,读一次够(每次开新弹窗都是全新挂载)
396
+ function MyConfirmContent() {
397
+ const data = window.linkdesk.dialogHost.current();
398
+ if (!data || data.open !== true) return null; // 防御:不白屏
399
+ const payload = data.content?.payload as MyPayload;
400
+ return (
401
+ <div>
402
+ {/* 正文排版、按钮全归你画 */}
403
+ <button onClick={() => window.linkdesk.dialogHost.cancel()}>取消</button>
404
+ <button onClick={() => window.linkdesk.dialogHost.confirm()}>确定</button>
405
+ </div>
406
+ );
407
+ }
408
+ ```
409
+
410
+ **兜底是硬的**:`viewId` 解析不出来(视图没声明 / 声明插件没装)→ 壳**回落成纯文字确认框**(用 `title`/`message`),弹窗照样出、**不会静默死**。所以 `title`/`message` 别省。载荷经结构化克隆过 IPC,只能放可克隆的数据(不能放函数/React 元素)。结算只有 `dialogHost.confirm()` / `dialogHost.cancel()` 两条路——**别自己 `setState` 关弹窗**,壳不认。
411
+
412
+ ---
413
+
414
+ ## 10. 字号 → `--font-size-*` token + `--ui-scale`(度量体系归一化)
415
+
416
+ **❌ 禁止:** 插件文本字号写裸 `px`(`font-size: 14px`)——`check-font-scale-audit` 门禁(`npm run check`)机械拦截。
417
+
418
+ **✅ 正确:** 字号消费 `var(--font-size-*)`;行高 unitless(`1.5`)或 `calc(... * var(--ui-scale))`;固定上界(输入框/按钮/状态栏高)写 `calc(Npx * var(--ui-scale))` 随全局缩放。统一全局字号缩放(设置 `app.uiFontScale` 85–150%,恒显恒生效)。
419
+
420
+ **档位表**(100% 渲染 = `--ui-scale: 1`;引擎按缩放系数算好最终 px):
421
+
422
+ | 档 | 基准 px | 语义 |
423
+ |---|---|---|
424
+ | `--font-size-2xs` | 11 | 徽章/路径 |
425
+ | `--font-size-xs` | 12 | 次要文本/按钮/统计 |
426
+ | `--font-size-sm` | 13 | UI 主文本(对齐 VS Code 13px) |
427
+ | `--font-size-md` | 14 | 菜单/tab/文件树 name |
428
+ | `--font-size-lg` | 16 | 图标字形/内容图标(配 14px 文字) |
429
+ | `--font-size-xl` | 18 | 区标题 |
430
+ | `--font-size-2xl` | 22 | 行图标/大字 |
431
+ | `--font-size-3xl` | 28 | pd-name |
432
+ | `--font-size-4xl` | 30 | welcome-title |
433
+
434
+ **铁律 + 边界(对标档案 §五 图标裁决 / §六.2 monaco 孤岛拍板):**
435
+ - **独立显示图标不随字号比例**(装饰/品牌语义,与文本不直接相邻)——`.icon-btn .plugin-icon--codicon` 24 / `.plugin-icon--emoji` 24 / `.hamburger-btn` 20 / hero-icon 48 / 行图标 20 等,白名单豁免见 `scripts/check-font-scale-audit.mjs`。
436
+ - **内容级字号走 `contributes.configuration`**(如 `editor.fontSize`)——大文本区/编辑器内容由插件自有配置控制,不随 `--ui-scale`。
437
+ - **monaco 内容孤岛先例**:编辑器内容读 `editor.fontSize`,chrome(状态栏/面包屑)随全局——两轴正交,各管各的。
438
+ - **对齐规则**:现有 `NNpx` 迁移到档位按「+1 档」——`12→sm / 13→md / 11→xs / 10→2xs / 14→lg / 18→xl`(100% 即放大到新默认基线,对标 VS Code)。
439
+
440
+ ---
441
+
442
+ ## 11. token 契约——六域矩阵 + 诚实边界 + 数据纪律(.5)
443
+
444
+ > **一句话:** 写 UI 前先查 11.1 六域矩阵——用 `var(--*)` 的表单/控件/表面**自动跟随主题 + 玻璃 + 全局缩放**,零插件感知。做对靠推荐、做错靠门禁显红但 WARN、绕过靠标准 eslint-disable 知情声明(内容/品牌死色合法豁免,见 11.2)。
445
+ > 门禁 = `linkdesk-plugin-sdk lint`(`@linkdesk/plugin-sdk` 内置):eslint 规则腿 + 三 check 扫描腿双轨,15 项**全 WARN 永不 fail build/上传**——是建议不是封锁。作者项目根跑一次,违规即红 + 自解释修复文案。
446
+
447
+ ### 11.1 token 六域矩阵——作者知道有哪些变量,才写得出「自动跟随」
448
+
449
+ | 域 | var() 键(完整清单永远以 `src/index.css` 为准) | 作者写法 | 门禁覆盖 |
450
+ |---|---|---|---|
451
+ | **颜色** | `--text-primary/--text-secondary/--text-muted`(文字色来源由 fontTone 控)+ `--bg-window/--bg-side-panel/--bg-card/--bg-input/--bg-selection` + `--accent/--accent-hover` | `color: var(--text-primary)` | `linkdesk/no-hardcoded-hex` |
452
+ | **表面** | `--bg-*` 表面填充 + `--surface-radius`(跟壳全局圆角滑杆) | `background: var(--bg-card)` | `linkdesk/no-hardcoded-hex` |
453
+ | **圆角** | `--radius-xs/sm/md/lg/xl/2xl` + `--surface-radius` | `border-radius: var(--radius-md)` | `linkdesk/no-hardcoded-radius`(border-radius 裸 px 即红) |
454
+ | **玻璃** | `--glass-blur/--glass-saturate/--glass-tint/--glass-morph/--glass-specular…`(`src/index.css` 全组) | `backdrop-filter: blur(var(--glass-blur)) …` | 契约引导——组合形态,逐条门禁管不住 |
455
+ | **字号** | `--font-size-2xs … 4xl` + `--ui-scale`(`app.uiFontScale` 缩放轴,档位表见 §10) | `font-size: var(--font-size-md)` / em/rem | `check-font-scale`(check 腿——字号裸 px 即红) |
456
+ | **字体族** | `--font-ui` / `--font-mono` | `font-family: var(--font-ui)` | 契约引导(作者合法自选字体) |
457
+
458
+ `var(--*)` = 换主题/玻璃/全局缩放自动跟随,零插件感知——**这正是 @linkdesk/ui 控件层「零思考跟随」的底层原因**(54b/54c:控件全 token,插件 `npm i @linkdesk/ui` 消费即跟)。控件复用统一从 `@linkdesk/ui` import(见 §速查),不手写轮子。
459
+
460
+ ### 11.2 诚实边界 / 知情绕行——内容与品牌色可以有自己天空
461
+
462
+ **门禁三档(07 §六):** 推荐(照抄即对)/ 警告(15 项自解释,红但 **WARN 永不 fail**)/ 知情绕行(标准 eslint-disable 声明带理由)。**任何生态都管不住作者硬写死颜色**——VS Code 也有不跟随主题的扩展。门禁做的是把「做对」变默认、「做错」变显式红但可**知情绕行**:注释带理由 = 浏览器危险站点「仍要访问」的知情确认,不是静默关灯。
463
+
464
+ **合法豁免类别:** var() 回退 hex(`color: var(--x, #fff)` = 合规形态,不拦)/ 取色器色板 / canvas 绘图 / 引擎区 / **内容画布视图级豁免**。
465
+
466
+ **内容 vs chrome 边界(愤怒的小鸟考核实证):** 游戏 / 数据可视化 / canvas 主区 = **内容世界,不是 UI chrome**——UI chrome 跟主题走(var()/t()/@linkdesk/ui),内容可以有自己天空(草地/血条红/天空蓝不必跟主题)。作者**视图级一次声明豁免**,门禁对内容区不逐条亮灯(一个游戏 5-10 处硬编码逐条 disable 太吵):
467
+
468
+ ```tsx
469
+ /* eslint-disable linkdesk/no-hardcoded-hex, linkdesk/no-hardcoded-radius -- 内容画布:游戏主区自绘 */
470
+ export function GameBoard() {
471
+ return <canvas /* 画蓝天草地血条红——内容世界,不是 UI chrome */ />;
472
+ }
473
+ ```
474
+
475
+ ```tsx
476
+ // 行级知情绕行(品牌死色徽标——只豁免本行,其他行照样拦)
477
+ // eslint-disable-next-line linkdesk/no-hardcoded-hex -- 品牌固定色徽标
478
+ const PRO_BADGE = <span style={{ color: "#ff6b00" }}>PRO</span>;
479
+ ```
480
+
481
+ ```css
482
+ /* css 里同款格式(check 脚本认)——取色器色板固定值,本行豁免 */
483
+ /* eslint-disable-next-line linkdesk/no-hardcoded-hex -- 取色器色板 */
484
+ .swatch--brand { background: #ffd700; }
485
+ ```
486
+
487
+ **语义:** 命中豁免的行**整体静默**不亮灯(对齐 eslint 原生 suppress——disable 声明后不逐条报);**无声明 = 未处理偏离**,`linkdesk-plugin-sdk lint` 报告正常亮 WARN。**不是新语法**——与壳现有 `no-hardcoded-hex` 报错建议格式同款。**背景不被玻璃化是机制层天然成立**——backdrop-filter 只刷壳表面元素,不套插件视图根节点,作者画的内容本就不被玻璃化。
488
+
489
+ ### 11.3 非 CSS 引擎适配——翻译桥(引擎自渲染不走 CSS 变量)
490
+
491
+ monaco 式引擎自渲染(canvas / WebGL / 富文本引擎同理)不消费 CSS 变量——要跟随主题走**翻译桥**:订阅主题变更 → 翻译成引擎自己的 theme API。先例:`src/services/theme-sync.ts`(住在 **editor 插件自己的仓** `Encaron/linkdesk-plugin-editor`——起发货插件源码不在壳仓):
492
+
493
+ ```ts
494
+ // 订阅主题变更(事件可能先于 mount → 顶层注册或 active 守卫,见 11.5)
495
+ const off = window.linkdesk.events.on("theme:changed", () => {
496
+ engine.updateTheme(translateTheme()); // 把你的 token → 引擎 theme 对象
497
+ });
498
+ ```
499
+
500
+ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开,不落死边界**——未来可能彻底适配主题。
501
+
502
+ ### 11.4 插件私有数据通道——自建设置界面 / 自管存档时选通道
503
+
504
+ 作者自建设置 UI / 自管存档(不走壳设置页声明)时,数据落地按语义选:
505
+
506
+ | 通道 | 适用 | 示例 |
507
+ |---|---|---|
508
+ | `window.linkdesk.pluginState`(**首选**) | 插件自管存档——集中缓存 + 文件持久化(正牌 API:`get/set/onChange(pluginId, key)`) | 游戏分数 / 关卡进度 / 高分榜 / 皮肤偏好 |
509
+ | `window.linkdesk.configuration.set(key)` 私有命名空间 | 跟设置语义走、可被其他插件/主题读、**要进壳设置页 UI**(声明 contributes.configuration 即进) | 插件参数(声明即 UI;不声明则纯私有键照写持久化) |
510
+ | `window.linkdesk.filesystem` | 大文件 / 二进制 / 跨插件共享 | 截图导出 / 存档文件 |
511
+ | `localStorage` | 补充——池内临时缓存(无跨机、无壳管理) | 会话内高频临时值 |
512
+
513
+ **铁律:不声明 `contributes.configuration` 的私有键不进壳设置页 UI**——`config.set` 对无 schema 键照写持久化(仅 enum 才过滤),作者要壳设置页就声明贡献、要自建界面就私有键直存,两不干扰。
514
+
515
+ ### 11.5 壳纪律转移清单——非 UI 写法的纪律按落点沉对应文档
516
+
517
+ | 纪律 | 落点规范 |
518
+ |---|---|
519
+ | 插件唯一入口 `window.linkdesk.*`,**禁止 import @src/core(含 @src 任何子路径)** | `01-插件API契约.md` |
520
+ | 配置**订阅不读一次**(linkdesk.configuration 事件驱动) | 本文件 §3 |
521
+ | linkdesk.events 订阅**时序**——事件可能先于 mount(IPC 缓冲)→ 顶层注册或 active 守卫 | `02-插件生命周期.md` |
522
+ | **不写死其他插件 ID**(差异性行为走 plugin.json 声明字段,Registry 模式消费) | `03-插件contributes规范.md` |
523
+ | 配置键**必给 default** | `06-plugin.json规范.md` |
524
+ | **只用文档化 API 命名空间**(禁 linkdesk.xxx 未文档化随手挂) | `01-插件API契约.md` |
525
+ | 控件统一走 `@linkdesk/ui`(54c 起内置控件从 npm 包 import,禁止 `@src/components/shared/*`) | 本文件 §速查 |
526
+
527
+ ---
528
+
529
+ ## 速查
530
+
531
+ | 你要做的 | 核心设施 | 引入方式 |
532
+ |---|---|---|
533
+ | 右键菜单 | `<ContextMenu>`(open-string menuId) | `@linkdesk/ui`(ContextMenu)+ `plugin.json contributes.menus` 声明(或 `window.linkdesk.menu.registerItems`,见 §1) |
534
+ | 浮层/弹窗 | `createPortal` | `react-dom`(渲染到 `document.body`,见 §2) |
535
+ | 持久化 | `window.linkdesk.configuration.get/set/onChange` | 插件通信铁律——只走 window.linkdesk.*(见 §3) |
536
+ | 系统选择器 | `window.linkdesk.quickPick.show` | 池内 QuickPickHost 统一渲染(见 §9) |
537
+ | 通知 | `window.linkdesk.notifications.show` | 池内**铃铛宽通知面板**统一渲染(见 §9;语义见 `01-插件API契约.md` §3.2) |
538
+ | 确认/提示/文件选择 | `window.linkdesk.dialog.confirm/alert/open/openFile` | 池内 DialogHost 统一渲染(见 §9) |
539
+ | 富内容确认框 | `window.linkdesk.dialog.confirmContent({ pluginId, viewId, payload })` | 池内 DialogHost 渲染壳,**内容 = 插件自绘视图**(见 §9) |
540
+ | 快捷键(非文本键) | `plugin.json contributes.keybindings` | —(文本键写这里 = 吞全池,见 §4.1) |
541
+ | 快捷键(文本键/焦点绑定键) | 容器 `onKeyDown` + `tabIndex` | 池侧自处理,见 §4.2(禁止 document/window keydown) |
542
+ | 颜色 | CSS 变量 | `var(--xxx)`,列表见 `src/index.css` |
543
+ | 字号 | CSS 变量 | `var(--font-size-*)` + `--ui-scale`,禁止裸 px(#180 门禁,见 §10) |
544
+ | 六域 token 总览 | 见 §11.1 矩阵 | 颜色/表面/圆角/玻璃/字号/字体族——`var(--*)` 自动跟随主题+玻璃+缩放;完整清单 `src/index.css` |
545
+ | UI 纪律门禁 | `linkdesk-plugin-sdk lint` | 15 项全 WARN 永不 fail;知情绕行 = 标准 eslint-disable 声明(见 §11.2) |
546
+ | 文字 | `t()` | `useTranslation()` from `react-i18next` |
547
+ | 侧栏列表选中 | `onMouseDown`(非 `onClick`) | 对标 VS Code Explorer——防止快速点击跨元素丢事件 |
548
+
549
+ **写插件时用这些设施,别手写。写了以后也得拆——不如从第一天就归一。**