@linkdesk/plugin-sdk 0.1.73 → 0.1.75

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,179 +1,179 @@
1
- # @linkdesk/plugin-sdk
2
-
3
- The LinkDesk plugin author SDK — the counterpart to `@types/vscode`: install one package and get **`window.linkdesk.*` type hints + one-command builds of `.linkdesk-plugin` + plugin.json validation**. Zero dependency on the shell source.
4
-
5
- > The source of truth for types = `@linkdesk/contracts` (this package re-exports it and does not copy the generated artifact — contract drift → your tsc turns red immediately).
6
- > Plugin authors always write code against `window.linkdesk.*` (injected by the preload); **`import @src/core` is forbidden**.
7
-
8
- ## Installation
9
-
10
- ```bash
11
- npm install -D @linkdesk/plugin-sdk
12
- ```
13
-
14
- ## API cheat sheet
15
-
16
- <!-- BEGIN API-CHEATSHEET -->
17
-
18
- > 自动生成,**勿手改**——由 `scripts/generate-api-cheatsheet.mjs` 从 `@linkdesk/contracts` 的 `linkdesk.d.ts` 现读产出,
19
- > `npm run check` 机械盯漂。完整签名与逐方法说明见 `linkdesk.d.ts` 本体(IDE 里可直接跳转)。
20
-
21
- **16 个域接口 → 47 个命名空间 / 255 个方法**,全部经 `window.linkdesk.<命名空间>.<方法>` 调用。 (plus 1 deprecated alias/es `config`, not counted twice)
22
-
23
- | Namespace | Methods | Method | Notes |
24
- |:--|:--:|:--|:--|
25
- | `commands` | 5 | `execute` `executeCommand` `registerCommand` `unregisterCommands` `getCommands` | 命令——对标 VS Code vscode.commands |
26
- | `configuration` | 15 | `get` `set` `getSchema` `onChange` `getConfigurationContributions` `inspectConfiguration` `getUserSettings` `onDidChangeConfiguration` `onPluginLifecycleChange` `consumeSettingsGroup` `onRequestSettingsGroup` `consumeScrollToSetting` `onRequestScrollToSetting` `consumeOpenKeybindings` `onRequestOpenKeybindings` | 配置—新名——对标 VS Code vscode.workspace.getConfiguration |
27
- | `config` | 15 | (废弃别名 → `configuration`) | @deprecated 向后兼容别名,新代码用 configuration |
28
- | `theme` | 11 | `getCurrent` `getAvailable` `apply` `listRecipes` `getActive` `getEffectiveTokens` `setRecipe` `setColorway` `resetAppearance` `resetMix` `getBaselineSeeds` | —— |
29
- | `language` | 5 | `getCurrent` `getAvailable` `set` `getInitial` `onChange` | —— |
30
- | `appearance` | 2 | `importImage` `revealStorage` | 外观资产——本地选图拷贝入库(受控来源——用户任选路径不能 file:// 直读) |
31
- | `storage` ⚠️ | 2 | `revealCache` `cacheDir` | —— |
32
- | `tabs` | 9 | `create` `openOrFocus` `focus` `close` `focusBySourceId` `updateLabelBySourceId` `closeBySourceId` `onDidChangeActiveTab` `list` | —— |
33
- | `keybindings` | 12 | `getKeybindings` `getConflicts` `registerKeybinding` `saveUserKeybindings` `removeKeybindingForCommand` `resetKeybindingToDefault` `findKeybindingForCommand` `setKeybindingCaptureActive` `keyboardEventToKeyString` `onChange` `syncToMainProcess`° `onForwardedEvent`° | —— |
34
- | `notifications` | 3 | `show` `list` `subscribe` | 通知——插件弹通知(唯一通知面 = 铃铛宽通知面板,右下窄卡链路已整删),对标 VS Code vscode.wind… |
35
- | `menu` | 2 | `registerItems` `getItems` | 菜单——插件声明式读写 |
36
- | `contextKey` | 1 | `set` | ContextKey——插件 SET 状态供壳 when 子句读 |
37
- | `dialog` | 5 | `confirm` `alert` `open` `openFile` `confirmContent` | 弹窗——确认/提示/文件选择 |
38
- | `quickPick` | 1 | `show` | 插件 quickPick 选择器——池内本地桥(零 IPC,QuickPickHost 渲染) |
39
- | `quickPickHost` | 6 | `registerHost` `onShow` `select` `highlight` `close` `itemAction` | QuickPick 宿主渲染桥——池 QuickPickHost 消费(壳 preload 无此面) |
40
- | `dialogHost` | 5 | `onShow` `current` `pending` `confirm` `cancel` | Dialog 哑渲染订阅——池 DialogHost 消费(壳 preload 无此面) |
41
- | `floatingPanelHost` | 4 | `onShow` `action` `registerBoundsHost` `getBounds` | (类型 B):悬浮面板哑渲染订阅——池 FloatingPanelHost 消费(壳 preload 无此面) |
42
- | `serial` | 11 | `listPorts` `getStatus` `openPort` `closePort` `sendData` `sendText` `setDtr` `setRts` `onData` `onStats` `onSystem` | 串口——读/写/监听,对标 VS Code SerialPort API |
43
- | `clipboard` | 3 | `readText` `writeText` `writeFileList` | 剪贴板——读/写系统剪贴板 |
44
- | `p2p` | 2 | `send` `on` | p2p 插件间定向推流——和 bridge.broadcast 同模式(fire-and-forget) |
45
- | `events` | 4 | `on` `emit` `heartbeat`° `notifyTheme`° | 通用事件订阅 + 发布——插件间数据管道 |
46
- | `pluginState` | 3 | `get` `set` `onChange` | 插件持久化存储——集中缓存 + 文件持久化 |
47
- | `workspace` | 8 | `getFolders` `getActive` `setActive` `openFolder` `addFolder` `removeFolder` `onDidChangeFolders` `onDidChangeActiveWorkspace` | 工作区——池 preload 注入(壳侧经 WorkspaceService 直用) |
48
- | `filesystem` | 12 | `readTextFile` `writeTextFile` `exists` `createDir` `copy` `rename` `remove` `listDir` `readBinaryFile` `writeBinaryFile` `watch` `readdir`° | 文件系统——插件读写(路径校验由主进程执行) |
49
- | `path` | 6 | `appDataDir`° `normalize` `join` `basename` `dirname` `extname` | 路径工具——壳/池双端注入(editor/file-tree 池插件消费 normalize/join 等) |
50
- | `env` | 1 | `get` | 环境信息——对标 VS Code ExtensionContext |
51
- | `search` | 1 | `searchFiles` | 文件搜索——全文搜索/替换(IPC 到壳/主进程执行) |
52
- | `encoding` | 4 | `detect` `decode` `encode` `isBinary` | 编码检测/转换(主进程 EncodingService) |
53
- | `decorations` | 4 | `registerProvider` `unregisterProvider` `getDecoration` `onDidChange` | 文件装饰——池内本地注册表(零 IPC) |
54
- | `fileAssociation` | 1 | `getPluginFor` | 文件关联——扩展名→插件 ID(主进程 FileAssociationService 直答) |
55
- | `langDef` | 1 | `get` | langDef——语言定义注册表(主进程直答) |
56
- | `lsp` | 4 | `spawn` `write` `dispose` `onData` | LSP 桥——自动补全/F12/诊断/重命名 |
57
- | `protocol` | 3 | `listProtocols` `getActiveProtocolId` `setActiveProtocolId` | protocol——协议注册表(主进程直答) |
58
- | `viewContainer` | 4 | `getViewContainer` `getViews` `getView` `registerView` | viewContainer——真 IPC 查询/更新(问壳侧注册表) |
59
- | `plugins` | 14 | `resolvePath` `resolveEntry`° `getCompatibility`° `listDirs`° `listAll`° `listDisabledDirs`° `readManifest`° `readAllManifests`° `packageDownload`° `packageExtract`° `packageCancel`° `packageUpdateCheck`° `packageStageUpdate`° `packageCommitUpdate`° | 插件发现——双端注入:resolvePath 双端同面 |
60
- | `pluginManager` | 13 | `list` `enable` `disable` `uninstall` `install` `installWithProgress`° `reinstall` `getDisabled` `getUninstalled` `isDisabled` `update`° `checkUpdates`° `notifyManifestChanged`° | 插件管理——桥接 IpcBridgeHandler → loader 函数 |
61
- | `bridge` ⚠️ | 4 | `onRequest` `respond` `broadcast` `notifyConfigChanged` | 壳↔插件通信中继——壳 preload 独有 |
62
- | `pool` | 32 | `pushLayout` `onReady` `toggleDevTools` `onSidebarAction` `onTabAction` `onTabBarRects` `onDragPosition` `pushAdsorbHint` `onAdsorbIndex` `pushQuickPick` `onQuickPickAction` `pushDialog` `onDialogAction` `pushFloatingPanel` `onFloatingPanelAction` `onMemoryPressure` `createWindow` `closeWindow` `onWindowClosed` `onWindowBoundsChanged` `getLayout` `onLayout` `ready` `sidebarAction` `tabAction` `tabBarRects` `dragPosition` `onAdsorbHint` `adsorbIndex` `registerBeforeClose` `unregisterBeforeClose` `beforeClose` | 池控制——壳 preload:推送布局 + 注册池→壳动作回调 |
63
- | `window` | 11 | `minimize` `maximize` `unmaximize` `close` `setZoom` `toggleDevTools` `isMaximized` `onMaximizeChange` `setAlwaysOnTop` `isAlwaysOnTop` `onAlwaysOnTopChange` | 窗口控制——TitleBar 按钮映射,双端注入(11 方法同通道,共享模块 electron/window-name… |
64
- | `shell` | 6 | `showItemInFolder` `openInTerminal` `pluginLocation` `openPluginFolder` `startDrag` `relaunch`° | 壳级命令——revealInOS / openInTerminal / startDrag / relaunch,双端… |
65
- | `hotExit` ⚠️ | 3 | `save` `load` `clear` | 热退出暂存——编辑器未保存内容落盘 |
66
- | `getFilePath` | 0 | (top-level function)`getFilePath: (file: File) => string;` | OS 拖入文件路径获取——双端注入 |
67
- | `panel` | 3 | `reveal` `revealFloating` `setFloatingBounds` | —— |
68
- | `settings` | 3 | `list` `getActive` `setActive` | —— |
69
- | `factorySlots` | 4 | `listRoles` `list` `getActive` `setActive` | —— |
70
- | `app` | 1 | `getVersion` | app 命名空间——只读产品身份 |
71
- | `update` | 1 | `getState` | update 命名空间——只读更新状态(供「关于」类插件读宿主版本/更新态) |
72
-
73
- ⚠️ = optional namespace in the contract (injected on one side only): `storage` `bridge` `hotExit` — check for existence before calling; on the other side it is undefined.
74
- ° = member marked `?` in the contract: injected in one side's preload only (almost always shell-side). **Your plugin runs in the pool** — check for existence before calling.
75
-
76
- <!-- END API-CHEATSHEET -->
77
-
78
- ## Usage
79
-
80
- ### 1. tsconfig — give `window.linkdesk.` its types
81
-
82
- ```jsonc
83
- {
84
- "compilerOptions": {
85
- "types": ["@linkdesk/plugin-sdk"], // the global window.linkdesk declarations come in with the contracts
86
- "jsx": "react-jsx"
87
- }
88
- }
89
- ```
90
-
91
- Create no global.d.ts at all. In `.ts`/`.tsx`, `window.linkdesk.tabs.create({...})` gets parameter and return type checking directly.
92
-
93
- ### 2. plugin.json — declare the plugin (required `name` + `version`; comments and trailing commas allowed)
94
-
95
- ```jsonc
96
- {
97
- "name": "My Plugin", // display name
98
- "version": "1.0.0",
99
- "entry": "src/index.tsx", // required for view/card/protocol plugins
100
- "contributes": { "i18n": { "en": "i18n/en.json" } }
101
- }
102
- ```
103
-
104
- ### 3. Build — produce the `.linkdesk-plugin` distributable
105
-
106
- ```bash
107
- npm run build # the package ships its own bin; equivalent to linkdesk-plugin-sdk build
108
- ```
109
-
110
- The build does all of this automatically: **validate plugin.json → Vite bundles `src/index.tsx` into `index.bundle.js` → gather manifest/icons/i18n/README into `dist/<id>.linkdesk-plugin/` → zip it into `<id>.linkdesk-plugin` at the project root**.
111
-
112
- - `react` / `react-dom` / `react-i18next` / `i18next` are provided by the shell and are **not bundled** — every other dependency is inlined, so plugins are self-contained.
113
- - Plugin id = the `pluginId` field of `plugin.json`; if it is not declared, the **project directory name** is used as a fallback (matching the shell's loading contract).
114
- - To customize the entry, output directory, or extra externals:
115
- ```js
116
- // vite.config.ts
117
- import { defineLinkdeskPluginConfig } from "@linkdesk/plugin-sdk";
118
- export default defineLinkdeskPluginConfig({ entry: "src/index.tsx", outDir: "dist" });
119
- ```
120
-
121
- ### Standalone validation
122
-
123
- ```bash
124
- npm run validate # or linkdesk-plugin-sdk validate ./plugin.json
125
- ```
126
-
127
- ### Theme/icon data file schemas (the npm channel for theme and icon authors)
128
-
129
- `schemas/theme.schema.json` + `schemas/icon-theme.schema.json` ship with the package (kept byte-synced with the repository's `public/schemas/`; drift is caught by `check-plugin-schema-sync`). Theme and icon authors reference `$schema` on the first line of their data JSON to get IntelliSense:
130
-
131
- ```jsonc
132
- // themes/my-glass.json (relative to the plugin root)
133
- {
134
- "$schema": "./node_modules/@linkdesk/plugin-sdk/schemas/theme.schema.json",
135
- // …
136
- }
137
- ```
138
-
139
- Data files are **not JSONC** (strict JSON, loaded by the same engine). At build time or in CI, the validate family can catch format errors (the same schema files the repository's `check-theme-schema.mjs` uses, so the rules never drift):
140
-
141
- ```js
142
- import { validateThemeJson, validateIconThemeJson } from "@linkdesk/plugin-sdk";
143
-
144
- validateThemeJson("themes/my-glass.json"); // theme.schema.json
145
- validateIconThemeJson("icons/my-icons.json"); // icon-theme.schema.json (dual-form contract for the match table)
146
- ```
147
-
148
- ### index.bundle.js conventions
149
-
150
- The bundle `export default`s a React component — the shell renders it with `{ isActive }`:
151
-
152
- ```tsx
153
- export default function MyView({ isActive }: { isActive: boolean }) {
154
- return <div>Hello LinkDesk</div>;
155
- }
156
- ```
157
-
158
- ## Limitations
159
-
160
- - **dev preview** (source glob loading inside the shell) parses plugin.json as strict JSON; this SDK's validate tolerating comments/trailing commas is a publish-time capability — if a plugin needs to run in dev preview, keep plugin.json free of comments.
161
- - Dropping a commented plugin.json straight into the shell's `plugins/` dev directory breaks preview loading (jsonc support on the shell side is still to come).
162
-
163
- ## Maintaining this package (LinkDesk maintainers)
164
-
165
- This package is **one of the five author axes** (the others: `@linkdesk/contracts` / `create-linkdesk-plugin` / `@linkdesk/ui` / `@linkdesk/plugin-docs`) and has its own version axis — **publishing it does not bump the application, and the application does not bump it**.
166
-
167
- Its surface is `src/**` + `schemas/**` + `dev-host/**` + this README: change any of them and the version must be bumped and published, otherwise plugin authors keep building against the old CLI/schemas.
168
-
169
- ```bash
170
- # 1. bump packages/plugin-sdk/package.json version (0.x backward-compatible → patch)
171
- # 2. build the dist the publish channel ships (npm run build, inside the package)
172
- # 3. publish
173
- npm publish --registry=https://registry.npmjs.org # 🔴 the registry flag is mandatory — the machine default is a read-only mirror
174
- # 4. record the baseline (run in the LinkDesk repo root)
175
- npm run release:mark
176
- ```
177
-
178
- > 🔴 The shelf read has a **~3 minute replication delay** (`contracts` is visible within seconds, `plugin-sdk` takes minutes) — do **not** re-publish on a 404, npm will reject the duplicate version.
179
- > Full procedure + all three measured pitfalls → **`docs/06-发布管理/作者轴npm发版.md`** in the LinkDesk repository.
1
+ # @linkdesk/plugin-sdk
2
+
3
+ The LinkDesk plugin author SDK — the counterpart to `@types/vscode`: install one package and get **`window.linkdesk.*` type hints + one-command builds of `.linkdesk-plugin` + plugin.json validation**. Zero dependency on the shell source.
4
+
5
+ > The source of truth for types = `@linkdesk/contracts` (this package re-exports it and does not copy the generated artifact — contract drift → your tsc turns red immediately).
6
+ > Plugin authors always write code against `window.linkdesk.*` (injected by the preload); **`import @src/core` is forbidden**.
7
+
8
+ ## Installation
9
+
10
+ ```bash
11
+ npm install -D @linkdesk/plugin-sdk
12
+ ```
13
+
14
+ ## API cheat sheet
15
+
16
+ <!-- BEGIN API-CHEATSHEET -->
17
+
18
+ > 自动生成,**勿手改**——由 `scripts/generate-api-cheatsheet.mjs` 从 `@linkdesk/contracts` 的 `linkdesk.d.ts` 现读产出,
19
+ > `npm run check` 机械盯漂。完整签名与逐方法说明见 `linkdesk.d.ts` 本体(IDE 里可直接跳转)。
20
+
21
+ **16 个域接口 → 47 个命名空间 / 256 个方法**,全部经 `window.linkdesk.<命名空间>.<方法>` 调用。 (plus 1 deprecated alias/es `config`, not counted twice)
22
+
23
+ | Namespace | Methods | Method | Notes |
24
+ |:--|:--:|:--|:--|
25
+ | `commands` | 5 | `execute` `executeCommand` `registerCommand` `unregisterCommands` `getCommands` | 命令——对标 VS Code vscode.commands |
26
+ | `configuration` | 15 | `get` `set` `getSchema` `onChange` `getConfigurationContributions` `inspectConfiguration` `getUserSettings` `onDidChangeConfiguration` `onPluginLifecycleChange` `consumeSettingsGroup` `onRequestSettingsGroup` `consumeScrollToSetting` `onRequestScrollToSetting` `consumeOpenKeybindings` `onRequestOpenKeybindings` | 配置—新名——对标 VS Code vscode.workspace.getConfiguration |
27
+ | `config` | 15 | (废弃别名 → `configuration`) | @deprecated 向后兼容别名,新代码用 configuration |
28
+ | `theme` | 11 | `getCurrent` `getAvailable` `apply` `listRecipes` `getActive` `getEffectiveTokens` `setRecipe` `setColorway` `resetAppearance` `resetMix` `getBaselineSeeds` | —— |
29
+ | `language` | 5 | `getCurrent` `getAvailable` `set` `getInitial` `onChange` | —— |
30
+ | `appearance` | 2 | `importImage` `revealStorage` | 外观资产——本地选图拷贝入库(受控来源——用户任选路径不能 file:// 直读) |
31
+ | `storage` ⚠️ | 2 | `revealCache` `cacheDir` | —— |
32
+ | `tabs` | 9 | `create` `openOrFocus` `focus` `close` `focusBySourceId` `updateLabelBySourceId` `closeBySourceId` `onDidChangeActiveTab` `list` | —— |
33
+ | `keybindings` | 13 | `getKeybindings` `getConflicts` `registerKeybinding` `saveUserKeybindings` `removeKeybindingForCommand` `resetKeybindingToDefault` `clearKeybindingForCommand` `findKeybindingForCommand` `setKeybindingCaptureActive` `keyboardEventToKeyString` `onChange` `syncToMainProcess`° `onForwardedEvent`° | —— |
34
+ | `notifications` | 3 | `show` `list` `subscribe` | 通知——插件弹通知(唯一通知面 = 铃铛宽通知面板,右下窄卡链路已整删),对标 VS Code vscode.wind… |
35
+ | `menu` | 2 | `registerItems` `getItems` | 菜单——插件声明式读写 |
36
+ | `contextKey` | 1 | `set` | ContextKey——插件 SET 状态供壳 when 子句读 |
37
+ | `dialog` | 5 | `confirm` `alert` `open` `openFile` `confirmContent` | 弹窗——确认/提示/文件选择 |
38
+ | `quickPick` | 1 | `show` | 插件 quickPick 选择器——池内本地桥(零 IPC,QuickPickHost 渲染) |
39
+ | `quickPickHost` | 6 | `registerHost` `onShow` `select` `highlight` `close` `itemAction` | QuickPick 宿主渲染桥——池 QuickPickHost 消费(壳 preload 无此面) |
40
+ | `dialogHost` | 5 | `onShow` `current` `pending` `confirm` `cancel` | Dialog 哑渲染订阅——池 DialogHost 消费(壳 preload 无此面) |
41
+ | `floatingPanelHost` | 4 | `onShow` `action` `registerBoundsHost` `getBounds` | (类型 B):悬浮面板哑渲染订阅——池 FloatingPanelHost 消费(壳 preload 无此面) |
42
+ | `serial` | 11 | `listPorts` `getStatus` `openPort` `closePort` `sendData` `sendText` `setDtr` `setRts` `onData` `onStats` `onSystem` | 串口——读/写/监听,对标 VS Code SerialPort API |
43
+ | `clipboard` | 3 | `readText` `writeText` `writeFileList` | 剪贴板——读/写系统剪贴板 |
44
+ | `p2p` | 2 | `send` `on` | p2p 插件间定向推流——和 bridge.broadcast 同模式(fire-and-forget) |
45
+ | `events` | 4 | `on` `emit` `heartbeat`° `notifyTheme`° | 通用事件订阅 + 发布——插件间数据管道 |
46
+ | `pluginState` | 3 | `get` `set` `onChange` | 插件持久化存储——集中缓存 + 文件持久化 |
47
+ | `workspace` | 8 | `getFolders` `getActive` `setActive` `openFolder` `addFolder` `removeFolder` `onDidChangeFolders` `onDidChangeActiveWorkspace` | 工作区——池 preload 注入(壳侧经 WorkspaceService 直用) |
48
+ | `filesystem` | 12 | `readTextFile` `writeTextFile` `exists` `createDir` `copy` `rename` `remove` `listDir` `readBinaryFile` `writeBinaryFile` `watch` `readdir`° | 文件系统——插件读写(路径校验由主进程执行) |
49
+ | `path` | 6 | `appDataDir`° `normalize` `join` `basename` `dirname` `extname` | 路径工具——壳/池双端注入(editor/file-tree 池插件消费 normalize/join 等) |
50
+ | `env` | 1 | `get` | 环境信息——对标 VS Code ExtensionContext |
51
+ | `search` | 1 | `searchFiles` | 文件搜索——全文搜索/替换(IPC 到壳/主进程执行) |
52
+ | `encoding` | 4 | `detect` `decode` `encode` `isBinary` | 编码检测/转换(主进程 EncodingService) |
53
+ | `decorations` | 4 | `registerProvider` `unregisterProvider` `getDecoration` `onDidChange` | 文件装饰——池内本地注册表(零 IPC) |
54
+ | `fileAssociation` | 3 | `getPluginFor` `listHandlersFor` `setDefault` | 文件关联——扩展名→插件 ID(主进程 FileAssociationService 直答)。`getPluginFor` 已升级为覆盖表感知的完整解析(用户覆盖表 → 声明表 → 角色兜底);`listHandlersFor` 列全部声明者+当前默认标记(「打开方式」选择器数据源);`setDefault(ext, pluginId\|null)` = 覆盖表唯一写口(null = 恢复自动,写后 `configuration.onChange("workbench.fileAssociations")` 即时广播) |
55
+ | `langDef` | 1 | `get` | langDef——语言定义注册表(主进程直答) |
56
+ | `lsp` | 4 | `spawn` `write` `dispose` `onData` | LSP 桥——自动补全/F12/诊断/重命名 |
57
+ | `protocol` | 3 | `listProtocols` `getActiveProtocolId` `setActiveProtocolId` | protocol——协议注册表(主进程直答) |
58
+ | `viewContainer` | 4 | `getViewContainer` `getViews` `getView` `registerView` | viewContainer——真 IPC 查询/更新(问壳侧注册表) |
59
+ | `plugins` | 14 | `resolvePath` `resolveEntry`° `getCompatibility`° `listDirs`° `listAll`° `listDisabledDirs`° `readManifest`° `readAllManifests`° `packageDownload`° `packageExtract`° `packageCancel`° `packageUpdateCheck`° `packageStageUpdate`° `packageCommitUpdate`° | 插件发现——双端注入:resolvePath 双端同面 |
60
+ | `pluginManager` | 13 | `list` `enable` `disable` `uninstall` `install` `installWithProgress`° `reinstall` `getDisabled` `getUninstalled` `isDisabled` `update`° `checkUpdates`° `notifyManifestChanged`° | 插件管理——桥接 IpcBridgeHandler → loader 函数 |
61
+ | `bridge` ⚠️ | 4 | `onRequest` `respond` `broadcast` `notifyConfigChanged` | 壳↔插件通信中继——壳 preload 独有 |
62
+ | `pool` | 32 | `pushLayout` `onReady` `toggleDevTools` `onSidebarAction` `onTabAction` `onTabBarRects` `onDragPosition` `pushAdsorbHint` `onAdsorbIndex` `pushQuickPick` `onQuickPickAction` `pushDialog` `onDialogAction` `pushFloatingPanel` `onFloatingPanelAction` `onMemoryPressure` `createWindow` `closeWindow` `onWindowClosed` `onWindowBoundsChanged` `getLayout` `onLayout` `ready` `sidebarAction` `tabAction` `tabBarRects` `dragPosition` `onAdsorbHint` `adsorbIndex` `registerBeforeClose` `unregisterBeforeClose` `beforeClose` | 池控制——壳 preload:推送布局 + 注册池→壳动作回调 |
63
+ | `window` | 11 | `minimize` `maximize` `unmaximize` `close` `setZoom` `toggleDevTools` `isMaximized` `onMaximizeChange` `setAlwaysOnTop` `isAlwaysOnTop` `onAlwaysOnTopChange` | 窗口控制——TitleBar 按钮映射,双端注入(11 方法同通道,共享模块 electron/window-name… |
64
+ | `shell` | 6 | `showItemInFolder` `openInTerminal` `pluginLocation` `openPluginFolder` `startDrag` `relaunch`° | 壳级命令——revealInOS / openInTerminal / startDrag / relaunch,双端… |
65
+ | `hotExit` ⚠️ | 3 | `save` `load` `clear` | 热退出暂存——编辑器未保存内容落盘 |
66
+ | `getFilePath` | 0 | (top-level function)`getFilePath: (file: File) => string;` | OS 拖入文件路径获取——双端注入 |
67
+ | `panel` | 3 | `reveal` `revealFloating` `setFloatingBounds` | —— |
68
+ | `settings` | 3 | `list` `getActive` `setActive` | —— |
69
+ | `factorySlots` | 4 | `listRoles` `list` `getActive` `setActive` | —— |
70
+ | `app` | 1 | `getVersion` | app 命名空间——只读产品身份 |
71
+ | `update` | 1 | `getState` | update 命名空间——只读更新状态(供「关于」类插件读宿主版本/更新态) |
72
+
73
+ ⚠️ = optional namespace in the contract (injected on one side only): `storage` `bridge` `hotExit` — check for existence before calling; on the other side it is undefined.
74
+ ° = member marked `?` in the contract: injected in one side's preload only (almost always shell-side). **Your plugin runs in the pool** — check for existence before calling.
75
+
76
+ <!-- END API-CHEATSHEET -->
77
+
78
+ ## Usage
79
+
80
+ ### 1. tsconfig — give `window.linkdesk.` its types
81
+
82
+ ```jsonc
83
+ {
84
+ "compilerOptions": {
85
+ "types": ["@linkdesk/plugin-sdk"], // the global window.linkdesk declarations come in with the contracts
86
+ "jsx": "react-jsx"
87
+ }
88
+ }
89
+ ```
90
+
91
+ Create no global.d.ts at all. In `.ts`/`.tsx`, `window.linkdesk.tabs.create({...})` gets parameter and return type checking directly.
92
+
93
+ ### 2. plugin.json — declare the plugin (required `name` + `version`; comments and trailing commas allowed)
94
+
95
+ ```jsonc
96
+ {
97
+ "name": "My Plugin", // display name
98
+ "version": "1.0.0",
99
+ "entry": "src/index.tsx", // required for view/card/protocol plugins
100
+ "contributes": { "i18n": { "en": "i18n/en.json" } }
101
+ }
102
+ ```
103
+
104
+ ### 3. Build — produce the `.linkdesk-plugin` distributable
105
+
106
+ ```bash
107
+ npm run build # the package ships its own bin; equivalent to linkdesk-plugin-sdk build
108
+ ```
109
+
110
+ The build does all of this automatically: **validate plugin.json → Vite bundles `src/index.tsx` into `index.bundle.js` → gather manifest/icons/i18n/README into `dist/<id>.linkdesk-plugin/` → zip it into `<id>.linkdesk-plugin` at the project root**.
111
+
112
+ - `react` / `react-dom` / `react-i18next` / `i18next` are provided by the shell and are **not bundled** — every other dependency is inlined, so plugins are self-contained.
113
+ - Plugin id = the `pluginId` field of `plugin.json`; if it is not declared, the **project directory name** is used as a fallback (matching the shell's loading contract).
114
+ - To customize the entry, output directory, or extra externals:
115
+ ```js
116
+ // vite.config.ts
117
+ import { defineLinkdeskPluginConfig } from "@linkdesk/plugin-sdk";
118
+ export default defineLinkdeskPluginConfig({ entry: "src/index.tsx", outDir: "dist" });
119
+ ```
120
+
121
+ ### Standalone validation
122
+
123
+ ```bash
124
+ npm run validate # or linkdesk-plugin-sdk validate ./plugin.json
125
+ ```
126
+
127
+ ### Theme/icon data file schemas (the npm channel for theme and icon authors)
128
+
129
+ `schemas/theme.schema.json` + `schemas/icon-theme.schema.json` ship with the package (kept byte-synced with the repository's `public/schemas/`; drift is caught by `check-plugin-schema-sync`). Theme and icon authors reference `$schema` on the first line of their data JSON to get IntelliSense:
130
+
131
+ ```jsonc
132
+ // themes/my-glass.json (relative to the plugin root)
133
+ {
134
+ "$schema": "./node_modules/@linkdesk/plugin-sdk/schemas/theme.schema.json",
135
+ // …
136
+ }
137
+ ```
138
+
139
+ Data files are **not JSONC** (strict JSON, loaded by the same engine). At build time or in CI, the validate family can catch format errors (the same schema files the repository's `check-theme-schema.mjs` uses, so the rules never drift):
140
+
141
+ ```js
142
+ import { validateThemeJson, validateIconThemeJson } from "@linkdesk/plugin-sdk";
143
+
144
+ validateThemeJson("themes/my-glass.json"); // theme.schema.json
145
+ validateIconThemeJson("icons/my-icons.json"); // icon-theme.schema.json (dual-form contract for the match table)
146
+ ```
147
+
148
+ ### index.bundle.js conventions
149
+
150
+ The bundle `export default`s a React component — the shell renders it with `{ isActive }`:
151
+
152
+ ```tsx
153
+ export default function MyView({ isActive }: { isActive: boolean }) {
154
+ return <div>Hello LinkDesk</div>;
155
+ }
156
+ ```
157
+
158
+ ## Limitations
159
+
160
+ - **dev preview** (source glob loading inside the shell) parses plugin.json as strict JSON; this SDK's validate tolerating comments/trailing commas is a publish-time capability — if a plugin needs to run in dev preview, keep plugin.json free of comments.
161
+ - Dropping a commented plugin.json straight into the shell's `plugins/` dev directory breaks preview loading (jsonc support on the shell side is still to come).
162
+
163
+ ## Maintaining this package (LinkDesk maintainers)
164
+
165
+ This package is **one of the five author axes** (the others: `@linkdesk/contracts` / `create-linkdesk-plugin` / `@linkdesk/ui` / `@linkdesk/plugin-docs`) and has its own version axis — **publishing it does not bump the application, and the application does not bump it**.
166
+
167
+ Its surface is `src/**` + `schemas/**` + `dev-host/**` + this README: change any of them and the version must be bumped and published, otherwise plugin authors keep building against the old CLI/schemas.
168
+
169
+ ```bash
170
+ # 1. bump packages/plugin-sdk/package.json version (0.x backward-compatible → patch)
171
+ # 2. build the dist the publish channel ships (npm run build, inside the package)
172
+ # 3. publish
173
+ npm publish --registry=https://registry.npmjs.org # 🔴 the registry flag is mandatory — the machine default is a read-only mirror
174
+ # 4. record the baseline (run in the LinkDesk repo root)
175
+ npm run release:mark
176
+ ```
177
+
178
+ > 🔴 The shelf read has a **~3 minute replication delay** (`contracts` is visible within seconds, `plugin-sdk` takes minutes) — do **not** re-publish on a 404, npm will reject the duplicate version.
179
+ > Full procedure + all three measured pitfalls → **`docs/06-发布管理/作者轴npm发版.md`** in the LinkDesk repository.
@@ -103,6 +103,7 @@ export const linkdeskMock: Record<string, unknown> = {
103
103
  saveUserKeybindings: async (..._args: unknown[]) => { console.info("[linkdesk-mock] keybindings.saveUserKeybindings", ..._args); },
104
104
  removeKeybindingForCommand: async (..._args: unknown[]) => { console.info("[linkdesk-mock] keybindings.removeKeybindingForCommand", ..._args); },
105
105
  resetKeybindingToDefault: async (..._args: unknown[]) => { console.info("[linkdesk-mock] keybindings.resetKeybindingToDefault", ..._args); },
106
+ clearKeybindingForCommand: async (..._args: unknown[]) => { console.info("[linkdesk-mock] keybindings.clearKeybindingForCommand", ..._args); },
106
107
  findKeybindingForCommand: async (..._args: unknown[]) => { console.info("[linkdesk-mock] keybindings.findKeybindingForCommand", ..._args); },
107
108
  setKeybindingCaptureActive: async (..._args: unknown[]) => { console.info("[linkdesk-mock] keybindings.setKeybindingCaptureActive", ..._args); },
108
109
  keyboardEventToKeyString: (..._args: unknown[]) => { console.info("[linkdesk-mock] keybindings.keyboardEventToKeyString", ..._args); return ""; },
@@ -239,6 +240,8 @@ export const linkdeskMock: Record<string, unknown> = {
239
240
  },
240
241
  fileAssociation: {
241
242
  getPluginFor: async (..._args: unknown[]) => { console.info("[linkdesk-mock] fileAssociation.getPluginFor", ..._args); },
243
+ listHandlersFor: async (..._args: unknown[]) => { console.info("[linkdesk-mock] fileAssociation.listHandlersFor", ..._args); return []; },
244
+ setDefault: async (..._args: unknown[]) => { console.info("[linkdesk-mock] fileAssociation.setDefault", ..._args); },
242
245
  },
243
246
  langDef: {
244
247
  get: async (..._args: unknown[]) => { console.info("[linkdesk-mock] langDef.get", ..._args); },
package/package.json CHANGED
@@ -1,97 +1,97 @@
1
- {
2
- "name": "@linkdesk/plugin-sdk",
3
- "version": "0.1.73",
4
- "description": "@linkdesk/plugin-sdk——LinkDesk 插件作者 SDK(对标 @types/vscode):window.linkdesk.* 类型 + 一键 build(.linkdesk-plugin) + dev 宿主 + plugin.json 验证 + eslint 门禁(E6#54d)。作者 npm i 后零壳源码依赖。",
5
- "type": "module",
6
- "main": "./dist/index.js",
7
- "types": "./dist/index.d.ts",
8
- "exports": {
9
- ".": {
10
- "types": "./dist/index.d.ts",
11
- "default": "./dist/index.js"
12
- },
13
- "./eslint": {
14
- "types": "./dist/eslint/index.d.ts",
15
- "default": "./dist/eslint/index.js"
16
- },
17
- "./vitest-setup": {
18
- "types": "./dist/vitest-setup.d.ts",
19
- "default": "./dist/vitest-setup.js"
20
- },
21
- "./test-audit": {
22
- "types": "./test-audit.d.ts",
23
- "default": "./test-audit.mjs"
24
- },
25
- "./svg-wellformed": {
26
- "types": "./svg-wellformed.d.ts",
27
- "default": "./svg-wellformed.mjs"
28
- },
29
- "./package.json": "./package.json",
30
- "./own-dict-coverage": {
31
- "types": "./own-dict-coverage.d.ts",
32
- "default": "./own-dict-coverage.mjs"
33
- },
34
- "./check-config-titles": {
35
- "types": "./check-config-titles.d.ts",
36
- "default": "./check-config-titles.mjs"
37
- }
38
- },
39
- "files": [
40
- "dist",
41
- "schemas",
42
- "dev-host",
43
- "test-audit.mjs",
44
- "test-audit.d.ts",
45
- "svg-wellformed.mjs",
46
- "svg-wellformed.d.ts",
47
- "own-dict-coverage.mjs",
48
- "own-dict-coverage.d.ts",
49
- "check-config-titles.mjs",
50
- "check-config-titles.d.ts"
51
- ],
52
- "sideEffects": false,
53
- "bin": {
54
- "linkdesk-plugin-sdk": "./dist/bin.js"
55
- },
56
- "publishConfig": {
57
- "access": "public"
58
- },
59
- "engines": {
60
- "node": ">=20.0.0"
61
- },
62
- "scripts": {
63
- "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
64
- "typecheck": "tsc -p tsconfig.json --noEmit",
65
- "prepack": "npm run build"
66
- },
67
- "dependencies": {
68
- "@linkdesk/contracts": "^0.1.1",
69
- "@typescript-eslint/eslint-plugin": "^8.0.0",
70
- "@typescript-eslint/parser": "^8.0.0",
71
- "@vitejs/plugin-react": "^4.3.4",
72
- "ajv": "^8.17.1",
73
- "eslint": "^9.0.0",
74
- "eslint-import-resolver-typescript": "^4.4.5",
75
- "eslint-plugin-import-x": "^4.17.1",
76
- "eslint-plugin-react-hooks": "^7.1.1",
77
- "i18next": "^26.3.6",
78
- "jsonc-parser": "^3.3.1",
79
- "jszip": "^3.10.1",
80
- "react": "^18.3.1",
81
- "react-dom": "^18.3.1",
82
- "react-i18next": "^17.0.10",
83
- "saxes": "^6.0.0",
84
- "vite": "^6.0.0"
85
- },
86
- "devDependencies": {
87
- "@types/node": "^24.0.0",
88
- "typescript": "^5.9.0"
89
- },
90
- "keywords": [
91
- "linkdesk",
92
- "plugin",
93
- "sdk",
94
- "vite"
95
- ],
96
- "license": "MIT"
97
- }
1
+ {
2
+ "name": "@linkdesk/plugin-sdk",
3
+ "version": "0.1.75",
4
+ "description": "@linkdesk/plugin-sdk——LinkDesk 插件作者 SDK(对标 @types/vscode):window.linkdesk.* 类型 + 一键 build(.linkdesk-plugin) + dev 宿主 + plugin.json 验证 + eslint 门禁(E6#54d)。作者 npm i 后零壳源码依赖。",
5
+ "type": "module",
6
+ "main": "./dist/index.js",
7
+ "types": "./dist/index.d.ts",
8
+ "exports": {
9
+ ".": {
10
+ "types": "./dist/index.d.ts",
11
+ "default": "./dist/index.js"
12
+ },
13
+ "./eslint": {
14
+ "types": "./dist/eslint/index.d.ts",
15
+ "default": "./dist/eslint/index.js"
16
+ },
17
+ "./vitest-setup": {
18
+ "types": "./dist/vitest-setup.d.ts",
19
+ "default": "./dist/vitest-setup.js"
20
+ },
21
+ "./test-audit": {
22
+ "types": "./test-audit.d.ts",
23
+ "default": "./test-audit.mjs"
24
+ },
25
+ "./svg-wellformed": {
26
+ "types": "./svg-wellformed.d.ts",
27
+ "default": "./svg-wellformed.mjs"
28
+ },
29
+ "./package.json": "./package.json",
30
+ "./own-dict-coverage": {
31
+ "types": "./own-dict-coverage.d.ts",
32
+ "default": "./own-dict-coverage.mjs"
33
+ },
34
+ "./check-config-titles": {
35
+ "types": "./check-config-titles.d.ts",
36
+ "default": "./check-config-titles.mjs"
37
+ }
38
+ },
39
+ "files": [
40
+ "dist",
41
+ "schemas",
42
+ "dev-host",
43
+ "test-audit.mjs",
44
+ "test-audit.d.ts",
45
+ "svg-wellformed.mjs",
46
+ "svg-wellformed.d.ts",
47
+ "own-dict-coverage.mjs",
48
+ "own-dict-coverage.d.ts",
49
+ "check-config-titles.mjs",
50
+ "check-config-titles.d.ts"
51
+ ],
52
+ "sideEffects": false,
53
+ "bin": {
54
+ "linkdesk-plugin-sdk": "./dist/bin.js"
55
+ },
56
+ "publishConfig": {
57
+ "access": "public"
58
+ },
59
+ "engines": {
60
+ "node": ">=20.0.0"
61
+ },
62
+ "scripts": {
63
+ "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
64
+ "typecheck": "tsc -p tsconfig.json --noEmit",
65
+ "prepack": "npm run build"
66
+ },
67
+ "dependencies": {
68
+ "@linkdesk/contracts": "^0.1.1",
69
+ "@typescript-eslint/eslint-plugin": "^8.0.0",
70
+ "@typescript-eslint/parser": "^8.0.0",
71
+ "@vitejs/plugin-react": "^4.3.4",
72
+ "ajv": "^8.17.1",
73
+ "eslint": "^9.0.0",
74
+ "eslint-import-resolver-typescript": "^4.4.5",
75
+ "eslint-plugin-import-x": "^4.17.1",
76
+ "eslint-plugin-react-hooks": "^7.1.1",
77
+ "i18next": "^26.3.6",
78
+ "jsonc-parser": "^3.3.1",
79
+ "jszip": "^3.10.1",
80
+ "react": "^18.3.1",
81
+ "react-dom": "^18.3.1",
82
+ "react-i18next": "^17.0.10",
83
+ "saxes": "^6.0.0",
84
+ "vite": "^6.0.0"
85
+ },
86
+ "devDependencies": {
87
+ "@types/node": "^24.0.0",
88
+ "typescript": "^5.9.0"
89
+ },
90
+ "keywords": [
91
+ "linkdesk",
92
+ "plugin",
93
+ "sdk",
94
+ "vite"
95
+ ],
96
+ "license": "MIT"
97
+ }