@linkdesk/plugin-docs 0.1.64 → 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.
package/docs/00-readme.md CHANGED
@@ -25,7 +25,8 @@
25
25
  | **Build a theme** (no code) | [themes/01-build-a-theme-plugin](themes/01-build-a-theme-plugin.md) | → [themes/02-theme-field-index](themes/02-theme-field-index.md) |
26
26
  | **Add a setting to my plugin** | [20-adding-a-setting](20-adding-a-setting.md) | → [03-contributes-spec](03-contributes-spec.md) |
27
27
  | **Let AI / keybindings / the Command Palette operate my plugin** | [21-command-ification-spec](21-command-ification-spec.md) | → [03-contributes-spec §3.1](03-contributes-spec.md) (every `commands` field) |
28
- | **Add an item to a menu (context menu / gear / hamburger)** | [22-menu-contribution-points](22-menu-contribution-points.md) | → [21-command-ification-spec](21-command-ification-spec.md) (make it a command first) |
28
+ | **Add an item to a menu (context menu / gear / hamburger)** | [22-menu-contribution-points](22-menu-contribution-points.md) | → [21-command-ification-spec](21-command-ification-spec.md) (make it a command first) · §3 "Payload" covers `commandArgs` vs `context` when a shared component opens the menu |
29
+ | **Let the user choose which plugin opens a file (the "Open with…" picker)** | [21-command-ification-spec §2.1](21-command-ification-spec.md) (call the **host command** via `@linkdesk/plugin-sdk`) | → [19-component-cheatsheet](19-component-cheatsheet.md) (`OpenWithPicker`: ⛔ don't build your own panel) · [06-plugin-json-spec `fileAssociations`](06-plugin-json-spec.md) (declare the types you can open) |
29
30
  | **Make several regions work together** (sidebar selection → main area switch → status bar update) | [18-cross-region-wiring](18-cross-region-wiring.md) | → [07-plugin-to-plugin-communication](07-plugin-to-plugin-communication.md) |
30
31
  | **Look up the API** (what can I call) | [01-plugin-api-contract §3](01-plugin-api-contract.md) (the entry table for the three API surfaces) | → the SDK package README cheatsheet / `linkdesk.d.ts` |
31
32
  | **Use the UI parts the shell provides** | [19-component-cheatsheet](19-component-cheatsheet.md) | → [05-ui-conventions](05-ui-conventions.md) |
@@ -179,8 +180,8 @@ Full story → [04-distribution-format §Listing Is Two Steps](04-distribution-f
179
180
  | **18** | **[18-cross-region-wiring](18-cross-region-wiring.md)** | **How regions wire together** — sidebar selection → main area switch → status bar update (a set of recipes) |
180
181
  | **19** | **[19-component-cheatsheet](19-component-cheatsheet.md)** | **Which UI parts the shell provides**, and when to use which |
181
182
  | **20** | **[20-adding-a-setting](20-adding-a-setting.md)** | The minimal approach: declare one → it appears on the settings page automatically → read it in code |
182
- | **21** | **[21-command-ification-spec](21-command-ification-spec.md)** | **Let AI/keybindings/the Command Palette operate my plugin** — how to turn actions into commands, plus the author checklist |
183
- | **22** | **[22-menu-contribution-points](22-menu-contribution-points.md)** | **Put an action into one of the host's menus** — the 14 slots, the `group`/`when` conventions, and the public context-key table |
183
+ | **21** | **[21-command-ification-spec](21-command-ification-spec.md)** | **Let AI/keybindings/the Command Palette operate my plugin** — how to turn actions into commands, plus the author checklist; §2.1 covers calling **host** commands (`SHELL_COMMANDS` / helpers) without hard-coding their ids |
184
+ | **22** | **[22-menu-contribution-points](22-menu-contribution-points.md)** | **Put an action into one of the host's menus** — the 14 slots, the `group`/`when` conventions, the public context-key table, and the menu **payload law** (`commandArgs` vs `context`) |
184
185
  | **T1** | **[themes/01-build-a-theme-plugin](themes/01-build-a-theme-plugin.md)** | The theme-authoring walkthrough (no code) |
185
186
  | **T2** | **[themes/02-theme-field-index](themes/02-theme-field-index.md)** | A cross-index of recipe fields and CSS variables |
186
187
 
@@ -59,6 +59,25 @@ window.linkdesk.menu.registerItems("editorContext", "myPlugin", [
59
59
 
60
60
  New context-menu scenarios → just declare a new open-string MenuId (e.g. `"myMenu"`): declare `contributes.menus.myMenu` + consume it with `<ContextMenu menuId="myMenu" />`—**zero shell changes** (the plugin-independence iron rule). The shell only needs to add a MENU_SLOTS entry if it wants to provide a unified render point for that scenario.
61
61
 
62
+ ### Consuming a **shared component's** menu—the payload arrives in two parts
63
+
64
+ Some shared components open their own menu and hand you a line: a card's gear, a list row's gear. When you
65
+ do, the shared component **fixes the shape of what your handler receives**—and it also adds its own
66
+ `context`. The rule (full statement in
67
+ [22-menu-contribution-points](22-menu-contribution-points.md) §3 "Payload"):
68
+
69
+ > `args = [...commandArgs, context]` — your own identity first (from `commandArgs`), the shared component's
70
+ > `context` **at the end**. ⛔ Never assume `args[0]` is your data when the slot has a shared context.
71
+
72
+ | Shared component | What it sends as `context` | What your handler must do |
73
+ |:--|:--|:--|
74
+ | `PluginCard` (card gear) | `{ pluginId }` | read `args[0]`, keep reading the trailing `context` if you add your own `commandArgs` |
75
+
76
+ So a handler written for "my own menu" and a handler written for "a shared component's menu" are **not**
77
+ interchangeable: read the shared component's document for the exact `context` shape before you write the
78
+ handler, and always keep the "no target ⇒ do nothing" guard (⛔ an item that does nothing is worse than an
79
+ item that is not there).
80
+
62
81
  ---
63
82
 
64
83
  ## 2. Overlays / Dialogs → `createPortal`
@@ -651,13 +651,15 @@ Declares "which extensions' files are opened by me". When the user double-clicks
651
651
 
652
652
  | Field | Required | Notes |
653
653
  |:--|:--:|:--|
654
- | `extension` | ✅ | Extension — **without the dot** (`dxf` / `ts`); case-insensitive (the shell lower-cases it) |
654
+ | `extension` | ✅ | Extension — **without the dot** (`dxf` / `ts`). **Normalized by the shell**: whitespace trimmed, lower-cased, a leading dot dropped; an entry containing whitespace or `/` `\` is **illegal and discarded** |
655
655
  | `command` | — | Which of your commands to run on open; omit to use the framework's default open action |
656
- | `displayName` | — | The name shown in the "Open with…" picker |
656
+ | `displayName` | — | The **file-type** display name (e.g. `.rs` → `"Rust"`). 🔴 **This is NOT the plugin/handler name**: the "Open with…" picker labels each row with your plugin's **top-level `name`**, and `displayName` only appears in non-naming positions such as the panel title. If you want to name *yourself*, use the manifest's top-level `name` — ⛔ do not put it here (that is exactly how a picker row ends up reading "Rust") |
657
657
  | `role` | — | **Role declaration** (see below). The first version defines only `"text-fallback"` |
658
658
 
659
659
  **Several plugins may declare the same extension** (your `ts` coexists with someone else's `ts`) — the shell does not pick a winner for you; the user picks from "Open with…", and the default is **whichever plugin activated first**. So declaring is **not** a takeover; it means "I can open it too".
660
660
 
661
+ > **Why normalization matters to you**: entries are de-duplicated and grouped **by the normalized extension string** — `MX`, `mx` and `.mx` are one and the same kind. A type counts as **contested** only when **two or more enabled plugins** declare it (one handler is never contested — the shell decides alone and does not bother the user). ⇒ **Not declaring means you never meet the competition**: if your plugin can open a kind but does not declare it, the shell will never offer it to you.
662
+
661
663
  ##### `role` — how to become the default text editor
662
664
 
663
665
  The shell **does not know, and must not know, any plugin id** (iron law ② of the shell) — "when no plugin declares a file's kind, which tab should open it" is answered by plugins **self-declaring a role**:
@@ -65,7 +65,7 @@ The version of `@linkdesk/ui` **moves on its own** (patch +1 per publish) and is
65
65
 
66
66
  | Component | What it does | When to use it |
67
67
  |:--|:--|:--|
68
- | `Button` | Button | Any "click and it happens" action; variants/sizes follow the theme |
68
+ | `Button` | Button | Any "click and it happens" action; variants/sizes follow the theme. **`variant` is the action tier**: default = solid primary, `success` = positive primary (install/enable), `danger` = destructive secondary, `ghost` = secondary transparent; `size="sm"` = a 22px button for a 30px toolbar |
69
69
  | `Toggle` | Toggle switch | Two-state settings (on/off) |
70
70
  | `Slider` | Slider | Adjusting a numeric range (pair with `inferSliderStep` for the step) |
71
71
  | `NumberInput` | Numeric input box | Numbers that need precise entry (often sits next to a slider) |
@@ -89,6 +89,7 @@ The version of `@linkdesk/ui` **moves on its own** (patch +1 per publish) and is
89
89
  | `HintCard` | Anchored hover hint card (non-interactive) | For "hover a small badge, see a short explanation card": give `lines` (1–3 sentences) and the anchor element; triggering/positioning/glass are all handled by the shell; ⛔ no links or buttons inside the card |
90
90
  | `ReadOnlyText` | Read-only text (single-line or multi-line, not editable) | Showing a **read-only value**: paths, addresses, live status lines (this is what the settings page's read-only status rows use — declare `renderHint: "readonly"` + `statusCommand`, see [20-adding-a-setting](20-adding-a-setting.md)) |
91
91
  | `SectionSubtitle` | Section subtitle (one small line under a heading) | A one-line note under a group/section — the settings page renders `subtitle` / `groupDescriptions` with it, and you can use it directly when assembling your own explanatory block |
92
+ | `OpenWithPicker` | The "Open with…" picker panel (rows = handlers, each labelled with the plugin's name and its icon) | Letting the user choose **which plugin opens a file / a type**. 🔴 **Call the host command, don't build your own panel**: `openWith({ uri })` / `openWith({ ext })` from `@linkdesk/plugin-sdk` rises the centered panel; the shell assembles the handler list (names, icons, current default) and sends the action back. The component is exported so the panel is one implementation, ⛔ not so every plugin draws its own |
92
93
 
93
94
  > The list follows the package's actual export surface (`packages/linkdesk-ui/src/index.ts` is the single source of truth) — if this page disagrees with the package, **the package wins**.
94
95
 
@@ -62,9 +62,43 @@ useEffect(() => {
62
62
  }, []);
63
63
  ```
64
64
 
65
- > ⚠️ **Declaring without registering a handler** = the palette shows it, clicking does nothing (no-op + a diagnostic warning).
65
+ > ⚠️ **Declaring without registering a handler** = the palette shows it, nothing happens when clicked (no-op + a diagnostic warning).
66
66
  > The declaration side contributes **metadata** (a placeholder); the handler is what actually runs.
67
67
 
68
+ ### 2.1 Calling a **host** command—never hard-code its id
69
+
70
+ The host also exposes commands of its own (`workbench.action.*`): opening a file, opening the "Open With"
71
+ picker, and so on. Your plugin may call them; the contract for doing so is deliberately narrow:
72
+
73
+ ```ts
74
+ import { SHELL_COMMANDS, openWith } from "@linkdesk/plugin-sdk/shell-commands";
75
+ // ↑ the subpath, not the root entry — see the red note below
76
+
77
+ // ✅ preferred: the helper takes the request object and returns nothing to remember
78
+ openWith({ uri: "/path/to/file.pdf" }); // or { ext: "pdf" } when you only know the type
79
+
80
+ // ✅ equivalent, if you need the raw command face
81
+ window.linkdesk.commands.executeCommand(SHELL_COMMANDS.openWith, { uri });
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
+
90
+ | Rule | Why |
91
+ |:--|:--|
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) |
93
+ | ✅ **Probe before you show an affordance** | Feature-detect with `commands.getCommands()`; if the command is not registered, **hide the entry** — ⛔ no dead buttons (an item that is visible but does nothing is worse than one that is absent) |
94
+ | ⛔ **Do not use `placeholder` as an existence test** | Every command a plugin declares carries `placeholder: true` (that is the "metadata registered, execution routed to the pool" marker, not an implementation check)—it cannot tell you whether the host command really works |
95
+
96
+ ```ts
97
+ // Feature-detect a host command before rendering the entry that calls it
98
+ const list = await window.linkdesk.commands?.getCommands?.();
99
+ setCanOpenWith(!!list?.some((c) => c?.id === SHELL_COMMANDS.openWith));
100
+ ```
101
+
68
102
  ---
69
103
 
70
104
  ## 3. Five things every command should get right
@@ -108,6 +108,33 @@ or your own `<pluginId>.*` flags.
108
108
  }
109
109
  ```
110
110
 
111
+ ### Payload: `commandArgs` vs `context`
112
+
113
+ `MenuItemDescriptor` has one more field that matters as soon as a menu is built by shared code rather
114
+ than by you:
115
+
116
+ | Field | Meaning |
117
+ |:--|:--|
118
+ | `commandArgs` | **This item's own arguments.** The only place per-item identity belongs |
119
+ | `context` | **Shared by the whole menu.** When the menu is opened by a shared component, that component supplies it (it is not yours to set) |
120
+
121
+ **The menu payload law.** `context` is **shared by the whole menu**; each item's identity must travel in
122
+ `MenuItemDescriptor.commandArgs`. The host handler receives `args = [...commandArgs, context]`. A shared
123
+ component (for example `PluginCard`) always sends **its own** `context` (`PluginCard` = `{pluginId}`) ⇒
124
+ when you consume a shared component's context menu, your handler must tolerate **both** its own payload in
125
+ `args[0]` **and** the shared component's context **at the end** — ⛔ never assume `args[0]` is your data
126
+ (unless that slot has no shared context at all).
127
+
128
+ ```ts
129
+ // Consuming PluginCard's gear menu: args = [{ pluginId }, context]
130
+ // Your own payload (from commandArgs) first, the shared component's context last.
131
+ linkdesk.commands.registerCommand("my-plugin.onCardGear", (args) => {
132
+ const mine = args?.[0] as { pluginId?: string } | undefined;
133
+ if (!mine?.pluginId) return; // no target ⇒ do nothing (never "act on an empty one")
134
+ /* … */
135
+ });
136
+ ```
137
+
111
138
  ---
112
139
 
113
140
  ## 4. `group` and ordering (what the menu ends up looking like)
@@ -25,7 +25,8 @@
25
25
  | **做一个主题**(不写代码) | [主题/01-做一个主题插件](主题/01-做一个主题插件.md) | → [主题/02-主题字段速查](主题/02-主题字段速查.md) |
26
26
  | **给我的插件加一条配置项** | [20-我的插件加一条配置项](20-我的插件加一条配置项.md) | → [03-插件contributes规范](03-插件contributes规范.md) |
27
27
  | **让 AI / 快捷键 / 命令面板也能操作我的插件** | [21-插件命令化规范](21-插件命令化规范.md) | → [03-插件contributes规范 §3.1](03-插件contributes规范.md)(`commands` 全字段) |
28
- | **往某个菜单(右键/齿轮/汉堡)里加一项** | [22-菜单贡献点](22-菜单贡献点.md) | → [21-插件命令化规范](21-插件命令化规范.md)(先把动作做成命令) |
28
+ | **往某个菜单(右键/齿轮/汉堡)里加一项** | [22-菜单贡献点](22-菜单贡献点.md) | → [21-插件命令化规范](21-插件命令化规范.md)(先把动作做成命令)· §三「载荷」讲共享件弹菜单时 `commandArgs` 与 `context` 怎么分 |
29
+ | **让用户挑「这个文件用哪只插件打开」(打开方式选择器)** | [21-插件命令化规范 §2.1](21-插件命令化规范.md)(经 `@linkdesk/plugin-sdk` 调**宿主命令**) | → [19-组件速查](19-组件速查.md)(`OpenWithPicker`:⛔ 别自己实现面板)· [06-plugin.json规范 `fileAssociations`](06-plugin.json规范.md)(先声明你能开的类型) |
29
30
  | **让几个区域联动**(侧栏选中 → 主区切换 → 状态栏更新) | [18-区域间互动](18-区域间互动.md) | → [07-插件间通信](07-插件间通信.md) |
30
31
  | **查 API**(能调什么) | [01-插件API契约 §三](01-插件API契约.md)(三处 API 面的入口表) | → SDK 包内 README 速查表 / `linkdesk.d.ts` |
31
32
  | **用壳提供的 UI 零件** | [19-组件速查](19-组件速查.md) | → [05-插件UI写法规约](05-插件UI写法规约.md) |
@@ -179,8 +180,8 @@ npm run publish # 发布到你自己的 GitHub 仓(上
179
180
  | **18** | **[18-区域间互动](18-区域间互动.md)** | **区域之间怎么联动**——侧栏选中 → 主区切换 → 状态栏更新(配方集) |
180
181
  | **19** | **[19-组件速查](19-组件速查.md)** | **壳提供了哪些 UI 零件**、什么时候用哪个 |
181
182
  | **20** | **[20-我的插件加一条配置项](20-我的插件加一条配置项.md)** | 最小做法:声明一条 → 设置页自动出现 → 代码里读 |
182
- | **21** | **[21-插件命令化规范](21-插件命令化规范.md)** | **让 AI/快捷键/命令面板能操作我的插件**——动作做成命令的规范 + 作者检查清单 |
183
- | **22** | **[22-菜单贡献点](22-菜单贡献点.md)** | **把一个动作放进宿主的菜单**——14 个槽位清单 + `group`/`when` 约定 + 公共 context key 表 |
183
+ | **21** | **[21-插件命令化规范](21-插件命令化规范.md)** | **让 AI/快捷键/命令面板能操作我的插件**——动作做成命令的规范 + 作者检查清单;§2.1 讲调**宿主命令**(`SHELL_COMMANDS` / helper)而不硬编码其 id |
184
+ | **22** | **[22-菜单贡献点](22-菜单贡献点.md)** | **把一个动作放进宿主的菜单**——14 个槽位清单 + `group`/`when` 约定 + 公共 context key 表 + **菜单载荷律**(`commandArgs` vs `context`) |
184
185
  | **T1** | **[主题/01-做一个主题插件](主题/01-做一个主题插件.md)** | 做主题的动线(零代码) |
185
186
  | **T2** | **[主题/02-主题字段速查](主题/02-主题字段速查.md)** | 配方字段与 CSS 变量的对照索引 |
186
187
 
@@ -59,6 +59,19 @@ window.linkdesk.menu.registerItems("editorContext", "myPlugin", [
59
59
 
60
60
  新增右键场景 → MenuId 开放 string 直接声明即可(如 `"myMenu"`):`contributes.menus.myMenu` 声明 + `<ContextMenu menuId="myMenu" />` 消费——**零壳改动**(插件独立铁律)。壳若要在此场景提供统一渲染点才需在 MENU_SLOTS 加条目。
61
61
 
62
+ ### 消费**共享件**的菜单——载荷分两段到
63
+
64
+ 有些共享件会自弹菜单、把一行递给你:卡头齿轮、列表行齿轮。这时**你收到的入参形状是共享件定的**——而且它还会塞进自己的 `context`。规则(完整表述见 [22-菜单贡献点](22-菜单贡献点.md) §三「载荷」):
65
+
66
+ > `args = [...commandArgs, context]`——自己的身份在前(来自 `commandArgs`),共享件的 `context` 在**末尾**。
67
+ > ⛔ 该槽位有共享 context 时,绝不要假设 `args[0]` 是你的数据。
68
+
69
+ | 共享件 | 它送的 `context` | 你的 handler 要做什么 |
70
+ |:--|:--|:--|
71
+ | `PluginCard`(卡头齿轮) | `{ pluginId }` | 读 `args[0]`;若你自己还要加 `commandArgs`,末尾那个 `context` 得继续容忍 |
72
+
73
+ ⇒ 「给自弹菜单写的 handler」与「给共享件齿轮写的 handler」**不通用**:动笔前先读共享件文档里 `context` 的确切形状,并永远保留「没有目标 ⇒ 什么都不做」的守卫(⛔ 一个点了不动的项比一个不存在的项更糟)。
74
+
62
75
  ---
63
76
 
64
77
  ## 2. 浮层 / 弹窗 → `createPortal`
@@ -648,13 +648,15 @@ function CadView() {
648
648
 
649
649
  | 字段 | 必需 | 说明 |
650
650
  |:--|:--:|:--|
651
- | `extension` | ✅ | 扩展名——**不带点**(`dxf` / `ts`);大小写不敏感(壳统一转小写) |
651
+ | `extension` | ✅ | 扩展名——**不带点**(`dxf` / `ts`)。**由壳归一**:去空白、转小写、掉前导点;含空白或 `/` `\` 的条目**非法、直接丢弃** |
652
652
  | `command` | — | 打开时执行你的哪个命令;缺省走框架的文件打开动作 |
653
- | `displayName` | — | 在「打开方式…」选择器里显示的名字 |
653
+ | `displayName` | — | **文件类型**显示名(如 `.rs → "Rust"`)。🔴 **⛔ 它不是插件名/处理器名**:「打开方式…」选择器每行的主标签取的是你 manifest 顶层 `name`,`displayName` 只出现在「打开方式 · {{类型名}}」这类**非命名位**。想给**自己**起名用顶层 `name`——⛔ 别写在这里(面板行写着 "Rust" 就是这么来的) |
654
654
  | `role` | — | **角色挂牌**(见下)。首版只定义 `"text-fallback"` |
655
655
 
656
656
  **同一扩展名可以多家声明**(你声明的 `ts` 与别人的 `ts` 并存)——壳不替你判给谁,用户从「打开方式…」里挑;默认取**先激活的那家**。所以声明**不是抢占**,是「我也能开」。
657
657
 
658
+ > **归一为什么与你有关**:条目按**归一化扩展名字符串**去重与聚合——`MX`、`mx`、`.mx` 是同一类。某类只有在**两家及以上已启用插件**声明时才算「竞争」(一个处理器从来不算竞争——壳自己定,不打扰用户)。⇒ **不声明就等于永远碰不上竞争**:你的插件明明能开某类,却没声明,壳永远不会把它派给你。
659
+
658
660
  ##### `role`:怎么成为「默认文本编辑器」
659
661
 
660
662
  壳**不知道也不该知道**任何插件 id(壳的铁律②)——「某类文件没有任何插件声明时,开哪个标签页」这件事,靠插件**自报角色**:
@@ -66,7 +66,7 @@ import { Button, Toggle, ContextMenu } from "@linkdesk/ui";
66
66
 
67
67
  | 组件 | 干什么 | 什么时候用它 |
68
68
  |:--|:--|:--|
69
- | `Button` | 按钮 | 任何"点一下就做"的动作;变体/尺寸跟着主题 |
69
+ | `Button` | 按钮 | 任何"点一下就做"的动作;变体/尺寸跟着主题。**`variant` 是动作层级**:缺省=实心主操作、`success`=正面主操作(安装/启用)、`danger`=破坏性次级、`ghost`=次级透明;`size="sm"`=22px(给 30px 工具条用) |
70
70
  | `Toggle` | 开关 | 二值设置项(开/关) |
71
71
  | `Slider` | 滑杆 | 数值区间调节(配合 `inferSliderStep` 推步进) |
72
72
  | `NumberInput` | 数字输入框 | 需要精确输入的数字(滑杆旁边常配一个) |
@@ -90,6 +90,7 @@ import { Button, Toggle, ContextMenu } from "@linkdesk/ui";
90
90
  | `HintCard` | 贴锚的悬停说明卡(非交互) | 「停在某个小标上出一张说明卡」——给 `lines`(1–3 句)与锚元素,触发/定位/玻璃全归壳;⛔ 卡内不放链接按钮 |
91
91
  | `ReadOnlyText` | 只读文字(单行/多行,不可编辑) | 显示**只读值**:路径、地址、实时状态行(设置页的只读状态行使的就是它——声明 `renderHint: "readonly"` + `statusCommand` 即可,见 [20-我的插件加一条配置项](20-我的插件加一条配置项.md)) |
92
92
  | `SectionSubtitle` | 分节副标题(标题下的一行小字) | 分组/分节下面的一行说明——设置页用它渲染 `subtitle` / `groupDescriptions`,自己拼说明区时也可以直接用它 |
93
+ | `OpenWithPicker` | 「打开方式…」选择器面板(每行一个处理器:插件名 + 图标) | 让用户挑**某文件/某类型用哪个插件打开**时。🔴 **调宿主命令即可,⛔ 别自己实现面板**:`@linkdesk/plugin-sdk` 的 `openWith({ uri })` / `openWith({ ext })` 升起居中选择面板,处理器表(名字、图标、当前默认)由宿主装配、动作由宿主回收。本组件导出是为了「面板只有一份实现」,⛔ 不是让每只插件各画一套 |
93
94
 
94
95
  > 清单以包的实际导出面为准(`packages/linkdesk-ui/src/index.ts` 是唯一真相源)——本页若与包不一致,**以包为准**。
95
96
 
@@ -68,6 +68,37 @@ useEffect(() => {
68
68
  > (`describe` 的 `commandsPending`,每条带"先开哪个视图"那一步),撞上时 `exec` 的 `EUNKNOWN`
69
69
  > 正文也给同一步。⛔ 别指望 AI 自己"先撞一次报错 → 猜要开视图 → 再试"。(2026-09-29 壳侧落地)
70
70
 
71
+ ### 2.1 调用**宿主**命令——⛔ 不许硬编码它的 id
72
+
73
+ 宿主自己也有一批命令(`workbench.action.*`):打开文件、升起「打开方式」选择器等等。你的插件可以调它们,写法面刻意收得很窄:
74
+
75
+ ```ts
76
+ import { SHELL_COMMANDS, openWith } from "@linkdesk/plugin-sdk/shell-commands";
77
+ // ↑ 子路径,不是根入口——见下方红字
78
+
79
+ // ✅ 首选:helper 收一个请求对象,不用记命令 id
80
+ openWith({ uri: "/path/to/file.pdf" }); // 只知道类型时给 { ext: "pdf" }
81
+
82
+ // ✅ 等价写法:需要 raw 命令面时
83
+ window.linkdesk.commands.executeCommand(SHELL_COMMANDS.openWith, { uri });
84
+ ```
85
+
86
+ > 🔴 **运行时代码必须写子路径 `/shell-commands`**:SDK 根入口还 re-export 构建工具(`vite.config.ts` → `vite`),
87
+ > 从**根入口**取这两个值会把整条构建链一起打进你的插件包——**Windows 上直接 build 失败**(rollup 要解析仅 macOS 存在的 `fsevents`)。
88
+ > 类型(`OpenWithRequest` 等)不受影响:那是 `import type`,从根入口或子路径取都一样,编译期即擦除。
89
+
90
+ | 纪律 | 为什么 |
91
+ |:--|:--|
92
+ | ⛔ **插件里不许把宿主命令 id 写成字符串字面量** | id 归宿主所有、会被归一/改名;用 `SHELL_COMMANDS.*`(两处字面量——壳常量 + SDK 常量——由门禁对账,你的插件不是第三处) |
93
+ | ✅ **先探测再上屏** | 用 `commands.getCommands()` 特性探测;命令不在册就**整条不出现**——⛔ 不留死钮(看得见却没反应的项比不存在的项更糟) |
94
+ | ⛔ **别拿 `placeholder` 当"存在/可用"判据** | 插件声明的每条命令都带 `placeholder: true`(那是「元数据已注册、执行转发给池」的**路由标记**,不是实现检查)——它答不了"宿主这条命令真能跑吗" |
95
+
96
+ ```ts
97
+ // 上屏前特性探测一条宿主命令
98
+ const list = await window.linkdesk.commands?.getCommands?.();
99
+ setCanOpenWith(!!list?.some((c) => c?.id === SHELL_COMMANDS.openWith));
100
+ ```
101
+
71
102
  ---
72
103
 
73
104
  ## 三、命令要写全的五件事
@@ -105,6 +105,30 @@
105
105
  }
106
106
  ```
107
107
 
108
+ ### 载荷:`commandArgs` vs `context`
109
+
110
+ `MenuItemDescriptor` 还差两个字段没说——它们在你**消费共享件弹出的菜单**时立刻要紧:
111
+
112
+ | 字段 | 说明 |
113
+ |:--|:--|
114
+ | `commandArgs` | **本项自己的入参**。每一项的身份只有这一个落点 |
115
+ | `context` | **整菜单共享**。菜单由共享件弹出时,由那个共享件供给(轮不到你设) |
116
+
117
+ > **菜单载荷律**:`ContextMenu` 的 `context` 是**整菜单共享**的;每一项的身份必须走 `MenuItemDescriptor.commandArgs`。
118
+ > 壳 handler 收到 `args = [...commandArgs, context]`。共享件(如 `PluginCard`)会固定送**它自己的** `context`
119
+ > (`PluginCard` = `{pluginId}`)⇒ 消费共享件齿轮的插件,handler 必须同时容忍 `args[0]` 是自己的载荷、
120
+ > **末尾**是共享件的 context——⛔ 不要假设 `args[0]` 一定是你的数据(除非该槽位无共享 context)。
121
+
122
+ ```ts
123
+ // 消费 PluginCard 的齿轮菜单:args = [{ pluginId }, context]
124
+ // 自己的载荷(来自 commandArgs)在前,共享件的 context 在末。
125
+ linkdesk.commands.registerCommand("my-plugin.onCardGear", (args) => {
126
+ const mine = args?.[0] as { pluginId?: string } | undefined;
127
+ if (!mine?.pluginId) return; // 没有目标 ⇒ 什么都不做(⛔ 不「清了个空的」)
128
+ /* … */
129
+ });
130
+ ```
131
+
108
132
  ---
109
133
 
110
134
  ## 四、`group` 与排序(决定菜单长什么样)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.64",
3
+ "version": "0.1.66",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [