@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
+ # 11-主题制作(第三方主题插件作者指南)
2
+
3
+ > **状态:** 定稿(2026-08-23)——schema 已冻结([05](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/05-主题数据模型.md) 决策 A-F)。
4
+ > **一句话:** 主题 = 插件的一种——一个配方 json(风格域 + 配色变体)+ 可选资产;「域贡献者」缺的域继承默认,写得越少越稳。
5
+ > **ai化 = AI 友好度:** 本文读者 = **人类 + AI**——AI 读本文能产出合法主题文件,AI 读示例主题(如迁移后的 mint-soda)能仿造同类。schema 每个概念只有一种写法(决策 F:一律 `colorways[]`)。
6
+ > **2026-09-06 与实现对齐核对**(对账):塌平单根(无 plugins/{builtin,user})· 共享控件走 @linkdesk/ui · 分发 = .linkdesk-plugin zip。本页对应机制引用已清。
7
+
8
+ ## 1. 主题插件是什么
9
+
10
+ - 主题是**插件**(硬约束 10:壳不写死任何插件 id,主题也走 plugin.json 声明)。
11
+ - 一个主题插件 = 1 个配方 json(`appearance` 风格域 + `colorways[]` 配色变体)。也可包含多个配方 json。
12
+ - **域贡献者**:只写你拥有的域,缺的继承壳默认([03 域贡献者](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/03-域贡献者与混搭.md))——纯配色主题 = 只写颜色;玻璃主题 = 写玻璃 + 颜色。
13
+ - **风格 vs 配色分离**:想要「1 个风格基座 + N 个配色」→ 一个配方里放 `colorways[]`([05 §2](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/05-主题数据模型.md) 完整 schema)。
14
+
15
+ ## 2. 写一个主题(先建目录 → 三步)
16
+
17
+ ### ⓪ 目录结构(必读——禁止平铺在根目录)
18
+
19
+ 主题插件目录 = 三类各归其位(对齐 [09-插件目录规范](09-插件目录规范.md) 通用约定):
20
+
21
+ ```
22
+ theme-myglass/
23
+ ├── plugin.json # 声明(contributes.themes)
24
+ ├── themes/ # 配方 json 唯一住处——禁止平铺在插件根目录
25
+ │ └── myglass.json
26
+ ├── assets/ # 资产:字体(woff2/ttf)+ 背景图(png/jpeg/webp)
27
+ │ ├── MyFont.woff2
28
+ │ └── bg.png
29
+ └── resources/ # 插件图标等元数据资产(09 §通用约定)
30
+ ```
31
+
32
+ | 目录 | 放什么 | 规则 |
33
+ |:--|:--|:--|
34
+ | `themes/` | 配方 json(`appearance` + `colorways[]`) | **配方 json 一律放这里,禁止平铺在插件根目录**;一个插件可含多个配方 json(`contributes.themes` 每条 `path` 指向一个) |
35
+ | `assets/` | 字体(woff2/ttf)+ 背景图(png/jpeg/webp) | json 里写相对路径 `assets/...` → 壳 `getPluginAssetPath(pluginId, path)` 统一解析(硬约束 12);**禁止 `/assets/...` 绝对路径** |
36
+ | `resources/` | 插件图标等元数据资产 | 与 [09-插件目录规范](09-插件目录规范.md) 通用约定一致 |
37
+
38
+ > **为什么禁平铺:** 主题会越做越深——per-surface 精调 json、i18n、README、src(如需脚本/UI)都会陆续进插件目录。平铺根目录 = 未来每个新文件都要临时想放哪;`themes/`+`assets/`+`resources/` 三槽先立好,**每类定制化各归其位,扩展零搬动**(2026-08-23 用户拍板「未来肯定有更多东西要主题定制化,要容易加入主题制作」)。
39
+ >
40
+ > **最小主题 = 只要 `themes/` 一个目录**(纯配色主题不引资产连 `assets/` 都可以没有);字体/背景图才需要 `assets/`。
41
+
42
+ ### ① plugin.json 声明
43
+
44
+ ```jsonc
45
+ // plugin.json —— 主题声明走 contributes.themes(对标 VS Code,schema 权威见 plugin.schema.json)
46
+ {
47
+ "id": "theme-myglass",
48
+ "name": "我的玻璃主题",
49
+ "version": "0.1.0",
50
+ "contributes": {
51
+ "themes": [
52
+ { "id": "myglass", "label": "My Glass", "uiTheme": "dark", "path": "themes/myglass.json" }
53
+ ]
54
+ }
55
+ }
56
+ ```
57
+
58
+ ### ② 配方 json(引用 schema)
59
+
60
+ ```jsonc
61
+ // themes/myglass.json —— 契约 = theme.schema.json(契约随 @linkdesk/plugin-sdk 分发 = 作者 npm 通道)
62
+ // 建议首行注入 $schema 拿编辑器 IntelliSense(对标 plugin.schema.json):
63
+ // "$schema": "./node_modules/@linkdesk/plugin-sdk/schemas/theme.schema.json"
64
+ // ↑ 只有这一种写法(相对**插件自己的工程根**)。官方主题插件也住在自己的仓里,
65
+ // 与第三方同款工程形态;仓库内那份 "../../../public/schemas/…" 的相对写法**已随源码外移作废**。
66
+ // 格式错拦截:编辑器 IntelliSense + SDK validateThemeJson(npm 工程与官方插件仓同一条通道)
67
+ // 全量 schema 见 [05 §2](../02-Electron架构/E5.8_归一化基建/外观主题化/05-主题数据模型.md);运行时 parseThemeRecipe toast 是第二道防线
68
+ {
69
+ "id": "myglass", "name": "My Glass", "type": "dark",
70
+ "appearance": {
71
+ "radius": { "md": 10, "lg": 16 },
72
+ "glass": { "blur": 16, "saturate": 1.3, "tint": "rgba(255,255,255,0.06)", "opacity": 0.9 },
73
+ "font": { "ui": "assets/MyFont.woff2", "mono": "JetBrains Mono" },
74
+ "background": { "image": "assets/bg.png", "opacity": 0.85, "mask": 0.3 } // mask = 0-1 明暗系数(number),基色另走 maskColor
75
+ },
76
+ "colorways": [
77
+ { "id": "violet", "name": "紫罗兰", "colors": { "bg-window": "#0E0B16", "accent": "#8B5CF6" } },
78
+ { "id": "emerald", "name": "翡翠", "colors": { "bg-window": "#0A1410", "accent": "#34D399" } }
79
+ ]
80
+ }
81
+ ```
82
+
83
+ > **单配色主题** = `colorways` 数组只含 1 项(例:官方主题 dark 迁移后 = `colorways: [{ id:"dark", name:"Dark", colors:{…} }]`)——**没有第二种写法**(决策 F)。
84
+
85
+ ### ③ 资产(可选)
86
+
87
+ - 字体/背景图挂在插件目录,json 里写**相对路径**(`assets/...`)——渲染时壳用 `getPluginAssetPath(pluginId, path)` 统一解析(硬约束 12)。**禁止写 `/assets/...` 绝对路径。**
88
+ - 字体两种形式:①资产路径(随插件分发)②系统字体族名字符串(用户机器上已有的)。
89
+
90
+ ### ④ 满配示例(六域全写 + 资产 + 3-4 配色——「几乎全部可主题化」的范本)
91
+
92
+ > 想一次写完所有可主题化域的作者照这份抄。**风格(appearance 六域)与配色(colorways)分离**——换配色只动数组项;资产全相对路径。范本源自壳内置的液态玻璃配方。
93
+
94
+ ```
95
+ theme-liquid-glass/
96
+ ├── plugin.json # contributes.themes 声明
97
+ ├── themes/
98
+ │ └── liquid-glass.json # 满配配方(六域全写 + 3 配色)
99
+ ├── assets/ # 资产:字体 + 背景图
100
+ │ ├── SpaceGrotesk.woff2 # font.ui 资产字体
101
+ │ ├── JetBrainsMono.ttf # font.mono 资产字体
102
+ │ └── aurora.jpg # background.image 资产
103
+ └── resources/
104
+ └── icon.svg # 插件图标
105
+ ```
106
+
107
+ ```jsonc
108
+ // themes/liquid-glass.json
109
+ {
110
+ "id": "liquid-glass",
111
+ "name": "液态玻璃",
112
+ "type": "dark",
113
+ "appearance": {
114
+ "radius": { "xs": 2, "sm": 4, "md": 8, "lg": 14, "xl": 20, "2xl": 24 },
115
+ "glass": { "blur": 20, "saturate": 1.8, "tint": "rgba(14,16,24,0.38)", "opacity": 0.9, "specular": 0.6, "morph": 400, "radius": 14, "shadow": true },
116
+ "font": { "ui": "assets/SpaceGrotesk.woff2", "mono": "JetBrains Mono" },
117
+ "background": { "image": "assets/aurora.jpg", "opacity": 1, "mask": "rgba(0,0,0,0.88)" }
118
+ },
119
+ "colorways": [
120
+ { "id": "aurora", "name": "极光紫", "colors": { "bg-window": "#0E0B16", "accent": "#8B5CF6" } },
121
+ { "id": "emerald", "name": "翡翠", "colors": { "bg-window": "#0A1410", "accent": "#34D399" } },
122
+ { "id": "ocean", "name": "深海", "colors": { "bg-window": "#0B121E", "accent": "#38BDF8" } }
123
+ ]
124
+ }
125
+ ```
126
+
127
+ | 域 | 写法 | 备注 |
128
+ |:--|:--|:--|
129
+ | radius | 六档尺寸 | `--radius-pill`/`--radius-full` 形态值不在此写(scale 排除,[08 §3](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/08-持久化与配置.md)) |
130
+ | glass | 材质键 + 悬浮形态 | specular/morph = 液态玻璃「反光/响应」([02 §2.3](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/02-变量契约.md) 材质定位);radius/shadow = 悬浮圆角/投影(surface 域删后并入 glass;inset 宿主派生、border 非字段) |
131
+ | font | ui 资产路径 + mono 系统族名 | 资产字体两步:先 @font-face 注册族名→写 `--font-ui` |
132
+ | background | image 资产 + opacity + mask | 相对路径 → getPluginAssetPath(硬约束 12) |
133
+ | colorways | 风格基座 + N 配色 | 3-4 个 = 推荐;单配色也写数组 1 项(决策 F) |
134
+
135
+ > **稀疏可省:** 满配只是「所有域都写了」——缺的域继承壳默认、域内缺的键继承(§3 稀疏覆盖),写越少越稳。纯配色主题 = 只写 colorways(连 `assets/` 都可以没有)。
136
+
137
+ ## 3. 避坑
138
+
139
+ | 坑 | 说明 |
140
+ |:--|:--|
141
+ | 配方 json 平铺在插件根目录 | **禁(§2 ⓪ 目录规范)**——一律放 `themes/`;未来 i18n/README 各归其位 |
142
+ | 写顶层 `colors`(无 `colorways`) | **旧格式已弃**(决策 F)——引擎只读 `colorways[]`;单配色也写数组 1 项 |
143
+ | 写绝对路径 | 打包后 `file://` 全炸——一律相对路径 + getPluginAssetPath |
144
+ | 重复写全部颜色 | 稀疏覆盖 = 只写差异键,未写继承 `:root`,更稳 |
145
+ | 想摆脱强调色 | 用**自己的 token**(如 `--toggle-on-bg`),不读 `--accent`([04 §6](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/04-两层调节与设置页.md)) |
146
+ | 大 blur 值 | `--glass-blur` 有性能上限(大面积 backdrop-filter 是 GPU 负担)——契约会写明数值([02 §2.3](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/02-变量契约.md) 待拍板) |
147
+
148
+ ## 4. 主题制作者能拿到什么
149
+
150
+ - 数据:`window.linkdesk.theme.listRecipes()`(含配色/预览色)——第三方 UI 也可以消费([06 §6](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/06-主题API契约.md) 待拍板 3:通用 API 优先复用)。
151
+ - 应用:`setRecipe`/`setColorway` 或直接写 `app.theme` 配置。
152
+ - 事件:`theme:changed`(payload 带 tokens),做实时联动。
153
+ - 混搭:你的主题按贡献的域(`RecipeMeta.domains`)自动出现在设置页混搭来源里,**作者零额外工作**([10 §2](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/10-混搭设计.md))。
154
+
155
+ ## 5. 迁移(现有主题插件——决策 F:零向后兼容)
156
+
157
+ 引擎**只读新格式**(`colorways[]`),旧格式平铺不再兼容读([05 §5](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/05-主题数据模型.md))。现有主题插件改造:
158
+
159
+ | 插件 | 现状 | 迁移后 |
160
+ |:--|:--|:--|
161
+ | `theme-defaults` | dark.json + light.json(平铺 colors) | 单配方 json:`colorways: [{id:"dark",…},{id:"light",…}]` |
162
+ | `theme-mint-soda` | 4 json(mint-soda/mint-dew/sea-salt-mint/lime-mint) | 1 配方 json = 4 colorways(theme 列表收 1 卡片,推荐) |
163
+ | `theme-twilight-forest` | 4 json(green/purple/sunset/teal) | 同上 → 1 配方 4 colorways |
164
+
165
+ 改造 = **纯数据编辑**(把 `colors` 包进 `colorways[]` 数组),不动引擎。合并后 theme 选择器列表更清爽(1 卡片多配色 vs N 卡片)。**迁移时顺手按 §2 ⓪ 目录规范归位**(json 入 `themes/`、资产入 `assets/`,平铺旧结构清零)。
166
+
167
+ ## 6. 关联
168
+
169
+ - schema 权威:[05-主题数据模型](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/05-主题数据模型.md)
170
+ - API 权威:[06-主题API契约](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/06-主题API契约.md)
171
+ - 主题外观文档包:[外观主题化 README](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/外观主题化/README.md)
172
+ - 插件一般规范:[06-plugin.json规范](06-plugin.json规范.md) / [03-插件contributes规范](03-插件contributes规范.md)
@@ -0,0 +1,74 @@
1
+ # README 说明区媒体契约
2
+
3
+ > 2026-09-09 ·文档化(70a-d 四形态实现全闭后补作者契约)。**写给第三方插件作者。**
4
+ > 这份文档回答一个问题:**你的 README 在 LinkDesk 软件里会被插件详情页展示——里面想放图 / 动图 / 演示视频,怎么写才对、有什么规矩。** 对标 VS Code 更新页 / 扩展 README 的开放展示画布。
5
+ > 性质 = **接口契约**——只定义「作者怎么写得对 + 会显示成什么样」,不写实现代码(实现面 = 壳共享 MarkdownView + 市场 DetailView)。作者不需要知道 App 怎么渲染,把下面几条写对即可。
6
+
7
+ ---
8
+
9
+ ## 一、你的 README 在哪展示、两种来源两套规矩
10
+
11
+ 插件根目录的 `README.md` 显示在**插件详情页的「详情」标签**里(该标签 = 截图画廊 + 这块 README 区域,README 区即项目常说的「说明区」)。详情页横向三个标签:**详情 / 功能 / 更改日志**,README 属「详情」这一格。**但同一份 README 有两种读到它的路,媒体显示能力不一样——这是最容易踩错的一条:**
12
+
13
+ | 态 | README 从哪来 | 相对路径媒体(随包资源) | https 绝对 URL 媒体 |
14
+ |:--|:--|:--:|:--:|
15
+ | **已装态**(用户下载安装 / 随壳发货后看详情) | 读**你打包进 zip 的那份** | ✅ 显示 | ✅ 显示 |
16
+ | **市场预览态**(未安装,列表/详情读目录条目的远程 README) | 读**远端 readmeUrl** | ❌ 不显示(诚实不显——此刻没有你的包内副本,无从解析) | ✅ 显示 |
17
+
18
+ > **含义:** 想让图/视频在「用户已装」后必然看到 → 用**相对路径放包内**(下 §三);想让图/视频连「还没装的浏览者」也看得到 → 用 **https 绝对 URL**。只放相对路径媒体 = 装了才见。
19
+
20
+ ---
21
+
22
+ ## 二、支持的媒体形态(四种,照抄即可用)
23
+
24
+ | 形态 | 作者怎么写(README markdown / 内嵌 HTML 均可) | 说明区行为 |
25
+ |:--|:--|:--|
26
+ | **静态图** | `![串口封面](resources/cover.svg)` 或 `<img src="resources/cover.svg" alt="串口封面">` | 显示。png / svg / webp / jpg / gif 通吃。**建议写 alt**(读屏友好,纯装饰图给空串) |
27
+ | **动图** | 同一行写法,放真动画 gif | 显示且**真会动**(跟静态图同链路) |
28
+ | **封面外链视频**(GitLens 式) | `<a href="https://youtube.com/…"><img src="resources/cover.svg" alt="点封面看演示"></a>` | 说明区显示为**可点封面**;点击 = **系统默认浏览器**打开外链页(App 内永不载外部页) |
29
+ | **页内视频**(VS Code 更新页式) | `<video src="resources/demo.mp4" controls poster="resources/cover.svg"></video>`<br>或 `<video controls><source src="resources/demo.mp4" type="video/mp4"></video>` | 说明区**就地播放**:有原生控制条、可拉进度条、可点全屏(一次点满屏、退出一次还原)。mp4 / webm / m4v |
30
+
31
+ > 任何 **https 外链文字链接**(`[看演示](https://…)`)同样:点击走系统默认浏览器。mailto: 走邮件客户端。**app 内从不弹窗载外部网页。**
32
+
33
+ ---
34
+
35
+ ## 三、图 / 视频文件放哪、src 怎么写(源规则)
36
+
37
+ 1. **写「相对路径 + 随包」**:媒体文件放**插件根目录的 `resources/`**,README 里写相对路径 `resources/cover.svg`。**SDK 构建自动把这些被 README 引用的资产打进 zip**(零声明,见 [04-插件分发格式.md](04-插件分发格式.md))→ 已装态必然显示。
38
+ 🔴 **媒体一律住 `resources/`**——图标同理(`plugin.json` 的 `icon` / `marketIcon` 也写 `resources/…`)。**插件根目录不放散图。**
39
+ 2. **远程 URL**:`https://…` 绝对地址直接可用(适合市场预览也显)。
40
+ 3. **别碰的**:`http:` / `data:` / `javascript:` / `file:` 图源**一律不显示**(安全白名单拒绝);`//` 开头的协议相对 URL 也不显示;**别引用包外**(`../` 上层目录、绝对盘路径)——既不随包也不显示。
41
+
42
+ > ℹ️ **技术上放插件根目录也能工作**(SDK 只看 README 里写了什么路径,不看目录)。**收口到 `resources/` 是规整性要求,不是正确性要求**——新插件跟齐官方范本的 `resources/` 写法即可。
43
+
44
+ ---
45
+
46
+ ## 四、渲染契约——哪些做不了,别指望(安全硬保证)
47
+
48
+ - **不能跑脚本。** README 是纯展示画布:`<script>`、事件属性(`onclick` 等)、`javascript:` 协议被消毒层**整枝剥除**——不是你没写对,是设计上就进不去。别用「README 里塞 JS 让详情页执行」的思路。
49
+ - **视频永不自动播。** `autoplay` 写了也无效(打开说明区绝不突然出声)。加载策略 = `preload: metadata`(不整片预下载,省带宽)。
50
+ - **控制条强制给。** 页内 `<video>` 你没写 `controls` 也会被加上(否则读者无从起播)。
51
+ - 危险 / 未知协议的链接整枝不落 DOM。
52
+
53
+ ---
54
+
55
+ ## 五、随包与发布纪律(改了内容要重发,否则用户看不到)
56
+
57
+ 1. **内容变更必 bump `plugin.json.version`**([04 §四](04-插件分发格式.md) 核心纪律):已装用户的副本**按版本固化**——软件只补缺失、永不刷新已装。你给 README 加了图 / 换了视频但没 bump → 已装用户永远看旧内容。README 动了 = 内容变更 = 必须 bump + 重新构建 zip。
58
+ 2. **zip 是一次构建产物,不自动重生。** SDK build(或主题类 `pack`)自动收集 README 引用资产随包——但**改了 README / 媒体 / 或动了 SDK 打包配置**(外部化清单等)后,磁盘上的旧 zip 不会自己变新;**必须重 build + 重发**。判据:装了新包仍不对 → 多半是 zip 本体陈旧 → 重建。
59
+ 3. **随壳发货的 bundled zip 同理**:重打 zip 必 bump;`npm run check` 的打包 gate 会在「同版本内容 diff」时红拦,别绕过。
60
+
61
+ ---
62
+
63
+ ## 六、活的样板(照抄不会错)
64
+
65
+ - 官方 8 只已嵌场景封面的插件 README = 现成范本:`editor` / `file-tree` / `serial-monitor` / `settings` / `python` / `theme-terminal` / `theme-aurora-glass` / `lang-defaults`(另有首个第三方真插件 `hello-linkdesk`)。看它们 README 顶部那张 `![…](resources/cover.svg)` 就是封面标准写法。
66
+ - 页内 `<video>` / 封面外链写法:串口监视器 README 的 git 历史 commit `2f9a52c6b`(页内真播)与 `8c9d71551`(全屏修复)各带一段当时手测用的完整 `<video>` / `<a><img></a>` 示例,验完即撤——要抄完整写法可看那两次提交。
67
+
68
+ ---
69
+
70
+ ## 相关
71
+
72
+ - [04-插件分发格式.md](04-插件分发格式.md)——zip 打包、内容变更 bump、`linkdesk://` 资源协议
73
+ - [09-插件目录规范.md](09-插件目录规范.md)——文件放哪
74
+ - 市场图标双字段 `marketIcon` / 封面 → [06-plugin.json规范](06-plugin.json规范.md)
@@ -0,0 +1,259 @@
1
+ # 插件开发指南——从零到上线
2
+
3
+ > 2026-09-12 ·。**这是一条动线,不是参考手册。** 每一步只说三件事:**做什么** / **怎么知道做对了** / **细节点哪一篇**。
4
+ > 字段含义、方法签名、规范条文一律**不在这里复述**——那些各有唯一真相源,跟着链接走。复述 = 制造第二份真相源 = 迟早跟正文打架。
5
+
6
+ | | |
7
+ |---|---|
8
+ | 读者 | 第一次写 LinkDesk 插件的人 |
9
+ | 形态 | 教程动线(从头顺序执行即可) |
10
+ | 不是 | API 参考(→ [01-插件API契约](01-插件API契约.md) + [plugin-sdk README 速查表](https://github.com/Encaron/linkdesk/blob/electron/packages/plugin-sdk/README.md#api-速查表))· 字段字典(→ [06-plugin.json规范](06-plugin.json规范.md))· 规范条文(→ [00-README](00-README.md) 索引) |
11
+ | 预计 | 第 1-3 步 10 分钟能看见自己的插件在跑 |
12
+
13
+ ---
14
+
15
+ ## 开写前——三条铁律
16
+
17
+ 违反这三条,插件**装得上但会坏**(甚至带崩壳)。先记住,比写完再改便宜得多:
18
+
19
+ 1. **只走 `window.linkdesk.*`**——禁止 `import` 壳内部(`@src/core/...`)。ESLint `noCoreImportInPlugin` 是 error 级,写下去就红。
20
+ 2. **颜色走 CSS 变量 `var(--xxx)`**——禁止硬编码 hex,否则主题切换时你的插件不跟随。
21
+ 3. **文案走 `t()`**——key 就是原文(中文插件用中文 key,中文自带兜底,英文译文放 `i18n/en.json`)。
22
+
23
+ > 全八条 + 适用范围 → [00-README §硬约束](00-README.md#硬约束写任何一行插件代码前)。
24
+
25
+ ---
26
+
27
+ ## 第 1 步:生成项目骨架
28
+
29
+ **做什么**
30
+
31
+ ```bash
32
+ npm create linkdesk-plugin my-cool-plugin # 名字必须 kebab-case(小写字母/数字/连字符)
33
+ cd my-cool-plugin
34
+ npm install
35
+ ```
36
+
37
+ 不带参数运行 `npm create linkdesk-plugin` 会交互式问插件名。
38
+
39
+ **怎么知道做对了**
40
+ 新目录里出现 `plugin.json` + `src/index.tsx`,且 `plugin.json` 里的 `{{pluginName}}` 之类占位符**已替换成你的真实插件名**(还有 `pluginId` / `name` / `description` / `author` 已填好,`author` 默认取 `git config user.name`)。CLI 会打印一行告诉你**建没建 git 仓**:建了的话 `git log` 里有一笔「初始骨架」提交、分支叫 `main`。
41
+
42
+ **细节点哪一篇**
43
+ [02-插件开发工具链/01-create-linkdesk-plugin脚手架.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/01-create-linkdesk-plugin脚手架.md)——生成产物的**逐文件契约**(每个文件为什么存在、占位符规则、15 个模板文件的角色)。**项目结构不要在这里找**,那篇是唯一真相源。
44
+
45
+ > ✅ **建仓(2026-09-14 已落地)**:脚手架**代建 git 仓**——照 `cargo new` 的三条语义,**不是「一律 `git init`」**:
46
+ > - 工程目录**不在任何 git 仓里** ⇒ 自动 `git init -b main` + **一次初始提交**(模板自带 `.gitignore`,所以你第一步看到的不是满屏 untracked);
47
+ > - 工程目录**已经在某个 git 仓里** ⇒ **不建**(防嵌套仓——比如你把插件生成在另一个已有仓库的子目录下);
48
+ > - **`--no-git`** ⇒ 一律不建(逃生口,对标 `cargo new --vcs none`)。
49
+ >
50
+ > CLI 会**明确打印**它到底建没建、为什么,别自己猜。🔴 **前提是脚手架的版本 ≥ 0.1.3**——旧版
51
+ > 既不会建仓、生成的工程也没有 CI(`npm create linkdesk-plugin` 默认取最新版)。
52
+ > 工程该放哪、仓该叫什么 → [15-多仓开发与本地工作区](15-多仓开发与本地工作区.md)。
53
+
54
+ ---
55
+
56
+ ## 第 2 步:跑起来,看见它
57
+
58
+ **做什么**
59
+
60
+ ```bash
61
+ npm run dev # = linkdesk-plugin-sdk dev
62
+ ```
63
+
64
+ **怎么知道做对了**
65
+ 浏览器自动打开 dev 宿主页,页面上是模板自带的 **「插件跑起来了 ✨」**。此时改 `src/index.tsx` 里的文字并保存,**页面即时变**(HMR,不用重启)。
66
+
67
+ **细节点哪一篇**
68
+ [02-本地预览环境.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/02-本地预览环境.md)——dev 宿主是什么、作者侧为什么零配置、HMR 边界。这一步**不开 LinkDesk 主程序**,只跑插件自己的预览宿主。
69
+
70
+ ---
71
+
72
+ ## 第 3 步:写你的第一段 UI
73
+
74
+ **做什么**
75
+ 改 `src/index.tsx` 里 `default export` 的那个 React 组件。壳就是这么渲染它的:
76
+
77
+ ```tsx
78
+ export default function HelloPlugin({ isActive }: { isActive: boolean }) { … }
79
+ ```
80
+
81
+ - `isActive` = 本标签页当前是否聚焦。**keep-alive 架构下所有标签页始终挂载**——别用 `isActive` 整块 blank 掉内容,它只配用来 gate「聚焦才该跑的副作用」(如自动保存、轮询)。
82
+ - `tabId` / `sourceId` = 本标签 id / 上下文数据(编辑器类插件靠 `sourceId` 知道用户打开了哪个文件)。
83
+
84
+ **怎么知道做对了**
85
+ 预览宿主里 UI 随你改。**并且**:界面里没有任何裸 hex 颜色、没有硬编码中文(用 `t()`)——这两条肉眼可查,也是后面 `npm run lint` 会拦的。
86
+
87
+ **细节点哪几篇**
88
+ - 视图契约细节 → [05-插件UI写法规约](05-插件UI写法规约.md)(右键菜单/浮层/持久化/快捷键两轨道)
89
+ - 想放进侧栏或底部面板 → [08-ViewContainer-视图容器API](08-ViewContainer-视图容器API.md)
90
+
91
+ ---
92
+
93
+ ## 第 4 步:调一个 API
94
+
95
+ **做什么**
96
+ `window.linkdesk.` 后面能接什么,看**速查表**(45 个命名空间 / 242 个方法,从契约自动生成):
97
+
98
+ - 👉 [plugin-sdk README §API 速查表](https://github.com/Encaron/linkdesk/blob/electron/packages/plugin-sdk/README.md#api-速查表)
99
+ - 完整签名与逐方法说明 → `node_modules/@linkdesk/contracts/linkdesk.d.ts`(IDE 里能直接跳转)
100
+
101
+ 例:读一个配置项、订一个变更。
102
+
103
+ ```ts
104
+ const theme = await window.linkdesk.theme.getCurrent();
105
+ const dispose = window.linkdesk.configuration.onChange("my-plugin.greeting", (v) => { … });
106
+ ```
107
+
108
+ **怎么知道做对了**
109
+ TypeScript 编译通过就是对的——`window.linkdesk.*` 的类型随 SDK 注入(`tsconfig.json` 的 `types` 已配好),**方法名拼错、参数类型不对,`tsc` 当场红**。这是契约给作者的免费防线。
110
+
111
+ **细节点哪几篇**
112
+ - 哪些面在池/壳哪一侧可用、`?` 标法什么意思 → [01-插件API契约 §三 唯一真相源](01-插件API契约.md)
113
+ - ⚠️ **速查表里带 `°` 的方法**(契约标 `?`)只在一侧 preload 注入,**多数是壳侧独有**——你的插件跑在池里,调之前先判存在。
114
+ - 插件间怎么传数据 → [07-插件间通信](07-插件间通信.md)(事件广播 / 命令调用 / 数据管道)
115
+
116
+ ---
117
+
118
+ ## 第 5 步:声明贡献点(命令 / 菜单 / 快捷键 / 配置 / 标签页 / i18n)
119
+
120
+ **做什么**
121
+ 在 `plugin.json` 的 `contributes` 里声明。命令、菜单项、快捷键、配置项、视图、主题、i18n、顶栏按钮**全在这里登记**。
122
+
123
+ **怎么知道做对了**
124
+
125
+ ```bash
126
+ npm run validate # 校验 plugin.json:$schema / 字段合法性 / i18n 文件存在
127
+ ```
128
+
129
+ 输出无错即通过。声明了命令 → 按 `Ctrl+Shift+P` 能在命令面板里搜到它;声明了配置项 → 设置页出现该项。
130
+
131
+ **细节点哪几篇**
132
+ - 每种贡献点的完整写法与示例 → [03-插件contributes规范](03-插件contributes规范.md)(**最厚的一篇,按你要做的点查**)
133
+ - 每个字段的含义/类型/默认值 → [06-plugin.json规范](06-plugin.json规范.md)
134
+ - 生命周期(注册→激活→运行→卸载)→ [02-插件生命周期](02-插件生命周期.md)
135
+
136
+ ---
137
+
138
+ ## 第 6 步:用共享组件(别自己造右键菜单)
139
+
140
+ **做什么**
141
+
142
+ ```bash
143
+ npm i @linkdesk/ui
144
+ ```
145
+
146
+ 右键菜单、下拉、开关这类控件走共享包——**玻璃/主题自动跟随**,不用自己调样式。
147
+
148
+ **怎么知道做对了**
149
+ 切换主题时你的右键菜单外观跟着变(自造的实现通常不会)。仓库硬约束 3 明确:手写右键菜单是违规的。
150
+
151
+ **细节点哪一篇**
152
+ [05-插件UI写法规约](05-插件UI写法规约.md) + [19-组件速查](19-组件速查.md)
153
+
154
+ ---
155
+
156
+ ## 第 7 步:装进真的 LinkDesk 里验证
157
+
158
+ **做什么**
159
+ 预览宿主毕竟不是真壳。要确认真机行为(真串口、真文件、真窗口):
160
+
161
+ ```bash
162
+ npm run dev:real # = linkdesk-plugin-sdk dev --real
163
+ ```
164
+
165
+ **怎么知道做对了**
166
+ LinkDesk 主程序里能看到你的插件、行为与预览一致。**注意一个边界**:安装态插件跑的是**预构建 bundle**,改了源码必须重 build 才生效——这不是 bug,是分发纪律。
167
+
168
+ **细节点哪一篇**
169
+ [04-作者真机调试环.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/04-作者真机调试环.md)——真机环怎么自动化「重 build + 直写」,以及为什么安装态改 bundle 不算热更。
170
+
171
+ ---
172
+
173
+ ## 第 8 步:打包分发给别人
174
+
175
+ **做什么**
176
+
177
+ ```bash
178
+ npm run build
179
+ ```
180
+
181
+ **怎么知道做对了**
182
+ 项目根出现**一个** `<pluginId>.linkdesk-plugin` 单文件(zip),外加 `dist/<pluginId>.linkdesk-plugin/` 解包目录。把这个单文件给别人,对方就能装。
183
+
184
+ ⚠️ **别把源码目录当分发载体**——「整目录复制即安装」的时代已结束。而且 `plugin.json` 的 `version` 一旦 +1,**必须同笔在 `CHANGELOG.md` 补一段 `## v<新版本>(YYYY-MM-DD)`**,否则插件详情页会显示「此版本未提供变更说明」。
185
+
186
+ **细节点哪几篇**
187
+ - 分发格式与安装流程 → [04-插件分发格式](04-插件分发格式.md)
188
+ - zip 内部的字节级格式规范 → [01-插件独立构建/02-linkdesk-plugin格式规范.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/01-插件独立构建/02-linkdesk-plugin格式规范.md)
189
+ - README 里放图/动图/视频的规则 → [12-README说明区媒体契约](12-README说明区媒体契约.md)
190
+
191
+ ---
192
+
193
+ ## 第 9 步:上架市场
194
+
195
+ > 🔴 **先破一个最常见的误解:上架是「两步」,`npm run publish` 只是第一步的半程。**
196
+ >
197
+ > | 步 | 做什么 | 做完之后谁看得见 |
198
+ > |:--:|------|------|
199
+ > | **①** | `npm run publish`——发布到你**自己**的 GitHub 仓(Release 资产 + 仓库根 `marketplace.json`) | **只有手动把你的仓库地址加进「市场源」的人**。默认用户**看不见** |
200
+ > | **②** | **把你的插件收录进官方目录** `Encaron/linkdesk-marketplace`(往目录的 `marketplace.json` 提一个条目 PR) | **所有默认配置的用户**——这一步才是真正的「上架」 |
201
+ >
202
+ > 「我跑了 publish,怎么市场上搜不到」= 卡在第二步。完整口径(含官方目录收录怎么提)→ [04-插件分发格式](04-插件分发格式.md)。
203
+
204
+ **做什么**
205
+
206
+ ```bash
207
+ npm run publish # = linkdesk-plugin-sdk publish —— 第 ① 步
208
+ ```
209
+
210
+ **前置——工程必须已是推到 GitHub 的 git 仓库**
211
+
212
+ publish 的目标仓库 = 你工程的 git remote `origin`(发布到**你自己的** GitHub 仓:Release 资产 + 仓库根 `marketplace.json`;多市场源模型)。跑之前 `git remote -v` 确认 origin 指向你的 GitHub 仓。
213
+
214
+ > ✅ **现状(2026-09-14 已落地)**:脚手架**已代建 git 仓**(`main` 分支 + 一次初始提交,见第 1 步)⇒ 推到 GitHub **只剩两条**,别人常说的三条里 `git init` 那条已经不需要了:
215
+ >
216
+ > ```bash
217
+ > git remote add origin git@github.com:<你>/<仓>.git
218
+ > git push -u origin main
219
+ > ```
220
+ >
221
+ > 什么时候仍需自己 `git init`:生成时带了 `--no-git`,或工程被生成在**另一个 git 仓里**(那时脚手架按 `cargo new` 语义刻意不建嵌套仓)。
222
+
223
+ **怎么知道做对了**
224
+ 第一步:GitHub Release 上出现你的 `.linkdesk-plugin` 资产;第二步:官方目录出现你的条目后,**在一台干净机器(默认配置、不加任何市场源)**上市场里搜得到、能装、能更新——这才是「上架完成」的判据。
225
+
226
+ **细节点哪几篇**
227
+ - 完整链路(本地 → GitHub → 用户电脑)→ [03-插件发布流水线.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/03-插件发布流水线.md)
228
+ - 作者视角的端到端旅程 → [05-文档与发布/00-第三方作者旅程.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/05-文档与发布/00-第三方作者旅程.md)
229
+
230
+ ---
231
+
232
+ ## 新手最常踩的坑
233
+
234
+ | 症状 | 病根 | 去哪看 |
235
+ |---|---|---|
236
+ | 主题一换,我的界面颜色不跟随 | 硬编码了 hex | 铁律 2 · [00-README](00-README.md#硬约束写任何一行插件代码前) |
237
+ | 切走标签页再切回来,状态丢了/内容空了 | 用 `isActive` 条件渲染了——keep-alive 下不该卸载 | [05-插件UI写法规约](05-插件UI写法规约.md) |
238
+ | `npm run build` 后装上去还是旧行为 | 安装态跑预构建 bundle,改源码要重 build | 第 7 步 · [04-作者真机调试环.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/04-作者真机调试环.md) |
239
+ | 详情页说「此版本未提供变更说明」 | 版本 +1 了但 `CHANGELOG.md` 没补新段 | 第 8 步 |
240
+ | 插件详情页说明区不显示 | 说明以 `README.md` 文件为准,**`plugin.json` 里没有 `readme` 字段** | [09-插件目录规范](09-插件目录规范.md) · [06-plugin.json规范](06-plugin.json规范.md) |
241
+ | 右键菜单样式跟壳对不上 | 手写了右键菜单 | 第 6 步 · [05-插件UI写法规约](05-插件UI写法规约.md) |
242
+ | `import @src/core/xxx` 报错 | 这是壳内部实现,插件不得 import | 铁律 1 |
243
+
244
+ ---
245
+
246
+ ## 文档地图(按你要干的事找)
247
+
248
+ | 想干什么 | 读这篇 |
249
+ |---|---|
250
+ | 知道**能调什么 API** | [01-插件API契约](01-插件API契约.md) + [SDK README 速查表](https://github.com/Encaron/linkdesk/blob/electron/packages/plugin-sdk/README.md#api-速查表) |
251
+ | 查**某个字段**什么意思 | [06-plugin.json规范](06-plugin.json规范.md) + `plugin.schema.json` |
252
+ | 注册**命令/菜单/快捷键/配置/视图/主题/i18n** | [03-插件contributes规范](03-插件contributes规范.md) |
253
+ | 理解**插件什么时候被激活/卸载** | [02-插件生命周期](02-插件生命周期.md) |
254
+ | **插件之间**传数据 | [07-插件间通信](07-插件间通信.md) |
255
+ | **侧栏/面板视图**、往别人容器里加东西 | [08-ViewContainer-视图容器API](08-ViewContainer-视图容器API.md) |
256
+ | 整套**替代设置 UI** | [10-如何造一个设置插件](10-如何造一个设置插件.md) |
257
+ | 做**主题/图标** | [11-主题制作](11-主题制作.md) |
258
+ | 文件**该放哪**、README/CHANGELOG 权威判据 | [09-插件目录规范](09-插件目录规范.md) |
259
+ | 全部文档索引 | [00-README §文档索引](00-README.md#文档索引) |