@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,299 @@
1
+ # 07 — 插件间通信
2
+
3
+ > 2026-07-28 · 2026-08-21 全量更新 · **2026-09-06 与实现对齐核对**(三通信机制自定型后未变,逐段核零残留,原样保留)。**插件之间怎么传数据?** 不是"终端开个门给协议"——所有通信走核心提供的管道。插件只负责用,不需要建。
4
+
5
+ ---
6
+
7
+ ## 一、核心原则
8
+
9
+ ```
10
+ ❌ 插件 ⇄ 插件 (直接握手——LinkDesk 不允许)
11
+
12
+ ✅ 插件 → 核心 → 插件 (核心提供管道,插件只是用)
13
+ ```
14
+
15
+ **只有核心建 API。插件不建 API。** 插件做的事:调核心给的函数,往管道里读写数据。
16
+
17
+ ---
18
+
19
+ ## 二、三通信机制——核心提供,插件选用
20
+
21
+ | | 广播 `events` | 命令 `commands` | 数据管道 |
22
+ |------|------|------|------|
23
+ | API | `events.emit/on` | `registerCommand` / `executeCommand` | `serial.onData/onStats/onSystem` + `lsp.onData` + `filesystem.watch` |
24
+ | 语义 | 谁订阅谁收到(同池内按 channel 过滤) | 具名可调用动作 | 高频推流——**流**,不是事件 |
25
+ | 生产者知道消费者吗 | 不知道 | 不知道(命令谁都能调) | 不知道 |
26
+ | 目标不在线 | 无所谓——没人听就没人听 | 命令未注册 → no-op | 订阅方自己负责 |
27
+ | 适合 | 事件广播、状态变更、数据共享 | 暴露能力给别人调 | 串口数据、LSP 输出、目录变更 |
28
+ | 比喻 | 广场上的喇叭 | 服务台叫号 | 水龙头 |
29
+
30
+ **三套可同时使用。** 终端收到一串串口数据,可以同时:
31
+ - 走 `events.emit` 广播给日志插件(谁都该知道)
32
+ - 走数据管道 `serial.onData` 推给协议解析(高频、流式、带端口路由键)
33
+ - 暴露 `registerCommand('xxx.send', handler)` 让别的插件发数据回设备
34
+
35
+ > 历史上有「后门 p2p」作为第二管道——见 §四:已建,但 target 路由已删,语义归一为池内广播。
36
+
37
+ ---
38
+
39
+ ## 三、广播 `events`——广场上的喇叭
40
+
41
+ ```
42
+ 终端 协议 日志插件
43
+ │ │ │
44
+ │ events.emit( │ │
45
+ │ 'serial:rawData', │ │
46
+ │ { portName, text } │ │
47
+ │ ) │ │
48
+ │ ↓ │ │
49
+ │ 核心广播 │ │
50
+ │ (池 + 壳,按 channel) │ │
51
+ │ ↓ ↓ ↓
52
+ │ events.on( events.on(
53
+ │ 'serial:rawData', 'serial:rawData',
54
+ │ callback callback
55
+ │ ) )
56
+ │ 解析字节 记录日志
57
+ ```
58
+
59
+ **发送方不知道谁在听。** 0 个人、1 个人、10 个人——都一样,`emit` 完就走。
60
+
61
+ **频道名是字符串。** 核心不知道 `'serial:rawData'` 是什么意思。频道名约定:`<插件id>:<数据名>`。
62
+
63
+ **代码(`on<T>` 泛型——载荷类型按订阅方 cb 推断,跨进程类型安全见 §十一):**
64
+ ```typescript
65
+ // ── 发出数据(插件 A)──
66
+ window.linkdesk.events.emit('serial:rawData', {
67
+ portName: 'COM3',
68
+ text: '\xAA\x01\x02'
69
+ })
70
+
71
+ // ── 接收数据(插件 B)──
72
+ const unsub = window.linkdesk.events.on<{ portName: string; text: string }>(
73
+ 'serial:rawData',
74
+ (data) => {
75
+ console.log(data.portName, data.text) // COM3, \xAA\x01\x02
76
+ }
77
+ )
78
+ // 组件卸载时清理
79
+ // unsub()
80
+ ```
81
+
82
+ **通道是广播到「池 + 壳」。** 池 emit → 主进程 `plugin:emit` → 广播 `plugin:push` → 池 + 壳都收到。想从池侧直接发到壳且不回流 = `p2p`(§四)。
83
+
84
+ ---
85
+
86
+ ## 四、后门 `p2p`——包间里的电话(已建,target 路由已删)
87
+
88
+ ```
89
+ 终端 协议
90
+ │ │
91
+ │ p2p.send( │
92
+ │ 'sbq-protocol', ← 指定收件人(历史语义)
93
+ │ 'serial:raw', │
94
+ │ data │
95
+ │ ) │
96
+ │ ↓ │
97
+ │ 主进程直接发池 │
98
+ │ (不经 broadcast) │
99
+ │ ↓ │
100
+ │ p2p.on('serial:raw', callback)
101
+ │ 按 channel 过滤——不广播
102
+ ```
103
+
104
+ **状态:已建,不再是「计划」。** 签名:
105
+
106
+ ```typescript
107
+ interface P2pApi {
108
+ send(target: string, channel: string, data: unknown): void; // fire-and-forget
109
+ on(channel: string, cb: (data: unknown) => void): () => void; // 返回 unsubscribe
110
+ }
111
+ ```
112
+
113
+ **⚠️ `target` 路由已删。** Per-Tab WebView(每个插件一个实例)不存在后,唯一接收方就是池——`target` 参数保留(向后兼容、不删签名)但**不参与路由**:发出去就是发到池,谁 `p2p.on` 同一个 channel 谁收到。**零验证、零报错**——target 写错也不会报"目标未运行"。
114
+
115
+ **p2p vs events 现在的差别:**
116
+ - `events.emit` → 广播 `plugin:push` → **池 + 壳**都收到(壳可加桥联动,见 §十一)
117
+ - `p2p.send` → 主进程直发 **池**(独立 `p2p:data` 通道),不经 broadcast
118
+
119
+ 所以:需要壳联动 → 用 events;只打算在插件之间传且不想触发壳桥 → p2p。高频场景二者性能差异已无所谓(单池内同进程分发)。新代码默认 events,p2p 用于不想扰动壳广播路径的定向测试通道(serial-monitor 的 `test-p2p` 就是这种用法)。
120
+
121
+ ---
122
+
123
+ ## 五、命令 `commands`——服务台叫号
124
+
125
+ **一个插件的"能力" = 一组具名命令。** 别人(壳或另一个插件)调用它 = `executeCommand`。
126
+
127
+ ```typescript
128
+ // ── 插件 A 注册能力(组件 mount 时)──
129
+ window.linkdesk.commands.registerCommand('serial-monitor.send', (args?: { text: string }) => {
130
+ // 往串口发数据
131
+ })
132
+
133
+ // ── 插件 B 调用能力 ──
134
+ await window.linkdesk.commands.executeCommand('serial-monitor.send', { text: 'AT\r\n' })
135
+ ```
136
+
137
+ **注册语义:**
138
+ - `registerCommand` 幂等(Map.set 覆盖)——StrictMode 双挂载安全
139
+ - `when: "false"` = 纯程序化命令,不进命令面板(`titleActions` 声明制专属命令就是这种,见 `08`)
140
+ - **命令是 `titleActions` 的落地机制**——声明式 `titleActions` 里每个 widget 的 `command` 字段,点击时池侧 `executeCommand` 执行(池侧注册表优先、壳 IPC fallback)
141
+
142
+ ---
143
+
144
+ ## 六、数据管道——流,不是事件
145
+
146
+ 广播 `events` 处理"一次性通知";**数据管道处理"持续灌入的流"**。串口数据、LSP 输出、目录变更都是流——不是"告诉你一次",是"不停灌给你"。
147
+
148
+ | 管道 | API | 载荷 | 路由键 |
149
+ |------|------|------|------|
150
+ | 串口数据 | `serial.onData(cb)` | `SerialDataPayload` | `portName`(多口) |
151
+ | 串口统计 | `serial.onStats(cb)` | `SerialStatsPayload` | `portName` |
152
+ | 串口系统事件 | `serial.onSystem(cb)` | `SerialSystemPayload` | `portName` |
153
+ | LSP 输出 | `lsp.onData(cb)` | `(channelId: string, data: string)` | `channelId` |
154
+ | 目录变更 | `filesystem.watch(dir, cb)` | `FileChangeEvent` | —(内部 `filesystem:changed:<watcherId>`) |
155
+
156
+ ```typescript
157
+ // 订阅串口数据——载荷对象化带 portName 路由键:多口并存各口各收
158
+ const unsub = window.linkdesk.serial.onData((p) => {
159
+ if (p.portName !== 'COM3') return; // 谁消费谁过滤——壳不代收
160
+ handleBytes(p.data);
161
+ });
162
+ // 卸载清理
163
+ // unsub()
164
+
165
+ // 监听目录变更——返回 unsubscribe
166
+ const off = await window.linkdesk.filesystem.watch('/workspace', (e) => {
167
+ // e: FileChangeEvent
168
+ });
169
+ // off()
170
+ ```
171
+
172
+ **流语义(RingBuffer 教训):**
173
+ - **数据是流不是事件。** 不是"通知一次"——是"持续灌入"。订阅方自备缓冲/过滤。
174
+ - **消费方按路由键过滤**(`portName` / `channelId`)——这是通用路由键模式:谁消费谁过滤,壳不代收。
175
+ - **需要完整历史的消费方**可 `import { RingBuffer } from "@src/core/pipeline/RingBuffer"`(纯工具白名单——`@src/core/pipeline/*` 是插件允许 import 的例外,见 `01 §五`)。RingBuffer 是流式消费的标准件,不是事件总线。
176
+ - **内部归一化:**起 `serial.onData/onStats/onSystem` 底层就是 `events.on("serial:data"/"stats"/"system")`——三通道走广播管道,无独立 direct 通道。插件不需要知道这些细节,`serial.onXxx` 就是唯一入口。
177
+
178
+ ---
179
+
180
+ ## 七、终端——第一个交出数据的插件(E3j #77-#79,历史参考)
181
+
182
+ > 2026-08-21 注:本节是 E3 时代的历史记录,**终端插件的当前实现已与下述任务有出入**(数据源已归一化到数据管道)。保留作为"第一个数据源插件怎么做"的模式参考。
183
+
184
+ 终端插件当初把三样东西交到大厅:
185
+
186
+ | # | 做什么 | 用哪个 API | 谁受益 |
187
+ |---|--------|-----------|--------|
188
+ | #77 | 推原始串口数据 | `events.emit('serial:rawData', data)` | 协议插件订阅后解析 |
189
+ | #78 | 广播连接状态 | `events.emit('serial:connected', {...})` | 状态栏/其他插件 |
190
+ | #79 | 接收发送命令 | `registerCommand('serial-monitor.send', handler)` | 工作台卡片发数据回 MCU |
191
+
192
+ **终端没有建任何 API。** 它只调了核心已有的函数:`events.emit`、`registerCommand`。今天的终端走 `serial.onData/onStats/onSystem` 数据管道(§六)+ 命令(§五)——同一原则的进化版。
193
+
194
+ ---
195
+
196
+ ## 八、以后每个插件怎么做
197
+
198
+ 新插件进场,回答两个问题:
199
+
200
+ **1. 我有什么数据别人可能需要?**
201
+ → 数据是流 → 走数据管道(§六,串口/LSP/文件场景)或 `events.emit('频道名', 数据)`。频道名按约定起。
202
+
203
+ **2. 我有什么能力别人可能需要调用?**
204
+ → 调 `registerCommand('命令名', handler)`。命令名自己起。`handler` 是自己写的处理函数。
205
+
206
+ 两个问题答完,该插件没有额外工作要做。**桌子是核心的,管道是核心的,函数是核心的。插件只是用。**
207
+
208
+ ---
209
+
210
+ ## 九、为什么这么说
211
+
212
+ > "终端建 API,协议连接终端的 API"
213
+
214
+ **这不是 LinkDesk 的模式。** 这是"开门"模式——每加一个插件,N 个插件之间开 N×(N-1) 扇门。
215
+
216
+ LinkDesk 的模式:
217
+
218
+ - **管道 = 核心建一次。** `events.emit`、`events.on`、`p2p.send`、`p2p.on`、`registerCommand`、`serial.onData`——这些函数是核心的,不是任何插件的。
219
+ - **频道名/命令名 = 插件自己起。** `'serial:rawData'`、`'sbq-protocol:parsed'`——字符串而已,核心不知道意思。
220
+ - **新数据源 = 不需要改核心。** 新插件调同一行 `events.emit('新频道名', 数据)`,核心代码零改动。
221
+
222
+ **核心的工作量是 O(1),不是 O(N)。** 这就是插件自由化。
223
+
224
+ ---
225
+
226
+ ## 十、相关
227
+
228
+ - `01-插件API契约.md` —— §3.2 `events`(频道命名 + 壳广播事件表)与 `commands` 运行时约定;方法签名唯一真相源 = `contracts/linkdesk.d.ts`(`DataAPI.events/p2p` / `CommandsAPI`)
229
+ - `05-插件UI写法规约.md` —— §8 插件自有数据模型(EventTarget);§9 系统 UI 浮层(quickPick/notifications/dialog)
230
+ - `08-ViewContainer-视图容器API.md` —— `titleActions` 声明制如何经 `executeCommand` 落地
231
+
232
+ ---
233
+
234
+ ## 🔥 十一、AI 开发者必读——新插件需要新通信时怎么改
235
+
236
+ > 2026-08-04。**React Fallback 退役后发现的模式。**
237
+ > 这也是 LinkDesk 插件自由化的核心循环——不是 bug,是正常开发流程。
238
+
239
+ **先问一句:这条通信需要壳参与吗?** 答案决定改哪里。
240
+
241
+ ### 11.1 场景
242
+
243
+ 你正在开发一个新插件。它需要接收某种外部指令(壳或其他插件发来的数据),但现有 `window.linkdesk.events` 里没有对应的事件类型。
244
+
245
+ **示例:** editor 插件需要知道打开了哪个文件。但当前没有 `editor:openFile` 事件——editor 的 `sourceId` 是靠 React props `<EditorView sourceId="xxx" />` 传的。
246
+
247
+ ### 11.2 三种情况,三种改法
248
+
249
+ | 情况 | 改哪里 | 壳要动吗 |
250
+ |:--|:--|:--|
251
+ | **插件 ↔ 插件**——只是两个插件间传数据 | **零改动。** `events.emit('myPlugin:xxx', payload)` + 对方 `events.on`。channel 是自由字符串契约,订阅方收窄载荷 | ❌ 不用 |
252
+ | **插件 → 壳联动**——壳要响应(关标签/切视图/显隐) | **`src/App/bridges.ts`(`useUiBridges`)加一个桥**:一段 `events.on("channel", ...)` → `shellEvents.emit(...)` | ✅ 只加桥,不改架构 |
253
+ | **跨进程载荷要类型安全** | 载荷类型定义进 `src/core/api/` 生成源 → `contracts:gen` 重新生成契约 → 双端 `import type` | ✅ 契约机械门禁 |
254
+
255
+ **插件 ↔ 插件(最常见,零壳改动):**
256
+ ```typescript
257
+ // 插件 A——发
258
+ window.linkdesk.events.emit('editor:openFile', { filePath: 'xxx' })
259
+
260
+ // 插件 B——收(零壳改动)
261
+ window.linkdesk.events.on('editor:openFile', ({ filePath }) => { ... })
262
+ ```
263
+
264
+ **插件 → 壳联动(加桥——`bridges.ts` 现有桥清单):**
265
+
266
+ | 桥(`bridges.ts` 已内置) | 壳联动做什么 |
267
+ |:--|:--|
268
+ | `icon:selected` / `icon:reordered` | 图标栏点选开标签 / 拖拽换位持久化 |
269
+ | `file:deleted` / `file:renamed` | 文件树资源事件 → TabManager 关标签/迁移 label |
270
+ | `panel:viewSelected` / `panel:resize` / `panel:toggleViewVisibility` | 面板切视图 / 拖拽改高 / 勾选显隐 |
271
+ | `panel:createView` | 面板 [+] → QuickPick 视图选择器 |
272
+
273
+ ```typescript
274
+ // 壳侧 bridges.ts 加桥的模板(对照现有 file:deleted 桥):
275
+ useEffect(() => {
276
+ const off = window.linkdesk?.events?.on("myPlugin:someEvent", (payload) => {
277
+ shellEvents.emit("myPlugin:someEvent", payload);
278
+ });
279
+ return () => { off?.(); };
280
+ }, []);
281
+ ```
282
+
283
+ **壳侧事件类型**(`shellEvents.emit` 的载荷)定义在 `src/core/react/events/ShellEvents.ts`——需要时在类型表加一行。
284
+
285
+ ### 11.3 什么情况需要加通信
286
+
287
+ | 场景 | 需要通信? | 用哪个 |
288
+ |:--|:--|:--|
289
+ | 新插件需要接收壳指令 | ✅ 是 | 壳 `bridges.ts` 加桥 → `events.on` 订阅 |
290
+ | 新插件推送数据给其他插件 | ✅ 是 | `events.emit`(事件)或数据管道(流) |
291
+ | 新插件只在内部管理状态 | ❌ 不用 | 组件内 state / 插件自有 EventTarget model(`05 §8`) |
292
+ | 新插件需要读取配置 | ❌ 不用 | `linkdesk.configuration.get()` |
293
+ | 新插件需要操作文件 | ❌ 不用 | `linkdesk.filesystem` |
294
+
295
+ ### 11.4 关键原则
296
+
297
+ - **`contracts/linkdesk.d.ts` 是 API 签名唯一真相源;`bridges.ts` 是壳↔池桥接器集合。** 新 AI 只需要读这两个就知道全部通信面。
298
+ - **加通信是正常的,不是 hack。** LinkDesk 的设计就是"壳是空的,API 在管道里长"。VS Code 从 10 个 API 长到 1000+,LinkDesk 同理——频道表会持续增长。
299
+ - **不要在壳里为插件写分支代码。** 壳只负责 `emit`/`on` 转发——插件自己处理业务逻辑。