@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
package/docs/zh/02-/346/217/222/344/273/266/347/224/237/345/221/275/345/221/250/346/234/237.md
ADDED
|
@@ -0,0 +1,348 @@
|
|
|
1
|
+
# 02 — 插件生命周期
|
|
2
|
+
|
|
3
|
+
> 2026-07-24 · 2026-08-21 全量重写 · **2026-09-06 与实现对齐核对**(塌平单根 + zip 分发装卸流)。**插件从存在到消失的完整状态机。**
|
|
4
|
+
> 基座已换代:早期的多进程模型(每插件一个独立渲染容器)→ **极简 Pool——1 BrowserWindow + 1 WebContentsView,所有插件组件渲染在同一渲染进程**。
|
|
5
|
+
> 加载/卸载语义由壳侧状态机 + 可逆注册 + 依赖编排定义(`src/pluginLoader/`)。第三方作者读这一页就够。
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 一、两条加载路径——repo 源码树(HMR)与安装态(bundle)
|
|
10
|
+
|
|
11
|
+
启动扫描与文件监听都能发现插件,**统一走 `loadPlugin(pluginId, reason)` 唯一入口**(E5 归一化——调用方不再自己判断"该走哪条路"):
|
|
12
|
+
|
|
13
|
+
| 路径 | 来源 | manifest 怎么读 | JS 入口怎么加载 |
|
|
14
|
+
|------|------|----------------|----------------|
|
|
15
|
+
| **repo 源码树**(dev) | `<repo>/plugins/<id>/`(塌平单根,`import.meta.glob` 展开) | Vite eager import | `loadPluginComponent` → Vite 构建 chunk(**HMR 即时生效**) |
|
|
16
|
+
| **安装态** | `{userData}/plugins/<id>/`(`.linkdesk-plugin` zip 解出,`plugins.readManifest`) | `JSON.parse` | 检测 `index.bundle.js` → 运行时动态 import(dev 经 `resolveUserDataBundles` 把 react 系指回,prod `linkdesk://{id}`)——**预构建产物:改包需重 build 重装,无 HMR** |
|
|
17
|
+
|
|
18
|
+
**`loadPlugin` 一条管线覆盖两路**:repo 走 Vite 模块,userData 走运行时 bundle。新增能力只需改 `loadPlugin` 一处。
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## 二、启动加载管线——`loadPlugin` 步骤明细
|
|
23
|
+
|
|
24
|
+
每次 `loadPlugin(pluginId, reason)` 按序执行(`reason` = `startup` \| `install` \| `reinstall` \| `enable`):
|
|
25
|
+
|
|
26
|
+
```
|
|
27
|
+
markLoadStarted(PENDING → LOADING)
|
|
28
|
+
↓ ① 读 manifest(glob eager import / 运行时 IPC)——失败 → markLoadFailed + toast
|
|
29
|
+
↓ ② minAppVersion 检查——versionGte 不满足 → markLoadFailed + toast
|
|
30
|
+
↓ ③ 依赖检查——环 → fail-loud;缺 → 挂起 PENDING(见 §四)
|
|
31
|
+
↓ ④ 元数据入缓存(卸载后仍可浏览详情)
|
|
32
|
+
↓ ⑤ 加载 JS 入口 + statusBar(glob = chunk;运行时 = 动态 import)
|
|
33
|
+
↓ ⑥ 注册视图——运行时/entryless 插件 registerViewPlugin(见 §二.2)
|
|
34
|
+
↓ ⑦ 解析 contributes → 分发各 Registry(normalizeManifest → parseContributions,见 §二.3)
|
|
35
|
+
↓ ⑧ themes / languages / i18n 数据文件异步加载(fetch)
|
|
36
|
+
↓ ⑨ 收尾:loadedPluginIds.add + markLoadSuccess(→ ACTIVE)+ 同步主题/语言枚举 + onDidInstall.fire
|
|
37
|
+
↓ ⑩ 扫描挂起队列——依赖就绪的插件补载(sweepPendingDependencies)
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
**🔥 硬约束 13 竞态守卫:** 两次 concurrent `loadPlugin` 调用 → 第二次返回第一次的进行中 Promise(`_loadingPromises` Map)。StrictMode 双挂载 / watcher 与启动扫描撞车都安全。
|
|
41
|
+
|
|
42
|
+
### 2.1 旧格式归一化 + 角色派生
|
|
43
|
+
|
|
44
|
+
- **`normalizeManifest`(纯函数,不 mutate 只读 manifest):** E3 时代的顶层 `themes` / `languages` / `file` 字段 → 自动折成 `contributes.themes` / `contributes.languages`。新插件直接写 `contributes`,不用管这层。
|
|
45
|
+
- **角色派生:** `pluginRole` 显式声明;未声明时自动推导——`!manifest.entry && 有 contributes` → `"data"`(纯数据插件:主题/语言包,无 React 组件,跳过组件加载)。`pluginRole: "data"` 的插件不加载 JS 入口。
|
|
46
|
+
|
|
47
|
+
### 2.2 entryless 插件——没有入口也能有视图
|
|
48
|
+
|
|
49
|
+
**`entry` 不是必须的。** 声明 `contributes.viewsContainers`(location 默认 sidebar)+ `contributes.views` 就够——组件由 `contributes.views[].render` 声明路径加载,`render` 是模块路径字符串,不需要 `index.tsx` 入口。
|
|
50
|
+
|
|
51
|
+
**图标栏缺口修复:** `!manifest.entry && hasSidebarContainers(manifest)` → 也进 viewRegistry(元数据-only 注册)——否则 entryless 插件声明 `appearsIn.iconBar` 被静默丢弃、图标栏不出图标。组件由 ViewContainerService 经 render 路径加载,注册表只作元数据/图标入口(component 为空,可选项)。
|
|
52
|
+
|
|
53
|
+
### 2.3 contributes → 各 Registry
|
|
54
|
+
|
|
55
|
+
`parseContributions(pluginId, contributes)` 按 key 逐项检测,分发给 12 个消费点(commands/menus/keybindings/configuration/configurationDefaults/themes/iconThemes/icons/languages/titleBar/viewsContainers/views/i18n)——**完整清单见 `03-插件contributes规范.md`**。不认识的 key 静默跳过——新增贡献点不改 loader 也能跑。
|
|
56
|
+
|
|
57
|
+
### 2.4 加载顺序(`initPluginLoader`)
|
|
58
|
+
|
|
59
|
+
1. 发现单源 `plugins:listAll`(主进程直扫 plugins/ 全子目录,dev/prod 同面)→ 全量条目(含打包/市场安装插件,glob 已退役)
|
|
60
|
+
2. 逐个 `loadPlugin("startup")`——**跳过已禁用**;全量注册 manifest/contributes,**零 JS import**(JS 由池按 URL 懒加载,见 §五)
|
|
61
|
+
3. 账本 reconcile(差集双向墓碑,清章置章永不整条删)
|
|
62
|
+
4. 错误汇总 → toast + 诊断日志(失败插件 + 原因落 pluginLoader 日志频道)
|
|
63
|
+
5. 清理僵尸缓存(status="installed" 但未真正加载的幽灵条目)
|
|
64
|
+
6. `.disabled/` 坟场孤儿 boot 清扫(跨重启坟场 = 同会话 undo toast 已失效的无主副本 → 真删 + 清幽灵 uninstalled 缓存)
|
|
65
|
+
|
|
66
|
+
### 2.5 文件监听(热插拔)
|
|
67
|
+
|
|
68
|
+
`startPluginWatcher` 每 2s 轮询 `listDirs`:
|
|
69
|
+
- **新目录出现** → `loadPlugin` 即时加载(repo 源码树走 Vite chunk;userData 走 install 发现)
|
|
70
|
+
- **已加载但目录被手动删除** → `unloadPlugin(id, "uninstall")` 自动移除注册
|
|
71
|
+
- 跳过条件(`shouldWatcherSkip`):状态机为 `failed` / `pendingReason` 有值——防止 2s 轮询反复重入炸膛(环 toast 刷屏回归教训)
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## 三、状态机——`LOADING → ACTIVE / FAILED / PENDING`,卸载 `UNLOADING → DISPOSED`
|
|
76
|
+
|
|
77
|
+
```
|
|
78
|
+
PENDING ──loadPlugin──▶ LOADING ──注册全量生效──▶ ACTIVE
|
|
79
|
+
▲ │ │ 卸载/禁用
|
|
80
|
+
│ ▼ 加载抛错 ▼
|
|
81
|
+
└────────── FAILED ◀──记录 failureReason UNLOADING
|
|
82
|
+
(重试回 LOADING) │ rollback 完成
|
|
83
|
+
▼
|
|
84
|
+
DISPOSED
|
|
85
|
+
(重装/启用回 LOADING)
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
| 状态 | 含义 |
|
|
89
|
+
|------|------|
|
|
90
|
+
| `pending` | 未开始加载。**disabled 插件也停在 pending**——不进状态机 |
|
|
91
|
+
| `loading` | `loadPlugin` 运行中 |
|
|
92
|
+
| `active` | 注册全量生效,可消费 |
|
|
93
|
+
| `unloading` | 卸载/禁用中——rollback 执行区间 |
|
|
94
|
+
| `disposed` | rollback 完成,登记清空 |
|
|
95
|
+
| `failed` | 加载失败——`failureReason` 可查 |
|
|
96
|
+
|
|
97
|
+
**缺依赖挂起:** `loading → pending` 也是合法迁移——`pendingReason`(如 `等待依赖: "a"`)记录挂起原因,marketplace 列表显示"等待依赖"。
|
|
98
|
+
|
|
99
|
+
**迁移规则(机械保障):**
|
|
100
|
+
- **卸载侧收敛:** `pending/loading/failed → unloading` 一律允许——**卸载必须总能完成到 DISPOSED**(加载中卸载 = 竞态收敛;失败态/未加载态卸载 = 诚实清场),防止插件卡在中间态。
|
|
101
|
+
- **加载侧严格:** `active → loading`(双重加载)等非法迁移 `console.warn` 不生效——抓真 bug。
|
|
102
|
+
- **状态机是诊断面不是看门狗**:非法迁移 warn 不 throw,禁止把加载流程带崩。诊断面 `getLoadDiagnostics(pluginId)` 返回 `loadState/failureReason/pendingReason/registeredEffects`。
|
|
103
|
+
|
|
104
|
+
**三方状态边界(不要混):**
|
|
105
|
+
|
|
106
|
+
| 层 | 是什么 | 谁消费 |
|
|
107
|
+
|------|------|------|
|
|
108
|
+
| **LoadState(本状态机)** | "插件为什么没激活"诊断面 | dev 面板 / 诊断日志 |
|
|
109
|
+
| **CachedPluginMeta.status** | 安装态:`installed` / `disabled` / `uninstalled` | marketplace(disabled 插件停在 PENDING 不冲突) |
|
|
110
|
+
| **PluginStateService** | 插件私有存储,非状态 | 插件自己读写 |
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## 四、依赖编排——`requires`
|
|
115
|
+
|
|
116
|
+
**`requires: string[]` 声明插件级激活顺序依赖**(按 pluginId,依赖须先激活本插件再激活)。旧字段 `extensionDependencies` 兼容合并(deprecated——统一用 `requires`)。
|
|
117
|
+
|
|
118
|
+
```json
|
|
119
|
+
{
|
|
120
|
+
"requires": ["file-tree", "editor"]
|
|
121
|
+
}
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
**加载时的三条规则:**
|
|
125
|
+
|
|
126
|
+
| 情形 | 行为 |
|
|
127
|
+
|------|------|
|
|
128
|
+
| **依赖已激活** | 正常加载 |
|
|
129
|
+
| **缺依赖** | **挂起 PENDING**(非失败)——`pendingReason = "等待依赖: "xxx""`,manifest 留存挂起注册表;依赖就绪后 sweep 自动补载(拓扑序激活,扫描序不再影响激活顺序) |
|
|
130
|
+
| **依赖环**(自环 + 传递环 A→B→C→A) | **fail-loud**——toast + `markLoadFailed`。图级环检测,非两两对 |
|
|
131
|
+
|
|
132
|
+
**每加载完成一个插件 → sweep 挂起队列**(依赖就绪者补载)。收敛:每轮 while 至少激活一个挂起插件才继续;guard 1000 兜底防极端竞态死循环。
|
|
133
|
+
|
|
134
|
+
**依赖消失连带卸载:** 卸载/禁用/目录删除任一途径触发时,先连带卸载依赖本插件的**活跃消费方**(逆拓扑序——消费方回滚期可能查询依赖的注册表贡献,依赖须最后退):
|
|
135
|
+
|
|
136
|
+
```
|
|
137
|
+
卸载插件 A
|
|
138
|
+
→ 连带卸载所有 requires 含 A 的活跃插件(递归——它们的消费方也先退)
|
|
139
|
+
→ 每个消费方:rollback 全量生效 + 落 PENDING(等待依赖回归,非卸载)+ pendingReason
|
|
140
|
+
→ 依赖恢复后 sweep 自动补载(自动复活)
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
**用户显式禁用优先:** 被禁用的消费插件不被依赖出现事件自动激活(禁用意图优先于依赖编排,防止被禁用插件"复活")。
|
|
144
|
+
|
|
145
|
+
---
|
|
146
|
+
|
|
147
|
+
## 五、JS 加载时机——壳零 import,池按需激活(定案,取代 activationEvents)
|
|
148
|
+
|
|
149
|
+
> 🔴 **2026-09-09 退役:`activationEvents` 字段已整体删除**(壳侧延迟激活轨已全退役——activation.ts / loader defer / `activatePlugin` / CommandRegistry 预激活钩全删,schema 三副本去字段)。**壳启动一律注册全量元数据**(`loadPlugin(pluginId, "startup")`,零 JS import);插件 **JS 由池按 URL 懒加载**。无字段可写、无需声明——加载模型只剩下面两种按需轨。
|
|
150
|
+
|
|
151
|
+
**启动即注册元数据:** 启动 `initPluginLoader` 发现全部插件 → 壳注册 manifest/contributes(命令显示名/菜单/配置 schema/图标栏元数据全可见)——**不 import 任何插件 JS**(硬约束 #17d:壳 bundle 零插件源码)。
|
|
152
|
+
|
|
153
|
+
**JS 加载 = 池的两种按需轨(插件作者契约):**
|
|
154
|
+
|
|
155
|
+
| 轨 | 触发点 | 机制 | 适用 |
|
|
156
|
+
|------|---------|------|------|
|
|
157
|
+
| **① 表面挂载** | 视图打开(contributes.views / 主区 tab) | 池 `PluginComponent`/`PluginDetailViewHost` 经 `resolvePluginViewLoader` 动态 import 视图 URL(dev `/@fs`、prod `linkdesk://`) | 有视图/入口的插件 |
|
|
158
|
+
| **② on-command 激活** | 命令 miss——`window.linkdesk.commands.executeCommand` 命中未注册命令 | 池 preload 回调 renderer → `import` **属主插件 entry**(顶层副作用注册命令 handler)→ 重试命中 | **无视图可开的纯命令插件**(entry 从未被任何表面 import 的缺口) |
|
|
159
|
+
|
|
160
|
+
**🔴 纯命令插件作者契约:命令 handler 必须放 entry 顶层(模块作用域),不要只放视图组件里。** 视图组件内的 `registerCommand` 只在视图挂载时执行——若插件无任何可开表面(或表面从不开),entry 从未被 import,命令恒 miss。顶层注册让 on-command 激活一次 import 即全量就位(`import()` 模块缓存幂等,重复 miss 不重复执行)。视图类插件(命令大多在视图 mount 注册)天然被轨①覆盖,无需顶层重复。
|
|
161
|
+
|
|
162
|
+
**入口 import 安全约定:** entry 顶层不应依赖「某个 DOM 容器已存在」才不崩(视图渲染走组件导出 + 池挂载,不在 entry 顶层 createRoot)——与主区 tab 现行为一致(池本就对主区 tab 直接 import entry)。
|
|
163
|
+
|
|
164
|
+
> **诚实标注:** 轨②由池 preload `executeLocal`(壳占位命令经 executeRequest 转发)与池直调 `executeCommand` 两条 miss 路径共用——命中后重试一次;entry import 完成仍 miss(命令确实只在视图组件注册)→ 按原语义 reject「命令未在池内注册」。无 `activationEvents` 级的事件精确控制——启动全量注册元数据 + 按需 import JS,是当前模型。
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## 六、运行契约——`isActive` + keep-alive + tabBehavior
|
|
169
|
+
|
|
170
|
+
**`isActive` prop 约定(入口组件):**
|
|
171
|
+
|
|
172
|
+
| 场景 | `isActive` |
|
|
173
|
+
|------|:--:|
|
|
174
|
+
| 标签页在前台 + 所在分屏面板活跃 | `true` |
|
|
175
|
+
| 标签页被其他标签页遮住 | `false` |
|
|
176
|
+
| 标签页所在面板不活跃(分屏时另一个面板活跃) | `false` |
|
|
177
|
+
|
|
178
|
+
**keep-alive 机制:** 所有标签页内容始终挂载,用 CSS `display` 切换。不要用 `{isActive && <View/>}` 条件渲染——会销毁 Monaco/Canvas 状态。
|
|
179
|
+
|
|
180
|
+
```tsx
|
|
181
|
+
// ✅ 正确——副作用用 isActive 守卫(硬约束 14)
|
|
182
|
+
useEffect(() => {
|
|
183
|
+
if (!isActive) return;
|
|
184
|
+
editorRef.current?.layout(); // Monaco 重新布局
|
|
185
|
+
}, [isActive]);
|
|
186
|
+
|
|
187
|
+
// ❌ 错误——销毁组件状态
|
|
188
|
+
if (!isActive) return null;
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
**`tabBehavior`(顶层字段)决定标签页语义:**
|
|
192
|
+
|
|
193
|
+
| 声明 | 行为 |
|
|
194
|
+
|------|------|
|
|
195
|
+
| 默认(无声明) | 每次点击图标 → 创建新标签页 |
|
|
196
|
+
| `singleton: true` | 全局只一个实例。重复点击 → 聚焦已有标签页 |
|
|
197
|
+
| `isFallback: true` | 场上无标签页时自动创建。不可关闭。只有欢迎页声明 |
|
|
198
|
+
| `confirmOnClose` | 关闭前弹确认框(值 = 提示文本) |
|
|
199
|
+
| `identityField` | 标签页身份字段——同名不重复开(如 workspace 声明 `"workspaceName"`) |
|
|
200
|
+
|
|
201
|
+
```json
|
|
202
|
+
{
|
|
203
|
+
"tabBehavior": {
|
|
204
|
+
"singleton": true,
|
|
205
|
+
"confirmOnClose": "确定关闭设置页?"
|
|
206
|
+
}
|
|
207
|
+
}
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
> `invokeBeforeClose` 否决回路已停用(该回路已删除)——声明保留待未来池侧 requests 命名空间;`confirmOnClose` 仍生效。
|
|
211
|
+
|
|
212
|
+
---
|
|
213
|
+
|
|
214
|
+
## 七、可逆注册——registrationTracker
|
|
215
|
+
|
|
216
|
+
**一切注册返回 disposer,卸载逆序回滚(LIFO——后注册的先滚)。**
|
|
217
|
+
|
|
218
|
+
- **登记:** 每个 `register()` 内部把条目入表后调 `trackRegistration(pluginId, disposer)` 登记"删这一条"的 disposer。
|
|
219
|
+
- **触发:** 模块加载时订阅一次 `PluginLifecycle.onWillUninstall` → 任何有登记的插件卸载/禁用**自动逆序回滚**——无需手动 unregister* 清理(删掉了全部 per-entry 手动清理消费端)。
|
|
220
|
+
- **幂等:** 返回的 disposer 带 done 守卫——手动 dispose + rollback 双跑不双清。
|
|
221
|
+
- **容错:** 单条 disposer 抛错不中断后续回滚(错误入 ErrorService 诊断面)。
|
|
222
|
+
- **覆盖:** 类注册表(RegistryBase.track)与函数注册表(Command/Keybinding/Menu/Configuration…直接调 trackRegistration)共用同一套机制。
|
|
223
|
+
|
|
224
|
+
**插件作者不需要做任何事**——你的组件 mount 时 `registerCommand`/`window.linkdesk.*` 池侧注册,卸载时壳统一逆序回滚。卸载是原子操作,不会留下半个插件的幽灵注册。
|
|
225
|
+
|
|
226
|
+
---
|
|
227
|
+
|
|
228
|
+
## 八、卸载状态机——`unloadPlugin`(唯一卸载路径)
|
|
229
|
+
|
|
230
|
+
**三条生产流共用同一个卸载入口:** 用户卸载、用户禁用、文件监听发现目录被删。顺序由迁移图机械保障(L6b——此前 5 个生命周期函数各自维护 5-6 个副作用 = 30 个维护点,80 个 commit 修同一处漏改):
|
|
231
|
+
|
|
232
|
+
```
|
|
233
|
+
unloadPlugin(pluginId, reason, displayName)
|
|
234
|
+
reason = "uninstall"(卸载)| "disable"(禁用)
|
|
235
|
+
① 幂等守卫——已在 unloading/disposed → 跳过
|
|
236
|
+
② 连带卸载消费方(cascadeDependents,逆拓扑序,见 §四)
|
|
237
|
+
③ 清理本插件的挂起登记
|
|
238
|
+
④ 迁移 → UNLOADING
|
|
239
|
+
⑤ notifyPluginRemoved——CustomEvent PLUGIN_REMOVED → 壳关闭相关标签页 + 侧栏视图
|
|
240
|
+
🔥 必须先于 onWillUninstall:壳 revert 逻辑要读 viewRegistry 的 manifest,
|
|
241
|
+
tracker 回滚在 fire 内同步删 viewRegistry 条目——先 fire 则回退静默失效
|
|
242
|
+
⑥ onWillUninstall.fire——registrationTracker 逆序回滚在此同步执行(全部登记清除)
|
|
243
|
+
⑦ loadedPluginIds.delete + _deferredPlugins.delete
|
|
244
|
+
⑧ 迁移 → DISPOSED
|
|
245
|
+
⑨ onDidUninstall.fire——toast(带「撤销」按钮)+ 视图刷新 + IPC plugin:uninstalled 广播
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
**连带卸载(orphanPlugin)走同序但落 PENDING:** `unloading → notifyPluginRemoved → onWillUninstall[tracker 回滚] → 集合清理 → pending`——不发 onDidUninstall(非用户卸载,静默;后果 toast 由顶层 unloadPlugin 聚合:"插件 X 因依赖 A 消失转入等待——依赖恢复后自动启用")。
|
|
249
|
+
|
|
250
|
+
**生命周期事件总览(`PluginLifecycle` Emitter):**
|
|
251
|
+
|
|
252
|
+
| 事件 | 载荷 | 触发时机 |
|
|
253
|
+
|------|------|------|
|
|
254
|
+
| `onDidInstall` | `{ pluginId, manifest, reason: install/reinstall/enable/startup }` | 注册全量生效后 |
|
|
255
|
+
| `onWillUninstall` | `{ pluginId, reason: uninstall/disable, displayName }` | 回滚前(viewRegistry 条目还在) |
|
|
256
|
+
| `onDidUninstall` | 同上 | 回滚完成后(viewRegistry 条目已删) |
|
|
257
|
+
|
|
258
|
+
消费端(壳内置,插件不用管):图标排序(install/reinstall 追加末尾;uninstall 移除;disable/enable 保留原位)、toast(startup 静默)、视图刷新、IPC `plugin:installed`/`plugin:uninstalled` 广播(仅 install/reinstall/uninstall)。
|
|
259
|
+
|
|
260
|
+
---
|
|
261
|
+
|
|
262
|
+
## 九、生命周期操作——安装 / 启用 / 禁用 / 卸载 / 重装
|
|
263
|
+
|
|
264
|
+
### 9.1 安装 `installPlugin(sourcePath)`(E6 zip 分发路由)
|
|
265
|
+
|
|
266
|
+
`sourcePath` 三态自适应(`isPackageSource`):目录路径 / `http(s)://` URL / 磁盘 `.linkdesk-plugin` zip。**分发主路 = zip / URL 包源**(E6 zip 单文件);目录源仅 dev 便捷用。
|
|
267
|
+
|
|
268
|
+
```
|
|
269
|
+
validating → 包源:主进程 plugins:download / plugins:extract → 解压前校验
|
|
270
|
+
(zip 顶层 plugin.json 定位 + JSONC 解析(#55)+ pluginId 裁决 + zip-slip 防护——不留半装目录)
|
|
271
|
+
→ 目录源:plugin.json 存在 + JSON.parse 合法
|
|
272
|
+
→ pluginId 裁决(**manifest.pluginId 优先**;缺省 zip 基名/源目录名兜底——**兜底只为兼容存量第三方
|
|
273
|
+
插件**,新插件一律显式声明,见 [16-命名规范](16-命名规范.md);须过安全字符集);version 必填
|
|
274
|
+
→ 目标 {userData}/plugins/<id>/ 已存在 → 读盘比对版本(resolveVersionConflict):
|
|
275
|
+
同版 → 跳过(包源删重复源);异版 → 拒绝(升级走 checkUpdates/update,不覆盖)
|
|
276
|
+
extracting → zip 解压到 {userData}/plugins/<id>/(wrapper 剥离)
|
|
277
|
+
→ 消毒 manifest:distribution 遗留字段恒归一化为 user(2026-09-05 塌平后无 builtin/user 目录语义)
|
|
278
|
+
→ 主进程 notifyManifestChanged(重扫 LangDef/Protocol/FileAssociation 三表)
|
|
279
|
+
loading → loadPlugin(pluginId, "install")(安装态 bundle 路径即时加载)
|
|
280
|
+
→ 成功 toast「已安装:name v1.0.0」
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
**版本处理定案:不覆盖安装**——同版跳过(无需重复安装)、异版拒绝(如需升级走更新流,见 [04-插件分发格式 §四](04-插件分发格式.md))。真升级 = stage→原子替换→失败退旧版(`PluginUpdateService`)。
|
|
284
|
+
|
|
285
|
+
### 9.2 启用 `enablePlugin(pluginId)`
|
|
286
|
+
|
|
287
|
+
从 `disabledPlugins` 列表移除 → `loadPlugin(pluginId, "enable")`。repo 源码树即时生效;安装态(userData bundle)插件若无法运行时动态注入则返回 `needRestart: true`。
|
|
288
|
+
|
|
289
|
+
### 9.3 禁用 `disablePlugin(pluginId)`
|
|
290
|
+
|
|
291
|
+
`disabledPlugins` 列表加入 + 持久化 → 元数据缓存标 `disabled` → **主题/语言回退**(当前主题/语言来自此插件 → 自动切到替代)→ `unloadPlugin(pluginId, "disable")`。**插件文件保留**,下次启动跳过。禁用 → iconOrder 保留原位(下次启用恢复)。对标 VS Code "Disable Extension"。
|
|
292
|
+
|
|
293
|
+
### 9.4 卸载 `uninstallPlugin(pluginId)`
|
|
294
|
+
|
|
295
|
+
1. `core: true` 前置守卫——core:true 的插件卸载按钮在 UI 不显示/禁用(**防误删旗标**,非类别:外壳依赖它提供设置页/市场等基础交互)
|
|
296
|
+
2. **双分支(2026-09-05 塌平后)**:
|
|
297
|
+
- 目标在 `{userData}/plugins/<id>/`(安装态 zip 装的)→ **真删目录 + `PluginInstallService.remove` 销账**(写 removed 标记——boot 见标记不再自动恢复)
|
|
298
|
+
- 目标在 repo 源码树(app 插件)→ 移 `plugins/.disabled/<id>/` 坟场 + 可 reinstall(Windows 跨目录 rename 文件锁教训,copy+remove 非 rename)
|
|
299
|
+
3. 元数据缓存标 `uninstalled`(卸载后 marketplace 仍可浏览详情)
|
|
300
|
+
4. 主题/语言回退 → `unloadPlugin(pluginId, "uninstall")`
|
|
301
|
+
5. 清理禁用列表(卸载优先级高于禁用)→ 同步枚举 → toast「已卸载:name」→ `notifyManifestChanged`
|
|
302
|
+
|
|
303
|
+
### 9.5 重装 `reinstallPlugin(pluginId)`
|
|
304
|
+
|
|
305
|
+
源码树 app 插件:从 `plugins/.disabled/<id>/` 复制回 `plugins/<id>/` → `loadPlugin(pluginId, "reinstall")`。安装态插件重装 = 重新走安装流(9.1)。对标 VS Code 卸载后本地保留一键重装——**任何能被卸载的插件,重装必须同 session 恢复全部贡献**(见 9.6)。
|
|
306
|
+
|
|
307
|
+
### 9.6 🔥 可卸载 ⇒ 可重装契约
|
|
308
|
+
|
|
309
|
+
**任何插件,只要能被卸载,重装就必须同 session 立即恢复全部贡献**——与插件形状无关:repo 源码树/安装态、有无 entry、core 标志全不豁免(core 只是防误删旗标,不是类别例外)。
|
|
310
|
+
|
|
311
|
+
**实现依赖:** 插件根 URL 归一化入口 `resolveRuntimePluginRoot`(同一句 `dev ? /@fs/{abs} : linkdesk://{id}`)——entryless 插件(纯 views/commands 贡献)重装后 `views` 注册兜底链依赖它做动态 import。曾因 pluginRoot 赋值绑死 `manifest.entry` 而断裂(entryless 重装后 view 加载失败)——已修复。
|
|
312
|
+
|
|
313
|
+
---
|
|
314
|
+
|
|
315
|
+
## 十、错误处理
|
|
316
|
+
|
|
317
|
+
| 错误 | 壳行为 | 插件责任 |
|
|
318
|
+
|------|------|------|
|
|
319
|
+
| plugin.json 格式错误 | 跳过该插件 + toast + `markLoadFailed` | 校验格式(IDE 走 `$schema` 自动补全) |
|
|
320
|
+
| `minAppVersion` 不满足 | toast「需要应用版本 ≥X」+ `markLoadFailed` | 声明保守的 minAppVersion |
|
|
321
|
+
| 依赖环 | toast + `markLoadFailed`(fail-loud) | 别环——检查 requires 拓扑 |
|
|
322
|
+
| 缺依赖 | **挂起 PENDING**(非失败)——依赖就绪自动加载 | 先装依赖 |
|
|
323
|
+
| entry 文件找不到 | toast + `markLoadFailed` | 确保 entry 路径正确 |
|
|
324
|
+
| 运行时 JS 加载失败(可能未构建) | toast「可能未构建」——**不阻断**:contributes 仍注册 | 构建后再装 |
|
|
325
|
+
| React 组件 throw | ErrorBoundary 捕获 → "「插件名」已崩溃 [重试]" | 不写不崩的代码 |
|
|
326
|
+
| 卸载中某 disposer 抛错 | 不中断——registrationTracker 逐条容错,错误入诊断面 | — |
|
|
327
|
+
| 并发 loadPlugin(StrictMode 双挂载) | 第二次等第一次 Promise(硬约束 13) | — |
|
|
328
|
+
|
|
329
|
+
---
|
|
330
|
+
|
|
331
|
+
## 十一、与 VS Code 对照
|
|
332
|
+
|
|
333
|
+
| 维度 | VS Code | LinkDesk |
|
|
334
|
+
|------|---------|----------|
|
|
335
|
+
| 激活时机 | `activationEvents` 多事件(onLanguage/onCommand/workspaceContains…) | **无事件字段**(已退役)——启动全量注册元数据;JS 由池按需加载 |
|
|
336
|
+
| 延迟加载 | 扩展 JS 按需 import | 壳启动零 JS import(#17d);JS 唯一执行者 = 池——表面挂载 URL 懒加载 / 命令 miss 时 import entry(on-command 激活、§五) |
|
|
337
|
+
| 加载扫描 | 启动 scan `extensions/` | 发现单源 `plugins:listAll` 主进程直扫(dev/prod 同面)+ 2s 轮询热插拔 |
|
|
338
|
+
| 依赖 | `extensionDependencies` | `requires`(string 数组)+ 挂起 PENDING / 环 fail / 连带卸载 |
|
|
339
|
+
| 卸载 | Disable / Uninstall | 安装态 = 真删目录 + 销账(removed 标记,boot 不复活);repo 源码树 app 插件 = 移 `.disabled/` 作**同会话** undo(跨重启孤儿 boot 自动清) |
|
|
340
|
+
| 清理 | onWillUninstall 手动 unregister | **registrationTracker 自动逆序回滚**(零手动清理) |
|
|
341
|
+
| core 插件 | 不可卸载 | `core: true` 插件详情 UI 无卸载入口(纯防误删旗标——API/命令层可卸可禁,卸后写 removed 墓碑不复活) |
|
|
342
|
+
|
|
343
|
+
---
|
|
344
|
+
|
|
345
|
+
> **← 上一份:** `01-插件API契约.md`
|
|
346
|
+
> **→ 下一份:** `03-插件contributes规范.md`
|
|
347
|
+
> **→ 相关:** `04-插件分发格式.md`(安装/卸载的文件形态)
|
|
348
|
+
> **全部文档索引:** `00-README.md`
|