@linkdesk/plugin-docs 0.1.35 → 0.1.37

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.
@@ -29,11 +29,13 @@ A few key points (a summary of Matrix §2; the matrix wins on details):
29
29
 
30
30
  | Fact | Explanation |
31
31
  |------|------|
32
- | **The contract has 40 namespaces** | The pool injects 39 (the only missing one is `bridge`); the shell injects 22; mock injects 12 |
32
+ | **The contract has 46 namespaces** | The pool injects 45 (the only missing one is `bridge`); the shell injects 25; mock injects 13 — **the live readings of the `check-namespace-matrix` gate are authoritative** (this row is mechanically reconciled by it; ⛔ do not copy the comment in `surfaces.ts` — that one drifts too) |
33
33
  | **Pool = the plugin runtime source of truth** | Plugins run in the pool preload — namespaces injected by the pool are **required**; `bridge` is real-shell-only |
34
34
  | **"Shell-only" ≠ plugins can't call it** | `window.*`/`shell.*`/`hotExit.*`/`getFilePath` **are actually injected in the pool** — the older version's ❌ shell-only marking for those surfaces was wrong |
35
35
  | **Contract required-surface drift is now zero** | `env.get(pluginId)` forwarding, `clipboard.readText` shell completion, `dialog.openFile` shell completion — all three are implemented, with no `?` degradation |
36
36
 
37
+ > **That table only says which surfaces are callable — not what can be read.** Read surfaces (reading "what is open right now / what is waiting on the user") get their own section — see §3.3: **an API with an operation surface but no read surface is half-finished** (you can open a tab, yet you cannot read which tabs are open).
38
+
37
39
  ---
38
40
 
39
41
  ## 3. Complete API Definition → Pointer
@@ -42,7 +44,7 @@ A few key points (a summary of Matrix §2; the matrix wins on details):
42
44
 
43
45
  **Every method signature, parameter, return value, and payload type for `window.linkdesk.*` = [contracts/linkdesk.d.ts](https://github.com/Encaron/linkdesk/blob/electron/contracts/linkdesk.d.ts)** (auto-generated; do not hand-edit).
44
46
 
45
- - **Generation sources:** `src/core/api/linkdesk-api.ts` + `linkdesk-api/` (14 domain interfaces) + `src/core/types/ipc/*` + `src/core/types/pool/*` (wire payload types)
47
+ - **Generation sources:** `src/core/api/linkdesk-api.ts` + `linkdesk-api/` (15 domain interfaces) + `src/core/types/ipc/*` + `src/core/types/pool/*` (wire payload types)
46
48
  - **Generator:** `scripts/generate-contract.mjs` (Route C — the contract type file is the source; pure types bundled into a single file)
47
49
  - **Mechanical gate:** the preload on both sides `satisfies` the contract surface types → tsc drift gate; `contracts:check` byte-compares hashes inside `npm run check`
48
50
  - **Coverage matrix:** every namespace × pool/shell/mock coverage → [Namespace Matrix §2](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/契约生成/命名空间矩阵.md#2-命名空间--四面覆盖矩阵)
@@ -101,7 +103,40 @@ async function list(): Promise<FileEntry[]> {
101
103
  | `workspace:changed` | `{ rootPath }` | The user opens/switches a folder |
102
104
  | `plugin:installJobs` | `{ jobs: InstallJob[] }` (**a full snapshot, not a delta**) | The shell-side install/uninstall queue changes (added: stage and percent; added: `kind`·`cancellable`). `InstallJob` = `{ jobId, pluginId, origin: "user"\|"dependency", kind: "install"\|"uninstall", cancellable: boolean, displayName, state: "queued"\|"running"\|"settled", terminal?: "success"\|"failed"\|"parked", error?, stage?, percent?, message? }` — **every broadcast is the whole table**, so consumers **replace their local mirror outright** instead of merging deltas. **Late subscribers get the latest full table**: the pool preload caches one at the top level and replays it synchronously on subscribe (a remounted view never gets stuck on an old snapshot). ⚠️ This is a **public event surface**, not a marketplace-private pipe — any plugin can subscribe and build its own progress UI; ⚠️ **`stage`/`percent`/`message`/`kind`/`cancellable` are additive-only fields**, so older consumers can simply ignore them. ⚠️ `origin: "dependency"` = a dependency some plugin dragged in, nested inside the row that initiated it (`origin: "user"`) |
103
105
 
104
- ### 3.3 Differences from the Old Hand-Written Version (note for readers)
106
+ ### 3.3 Read Surfaces — the machine-readable outlet for "what is open / what is waiting"
107
+
108
+ §3.1/§3.2 describe the **operation surfaces** (what a plugin can do); this section describes the **read surfaces** (what a plugin/AI can **read**).
109
+
110
+ **Why it gets its own section:** a complete operation surface does not add up to automation. If you can open tabs and raise notifications but cannot read "which tabs are open / what is stacked in the notification panel / whether a dialog is waiting on the user", an external driver (AI, scripts, remote control) can only guess — and **a guessed state that disagrees with the screen becomes a false source of truth**, which is worse than having no read surface at all.
111
+
112
+ | Read surface | Method | What you get |
113
+ |:--|:--|:--|
114
+ | **Notifications** | `notifications.list()` | The state of the bell's wide notification panel — count, unread count, each entry's text and buttons, wake and persistence criteria. The return value **is the panel's own DTO** (`NotifLayout`, produced by the same `buildNotif` as `pool.onLayout`'s `statusBar.notif`) |
115
+ | **Notification changes** | `notifications.subscribe(cb)` | A "**it changed just now**" signal (added/updated/dismissed/acknowledged, panel opened/closed). 🔴 **The callback carries no payload** — call `list()` again for the answer (the same "state push + pull on demand" split as `events.on`) |
116
+ | **Tabs** | `tabs.list()` | The tab listing for **all** windows (`TabsSnapshot`: `windowId`/`mode`/`ready`/`activeGroupId`/`root`/`groups`, each group carrying `activeTabId`). Produced by the **same `serializeGroups`** as the layout tree pushed to the pool ⇒ the listing's `label`/`icon` necessarily match the tab drawn on screen |
117
+ | **Layout** | `pool.getLayout()` | The snapshot body of the **most recent** `onLayout` in this window (tree `root` + groups `groups`). No push has arrived yet → `null` (⛔ never invent an empty layout) |
118
+ | **Dialogs in flight** | `dialogHost.pending()` | The confirm/alert currently on screen waiting for the user (`options` verbatim + `kind` + button labels + rich-content view identity). An empty array = nothing is open right now |
119
+ | **Command metadata** | `commands.getCommands()` | Every command's `id`/`title`/`category`/**`description`**/**`params`** (the latter two exist since M1; `params[i]` corresponds positionally to the handler's argument) — the command list itself is a structure you can **feed straight to a large model as a tool list (function calling)** |
120
+
121
+ > Method signatures follow [contracts/linkdesk.d.ts](https://github.com/Encaron/linkdesk/blob/electron/contracts/linkdesk.d.ts); the table above only answers "which ones exist and what they read".
122
+
123
+ **Three rules for read surfaces (for implementers and consumers alike):**
124
+
125
+ 1. **A read surface ≡ the screen, one single ruler.** It must return **the DTO that the screen is drawn from**, ⛔ never a separately computed summary — two rulers inevitably disagree: if the grouping/unread count/text you read differs from what is painted, the read surface has become a false source of truth.
126
+ 2. **Signals and answers are separate.** A subscription only answers "**it changed**" (no payload); answers always come from `list()`. Put data in the signal and someone will stop asking the authority, and a second ruler grows back.
127
+ 3. **Text is already resolved — display it as-is.** Text fields such as `bellTitle`/`panelTitle`/group labels/`timeLabel` are **already resolved by the shell with `t()` in the current language** (the display-text rule) — display them verbatim; do not run i18n again.
128
+
129
+ **Boundaries (all of them "honestly report not knowing", not defects):**
130
+
131
+ - In a **detached window**, `pool.getLayout()` returns a strategy subset (`WINDOW_MODE_STRATEGIES`: `detached` = `titleBar`+`groups`; `drift` = `titleBar`+`panel`) — `statusBar`/`sidebar`/`iconBar` do not exist there. To see the whole picture across windows, use `tabs.list()` (ask the shell).
132
+ - `tabs.list()` returns **all windows in one shot**: the shell has no "current window" source of truth ⇒ filter by `windowId` yourself (⛔ do not expect the shell to guess which window you mean).
133
+ - `notifications.list()` asks the **shell** via `plugins:call` (the shell holds the full state) — so it **also works in a detached window** (reading this window's layout subset would answer "no notifications").
134
+ - In `dialogHost.pending()`, `buttons` is **in declaration order** (`[confirm, cancel]`), **not the left/right positions on screen** (measured: the screen paints cancel on the left and confirm on the right). To act, call `dialogHost.confirm()`/`cancel()` by index, ⛔ never by visual position.
135
+ - **Pool-side only, not implemented in the shell:** `tabs.list()` / `pool.getLayout()` **do not exist** in `preload-shell` (the shell already holds that state in hand and will not ask itself over IPC). Shell views that need them should go through the shell's own services.
136
+
137
+ **Adding a read surface later:** the criterion is one sentence — **"if it is on screen, the machine must be able to read it."** Before adding one, ask three questions: ① does it return the DTO the screen is drawn from? ② does it spawn a second piece of state / a second ruler? ③ does a consumer have a workaround that does not need it (if not ⇒ it is a gap, not an optional extra)?
138
+
139
+ ### 3.4 Differences from the Old Hand-Written Version (note for readers)
105
140
 
106
141
  The old §3.x per-namespace method list has been deleted (= a hand-written second source of truth, guaranteed to drift). The generated contract resolved several places where **the old docs disagreed with the implementation**:
107
142
 
@@ -76,7 +76,12 @@
76
76
  "id": "cad.importDxf",
77
77
  "title": "Import DXF…",
78
78
  "category": "CAD",
79
- "when": "activeEditor == 'cad'"
79
+ "when": "activeEditor == 'cad'",
80
+ "description": "Import CAD geometry from a DXF file into the current project",
81
+ "params": [
82
+ { "name": "layerFilter", "type": "string", "description": "Import only this layer (omit for all)" },
83
+ { "name": "explodeBlocks", "type": "boolean", "description": "Explode blocks into primitive entities" }
84
+ ]
80
85
  }
81
86
  ]
82
87
  }
@@ -89,6 +94,19 @@
89
94
  | `title` | ✅ | display name (an i18n key — the original Chinese text) |
90
95
  | `category` | ❌ | command palette grouping — "CAD" / "Terminal" / "File" |
91
96
  | `when` | ❌ | context key when condition. Without `when` the command is visible in any context |
97
+ | `description` | ❌ | **what this command does** — the intent from the user/AI perspective (an i18n key, same rule as `title`). ⛔ Do not restate the `id`. Omitted = no description |
98
+ | `params` | ❌ | **parameter structure** — an array corresponding positionally to the handler's arguments. Omitted = a command without parameters |
99
+
100
+ **`params` item fields (positionally matching the handler's arguments):**
101
+
102
+ | Field | Required | Description |
103
+ |------|:--:|------|
104
+ | `name` | ✅ | parameter name — **use the handler's own parameter name** (e.g. `tabId` / `settingKey` / `groupId`) |
105
+ | `type` | ✅ | one of four values: `"string"` \| `"number"` \| `"boolean"` \| `"object"` (`object` = a structured payload; document its fields in `description`) |
106
+ | `required` | ❌ | whether the parameter is required. Defaults to `false` (optional) |
107
+ | `description` | ❌ | one sentence on what this parameter is (omit when the name speaks for itself) |
108
+
109
+ > **`description` / `params` travel through `getCommands()` into the contract** (`LinkDeskCommand.description` / `LinkDeskCommand.params`) — consumers (the command palette, automation, AI) can build `executeCommand(id, ...params)` straight from `params` **instead of reading source code to guess the arguments**. The same optional fields exist on **runtime registration** (`registerCommand(id, handler, meta)`); the two are synonymous (declaring them once is enough — a runtime registration usually does not repeat them).
92
110
 
93
111
  **Declaring registers metadata (a placeholder):** `contributes.commands` only registers command metadata (id/title/category/when); **the real handler is registered on the pool side** (pool-side `_poolCommands` wins). A command whose handler was never registered is a no-op when invoked (with a diagnostic warn).
94
112
 
@@ -247,6 +265,12 @@ useEffect(() => {
247
265
  | `enumDescriptions` | ❌ | option descriptions — one-to-one with enum |
248
266
  | `uiHint` | ❌ | rendering hint — SettingsView picks the control from the hint (known values include `"color"`/`"fontFamily"`/`"fontSize"`/`"file"`/`"directory"`/`"slider"`/`"segmented"`/`"image"`; it is an open string — an unknown hint degrades to the default rendering for the type). `"segmented"` = a segmented single-select (the ghost dual-track scheme, declared together with `enum` + `enumDescriptions`; the short label = the part of the enumDescription before `—`, the tooltip = the whole line) |
249
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
+ | `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
+ | `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": … }]` |
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
+
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).
250
274
 
251
275
  **Effect after installation:** the Settings Editor's left navigation tree automatically gains a "CAD Viewer" group → the form is rendered automatically on the right — no hand-written settings UI needed.
252
276
 
@@ -99,7 +99,7 @@ The table below is **reconciled name by name** against it (gate `scripts/check-r
99
99
  |:--|:--|:--|
100
100
  | Host command prefix | `app.`、`core.`、`theme.`、`update.`、`view.`、`workbench.` | Your command id lands in the host's own segment — in the command palette and the keybindings page it looks like a host feature |
101
101
  | Host protocol id | `bracket` | Same name as the host's bracket-matching protocol handler ⇒ one of the two never runs, with no error |
102
- | Host pseudo plugin id | `app`、`appearance` | The host registers as a "plugin" too (shell core / appearance; the former "update" group merged into General on 2026-09-26 — `update` is retired & logged) ⇒ these ids read as the host itself |
102
+ | Host pseudo plugin id | `app`、`appearance`、`ai-bridge` | The host registers as a "plugin" too (shell core / appearance / AI integration section; the former "update" group merged into General on 2026-09-26 — `update` is retired & logged) ⇒ these ids read as the host itself; its config keys (`ai.*`) are under the same protected-zone rules |
103
103
  | Host config key | `app.schemaVersion` | The config **internal version marker** (invisible in the settings UI, never registered) — taking it derails migration bookkeeping and the user's data looks lost |
104
104
  | Host config key | `app.theme`、`app.themeColor`、`app.themeColorMode`、`app.iconTheme` | Theme and colours — taking it overwrites the theme the user is currently using |
105
105
  | Host config key | `app.appearanceMode`、`app.accentColor`、`app.accentMode`、`app.accentSource`、`app.menuStyle`、`app.hint.enabled` | Light/dark mode, accent colour, menu style, hover hints |
@@ -86,6 +86,8 @@ The version of `@linkdesk/ui` **equals the version of the LinkDesk shell you ins
86
86
  | `OverlayPortal` | Overlay portal host | Use it when a custom-drawn dialog needs to portal to body; don't scatter bare `createPortal` calls everywhere |
87
87
  | `HintTip` | Lightweight hover hint (component form) | For "give it a child element and one sentence" — **most cases just write the `data-hint` attribute, no import needed**; use this component when you want to control the wrapper yourself (see [05-UI Conventions](05-ui-conventions.md) §13; a native `title=` is red) |
88
88
  | `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 |
89
+ | `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)) |
90
+ | `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 |
89
91
 
90
92
  > 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**.
91
93
 
@@ -65,6 +65,9 @@ Once installed into LinkDesk, a "My Plugin" group appears on the left of the set
65
65
  | **A more fitting widget** (color picker / slider / file picker…) | `uiHint` — see the table below |
66
66
  | Subheadings inside the same group | `group` — entries sharing a `group` value collect under one second-level heading |
67
67
  | Dropdown options that **show a short label**, with the full sentence on hover | `enum` + `enumDescriptions`, together with `uiHint: "segmented"` |
68
+ | The entry is not user-editable but **shows a live status** | `renderHint: "readonly"` + `statusCommand` — see 2.2 below |
69
+ | The entry is a **button** (click to do something) | `renderHint: "action"` + `actionCommand` — see 2.3 below |
70
+ | A one-line note under the group name / under each section | `subtitle` / `groupDescriptions` (written on the `configuration` level, not on a key) |
68
71
 
69
72
  **Known `uiHint` values** (an unknown value falls back to the default rendering for its `type`, without error):
70
73
 
@@ -90,6 +93,66 @@ Once installed into LinkDesk, a "My Plugin" group appears on the left of the set
90
93
 
91
94
  > ⚠️ **There is no `"integer"`** — integers use `"number"` too (with `step: 1`).
92
95
 
96
+ ### 2.1 Notes for the Group and Its Sections
97
+
98
+ Besides the group name (`title`) you can add one subtitle line under it, and one line under each section (`group`) — **written on the `configuration` level**:
99
+
100
+ ```jsonc
101
+ "configuration": {
102
+ "title": "My Plugin",
103
+ "subtitle": "What this whole group is about, in one line",
104
+ "groupDescriptions": { "Sampling": "The settings here affect the sampling stage" },
105
+ "properties": { /* … */ }
106
+ }
107
+ ```
108
+
109
+ Both are optional. The key in `groupDescriptions` **must match the `group` text on the entry character for character** (otherwise that line does not appear); sections you don't describe stay exactly as they were — no empty rows.
110
+
111
+ ### 2.2 Read-Only Status Row: Show **Live State**, Not a Configuration Value
112
+
113
+ Some rows are not meant to be edited; they let the user (and an AI) **see what is happening right now** — for example "Channel status: running · 127.0.0.1:47001". Use `renderHint: "readonly"` for those: the value comes from the **return value of a command**, and it is re-fetched **every 3 seconds**, so what you see is a live reading.
114
+
115
+ ```jsonc
116
+ "my-plugin.engine.status": {
117
+ "type": "string", "default": "",
118
+ "description": "Engine status",
119
+ "renderHint": "readonly",
120
+ "statusCommand": "my-plugin.engineStatus" // ← a command you registered (returns one line of text)
121
+ }
122
+ ```
123
+
124
+ ```ts
125
+ // Register that command in your plugin — its return value is the text shown on the row (\n allowed)
126
+ window.linkdesk?.commands?.registerCommand?.("my-plugin.engineStatus", async () => {
127
+ return connected ? `running · ${endpoint}` : "not connected";
128
+ });
129
+ ```
130
+
131
+ | Point | Explanation |
132
+ |:--|:--|
133
+ | Where the value comes from | **The command**, not `configuration` — that is why it can show runtime state; `default` only exists to satisfy validation and is never displayed |
134
+ | What the command returns | A string (use `\n` for multiple lines; rendered as multiple lines) |
135
+ | Whose command goes in `statusCommand` | **One of your own**; a shell command id works too, as long as you know what it returns |
136
+ | Can the user edit it? | No — it is a read-only row with no input control |
137
+ | What if the command does not exist yet | The row stays **blank** (no error, no placeholder) — so don't expect text before the command is registered |
138
+
139
+ ### 2.3 Button Row: Click to Do Something
140
+
141
+ ```jsonc
142
+ "my-plugin.openDashboard": {
143
+ "type": "string", "default": "",
144
+ "description": "Open dashboard", // ← this line is the button text
145
+ "renderHint": "action",
146
+ "actionCommand": "my-plugin.showDashboard" // ← executed when clicked
147
+ }
148
+ ```
149
+
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
+ - 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.
153
+
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
+
93
156
  ---
94
157
 
95
158
  ## 3. Step 3: Read It in Code
@@ -29,11 +29,13 @@
29
29
 
30
30
  | 事实 | 说明 |
31
31
  |------|------|
32
- | **契约 40 命名空间** | 池注入 39(唯一缺 `bridge`);壳注入 22;mock 注入 12 |
32
+ | **契约 46 命名空间** | 池注入 45(唯一缺 `bridge`);壳注入 25;mock 注入 13——**以 `check-namespace-matrix` 门禁的活读数为准**(本行已由它机械对账,⛔ 别照 `surfaces.ts` 里的注释抄,那份也在漂) |
33
33
  | **池 = 插件运行时真相源** | 插件运行在池(pool)preload——池注入的命名空间为 **required**;`bridge` 真壳独有 |
34
34
  | **「仅壳」≠ 插件不可调** | `window.*`/`shell.*`/`hotExit.*`/`getFilePath` 池**实有注入**——旧版把这几面标 ❌ 仅壳是错的 |
35
35
  | **契约必选面漂移已清零** | `env.get(pluginId)` 转发、`clipboard.readText` 壳补、`dialog.openFile` 壳补——三项都已补齐实现,无 `?` 降级 |
36
36
 
37
+ > **上面这张表只说「哪面能调」,不说「能读到什么」。** 读取面(插件/AI 读「现在有什么、在等什么」)单列一章——见 §3.3:**只有操作面、没有读取面的 API 是半成品**(能开标签页,却读不到现在开了哪些)。
38
+
37
39
  ---
38
40
 
39
41
  ## 三、完整 API 定义 → 指针
@@ -42,7 +44,7 @@
42
44
 
43
45
  **`window.linkdesk.*` 的全部方法签名、入参、返回、载荷类型 = [contracts/linkdesk.d.ts](https://github.com/Encaron/linkdesk/blob/electron/contracts/linkdesk.d.ts)**(自动生成,勿手改)。
44
46
 
45
- - **生成源:** `src/core/api/linkdesk-api.ts` + `linkdesk-api/`(14 域接口)+ `src/core/types/ipc/*` + `src/core/types/pool/*`(wire 载荷类型)
47
+ - **生成源:** `src/core/api/linkdesk-api.ts` + `linkdesk-api/`(15 域接口)+ `src/core/types/ipc/*` + `src/core/types/pool/*`(wire 载荷类型)
46
48
  - **生成器:** `scripts/generate-contract.mjs`(Route C——契约类型文件为源,纯类型打包单文件)
47
49
  - **机械门禁:** preload 双端 `satisfies` 契约面类型 → tsc 漂移门禁;`npm run check` 内 `contracts:check` hash 字节比对
48
50
  - **覆盖矩阵:** 每个命名空间 × 池/壳/mock 四面覆盖 → [命名空间矩阵 §2](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E5.8_归一化基建/契约生成/命名空间矩阵.md#2-命名空间--四面覆盖矩阵)
@@ -101,7 +103,40 @@ async function list(): Promise<FileEntry[]> {
101
103
  | `workspace:changed` | `{ rootPath }` | 用户打开/切换文件夹 |
102
104
  | `plugin:installJobs` | `{ jobs: InstallJob[] }`(**全量快照,非增量**) | 壳侧安装/卸载队列变化(建 /补阶段与百分比 /补 `kind`·`cancellable`)。`InstallJob` = `{ jobId, pluginId, origin: "user"\|"dependency", kind: "install"\|"uninstall", cancellable: boolean, displayName, state: "queued"\|"running"\|"settled", terminal?: "success"\|"failed"\|"parked", error?, stage?, percent?, message? }`——**每次广播都是整表**,消费方**直接替换本地镜像**,别做增量合并。**晚订阅者拿到最新整表**:池 preload 顶层缓存一份、订阅时同步回放(视图重挂不会停在旧快照)。⚠️ 这是**公开事件面**,不是市场私有管道——任何插件可订阅做自己的进度面;⚠️ **`stage`/`percent`/`message`/`kind`/`cancellable` 均为只增不改的增补字段**,旧消费方忽略即可。⚠️ `origin: "dependency"` = 某插件自己拖来的依赖,藏在发起它的那一行(`origin: "user"`)里面 |
103
105
 
104
- ### 3.3 与旧手写版的差异(读者注意)
106
+ ### 3.3 读取面——「现在有什么 / 在等什么」的机器出口
107
+
108
+ §3.1/§3.2 讲的是**操作面**(插件能做什么);本节讲**读取面**(插件/AI 能**读到**什么)。
109
+
110
+ **为什么单列一章:** 操作面齐全 ≠ 自动化可行。能开标签页、能弹通知,却没有「现在开了哪些标签 / 面板里堆着什么通知 / 有没有弹窗在等用户」的读法,外部驱动方(AI、脚本、远程控制)就只能靠猜——**猜出来的状态与屏幕一不符,就成了假信息源**,比没有读取面更坏。
111
+
112
+ | 读取面 | 方法 | 读到什么 |
113
+ |:--|:--|:--|
114
+ | **通知** | `notifications.list()` | 铃铛宽通知面板现状——条数、未读计数、每条文案与按钮、唤醒与存活判据。返回 = **面板的 DTO 本体**(`NotifLayout`,与 `pool.onLayout` 的 `statusBar.notif` 同一个 `buildNotif` 产出) |
115
+ | **通知变更** | `notifications.subscribe(cb)` | 「**现在变了**」信号(新增/更新/收掉/认账/面板开合)。🔴 **回调不带载荷**——要答案请再 `list()`(「状态推流 + 按需拉」分工,同 `events.on` 那套) |
116
+ | **标签** | `tabs.list()` | 全部窗口的标签清单(`TabsSnapshot`:`windowId`/`mode`/`ready`/`activeGroupId`/`root`/`groups`,每组含 `activeTabId`)。与推给池的布局树**同一个 `serializeGroups`** ⇒ 清单里的 `label`/`icon` 与屏幕上那一条必然一致 |
117
+ | **布局** | `pool.getLayout()` | 本窗**最近一次** `onLayout` 的快照本体(树 `root` + 分组 `groups`)。未收到过任何推送 → `null`(⛔ 不编一份空布局) |
118
+ | **在途弹窗** | `dialogHost.pending()` | 此刻正弹着、等用户决定的 confirm/alert(`options` 原形 + `kind` + 按钮文案 + 富内容视图身份)。空数组 = 此刻没有弹窗 |
119
+ | **命令元数据** | `commands.getCommands()` | 全部命令的 `id`/`title`/`category`/**`description`**/**`params`**(后两者 M1 起有;`params[i]` 与 handler 实参**逐位对应**)——命令清单本身就是一份**可直接喂给大模型当工具清单(function calling)**的结构 |
120
+
121
+ > 方法签名以 [contracts/linkdesk.d.ts](https://github.com/Encaron/linkdesk/blob/electron/contracts/linkdesk.d.ts) 为准;上表只回答「哪几件、读什么」。
122
+
123
+ **三条读取面规矩(写给实现者,也写给消费方):**
124
+
125
+ 1. **读取面 ≡ 屏幕,同一把尺。** 返回的必须是**屏幕上那份 DTO 本体**,⛔ 不许另算一份摘要——两把尺子必然打架:读到的分组/未读/文案若与屏幕上画的不同,读取面就成了假信息源。
126
+ 2. **信号与答案分家。** 订阅只回答「**变了**」(无载荷),答案一律问 `list()`。信号里带了数据,就会有人不去问权威,于是又长出第二把尺。
127
+ 3. **文案已解析,原样显示。** `bellTitle`/`panelTitle`/分组 label/`timeLabel` 等文案类字段**已由壳按当前语言 `t()` 解析**(显示文本铁律)——调用方原样显示,不要再查一次 i18n。
128
+
129
+ **边界(都是「如实报不知道」,不是缺陷):**
130
+
131
+ - `pool.getLayout()` 在**脱出窗**拿到的是策略子集(`WINDOW_MODE_STRATEGIES`:`detached` = `titleBar`+`groups`;`drift` = `titleBar`+`panel`)——那些窗里 `statusBar`/`sidebar`/`iconBar` 不存在。要跨窗看全貌用 `tabs.list()`(问壳)。
132
+ - `tabs.list()` **全窗一次性给全**:壳侧没有「当前窗」这个真相源 ⇒ 调用方自己按 `windowId` 筛(⛔ 别指望壳猜你想看哪一窗)。
133
+ - `notifications.list()` 经 `plugins:call` 问**壳**(壳持全量状态)——所以**脱出窗也拿得到**(只读本窗布局子集会答「没有通知」)。
134
+ - `dialogHost.pending()` 的 `buttons` **序 = 声明序**(`[确认, 取消]`),**不是屏幕上的左右位**(实测:屏幕上取消画左、确认画右)。想动手就按序号调 `dialogHost.confirm()`/`cancel()`,⛔ 别拿视觉位置对号入座。
135
+ - **池侧读、壳侧不实现**:`tabs.list()` / `pool.getLayout()` 在 `preload-shell` 里**不存在**(壳自己手上就是那份 state,不绕 IPC 问自己)。壳内视图要用请走壳自己的 service。
136
+
137
+ **将来要加读取面:** 判据一句话——**「屏幕上有的,机器就得读得到」**。加一件前先问三句:① 返回的是不是屏幕那份 DTO 本体?② 有没有因此长出第二份状态/第二把尺?③ 消费方有没有不靠它的替代路径(没有 ⇒ 这是缺口,不是可选项)。
138
+
139
+ ### 3.4 与旧手写版的差异(读者注意)
105
140
 
106
141
  旧版 §3.x 逐命名空间方法清单已删除(= 手写第二份真相源,必然漂移)。生成的契约解决了几处**旧文档与实现不符**的漂移:
107
142
 
@@ -76,7 +76,12 @@
76
76
  "id": "cad.importDxf",
77
77
  "title": "导入 DXF…",
78
78
  "category": "CAD",
79
- "when": "activeEditor == 'cad'"
79
+ "when": "activeEditor == 'cad'",
80
+ "description": "从 DXF 文件导入图形到当前工程",
81
+ "params": [
82
+ { "name": "layerFilter", "type": "string", "description": "只导入该图层(省略 = 全部)" },
83
+ { "name": "explodeBlocks", "type": "boolean", "description": "块是否炸开为基本图元" }
84
+ ]
80
85
  }
81
86
  ]
82
87
  }
@@ -89,8 +94,21 @@
89
94
  | `title` | ✅ | 显示名称(i18n key——中文原文) |
90
95
  | `category` | ❌ | 命令面板分组——"CAD" / "终端" / "文件" |
91
96
  | `when` | ❌ | context key when 条件。不加 `when` = 任何上下文可见 |
97
+ | `description` | ❌ | **这条命令干什么**——用户/AI 视角的意图(i18n key,同 `title` 规矩)。⛔ 不复述 `id`。缺省 = 无说明 |
98
+ | `params` | ❌ | **参数结构**——数组,逐位对应 handler 实参。缺省 = 无参数命令 |
92
99
 
93
- **声明即注册元数据(placeholder):** `contributes.commands` 只注册命令元数据(id/title/category/when),**真实 handler 在池侧注册**(池侧 `_poolCommands` 优先)。不注册 handler 的命令被调用 → no-op(诊断 warn)。
100
+ **`params` 条目字段(逐位对应 handler 实参):**
101
+
102
+ | 字段 | 必需 | 说明 |
103
+ |------|:--:|------|
104
+ | `name` | ✅ | 参数名——**照 handler 实参名写**(如 `tabId` / `settingKey` / `groupId`) |
105
+ | `type` | ✅ | 四值收敛:`"string"` \| `"number"` \| `"boolean"` \| `"object"`(`object` = 结构化载荷,字段明细写在 `description`) |
106
+ | `required` | ❌ | 是否必填。缺省 `false`(可选) |
107
+ | `description` | ❌ | 一句话说明这个参数是什么(省略 = 名字已自明) |
108
+
109
+ > **`description` / `params` 随 `getCommands()` 出契约**(`LinkDeskCommand.description` / `LinkDeskCommand.params`)——消费方(命令面板、自动化、AI)照 `params` 拼 `executeCommand(id, ...params)` 即可,**不必读源码猜参数**。同名字段在**运行时注册**(`registerCommand(id, handler, meta)`)上同样可选,两处同义(声明面写一次即可,运行时注册通常不必重复)。
110
+
111
+ **声明即注册元数据(placeholder):** `contributes.commands` 只注册命令元数据(id/title/category/when/description/params),**真实 handler 在池侧注册**(池侧 `_poolCommands` 优先)。不注册 handler 的命令被调用 → no-op(诊断 warn)。
94
112
 
95
113
  ```typescript
96
114
  // 池侧注册真实 handler(组件 mount 时)
@@ -247,6 +265,12 @@ useEffect(() => {
247
265
  | `enumDescriptions` | ❌ | 选项说明——和 enum 一一对应 |
248
266
  | `uiHint` | ❌ | 渲染提示——SettingsView 按 hint 选择控件(已知值 `"color"`/`"fontFamily"`/`"fontSize"`/`"file"`/`"directory"`/`"slider"`/`"segmented"`/`"image"` 等,开放 string——未知 hint 降级回 type 默认渲染)。`"segmented"` = 分段单选(ghost 双轨制,配合 `enum` + `enumDescriptions` 声明,短标签 = enumDescription `—` 前段、tooltip = 全句) |
249
267
  | `group` | ❌ | **组内二级标题**——同 `group` 值的 key 在设置页归到子标题下渲染;无 `group` 的 key 保持平铺。声明中文节名即显示;节名标题走 i18n(插件 `contributes.i18n` 提供翻译)。零壳改动——壳机制对插件键同样生效。 |
268
+ | `renderHint` | ❌ | 特殊行的渲染提示(开放 string,未知值降级回 `type` 默认渲染)。`"action"` = 渲染成**按钮**(按钮文字 = `description`,点击执行 `actionCommand`);`"readonly"` = 渲染成**只读状态行**(值 = 执行 `statusCommand` 的返回值,每 3 秒重取;不读配置存储)。两个值都是通用能力——任何插件声明即生效,用法与示例见 [20-我的插件加一条配置项](20-我的插件加一条配置项.md) |
269
+ | `actionCommand` | ❌ | `renderHint: "action"` 的行点击时执行的命令 id——可以是插件自己的命令,也可以是壳命令 |
270
+ | `actionDisabledAll` | ❌ | `renderHint: "action"` 的按钮禁用条件——**列出的每一项都匹配当前配置值**时禁用,形如 `[{ "key": "…", "value": … }]` |
271
+ | `statusCommand` | ❌ | `renderHint: "readonly"` 的数据源命令 id——返回值(字符串)就是那一行显示的文字;值来自命令而非配置存储 |
272
+
273
+ **分组层的两个可选字段**(写在 `configuration` 这层,不在键上):`subtitle` = 分组名下面的一行副标题;`groupDescriptions` = **分节说明**,键 = 该 `group` 的原文(逐字相同才会显示)。两条都不声明 = 不渲染(零侵入)。
250
274
 
251
275
  **安装后效果:** Settings Editor 左侧导航树自动出现 "CAD 查看器" 分组 → 右侧自动渲染表单——不需要手写设置界面。
252
276
 
@@ -101,7 +101,7 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
101
101
  |:--|:--|:--|
102
102
  | 宿主命令前缀 | `app.`、`core.`、`theme.`、`update.`、`view.`、`workbench.` | 你的命令 id 落进宿主自己的段——命令面板、快捷键设置页里它看起来像宿主的功能 |
103
103
  | 宿主协议 id | `bracket` | 与宿主的括号匹配协议处理器同名 ⇒ 有一方不生效(不报错) |
104
- | 宿主伪 pluginId | `app`、`appearance` | 宿主自己也以「插件」身份注册(壳通用 / 外观;原「更新」组 2026-09-26 并入「通用」,`update` 已退役登记)⇒ 用这些 id 会被当成宿主自己 |
104
+ | 宿主伪 pluginId | `app`、`appearance`、`ai-bridge` | 宿主自己也以「插件」身份注册(壳通用 / 外观 / AI 接入分区;原「更新」组 2026-09-26 并入「通用」,`update` 已退役登记)⇒ 用这些 id 会被当成宿主自己;其名下配置键(`ai.*`)同样受保护区管辖 |
105
105
  | 宿主配置键 | `app.schemaVersion` | 配置的**内部版本标志**(设置界面里看不到、也没有注册过)——占它会让迁移记账错乱,用户数据看着丢 |
106
106
  | 宿主配置键 | `app.theme`、`app.themeColor`、`app.themeColorMode`、`app.iconTheme` | 主题与配色——占它 = 直接顶掉用户当前选的主题 |
107
107
  | 宿主配置键 | `app.appearanceMode`、`app.accentColor`、`app.accentMode`、`app.accentSource`、`app.menuStyle`、`app.hint.enabled` | 亮暗模式、强调色、菜单样式、悬停提示 |
@@ -87,6 +87,8 @@ import { Button, Toggle, ContextMenu } from "@linkdesk/ui";
87
87
  | `OverlayPortal` | 弹层 portal 宿主 | 自绘弹窗要 portal 到 body 时用它,别裸写 `createPortal` 到处飘 |
88
88
  | `HintTip` | 轻量悬停提示(组件式) | 「给它一个子元素、一句话」——**多数场景直接写 `data-hint` 属性即可,不必 import**;要自己控制包裹时用这个组件(见 [05-插件UI写法规约](05-插件UI写法规约.md) §13;原生 `title=` 判红) |
89
89
  | `HintCard` | 贴锚的悬停说明卡(非交互) | 「停在某个小标上出一张说明卡」——给 `lines`(1–3 句)与锚元素,触发/定位/玻璃全归壳;⛔ 卡内不放链接按钮 |
90
+ | `ReadOnlyText` | 只读文字(单行/多行,不可编辑) | 显示**只读值**:路径、地址、实时状态行(设置页的只读状态行使的就是它——声明 `renderHint: "readonly"` + `statusCommand` 即可,见 [20-我的插件加一条配置项](20-我的插件加一条配置项.md)) |
91
+ | `SectionSubtitle` | 分节副标题(标题下的一行小字) | 分组/分节下面的一行说明——设置页用它渲染 `subtitle` / `groupDescriptions`,自己拼说明区时也可以直接用它 |
90
92
 
91
93
  > 清单以包的实际导出面为准(`packages/linkdesk-ui/src/index.ts` 是唯一真相源)——本页若与包不一致,**以包为准**。
92
94
 
@@ -65,6 +65,9 @@ npm run validate # 校验 plugin.json 合法
65
65
  | **换一个更合适的控件**(取色器 / 滑杆 / 文件选择…) | `uiHint`——见下表 |
66
66
  | 同一分组里再分小标题 | `group`——同 `group` 值的几条会归到一个二级标题下 |
67
67
  | 下拉选项**显示短标签**、鼠标悬停看全句 | `enum` + `enumDescriptions`,并配 `uiHint: "segmented"` |
68
+ | 这一项不是给用户改的,而是**显示一个实时状态** | `renderHint: "readonly"` + `statusCommand`——见 §二·2 |
69
+ | 这一项是个**按钮**(点一下去做某件事) | `renderHint: "action"` + `actionCommand`——见 §二·3 |
70
+ | 分组名下面加一行说明 / 每个小分节加一行说明 | `subtitle` / `groupDescriptions`(写在 `configuration` 这一层,不是键上) |
68
71
 
69
72
  **`uiHint` 已知值**(未知值会降级回按 `type` 默认渲染,不会报错):
70
73
 
@@ -90,6 +93,66 @@ npm run validate # 校验 plugin.json 合法
90
93
 
91
94
  > ⚠️ **没有 `"integer"`**——整数也用 `"number"`(配 `step: 1`)。
92
95
 
96
+ ### 二·1 分组与小分节的说明文字
97
+
98
+ 分组名(`title`)下面可以加一行副标题,每个小分节(`group`)也可以各加一行——**写在 `configuration` 这一层**:
99
+
100
+ ```jsonc
101
+ "configuration": {
102
+ "title": "我的插件",
103
+ "subtitle": "这个分组整体是干什么的,一行话",
104
+ "groupDescriptions": { "采样": "这一节里的设置影响采样阶段" },
105
+ "properties": { /* … */ }
106
+ }
107
+ ```
108
+
109
+ 两条都可选。`groupDescriptions` 的键**必须与键上写的 `group` 逐字相同**(否则那一行不会出现);没有声明的分节保持原样,不会留空行。
110
+
111
+ ### 二·2 只读状态行:显示**实时状态**,不是配置值
112
+
113
+ 有些行不是让用户改的,而是让他(和 AI)**看见正在发生什么**——比如「通道状态:运行中 · 127.0.0.1:47001」。这类行用 `renderHint: "readonly"`:它的值来自**一条命令的返回值**,每次渲染后还会**每 3 秒重取一次**,所以显示的是活读数。
114
+
115
+ ```jsonc
116
+ "my-plugin.engine.status": {
117
+ "type": "string", "default": "",
118
+ "description": "引擎当前状态",
119
+ "renderHint": "readonly",
120
+ "statusCommand": "my-plugin.engineStatus" // ← 你自己注册的命令(返回一句话)
121
+ }
122
+ ```
123
+
124
+ ```ts
125
+ // 插件代码里注册这条命令——返回值就是那一行要显示的文字(可含 \n 换行)
126
+ window.linkdesk?.commands?.registerCommand?.("my-plugin.engineStatus", async () => {
127
+ return connected ? `运行中 · ${endpoint}` : "未连接";
128
+ });
129
+ ```
130
+
131
+ | 要点 | 说明 |
132
+ |:--|:--|
133
+ | 值从哪来 | **命令行**,不读 `configuration`——所以它能显示运行时状态;`default` 只为通过校验,不会显示 |
134
+ | 命令返回什么 | 一个字符串(多行用 `\n`,渲染成多行) |
135
+ | `statusCommand` 写谁的 | **你自己注册的命令**;写壳命令 id 也行(只要你清楚它返回什么) |
136
+ | 用户能改吗 | 不能——这是只读行,没有输入控件 |
137
+ | 命令还不存在会怎样 | 那一行**空着**(不报错、不占位)——所以别在命令注册前就指望它有字 |
138
+
139
+ ### 二·3 按钮行:点一下去做某件事
140
+
141
+ ```jsonc
142
+ "my-plugin.openDashboard": {
143
+ "type": "string", "default": "",
144
+ "description": "打开仪表盘", // ← 这一行就是按钮上的文字
145
+ "renderHint": "action",
146
+ "actionCommand": "my-plugin.showDashboard" // ← 点击时执行这条命令
147
+ }
148
+ ```
149
+
150
+ - **按钮文字 = `description`**(这行没有别的字符串可用,所以 `description` 要写成动作短语,别写成名词解释)。
151
+ - 点击时执行 `actionCommand`;命令可以是**你自己注册的**,也可以是**壳命令**(如 `app.openAiManual`)。
152
+ - 想「条件不满足时置灰」:加 `actionDisabledAll: [{ "key": "my-plugin.engine", "value": "off" }]`——**列出的每一项都匹配当前配置值**时按钮禁用。
153
+
154
+ > 三样都是**通用能力**:任何插件声明就生效,宿主没有特权(设置页的渲染方换一只插件也照渲染——契约就写在 `plugin.schema.json` 里)。
155
+
93
156
  ---
94
157
 
95
158
  ## 三、第 3 步:在代码里读它
@@ -299,7 +299,26 @@
299
299
  "id": { "type": "string", "description": "Command ID — e.g. terminal.clear" },
300
300
  "title": { "type": "string", "description": "Display name" },
301
301
  "category": { "type": "string", "description": "Command palette group" },
302
- "when": { "type": "string", "description": "context key when condition — e.g. activeEditor == 'terminal'" }
302
+ "when": { "type": "string", "description": "context key when condition — e.g. activeEditor == 'terminal'" },
303
+ "description": {
304
+ "type": "string",
305
+ "description": "What this command does — the intent from the user/AI perspective. Do not restate the command id."
306
+ },
307
+ "params": {
308
+ "type": "array",
309
+ "description": "Parameter structure — items correspond positionally to the handler's arguments.",
310
+ "items": {
311
+ "type": "object",
312
+ "required": ["name", "type"],
313
+ "properties": {
314
+ "name": { "type": "string", "description": "Parameter name — must match the handler's parameter name (e.g. tabId / settingKey / groupId)" },
315
+ "type": { "type": "string", "enum": ["string", "number", "boolean", "object"], "description": "Parameter type — object = structured payload (document its fields in description)" },
316
+ "required": { "type": "boolean", "description": "Whether the parameter is required. Defaults to false." },
317
+ "description": { "type": "string", "description": "One sentence on what this parameter is" }
318
+ },
319
+ "additionalProperties": false
320
+ }
321
+ }
303
322
  },
304
323
  "additionalProperties": false
305
324
  }
@@ -337,6 +356,8 @@
337
356
  "required": ["title", "properties"],
338
357
  "properties": {
339
358
  "title": { "type": "string", "description": "Settings group name" },
359
+ "subtitle": { "type": "string", "description": "One-line subtitle under the group title (optional — omitted = nothing is rendered)" },
360
+ "groupDescriptions": { "type": "object", "description": "Per-section one-line description — key = the group's exact text, value = the line shown under that section heading (optional)", "additionalProperties": { "type": "string" } },
340
361
  "properties": {
341
362
  "type": "object",
342
363
  "description": "Configuration mapping — key → { type, default, enum?, description }",
@@ -350,6 +371,10 @@
350
371
  "enumDescriptions": { "type": "object", "description": "enum value → display name mapping" },
351
372
  "description": { "type": "string" },
352
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
+ "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
+ "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 } },
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." },
353
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)." },
354
379
  "minimum": { "type": "number", "description": "Numeric lower bound — applies when type is number (range of the slider/numeric control)" },
355
380
  "maximum": { "type": "number", "description": "Numeric upper 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.35",
3
+ "version": "0.1.37",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [