@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,800 @@
1
+ # 03 — 插件 contributes 规范
2
+
3
+ > 2026-07-24 · 2026-08-21 全量重写 · **2026-09-06 与实现对齐核对**(contributes 面无目录/分发语义,逐段核零塌平残留,原样保留)。**plugin.json `contributes` 字段——插件声明"我能做什么"。** 对标 VS Code `package.json` contributes。壳自动接线——不改任何核心代码。
4
+ > 真相源:`src/pluginLoader/contributions.ts`(parseContributions——壳侧 13 个消费点)+ `electron/plugins/plugin-manifest-loader.ts`(主进程 2 个消费点)+ `public/schemas/plugin.schema.json`(IDE 校验)。
5
+
6
+ ---
7
+
8
+ ## 一、核心原则
9
+
10
+ **插件声明 → 壳自动接线。** 你声明 `contributes.configuration`,Settings Editor 自动多一个分组。你声明 `contributes.commands`,Ctrl+Shift+P 自动多一项。
11
+
12
+ **不让壳知道你的插件是干什么的。** 壳只知道"有插件注册了这些命令/菜单/快捷键/配置项",不知道"这是 CAD 插件还是地图插件"。
13
+
14
+ ---
15
+
16
+ ## 二、全部贡献点
17
+
18
+ > 消费端分两处:**壳侧**(`parseContributions`,插件代码跑的地方)与**主进程**(`plugin-manifest-loader`,启动扫盘 + 装卸重扫三表)。
19
+
20
+ ### 壳侧消费(14 个)
21
+
22
+ | 贡献点 | 状态 | 说明 | 壳消费方 |
23
+ |------|:--:|------|------|
24
+ | `commands` | ✅ | 注册命令 → 命令面板/右键菜单/快捷键 | CommandRegistry |
25
+ | `menus` | ✅ | 注册菜单项 → 右键菜单/齿轮菜单/菜单栏 | MenuRegistry |
26
+ | `keybindings` | ✅ | 注册快捷键 | KeybindingRegistry |
27
+ | `configuration` | ✅ | 注册设置项 → Settings Editor 自动渲染 | ConfigurationRegistry |
28
+ | `configurationDefaults` | ✅ | 弱默认值——用户手动设置优先 | ConfigurationRegistry |
29
+ | `themes` | ✅ | 注册主题 → 主题浏览器/外观 | ThemeRegistry(数据异步加载) |
30
+ | `iconThemes` | ✅ | 注册图标主题 → 用户切换图标集 | IconRegistry |
31
+ | `icons` | ✅ | 共享图标——插件 A 贡献、插件 B 引用 | IconRegistry |
32
+ | `languages` | ✅ | 注册 UI 语言包 | LanguageRegistry(数据异步加载) |
33
+ | `titleBar` | ✅ | 顶栏左右槽位按钮 | MenuRegistry |
34
+ | `viewsContainers` | ✅ | 声明侧栏/面板容器 | ViewContainerService |
35
+ | `views` | ✅ | 往容器注册视图——任何插件可往任意容器注册 | ViewContainerService |
36
+ | `floatingPanel` | ✅ | 声明某视图可在壳内悬浮面板显示(类型 B)——viewId 引用已注册视图;未声明则无「在悬浮面板中打开」右键(I8-3) | 声明寻址 → FloatingPanelService |
37
+ | `i18n` | ✅ | 插件自带翻译文件 | i18nResources(i18next 命名空间) |
38
+
39
+ ### 主进程消费(2 个)
40
+
41
+ | 贡献点 | 状态 | 说明 | 消费方 |
42
+ |------|:--:|------|------|
43
+ | `langDefs` | ✅ | **编程语言声明**(ID/扩展名/语法高亮/LSP)——主进程唯一写入方 | 主进程 LangDefRegistry(壳侧注册已删) |
44
+ | `fileAssociations` | ✅ | 文件扩展名 → 插件路由 | 主进程 FileAssociationService(壳侧注册已删) |
45
+
46
+ ### 顶层字段(不是 contributes,但常被误认)
47
+
48
+ | 字段 | 说明 |
49
+ |------|------|
50
+ | `statusBar` | **状态栏条目——顶层字段**,不是 contributes.statusBar(对标 VS Code `contributes.views` 之外的状态栏扩展点) |
51
+ | `tabBehavior` | 标签页行为(singleton/isFallback/confirmOnClose/identityField)——见 `02 §六` |
52
+ | `appearsIn` | 插件 UI 出现位置(iconBar/sidePanel/tabBar/statusBar)——替代旧 iconLocation/viewRole |
53
+ | `requires` | 插件级激活顺序依赖(string 数组)——见 `02 §四` |
54
+ | `factoryRole` | 系统插槽(settings=设置页 / marketplace=插件市场)——**填 = 形态二(替换/进槽位切换);不填 = 形态一(普通视图插件并存)**,详见 `06 §factoryRole 字段详解`。**同角色多插件并存已落地**:同角色多插件合法并存(一对多),默认 = 首注册稳定序(core:true 无行为特权,不抢默认),设置页角色分组 + 切换按钮 + 图标激活套占槽,活动套持久化重启保持 |
55
+ | `pluginRole` | 加载策略(view/data)——不填自动推导,见 `02 §二.1` |
56
+
57
+ ### ❌ 不存在 / 已删的假点
58
+
59
+ | 贡献点 | 现状 |
60
+ |------|------|
61
+ | `cards` | **已删**——CardRegistry 已整删,卡片工作台是插件(硬约束 3)。**写了不生效** |
62
+ | `protocols` | **假点**——`contributes.protocols` 无消费方。协议解析走 `serial.onData` 数据管道 + `ProtocolParser`(白名单工具),不是 contributes 声明 |
63
+ | `aiFunctions` | 从未实现 |
64
+
65
+ ---
66
+
67
+ ## 三、各贡献点详述
68
+
69
+ ### 3.1 `contributes.commands`——命令
70
+
71
+ ```json
72
+ {
73
+ "contributes": {
74
+ "commands": [
75
+ {
76
+ "id": "cad.importDxf",
77
+ "title": "导入 DXF…",
78
+ "category": "CAD",
79
+ "when": "activeEditor == 'cad'"
80
+ }
81
+ ]
82
+ }
83
+ }
84
+ ```
85
+
86
+ | 字段 | 必需 | 说明 |
87
+ |------|:--:|------|
88
+ | `id` | ✅ | 命令 ID。命名:`<pluginId>.<action>`,如 `terminal.copy` |
89
+ | `title` | ✅ | 显示名称(i18n key——中文原文) |
90
+ | `category` | ❌ | 命令面板分组——"CAD" / "终端" / "文件" |
91
+ | `when` | ❌ | context key when 条件。不加 `when` = 任何上下文可见 |
92
+
93
+ **声明即注册元数据(placeholder):** `contributes.commands` 只注册命令元数据(id/title/category/when),**真实 handler 在池侧注册**(池侧 `_poolCommands` 优先)。不注册 handler 的命令被调用 → no-op(诊断 warn)。
94
+
95
+ ```typescript
96
+ // 池侧注册真实 handler(组件 mount 时)
97
+ useEffect(() => {
98
+ window.linkdesk.commands.registerCommand("cad.importDxf", async () => {
99
+ const paths = await window.linkdesk.dialog.openFile({ filters: [{ name: "DXF 文件", extensions: ["dxf"] }] });
100
+ // ...
101
+ });
102
+ }, []);
103
+ ```
104
+
105
+ ### 3.2 `contributes.menus`——菜单项
106
+
107
+ ```json
108
+ {
109
+ "contributes": {
110
+ "menus": {
111
+ "editorContext": [
112
+ "cad.importDxf",
113
+ { "command": "cad.exportPdf", "when": "activeEditor == 'cad'", "group": "edit" }
114
+ ],
115
+ "tabContext": [
116
+ { "command": "cad.closeAll", "when": "activeEditor == 'cad'" }
117
+ ]
118
+ }
119
+ }
120
+ }
121
+ ```
122
+
123
+ **MenuId 是开放 string(`MenuRegistry` `type MenuId = string`)——插件声明任意字符串即契约,无需壳加代码。** 壳内置注册点(MENU_SLOTS 常量表,14 槽):
124
+
125
+ | MenuId | 场景 |
126
+ |------|------|
127
+ | `commandPalette` | Ctrl+Shift+P 命令面板 |
128
+ | `tabContext` | 标签栏标签右键 |
129
+ | `panelViewContext` | 面板标签栏右键(位置/对齐子菜单 + 视图显隐列表) |
130
+ | `editorContext` | 标签页主内容区右键 |
131
+ | `extensionGear` | 底部齿轮菜单(设置/命令面板/主题选择器) |
132
+ | `marketplaceItemGear` | 插件市场条目齿轮(启用/禁用/卸载) |
133
+ | `menuBar` | ☰ 汉堡菜单栏 |
134
+ | `panel` | 菜单栏「面板」组归并(壳招牌已删——插件 `group:"panel"` 项仍归并入菜单栏独立成组) |
135
+ | `fileContext` | 文件树右键 |
136
+ | `cardContext` | 卡片右键 |
137
+ | `quickSendContext` | 快捷发送药丸右键 |
138
+ | `iconBar` | 图标栏右键 |
139
+ | `settingItemGear` | 设置项齿轮(Settings Editor 行 hover) |
140
+ | `viewTitleContext` | 侧栏视图 title 右键(折叠/重置位置/视图同组) |
141
+
142
+ **菜单项字段:**
143
+
144
+ | 字段 | 必需 | 说明 |
145
+ |------|:--:|------|
146
+ | `command` | ✅ | 命令 ID——有 `children` 时可为空字符串(父菜单项不执行命令,展开子菜单) |
147
+ | `label` | ❌ | 显示标签——有值时覆盖命令标题 `getCommand(id).title`;父菜单项(无 `command`)必填 |
148
+ | `group` | ❌ | 分组——同组内聚在一起,组间有分隔线。如 `"navigation"` / `"edit"` / `"delete"` |
149
+ | `when` | ❌ | context key when 条件 |
150
+ | `order` | ❌ | 排序权重——同组内越小越靠前 |
151
+ | `children` | ❌ | 嵌套子菜单——**任意深度递归**(对标 VS Code `SubmenuAction`);子项同构(`children` 内可再嵌 `children`) |
152
+
153
+ **简写:** 只填命令 ID 的字符串 = `{ "command": "<id>" }`
154
+
155
+ **嵌套子菜单示例(任意深度):**
156
+ ```json
157
+ {
158
+ "contributes": {
159
+ "menus": {
160
+ "menuBar": [
161
+ { "command": "", "label": "查看", "group": "view", "children": [
162
+ { "command": "cad.importDxf", "group": "view" },
163
+ { "command": "", "label": "界面", "group": "view", "children": [
164
+ { "command": "cad.togglePanel", "label": "面板", "group": "view" }
165
+ ] }
166
+ ] }
167
+ ]
168
+ }
169
+ }
170
+ }
171
+ ```
172
+
173
+ ### 3.3 `contributes.keybindings`——快捷键
174
+
175
+ ```json
176
+ {
177
+ "contributes": {
178
+ "keybindings": [
179
+ { "command": "cad.importDxf", "key": "ctrl+shift+i", "when": "activeEditor == 'cad'" },
180
+ { "command": "cad.exportPdf", "key": "ctrl+shift+e", "when": "activeEditor == 'cad'" }
181
+ ]
182
+ }
183
+ }
184
+ ```
185
+
186
+ | 字段 | 必需 | 说明 |
187
+ |------|:--:|------|
188
+ | `command` | ✅ | 命令 ID |
189
+ | `key` | ✅ | 键序列——`"ctrl+k"` / `"ctrl+shift+p"` / `"ctrl+k ctrl+o"`(Chord) |
190
+ | `when` | ❌ | context key when 条件 |
191
+
192
+ **⚠️ 轨道选择(`05 §4`):** 只把**非文本键**写进 `contributes.keybindings`。`ctrl+c` / `ctrl+v` / `f2` 等文本编辑键写这里 = 主进程 `before-input-event` 无条件吞全池输入框。文本键/焦点绑定键正解 = 池侧容器 `onKeyDown`(DOM 焦点天然分区)。
193
+
194
+ ### 3.4 `contributes.configuration`——设置项
195
+
196
+ ```json
197
+ {
198
+ "contributes": {
199
+ "configuration": {
200
+ "title": "CAD 查看器",
201
+ "properties": {
202
+ "cad.gridSize": {
203
+ "type": "number",
204
+ "default": 10,
205
+ "description": "网格大小 (mm)"
206
+ },
207
+ "cad.units": {
208
+ "type": "string",
209
+ "default": "mm",
210
+ "enum": ["mm", "cm", "inch"],
211
+ "enumDescriptions": ["毫米", "厘米", "英寸"],
212
+ "description": "单位"
213
+ },
214
+ "cad.autoSave": {
215
+ "type": "boolean",
216
+ "default": true,
217
+ "description": "自动保存"
218
+ },
219
+ "cad.showGrid": {
220
+ "type": "object",
221
+ "default": { "enabled": true, "color": "#555" },
222
+ "description": "网格外观(对象)"
223
+ },
224
+ "cad.exportFormats": {
225
+ "type": "array",
226
+ "default": ["dxf", "stl"],
227
+ "description": "可导出的格式列表"
228
+ }
229
+ }
230
+ }
231
+ }
232
+ }
233
+ ```
234
+
235
+ **支持的类型(schema 全量):** `"string"` | `"number"` | `"boolean"` | `"object"` | `"array"`
236
+
237
+ > **注意:** 没有 `"integer"`——用 `"number"`。`minimum`/`maximum` 运行时类型支持,但 schema 暂未声明(IDE 会提示)——高级用法可写,加载不校验。
238
+
239
+ **字段:**
240
+
241
+ | 字段 | 必需 | 说明 |
242
+ |------|:--:|------|
243
+ | `type` | ✅ | string/number/boolean/object/array |
244
+ | `default` | ✅ | 默认值 |
245
+ | `description` | ✅ | 说明——Settings Editor 渲染为提示 |
246
+ | `enum` | ❌ | 下拉选项(string 类型时可选) |
247
+ | `enumDescriptions` | ❌ | 选项说明——和 enum 一一对应 |
248
+ | `uiHint` | ❌ | 渲染提示——SettingsView 按 hint 选择控件(已知值 `"color"`/`"fontFamily"`/`"fontSize"`/`"file"`/`"directory"`/`"slider"`/`"segmented"`/`"image"` 等,开放 string——未知 hint 降级回 type 默认渲染)。`"segmented"` = 分段单选(ghost 双轨制,配合 `enum` + `enumDescriptions` 声明,短标签 = enumDescription `—` 前段、tooltip = 全句) |
249
+ | `group` | ❌ | **组内二级标题**——同 `group` 值的 key 在设置页归到子标题下渲染;无 `group` 的 key 保持平铺。声明中文节名即显示;节名标题走 i18n(插件 `contributes.i18n` 提供翻译)。零壳改动——壳机制对插件键同样生效。 |
250
+
251
+ **安装后效果:** Settings Editor 左侧导航树自动出现 "CAD 查看器" 分组 → 右侧自动渲染表单——不需要手写设置界面。
252
+
253
+ **Key 命名规则:** `<pluginId>.<property>`,如 `cad.gridSize`、`terminal.baudRate`
254
+
255
+ **插件读设置(插件通信铁律——只走 `window.linkdesk.configuration`):**
256
+ ```typescript
257
+ const gridSize = await window.linkdesk.configuration.get<number>("cad.gridSize");
258
+ // 或订阅变化
259
+ useEffect(() => {
260
+ return window.linkdesk.configuration.onChange<number>("cad.gridSize", (val) => {
261
+ // 用户在 Settings Editor 改值 → 自动通知
262
+ });
263
+ }, []);
264
+ ```
265
+
266
+ ### 3.5 `contributes.configurationDefaults`——弱默认值
267
+
268
+ ```json
269
+ {
270
+ "contributes": {
271
+ "configurationDefaults": {
272
+ "terminal.baudRate": 115200,
273
+ "terminal.encoding": "utf-8"
274
+ }
275
+ }
276
+ }
277
+ ```
278
+
279
+ 和 `configuration` 的区别:`configuration` 定义了**自己的**设置项。`configurationDefaults` 给**别人的**设置项提供建议值。用户手动设置优先——弱默认只在用户从未设置过该 key 时生效。
280
+
281
+ ### 3.6 `contributes.themes`——主题
282
+
283
+ ```json
284
+ {
285
+ "contributes": {
286
+ "themes": [
287
+ { "id": "my-theme-dark", "label": "My Theme Dark", "uiTheme": "dark", "path": "themes/my-dark.json" }
288
+ ]
289
+ }
290
+ }
291
+ ```
292
+
293
+ | 字段 | 必需 | 说明 |
294
+ |------|:--:|------|
295
+ | `id` | ✅ | 主题 ID |
296
+ | `label` | ✅ | 显示名称 |
297
+ | `uiTheme` | ✅ | `"dark"` \| `"light"` \| `"highContrast"` |
298
+ | `path` | ✅ | 主题定义 JSON 文件路径(`appearance` + `colorways[]`)——**相对插件目录** |
299
+
300
+ 声明是 metadata-only;主题颜色数据在加载时异步 fetch。旧格式顶层 `themes` 字段自动归一化(见 `02 §二.1`)。
301
+
302
+ > **🔥 配方 JSON 契约(已随 plugin-sdk 收编)**:`path` 指向的配方文件按 `theme.schema.json` 校验——repo 内 = `public/schemas/theme.schema.json`(`npm run check` 链 `check-theme-schema.mjs`,格式错当场红灯 exit 1 不静默);npm 作者 = 随 `@linkdesk/plugin-sdk` 分发的 `schemas/theme.schema.json` + SDK `validateThemeJson`(同一 schema 文件,规则永不漂移)。运行时 `parseThemeRecipe` toast 是第二道防线。主题文件建议首行 `"$schema"` 引 schema 拿编辑器 IntelliSense(npm 路径见 [11-主题制作](11-主题制作.md) §②)。
303
+
304
+ ### 3.7 `contributes.iconThemes`——图标主题
305
+
306
+ ```json
307
+ {
308
+ "contributes": {
309
+ "iconThemes": [
310
+ { "id": "my-icons", "label": "My Icons", "path": "icons/icon-theme.json" }
311
+ ]
312
+ }
313
+ }
314
+ ```
315
+
316
+ 对标 VS Code `productIconThemes`。字段同 themes(id/label/path)。**mappings JSON 双形态(④ 拍板)**——每条目二选一:
317
+
318
+ ```json
319
+ {
320
+ "files": {
321
+ "readme.md": { "class": "codicon codicon-markdown" },
322
+ "main.rs": { "class": "myfont myfont-rust", "color": "#dea584" },
323
+ "logo.svg": { "imagePath": "icons/logo.svg" }
324
+ },
325
+ "extensions": { ".ts": { "class": "codicon codicon-typescript" } },
326
+ "folders": { "src": { "class": "codicon codicon-folder" } },
327
+ "foldersExpanded": { "src": { "class": "codicon codicon-folder-opened" } }
328
+ }
329
+ ```
330
+
331
+ | 形态 | 字段 | 渲染 | 说明 |
332
+ |------|------|------|------|
333
+ | **字体 glyph** | `class`(必)+ `color?`(可选) | `<span>` | 单色/带色字体 glyph(seti/material 即此类,每图标一色);自定义字体走 `@font-face`(见下方 `font` 段) |
334
+ | **图像资产** | `imagePath` | `<img>` | 任意多色(拟物化/贴图);相对路径 → 壳加载时解析为 `linkdesk://{pluginId}/{path}` 绝对 URL(消费方零解析负担) |
335
+
336
+ 同一主题可混用两形态。**选择器 = 设置 `app.iconTheme`**(壳声明,默认 `"default"` = 内置 codicon 保底,零图标主题插件也成立;枚举 = 已登记图标主题 + default,装/卸动态刷新)。切换经事件 `iconTheme:changed` 广播(载荷 + 契约见 `01-插件API契约.md` §3.2 壳广播事件表)——**需要自定义文件图标视觉的插件手动订阅应用**。
337
+
338
+ **可选顶层 `font` 段(自定义图标字体)**——`class` 引用自定义字体 glyph 时声明;壳生成 @font-face 广播进池 + 注入 glyph 类 CSS,作者零 @font-face 负担:
339
+
340
+ ```json
341
+ {
342
+ "font": {
343
+ "path": "icons/fonts/my-icons.woff2",
344
+ "family": "my-icons",
345
+ "glyphs": "icons/my-icons.css"
346
+ },
347
+ "files": { "main.rs": { "class": "my-icons my-icons-rust", "color": "#dea584" } }
348
+ }
349
+ ```
350
+
351
+ | `font` 字段 | 类型 | 说明 |
352
+ |------|------|------|
353
+ | `path` | string(必) | 字体资产相对路径(或绝对 URL)——壳解析 `linkdesk://` + 生成 `@font-face` |
354
+ | `family` | string(必) | 字体族名——glyph CSS 里 `font-family` 写它 |
355
+ | `glyphs` | string(选) | glyph 类 CSS 文件相对路径(`@font-face` **不要**写在里面——壳已生成;只写 `.my-icons-x::before{content:"…"}`) |
356
+
357
+ 无 `font` 段 → 零自定义字体(codicon 保底 / 纯图像资产主题)。字体注入对消费方透明(preload 机械层处理),无需手动订阅。
358
+
359
+ **顶层默认图标五键(对齐 VS Code iconTheme 顶层键)**——匹配表(files/extensions/folders/foldersExpanded)未命中时用主题默认而非 codicon 保底;条目同双形态:
360
+
361
+ ```json
362
+ {
363
+ "file": { "imagePath": "icons/material/file.svg" },
364
+ "folder": { "imagePath": "icons/material/folder.svg" },
365
+ "folderExpanded": { "imagePath": "icons/material/folder-open.svg" },
366
+ "rootFolder": { "imagePath": "icons/material/folder-root.svg" },
367
+ "rootFolderExpanded": { "imagePath": "icons/material/folder-root-open.svg" }
368
+ }
369
+ ```
370
+
371
+ > **🔥 mappings JSON 契约(立——icon-theme.schema.json 重写对齐引擎 normalizeIconThemeMappings)**:`path` 指向的 mappings 文件按 `icon-theme.schema.json` 校验——repo 内 = `public/schemas/icon-theme.schema.json`(`npm run check` 链 `check-theme-schema.mjs` 兼扫 `contributes.iconThemes`);npm 作者 = 随 `@linkdesk/plugin-sdk` 分发的 `schemas/icon-theme.schema.json` + SDK `validateIconThemeJson`(同一 schema 文件,规则永不漂移)。运行时解析失败 warn/toast 是第二道防线。文件建议首行 `"$schema"` 引 schema 拿编辑器 IntelliSense。
372
+
373
+ ### 3.8 `contributes.icons`——共享图标
374
+
375
+ ```json
376
+ {
377
+ "contributes": {
378
+ "icons": {
379
+ "stm32-chip": {
380
+ "description": "STM32 芯片图标",
381
+ "default": { "fontPath": "icons.woff", "fontCharacter": "\\e001" }
382
+ }
383
+ }
384
+ }
385
+ }
386
+ ```
387
+
388
+ 插件 A 贡献、插件 B 引用(`"icon": "stm32-chip"` + `"iconSource": "shared"`)。
389
+
390
+ ### 3.9 `contributes.languages`——UI 语言包 + `contributes.i18n`——插件自带翻译
391
+
392
+ **两条翻译管道,别混:**
393
+
394
+ | 管道 | 声明位置 | 作用 | 例子 |
395
+ |------|------|------|------|
396
+ | **UI 语言包** | `contributes.languages` | 换整个界面的语言(全局) | 中文/English/日本語 |
397
+ | **插件自带翻译** | `contributes.i18n` | 本插件文字的多语言翻译(按语言代码声明文件) | `{ "en": "i18n/en.json" }` |
398
+
399
+ ```json
400
+ {
401
+ "contributes": {
402
+ "languages": [
403
+ { "id": "zh", "label": "中文", "path": "lang/zh.json" },
404
+ { "id": "en", "label": "English", "path": "lang/en.json" }
405
+ ],
406
+ "i18n": { "en": "i18n/en.json" }
407
+ }
408
+ }
409
+ ```
410
+
411
+ - `contributes.i18n` 的 key = 语言代码,value = JSON 翻译文件路径(key = 中文原文,value = 译文)。**不需要 zh.json**——中文 key 自带兜底。
412
+ - 翻译文件经 `fetchPluginDataFile` 加载(绕开 Vite glob 缓存——新装插件目录的 JSON 实时发现)。
413
+ - 插件文字铁律:**所有 UI 文字走 `t()`**,i18n key = 中文原文(`05 §6`)。
414
+
415
+ ### 3.10 `contributes.titleBar`——顶栏按钮
416
+
417
+ ```json
418
+ {
419
+ "contributes": {
420
+ "titleBar": {
421
+ "right": [
422
+ { "command": "myPlugin.openPanel", "icon": "codicon-graph-line", "when": "myContext" },
423
+ { "command": "myPlugin.runTask", "label": "运行任务" },
424
+ { "command": "myPlugin.showStatus", "label": "$myPluginStatus", "when": "myStatusVisible" }
425
+ ]
426
+ }
427
+ }
428
+ }
429
+ ```
430
+
431
+ | 字段 | 必需 | 说明 |
432
+ |------|:--:|------|
433
+ | `command` | ✅ | 点击执行的命令 ID |
434
+ | `icon` | ❌ | codicon 图标名或图片路径 |
435
+ | `label` | ❌ | 按钮文字——**填了就不渲染 icon**(有 label 优先)。全文字按钮,宽度随文字自适应 |
436
+ | `when` | ❌ | context key when 条件——不满足时按钮隐藏 |
437
+
438
+ 槽位:`left`(标题栏左侧)/ `right`(右侧)。
439
+
440
+ **`label` 的两种形态**——按**字面前缀**区分,不是「猜这个名字像不像一个键」:
441
+
442
+ | 写法 | 含义 |
443
+ |:--|:--|
444
+ | `"label": "运行任务"` | **静态文字**。当 i18n key 走 `t()`(本仓 i18n key = 中文原文),译文在插件的 i18n 文件里给(§3.9) |
445
+ | `"label": "$myPluginStatus"` | **动态文字**。`$` 之后是 context key 名——壳侧取该键的**当前值**当文字,按键值随状态切换(对标 VS Code 的 `${...}` 思路) |
446
+
447
+ ⚠️ **动态文字的键由你自己用 `linkdesk.contextKey.set("myPluginStatus", "…")` 维护**;键不存在时按钮显示字面 `$myPluginStatus`(**故意让它显眼**——静默空白最难查)。
448
+
449
+ ⚠️ **`$` 前缀是必须的**:本仓 i18n key 并非恒为中文(英文界面下的 `EN`/`JSON`/`workspace`/`settings` 这类键就是纯 ASCII),所以「这个名字是不是一个活着的 context key」无法可靠判定——不加前缀时,别的插件注册一个同名 context key 就会把你的按钮文字**静默顶掉**。
450
+
451
+ ⚠️ **动态文字的值也是 i18n key**:`set` 进去的应是中文原文(如 `"运行中"`),壳侧仍会过一次 `t()` ⇒ 英文界面跟着变。直接塞成品译文会绕过翻译层。
452
+
453
+ ### 3.11 `contributes.viewsContainers` + `contributes.views`——视图容器
454
+
455
+ > **完整 API 文档:`08-ViewContainer-视图容器API.md`**(含 titleActions 声明制、panel.reveal、运行时元数据更新)。这里只给字段总表。
456
+
457
+ **viewsContainers——声明侧栏/面板/主区频道:**
458
+
459
+ ```json
460
+ {
461
+ "contributes": {
462
+ "viewsContainers": {
463
+ "explorer": {
464
+ "title": "资源管理器",
465
+ "location": "sidebar",
466
+ "hideIfEmpty": false
467
+ }
468
+ }
469
+ }
470
+ }
471
+ ```
472
+
473
+ | 字段 | 必需 | 说明 |
474
+ |------|:--:|------|
475
+ | `title` | ✅ | 侧栏 header 显示的名称 |
476
+ | `location` | ❌ | `"sidebar"` \| `"panel"` \| `"auxiliarybar"` \| `"main"`。默认 `"sidebar"`(sidebar=左/auxiliarybar=右/panel=底部面板标签栏/main=主区标签页渲染面——仅活跃 factoryRole 插件(市场)经 `views."main"[]` 贡献,壳 ShellViewRenderer 解析 plugin-detail 类 tab 时消费;需配套 `viewsContainers."main"` 声明,见) |
477
+ | `hideIfEmpty` | ❌ | 无活跃 view 时自动隐藏容器 |
478
+ | `order` | ❌ | 同位置排序。小值靠前 |
479
+ | `icon` | ❌ | 覆盖插件自身图标 |
480
+ | `mergeHeaderWhenSingle` | ❌ | 容器内只有一个 view 时隐藏 view header——标题合并到容器 header |
481
+
482
+ **views——往容器注册内容:**
483
+
484
+ ```json
485
+ {
486
+ "contributes": {
487
+ "views": {
488
+ "explorer": [
489
+ { "id": "folders", "title": "", "render": "src/views/FoldersView.tsx", "order": 0 },
490
+ { "id": "search", "title": "搜索", "render": "src/views/SearchView.tsx", "order": 1 }
491
+ ]
492
+ }
493
+ }
494
+ }
495
+ ```
496
+
497
+ | 字段 | 必需 | 说明 |
498
+ |------|:--:|------|
499
+ | `id` | ✅ | View 唯一 ID |
500
+ | `render` | ✅ | 组件模块路径——**相对插件目录** |
501
+ | `title` | ❌ | SidebarSection 折叠头标题。空字符串 = 不渲染折叠头 |
502
+ | `role` | ❌ | `"toolbar"` \| `"section"`——toolbar 粘顶不被 section 覆盖 |
503
+ | `order` | ❌ | 容器内排序。小值在上 |
504
+ | `collapsed` | ❌ | 初始折叠 |
505
+ | `when` | ❌ | context key 条件——满足时才显示 |
506
+ | `canToggleVisibility` | ❌ | ✅ 已实现——用户可在面板切换器/侧栏「视图」子菜单切换可见性 |
507
+ | `canMoveView` | ❌ | ✅ 已实现——用户可拖放此 view 到其他容器 |
508
+ | `hideByDefault` | ❌ | ✅ 已实现——默认隐藏,用户需手动开启 |
509
+ | `singleViewPaneContainerTitle` | ❌ | 单 view 且容器 `mergeHeaderWhenSingle` 时替代容器 title |
510
+ | `titleDescription` | ❌ | 标题旁的副文字——如 `(5 files)` |
511
+ | `showActions` | ❌ | `"always"` \| `"whenExpanded"` \| `"default"`——动作区显隐时机 |
512
+ | `titleTooltip` | ❌ | 标题 hover tooltip——标题截断时显示完整文字 |
513
+ | `minHeight` | ❌ | 拖拽 resize 最小高度(px)。默认 100 |
514
+ | `titleActions` | ❌ | **视图动作区声明制**——见下方小节 |
515
+
516
+ **关键特性:任何插件** 都能往别人的容器注册 view:
517
+ ```json
518
+ // Git 插件——往 file-tree 的 explorer 容器注册 TIMELINE
519
+ { "contributes": { "views": { "explorer": [{ "id": "timeline", ... }] } } }
520
+ ```
521
+ 文件树插件零改动。
522
+
523
+ #### titleActions——视图 header 右侧动作区
524
+
525
+ **对标 VS Code 视图 header 右侧的 `[+][🔄][⊟]` / 终端 `[+][▾]`。** 三 widget 形态:
526
+
527
+ | 类型 | 形态 | 点击行为 |
528
+ |------|------|------|
529
+ | `icon` | 单图标按钮 | 执行 `command` |
530
+ | `dropdown` | 纯下拉(chevron) | 展开 `items` 列表,点条目执行对应 `command` |
531
+ | `split` | 主按钮 + 下拉复合 | 主按钮执行 `command`(默认动作),右侧 chevron 展开 `items` |
532
+
533
+ **widget 字段:** `id`(唯一)、`command`(点击执行的命令 ID)、`args`(可选——`executeCommand(command, args)` 单个位置参数透传)、`icon`(codicon 类名)、`title`(tooltip/aria-label)、`items`(dropdown/split 备选条目 `{ label, command, args }`)。**label/title 为 i18n key(中文原文)**。
534
+
535
+ ```json
536
+ {
537
+ "id": "demo-output",
538
+ "title": "输出",
539
+ "render": "src/views/DemoOutputView.tsx",
540
+ "order": 0,
541
+ "titleActions": [
542
+ {
543
+ "type": "split",
544
+ "id": "add-log",
545
+ "command": "panel-demo.addLog",
546
+ "icon": "codicon-add",
547
+ "title": "添加演示日志",
548
+ "args": { "level": "info" },
549
+ "items": [
550
+ { "label": "添加信息", "command": "panel-demo.addLog", "args": { "level": "info" } },
551
+ { "label": "添加警告", "command": "panel-demo.addLog", "args": { "level": "warn" } }
552
+ ]
553
+ },
554
+ { "type": "icon", "id": "clear-log", "command": "panel-demo.clearLog", "icon": "codicon-clear-all", "title": "清空输出" }
555
+ ]
556
+ }
557
+ ```
558
+
559
+ **命令注册(titleActions 的 command 执行真相源 = 池侧命令注册表):**
560
+ ```typescript
561
+ useEffect(() => {
562
+ window.linkdesk.commands.registerCommand("panel-demo.addLog", (args) => { addLine(args.level, args.text); });
563
+ }, []);
564
+ ```
565
+ > **`when: "false"` = 纯程序化命令不进命令面板**——titleActions 专属命令都这样声明,防止在 Ctrl+Shift+P 里刷屏。壳统一渲染器 `ViewTitleActions.tsx` 两处消费:面板标签栏(活动视图)+ 侧栏 section 折叠头。真实示例见 `08 §三`。
566
+
567
+ ### 3.12 `contributes.langDefs`——编程语言声明(主进程)
568
+
569
+ > **唯一写入方是主进程** `plugin-manifest-loader`(启动扫盘 + 装卸重扫)。壳侧 `parseContributions` 不消费。插件侧不用管加载——声明即可。
570
+
571
+ ```json
572
+ {
573
+ "contributes": {
574
+ "langDefs": [
575
+ {
576
+ "id": "python",
577
+ "extensions": [".py", ".pyi"],
578
+ "aliases": ["Python"],
579
+ "monarch": { "tokenizer": { } },
580
+ "lsp": {
581
+ "command": "node",
582
+ "args": ["node_modules/pyright/dist/pyright-langserver.js", "--stdio"]
583
+ }
584
+ }
585
+ ]
586
+ }
587
+ }
588
+ ```
589
+
590
+ | 字段 | 必需 | 说明 |
591
+ |------|:--:|------|
592
+ | `id` | ✅ | 语言 ID——如 cpp / python / rust |
593
+ | `extensions` | ✅ | 扩展名列表——如 `['.cpp', '.cxx', '.h']` |
594
+ | `aliases` | ❌ | 别名——如 `['C++', 'C']` |
595
+ | `monarch` | ❌ | Monarch tokenizer 定义(Monaco 内建语法高亮) |
596
+ | `lsp` | ❌ | LSP 语言服务器配置(command/args) |
597
+
598
+ > **`command` = 解释器或可执行名**(如 `node` / `clangd` / 绝对路径),不是脚本路径——脚本路径放 `args` 首位。
599
+ > **`args` 相对路径式参数以插件根目录为基准解析**(注册处一次绝对化)——上例 `node_modules/pyright/dist/pyright-langserver.js` → `<插件根>/node_modules/pyright/dist/pyright-langserver.js`;`--stdio` 等 flag 原样透传。**LSP 二进制随插件自带**:先在插件根 `npm install` 装依赖,SDK 打包时按 args 引用把对应 `node_modules` 包自动打进 `.linkdesk-plugin`(壳不再发货 LSP,python 插件即真示例)。
600
+
601
+ ### 3.13 `contributes.fileAssociations`——文件关联(主进程)
602
+
603
+ > **唯一写入方是主进程**。扩展名指给壳——由插件自己处理打开。
604
+
605
+ ```json
606
+ {
607
+ "contributes": {
608
+ "fileAssociations": [
609
+ { "extension": "dxf", "command": "cad.openFile", "displayName": "DXF 图纸" },
610
+ { "extension": "stl" },
611
+ { "extension": "step" }
612
+ ]
613
+ }
614
+ }
615
+ ```
616
+
617
+ | 字段 | 必需 | 说明 |
618
+ |------|:--:|------|
619
+ | `extension` | ✅ | 文件扩展名——**不含点**,如 dxf / stl / step |
620
+ | `command` | ❌ | 打开该扩展名文件时执行的命令 ID |
621
+ | `displayName` | ❌ | "打开方式…"选择器中的显示名 |
622
+
623
+ > **pluginId 由顶层 `pluginId` 字段声明**(起要求显式写;`contributes` 下**不写**)。不声明时退回「项目目录名」兜底——兜底路径保留只为兼容仓外存量第三方插件,**新插件一律显式声明**(目录名/仓库名是自由的,靠兜底 = 身份跟着名字漂,且五条后果全不报错)。规则见 [16-命名规范](16-命名规范.md)。
624
+
625
+ ### 3.14 `statusBar`——状态栏条目(顶层字段)
626
+
627
+ ```json
628
+ {
629
+ "statusBar": [
630
+ { "id": "units", "label": "mm", "align": "right" },
631
+ { "id": "zoom", "label": "100%", "align": "right", "onClick": "cad.zoomFit" },
632
+ { "id": "lock", "icon": "codicon-lock", "configurable": true }
633
+ ]
634
+ }
635
+ ```
636
+
637
+ | 字段 | 必需 | 说明 |
638
+ |------|:--:|------|
639
+ | `id` | ✅ | 唯一标识 |
640
+ | `label` | ❌ | 显示文字 |
641
+ | `icon` | ❌ | codicon 名称或 SVG 路径 |
642
+ | `align` | ❌ | `"left"` \| `"right"` |
643
+ | `onClick` | ❌ | 点击行为——命令名 |
644
+ | `configurable` | ❌ | 声明 `true` → 壳自动注册配置项 + 注入 visible prop。插件作者只写一行 JSON,零代码 |
645
+
646
+ **注意:** `statusBar` 是**顶层**字段,不是 `contributes.statusBar`。组件放 `statusBar.tsx` / `src/statusBar.tsx` / `src/components/statusBar.tsx`(运行时自动尝试三条路径)。
647
+
648
+ ### 3.15 `contributes.floatingPanel`——悬浮面板声明
649
+
650
+ > **壳内悬浮面板(类型 B)**——插件声明某视图可在悬浮面板显示。壳以声明寻址解析视图(pluginId/renderPath/title),零硬编码插件 ID(硬约束 10/11 同款消费)。
651
+
652
+ ```json
653
+ {
654
+ "contributes": {
655
+ "floatingPanel": { "viewId": "settings" }
656
+ }
657
+ }
658
+ ```
659
+
660
+ | 字段 | 必需 | 说明 |
661
+ |------|:--:|------|
662
+ | `viewId` | ✅ | **contributes.views 中已注册的视图 ID**——声明寻址解析出插件/renderPath/title |
663
+
664
+ **声明即消费,四件事自动出现:**
665
+
666
+ | 声明后效果 | 机制 |
667
+ |------|------|
668
+ | 标签页右键出现「在悬浮面板中打开」 | I8-3——未声明不出现(按声明过滤) |
669
+ | 打开后面板内三动作(在主窗口中打开 / 最大化 / 关闭) | I8-4/I8-9——「在主窗口中打开」落点 = 当前活动 group 尾部(复用文件树打开落点规则) |
670
+ | `linkdesk.panel.revealFloating(viewId)` 可编程弹面板 | I8-2 面板身份开关键——无面板→开;同视图→关;他面板→替换 |
671
+ | 卸载声明插件 → 右键条目消失 + revealFloating no-op 不崩 | 声明随插件生命周期卸载 |
672
+
673
+ **首批声明者 = settings**(`core.openSettings` Ctrl+, 弹面板);**第二声明者验证载体 = `floating-panel-demo`** 测试插件(标签页型视图,端到端验证替换 + 右键回程 + 卸载 no-op)。
674
+
675
+ ---
676
+
677
+ ## 四、Context Key when 条件
678
+
679
+ 菜单项和命令的 `when` 字段用 ContextKeyService 表达式:
680
+
681
+ | 运算符 | 示例 | 含义 |
682
+ |------|------|------|
683
+ | 裸 key | `portOpen` | key 值为 truthy → true |
684
+ | `!` | `!portOpen` | 取反 |
685
+ | `&&` | `activeEditor == 'cad' && portOpen` | 逻辑与 |
686
+ | `\|\|` | `activeEditor == 'a' \|\| activeEditor == 'b'` | 逻辑或 |
687
+ | `==` | `activeEditor == 'cad'` | 等于 |
688
+ | `!=` | `editorCount != 0` | 不等于 |
689
+ | `in` | `activeEditor in ['cad', 'terminal']` | 集合成员 |
690
+ | `()` | `!(portOpen \|\| editorCount > 1)` | 分组 |
691
+
692
+ **可用的 Context Key(壳写入):**
693
+
694
+ | Key | 类型 | 写入者 |
695
+ |------|------|------|
696
+ | `activeEditor` | `string \| null` | 标签页切换时——当前聚焦标签页的 pluginId |
697
+ | `portOpen` | `boolean` | 串口开关时 |
698
+ | `portName` | `string \| null` | 串口开关时 |
699
+ | `editorCount` | `number` | 标签页增删时 |
700
+ | `editorHasSelection` | `boolean` | 编辑器有选中文本时(预留) |
701
+
702
+ ---
703
+
704
+ ## 五、完整 plugin.json 示例——CAD 插件(字段全对齐真实消费面)
705
+
706
+ ```json
707
+ {
708
+ "$schema": "plugin.schema.json",
709
+ "name": "CAD 查看器",
710
+ "version": "1.0.0",
711
+ "icon": "PencilRuler",
712
+ "iconSource": "lucide",
713
+ "description": "DWG/DXF/STL 文件查看器",
714
+ "author": "社区",
715
+ "entry": "src/index.tsx",
716
+ "appearsIn": { "iconBar": "top", "tabBar": true },
717
+ "tabBehavior": {
718
+ "singleton": true,
719
+ "confirmOnClose": "未保存的修改将丢失"
720
+ },
721
+ "requires": ["file-tree"],
722
+ "statusBar": [
723
+ { "id": "units", "label": "mm", "align": "right" }
724
+ ],
725
+ "contributes": {
726
+ "i18n": { "en": "i18n/en.json" },
727
+ "commands": [
728
+ { "id": "cad.importDxf", "title": "导入 DXF…", "category": "CAD" },
729
+ { "id": "cad.zoomFit", "title": "适应窗口", "category": "CAD", "when": "activeEditor == 'cad'" }
730
+ ],
731
+ "menus": {
732
+ "editorContext": [
733
+ { "command": "cad.importDxf", "group": "navigation" },
734
+ { "command": "cad.zoomFit", "group": "view" }
735
+ ],
736
+ "commandPalette": [
737
+ { "command": "cad.importDxf" },
738
+ { "command": "cad.zoomFit", "when": "activeEditor == 'cad'" }
739
+ ]
740
+ },
741
+ "keybindings": [
742
+ { "command": "cad.zoomFit", "key": "ctrl+0", "when": "activeEditor == 'cad'" }
743
+ ],
744
+ "configuration": {
745
+ "title": "CAD 查看器",
746
+ "properties": {
747
+ "cad.gridSize": { "type": "number", "default": 10, "description": "网格大小" },
748
+ "cad.units": { "type": "string", "default": "mm", "enum": ["mm", "cm", "inch"], "description": "单位" },
749
+ "cad.autoSave": { "type": "boolean", "default": true, "description": "自动保存" }
750
+ }
751
+ },
752
+ "viewsContainers": {
753
+ "cad": { "title": "CAD 查看器", "location": "sidebar" }
754
+ },
755
+ "views": {
756
+ "cad": [
757
+ { "id": "layers", "title": "图层", "render": "src/views/LayersView.tsx", "order": 0 }
758
+ ]
759
+ },
760
+ "fileAssociations": [
761
+ { "extension": "dxf", "command": "cad.openFile", "displayName": "DXF 图纸" },
762
+ { "extension": "dwg" },
763
+ { "extension": "stl" }
764
+ ]
765
+ }
766
+ }
767
+ ```
768
+
769
+ ---
770
+
771
+ ## 六、与 VS Code contributes 对照
772
+
773
+ | VS Code contributes | LinkDesk | 差异 |
774
+ |------|------|------|
775
+ | `commands` | ✅ | 同——元数据声明 + 池侧注册 handler |
776
+ | `menus` | ✅ | LinkDesk 多 `quickSendContext` / `cardContext` / `viewTitleContext` 等(MenuId 开放 string) |
777
+ | `keybindings` | ✅ | 同——但文本键走池侧 onKeyDown(`05 §4`) |
778
+ | `configuration` | ✅ | 同——类型含 object/array |
779
+ | `configurationDefaults` | ✅ | 同 |
780
+ | `themes` | ✅ | 同 |
781
+ | `productIconThemes` | ✅ `iconThemes` | 同 |
782
+ | `icons` | ✅ | 同(共享图标,iconSource:shared) |
783
+ | `languages`(编程语言) | ✅ `langDefs` | **主进程**消费——语法高亮/LSP |
784
+ | `languages`(翻译包) | ✅ `languages` | LinkDesk 的 `languages` = UI 语言包(i18n);VS Code 用 l10n 体系 |
785
+ | `views` / `viewsContainers` | ✅ | 同 + LinkDesk 多 `titleActions` 声明制 + 显隐/迁移/panel.reveal |
786
+ | `titleBar` | ✅ | 顶栏左右按钮 |
787
+ | `viewsWelcome` | ⏳ | 欢迎内容——未来 |
788
+ | `fileAssociations` | ✅ | **主进程**——VS Code 由操作系统管理文件关联,LinkDesk 内置 |
789
+ | `extensionDependencies` | ✅ `requires` | string 数组(`02 §四`) |
790
+ | ~~`activationEvents`~~ | ~~✅~~ | **已删除**(退役,2026-09-09)——加载模型简化:启动全量注册元数据,JS 由池按需加载(`02 §五`) |
791
+ | `snippets` / `problemMatchers` | ❌ 不在规划 | Monaco/LSP 插件自带 |
792
+ | `breakpoints` / `debuggers` | ❌ 不在规划 | 调试器——当前不需要 |
793
+
794
+ ---
795
+
796
+ > **← 上一份:** `02-插件生命周期.md`
797
+ > **→ 下一份:** `04-插件分发格式.md`
798
+ > **→ 相关:** `08-ViewContainer-视图容器API.md`(views 完整语义)
799
+ > **→ 真相源:** `src/pluginLoader/contributions.ts` / `public/schemas/plugin.schema.json`(contributes 形状);主题配方数据 = `public/schemas/theme.schema.json`、图标主题 mappings 数据 = `public/schemas/icon-theme.schema.json`(theme/icon-theme 同随 `@linkdesk/plugin-sdk` 分发)
800
+ > **全部文档索引:** `00-README.md`