@binblink/wasmnest-plugin-sdk-desktop 0.0.0-stage → 0.0.1

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 (80) hide show
  1. package/README.md +287 -2
  2. package/README_en.md +284 -0
  3. package/bin/cli.js +602 -0
  4. package/bin/manifest-gen.js +454 -0
  5. package/bin/manifest-validate.js +432 -0
  6. package/bin/permission-vocabulary.json +5 -0
  7. package/bin/plugin-watch.js +331 -0
  8. package/bin/wasm-hash.js +124 -0
  9. package/dev-shell/README.md +121 -0
  10. package/dev-shell/index.html +12 -0
  11. package/dev-shell/package.json +28 -0
  12. package/dev-shell/pnpm-workspace.yaml +9 -0
  13. package/dev-shell/postcss.config.js +6 -0
  14. package/dev-shell/src/App.vue +90 -0
  15. package/dev-shell/src/components/LogPanel.vue +90 -0
  16. package/dev-shell/src/loader.ts +109 -0
  17. package/dev-shell/src/locale.ts +29 -0
  18. package/dev-shell/src/locales.ts +50 -0
  19. package/dev-shell/src/main.ts +46 -0
  20. package/dev-shell/src/mock/agent-hub-commands.ts +1065 -0
  21. package/dev-shell/src/mock/agent-hub.ts +42 -0
  22. package/dev-shell/src/mock/app-env.ts +102 -0
  23. package/dev-shell/src/mock/commands.ts +54 -0
  24. package/dev-shell/src/mock/domain-context.ts +46 -0
  25. package/dev-shell/src/mock/events.ts +16 -0
  26. package/dev-shell/src/mock/file-transfer.ts +512 -0
  27. package/dev-shell/src/mock/tauri-ipc.ts +109 -0
  28. package/dev-shell/src/registry.ts +90 -0
  29. package/dev-shell/src/shell/components/AppMountSlot.vue +241 -0
  30. package/dev-shell/src/shell/components/ShellIcon.vue +141 -0
  31. package/dev-shell/src/shell/components/ShellStatusBar.vue +87 -0
  32. package/dev-shell/src/shell/components/ShellToolbar.vue +287 -0
  33. package/dev-shell/src/shell/mount/appSession.ts +45 -0
  34. package/dev-shell/src/shell/mount/devAppMount.ts +80 -0
  35. package/dev-shell/src/shell/types.ts +132 -0
  36. package/dev-shell/src/styles/dev.css +27 -0
  37. package/dev-shell/src/styles/shell.css +546 -0
  38. package/dev-shell/src/styles/style.css +1132 -0
  39. package/dev-shell/src/theme.ts +140 -0
  40. package/dev-shell/src/vite-env.d.ts +24 -0
  41. package/dev-shell/tailwind.config.js +98 -0
  42. package/dev-shell/vite.config.ts +174 -0
  43. package/dist/index.d.ts +109 -0
  44. package/dist/index.js +170 -0
  45. package/dist/types.d.ts +585 -0
  46. package/dist/types.js +0 -0
  47. package/dist/vite-plugin.d.ts +25 -0
  48. package/dist/vite-plugin.js +80 -0
  49. package/package.json +89 -3
  50. package/src/config.ts +49 -0
  51. package/src/global-dialog.ts +169 -0
  52. package/src/index.ts +80 -0
  53. package/src/runtime.ts +54 -0
  54. package/src/types.ts +630 -0
  55. package/src/ui/MarkdownEditor.vue +520 -0
  56. package/src/ui/PluginGlobalDialog.vue +401 -0
  57. package/src/ui/Select.d.ts +36 -0
  58. package/src/ui/Select.vue +220 -0
  59. package/src/ui/TerminalInputRail.vue +184 -0
  60. package/src/ui/apply-select-position.ts +65 -0
  61. package/src/ui/markdown-editor-syntax.ts +234 -0
  62. package/src/ui/markdown-editor.d.ts +36 -0
  63. package/src/ui/plugin-global-dialog.d.ts +12 -0
  64. package/src/ui/select-position.ts +79 -0
  65. package/src/ui/terminal-input-rail.d.ts +30 -0
  66. package/src/ui/zoom-compensation.d.ts +9 -0
  67. package/src/ui/zoom-compensation.ts +52 -0
  68. package/src/vite-plugin.ts +124 -0
  69. package/template/README.md +39 -0
  70. package/template/package.json +23 -0
  71. package/template/plugin.json +14 -0
  72. package/template/rust/Cargo.toml +21 -0
  73. package/template/rust/src/lib.rs +39 -0
  74. package/template/src/env.d.ts +24 -0
  75. package/template/src/index.ts +37 -0
  76. package/template/tsconfig.json +17 -0
  77. package/template/vite.config.ts +21 -0
  78. package/tools/componentize/Cargo.lock +270 -0
  79. package/tools/componentize/Cargo.toml +15 -0
  80. package/tools/componentize/src/main.rs +94 -0
package/src/types.ts ADDED
@@ -0,0 +1,630 @@
1
+ /**
2
+ * @binblink/wasmnest-plugin-sdk-desktop 类型定义
3
+ *
4
+ * 插件系统所有公开类型 — 插件通过此包引用,无需依赖宿主源码
5
+ *
6
+ * desktop-host-frontend-downsink(2026-10-17):宿主前端整树退役,原双写副本
7
+ * 宿主侧 `wasmnest-desktop/src/plugin/types.ts` 随之删除——本文件成为桌面端唯一真源。
8
+ */
9
+
10
+ // ==================== 基础类型 ====================
11
+
12
+ /** Disposable 接口 — 用于资源清理 */
13
+ export interface Disposable {
14
+ dispose(): void
15
+ }
16
+
17
+ /** 插件类型 */
18
+ export type PluginType = 'rust' | 'rust-ts' | 'ts-only'
19
+
20
+ /**
21
+ * 组件装配角色(manifest `type` 字段,core-plugin-manager · ADR 0032)
22
+ *
23
+ * 三层加载顺序固定 `L1 → L2 → L3`:
24
+ * - `basic-service`(L1):引擎域组件,提供 host-* 同形能力,最先激活;
25
+ * - `internal-business`(L2):宿主网关的裁决依赖方(宿主**主动调它**);
26
+ * - `business-app`(L3):业务应用面,缺省。
27
+ *
28
+ * 历史拼写 `system` / `application` 仍被宿主按别名解析(只影响反序列化),
29
+ * 新声明一律用上面的三个值。
30
+ */
31
+ export type PluginKind = 'basic-service' | 'internal-business' | 'business-app'
32
+
33
+ /**
34
+ * 实例生命周期策略(manifest `lifecycle` 字段,ADR 0032)
35
+ *
36
+ * 正交于装配角色:角色管「装配在哪一层」,本字段管「实例活多久」。
37
+ * `ephemeral` = 业务 worker(无页面、即用即弃;存在理由是避开 wasm 线性内存
38
+ * 单调增长撞单实例限额)。**本期只预留类型**,宿主加载期与构建链均显式拒绝声明。
39
+ */
40
+ export type InstanceLifecycle = 'persistent' | 'ephemeral'
41
+
42
+ /**
43
+ * 适配平台(manifest `platform` 字段,必填)
44
+ *
45
+ * 三值:`desktop`(仅桌面)/ `mobile`(仅移动)/ `both`(双端适配)。
46
+ * 宿主在加载 / zip 安装期按本端校验:桌面拒 `mobile`、移动拒 `desktop`,
47
+ * `both` 两端均可装载(真源 SDK `rust/src/types.rs::PluginPlatform`)。
48
+ */
49
+ export type PluginPlatform = 'desktop' | 'mobile' | 'both'
50
+
51
+ /** 插件描述文件 (plugin.json) 结构 */
52
+ export interface PluginManifest {
53
+ id: string
54
+ name: string
55
+ version: string
56
+ /**
57
+ * 适配平台:`desktop`(仅桌面)/ `mobile`(仅移动)/ `both`(双端适配)。
58
+ *
59
+ * **必填**(与 id/name/version 同档):宿主加载 / 安装时校验声明必须覆盖
60
+ * 当前端,不匹配即 fail-visible 拒绝装载。
61
+ */
62
+ platform: PluginPlatform
63
+ description: string
64
+ author: string
65
+ main: string
66
+ pluginType: PluginType
67
+ /** WASM 库文件名(仅 rust-ts 类型插件使用) */
68
+ rustLibrary?: string
69
+ /** 插件图标:图片路径(相对插件目录)或内联 SVG 标记 */
70
+ icon?: string
71
+ permissions: string[]
72
+ contributes: PluginContributes
73
+ /**
74
+ * 组件装配角色:`basic-service`(L1)/ `internal-business`(L2)/
75
+ * `business-app`(L3,缺省)。缺省 L3,旧插件零迁移。
76
+ */
77
+ type?: PluginKind
78
+ /**
79
+ * 实例生命周期策略:`persistent`(缺省)/ `ephemeral`(即用即弃 worker)
80
+ *
81
+ * `ephemeral` 目前**只预留类型**(ADR 0032 §6):宿主的一次性实例机制与
82
+ * 调度框架未落地,声明即在加载期与构建链被显式拒绝(不静默当常驻处理)。
83
+ */
84
+ lifecycle?: InstanceLifecycle
85
+ /**
86
+ * 运行期传输租约声明(manifest `backgroundTransport`,服务端型应用)
87
+ *
88
+ * `true` = 应用**运行期间**(启动成功 → 停用 / Error)持有宿主传输面
89
+ * (`net.transport`:WS + HTTP 同端口 + mDNS 广播)租约;**界面挂载 / 卸载
90
+ * 不再是其生死开关**(服务端属性跟应用启动走,不跟界面槽走)。代价是整段
91
+ * 运行期对外可达,故必须显式 opt-in,并在 `permissions` 声明 `ws:server` /
92
+ * `network:http` 至少一个——构建期与宿主加载期双侧校验,缺权限即拒。
93
+ *
94
+ * 缺省 `false` = 既有行为:界面打开才 acquire,关闭最后一个界面即停播。
95
+ */
96
+ backgroundTransport?: boolean
97
+ /**
98
+ * 能力依赖声明(应用插件消费的能力名,WIT host-* 接口名)
99
+ *
100
+ * 宿主激活时校验:每个依赖必须已有提供者(宿主原语或已激活的 L1 基础服务),
101
+ * 缺失即激活失败并指明能力名。缺省空数组 = 无依赖。
102
+ */
103
+ dependencies?: string[]
104
+ /**
105
+ * 单插件 Store 资源上限覆盖请求(core-config × core-security)
106
+ *
107
+ * 重型插件可请求更大的燃料预算/线性内存;未设置的字段继承内核配置。
108
+ * 最终值由宿主安全模块仲裁:逐字段取 min(请求值、内核配置值、编译期
109
+ * 硬上限)——插件只能自我收紧,放宽请求被钳回上限。缺省 = 全部继承。
110
+ */
111
+ resourceOverrides?: ResourceOverrides
112
+ /**
113
+ * 单插件在册 `host-pty` 句柄数上限声明(会话引擎下沉 P1 / H1)
114
+ *
115
+ * 缺省 = 内核默认档(8 条)。业务会话由插件经 `host-pty.spawn` 自持 PTY 后,
116
+ * 「用户可开多少终端」是属主插件的产品档位,不再是单一内核常量。
117
+ * 区间上限由宿主内核常量仲裁(越界在**加载期**拒绝、不夹取);构建期只校形态。
118
+ */
119
+ ptyQuota?: number
120
+ /**
121
+ * WASI 预打开目录声明(manifest `wasiPreopenDirs`,**仅 worker 类别可用**,ADR 0034)
122
+ *
123
+ * 主 wasm-app 文件访问一律走宿主 `host-fs` 授权机制(manifest permissions 声明
124
+ * `fs:read` / `fs:write`,目录经 `fs_request_auth` / preauth 授权并持久化),不再
125
+ * 使用 WASI preopen。本字段为 worker 类别(`lifecycle: ephemeral`,ADR 0032 L3.b
126
+ * 预留)保留:worker 未实现期间(ephemeral 本身被拒)它对一切 manifest 不可达——
127
+ * 非 worker 声明在构建期与宿主加载期双侧显性拒绝。
128
+ *
129
+ * 条目两形态:裸路径字符串 = 可写挂载(既有形态,零迁移);
130
+ * `{ path, readonly: true }` = 只读挂载。宿主实例化时逐项过授权
131
+ * (无弹窗的 is_granted)后才挂载,未授权目录无论哪一档都挂不上——
132
+ * 只读档收紧的是 guest 的写能力,不是免授权通道。
133
+ *
134
+ * 缺省空 = 无预打开。支持 `${home}` 展开为主目录。
135
+ */
136
+ wasiPreopenDirs?: WasiPreopenDir[]
137
+ }
138
+
139
+ /**
140
+ * 一条 WASI 预打开目录声明(manifest `wasiPreopenDirs` 的对象形态)
141
+ *
142
+ * `readonly` 缺省 = 可写,与改造前行为一致;只有显式 `true` 才挂只读档。
143
+ * 未知字段会被宿主判为非法条目(整份 manifest 解析失败),不要往里加键。
144
+ */
145
+ export interface WasiPreopenDirDecl {
146
+ /** 主机路径,支持 `${home}` 前缀 */
147
+ path: string
148
+ /** `true` = 只读挂载;缺省 / `false` = 可写 */
149
+ readonly?: boolean
150
+ }
151
+
152
+ /** WASI 预打开目录声明条目:裸路径(可写)或 `{ path, readonly }` 对象 */
153
+ export type WasiPreopenDir = string | WasiPreopenDirDecl
154
+
155
+ /**
156
+ * 单插件 Store 资源上限覆盖请求(manifest `resourceOverrides`)
157
+ *
158
+ * 字段可选:未设置即继承内核配置;设置即请求值,宿主仲裁后生效
159
+ * (见 `PluginManifest.resourceOverrides`)。
160
+ */
161
+ export interface ResourceOverrides {
162
+ /** 单次导出调用燃料预算(指令数) */
163
+ fuelPerCall?: number
164
+ /** 线性内存上限(字节) */
165
+ maxMemoryBytes?: number
166
+ /** 表元素上限 */
167
+ maxTableEntries?: number
168
+ /** 单 Store 核心实例数上限 */
169
+ maxInstances?: number
170
+ /** 单 Store 线性内存数量上限 */
171
+ maxMemories?: number
172
+ /** 单 Store 表数量上限 */
173
+ maxTables?: number
174
+ }
175
+
176
+ /** 插件配置声明 */
177
+ export interface PluginConfiguration {
178
+ title: string
179
+ properties: Record<string, ConfigProperty>
180
+ }
181
+
182
+ /** 配置属性定义 */
183
+ export interface ConfigProperty {
184
+ type: 'string' | 'number' | 'boolean'
185
+ title: string
186
+ description?: string
187
+ default?: any
188
+ enum?: string[]
189
+ }
190
+
191
+ /** 插件扩展点声明 */
192
+ export interface PluginContributes {
193
+ commands: CommandContribution[]
194
+ views: ViewContribution[]
195
+ terminal?: TerminalContribution
196
+ toolProviders: ToolProviderContribution[]
197
+ fileHandlers: FileHandlerContribution[]
198
+ /**
199
+ * 插件 HTTP 端点清单(`_http_endpoint` 的路径白名单 + 认证档位,票 08)。
200
+ * 条目为相对路径段(不含 `/api/plugin/<插件 id>/` 前缀)。宿主**只认声明**:未声明
201
+ * 的路径 404,未声明清单等于没有 HTTP 面(票据 03 的「前缀内 ANY 放行」过渡策略已退役)。
202
+ * 条目可写成对象以声明档位;缺 `auth` 即最严档 `jwt`,免凭证必须逐条显式写 `none`。
203
+ */
204
+ httpEndpoints?: HttpEndpointContribution[]
205
+ wsEndpoints?: WsEndpointContribution[]
206
+ configuration?: PluginConfiguration
207
+ lifecycle?: LifecycleContribution
208
+ /** 自定义监控面板声明(monitor 统一壳消费;实现住提供方应用工程) */
209
+ monitorPanels?: MonitorPanelContribution[]
210
+ }
211
+
212
+ /** 自定义监控面板声明(只登记元数据) */
213
+ export interface MonitorPanelContribution {
214
+ id: string
215
+ title: string
216
+ /** 排序权重(小者靠前;缺省 100) */
217
+ order?: number
218
+ }
219
+
220
+ /** HTTP 端点认证档位(与 WS 端点注册面同一张词汇表,票 08) */
221
+ export type EndpointAuthTier = 'none' | 'jwt'
222
+
223
+ /**
224
+ * 一条 HTTP 端点声明:纯路径段(档位取宿主最严缺省)或带 `auth` 的对象形态。
225
+ * 与 Rust 侧 `HttpEndpointContribution`(serde untagged)逐形对应。
226
+ */
227
+ export type HttpEndpointContribution = string | { path: string; auth?: EndpointAuthTier }
228
+ export type WsEndpointContribution = string | { path: string; auth?: EndpointAuthTier }
229
+
230
+ /** 生命周期扩展点声明 */
231
+ export interface LifecycleContribution {
232
+ onStartup?: boolean
233
+ onShutdown?: boolean
234
+ }
235
+
236
+ /** 命令扩展点 */
237
+ export interface CommandContribution {
238
+ id: string
239
+ title: string
240
+ icon?: string
241
+ }
242
+
243
+ /** 视图扩展点 */
244
+ export interface ViewContribution {
245
+ id: string
246
+ type: 'sidebar' | 'toolbox' | 'statusbar'
247
+ title: string
248
+ component: string
249
+ icon?: string
250
+ }
251
+
252
+ /** 终端扩展点 */
253
+ export interface TerminalContribution {
254
+ inputHandlers: string[]
255
+ outputParsers: string[]
256
+ }
257
+
258
+ /** 外部工具扩展点 */
259
+ export interface ToolProviderContribution {
260
+ id: string
261
+ name: string
262
+ endpoint: string
263
+ }
264
+
265
+ /** 文件处理扩展点 */
266
+ export interface FileHandlerContribution {
267
+ id: string
268
+ extensions: string[]
269
+ viewer: string
270
+ icon?: string
271
+ }
272
+
273
+ // ==================== UI 描述符 ====================
274
+
275
+ /** 侧边栏面板描述符 */
276
+ export interface SidebarPanelDescriptor {
277
+ id: string
278
+ title: string
279
+ /** SVG path d 属性字符串(Heroicons outline 风格,stroke-width=2,viewBox=0 0 24 24)
280
+ * 与宿主内置菜单共用同一图标体系,可包含多个 M 子路径组合成完整图标 */
281
+ icon?: string
282
+ /** 菜单排序值,升序排列(越小越靠前),缺省 600。
283
+ * 宿主内置菜单只剩恒最末的插件管理(9998) / 设置(9999)(业务槽位已随票 13/14
284
+ * 下沉插件,宿主无内置业务入口);插件目录按自身 order 排布,同域其余项取 +1/+10。
285
+ * 同值按注册先后排列。 */
286
+ order?: number
287
+ component: any
288
+ }
289
+
290
+ /** 工具箱页面描述符 */
291
+ export interface ToolboxPageDescriptor {
292
+ id: string
293
+ title: string
294
+ /** SVG path d 属性字符串(Heroicons outline 风格,stroke-width=2,viewBox=0 0 24 24) */
295
+ icon?: string
296
+ /** 菜单排序值,升序排列(越小越靠前),缺省 600。
297
+ * 与宿主内置菜单共用同一排序空间,可插入任意内置项之间 */
298
+ order?: number
299
+ component: any
300
+ }
301
+
302
+ /** 设置分组描述符(插件往宿主设置页贡献一个分组,需 `ui:settings` 权限) */
303
+ export interface SettingsSectionDescriptor {
304
+ id: string
305
+ /** 分组标题的 i18n key,相对插件自身命名空间
306
+ * (宿主按 `${pluginId}.${titleKey}` 解析,与 `context.i18n.t` 同一前缀规则;
307
+ * 未注册该 key 时 vue-i18n 回退显示 key 本身) */
308
+ titleKey: string
309
+ /** SVG path d 属性字符串(Heroicons outline 风格,stroke-width=2,viewBox=0 0 24 24) */
310
+ icon?: string
311
+ /** 排序值,升序排列(越小越靠前),缺省与其余贡献面一致(600)。
312
+ * 与宿主内置分组共用同一排序空间,可指定任意值插入内置分组之间;同值按注册先后排列 */
313
+ order?: number
314
+ /** 分组内容组件:只渲染卡片正文,外层 `<section>` 与标题由宿主统一渲染(保证与内置分组像素一致) */
315
+ component: any
316
+ }
317
+
318
+ /** 状态栏项描述符 */
319
+ export interface StatusBarItemDescriptor {
320
+ id: string
321
+ label: string
322
+ icon?: string
323
+ onClick?: () => void
324
+ }
325
+
326
+ // ==================== 全局弹窗(桌面宿主通用能力) ====================
327
+
328
+ /** 弹窗动作按钮(预设模式,Label 文案由插件经自身 i18n 生成后传入) */
329
+ export interface PluginDialogAction {
330
+ label: string
331
+ /** 视觉变体:默认 / 主按钮 / 危险 / 幽灵 */
332
+ kind?: 'default' | 'primary' | 'danger' | 'ghost'
333
+ /** 点击回调(可异步);成功返回后自动关闭弹窗(抛错则保持打开以便重试) */
334
+ onClick?: () => void | Promise<void>
335
+ /** 点击后经宿主 router 跳转的目标路由(先关弹窗再跳转) */
336
+ navigateTo?: string
337
+ /** 动作进行中禁用(如提交中防重复点击);经 handle.update() 联动 */
338
+ disabled?: boolean
339
+ }
340
+
341
+ /**
342
+ * 全局弹窗选项(宿主统一渲染:遮罩/卡片/z-index/定时关闭/按钮/路由跳转)
343
+ *
344
+ * 两种模式:
345
+ * - 预设模式:title + message + icon + actions,常见「确认/拒绝」类请求开箱即用;
346
+ * - 组件模式:content 传入任意 Vue 组件(经 provide('pluginContext') 渲染),
347
+ * props 可经 handle.update() 热更新。
348
+ * 定时关闭为可选能力:仅当 timeoutSec / deadlineAt 之一提供时生效。
349
+ */
350
+ export interface PluginDialogOptions {
351
+ /** 自定义内容组件(组件模式);缺省用 title/message/icon/actions 预设渲染 */
352
+ content?: any
353
+ /** 内容组件 props(组件模式;handle.update() 可热更新) */
354
+ props?: Record<string, unknown>
355
+ /** 预设模式:标题 */
356
+ title?: string
357
+ /** 预设模式:正文 */
358
+ message?: string
359
+ /** 预设模式:图标(SVG path d,随文字颜色渲染) */
360
+ icon?: string
361
+ /** 预设模式:动作按钮组(缺省无按钮;顺序即展示顺序) */
362
+ actions?: PluginDialogAction[]
363
+ /** 定时自动关闭(可选):相对秒数,从弹窗弹出起算 */
364
+ timeoutSec?: number
365
+ /** 定时自动关闭(可选):绝对截止时间戳 ms(迟到打开 / 排队续算更准确,优先于 timeoutSec) */
366
+ deadlineAt?: number
367
+ /** 倒计时文案模板,{seconds} 占位(如 '{seconds} 秒后自动拒绝');缺省不显示倒计时 */
368
+ countdownLabel?: string
369
+ /** 超时回调(自动关闭前触发);缺省仅关闭 */
370
+ onTimeout?: () => void
371
+ /** 是否可手动关闭(右上角关闭按钮 / Escape / 遮罩点击),默认 true */
372
+ closable?: boolean
373
+ /** 点击遮罩是否关闭,默认 true(closable=false 时无效) */
374
+ closeOnBackdrop?: boolean
375
+ /** 卡片宽度(Tailwind max-w-* 类),默认 max-w-md */
376
+ widthClass?: string
377
+ /** 内容区 padding(Tailwind 类),默认 p-0(组件模式自带内距,预设模式内部处理) */
378
+ bodyClass?: string
379
+ /** 关闭后回调(按钮 / 遮罩 / Escape / 超时 / close() / 排队项被取消 均触发) */
380
+ onClose?: () => void
381
+ }
382
+
383
+ /** 全局弹窗句柄:调用方据此关闭或热更新当前弹窗 */
384
+ export interface PluginDialogHandle {
385
+ /** 关闭当前弹窗(幂等);队列中下一个弹窗自动接替 */
386
+ close(): void
387
+ /** 热更新选项(props / 文案 / 按钮 / 倒计时等) */
388
+ update(options: Partial<PluginDialogOptions>): void
389
+ }
390
+
391
+ /** 输入扩展描述符 */
392
+ export interface InputExtensionDescriptor {
393
+ id: string
394
+ label: string
395
+ icon?: string
396
+ onActivate?: () => void
397
+ }
398
+
399
+ /** 终端工具栏项描述符 */
400
+ export interface TerminalToolbarItemDescriptor {
401
+ id: string
402
+ label: string
403
+ icon?: string
404
+ onClick?: () => void
405
+ }
406
+
407
+ /** 标题栏项描述符 */
408
+ export interface TitleBarItemDescriptor {
409
+ id: string
410
+ label: string
411
+ icon?: string
412
+ onClick?: () => void
413
+ }
414
+
415
+ /** 页面工具栏项描述符 — 注入到指定页面的工具栏页头右操作区 */
416
+ export interface PageToolbarItemDescriptor {
417
+ /** 目标页面标识:sessions / devices / history / plugins / plugin-config / server / settings / terminal */
418
+ target:
419
+ | 'sessions'
420
+ | 'devices'
421
+ | 'history'
422
+ | 'plugins'
423
+ | 'plugin-config'
424
+ | 'server'
425
+ | 'settings'
426
+ | 'terminal'
427
+ id: string
428
+ label: string
429
+ icon?: string
430
+ onClick?: () => void
431
+ }
432
+
433
+ /** 文件处理器描述符 */
434
+ export interface FileHandlerDescriptor {
435
+ id: string
436
+ extensions: string[]
437
+ component: any
438
+ }
439
+
440
+ /** HTTP 请求处理器 */
441
+ export interface RequestHandler {
442
+ (req: { method: string; path: string; body: any; headers: Record<string, string> }): Promise<{
443
+ status: number
444
+ body: any
445
+ }>
446
+ }
447
+
448
+ // ==================== PluginContext API ====================
449
+
450
+ /** 命令注册表 */
451
+ export interface CommandRegistry {
452
+ register(id: string, handler: (...args: any[]) => any): Disposable
453
+ execute(id: string, ...args: any[]): Promise<any>
454
+ }
455
+
456
+ /** 终端 API(需 terminal:* 权限) */
457
+ export interface TerminalAPI {
458
+ sendInput(sessionId: string, text: string): Promise<void>
459
+ onOutput(handler: (sessionId: string, data: string) => void): Disposable
460
+ onInput(handler: (sessionId: string, text: string) => string | null): Disposable
461
+ }
462
+
463
+ /** 会话 API(需 session:* 权限) */
464
+ export interface SessionAPI {
465
+ list(): Promise<any[]>
466
+ get(sessionId: string): Promise<any>
467
+ onStatusChange(handler: (event: any) => void): Disposable
468
+ /**
469
+ * 预测宿主终端窗口的初始网格(宿主窗口几何 + 字体测量 + 整体缩放)。
470
+ *
471
+ * 供插件在启动会话前把 `cols` / `rows` 交给 `create-with-spec`——终端窗口本体、
472
+ * 创建尺寸与渲染管线留宿主(spec D3),预测规则必须与窗口创建规则同源,故留在
473
+ * 宿主一处实现而不在插件复刻。任一环节不可用(非 Tauri 环境 / 字体未就绪)返回
474
+ * `null`,调用方不传尺寸、由宿主兜底默认网格。
475
+ */
476
+ predictTerminalSize(): Promise<{ cols: number; rows: number } | null>
477
+ /**
478
+ * 打开(或聚焦)宿主终端窗口——宿主既有路由深链 `/terminal-window/:sessionId`。
479
+ *
480
+ * 窗口几何、贴靠、就绪事件与关闭一律留宿主;插件只触发,不自建窗口、不自带渲染管线。
481
+ *
482
+ * @returns `true` = 新建窗口(尚在就绪中,调用方宜显示 loading);`false` = 既有窗口已聚焦
483
+ */
484
+ openTerminal(session: { id: string; name: string }): Promise<boolean>
485
+ /**
486
+ * 关闭宿主终端窗口(幂等:窗口不存在时静默返回)。
487
+ *
488
+ * 会话停止 / 删除时由调用方触发——「何时该关窗」是插件侧的编排决策。
489
+ */
490
+ closeTerminal(sessionId: string): Promise<void>
491
+ /**
492
+ * 该会话是否已有打开的终端窗口(宿主窗口登记事实,同步)。
493
+ *
494
+ * 调用方据此决定「先聚焦(无需 loading)还是新建(显示就绪 loading)」——
495
+ * 与宿主会话页原行为同口径。
496
+ */
497
+ isTerminalOpen(sessionId: string): boolean
498
+ }
499
+
500
+ /** UI 注册表(需 ui:* 权限) */
501
+ export interface UIRegistry {
502
+ registerSidebarPanel(panel: SidebarPanelDescriptor): Disposable
503
+ registerToolboxPage(page: ToolboxPageDescriptor): Disposable
504
+ /**
505
+ * 注册一个可由插件页路由直达、但**不进入侧边栏菜单**的页面
506
+ * (viewType 'page',宿主全量注册表可见、sidebar/toolbox 菜单投影不含)。
507
+ * 仍经 `/plugin/sidebar/:pluginId/:viewId` 路由渲染——适合「从某页内进入的
508
+ * 二级页面 / 深链直达」场景(票 14 收尾:连接历史不再占侧边栏,改经设备列表入口)。
509
+ * order 字段在非菜单页面无排序意义,可省略。
510
+ */
511
+ registerPage(page: SidebarPanelDescriptor): Disposable
512
+ registerStatusBarItem(item: StatusBarItemDescriptor): Disposable
513
+ registerInputExtension(ext: InputExtensionDescriptor): Disposable
514
+ registerTerminalToolbarItem(item: TerminalToolbarItemDescriptor): Disposable
515
+ registerTitleBarItem(item: TitleBarItemDescriptor): Disposable
516
+ registerPageToolbarItem(item: PageToolbarItemDescriptor): Disposable
517
+ registerFileHandler(handler: FileHandlerDescriptor): Disposable
518
+ /** 往宿主设置页贡献一个分组(见 SettingsSectionDescriptor;权限 ui:settings) */
519
+ registerSettingsSection(section: SettingsSectionDescriptor): Disposable
520
+ /** 全局弹窗(宿主统一渲染遮罩/卡片/倒计时/按钮/路由跳转;见 PluginDialogOptions) */
521
+ showDialog(options: PluginDialogOptions): PluginDialogHandle
522
+ }
523
+
524
+ /** 事件 API */
525
+ export interface EventAPI {
526
+ on(event: string, handler: (...args: any[]) => void): Disposable
527
+ emit(event: string, ...args: any[]): void
528
+ }
529
+
530
+ /** 存储 API(默认授予) */
531
+ export interface StorageAPI {
532
+ get<T = any>(key: string): Promise<T | undefined>
533
+ set(key: string, value: any): Promise<void>
534
+ delete(key: string): Promise<void>
535
+ flush(): Promise<void>
536
+ }
537
+
538
+ /** HTTP API(需 network:http 权限) */
539
+ export interface HttpAPI {
540
+ registerEndpoint(path: string, handler: RequestHandler): Disposable
541
+ }
542
+
543
+ /** 国际化 API — 插件访问宿主 i18n 能力 */
544
+ export interface I18nAPI {
545
+ /** 获取宿主 i18n 实例(vue-i18n I18n 对象) */
546
+ getI18n(): any
547
+ /** 注册插件翻译到宿主 i18n(自动添加插件 ID 前缀隔离) */
548
+ registerMessages(locale: string, messages: Record<string, unknown>): void
549
+ /** 翻译快捷方法(自动添加插件 ID 前缀) */
550
+ t(key: string, params?: Record<string, unknown>): string
551
+ }
552
+
553
+ /** 插件上下文 — 插件访问宿主能力的唯一通道 */
554
+ export interface PluginContext {
555
+ readonly id: string
556
+ readonly extensionPath: string
557
+ readonly commands: CommandRegistry
558
+ readonly terminal: TerminalAPI
559
+ readonly session: SessionAPI
560
+ readonly ui: UIRegistry
561
+ readonly events: EventAPI
562
+ readonly storage: StorageAPI
563
+ readonly http: HttpAPI
564
+ /** 国际化 API */
565
+ readonly i18n: I18nAPI
566
+ /** 内部:所有 Disposable 收集器 */
567
+ readonly _disposables: Disposable[]
568
+ }
569
+
570
+ /** 插件入口模块约定 */
571
+ export interface PluginModule {
572
+ activate(context: PluginContext): Promise<void>
573
+ deactivate?: () => Promise<void>
574
+ /** dev-shell 领域种子数据(见 PluginDevMock);真实宿主忽略,无需条件编译 */
575
+ devMock?: PluginDevMock
576
+ }
577
+
578
+ // ==================== devMock 协议(dev-shell 领域种子数据) ====================
579
+ //
580
+ // 种子数据由插件工程持有(入口导出 devMock),dev-shell 只做通用接线:
581
+ // loader 按 pluginId 注册,mock 命令实现消费种子返回演示值。
582
+ // 真实宿主忽略多余导出,与移动端 SDK 同构。
583
+ //
584
+ // SDK 只约定「入口导出 devMock」的通用容器协议,不感知任何插件领域细节:
585
+ // 各插件自有类型(文件传输对等/传输域种子等)由插件工程自行定义,
586
+ // dev-shell 消费时 cast 到插件自有形状。
587
+
588
+ /** 插件 dev-shell 演示数据(通用容器;具体子域类型由各插件工程持有) */
589
+ export type PluginDevMock = Record<string, unknown>
590
+
591
+ /** 插件运行时状态
592
+ *
593
+ * 线协议真源 = 共享内核 crate `packages/wasmnest-wasm-core/src/manifest.rs` 的
594
+ * `PluginState`(`#[serde(tag = "state", rename_all = "camelCase")]`)——宿主命令返回
595
+ * 的 JSON 是 camelCase(`{state:'activated'}` / `{state:'needsApproval'}` …),
596
+ * 插件前端消费状态时必须按线上值分支。
597
+ */
598
+ export type PluginState =
599
+ | { state: 'loaded' }
600
+ | { state: 'activating' }
601
+ | { state: 'activated' }
602
+ | { state: 'degraded'; error: string }
603
+ | { state: 'needsApproval' }
604
+ | { state: 'error'; error: string }
605
+ | { state: 'deactivated' }
606
+
607
+ /** 插件信息(从后端获取) */
608
+ export interface PluginInfo {
609
+ id: string
610
+ name: string
611
+ version: string
612
+ description: string
613
+ author: string
614
+ main: string
615
+ pluginType: PluginType
616
+ /** WASM 库文件名(仅 rust-ts 类型插件使用) */
617
+ rustLibrary?: string
618
+ permissions: string[]
619
+ state: PluginState
620
+ extensionPath: string
621
+ contributes: PluginContributes
622
+ /** 插件图标(manifest.icon 透传,可为空) */
623
+ icon?: string
624
+ /** 插件来源:builtin / scanned / wasm */
625
+ source: string
626
+ /** 插件目录总大小(字节) */
627
+ sizeBytes: number
628
+ /** 安装时间(unix 毫秒,plugin.json mtime) */
629
+ installedAt?: number
630
+ }