@binblink/wasmnest-plugin-sdk-desktop 0.0.1 → 0.0.2

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