@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,172 @@
1
+ # 04 — 插件分发格式
2
+
3
+ > 2026-07-24 · 2026-08-21 更新 · **2026-09-06 全量重写(塌平单根 + zip 单文件分发)**。
4
+ > **插件怎么交付、怎么安装、版本兼容规则。** 对标 VS Code 的 `.vsix`——LinkDesk 用 **`.linkdesk-plugin` 单文件 zip** 分发。
5
+ > 打包格式细节的真相源 = [01-插件独立构建/02-linkdesk-plugin格式规范.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/01-插件独立构建/02-linkdesk-plugin格式规范.md)(本页只讲作者侧的交付/安装/版本故事)。
6
+
7
+ ---
8
+
9
+ ## 一、分发格式——一个 `.linkdesk-plugin` 单文件 zip
10
+
11
+ **LinkDesk 插件的交付形态 = 一个 `.linkdesk-plugin` 单文件**(zip 包,SDK 构建产物)。插件源码是一个普通目录([09-插件目录规范](09-插件目录规范.md)),但**分发给用户/上架市场的永远是那个 zip**——整目录复制即安装的目录分发时代已结束(2026-09-05 塌平单根拍板)。
12
+
13
+ ```
14
+ my-plugin/
15
+ ├── <id>.linkdesk-plugin ← 分发/安装/市场的唯一载体(zip)
16
+ │ ├── plugin.json ← 改写克隆(contributes.views[].render → views/<View>.bundle.js)
17
+ │ ├── index.bundle.js ← 主入口 bundle(loader 检测其存在即以 bundle 为运行时入口)
18
+ │ ├── index.bundle.css ← 聚合样式
19
+ │ ├── views/<View>.bundle.js ← 每个 contributes.views[].render 一次独立构建
20
+ │ ├── resources/ icon.svg 等 ← 资源随包
21
+ │ └── (themes/ assets/ i18n/ node_modules/ …) 按插件内容
22
+ └── src/ … ← 作者源码(不进 zip)
23
+ ```
24
+
25
+ **谁产 zip:** [plugin-sdk](https://github.com/Encaron/linkdesk/tree/electron/packages/plugin-sdk)(`npm run publish` 走 [E6 作者旅程](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/05-文档与发布/00-第三方作者旅程.md))在**项目根**产 `<id>.linkdesk-plugin` + 解包目录 `dist/<id>.linkdesk-plugin/`。zip 内 JS 全部预构建自包含(react 系 external,壳提供)——**安装态没有源码编译**。
26
+
27
+ **为什么是单文件:** 壳 loader 对安装态插件只认预构建 bundle——`plugin-file-service` 检测到 `index.bundle.js` 存在即覆盖 entry 指向它(`resolveEntry`,bundle 入口恒 `index.bundle.js`)。zip 是「一个插件 = 一个可下载/可校验/可原子替换的文件」,装卸与市场下载都对着它。
28
+
29
+ > **源码目录 vs 分发文件是两回事:** 开发是目录(dev 源码树 HMR),分发是 zip(预构建产物)。别拿源码目录当安装载体,也别改 zip 里的 bundle 当热更——改了源码要**重 build + 重发**(见 §二 版本纪律)。
30
+
31
+ ---
32
+
33
+ ## 二、安装流程——zip → `{userData}/plugins/<id>/`
34
+
35
+ **安装目标恒为 `{userData}/plugins/<pluginId>/`**(`env.userPluginsDir`,{userData} = Electron `app.getPath('userData')`,Windows `%APPDATA%/LinkDesk`)。安装态**没有 builtin/user 双层**——随壳发货的插件与用户装的第三方在**同一棵树平铺并列**,差异只剩 manifest 字段(见 §三)。
36
+
37
+ **两条到达路径(同一条落盘路):**
38
+
39
+ | 路径 | 谁 | 落点 | 语义 |
40
+ |------|------|------|------|
41
+ | **boot 自动装(首启种子一次化)** | 随壳发货的 `bundled-plugins/*.linkdesk-plugin`(prod 在 `resources/bundled-plugins`) | `{userData}/plugins/<id>/` | 决策序:① 目录在 → 跳过(同/异版都不覆盖)② 账本 `removed` → 跳过(尊重)③ **无任何记录 + 目录缺 → 铺种子**(首启/更新新随车件首现)④ 有活性记录 + 目录缺 → 跳过不铺(不复活——墓碑化动作归 renderer 对账置章)。损坏目录修复(完整性修复,≠复活被删的)保留 |
42
+ | **用户安装** | `pluginManager.install(url \| 磁盘 zip \| 目录)` | 同上 | 下载/解压/校验 → 落盘;目录源仅 dev 便捷用,分发主路是 zip |
43
+
44
+ **安装期校验(解压前拦截,不产生半装目录):**
45
+ - zip 顶层定位 `plugin.json`(basename 匹配,容忍单层 wrapper 目录)——JSONC 解析(#55)
46
+ - `pluginId` 裁决:manifest 优先、zip 文件基名兜底,双源互验;必须过安全字符集(无路径分隔符/相对段)
47
+ - zip-slip 防护——条目路径拒绝逃逸解压目标
48
+ - 目标已装同版本 → 跳过(用户安装删源);异版本 → 不动(升级是更新流职责,boot 不覆盖)
49
+
50
+ **源码根有三处,别混**(🔴起:**发货插件的源码不在壳仓**):
51
+
52
+ | 代码根 | 位置 | 形态 | HMR | 谁住这里 |
53
+ |------|------|------|:--:|------|
54
+ | **插件自己的仓** | GitHub `Encaron/linkdesk-plugin-<id>`(本地克隆落在容器目录 `E:\linkdesk-plugins\official\<id>\`) | 源码 + SDK build(`npm run build` → `<id>.linkdesk-plugin`) | ✅(`linkdesk-plugin-sdk dev`) | **18 只发货插件全部**——一只一个仓(D1),源码真相源只此一处 |
55
+ | **壳仓夹具** | `<壳仓>/plugins/<id>/`(`env.appPluginsDir`) | 源码 + Vite 即时编译 | ✅(`npm run dev` 热更) | 只剩两只**开发夹具**:`panel-demo` / `floating-panel-demo`(不发货、不进 zip) |
56
+ | **安装态** | `{userData}/plugins/<id>/` | zip 解出的预构建 bundle | ❌(改包需重 build + 重装/重物化) | 用户机器上所有已装插件 |
57
+
58
+ > 🔴 **为什么发货插件的源码不能两边都留一份**:一旦壳仓与插件仓各有一份,改了这头那头不变,而**没有任何门禁能发现分叉**(内容指纹门禁只管 zip 内容,不管源码)⇒ 真相源必须唯一。壳仓留下的两样是**产物**(`bundled-plugins/*.linkdesk-plugin`)与**文档档案**,不是源码。
59
+
60
+ > **真机环例外(作者 dev):** 安装态改包需「重 build + 重装/重物化」在**作者每次真机验证**场景 = WPF v2 一次性循环痛苦。真机环自动化它——SDK 秒级重建 + **直写** `{userData}/plugins/<id>`(同盘覆盖语义,reload 即生效)成循环,作者仍不碰壳。分发 zip 的「不自改 bundle」纪律不变(那是给终用户的包)。设计档案 → [04-作者真机调试环.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/04-作者真机调试环.md)。
61
+
62
+ > **卸载语义(2026-09-05 后):** 安装态插件卸载 = **删 `{userData}/plugins/<id>/` 目录 + 账本销账**(不再是 `.disabled/` 移入);只有 repo 源码树里的 app 插件卸载才移 `plugins/.disabled/` 坟场(可 reinstall 恢复)。账本 `installed-plugins.json` 唯一 owner = 渲染进程 PluginInstallService,boot 只读它的 `removed` 标记防误恢复。
63
+ > 🔵 **核对结论(`.disabled/` 坟场还有没有消费者)**:**机制仍在、当前无对象**。消费者是活的——`src/pluginLoader/loader.ts` 读它(`reinstallPlugin` / 卸载 toast 的「撤销」/ 跨重启孤儿清理都以 `env.appPluginsDir/.disabled` 为唯一权威面)。但 `env.appPluginsDir` = 壳仓 `plugins/`,而 18 只发货插件已外移 ⇒ 那里只剩两只夹具,**没有「在 repo 源码树里被卸载的 app 插件」了**。⇒ 机制**保留**(它是仓内插件 dev 路径的一部分,删它要动 loader 三处 + 主进程扫描面,风险大于收益),但**不要**再把它当成发货插件的可撤销卸载通道。
64
+
65
+ ---
66
+
67
+ ## 三、目录分类——没有「内置/用户」两类,只有字段
68
+
69
+ **插件只有一类。** 安装态全在 `{userData}/plugins/<id>/` 平铺,身份差异全在 plugin.json 声明字段,不在目录:
70
+
71
+ | 字段 | 语义(唯一真相) |
72
+ |------|------|
73
+ | `core: true` | **UI 防误删旗标**——卸载按钮不显示/禁用(外壳依赖它提供设置页/市场等基础交互,删了壳就残)。**不是类别、无行为特权**——加载/装卸走同一条路 |
74
+ | `distribution` | ⚠️ **遗留字段**(schema 已标注)——塌平后不再对应任何目录,安装侧恒归一化为 `user`。**第三方插件请勿填写** |
75
+
76
+ 措辞纪律(硬约束 11):不叫「内置插件 vs 第三方插件」两类——说「**core:true 的插件**」(纯 UI 藏钮防误删,API/命令层可卸可禁)与「**随壳发货的插件**」(bundled zip 那份)。**仓内现况(起)**:壳仓 `plugins/` 下只剩两只开发夹具;core:true 的 4 只(`editor` `file-tree` `marketplace` `settings`)源码住在**各自的仓**里;**随壳发货 = `bundled-plugins/` 的那 6 个 zip**(设置 / 插件市场 / 语言 / 基础主题 / 文件树 / 编辑器) —— 版本账见 `bundled-plugins.lock.json`(7.4 轮产出)。「哪几个 core:true」不是壳代码里的名单,只由 zip 与 lock 数据声明(硬约束 10)。
77
+
78
+ **插件数据目录(与代码根独立):**
79
+
80
+ | 路径 | 用途 |
81
+ |------|------|
82
+ | `{userData}/linkdesk/plugins/<id>/data/` | 插件持久化数据——唯一可写目录 |
83
+ | `.../data/cache/` | 缓存(可安全删除) |
84
+ | `.../data/exports/` | 导出文件(用户可见) |
85
+
86
+ > 🔥 **两个 "plugins" 根别混:** `{userData}/plugins` = 代码根(zip 解压处,`userPluginsDir`);`{userData}/linkdesk/plugins` = 数据根(`pluginsRootDir`)。卸载重装**不清数据**——数据在独立数据根。作者经 `window.linkdesk.env.get("<id>")` 拿 `pluginDataDir`(含 pluginId 才返回),壳自动建目录,插件无需自建。
87
+
88
+ ---
89
+
90
+ ## 四、版本兼容
91
+
92
+ ### 语义化版本 + 更新路
93
+
94
+ `version` 遵循 semver(`major.minor.patch`)。**boot 永不刷新已装插件**(bundled 夹 = 首启离线种子,非更新通道)——已装用户拿新内容只有一条路 = **更新流**:`pluginManager.checkUpdates`(fetch catalog + semver 对比)→ `update`(stage 到 tmp → 原子替换 → 失败退旧版)。市场真实条目按版本发现更新。
95
+
96
+ ### 🔥 内容变更必 bump 自身 version(2026-09-06 #15n 定案)
97
+
98
+ **分发过的插件,任何内容变更(代码 / 资源 / README / CHANGELOG)都必须 bump `plugin.json.version`。** 已装用户的副本是**按版本固化**的——boot 只补缺失、永不刷新已装;用户拿到新内容的唯一路 = **版本号**。改内容不 bump = 已装用户永远滞留在旧内容(2026-09-06 实证:bundled 发货 zip 加了 pyright 没 bump → 已装副本 LSP 全挂)。
99
+
100
+ **随壳分发的 bundled zip 同理**:重打 zip 内容变更必 bump——`npm run check` 的打包 gate 会在「同版内容 diff」时红拦(`scripts/check-bundled-version-bump.mjs`)。已装用户拿 bundled 内容修复 = 走市场真实条目按版本发现/更新,**boot 不伸手**。
101
+
102
+ ### minAppVersion / requires / permissions
103
+
104
+ 三者 schema 均已声明(见 [03-contributes](03-插件contributes规范.md)),安装期不强制——语义与 [02 生命周期 §九](02-插件生命周期.md) 对齐:
105
+
106
+ - `minAppVersion` —— 加载期校验(不满足 → toast + 跳过)
107
+ - `requires` —— 运行期依赖编排生效(缺依赖挂起 PENDING + 环 fail-loud + 连带卸载逆拓扑,见 [02 §四](02-插件生命周期.md))
108
+ - `permissions` —— 声明即用户知情,授权模型待 E6
109
+
110
+ ---
111
+
112
+ ## 五、资源路径——相对插件目录,壳解析(硬约束 12)
113
+
114
+ **🔥 禁止硬编码绝对路径。** 插件内资源(图标/图片/字体/任何资产)引用 = **相对插件目录的声明式路径**,壳加载时解析为当前协议下的绝对 URL(icon 走 `resolvePluginIcon`、`contributes.views[].render` / 资产走 `getPluginAssetPath`)——兼容 dev `http://localhost:1420` 与打包后 `file://`。**作者不 import 路径工具、不手拼 URL。**
115
+
116
+ ```jsonc
117
+ // ✅ 正确——声明相对路径,壳解析(dev 与打包版通吃)
118
+ { "icon": "resources/logo.png" }
119
+ // contributes.views[].render 同理: { "render": "src/views/MainView.tsx" }
120
+
121
+ // ❌ 错误——绝对路径字面量,打包后 file:// 下解析炸裂
122
+ // { "icon": "/assets/logo.png" }
123
+ ```
124
+
125
+ > **dev 能跑是巧合**(http 服务把绝对路径兜住了),打包后 `file://` 才现形。需要自渲染资源时走声明路径由壳解析,见 [09 §静态资源](09-插件目录规范.md) 与 [01-插件API契约](01-插件API契约.md)。
126
+
127
+ ---
128
+
129
+ ## 六、安装后的生命周期操作
130
+
131
+ 安装/卸载/更新/重装的作者侧说明在 [02-插件生命周期 §九](02-插件生命周期.md)。作者 API 面(install/installWithProgress/uninstall/update/checkUpdates/reinstall)见 [01-插件API契约](01-插件API契约.md) 的 `pluginManager` 段。
132
+
133
+ ---
134
+
135
+ ## 七、开发 → 分发全流程
136
+
137
+ ```
138
+ 1. 开发(自己的项目 or repo plugins/<id>)
139
+ 写 plugin.json + src/ → 源码树跑 → HMR 即时热更新
140
+
141
+ 2. 构建(第三方发布前)
142
+ 用 plugin-sdk → 产 <id>.linkdesk-plugin(作者视角全流程 → 00-第三方作者旅程)
143
+
144
+ 3. 分发
145
+ 交付 <id>.linkdesk-plugin 单文件 → 用户安装 / 上市场
146
+
147
+ 4. 安装
148
+ pluginManager.install(url | 磁盘 zip) → 校验 → 解压到 {userData}/plugins/<id>/
149
+ → 重启或即时加载 → 图标出现
150
+
151
+ 5. 更新
152
+ 内容变更必 bump version → 重 build 重发 → 用户 checkUpdates/update
153
+ ```
154
+
155
+ ---
156
+
157
+ ## 八、与 VS Code 对照
158
+
159
+ | LinkDesk | VS Code |
160
+ |------|------|
161
+ | `.linkdesk-plugin` 单文件 zip(下载/解压到 `{userData}/plugins/<id>/`) | `.vsix` 单文件(下载/解压到 `~/.vscode/extensions/<id>/`) |
162
+ | `{userData}/plugins/<id>/` 安装目录(平铺单根) | `~/.vscode/extensions/<id>/` |
163
+ | `core: true` 插件不可卸(防误删旗标) | `builtin/` 内置扩展 |
164
+ | 卸载 = 删目录 + 销账(真删);源码树 app 插件才移 `.disabled/` | 卸载 = 删文件(不可恢复) |
165
+ | `env.get(id).pluginDataDir` | `ExtensionContext.storagePath` |
166
+ | `core: true` 插件发货 = `bundled-plugins/*.linkdesk-plugin`(**首启种子**:boot 只补缺失、**永不刷新已装副本**;但**箱子本身会随壳版本刷新**——打包前由 `sync:bundled` 拉各插件「最新已发布版」,D3) | 随应用更新(安装包内置) |
167
+ | `requires` **运行期**依赖编排([02 §四](02-插件生命周期.md)) | `extensionDependencies` 安装期解析 |
168
+
169
+ ---
170
+
171
+ > **← 上一份:** `03-插件contributes规范.md`
172
+ > **→ 相关:** `02-插件生命周期.md`(安装/卸载/更新)· `09-插件目录规范.md`(源码目录)· [01-插件独立构建/02-linkdesk-plugin格式规范.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/01-插件独立构建/02-linkdesk-plugin格式规范.md)(zip 格式真相源)