@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
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
# 04 — 数据管道命令约定
|
|
2
|
+
|
|
3
|
+
> **类型:壳级别** — 参考文档,定义命令 ID 格式约定 | 2026-07-26。**在写任何协议/卡片插件之前定死。** 命令 ID 格式、参数约定、返回格式——定了就不能随便改,改了就是 API 断裂。
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 管道模型
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
滑杆卡片拖拽
|
|
11
|
+
→ 协议.encode(value)
|
|
12
|
+
→ 终端.sendBytes(bytes)
|
|
13
|
+
→ MCU 接收→计算→回传
|
|
14
|
+
→ 终端.receiveData(raw)
|
|
15
|
+
→ 协议.parse(raw)
|
|
16
|
+
→ 波形图卡片更新
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
三个角色:**数据源**(终端/串口/网络)→ **协议**(encode/decode)→ **卡片**(UI 控件)。
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## 命令 ID 格式
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
<pluginId>.<action>
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
| 角色 | 命令 | 示例 |
|
|
30
|
+
|---|---|---|
|
|
31
|
+
| 数据源 | `<pluginId>.sendBytes` | `terminal.sendBytes` |
|
|
32
|
+
| 数据源 | `<pluginId>.onData`(事件) | `terminal.onData` |
|
|
33
|
+
| 协议 | `<pluginId>.encode` | `bracket.encode` |
|
|
34
|
+
| 协议 | `<pluginId>.parse` | `bracket.parse` |
|
|
35
|
+
| 协议 | `<pluginId>.decode` | `modbus.decode` |
|
|
36
|
+
|
|
37
|
+
**规则:**
|
|
38
|
+
- 前缀 = 插件 ID(`plugin.json` 的 `id` 字段)
|
|
39
|
+
- 动作名 = 动词(`sendBytes` / `encode` / `parse` / `decode`)
|
|
40
|
+
- 数据源不叫 `send`——太模糊。字节级推送叫 `sendBytes`
|
|
41
|
+
- `onData` 是事件(Emitter),不是命令——走 CoreEvents 而非 CommandRegistry。此处列出只为命名一致性
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## 参数格式
|
|
46
|
+
|
|
47
|
+
### sendBytes——数据源发送字节
|
|
48
|
+
|
|
49
|
+
```typescript
|
|
50
|
+
// 请求
|
|
51
|
+
{
|
|
52
|
+
channel: number, // 通道/串口号
|
|
53
|
+
bytes: number[], // 待发送的原始字节
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
// 响应
|
|
57
|
+
{
|
|
58
|
+
success: boolean,
|
|
59
|
+
error?: string, // 失败原因(如 "port closed")
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### encode——协议编码(值 → 字节)
|
|
64
|
+
|
|
65
|
+
```typescript
|
|
66
|
+
// 请求
|
|
67
|
+
{
|
|
68
|
+
channel: number,
|
|
69
|
+
value: number, // 应用层值(如滑杆 0-100)
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
// 响应
|
|
73
|
+
{
|
|
74
|
+
success: boolean,
|
|
75
|
+
bytes?: number[], // 编码后的字节
|
|
76
|
+
error?: string,
|
|
77
|
+
}
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
### parse / decode——协议解析(字节 → 值)
|
|
81
|
+
|
|
82
|
+
```typescript
|
|
83
|
+
// 请求
|
|
84
|
+
{
|
|
85
|
+
channel: number,
|
|
86
|
+
bytes: number[], // 原始字节
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
// 响应
|
|
90
|
+
{
|
|
91
|
+
success: boolean,
|
|
92
|
+
value?: number, // 解析后的应用层值
|
|
93
|
+
fields?: Record<string, unknown>, // 结构化字段(如 { temp: 25.3, humidity: 60 })
|
|
94
|
+
error?: string,
|
|
95
|
+
}
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### 卡片更新——扩展版
|
|
99
|
+
|
|
100
|
+
```typescript
|
|
101
|
+
// 请求
|
|
102
|
+
{
|
|
103
|
+
cardId: string, // 卡片实例 ID
|
|
104
|
+
fields: Record<string, unknown>, // 字段→值映射
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
// 响应
|
|
108
|
+
{
|
|
109
|
+
success: boolean,
|
|
110
|
+
error?: string,
|
|
111
|
+
}
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
## 结果格式——统一信封
|
|
117
|
+
|
|
118
|
+
```typescript
|
|
119
|
+
interface PipelineResult {
|
|
120
|
+
success: boolean;
|
|
121
|
+
error?: string; // 人类可读,短——适合 toast 显示
|
|
122
|
+
}
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
**规则:**
|
|
126
|
+
- 所有管道命令返回 `PipelineResult` 或其子类型
|
|
127
|
+
- `success = false` 时 `error` 必填
|
|
128
|
+
- `error` 是人类可读的短字符串——不是堆栈、不是 code
|
|
129
|
+
- 具体数据字段(`bytes` / `value` / `fields`)只在 `success = true` 时保证存在
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
## 注册方式
|
|
134
|
+
|
|
135
|
+
插件在 `contributes.commands` 中声明:
|
|
136
|
+
|
|
137
|
+
```json
|
|
138
|
+
{
|
|
139
|
+
"contributes": {
|
|
140
|
+
"commands": [
|
|
141
|
+
{ "id": "bracket.encode", "title": "Bracket 协议: 编码" },
|
|
142
|
+
{ "id": "bracket.parse", "title": "Bracket 协议: 解析" }
|
|
143
|
+
]
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
调用方通过 `executeCommand`:
|
|
149
|
+
|
|
150
|
+
```typescript
|
|
151
|
+
const result = await executeCommand("bracket.encode", {
|
|
152
|
+
channel: 1,
|
|
153
|
+
value: 75,
|
|
154
|
+
}) as PipelineResult & { bytes?: number[] };
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
---
|
|
158
|
+
|
|
159
|
+
## 为什么现在定
|
|
160
|
+
|
|
161
|
+
| 不定 | 定了 |
|
|
162
|
+
|---|---|
|
|
163
|
+
| AI A 写 `terminal.send`,AI B 写 `serial.pushBytes`——接不上 | 所有数据源叫 `sendBytes`——管道自动对接 |
|
|
164
|
+
| 返回格式各写各的——`{ ok }` vs `{ success }` vs throw | 统一信封——调用方不猜 |
|
|
165
|
+
| 卡片不知道协议返回 `value` 还是 `fields` | 约定明确——AI 看此文档就知道怎么消费 |
|
|
166
|
+
|
|
167
|
+
---
|
|
168
|
+
|
|
169
|
+
## 不作为核心命令
|
|
170
|
+
|
|
171
|
+
这些命令**不在 `coreCommands.ts` 注册**——核心不知道协议/终端/卡片的存在。它们由各自插件注册,通过 CommandRegistry 互相发现。核心只提供 CommandRegistry 桌子。
|
|
172
|
+
|
|
173
|
+
> **← 07 索引:** `00-README.md`
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
# 多仓开发与本地工作区
|
|
2
|
+
|
|
3
|
+
> 2026-09-14 ·。**回答三问:我的插件工程该放哪?仓库该叫什么?怎么改显示名?**
|
|
4
|
+
> 每条都带「为什么」——这份文档的读者包含未来的 AI,只写「怎么做」它会在下一个会话里按自己的理解改掉。命名规则(id/版本/分发件名的字符集与可变性)的权威条文 → [16-命名规范](16-命名规范.md),本篇不复制。
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## 一、本地目录约定——工程收进容器,按归属分
|
|
9
|
+
|
|
10
|
+
**推荐布局**:所有插件工程收进**一个容器目录**(建议 `E:\linkdesk-plugins\`),内部按**归属**分两夹:
|
|
11
|
+
|
|
12
|
+
```
|
|
13
|
+
E:\linkdesk-plugins\
|
|
14
|
+
├─ official\ ← 你自己的插件(官方 18 只 + 后续新插件)
|
|
15
|
+
│ ├─ file-tree\
|
|
16
|
+
│ └─ settings\
|
|
17
|
+
└─ third-party\ ← 别人的插件(clone 下来学习/二开的)
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
**为什么按归属不按功能**:归属稳定(一只插件不会从官方变第三方),功能分类会随插件增加不断重划;且市场 catalog 里的 `category` 已经在做功能分类,本地再分一遍是重复劳动。
|
|
21
|
+
|
|
22
|
+
**为什么收进容器**:不收就会平铺散落(`E:\linkdesk-build+scratch\` 里现在就躺着两只),找不到、备份漏、AI 进场也不知道去哪找。
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## 二、🔴 容器目录本身绝不建仓
|
|
27
|
+
|
|
28
|
+
`E:\linkdesk-plugins\` **永远不要 `git init`**。这不是洁癖——一旦容器被建成仓库,三件坏事自动发生:
|
|
29
|
+
|
|
30
|
+
1. **每只插件的 `.git` 变成嵌套仓**,父仓把它们记成 gitlink——**静默坏掉且极难看出来**(clone 容器的人拿到的是空目录)。
|
|
31
|
+
2. **脚手架的规则被反转成灾难**:`create-linkdesk-plugin` 检测「已在 git 仓内 → 不再 init」,容器一旦是仓,**每只新插件都不建自己的仓**,全部变成容器的子目录——恰好造出你想避开的 monorepo。
|
|
32
|
+
3. 触发方式防不胜防:IDE 的「初始化仓库」提示、在错层级敲 `git init`、从父目录 `git add .` 都可能中招。
|
|
33
|
+
|
|
34
|
+
**护栏**:容器里放一张说明(`README.md` 或 `不要在这里建仓.txt`)——防的不只是作者本人,还有以后进场读目录的 AI。
|
|
35
|
+
|
|
36
|
+
---
|
|
37
|
+
|
|
38
|
+
## 三、仓库名完全自由(D5/N2)
|
|
39
|
+
|
|
40
|
+
**仓库名不强制任何前缀,第三方零约束。** 这是拍过板的:作者给自己的插件(仓库)取名是正当权利,不能定死。
|
|
41
|
+
|
|
42
|
+
- **建议但非强制的惯例**:官方插件仓统一 `linkdesk-plugin-<id>`(N3 待用户拍板,拍板后条文住 [插件源码外移层/09-命名规范.md §五](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md)——只此一处维护);第三方随意。
|
|
43
|
+
- **改仓库名的代价**:已发布 catalog 条目里的 `downloadUrl` / `readmeUrl` 内嵌 `owner/repo`,**改名会断已发布插件的下载与 README 链接**(源码本身不受影响)。改名后重发一版新条目即可自愈,但旧版本条目仍指旧链——**能不改就不改,要改趁早**。
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## 四、身份 vs 显示名 vs 仓库名(D5)
|
|
48
|
+
|
|
49
|
+
三个「名字」互不相干,混为一谈是一切命名问题的根源:
|
|
50
|
+
|
|
51
|
+
| | 是什么 | 能不能改 |
|
|
52
|
+
|:--|:--|:--|
|
|
53
|
+
| **插件身份**(`plugin.json` 的 id) | 安装目录名、卸载墓碑、更新对账的**唯一键** | 🔴 **发布后永不可变** |
|
|
54
|
+
| **显示名**(`plugin.json` 的 `name`) | 界面、市场卡片上给人看的 | ✅ **随便改**(改完 bump 重发一版) |
|
|
55
|
+
| **仓库名** | GitHub 上的工程仓 | ✅ 自由(代价见上节) |
|
|
56
|
+
|
|
57
|
+
对标 VS Code 的实测口径(`ms-vscode.cpptools`:身份 = `publisher.name` 永不可变,`displayName` = 随便改,仓库名与身份无关)→ 完整实测与论证 → [插件源码外移层/09-命名规范.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md);作者面规则条文 → [16-命名规范](16-命名规范.md)。
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## 五、本地目录位置与插件身份无关(本篇最重要的一条)
|
|
62
|
+
|
|
63
|
+
**插件工程 clone 到哪、目录叫什么,都不影响插件身份**——插件仓是自足的,壳只认 Release URL 与 catalog,**不认本地路径**。⇒ 本地目录结构随时可重排,零风险。
|
|
64
|
+
|
|
65
|
+
活证据:`hello-linkdesk` 与 `first-run-setup` 两只插件的源码仓平铺在容器外,照样构建、发布、上架、被安装版正常装卸。官方 18 只现在也全是这样(各自独立一仓)。
|
|
66
|
+
|
|
67
|
+
✅ **所以「改目录名」这件事今天已经安全**:插件身份 = 顶层 `pluginId` 字段(必须显式声明,发布后不可改),**与目录名无关**。
|
|
68
|
+
|
|
69
|
+
> ⚠️ **别读反了**:危险的是**改 `pluginId`**(= 换一个插件,装过的用户看不到更新、数据看似丢失,多数后果不报错),不是改目录名。详见 [16-命名规范](16-命名规范.md)。
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## 六、发布链路上的四个名字不许手改
|
|
74
|
+
|
|
75
|
+
它们参与安装裁决与更新对账,**手改即身份漂移或更新链断**:
|
|
76
|
+
|
|
77
|
+
| 名字 | 为什么不许手改 |
|
|
78
|
+
|:--|:--|
|
|
79
|
+
| `<id>.linkdesk-plugin`(分发件名) | zip 安装裁决按基名反查插件 id |
|
|
80
|
+
| `v<version>`(Release tag) | 更新检查按 tag 找版本 |
|
|
81
|
+
| 版本号格式 `^\d+\.\d+\.\d+$` | schema 直接拒预发布后缀等异形 |
|
|
82
|
+
| 插件 id | 身份永不可变(§四) |
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
> **← 索引:** [00-README](00-README.md) · **相关:** [16-命名规范](16-命名规范.md) · [09-插件目录规范 §源码位置与分发物的关系](09-插件目录规范.md)
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
# 命名规范——七种名字,一条身份
|
|
2
|
+
|
|
3
|
+
> 2026-09-14 ·。**读者 = 插件作者。** 读完能回答四问:**id 怎么起?能不能改?显示名怎么改?仓库叫什么?**
|
|
4
|
+
> 决策论证(N1-N6)与 VS Code 实测依据住 [插件源码外移层/09-命名规范.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md)——本篇是作者面落点,两处**只维护一处**:改规则先改本篇并回指,别造第二份。
|
|
5
|
+
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
## 一、七种名字一张表
|
|
9
|
+
|
|
10
|
+
| 名字 | 真源在哪 | 谁在用 | 能不能改 |
|
|
11
|
+
|:--|:--|:--|:--|
|
|
12
|
+
| **插件身份 id** | `plugin.json`(显式声明 `pluginId`;未声明时**临时**兜底 = 工程目录名——兜底不推荐,显式声明才是正路) | 安装目录、卸载记录、更新对账、catalog 去重 | 🔴 **发布后永不可变** |
|
|
13
|
+
| **显示名** `name` | `plugin.json` | 界面、市场卡片 | ✅ 随便改(改完 bump 重发) |
|
|
14
|
+
| **版本** | `plugin.json` 的 `version` | 更新比对、Release tag、catalog | 每次发布必变 |
|
|
15
|
+
| **分发件名** | `<id>.linkdesk-plugin`(SDK 自动生成) | zip 安装裁决、Release 资产 | 跟随 id,**不许手改** |
|
|
16
|
+
| **Release tag** | `v<version>`(publish 自动打) | 更新检查 | 跟随版本,**不许手打** |
|
|
17
|
+
| **GitHub 仓库名** | 无规则 | `downloadUrl` / `readmeUrl` / 详情页「仓库」 | ✅ 自由(改名代价见 §四) |
|
|
18
|
+
| **本地目录名** | 无规则 | 只有构建工具 | ✅ 自由(⚠️ 现状红线见 §五) |
|
|
19
|
+
|
|
20
|
+
**混为一谈是命名问题的总根源**:身份是给机器对的账,显示名是给人看的,仓库名和目录名只是工程住址——三者互不相干,改其中一个不该牵动其他。
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## 二、四条字符集/格式约束(机械执行,写错当场被拒)
|
|
25
|
+
|
|
26
|
+
| 约束 | 规则 | 出处 |
|
|
27
|
+
|:--|:--|:--|
|
|
28
|
+
| 插件 id | `^[A-Za-z0-9][A-Za-z0-9._-]*$`(首字符须字母或数字) | `@linkdesk/plugin-sdk` 的 `SAFE_PLUGIN_ID`(validate) |
|
|
29
|
+
| 版本号 | `^\d+\.\d+\.\d+$`——**不许 `-beta` 之类预发布后缀**(schema 直接拒;想表达预发布目前没有语法,这是现状不是遗漏) | `plugin.schema.json` |
|
|
30
|
+
| 视图容器 ID | `^[a-z][a-z0-9-]*$` | schema / [03-插件contributes规范](03-插件contributes规范.md) |
|
|
31
|
+
| 分发件基名 | = 插件 id | SDK `assetNameForId` |
|
|
32
|
+
|
|
33
|
+
**id 建议小写连字符**(如 `file-tree`)——规则允许大写与点,但小写连字符最省事,官方插件全这么做。
|
|
34
|
+
|
|
35
|
+
---
|
|
36
|
+
|
|
37
|
+
## 三、三问直答
|
|
38
|
+
|
|
39
|
+
- **id 怎么起?** 字符集见上表;**发布后永不可变**——它 = 安装目录名 + 卸载记录键 + 更新对账键,换了 id 等于换了一只插件(旧数据看似丢失、更新链静默断)。**在 `plugin.json` 里显式写 `"pluginId"`**,别依赖目录名兜底。
|
|
40
|
+
- **能不能改 id?** 不能。想换名字改的是显示名。
|
|
41
|
+
- **显示名怎么改?** `plugin.json` 的 `name` 随便改,改完 **bump 版本重发一版**(已装用户副本按版本固化,不重发别人看不到新名)。
|
|
42
|
+
- **仓库叫什么?** 完全自由,不强制前缀。官方插件建议统一 `linkdesk-plugin-<id>`(惯例条文住 [插件源码外移层/09-命名规范.md §五](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md),拍板后只那处维护);第三方随意。
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## 四、改仓库名的代价
|
|
47
|
+
|
|
48
|
+
已发布 catalog 条目里的 `downloadUrl` / `readmeUrl` 内嵌 `owner/repo`——**改名会断旧版本的下载与 README 链接**(源码不受影响)。重发一版新条目可自愈,但旧版本条目仍指旧链。**能不改就不改,要改趁早。**
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## 五、本地目录名与插件身份无关
|
|
53
|
+
|
|
54
|
+
**插件 id = 顶层 `pluginId` 字段**(必须显式声明;发布后不可改),**不是目录名**。⇒ 本地工程目录名**随便改**,身份不受影响。
|
|
55
|
+
|
|
56
|
+
反过来,**改 `pluginId` 才是危险动作——那等于换一个插件**:安装目录并存两份、卸载记录对不上、catalog 出现两条、更新链静默断、插件数据看似丢失,**五条后果全不报错**。真要换 id,等于发布一个新插件(见 [15-多仓开发与本地工作区 §五](15-多仓开发与本地工作区.md))。
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## 六、版本号——四处同源
|
|
61
|
+
|
|
62
|
+
版本号有**四个落点,必须同源**,改一处即四处同改:
|
|
63
|
+
|
|
64
|
+
```
|
|
65
|
+
① CHANGELOG.md 段标题的版本号 ## v<version>
|
|
66
|
+
② plugin.json.version ← 唯一真源(schema 级必填)
|
|
67
|
+
③ 目录条目 versions[].version ← publish 自动写
|
|
68
|
+
④ package.json.version ← 必须与 ② 相等
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
- ①②③ 的既有规则(段标题解析、诚实留空、倒序)→ [09-插件目录规范 §CHANGELOG.md 的格式约定](09-插件目录规范.md)。
|
|
72
|
+
- ④ 是第四处锚:`package.json` 是独立仓里新人(和 AI)**打开仓库第一眼看到的东西**——两个版本号并存且不一致,必然有人 bump 错那一个;而 `publish` 与内容指纹门禁读的都是 ② ⇒ **改错的那个 = 静默无效**。
|
|
73
|
+
- 什么时候 bump(MAJOR/MINOR/PATCH 判据)→ `.claude/skills/version-bump/SKILL.md`——那里是唯一权威,本篇不另立一套。
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
> **← 索引:** [00-README](00-README.md) · **相关:** [15-多仓开发与本地工作区](15-多仓开发与本地工作区.md) · [06-plugin.json规范](06-plugin.json规范.md) · [插件源码外移层/09-命名规范.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md)(决策论证)
|
|
@@ -0,0 +1,225 @@
|
|
|
1
|
+
# 17 — 区域地图:我的插件能出现在哪里
|
|
2
|
+
|
|
3
|
+
> **本页回答一个问题:** 我的插件要出现在窗口的**哪一块**?那一块**怎么声明**、**能放什么**?
|
|
4
|
+
> 如果你只知道"图标栏 / 侧栏 / 主区"这三个词但不知道哪个对应哪段声明——先读这页,再读 [13-插件开发指南](13-插件开发指南.md)。
|
|
5
|
+
|
|
6
|
+
| | |
|
|
7
|
+
|---|---|
|
|
8
|
+
| 读者 | 想知道"我要做的东西该落在哪"的作者(人 或 作者的 AI) |
|
|
9
|
+
| 形态 | **地图**——先看全景,再按区查声明片段 |
|
|
10
|
+
| 不是 | 字段字典(→ [06-plugin.json规范](06-plugin.json规范.md))· 每个贡献点的完整写法(→ [03-插件contributes规范](03-插件contributes规范.md))· 容器 API 详解(→ [08-ViewContainer-视图容器API](08-ViewContainer-视图容器API.md)) |
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## 一、一张图看全部区域
|
|
15
|
+
|
|
16
|
+
```
|
|
17
|
+
┌─────────────────────────────────────────────────────────────────────┐
|
|
18
|
+
│ ① 标题栏 [logo] LinkDesk [按钮…] ─ □ × │ ← contributes.titleBar
|
|
19
|
+
├──────┬───────────────────────────┬──────────────────────────────────┤
|
|
20
|
+
│ │ ③ 侧栏标题 [◀] │ ④ 标签栏 [终端][📊] [+] │
|
|
21
|
+
│ ⑤ ├───────────────────────────┼──────────────────────────────────┤
|
|
22
|
+
│ 图标 │ │ │
|
|
23
|
+
│ 栏 │ ③ 侧栏 │ ⑥ 主区(标签页内容) │
|
|
24
|
+
│ │ 容器 → 视图 │ (分屏时每块面板各有自己的标签栏)│
|
|
25
|
+
│ 42px │ (可叠多个 section) │ │
|
|
26
|
+
│ │ │ │
|
|
27
|
+
├──────┴───────────────────────────┴──────────────────────────────────┤
|
|
28
|
+
│ 底部面板(Ctrl+J) [输出][待办] [动作区] │ ← location: "panel"
|
|
29
|
+
├─────────────────────────────────────────────────────────────────────┤
|
|
30
|
+
│ ⑦ 状态栏 ● COM3 已连接 │ TX:1,234 │ 中:EN ☀ 🔔(3) │ ← 顶层 statusBar[]
|
|
31
|
+
└─────────────────────────────────────────────────────────────────────┘
|
|
32
|
+
|
|
33
|
+
浮层(右键菜单 / 对话框 / 快速选择 / 悬浮面板)画在最上层——它不属于任何区域
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
**区域名以本页为准**(`docs/总体设计/V3-部件命名规范.md` 是同一套名字的正典):标题栏 · 图标栏 · 侧栏 · 标签栏 · 主区 · 底部面板 · 状态栏 · 浮层。
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## 二、区域速查表
|
|
41
|
+
|
|
42
|
+
| 区域 | 你怎么进去(声明) | 放什么 | 用户怎么看到它 |
|
|
43
|
+
|:--|:--|:--|:--|
|
|
44
|
+
| **⑤ 图标栏** | `appearsIn.iconBar`(`"top"` / `"bottom"`)**+** 要么有 `entry`,要么有一个 **sidebar** 容器 | 一个图标按钮 | 图标出现在最左 42px 竖条,点了切换侧栏容器 |
|
|
45
|
+
| **③ 侧栏** | `contributes.viewsContainers` 里 `location: "sidebar"`(默认值)+ `contributes.views` 挂视图 | 可折叠的 section(每个视图一个) | 点图标栏切过来;多个插件可往同一个容器里加视图 |
|
|
46
|
+
| **⑥ 主区** | `entry` + `appearsIn.tabBar: true` | 一个标签页的内容 | 图标栏点一下/`[+]` 新建菜单里选;可多开、可分屏 |
|
|
47
|
+
| **底部面板** | `contributes.viewsContainers` 里 `location: "panel"` + 视图 | 标签栏切换的多个面板视图 | `Ctrl+J` 展开;代码里 `window.linkdesk.panel.reveal(viewId)` 聚焦 |
|
|
48
|
+
| **⑦ 状态栏** | 顶层 `statusBar: [...]` 数组(**不是** `contributes.statusBar`) | 一行文字 / 图标 / 可点的条目 | 常在底部;`align` 决定左右 |
|
|
49
|
+
| **① 标题栏** | `contributes.titleBar.right[]` / `.left[]` | 图标按钮或纯文字按钮 | 窗口最上一行右侧 |
|
|
50
|
+
| **浮层** | `contributes.floatingPanel`(把某个已声明视图声明成"可在悬浮面板打开") | 你已有的某个视图 | 标签页右键「在悬浮面板中打开」 |
|
|
51
|
+
| **视图动作区** | `contributes.views[].titleActions[]` | `icon` / `dropdown` / `split` 三种小控件 | 侧栏 section 折叠头右侧、面板标签栏右侧 |
|
|
52
|
+
|
|
53
|
+
### 两个"进不去"的地方
|
|
54
|
+
|
|
55
|
+
| 想放哪 | 实况 |
|
|
56
|
+
|:--|:--|
|
|
57
|
+
| **右侧栏**(`location: "auxiliarybar"`) | ⚠️ **壳当前未接线**——声明了也不渲染,是 dormant 区域。第三方要用侧栏请用 `"sidebar"` |
|
|
58
|
+
| **顶栏**(旧 TopBar) | 已在早期版本移除。`contributes.titleBar` 这个名字保留,但槽位落在**① 标题栏**,不是老"顶栏" |
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## 三、最容易搞混的三件事
|
|
63
|
+
|
|
64
|
+
### ① 图标栏 ≠ 标签页:两种插件形态
|
|
65
|
+
|
|
66
|
+
一个插件想被看见,有**两条路**,别混:
|
|
67
|
+
|
|
68
|
+
| 形态 | 需要什么 | 结果 |
|
|
69
|
+
|:--|:--|:--|
|
|
70
|
+
| **有 `entry`** | `entry` + `appearsIn.iconBar` | 图标+可当标签页打开(经典形态) |
|
|
71
|
+
| **entryless**(侧栏专用) | **不写 `entry`**,只要有 sidebar 容器 + `appearsIn.iconBar` | 只有图标+侧栏,**永远不是标签页** |
|
|
72
|
+
|
|
73
|
+
> **entryless 是侧栏专用插件的推荐路径**——不用为了"凑一个图标"去写一个空的 `src/index.tsx`。
|
|
74
|
+
> 反过来:`appearsIn.tabBar: true` **必须**配合 `entry`(标签页靠 entry 组件渲染)。
|
|
75
|
+
|
|
76
|
+
**拿不到图标的三种情况**(都不是 bug,是设计):
|
|
77
|
+
- 不声明 `appearsIn.iconBar`(**opt-in**——不写就没有图标)
|
|
78
|
+
- 数据插件(语言包 / 主题 / 图标主题这类没有侧栏容器的)
|
|
79
|
+
- 只有 panel / auxiliarybar 容器——图标栏的语义是"打开侧栏容器",底部面板不算
|
|
80
|
+
|
|
81
|
+
### ② 侧栏容器 ≠ 标签页
|
|
82
|
+
|
|
83
|
+
侧栏里是**容器 → 视图**两层:容器是"频道"(点图标栏切换),视图是容器里一个个**可折叠 section**。
|
|
84
|
+
**别的插件可以往你的容器里加视图,你的插件也可以往别人的容器里加视图**——容器主人不知道也不关心。
|
|
85
|
+
|
|
86
|
+
```jsonc
|
|
87
|
+
// 往别人的容器里加一个 section:只写 contributes.views,不写 viewsContainers
|
|
88
|
+
{ "contributes": { "views": { "explorer": [ { "id": "timeline", "title": "TIMELINE", "render": "src/views/TimelineView.tsx", "order": 100 } ] } } }
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### ③ 视图组件不要自己包 `SidebarSection`
|
|
92
|
+
|
|
93
|
+
壳用 `PoolSectionStack` 渲染时**自动**给你的组件包上折叠头。你返回**内容**就行,包了就是双层折叠头。
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## 四、每个区域的最小声明片段
|
|
98
|
+
|
|
99
|
+
### ⑤ 图标栏 + ⑥ 主区(经典标签页插件)
|
|
100
|
+
|
|
101
|
+
```jsonc
|
|
102
|
+
{
|
|
103
|
+
"pluginId": "my-plugin",
|
|
104
|
+
"name": "我的插件",
|
|
105
|
+
"icon": "resources/icon.svg",
|
|
106
|
+
"entry": "src/index.tsx",
|
|
107
|
+
"appearsIn": { "iconBar": "top", "tabBar": true }
|
|
108
|
+
}
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
```tsx
|
|
112
|
+
// src/index.tsx —— 入口组件:壳按 { isActive, tabId?, sourceId? } 注入 props
|
|
113
|
+
export default function MyView({ isActive }: { isActive: boolean }) {
|
|
114
|
+
return <div>Hello LinkDesk</div>;
|
|
115
|
+
}
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
### ③ 侧栏
|
|
119
|
+
|
|
120
|
+
```jsonc
|
|
121
|
+
{
|
|
122
|
+
"appearsIn": { "iconBar": "top" },
|
|
123
|
+
"contributes": {
|
|
124
|
+
"viewsContainers": { "my-sidebar": { "title": "我的工具", "location": "sidebar", "order": 100 } },
|
|
125
|
+
"views": { "my-sidebar": [ { "id": "main", "title": "", "render": "src/views/MainView.tsx", "order": 0 } ] }
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
### 底部面板
|
|
131
|
+
|
|
132
|
+
```jsonc
|
|
133
|
+
{
|
|
134
|
+
"contributes": {
|
|
135
|
+
"viewsContainers": { "my-panel": { "title": "我的面板", "location": "panel" } },
|
|
136
|
+
"views": { "my-panel": [ { "id": "output", "title": "输出", "render": "src/views/OutputView.tsx", "order": 0 } ] }
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
```ts
|
|
142
|
+
await window.linkdesk.panel.reveal("output"); // 聚焦底部面板的 output 视图(不在 panel 容器里 → no-op,不报错)
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
### ⑦ 状态栏
|
|
146
|
+
|
|
147
|
+
```jsonc
|
|
148
|
+
{
|
|
149
|
+
"statusBar": [
|
|
150
|
+
{ "id": "units", "label": "mm", "align": "right" },
|
|
151
|
+
{ "id": "zoom", "label": "100%", "align": "right", "onClick": "my-plugin.zoomFit" }
|
|
152
|
+
]
|
|
153
|
+
}
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
状态栏条目的 React 组件按三条路径自动找:`statusBar.tsx` / `src/statusBar.tsx` / `src/components/statusBar.tsx`。
|
|
157
|
+
|
|
158
|
+
### ① 标题栏按钮
|
|
159
|
+
|
|
160
|
+
```jsonc
|
|
161
|
+
{
|
|
162
|
+
"contributes": {
|
|
163
|
+
"titleBar": { "right": [ { "command": "my-plugin.refresh", "icon": "codicon-refresh", "when": "my-plugin.busy" } ] }
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
### 视图动作区(侧栏 section / 面板标签栏右侧)
|
|
169
|
+
|
|
170
|
+
```jsonc
|
|
171
|
+
{
|
|
172
|
+
"contributes": {
|
|
173
|
+
"views": {
|
|
174
|
+
"my-sidebar": [
|
|
175
|
+
{
|
|
176
|
+
"id": "main", "title": "我的工具", "render": "src/views/MainView.tsx",
|
|
177
|
+
"titleActions": [ { "type": "icon", "id": "reload", "command": "my-plugin.reload", "icon": "codicon-refresh", "title": "重新加载" } ]
|
|
178
|
+
}
|
|
179
|
+
]
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
}
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
`titleActions` 里的 `command` 由你的视图组件自己注册(`window.linkdesk.commands.registerCommand`);**这类纯程序化命令建议 `when: "false"`**,免得在命令面板里刷屏。
|
|
186
|
+
|
|
187
|
+
---
|
|
188
|
+
|
|
189
|
+
## 五、组件的 props 契约
|
|
190
|
+
|
|
191
|
+
不管你落在哪个区域,**内容组件收到的都是同一套 props**:
|
|
192
|
+
|
|
193
|
+
```ts
|
|
194
|
+
type PluginViewProps = { isActive: boolean; tabId?: string; sourceId?: string };
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
| prop | 含义 | 用法 |
|
|
198
|
+
|:--|:--|:--|
|
|
199
|
+
| `isActive` | 所在标签页/视图当前是否聚焦 | **只用来 gate "聚焦才该跑的副作用"**(轮询、自动保存)——keep-alive 下所有标签页始终挂载,用 `isActive` 整块 blank 掉内容 = bug |
|
|
200
|
+
| `tabId` | 本标签页 id | 区分多开的同一个插件 |
|
|
201
|
+
| `sourceId` | 上下文数据(文件路径 / 会话 id 等) | 编辑器类插件靠它知道"用户打开了哪个文件" |
|
|
202
|
+
|
|
203
|
+
侧栏/面板的**视图**组件签名同款(可以只声明用得上的那几个 prop)。
|
|
204
|
+
|
|
205
|
+
---
|
|
206
|
+
|
|
207
|
+
## 六、区域之间的互动
|
|
208
|
+
|
|
209
|
+
选好了区域只解决"住哪";"侧栏选中 → 主区切换 → 状态栏更新"这类**跨区域联动**是另一篇:
|
|
210
|
+
→ [18-区域间互动](18-区域间互动.md)。
|
|
211
|
+
|
|
212
|
+
---
|
|
213
|
+
|
|
214
|
+
## 七、相关篇目
|
|
215
|
+
|
|
216
|
+
| 你要做的 | 读这篇 |
|
|
217
|
+
|:--|:--|
|
|
218
|
+
| 视图容器 API 全字段(`viewsContainers` / `views` / `titleActions` 三形态) | [08-ViewContainer-视图容器API](08-ViewContainer-视图容器API.md) |
|
|
219
|
+
| 每个贡献点的完整写法与示例 | [03-插件contributes规范](03-插件contributes规范.md) |
|
|
220
|
+
| 每个字段的含义/类型/默认值 | [06-plugin.json规范](06-plugin.json规范.md) · `plugin.schema.json` |
|
|
221
|
+
| 区域之间怎么联系 | [18-区域间互动](18-区域间互动.md) |
|
|
222
|
+
| 第一次写插件 | [13-插件开发指南](13-插件开发指南.md) |
|
|
223
|
+
| 全部文档索引 | [00-README](00-README.md) |
|
|
224
|
+
|
|
225
|
+
> 临时负控行。
|