@linkdesk/plugin-docs 0.1.37 → 0.1.39
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 +2 -0
- package/docs/01-plugin-api-contract.md +2 -1
- package/docs/03-contributes-spec.md +1 -1
- package/docs/20-adding-a-setting.md +1 -1
- package/docs/21-command-ification-spec.md +127 -0
- package/docs/zh/00-README.md +2 -0
- package/docs/zh/01-/346/217/222/344/273/266API/345/245/221/347/272/246.md +2 -1
- package/docs/zh/03-/346/217/222/344/273/266contributes/350/247/204/350/214/203.md +1 -1
- package/docs/zh/20-/346/210/221/347/232/204/346/217/222/344/273/266/345/212/240/344/270/200/346/235/241/351/205/215/347/275/256/351/241/271.md +1 -1
- package/docs/zh/21-/346/217/222/344/273/266/345/221/275/344/273/244/345/214/226/350/247/204/350/214/203.md +132 -0
- package/docs/zh/plugin.schema.json +1 -1
- package/package.json +1 -1
package/docs/00-readme.md
CHANGED
|
@@ -24,6 +24,7 @@
|
|
|
24
24
|
| **Build an advanced plugin** (1-day tier: data pipeline / cross-plugin / Canvas / LSP) | [the 1-day tier in 13](13-development-guide.md) | → [07-plugin-to-plugin-communication](07-plugin-to-plugin-communication.md) · [14-data-pipeline-command-conventions](14-data-pipeline-command-conventions.md) |
|
|
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
|
+
| **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) |
|
|
27
28
|
| **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) |
|
|
28
29
|
| **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` |
|
|
29
30
|
| **Use the UI parts the shell provides** | [19-component-cheatsheet](19-component-cheatsheet.md) | → [05-ui-conventions](05-ui-conventions.md) |
|
|
@@ -177,6 +178,7 @@ Full story → [04-distribution-format §Listing Is Two Steps](04-distribution-f
|
|
|
177
178
|
| **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) |
|
|
178
179
|
| **19** | **[19-component-cheatsheet](19-component-cheatsheet.md)** | **Which UI parts the shell provides**, and when to use which |
|
|
179
180
|
| **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 |
|
|
181
|
+
| **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 |
|
|
180
182
|
| **T1** | **[themes/01-build-a-theme-plugin](themes/01-build-a-theme-plugin.md)** | The theme-authoring walkthrough (no code) |
|
|
181
183
|
| **T2** | **[themes/02-theme-field-index](themes/02-theme-field-index.md)** | A cross-index of recipe fields and CSS variables |
|
|
182
184
|
|
|
@@ -83,8 +83,9 @@ async function list(): Promise<FileEntry[]> {
|
|
|
83
83
|
| **decorations** | **Synchronous contract**: `provideDecoration` returns `FileDecoration \| null \| undefined` and **must not return a Promise** (async providers are skipped); a repeated `registerProvider` for the same pluginId idempotently overwrites; unregister/register automatically fires a full refresh notification `onDidChange([])`; if a provider throws, that entry is self-healed away |
|
|
84
84
|
| **filesystem** | Plugin permissions: read/write its own data directory, read the workspace directory, **other plugins' directories are off-limits** |
|
|
85
85
|
| **configuration** | Config key naming rule `<pluginId>.<property>` (e.g. `editor.fontSize`, `serial-monitor.baudRate`) |
|
|
86
|
+
| **pool (shell×pool intent channels)** | Pool→shell **upward intent** has only two umbrella methods (`pool.sidebarAction(action)` / `pool.tabAction(action)`), dispatched by their `action` payload. Three of those are the equivalent of "**just drag it**" (registered here as of M2 `AI#21`; each has a **non-mouse command counterpart**, so an AI/script never has to drag): ① `sidebarAction({ action: "setSidebarWidth", width })` — the same path the main-sidebar divider drag commits through (shell `useSubscriptions` → `LayoutEngine.resizeZone`, clamped by the dock declaration, 170–600) → commands `workbench.action.setSidebarWidth(width)` / `…resetSidebarWidth` (back to the 280 default); ② `tabAction({ action: "updateSplitSizes", branchIndex, sizes })` — where a split divider drag commits (shell `useTabManager.updateSplitSizes` → the SplitNode tree) → command `workbench.action.resetSplitSizes` (**every** branch back to 50/50); ③ the event `events.emit("panel:resize", { height })` — where dragging the bottom panel's top handle commits (the shell consumer routes **axis-aware**: for a panel with `edge ∈ {left,right}` it uses the width axis `resizeZone`, for `top/bottom` the height axis `resizeZoneHeight`) → commands `workbench.action.setPanelSize(size)` / `…resetPanelSize`. ⚠️ These three are **pool infrastructure** (used by the Zone dividers themselves), **not** a linkage mechanism plugins should call — to change the layout, use the commands above (`window.linkdesk.commands.executeCommand`) and ⛔ do not emit the pool-internal channels directly (the event names carry no plugin prefix, and how the shell routes them is an implementation detail). |
|
|
86
87
|
| **serial** | **Multi-port routing:** the `portName` of the open/close/action-targeting interfaces is **optional** — omitted = the single open port (0 ports throws "serial port not open"; ≥2 ports throws "multiple serial ports open, please specify portName"; **failures are visible, never silent**). The three streaming channels (`onData`/`onStats`/`onSystem`) carry **object** payloads with a `portName` routing key (`SerialDataPayload`/`SerialStatsPayload`/`SerialSystemPayload`) — subscribers filter by **their session's port** (key=portName is the generic routing-key pattern: whoever consumes filters; the shell does not collect on their behalf). Each tab is still single-port, and the session-to-port binding lives on the plugin side |
|
|
87
|
-
| **panel** | `panel.reveal(viewId)` focuses a Bottom Panel view through declarative addressing — panel hidden → expand it and switch to that view (the same mechanism as Ctrl+J); already shown → switch and focus; **viewId not in the panel container → no-op** (no error). **`panel.moveToEditor` has been removed** (deprecated content migration — moving position is the job of the layout command). `panel.revealFloating(viewId)` pops a view out as an in-shell Floating Panel (type B) — declared addressing. Declarative addressing = the ViewContainerService global view index (`contributes.views` registers a view in **any container**, not just panel — plugins declare `contributes.floatingPanel.viewId` to reference it). **Identity toggle key**: no panel → open; same view → close (toggle); another panel → replace; **viewId undeclared / declaring plugin not installed → no-op** (no crash). Default panel actions = "Open in main window" (appears only when the declaring plugin can open as a tab) + maximize toggle + close |
|
|
88
|
+
| **panel** | `panel.reveal(viewId)` focuses a Bottom Panel view through declarative addressing — panel hidden → expand it and switch to that view (the same mechanism as Ctrl+J); already shown → switch and focus; **viewId not in the panel container → no-op** (no error). **`panel.moveToEditor` has been removed** (deprecated content migration — moving position is the job of the layout command). `panel.revealFloating(viewId)` pops a view out as an in-shell Floating Panel (type B) — declared addressing. Declarative addressing = the ViewContainerService global view index (`contributes.views` registers a view in **any container**, not just panel — plugins declare `contributes.floatingPanel.viewId` to reference it). **Identity toggle key**: no panel → open; same view → close (toggle); another panel → replace; **viewId undeclared / declaring plugin not installed → no-op** (no crash). Default panel actions = "Open in main window" (appears only when the declaring plugin can open as a tab) + maximize toggle + close. **`panel.setFloatingBounds({ top, left, width, height } | null)`** (M2 `AI#20`) — the **non-mouse path** for floating-panel geometry: set position/size precisely (omitted fields keep their current value, `null` resets to the default centered card; no-op when no panel is open). Out-of-range values are clamped by **the same bounds as dragging** (`MIN_HEIGHT` / right-edge limit / 6 px inset). Read back via the command `workbench.action.getFloatingPanelBounds` (returns the last settled geometry). |
|
|
88
89
|
| **hotExit** | Crash recovery only — dirty content is written to disk at `%APPDATA%/linkdesk/hot-exit/` (a single-source path convention owned by the main process; plugins never write there directly); after saving/closing a tab, call `clear` to delete the backup |
|
|
89
90
|
| **shell** | Shell-level OS actions: `showItemInFolder(p)` highlights a single file in Explorer / `openInTerminal(dirPath, terminalExe?, customCommand?)` opens an external terminal / `startDrag(filePath, iconPath?)` drags out to the desktop. **`pluginLocation(pluginId)` / `openPluginFolder(pluginId, kind)` are the plugin-disk-location pair** — the former returns `{ installDir, dataDir } | null` (**it hands over identity, not the right to assemble paths**: the main process resolves paths and the plugin takes the result; not found on disk → `null`; `dataDir` is non-`null` only once the plugin has **actually written to disk**, and empty/absent means that row shouldn't be drawn); the latter's `kind: "install" \| "data"` opens the directory **contents** in Explorer (the same feel as `appearance.revealStorage`, not `showItemInFolder`'s single-file highlight) — the `install` directory not being on disk throws, while `data` creates an empty directory first, then opens. **`relaunch` genuinely restarts the app** (quits and relaunches the process) — ⚠️ **injected by the shell preload only (the contract marks it `?` optional)**, so pool-side callers must check existence first (`window.linkdesk.shell.relaunch?.`). The difference from `window.location.reload` is **whether the pool survives**: the pool is a separate `WebContentsView` that a shell reload does not rebuild, so after updating a view-type plugin a reload only shows the old bundle; after `relaunch` the current process terminates immediately, so **don't rely on its return value** (the Promise never settles) |
|
|
90
91
|
| **appearance** | `revealStorage` opens the appearance storage directory (`userData/appearance`) — the main process resolves the path and uses `shell.openPath` to open the Explorer **contents** (not `showItemInFolder`'s single-file highlight); a missing directory is created as well (opening it shows the storage location, and an empty directory is legal), while an `openPath` failure throws and fails loud. Returns `Promise<void>` |
|
|
@@ -267,7 +267,7 @@ useEffect(() => {
|
|
|
267
267
|
| `group` | ❌ | **a second-level heading inside the group** — keys sharing the same `group` value are rendered under a subheading on the settings page; keys without a `group` stay flat. Declaring a Chinese section name is enough for it to display; heading text goes through i18n (the plugin's `contributes.i18n` provides the translation). Zero shell changes — the shell mechanism works exactly the same for plugin keys |
|
|
268
268
|
| `renderHint` | ❌ | rendering hint for special rows (an open string — an unknown value degrades to the default rendering for the `type`). `"action"` renders a **button** (button text = `description`, clicking runs `actionCommand`); `"readonly"` renders a **read-only status line** (the value is the return value of `statusCommand`, re-fetched every 3 seconds; it does not read configuration storage). Both are general capabilities — any plugin gets them by declaring them; usage and examples in [20-adding-a-setting](20-adding-a-setting.md) |
|
|
269
269
|
| `actionCommand` | ❌ | command executed when a `renderHint: "action"` row is clicked — one of your own commands, or a shell command |
|
|
270
|
-
| `actionDisabledAll` | ❌ | disable condition for a `renderHint: "action"` button — disabled while **every** listed entry matches the current configuration value, shaped as `[{ "key": "…", "value": … }]
|
|
270
|
+
| `actionDisabledAll` | ❌ | disable condition for a `renderHint: "action"` button — disabled while **every** listed entry matches the current configuration value, shaped as `[{ "key": "…", "value": … }]`; **omit it (or pass an empty list) and the button stays always enabled** |
|
|
271
271
|
| `statusCommand` | ❌ | data-source command id for `renderHint: "readonly"` — its return value (a string) is the text shown on that row; the value comes from the command, not from configuration storage |
|
|
272
272
|
|
|
273
273
|
**Two optional fields on the group level** (written on the `configuration` level, not on a key): `subtitle` = one subtitle line under the group name; `groupDescriptions` = **per-section notes**, key = the exact `group` text (it only displays when it matches character for character). Declaring neither = nothing is rendered (zero intrusion).
|
|
@@ -149,7 +149,7 @@ window.linkdesk?.commands?.registerCommand?.("my-plugin.engineStatus", async ()
|
|
|
149
149
|
|
|
150
150
|
- **The button text is `description`** (there is no other string on an action row, so phrase it as an action, not as a noun explanation).
|
|
151
151
|
- Clicking runs `actionCommand`; the command can be **one of your own** or **a shell command** (such as `app.openAiManual`).
|
|
152
|
-
- To grey the button out while some condition holds, add `actionDisabledAll: [{ "key": "my-plugin.engine", "value": "off" }]` — the button is disabled while **every** listed entry matches the current configuration value.
|
|
152
|
+
- To grey the button out while some condition holds, add `actionDisabledAll: [{ "key": "my-plugin.engine", "value": "off" }]` — the button is disabled while **every** listed entry matches the current configuration value. **Leaving the field out means the button is always clickable** (same when none of the entries matches).
|
|
153
153
|
|
|
154
154
|
> All three are **general capabilities**: any plugin gets them by declaring them, and the host has no privilege here (a different settings plugin renders them just the same — the contract lives in `plugin.schema.json`).
|
|
155
155
|
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
# 21 — Command-ification Spec (so AI, keybindings and the Command Palette all take one road)
|
|
2
|
+
|
|
3
|
+
> 2026-09-28 · **In one line**: **everything a user can do in your UI should be a command.**
|
|
4
|
+
> A command is not "a shortcut for power users" — it is the **single entry point for an action**: the Command Palette, keybindings,
|
|
5
|
+
> context menus, automation and AI all come in through the same road.
|
|
6
|
+
> This doc is the **spec + author checklist**; field-level details live in [03-contributes-spec](03-contributes-spec.md) §3.1,
|
|
7
|
+
> and the runtime signature in [01-plugin-api-contract](01-plugin-api-contract.md) (the `commands` namespace).
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## 1. Why (the shell only knows commands)
|
|
12
|
+
|
|
13
|
+
**The shell has zero knowledge about your plugin.** It doesn't know whether you are a serial monitor or a note board — it only knows
|
|
14
|
+
"**some plugin registered these commands**".
|
|
15
|
+
|
|
16
|
+
So "let AI operate my plugin" is not an application or an integration — it is **register a command and you are supported automatically**:
|
|
17
|
+
|
|
18
|
+
| What you do | What appears for free |
|
|
19
|
+
|:--|:--|
|
|
20
|
+
| `contributes.commands` + a pool-side `registerCommand` | One more item in the Command Palette · bindable to a key · referenceable from context menus/title bar/section buttons · **one more callable command on the AI surface (the command list)** |
|
|
21
|
+
|
|
22
|
+
**The flip side**: actions that live only in the UI (buttons that appear on hover, context-menu items, double-clicking a row) have
|
|
23
|
+
**no command at all**. That is fine for a human (they have hands), but for keybindings, for automation and for AI they **do not exist** —
|
|
24
|
+
the only option left is to fake mouse input, and faked mouse input depends on movement thresholds, timing and coordinates, so it can
|
|
25
|
+
silently fail on another machine or another resolution. **A command is one line of JSON; a mouse simulation is a stretch of unreliable code.**
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## 2. Two legs (both are required)
|
|
30
|
+
|
|
31
|
+
| Leg | Where it is written | What it carries |
|
|
32
|
+
|:--:|:--|:--|
|
|
33
|
+
| ① **Metadata** | `plugin.json` → `contributes.commands` | id / title / category / when / **description** / **params** — this is the **manifest**; it is what AI reads |
|
|
34
|
+
| ② **The real handler** | Pool-side code (when the view component mounts) | `window.linkdesk.commands.registerCommand(id, handler, meta)` — this is the **execution**; it lives only in the pool renderer |
|
|
35
|
+
|
|
36
|
+
```json
|
|
37
|
+
{
|
|
38
|
+
"contributes": {
|
|
39
|
+
"commands": [
|
|
40
|
+
{
|
|
41
|
+
"id": "demo-notes.addNote",
|
|
42
|
+
"title": "New Note",
|
|
43
|
+
"category": "Notes",
|
|
44
|
+
"description": "Create a note and return its id",
|
|
45
|
+
"params": [
|
|
46
|
+
{ "name": "title", "type": "string", "description": "Note title (omitted = untitled)" }
|
|
47
|
+
]
|
|
48
|
+
}
|
|
49
|
+
]
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
```typescript
|
|
55
|
+
// Pool side: the real handler (registered when the component mounts; unregisterCommands(pluginId) on unmount)
|
|
56
|
+
useEffect(() => {
|
|
57
|
+
window.linkdesk.commands.registerCommand(
|
|
58
|
+
"demo-notes.addNote",
|
|
59
|
+
(title?: string) => createNote(title), // ← the *same* action function the UI button calls
|
|
60
|
+
{ description: "Create a note and return its id" },
|
|
61
|
+
);
|
|
62
|
+
}, []);
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
> ⚠️ **Declaring without registering a handler** = the palette shows it, clicking does nothing (no-op + a diagnostic warning).
|
|
66
|
+
> The declaration side contributes **metadata** (a placeholder); the handler is what actually runs.
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
## 3. Four things every command should get right
|
|
71
|
+
|
|
72
|
+
1. **`id` carries your own prefix**: `<pluginId>.<action>` (e.g. `demo-notes.addNote`).
|
|
73
|
+
Both AI and users list "what can this plugin do" by **prefix** — an id without one gets attributed to somebody else.
|
|
74
|
+
2. **`description` states the intent; do not restate the id.** That single sentence is **how AI picks a command**: write
|
|
75
|
+
"Delete every message logged in the current session", not "the clearSession command". Without it your command is just an id to AI.
|
|
76
|
+
3. **`params` written position by position** (`name` / `type` / `required` / `description`).
|
|
77
|
+
Callers build `executeCommand(id, ...params)` straight from it and **never have to read your source to guess arguments**.
|
|
78
|
+
4. **State must be readable back.** Once a command changes state, provide a separate read path (a list/query command, or
|
|
79
|
+
`configuration.get()`) — "do it, then verify" is basic behaviour for automation and AI, and with no read path it can only retry blindly.
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## 4. Four things not to do (each one has actually bitten us)
|
|
84
|
+
|
|
85
|
+
1. **⛔ Don't let the caller bypass your plugin.** The command handler must go through **your plugin's own state chain** (your existing
|
|
86
|
+
store/service). Calling a lower-level API directly behind its back produces "the command ran but the UI doesn't know" — the sidebar
|
|
87
|
+
lamp doesn't change, the list doesn't refresh.
|
|
88
|
+
2. **⛔ Don't write the command as a copy of the UI function.** Extract one shared action function and have the button's `onClick` call
|
|
89
|
+
**the same one** as the command handler. Two copies drift apart over time, and no light turns on when they do.
|
|
90
|
+
3. **⛔ Don't leave gestures as the only path.** Hover buttons, context menus and double-clicks **all stay** (they feel good to use), but
|
|
91
|
+
each one needs a command behind it: gestures are **feel**, commands are **entry points**. They coexist; this is not a replacement.
|
|
92
|
+
4. **⛔ Don't bury implicit preconditions in the command.** Express preconditions with `when` and spell them out in `description`
|
|
93
|
+
("requires an open serial port"), instead of relying on "some view happens to be selected right now" — the caller cannot see your focus.
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## 5. Author checklist (tick as you go)
|
|
98
|
+
|
|
99
|
+
- [ ] I listed every action **a user can perform** in my plugin (including the ones that only live on hover buttons / context menus / double-clicked rows)
|
|
100
|
+
- [ ] Each has a `contributes.commands` entry (`id` + `title` required, `id` carries my prefix)
|
|
101
|
+
- [ ] Each has a `description` (one plain sentence, intent first — it is how AI picks the command)
|
|
102
|
+
- [ ] Anything with parameters has `params` (`name` matching the handler's parameter name, one of the four `type` values, `required` marked)
|
|
103
|
+
- [ ] Each has a real handler registered pool-side (`registerCommand`), with `unregisterCommands(pluginId)` on `unmount`
|
|
104
|
+
- [ ] Buttons/menu items and the command handler call **the same** action function (not two implementations)
|
|
105
|
+
- [ ] Anything that changes state also has a **read-back** path (list/query)
|
|
106
|
+
- [ ] Self-test: install it → findable in the Command Palette → `description`/`params` visible in the command list → invoking it works **and the UI reflects it**
|
|
107
|
+
- [ ] I walked these actions through **without a mouse** (keyboard / Command Palette) and every step was reachable
|
|
108
|
+
|
|
109
|
+
---
|
|
110
|
+
|
|
111
|
+
## 6. Scope (how far this spec reaches)
|
|
112
|
+
|
|
113
|
+
- **This doc governs new plugins**; existing plugins are not retrofitted: whether and how thoroughly to add commands is
|
|
114
|
+
**each author's own call**.
|
|
115
|
+
- Whether a plugin command-ifies its business actions is **up to the author** — what this spec guarantees is that
|
|
116
|
+
"**when you do want to be operable by AI, there is a standard way**", not that "every plugin must be command-ified".
|
|
117
|
+
- The scaffolder **ships a command-registration template** with new plugins (see the three tiers in
|
|
118
|
+
[13-development-guide](13-development-guide.md)); this spec is the reasoning behind it. The two are complementary:
|
|
119
|
+
one is **default-by-construction**, the other is **knowing what to write**.
|
|
120
|
+
- `when` only decides **whether a command shows up in menus/the palette** (and whether its keybinding fires); it does **not** block API
|
|
121
|
+
calls — never use `when` as permission control.
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
**Related:** [03-contributes-spec](03-contributes-spec.md) §3.1 (every `contributes.commands` field) ·
|
|
126
|
+
[07-plugin-to-plugin-communication](07-plugin-to-plugin-communication.md) (calling another plugin's command) ·
|
|
127
|
+
[14-data-pipeline-command-conventions](14-data-pipeline-command-conventions.md) (naming conventions for data pipeline commands)
|
package/docs/zh/00-README.md
CHANGED
|
@@ -24,6 +24,7 @@
|
|
|
24
24
|
| **做一个高难度插件**(1 天档:数据管道 / 跨插件 / Canvas / LSP) | [13 的 1 天档](13-插件开发指南.md) | → [07-插件间通信](07-插件间通信.md) · [14-数据管道命令约定](14-数据管道命令约定.md) |
|
|
25
25
|
| **做一个主题**(不写代码) | [主题/01-做一个主题插件](主题/01-做一个主题插件.md) | → [主题/02-主题字段速查](主题/02-主题字段速查.md) |
|
|
26
26
|
| **给我的插件加一条配置项** | [20-我的插件加一条配置项](20-我的插件加一条配置项.md) | → [03-插件contributes规范](03-插件contributes规范.md) |
|
|
27
|
+
| **让 AI / 快捷键 / 命令面板也能操作我的插件** | [21-插件命令化规范](21-插件命令化规范.md) | → [03-插件contributes规范 §3.1](03-插件contributes规范.md)(`commands` 全字段) |
|
|
27
28
|
| **让几个区域联动**(侧栏选中 → 主区切换 → 状态栏更新) | [18-区域间互动](18-区域间互动.md) | → [07-插件间通信](07-插件间通信.md) |
|
|
28
29
|
| **查 API**(能调什么) | [01-插件API契约 §三](01-插件API契约.md)(三处 API 面的入口表) | → SDK 包内 README 速查表 / `linkdesk.d.ts` |
|
|
29
30
|
| **用壳提供的 UI 零件** | [19-组件速查](19-组件速查.md) | → [05-插件UI写法规约](05-插件UI写法规约.md) |
|
|
@@ -177,6 +178,7 @@ npm run publish # 发布到你自己的 GitHub 仓(上
|
|
|
177
178
|
| **18** | **[18-区域间互动](18-区域间互动.md)** | **区域之间怎么联动**——侧栏选中 → 主区切换 → 状态栏更新(配方集) |
|
|
178
179
|
| **19** | **[19-组件速查](19-组件速查.md)** | **壳提供了哪些 UI 零件**、什么时候用哪个 |
|
|
179
180
|
| **20** | **[20-我的插件加一条配置项](20-我的插件加一条配置项.md)** | 最小做法:声明一条 → 设置页自动出现 → 代码里读 |
|
|
181
|
+
| **21** | **[21-插件命令化规范](21-插件命令化规范.md)** | **让 AI/快捷键/命令面板能操作我的插件**——动作做成命令的规范 + 作者检查清单 |
|
|
180
182
|
| **T1** | **[主题/01-做一个主题插件](主题/01-做一个主题插件.md)** | 做主题的动线(零代码) |
|
|
181
183
|
| **T2** | **[主题/02-主题字段速查](主题/02-主题字段速查.md)** | 配方字段与 CSS 变量的对照索引 |
|
|
182
184
|
|
|
@@ -83,8 +83,9 @@ async function list(): Promise<FileEntry[]> {
|
|
|
83
83
|
| **decorations** | **同步契约**:`provideDecoration` 返回 `FileDecoration \| null \| undefined`,**不得返回 Promise**(异步提供方被跳过);同 pluginId 重复 `registerProvider` 幂等覆盖;注销/注册自动全量刷新通知 `onDidChange([])`;provider 抛异常自愈剔除该条目 |
|
|
84
84
|
| **filesystem** | 插件权限:插件数据目录读写、workspace 目录读、**其他插件目录禁止** |
|
|
85
85
|
| **configuration** | 配置 key 命名规则 `<pluginId>.<property>`(如 `editor.fontSize`、`serial-monitor.baudRate`) |
|
|
86
|
+
| **pool(壳×池意图通道)** | 池→壳的**上行意图**只有两条伞形方法(`pool.sidebarAction(action)` / `pool.tabAction(action)`),载荷按 `action` 分派。其中四条是「**拖一下**」的等价通道(M2 `AI#21`/`AI#50` 起在本文档登记;①–③ 每条**另有非鼠标命令出口**,AI/脚本不必真拖):① `sidebarAction({ action: "setSidebarWidth", width })` = 主侧栏分隔线拖拽落地的同一条路(壳 `useSubscriptions` → `LayoutEngine.resizeZone`,钳制随 dock 声明 170–600)→ 命令 `workbench.action.setSidebarWidth(width)` / `…resetSidebarWidth`(回默认 280);② `tabAction({ action: "updateSplitSizes", branchIndex, sizes })` = 分屏分隔线拖拽落地(壳 `useTabManager.updateSplitSizes` → SplitNode 树)→ 命令 `workbench.action.resetSplitSizes`(**所有**分支回 50/50);③ 事件 `events.emit("panel:resize", { height })` = 底部面板顶部手柄拖高落地(壳消费处**轴感知**路由:面板 `edge ∈ {left,right}` 走宽轴 `resizeZone`,`top/bottom` 走高轴 `resizeZoneHeight`)→ 命令 `workbench.action.setPanelSize(size)` / `…resetPanelSize`;④ `sidebarAction({ action: "reorder", containerId, viewId, newIndex })` = 侧栏视图拖拽排序落地的同一条路(壳侧重排容器/视图并持久化;M2 `AI#50` 起在本文档登记——**只有池 API 出口、无宿主命令**:池侧代码可用,外部 AI(CLI/MCP)暂不可达)。⚠️ 前三条是**池基础设施**(Zone 分隔线自用),**不是插件该调的联动手段**——插件要动布局请走上面那些命令(`window.linkdesk.commands.executeCommand`),⛔ 别直接发池内部通道(事件名不带插件前缀,且壳侧怎么路由是实现细节)。 |
|
|
86
87
|
| **serial** | **多口路由:** 打开/关闭/动作定向接口的 `portName` **可选**——缺省 = 唯一打开口(0 口抛「串口未打开」;≥2 口抛「多串口已打开,请指定 portName」;**失败可见,不静默**)。三推流通道(`onData`/`onStats`/`onSystem`)载荷**对象化**带 `portName` 路由键(`SerialDataPayload`/`SerialStatsPayload`/`SerialSystemPayload`)——订阅方按**会话口**过滤(key=portName 是通用路由键模式:谁消费谁过滤,壳不代收)。每标签页仍单口,会话-端口绑定在插件侧 |
|
|
87
|
-
| **panel** | `panel.reveal(viewId)` 声明寻址聚焦底部面板视图——面板隐藏 → 展开并切到该视图(Ctrl+J 同机制);已显示 → 切换聚焦;**viewId 不在 panel 容器 → no-op**(不报错)。**`panel.moveToEditor` 已移除**(弃内容迁移——位置移动是布局命令的事)。 `panel.revealFloating(viewId)` 壳内悬浮面板(类型 B)——按声明弹出某视图为悬浮面板。声明寻址 = ViewContainerService 全局视图索引(`contributes.views` 已注册**任意容器**视图,不限 panel——插件声明 `contributes.floatingPanel.viewId` 引用之)。**身份开关键**:无面板 → 开;同视图 → 关(toggle);他面板 → 替换;**viewId 未声明/声明插件未装 → no-op**(不崩)。面板默认动作 =「在主窗口中打开」(仅声明插件可开成标签页时出现)+ 最大化 toggle +
|
|
88
|
+
| **panel** | `panel.reveal(viewId)` 声明寻址聚焦底部面板视图——面板隐藏 → 展开并切到该视图(Ctrl+J 同机制);已显示 → 切换聚焦;**viewId 不在 panel 容器 → no-op**(不报错)。**`panel.moveToEditor` 已移除**(弃内容迁移——位置移动是布局命令的事)。 `panel.revealFloating(viewId)` 壳内悬浮面板(类型 B)——按声明弹出某视图为悬浮面板。声明寻址 = ViewContainerService 全局视图索引(`contributes.views` 已注册**任意容器**视图,不限 panel——插件声明 `contributes.floatingPanel.viewId` 引用之)。**身份开关键**:无面板 → 开;同视图 → 关(toggle);他面板 → 替换;**viewId 未声明/声明插件未装 → no-op**(不崩)。面板默认动作 =「在主窗口中打开」(仅声明插件可开成标签页时出现)+ 最大化 toggle + 关闭。 **`panel.setFloatingBounds({ top, left, width, height } | null)`**(M2 `AI#20`)——悬浮面板几何的**非鼠标路径**:精确设定位置/大小(省略的字段保持现值,`null` = 回默认居中大卡;面板未开 → no-op)。越界值按**与拖拽同一套边界**钳制(`MIN_HEIGHT` / 右侧上限 / 6px 内边距)。读数走 `commands.getCommands()` 侧的 `workbench.action.getFloatingPanelBounds`(返回最近一次落定几何)。 |
|
|
88
89
|
| **hotExit** | 崩溃恢复专用——脏内容落盘 `%APPDATA%/linkdesk/hot-exit/`(主进程路径约定单源,插件零直写);保存/关闭标签页后调 `clear` 删备份 |
|
|
89
90
|
| **shell** | 壳级 OS 动作:`showItemInFolder(p)` 资源管理器高亮单文件 / `openInTerminal(dirPath, terminalExe?, customCommand?)` 外部终端打开 / `startDrag(filePath, iconPath?)` 拖出到桌面。**`pluginLocation(pluginId)` / `openPluginFolder(pluginId, kind)` 插件磁盘位置两件套**——前者返回 `{ installDir, dataDir } | null`(**给身份不给路径拼装权**:路径由主进程解析,插件侧拿结果;盘上找不到 → `null`;`dataDir` 只在插件**真落过盘**时非 `null`,空/无 = 那行不该画);后者 `kind: "install" \| "data"` 用资源管理器开目录**内容**(同 `appearance.revealStorage` 手感,非 `showItemInFolder` 高亮单文件),`install` 目录不在盘上抛错,`data` 先建空目录再开。**`relaunch` 真重启应用**(退出并重新启动进程)——⚠️ **仅壳 preload 注入(契约 `?` 可选)**,池侧调用前必须判存在(`window.linkdesk.shell.relaunch?.`)。与 `window.location.reload` 的区别是**池在不在**:池是独立 `WebContentsView`,壳 reload 不重建它,更新视图类插件后 reload 只会看到旧 bundle;`relaunch` 调用后本进程随即终止,**不要依赖它的返回值**(Promise 永不落地) |
|
|
90
91
|
| **appearance** | `revealStorage` 打开外观存储目录(`userData/appearance`)——主进程解析路径并 `shell.openPath` 开资源管理器**内容**(非 `showItemInFolder` 高亮单文件);目录缺省也建(打开即见存储位置,空目录合法),`openPath` 失败抛错 fail-loud。返回 `Promise<void>` |
|
|
@@ -267,7 +267,7 @@ useEffect(() => {
|
|
|
267
267
|
| `group` | ❌ | **组内二级标题**——同 `group` 值的 key 在设置页归到子标题下渲染;无 `group` 的 key 保持平铺。声明中文节名即显示;节名标题走 i18n(插件 `contributes.i18n` 提供翻译)。零壳改动——壳机制对插件键同样生效。 |
|
|
268
268
|
| `renderHint` | ❌ | 特殊行的渲染提示(开放 string,未知值降级回 `type` 默认渲染)。`"action"` = 渲染成**按钮**(按钮文字 = `description`,点击执行 `actionCommand`);`"readonly"` = 渲染成**只读状态行**(值 = 执行 `statusCommand` 的返回值,每 3 秒重取;不读配置存储)。两个值都是通用能力——任何插件声明即生效,用法与示例见 [20-我的插件加一条配置项](20-我的插件加一条配置项.md) |
|
|
269
269
|
| `actionCommand` | ❌ | `renderHint: "action"` 的行点击时执行的命令 id——可以是插件自己的命令,也可以是壳命令 |
|
|
270
|
-
| `actionDisabledAll` | ❌ | `renderHint: "action"` 的按钮禁用条件——**列出的每一项都匹配当前配置值**时禁用,形如 `[{ "key": "…", "value": … }]
|
|
270
|
+
| `actionDisabledAll` | ❌ | `renderHint: "action"` 的按钮禁用条件——**列出的每一项都匹配当前配置值**时禁用,形如 `[{ "key": "…", "value": … }]`;**不声明(或空数组)= 按钮始终可点** |
|
|
271
271
|
| `statusCommand` | ❌ | `renderHint: "readonly"` 的数据源命令 id——返回值(字符串)就是那一行显示的文字;值来自命令而非配置存储 |
|
|
272
272
|
|
|
273
273
|
**分组层的两个可选字段**(写在 `configuration` 这层,不在键上):`subtitle` = 分组名下面的一行副标题;`groupDescriptions` = **分节说明**,键 = 该 `group` 的原文(逐字相同才会显示)。两条都不声明 = 不渲染(零侵入)。
|
|
@@ -149,7 +149,7 @@ window.linkdesk?.commands?.registerCommand?.("my-plugin.engineStatus", async ()
|
|
|
149
149
|
|
|
150
150
|
- **按钮文字 = `description`**(这行没有别的字符串可用,所以 `description` 要写成动作短语,别写成名词解释)。
|
|
151
151
|
- 点击时执行 `actionCommand`;命令可以是**你自己注册的**,也可以是**壳命令**(如 `app.openAiManual`)。
|
|
152
|
-
- 想「条件不满足时置灰」:加 `actionDisabledAll: [{ "key": "my-plugin.engine", "value": "off" }]
|
|
152
|
+
- 想「条件不满足时置灰」:加 `actionDisabledAll: [{ "key": "my-plugin.engine", "value": "off" }]`——**列出的每一项都匹配当前配置值**时按钮禁用。**不写这个字段就是永远可点**(写了却没有一项命中,同样可点)。
|
|
153
153
|
|
|
154
154
|
> 三样都是**通用能力**:任何插件声明就生效,宿主没有特权(设置页的渲染方换一只插件也照渲染——契约就写在 `plugin.schema.json` 里)。
|
|
155
155
|
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
# 21 — 插件命令化规范(让 AI、快捷键、命令面板走同一条路)
|
|
2
|
+
|
|
3
|
+
> 2026-09-28 · **一句话**:**界面上能做的每一件事,都该有一条命令**。
|
|
4
|
+
> 命令不是"给高级用户的快捷方式",它是**动作的统一入口**——命令面板、快捷键、右键菜单、自动化与 AI 都从同一条路进来。
|
|
5
|
+
> 本文是**规范 + 作者检查清单**;字段级细节在 [03-插件contributes规范](03-插件contributes规范.md) §3.1,运行期签名在
|
|
6
|
+
> [01-插件API契约](01-插件API契约.md)(`commands` 命名空间)。
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## 一、为什么(壳只认命令)
|
|
11
|
+
|
|
12
|
+
**壳对插件零知识。** 壳不知道你是串口监视器还是便签板,它只知道"**有插件注册了这些命令**"。
|
|
13
|
+
|
|
14
|
+
所以「让 AI 能操作我的插件」不是一份申请、也不是一次接入——而是**你注册了命令,就自动被支持**:
|
|
15
|
+
|
|
16
|
+
| 你做的事 | 自动长出来的入口 |
|
|
17
|
+
|:--|:--|
|
|
18
|
+
| `contributes.commands` + 池侧 `registerCommand` | 命令面板里多一项 · 快捷键可绑 · 右键菜单/顶栏/区块按钮可引用 · **AI 面(命令清单)里多一条可调命令** |
|
|
19
|
+
|
|
20
|
+
**反面**:只活在界面上的动作(悬停才出现的按钮、右键菜单项、双击行)**没有任何命令**——
|
|
21
|
+
对人没问题(他有手),但对快捷键、对自动化、对 AI 都是**不存在**:它们只能去模拟鼠标,而模拟鼠标有位移阈值、时序、坐标依赖,
|
|
22
|
+
换台机器、换个分辨率就可能静默失效。**一条命令是一行 JSON,一次鼠标模拟是一段不可靠的代码。**
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## 二、两条腿(缺一不可)
|
|
27
|
+
|
|
28
|
+
| 腿 | 写在哪 | 写什么 |
|
|
29
|
+
|:--:|:--|:--|
|
|
30
|
+
| ① **元数据** | `plugin.json` → `contributes.commands` | id / title / category / when / **description** / **params** —— 这是**清单**,AI 读的就是它 |
|
|
31
|
+
| ② **真 handler** | 池侧代码(视图组件 `mount` 时) | `window.linkdesk.commands.registerCommand(id, handler, meta)` —— 这是**执行**,只存在于池渲染进程 |
|
|
32
|
+
|
|
33
|
+
```json
|
|
34
|
+
{
|
|
35
|
+
"contributes": {
|
|
36
|
+
"commands": [
|
|
37
|
+
{
|
|
38
|
+
"id": "demo-notes.addNote",
|
|
39
|
+
"title": "新建便签",
|
|
40
|
+
"category": "便签",
|
|
41
|
+
"description": "新建一张便签并返回它的 id",
|
|
42
|
+
"params": [
|
|
43
|
+
{ "name": "title", "type": "string", "description": "便签标题(省略 = 未命名)" }
|
|
44
|
+
]
|
|
45
|
+
}
|
|
46
|
+
]
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
```typescript
|
|
52
|
+
// 池侧:真 handler(组件 mount 时注册;unmount 时 unregisterCommands(pluginId))
|
|
53
|
+
useEffect(() => {
|
|
54
|
+
window.linkdesk.commands.registerCommand(
|
|
55
|
+
"demo-notes.addNote",
|
|
56
|
+
(title?: string) => createNote(title), // ← 与界面按钮调用**同一个**动作函数
|
|
57
|
+
{ description: "新建一张便签并返回它的 id" },
|
|
58
|
+
);
|
|
59
|
+
}, []);
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
> ⚠️ **只声明不注册 handler** = 命令面板里有、点了没反应(no-op + 诊断 warn)。
|
|
63
|
+
> 声明面给出的是**元数据**(placeholder),handler 才是真的能跑。
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## 三、命令要写全的四件事
|
|
68
|
+
|
|
69
|
+
1. **`id` 带自己的前缀**:`<pluginId>.<动作>`(如 `demo-notes.addNote`)。
|
|
70
|
+
AI 与用户都靠**前缀**一次列出"这只插件能做什么"——不带前缀的 id 会被算到别人头上。
|
|
71
|
+
2. **`description` 写意图,不复述 id**。AI 选哪条命令**就看这一句**:写「清空当前会话的全部收发记录」,
|
|
72
|
+
别写「clearSession 命令」。缺这一句,你的命令在 AI 眼里只剩一个 id。
|
|
73
|
+
3. **`params` 逐位写清**(`name` / `type` / `required` / `description`)。
|
|
74
|
+
调用方照 `params` 拼 `executeCommand(id, ...params)`,**不必读你的源码猜参数**。
|
|
75
|
+
4. **状态要能读回来**。命令改了状态之后,另有一条读的路(列表/查询命令,或 `configuration.get()`)——
|
|
76
|
+
"做完验一遍"是自动化与 AI 的基本动作,没有读的路它只能盲目重试。
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## 四、四条别做(都是真踩过的坑)
|
|
81
|
+
|
|
82
|
+
1. **⛔ 别让调用方绕开插件**。命令的 handler 必须落在**插件自己的状态链路上**(走你既有的 store/service)——
|
|
83
|
+
绕过它直调底层 API,会出现「命令跑了、界面不知道」的不一致(侧栏灯不变、列表不更新)。
|
|
84
|
+
2. **⛔ 别把命令写成界面函数的复制品**。抽一个公共动作函数,按钮的 `onClick` 与命令 handler **调同一个**;
|
|
85
|
+
复制一份的下场是两份行为慢慢分叉,而没有任何灯会亮。
|
|
86
|
+
3. **⛔ 别只留手势路径**。悬停按钮、右键菜单、双击**都要保留**(人用着顺手),但每一条背后要有命令——
|
|
87
|
+
手势是**手感**,命令是**入口**,两者并存,不是替换关系。
|
|
88
|
+
4. **⛔ 别把隐式前置塞进命令**。前置条件用 `when` 表达、并在 `description` 里说清("先有打开的串口"这类),
|
|
89
|
+
不要依赖"当前正好选中了某个视图"——调用方看不见你的焦点状态。
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
## 五、作者检查清单(照着勾)
|
|
94
|
+
|
|
95
|
+
- [ ] 我把插件里**用户能做的动作**列了一遍(含只出现在悬停按钮/右键菜单/双击行上的那些)
|
|
96
|
+
- [ ] 每一条都有 `contributes.commands` 条目(`id` + `title` 必填,`id` 带自己的前缀)
|
|
97
|
+
- [ ] 每一条都写了 `description`(一句人话,写意图——AI 就靠它选命令)
|
|
98
|
+
- [ ] 带参数的都写了 `params`(`name` 照 handler 实参名、`type` 四值、必填标 `required`)
|
|
99
|
+
- [ ] 每一条都在池侧注册了真 handler(`registerCommand`),且 `unmount` 时 `unregisterCommands(pluginId)`
|
|
100
|
+
- [ ] 按钮/菜单项与命令 handler 调**同一个**动作函数(不是两份实现)
|
|
101
|
+
- [ ] 改了状态的东西,另有**读回来**的路(列表/查询)
|
|
102
|
+
- [ ] 自测:装进软件 → 命令面板里搜得到 → 命令清单里看得见 `description`/`params` → 调一次生效**且界面同步变化**
|
|
103
|
+
- [ ] 我在**没有鼠标**的情况下走过一遍这些动作(键盘/命令面板),确认每一步都到得了
|
|
104
|
+
|
|
105
|
+
---
|
|
106
|
+
|
|
107
|
+
## 六、边界(这份规范的射程)
|
|
108
|
+
|
|
109
|
+
- **本文治新插件**,不追溯已有插件:存量插件补不补、补到什么程度,**由各插件作者自己定**。
|
|
110
|
+
- 插件要不要业务动作命令化,**取决于作者**——本规范保证的是「**想被 AI 操作时,有标准做法**」,
|
|
111
|
+
不是"所有插件必须命令化"。
|
|
112
|
+
- 生成新插件时脚手架会**自带命令注册样板**(见 [13-插件开发指南](13-插件开发指南.md) 的三档入口),
|
|
113
|
+
本规范是它背后的判据;两者互补:一个是**默认就带**,一个是**写的时候知道该写什么**。
|
|
114
|
+
- `when` 只决定**命令在菜单/面板里出不出现**(以及快捷键是否触发),**不拦 API 调用**——
|
|
115
|
+
别用 `when` 当权限控制。
|
|
116
|
+
|
|
117
|
+
---
|
|
118
|
+
|
|
119
|
+
## 七、常驻纪律(2026-09-29 立 · `AI#49`)
|
|
120
|
+
|
|
121
|
+
- 🔴 **这不是一次性交付**:此后**每个新功能 / 新插件**都必须满足「**① 每个用户动作至少一条非鼠标路径;② 业务动作注册为命令,且注册 meta 带 `description` + `params`**」——壳侧的同一句话已进**壳仓库的硬约束 26**(内部工程规范,此处不指向)。理由:**破洞会随迭代重生**(AI 友好化系列的缘起,就是一个老功能里的隐藏门控卡住了 AI)。
|
|
122
|
+
- **机械自查两条**(写完跑一遍,⛔ 别肉眼过):`npm run audit:plugin-commands`(**只报不拦**——报「有视图声明却零命令」与「整批缺 description」)· `npm run manual:build`(宿主命令手册索引的逐字节漂移门禁;插件命令**不需要**进它,运行期 `getCommands()` 查得到即可)。
|
|
123
|
+
- **验收同样与物理指针无关**:测命令走命令 / API(或 CLI / MCP),⛔ 不拿「截图 → 猜坐标点击」当验证手段;**只出现在指针下的面**(悬停按钮那类)用「**先取元素、再落到元素自身**」的元素锚定方式验——⛔ 不按窗口位置推算坐标(推算出来的坐标换个窗口设置就错位)。
|
|
124
|
+
- ⚠️ **两条实录坑**(2026-09-29 会话 13 验收踩到,写在这省后人一轮):
|
|
125
|
+
1. **注册时机**——在**视图组件挂载时**才 `registerCommand` 的插件,**没开过视图时外部 AI 在命令清单里看不到你的命令**(调了报 `EUNKNOWN`)⇒ 能在 activate 期注册就别拖到 mount(账 = 生长格 `AI#54`)。
|
|
126
|
+
2. **参数形状**——`params` 是**具名**的,执行面却按**位置**透传 ⇒ 调用方照「具名对象」调会**静默无效**(`ok=true` 却没做事);今天的正解 = 调用方按 `params` **顺序平铺**传参,壳侧兼容在账(生长格 `AI#52`)。
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
**相关:** [03-插件contributes规范](03-插件contributes规范.md) §3.1(`contributes.commands` 全字段)·
|
|
131
|
+
[07-插件间通信](07-插件间通信.md)(命令调用另一只插件的命令)·
|
|
132
|
+
[14-数据管道命令约定](14-数据管道命令约定.md)(数据管道命令的命名约定)
|
|
@@ -373,7 +373,7 @@
|
|
|
373
373
|
"uiHint": { "type": "string", "description": "Settings editor rendering hint. SettingsView picks the control from the hint. An unknown hint falls back to the default rendering for its type — no error is thrown. The value is an open string, so third parties may declare new hint names." },
|
|
374
374
|
"renderHint": { "type": "string", "description": "Rendering hint for special rows — \"action\" renders a button (its text comes from description, clicking runs actionCommand); \"readonly\" renders a read-only status line whose value comes from executing statusCommand. Open string — an unknown hint falls back to the default rendering for the type." },
|
|
375
375
|
"actionCommand": { "type": "string", "description": "Command executed when an \"action\" button is clicked — a shell command id or one of your own (resolved when clicked)" },
|
|
376
|
-
"actionDisabledAll": { "type": "array", "description": "Disable the \"action\" button while every entry matches the current configuration value", "items": { "type": "object", "required": ["key", "value"], "properties": { "key": { "type": "string" }, "value": {} }, "additionalProperties": false } },
|
|
376
|
+
"actionDisabledAll": { "type": "array", "description": "Disable the \"action\" button while every entry matches the current configuration value (omit the field entirely — or pass an empty list — to keep the button always enabled)", "items": { "type": "object", "required": ["key", "value"], "properties": { "key": { "type": "string" }, "value": {} }, "additionalProperties": false } },
|
|
377
377
|
"statusCommand": { "type": "string", "description": "Command whose return value (a string) is shown by a \"readonly\" status line — the value comes from the command, not from configuration storage, so a status row can show live runtime state. Shell command id or one of your own." },
|
|
378
378
|
"monoOnly": { "type": "boolean", "description": "Monospace only — meaningful only with uiHint \"fontFamily\". true/omitted = list monospace families only (editor fonts); false = all families (UI fonts)." },
|
|
379
379
|
"minimum": { "type": "number", "description": "Numeric lower bound — applies when type is number (range of the slider/numeric control)" },
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@linkdesk/plugin-docs",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.39",
|
|
4
4
|
"description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"files": [
|