@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/09-/346/217/222/344/273/266/347/233/256/345/275/225/350/247/204/350/214/203.md
ADDED
|
@@ -0,0 +1,301 @@
|
|
|
1
|
+
# 插件目录结构规范
|
|
2
|
+
|
|
3
|
+
> 2026-08-05。**官方插件模板——第三方开发者看任一官方插件,目录结构一致。**
|
|
4
|
+
> **2026-09-06 与实现对齐核对**(对账):塌平单根(无 plugins/{builtin,user})· 共享控件走 @linkdesk/ui · 分发 = .linkdesk-plugin zip。本页对应机制引用已清。
|
|
5
|
+
> 🔥 **2026-09-11补三块**:① **每类文件的「行数上限」列**(此前本文档只管目录语义、不管多大算大——插件体量实际处于「规范说不管、门禁也不管」的双空白);② **`hooks/` 目录 + `utils/` 边界细则**;③ **`__tests__/` 的路径镜像语义写死**。**上限的机械执行 = `npm run check` 的体积门禁**(本节的表就是权威)。
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 标准目录结构
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
my-plugin/
|
|
13
|
+
├─ plugin.json # 插件声明——唯一必选文件
|
|
14
|
+
├─ icon.svg # 插件图标(可选)——根目录 或 resources/,由 plugin.json `icon` 字段声明
|
|
15
|
+
├─ README.md # 插件说明——详情页「详情」页签的数据源(强烈建议提供)
|
|
16
|
+
├─ CHANGELOG.md # 更新日志——详情页「更改日志」页签的唯一真源(强烈建议提供)
|
|
17
|
+
├─ i18n/ # 翻译文件——每种语言一个 JSON(可选)
|
|
18
|
+
│ └─ en.json # key=原文, value=译文
|
|
19
|
+
├─ resources/ # 静态资源——图标/字体/图片(可选——相对路径声明,壳解析)
|
|
20
|
+
│ └─ icon.png
|
|
21
|
+
└─ src/
|
|
22
|
+
├─ index.tsx # 入口——export default React 组件(≤120 行,薄门面)
|
|
23
|
+
├─ views/ # 页面级组件——每个对应一个 ViewContainer 视图(≤150 行)
|
|
24
|
+
│ ├─ MainView.tsx
|
|
25
|
+
│ └─ SettingsView.tsx
|
|
26
|
+
├─ components/ # 可复用 UI 组件——被 views/ 或外部引用(≤150 行)
|
|
27
|
+
│ └─ Toolbar.tsx
|
|
28
|
+
├─ hooks/ # React hook——use* 前缀,一个文件一个 hook(≤150 行)
|
|
29
|
+
│ └─ useToolbarState.ts
|
|
30
|
+
├─ services/ # 业务逻辑——数据模型、状态管理、API 封装(≤200 行)
|
|
31
|
+
│ ├─ model.ts
|
|
32
|
+
│ └─ api.ts
|
|
33
|
+
├─ utils/ # 纯函数工具——无副作用、无实例状态(≤150 行)
|
|
34
|
+
│ └─ format.ts
|
|
35
|
+
├─ styles/ # CSS 文件——每个视图/组件一个 .css,不内联(≤300 行)
|
|
36
|
+
│ ├─ MainView.css
|
|
37
|
+
│ └─ Toolbar.css
|
|
38
|
+
└─ __tests__/ # 测试——与被测文件同名 + .test 后缀,保持相同相对路径
|
|
39
|
+
├─ services/
|
|
40
|
+
│ └─ model.test.ts
|
|
41
|
+
└─ views/
|
|
42
|
+
└─ MainView.test.tsx
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## `README.md` / `CHANGELOG.md`——说明与更新日志
|
|
46
|
+
|
|
47
|
+
> 🔥 **2026-09-11**。**此前本文档一个字都没提这两个文件**,于是「补说明 / 补日志」这类事**没有权威判据**。这一节就是那把尺子。
|
|
48
|
+
|
|
49
|
+
### 分工与读者
|
|
50
|
+
|
|
51
|
+
| 文件 | 喂给谁 | 缺了会怎样 |
|
|
52
|
+
|:--|:--|:--|
|
|
53
|
+
| **`README.md`** | 插件详情页「**详情**」页签(Markdown 渲染,支持图 / 视频 / 外链——见 [12-README说明区媒体契约](12-README说明区媒体契约.md)) | 详情页**只剩一句 `description`** |
|
|
54
|
+
| **`CHANGELOG.md`** | 插件详情页「**更改日志**」页签 | 该页签显示**「该插件未附带更改日志」** |
|
|
55
|
+
|
|
56
|
+
### 位置固定——放插件根目录,不声明路径
|
|
57
|
+
|
|
58
|
+
两者都放**插件根目录**(与 `plugin.json` 同级),**文件名固定**。**不写进 `plugin.json`、不看任何字段**——读取方按**固定文件名**读包内文件。
|
|
59
|
+
|
|
60
|
+
> 🔴 **为什么把这条写死**:`plugin.json` 曾经有过 `readme` / `changelog` 两个字段,但**从无读取方**(读取方直接读 `README.md` / `CHANGELOG.md` 这两个**文件名**)。留着它 = 留一个**骗人的写法**。**2026-09-11 已删除** ⇒ **见到任何「在 `plugin.json` 里记说明 / 记更新日志」的写法,都是过期资料。**
|
|
61
|
+
|
|
62
|
+
### `CHANGELOG.md` 的格式约定
|
|
63
|
+
|
|
64
|
+
SDK `publish` 要从它**切段**填目录条目,所以**段标题格式有约束**:
|
|
65
|
+
|
|
66
|
+
```markdown
|
|
67
|
+
# 更新日志 ← 文档标题(内容自由)
|
|
68
|
+
|
|
69
|
+
## v1.0.0(2026-09-11) ← 🔴 版本段标题:`## v<版本号>`
|
|
70
|
+
- 修了某某问题
|
|
71
|
+
- 加了某个能力
|
|
72
|
+
|
|
73
|
+
## v0.9.0(2026-08-01) ← 旧版本往下排,最新在最上
|
|
74
|
+
- …
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
- **段标题必须能解析出版本号**——`## v1.0.0…` / `## 1.0.0…` 都认(`v` 可省),**版本号严格等于 `plugin.json` 的 `version`**。
|
|
78
|
+
- **解析不出版本号 → 该版本的目录条目留空**(**诚实留空,不猜**)。
|
|
79
|
+
- **日期写在标题行括号里**(`(2026-09-11)`)——**只用于展示**。
|
|
80
|
+
- **标题之外的正文 = 该版本的变更说明**——Markdown 原文照搬,不做二次解析。
|
|
81
|
+
- **版本倒序**(最新在最上)——详情页按此顺序渲染。
|
|
82
|
+
|
|
83
|
+
### 🔴 「一个概念一处表达」铁律
|
|
84
|
+
|
|
85
|
+
> **`plugin.json` 里没有 `changelog` / `readme` 字段,也不会有。**
|
|
86
|
+
> 更改日志**只**写 `CHANGELOG.md`;说明**只**写 `README.md`——同一件事**只有一个住处**。
|
|
87
|
+
|
|
88
|
+
这条要**显式写下来**:旧写法在旧提交、旧文档、旧插件里还有残影,**不写清楚,下一个人会照着抄回去**。
|
|
89
|
+
|
|
90
|
+
### 与版本号联动
|
|
91
|
+
|
|
92
|
+
改 `README.md` / `CHANGELOG.md` 的内容 **= 内容变更 = 必须 bump `plugin.json.version`**,并重新构建分发件——已装用户的副本**按版本固化**,软件只补缺失、永不刷新已装(详见 [04-插件分发格式 §四](04-插件分发格式.md))。
|
|
93
|
+
|
|
94
|
+
**`version` 是四处的锚**:`CHANGELOG.md` 段标题的版本号 ↔ `plugin.json.version` ↔ 目录条目 `versions[].version` ↔ `package.json.version`——**四处同源**。
|
|
95
|
+
|
|
96
|
+
> 第四处(`package.json.version`)是新纳入的:插件源码搬进各自独立的仓之后,`package.json` 是新人(和 AI)打开仓库**第一眼看到的东西**——两个版本号并存且不一致,必然有人 bump 错那一个,而发布链路与内容指纹门禁读的都是 `plugin.json.version` ⇒ **改错的那个 = 静默无效**。机械兜底 = `scripts/check-plugin-version-sync.mjs`(挂在 `npm run check`,带负控)。
|
|
97
|
+
|
|
98
|
+
---
|
|
99
|
+
|
|
100
|
+
**⚠️ 插件源码目录不产生构建产物(Vite 开发 chunk 是构建内部物,不落 `dist/`)。** 分发物 = 用 plugin-sdk 构建的单文件 `<id>.linkdesk-plugin` zip(内含 `index.bundle.js` + `views/*.bundle.js` + 改写后的 plugin.json,loader 检测到 `index.bundle.js` 即以 bundle 为入口)——作者不需要关心构建产物,只管上面的源码结构;分发细节见 [04-插件分发格式](04-插件分发格式.md)。
|
|
101
|
+
|
|
102
|
+
## 源码位置与分发物的关系
|
|
103
|
+
|
|
104
|
+
> 🔥 **2026-09-14**。本节回答一个此前从没被写下来的问题:**插件源码住在哪个仓库?** 本地目录怎么摆、仓库怎么建 → [15-多仓开发与本地工作区](15-多仓开发与本地工作区.md)。
|
|
105
|
+
|
|
106
|
+
1. **源码真相源 = 插件自己的仓库**(`github.com/<owner>/<repo>`),**不是壳仓**。壳仓内的 `plugins/` 只允许两类东西:**夹具**(不发货的 demo,如 `panel-demo`)与**构建产物**(`bundled-plugins/<id>.linkdesk-plugin`)。
|
|
107
|
+
2. **壳仓 `bundled-plugins/<id>.linkdesk-plugin` 的语义 = 出厂发货用的种子快照**,其版本由 `bundled-plugins.lock.json` 记账(第 7.4 轮产出)。它**不是源码的第二份拷贝**——源码改了必须回插件仓改,改完走发布链路刷新种子。
|
|
108
|
+
3. **从源码到用户桌面的链路**:插件仓 → `npm run build` → `<id>.linkdesk-plugin`(zip)→ GitHub Release asset → catalog 条目 → 用户安装。**没有一步经过壳仓。**
|
|
109
|
+
4. **插件身份(id)永不可变**;显示名(`name`)可改;仓库名可改——三分规则与全部命名判据 → [16-命名规范](16-命名规范.md)。
|
|
110
|
+
5. **插件内有且只有一处版本号真源 = `plugin.json.version`**。`package.json.version` 不是真源,但必须与它相等(版本号「四处同源」,N6——见 [16-命名规范 §5.1](16-命名规范.md))。
|
|
111
|
+
|
|
112
|
+
**与 `publish` 实现的对账**(规范不许与工具相反):发布目标仓库 = 工程 git remote `origin`(`packages/plugin-sdk/src/publish.ts` 的 `getCurrentRepoRemote`,非 git / 无 origin 直接报错);catalog 写到**仓库根 `marketplace.json`**(Contents API 读改写);`readmeUrl` / `versions[].changelog` 由 publish 从工程根 `README.md` / `CHANGELOG.md` 自动填写。
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
## 静态资源与图标
|
|
117
|
+
|
|
118
|
+
**图标位置:** 插件根目录 或 `resources/`——由 `plugin.json` 的 `icon` 字段声明。裸字符串 = 内置图标集(codicon 名 / `iconSource:"lucide"` 白名单名),如 `"icon": "FolderTree"`;路径 = 相对插件目录的文件,如 `"icon": "resources/icon.png"`(serial-monitor 官方用法)。
|
|
119
|
+
|
|
120
|
+
> ℹ️ **规范收口**:新插件把图标与媒体**一律放 `resources/`**(见 [12-README说明区媒体契约 §三](12-README说明区媒体契约.md))。「根目录也行」是**技术事实**(壳按你声明的相对路径解析),**不是推荐写法**——官方范本统一用 `resources/`,跟齐即可。
|
|
121
|
+
|
|
122
|
+
**读取资源(作者视角 = 只声明相对路径,壳解析):** plugin.json 声明字段里出现的资源路径(`icon` / `contributes.views[].render` / 主题配方 json 的 `assets/...`)一律写**相对插件目录**——壳在加载/渲染时经 `getPluginAssetPath(pluginId, path)` 解析成当前协议下的绝对 URL(dev `http://localhost:1420` 与打包后 `file://` 通吃)。**作者不 import 任何路径工具、不手拼 URL**(硬约束 12 禁的是作者手写 `/assets/...`、`/resources/...` 等绝对路径字面量——打包后 file:// 下全炸,dev 能工作只是巧合)。
|
|
123
|
+
|
|
124
|
+
```
|
|
125
|
+
resources/
|
|
126
|
+
├─ icon.svg # 插件图标——plugin.json icon 字段指向
|
|
127
|
+
├─ logo.png # 详情页/市场横幅图
|
|
128
|
+
└─ manual.html # 附带文档(`docs` 字段指向)
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
## 主题插件目录(themes/ + assets/——禁平铺根目录)
|
|
134
|
+
|
|
135
|
+
> 主题 = 纯数据插件(`contributes.themes` 声明 + 配方 json + 资产),通常**不产 `src/` 代码**。目录规范权威:[11-主题制作](11-主题制作.md) §2 ⓪。
|
|
136
|
+
|
|
137
|
+
```
|
|
138
|
+
theme-myglass/
|
|
139
|
+
├─ plugin.json # contributes.themes 声明——配方 json 路径指向 themes/ 下
|
|
140
|
+
├─ themes/ # 配方 json 唯一住处——禁止平铺在插件根目录
|
|
141
|
+
│ └─ myglass.json
|
|
142
|
+
├─ assets/ # 字体(woff2/ttf)+ 背景图(png/jpeg/webp)——json 相对路径
|
|
143
|
+
│ ├─ MyFont.woff2
|
|
144
|
+
│ └─ bg.png
|
|
145
|
+
└─ resources/ # 插件图标等(上方通用约定)
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
| 目录 | 放什么 | 规则 |
|
|
149
|
+
|:--|:--|:--|
|
|
150
|
+
| `themes/` | 配方 json(`appearance` + `colorways[]`) | **禁止平铺根目录**;`contributes.themes[].path` 指向;一个插件可多个配方 json |
|
|
151
|
+
| `assets/` | 字体/背景图 | json 写相对路径 `assets/...` → 壳 `getPluginAssetPath` 解析;禁绝对路径(硬约束 12) |
|
|
152
|
+
| `resources/` | 插件图标 | 通用约定(上方「静态资源与图标」) |
|
|
153
|
+
|
|
154
|
+
主题作者带 `src/`(如自定义 UI/脚本)时按通用结构走——纯数据主题没有 `src/`。
|
|
155
|
+
|
|
156
|
+
---
|
|
157
|
+
|
|
158
|
+
## 每类文件的判断标准
|
|
159
|
+
|
|
160
|
+
> 🔥 **2026-09-11补「行数上限」列**。**上限由 `npm run check` 里的体积门禁机械执行**——本节的表就是作者的第一手依据。**超限必拆**(走 feature-folder,见下)。
|
|
161
|
+
|
|
162
|
+
| 目录 | 放什么 | 不放什么 | 行数上限 |
|
|
163
|
+
|:--|:--|:--|--:|
|
|
164
|
+
| **views/** | 页面级 React 组件——有独立路由或 ViewContainer 入口 | 工具栏按钮、状态栏条目(→ components/) | ≤150 |
|
|
165
|
+
| **components/** | 可复用 UI 组件——被多处引用的无状态/弱状态组件 | 直接操作文件系统的逻辑(→ services/) | ≤150 |
|
|
166
|
+
| **hooks/** | React hook——`use*` 前缀,**一个文件一个 hook** | 组件(→ components/)、service(→ services/) | ≤150 |
|
|
167
|
+
| **services/** | 业务逻辑、数据模型、API 封装 | JSX 渲染代码(→ views/ 或 components/) | ≤200 |
|
|
168
|
+
| **utils/** | 纯函数工具——无副作用、与 UI/业务无关的通用函数(格式化/解析/数学) | 有状态/有副作用逻辑(→ services/);React hook(→ hooks/) | ≤150 |
|
|
169
|
+
| **styles/** | 独立 .css 文件——每个视图/组件一个 | 内联 style(禁止手写——走 CSS 变量) | ≤300 |
|
|
170
|
+
| **resources/** | 静态资源——图标/字体/图片/文档(相对路径声明,壳解析) | 会被 import 的模块(→ src/) | — |
|
|
171
|
+
| **`src/` 根单件** | 跨层共享的类型定义(`types.ts`)/ 常量(`constants.ts`) | 有逻辑的模块(→ 各 role 夹) | ≤150 |
|
|
172
|
+
| **`src/index.tsx`** | 插件 entry(薄门面,注册贡献点) | — | ≤120 |
|
|
173
|
+
| **__tests__/** | Vitest 测试——`<被测文件名>.test.ts(x)` | 测试辅助工具(→ `__tests__/helpers/`) | 不限(>1000 行按 describe 组拆同夹多文件) |
|
|
174
|
+
|
|
175
|
+
🔴 **上表是你自己写的目录**(`views`/`components`/`hooks`/`services`/`utils`/`styles`)。**另建顶层目录 = 门禁当场报错**(fail-loud:「未知 role 夹」)——这不是拦你,是**逼你显式说清「这是什么角色、该给多少行」**。诚实的做法是**登记**(例:serial-monitor 的 `cm6/` = CodeMirror 纯逻辑域,登记为 150 档),**不是**把代码挪进 `utils/` 去凑表。**这条加进规范前,先想清楚它是不是真的一类新东西。**
|
|
176
|
+
|
|
177
|
+
🔴 **`.css` 一律 300,不看它放在哪个目录**——组件自带样式(co-located,如 `views/SettingsView.css`)与 `styles/` 下的 CSS 用同一把尺。
|
|
178
|
+
|
|
179
|
+
🔴 **聚合器档(上限 ×2)——两形**:门面长什么样,取决于它有没有「basename 约束」。
|
|
180
|
+
|
|
181
|
+
| 形 | 长什么样 | 谁用 |
|
|
182
|
+
|:--|:--|:--|
|
|
183
|
+
| **(a) 夹旁散门面** | 文件 `X.ts(x)` 旁边**存在同名夹 `X/`** | `views/`——文件名 = `contributes.views[].render`,**改名即改产物** ⇒ 门面只能留在夹旁、只能叫原名 |
|
|
184
|
+
| **(b) 夹内入口** | 路径是 **`<roleDir>/<Feature>/index.ts(x)`** | `services/` / `components/` / `hooks/` / `utils/`——服务名/组件名不是任何声明字段(**无 basename 约束**)⇒ 门面就是夹的入口,根目录不留额外散件 |
|
|
185
|
+
|
|
186
|
+
两形都按本档 **×2** 计(`views`/`components`/`hooks`/`utils`→300 · `services`→400)。**这是上限放宽不是目标值**——门面仍应尽量薄,且**不许含纯逻辑**(纯函数/数据变换/类型必须下沉子模块)。
|
|
187
|
+
|
|
188
|
+
> ⚠️ **别把「同名夹」当成唯一判据**——你在 `services/` 下建 `services/foo/index.ts` + 子模块时,**门禁认它是聚合器**(形 b)。反过来,`views/` 下**不要**把门面改叫 `index.tsx`——那会改掉 `render` 指向的名字。
|
|
189
|
+
|
|
190
|
+
> **超限处置**:走 **feature-folder(同名夹 = 聚合器 + 子模块)**——门面保留原路径原文件名(**外部 import 零变更**),子模块进同名夹。**禁止拆成同 domain 平铺多文件。**
|
|
191
|
+
|
|
192
|
+
> 🔔 **夹宽黄灯(阈值 12)——只提醒,不阻断**:**一个夹的直接子项(文件 + 子夹)超过 12 个**时,`npm run check` 会打一条提醒(**`check` 照样绿**)。它不拦你,只逼你**看一眼 + 给一句理由**。**别为了消灯去建 3 文件的碎片夹**——那比平铺更糟。一个夹很宽==往往说明里面藏着两三个不同的功能域,值得一读。
|
|
193
|
+
>
|
|
194
|
+
> 📌 **门禁怎么读**:收尾那行会打出当前生效的档位(`档 A … ;档 B plugins/<id>/src 按角色表 · 档 C entry ≤120`)。**若哪天插件档被关掉,那行会变成 `⚠️ 插件档已关闭——插件域当前无人看管`**——所以「门禁在不在岗」是**看输出就知道**的,不用去读脚本。
|
|
195
|
+
|
|
196
|
+
### 判断流程
|
|
197
|
+
|
|
198
|
+
```
|
|
199
|
+
这个文件包含 JSX/React 渲染?
|
|
200
|
+
├─ 是 → 它是对应一个 ViewContainer 的页面吗?
|
|
201
|
+
│ ├─ 是 → views/
|
|
202
|
+
│ └─ 否 → components/
|
|
203
|
+
└─ 否 → 它是 React hook(use* 前缀)吗?
|
|
204
|
+
├─ 是 → hooks/(一个文件一个 hook)
|
|
205
|
+
└─ 否 → 它操作数据/状态/文件/网络吗?
|
|
206
|
+
├─ 是 → services/(有副作用)
|
|
207
|
+
└─ 否 → 它是纯函数(无状态无副作用)吗?
|
|
208
|
+
├─ 是 → utils/
|
|
209
|
+
└─ 否 → 它是 CSS 吗?
|
|
210
|
+
└─ 是 → 跟它服务的视图/组件放一起(co-located 合法),
|
|
211
|
+
否则放 styles/。**门禁按扩展名管(恒 300),
|
|
212
|
+
不看它放在哪个目录**
|
|
213
|
+
├─ 是 → __tests__/
|
|
214
|
+
└─ 否 → src/(根目录,特殊情况)
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
### 🔴 `utils/` 与 `services/`、`hooks/` 的边界(2026-09-11补)
|
|
218
|
+
|
|
219
|
+
`utils/` 只收**纯函数**——无实例状态、无副作用、不碰 React。**两条机械判据**:
|
|
220
|
+
|
|
221
|
+
- **有实例状态 / 有副作用**(持有 `Map`/`Set`/缓冲区、读写盘、发 IPC、维护单例)→ **不进 `utils/`,进 `services/`**。
|
|
222
|
+
- **是 React hook(`use*`)** → **不进 `utils/`,进 `hooks/`**。
|
|
223
|
+
|
|
224
|
+
> **实况教训**:`serial-monitor/src/utils/` 里曾同时躺着 `RingBuffer.ts`(**有状态的类**)与 `useSendData.ts`(**React hook**)——两个都不该在 `utils/`。这条边界以前没写死,作者只能靠猜。
|
|
225
|
+
|
|
226
|
+
### 🔴 `__tests__/` 的路径与命名(2026-09-11明确化)
|
|
227
|
+
|
|
228
|
+
**`__tests__/` 是插件层约定,一律使用**——壳层测试走壳自己的结构(`src/**/` 与壳代码同夹紧邻),**插件不采用同夹紧邻**(那是壳层做法)。插件测试用 Vitest。
|
|
229
|
+
|
|
230
|
+
**命名**:`<被测文件名>.test.ts(x)`——**`__tests__/` 内保持与被测文件相同的相对路径**:
|
|
231
|
+
|
|
232
|
+
```
|
|
233
|
+
src/services/model.ts → src/__tests__/services/model.test.ts
|
|
234
|
+
src/views/MainView.tsx → src/__tests__/views/MainView.test.tsx
|
|
235
|
+
src/views/Detail/state.ts → src/__tests__/views/Detail/state.test.ts
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
**行数**:测试文件**不受体积门禁约束**(门禁跳过 `__tests__/`)——fixture 天然长,不设上限;**但 >1000 行的测试按 `describe` 组拆到同夹多文件**。
|
|
239
|
+
|
|
240
|
+
> ⚠️ **迁移既有测试时最易翻车的点**:测试文件加深一层后,**所有相对 import 全变**(`./model` → `../../services/model`)。**漏改的表现是 Vitest 静默跳过该文件(`0 test`)而不是报错**——迁完必须核对用例总数没掉。
|
|
241
|
+
|
|
242
|
+
---
|
|
243
|
+
|
|
244
|
+
## 特殊情况——允许放 `src/` 根目录的
|
|
245
|
+
|
|
246
|
+
- **`index.tsx`**——插件入口,必须放在 `src/` 根
|
|
247
|
+
- **高度内聚的单文件插件**(总文件数 ≤ 3)——不强制建子目录
|
|
248
|
+
- **跨层共享的类型定义**(如 `types.ts`)——放 `src/` 根,被多个子目录 import
|
|
249
|
+
|
|
250
|
+
---
|
|
251
|
+
|
|
252
|
+
## `i18n/` 翻译目录
|
|
253
|
+
|
|
254
|
+
插件自带翻译文件,每种目标语言一个 JSON。key = 插件 UI 字符串原文(建议用作者母语),value = 译文。
|
|
255
|
+
|
|
256
|
+
```
|
|
257
|
+
i18n/
|
|
258
|
+
├─ en.json ← { "在文件树中显示": "Reveal in File Tree" }
|
|
259
|
+
└─ ja.json ← { "在文件树中显示": "ファイルツリーで表示" }
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
**声明:** `plugin.json` 的 `contributes.i18n` 字段声明各语言文件路径:
|
|
263
|
+
```json
|
|
264
|
+
"contributes": {
|
|
265
|
+
"i18n": { "en": "i18n/en.json", "ja": "i18n/ja.json" }
|
|
266
|
+
}
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
**不需要为作者母语写回退文件**——缺译文的 key 由 `parseMissingKeyHandler` 返回原文:中文插件不必建 `zh.json`,纯英文/纯法文插件同样不必为英文/法文建回退文件——key 就是原文,缺译文时静默回退显示 key 本身。
|
|
270
|
+
|
|
271
|
+
**翻译对象:** `plugin.json` 中的 `title`/`description`(命令、配置项、视图容器名)+ `.tsx` 中 `t()` 调用的 UI 字符串。
|
|
272
|
+
|
|
273
|
+
**切语言行为:** 壳自动加载各插件的 `contributes.i18n` → 注册到 i18next → 切语言时即时生效,无需重启。渲染时调 `t()` 即可,不要求 `namespace` 参数——翻译注册在全局 `"translation"` 命名空间。
|
|
274
|
+
|
|
275
|
+
---
|
|
276
|
+
|
|
277
|
+
## 命名约定
|
|
278
|
+
|
|
279
|
+
- **文件名:** PascalCase(组件)、camelCase(非组件)、kebab-case.css(样式)
|
|
280
|
+
- **测试文件:** `<被测文件名>.test.ts(x)`——放 `__tests__/`,**内保持与被测文件相同的相对路径**(见上方「`__tests__/` 的路径与命名」)
|
|
281
|
+
- **CSS 文件:** 与被 styled 的组件同名——`MainView.tsx` → `MainView.css`
|
|
282
|
+
|
|
283
|
+
---
|
|
284
|
+
|
|
285
|
+
## 对标 VS Code
|
|
286
|
+
|
|
287
|
+
VS Code 扩展没有强制目录结构,但官方示例遵循类似约定:
|
|
288
|
+
|
|
289
|
+
| VS Code | LinkDesk |
|
|
290
|
+
|:--|:--|
|
|
291
|
+
| `src/extension.ts` | `src/index.tsx` |
|
|
292
|
+
| `src/commands/` | 无——命令在 `index.tsx` 中注册 |
|
|
293
|
+
| `src/views/` | `src/views/`——完全相同 |
|
|
294
|
+
| `src/test/` | `src/__tests__/`——Vitest 约定双下划线 |
|
|
295
|
+
| `media/` | `src/styles/`——LinkDesk 统一放在 src 下 |
|
|
296
|
+
| `package.nls.json` / `l10n/` | `i18n/`——LinkDesk key=中文原文,只提供目标语言 JSON |
|
|
297
|
+
|
|
298
|
+
---
|
|
299
|
+
|
|
300
|
+
> **← 上一章:** `08-ViewContainer-视图容器API.md`
|
|
301
|
+
> **← 索引:** `00-README.md`
|
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
# 如何造一个设置插件
|
|
2
|
+
|
|
3
|
+
> 2026-08-22· **2026-09-06 与实现对齐核对**(塌平单根 + 共享控件收 @linkdesk/ui)。**给第三方插件作者。** 你的插件想给用户一个"设置 UI"?不用改壳——声明一个 `factoryRole: "settings"` 插件即可。这是**整套设置 UI 的完整替代品**,不是往里加一个设置项。
|
|
4
|
+
|
|
5
|
+
## 这是什么
|
|
6
|
+
|
|
7
|
+
**设置插件 = 一整套设置界面。** 声名 `factoryRole: "settings"` 的插件,会与官方设置并存:
|
|
8
|
+
|
|
9
|
+
- 用户打开设置(`Ctrl+,` / 齿轮)→ 进**当前激活套**的 UI(没切过 = 官方套)
|
|
10
|
+
- 可装多套 → 每套设置 UI 顶部有个**通用区**,列出全部 N 套(含自身),点哪套切到哪套
|
|
11
|
+
- 激活套选择**持久化**,重启保持
|
|
12
|
+
|
|
13
|
+
关键心智:**设置插件的 UI 只是渲染器,数据永远在同一个地方。** 所有套 UI 都调同一个 `window.linkdesk.configuration` API、看到同一份数据——切套只是换渲染器,数据不动。这不是"数据私有/公开"之分,是**一致性**:人人看同一份。
|
|
14
|
+
|
|
15
|
+
## 最小声明——plugin.json 三步
|
|
16
|
+
|
|
17
|
+
照官方设置(= **settings 插件自己的仓** `Encaron/linkdesk-plugin-settings` 的 `plugin.json`;发货插件源码已不在壳仓)写:
|
|
18
|
+
|
|
19
|
+
```jsonc
|
|
20
|
+
{
|
|
21
|
+
"$schema": "../../public/schemas/plugin.schema.json",
|
|
22
|
+
"name": "漂亮设置", // 插件名——通用区按钮显示的就是它(走 t())
|
|
23
|
+
"version": "1.0.0",
|
|
24
|
+
"icon": "resources/icon.png",
|
|
25
|
+
// 不填 core —— 可卸载;core: true 则 UI 无卸载按钮(防误删旗标,非类别)
|
|
26
|
+
"factoryRole": "settings", // ① 关键——声明自己是"设置套"的一份子
|
|
27
|
+
"entry": "src/index.tsx", // 标签页入口(appearsIn.tabBar 需要 entry)
|
|
28
|
+
"appearsIn": { "iconBar": "bottom", "tabBar": true },
|
|
29
|
+
"tabBehavior": { "singleton": true }, // 单例——切换时已开就不重复开
|
|
30
|
+
"contributes": {
|
|
31
|
+
"viewsContainers": {
|
|
32
|
+
"settings": { "title": "设置", "location": "auxiliarybar" } // ② 视图容器
|
|
33
|
+
},
|
|
34
|
+
"views": {
|
|
35
|
+
"settings": [
|
|
36
|
+
{ "id": "settings", "title": "设置", "render": "src/views/SettingsView.tsx", "order": 0 }
|
|
37
|
+
]
|
|
38
|
+
},
|
|
39
|
+
"floatingPanel": { "viewId": "settings" } // ③ 悬浮面板形态(可选)
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
三个关键声明缺一不可:**`factoryRole: "settings"`**(进通用区候选列表)+ **`contributes.views`**(真实渲染组件)+ **`floatingPanel`**(`Ctrl+,` 兜底形态)。
|
|
45
|
+
|
|
46
|
+
## 数据 API 形状——全走 `window.linkdesk.*`
|
|
47
|
+
|
|
48
|
+
设置插件**禁止 `import @src/core/...`**(插件通信铁律 + ESLint `noCoreImportInPlugin`)。数据全在公开 API:
|
|
49
|
+
|
|
50
|
+
| 你要的 | 调用 | 返回形状 |
|
|
51
|
+
|------|------|------|
|
|
52
|
+
| 全部配置分组 | `window.linkdesk.configuration.getConfigurationContributions()` | `[pluginId, { title, properties }][]`(具名类型 `LinkDeskConfigurationContribution`) |
|
|
53
|
+
| 合并 schema | `window.linkdesk.configuration.getSchema()` | `LinkDeskConfigSchema`——含 `type/default/description/enum/enumDescriptions` + **`uiHint`/`minimum`/`maximum`/`renderHint`/`dependsOn`**(类型补全,官方控件切色的依据) |
|
|
54
|
+
| 读/写/订阅配置 | `configuration.get/set/onChange` | 通用 API,任何插件可用 |
|
|
55
|
+
| 设置页专用刷新 | `configuration.onDidChangeConfiguration(cb)` | 配置变 → cb(key, value),UI 实时刷新 |
|
|
56
|
+
| 配置分组跳转 | `configuration.consumeSettingsGroup()` / `onRequestSettingsGroup(cb)` | 打开时切分组 |
|
|
57
|
+
| 滚动到某设置 | `configuration.consumeScrollToSetting()` / `onRequestScrollToSetting(cb)` | 打开时滚动定位 |
|
|
58
|
+
| 快捷键页数据 | `window.linkdesk.keybindings.getKeybindings()` | `Keybinding[]`(快捷键 UI 的数据源) |
|
|
59
|
+
| 主题选择器 | `window.linkdesk.commands.executeCommand("theme.pick")` | 唤起主题 QuickPick(两段式:配方→配色) |
|
|
60
|
+
| 语言选择器 | `window.linkdesk.commands.executeCommand("workbench.action.selectLanguage")` | 唤起语言 QuickPick |
|
|
61
|
+
| 插件装卸刷新 | `window.linkdesk.configuration.onPluginLifecycleChange(cb)` | 装卸插件 → cb,重拉候选/按钮消失 |
|
|
62
|
+
|
|
63
|
+
**`settings.json` 文件名常量 = 数据契约一部分。** 官方设置"以 JSON 打开"按钮这么定位落盘文件:
|
|
64
|
+
|
|
65
|
+
```ts
|
|
66
|
+
const dir = await window.linkdesk.path?.appDataDir?.();
|
|
67
|
+
const filePath = dir ? window.linkdesk.path.join(dir, "settings.json") : "";
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
文件名就叫 `settings.json`,没有壳侧 map——照抄即可。
|
|
71
|
+
|
|
72
|
+
## 共享控件——`@linkdesk/ui`
|
|
73
|
+
|
|
74
|
+
设置 UI 的共享控件在 **`@linkdesk/ui`** 包(收归——第三方 `npm i @linkdesk/ui` 后直接 import,**禁 `import @src/core/...` 也禁 `@src/components/...`**):
|
|
75
|
+
|
|
76
|
+
`ContextMenu` · `InlineInput` · `SelectBox` · `Toggle` · `ColorPicker` · `FontFamilySelect` · `FilePathInput` · `NumberInput` · `Slider`· `Combobox` · `FormRow` · `SegmentedRadio` · `ThemePicker` · `PluginIcon` · 共享 hooks(`useDebouncedInput` / `useClipboardKeys` 等)
|
|
77
|
+
|
|
78
|
+
```tsx
|
|
79
|
+
import { InlineInput, SelectBox, FormRow } from "@linkdesk/ui";
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
> 官方 settings 实样(`src/views/SettingsView.tsx`,在 settings 插件自己的仓里)就是从 `@linkdesk/ui` import——照抄 import 行即可,不用额外工程配置。
|
|
83
|
+
|
|
84
|
+
## 编排层自由组合——数据一样,想怎么排就怎么排
|
|
85
|
+
|
|
86
|
+
数据 API 只决定"有什么数据";**布局是你的自由发挥**。现役参考:
|
|
87
|
+
|
|
88
|
+
- **官方设置**(仓 `Encaron/linkdesk-plugin-settings`,core:true)= 左分组树 + 右表单 + 顶部平铺切换条——现役唯一设置套(旧 `settings-demo` 参考实样已下架,从零编排见下方造法一/二)
|
|
89
|
+
- 你做的设置套想怎么排就怎么排:banner 头 + 卡片分区(全部配置组 = 卡片,含角色胶囊行 + 快捷键键帽卡)+ 右下角胶囊切换套都行(形态二设计源 = 工厂角色并存 mockup `01-形态一形态二-复杂场景图.html`)
|
|
90
|
+
|
|
91
|
+
编排维度:分组导航 / 搜索框 / 控件渲染 / "以 JSON 打开" / 快捷键子页 / banner 头 / 卡片分区——每样都可以做、可以不做、可以换位置。
|
|
92
|
+
|
|
93
|
+
## 切换激活套——通用区按钮 + 全插件侧换套
|
|
94
|
+
|
|
95
|
+
每个设置插件的顶部通用区渲染**全部 N 套按钮(含自身)**,当前激活套高亮。点击切换 = **全插件侧换套**,零壳改动:
|
|
96
|
+
|
|
97
|
+
```ts
|
|
98
|
+
async function handleSettingsSwitch(targetId: string) {
|
|
99
|
+
await window.linkdesk.factorySlots.setActive("settings", targetId); // ① 落盘持久化
|
|
100
|
+
if (tabId) {
|
|
101
|
+
// ② 标签页形态:关本套 tab → 开目标套(singleton 去重已存在则聚焦)
|
|
102
|
+
await window.linkdesk.tabs.close(tabId).catch(() => {});
|
|
103
|
+
await window.linkdesk.tabs.create(targetId).catch(() => {});
|
|
104
|
+
} else {
|
|
105
|
+
// ③ 悬浮面板形态:原地换套——候选 viewId 复合寻址,壳复合替换面板内容
|
|
106
|
+
const target = settingsCandidates.find((c) => c.pluginId === targetId);
|
|
107
|
+
if (target?.viewId) {
|
|
108
|
+
await window.linkdesk.panel.revealFloating(target.viewId, target.pluginId).catch(() => {});
|
|
109
|
+
} else {
|
|
110
|
+
await window.linkdesk.tabs.create(targetId).catch(() => {}); // 无浮动面板声明 → 退回开 tab
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
组件在 `{ isActive, tabId }` props 里收 `tabId`(壳注入;浮动面板无标签页时为 `undefined` → 走悬浮面板原地换套分支)。`settingsCandidates` 来自 `factorySlots.list("settings")`——每条候选带 `viewId`(该套的 `contributes.floatingPanel.viewId`,供原地换套复合寻址)。`panel.revealFloating(viewId, pluginId?)` 的可选 pluginId 是后来新增的——双套同名 viewId 并存时携带 pluginId 精确命中目标套。
|
|
117
|
+
|
|
118
|
+
通用区按钮数量 = **活集合运行时推导**——删任意一套 → `onPluginLifecycleChange` → 重拉 → 按钮自动消失。
|
|
119
|
+
|
|
120
|
+
## 造法一:复制官方(最快)
|
|
121
|
+
|
|
122
|
+
把官方设置插件(仓 `Encaron/linkdesk-plugin-settings`)的目录整份拷进你的工程根,只改:
|
|
123
|
+
|
|
124
|
+
1. `plugin.json`——`name`/`description`;**去掉 `core: true`**(否则 UI 无卸载入口),新增 UI 文案见下方 i18n 节
|
|
125
|
+
2. 追加你自己的风格到 `src/views/SettingsView.css`——**但覆盖规则必须挂你自己的根类**,见下方「🔥 CSS 作用域铁律」
|
|
126
|
+
|
|
127
|
+
官方设置**零 `@src/core` import**(历史两个 `@src/core` 依赖已随消除:`getFilePath` → `path.appDataDir` 自推导;`useConfigurationIpc` → 直接调 `window.linkdesk.configuration.*`),复制即得自包含。
|
|
128
|
+
|
|
129
|
+
## 造法二:从零编排(画布全换)
|
|
130
|
+
|
|
131
|
+
不复制官方设置组件结构——**组件只依赖数据 API + `@linkdesk/ui` 共享控件,布局完全自己画**:banner 头、卡片网格、角色胶囊行、快捷键键帽卡、右下角悬浮胶囊,想怎么排怎么排(数据 API 形状见上表、控件见「共享控件」节)。
|
|
132
|
+
|
|
133
|
+
> 参考路径:官方 settings 插件仓里的 `src/views/SettingsView.tsx` 是最小设置套骨架;要画布全换就从零写自己的 `SettingsView.tsx`,用 `contributes.views[].render` 指向它。
|
|
134
|
+
|
|
135
|
+
## 🔥 CSS 作用域铁律
|
|
136
|
+
|
|
137
|
+
**两个设置套的 CSS 注入同一个 Pool 文档。** 你的覆盖规则若写裸共享类(如 `.settings-form .settings-row`、`.settings-role-switch--gen`),会和官方套的同类规则打架——后注入者赢,官方套被你的样式污染(真机实测 bug 2:demo 的卡片气泡泄漏进官方套——教训仍成立)。
|
|
138
|
+
|
|
139
|
+
结构性解法 = **你自己的独有根类命名空间**(用自己的 pluginId,如 `.my-settings`):
|
|
140
|
+
|
|
141
|
+
- 根元素挂一个独有类(`.my-settings`),你新增的覆盖/规则一律挂它:`.my-settings .settings-row { ... }`
|
|
142
|
+
- 规则只命中你自己子树 → 官方套零受影响;且自带"样式自包含"(官方套 CSS 加载与否都不影响你)
|
|
143
|
+
- 自己的新组件类也用独有前缀(`.ms-*`),别用裸名(`.keycap` 也要挂 `.my-settings .keycap`)
|
|
144
|
+
|
|
145
|
+
## i18n 新文案(i18n 审计门禁)
|
|
146
|
+
|
|
147
|
+
新增 UI 文案走 `t("中文原文")`;`npm run check` 的 i18n 审计要求**每个新 key 有英文翻译**,否则红灯。设置插件在 `contributes` 声明翻译文件即可:
|
|
148
|
+
|
|
149
|
+
```jsonc
|
|
150
|
+
"contributes": {
|
|
151
|
+
"i18n": { "en": "i18n/en.json" },
|
|
152
|
+
// ...
|
|
153
|
+
}
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
`i18n/en.json` = `{ "中文原文": "English" }`(zh 不需要——中文 key 自带兜底)。
|
|
157
|
+
|
|
158
|
+
## 验证
|
|
159
|
+
|
|
160
|
+
- `npm run check` 全绿(tsc + ESLint 零警告 + vitest)
|
|
161
|
+
- 实机:`npm run dev` 在你**自己的工程根**跑(或 build 成 zip 装进 `{userData}/plugins`)→ 重启 → 图标栏出现 → 打开设置 → 通用区出现新按钮 → 点击切换 → 持久化重启保持
|
|
162
|
+
- 可卸载重装(可卸载 ⇒ 可重装 = 插件性定义本身)
|
|
163
|
+
|
|
164
|
+
> 参考实体:仓 `Encaron/linkdesk-plugin-settings`(core:true 官方设置套,UI 无卸载入口)。
|