@linkdesk/plugin-docs 0.1.65 → 0.1.66

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.
@@ -71,7 +71,8 @@ The host also exposes commands of its own (`workbench.action.*`): opening a file
71
71
  picker, and so on. Your plugin may call them; the contract for doing so is deliberately narrow:
72
72
 
73
73
  ```ts
74
- import { SHELL_COMMANDS, openWith } from "@linkdesk/plugin-sdk";
74
+ import { SHELL_COMMANDS, openWith } from "@linkdesk/plugin-sdk/shell-commands";
75
+ // ↑ the subpath, not the root entry — see the red note below
75
76
 
76
77
  // ✅ preferred: the helper takes the request object and returns nothing to remember
77
78
  openWith({ uri: "/path/to/file.pdf" }); // or { ext: "pdf" } when you only know the type
@@ -80,6 +81,12 @@ openWith({ uri: "/path/to/file.pdf" }); // or { ext: "pdf" } when you only kno
80
81
  window.linkdesk.commands.executeCommand(SHELL_COMMANDS.openWith, { uri });
81
82
  ```
82
83
 
84
+ > 🔴 **Runtime code must use the `/shell-commands` subpath**: the SDK's root entry also re-exports its build
85
+ > tooling (`vite.config.ts` → `vite`), so pulling these two values from the **root entry** drags the whole build
86
+ > chain into your plugin bundle — and **fails outright on Windows** (rollup tries to resolve `fsevents`, which
87
+ > only exists on macOS). Types (`OpenWithRequest` etc.) are unaffected: those are `import type`, erased at compile
88
+ > time, so the root entry or the subpath is equally fine.
89
+
83
90
  | Rule | Why |
84
91
  |:--|:--|
85
92
  | ⛔ **Never write the host command id as a string literal** in your plugin | The id is owned by the host and can be unified/renamed; use `SHELL_COMMANDS.*` (the two literal sites—host constant + SDK constant—are reconciled by a gate, your plugin is not a third one) |
@@ -73,7 +73,8 @@ useEffect(() => {
73
73
  宿主自己也有一批命令(`workbench.action.*`):打开文件、升起「打开方式」选择器等等。你的插件可以调它们,写法面刻意收得很窄:
74
74
 
75
75
  ```ts
76
- import { SHELL_COMMANDS, openWith } from "@linkdesk/plugin-sdk";
76
+ import { SHELL_COMMANDS, openWith } from "@linkdesk/plugin-sdk/shell-commands";
77
+ // ↑ 子路径,不是根入口——见下方红字
77
78
 
78
79
  // ✅ 首选:helper 收一个请求对象,不用记命令 id
79
80
  openWith({ uri: "/path/to/file.pdf" }); // 只知道类型时给 { ext: "pdf" }
@@ -82,6 +83,10 @@ openWith({ uri: "/path/to/file.pdf" }); // 只知道类型时给 { ext: "pdf"
82
83
  window.linkdesk.commands.executeCommand(SHELL_COMMANDS.openWith, { uri });
83
84
  ```
84
85
 
86
+ > 🔴 **运行时代码必须写子路径 `/shell-commands`**:SDK 根入口还 re-export 构建工具(`vite.config.ts` → `vite`),
87
+ > 从**根入口**取这两个值会把整条构建链一起打进你的插件包——**Windows 上直接 build 失败**(rollup 要解析仅 macOS 存在的 `fsevents`)。
88
+ > 类型(`OpenWithRequest` 等)不受影响:那是 `import type`,从根入口或子路径取都一样,编译期即擦除。
89
+
85
90
  | 纪律 | 为什么 |
86
91
  |:--|:--|
87
92
  | ⛔ **插件里不许把宿主命令 id 写成字符串字面量** | id 归宿主所有、会被归一/改名;用 `SHELL_COMMANDS.*`(两处字面量——壳常量 + SDK 常量——由门禁对账,你的插件不是第三处) |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.65",
3
+ "version": "0.1.66",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [