@linkdesk/plugin-docs 0.1.35 → 0.1.36
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/01-plugin-api-contract.md +38 -3
- package/docs/03-contributes-spec.md +19 -1
- package/docs/16-naming-conventions.md +1 -1
- package/docs/zh/01-/346/217/222/344/273/266API/345/245/221/347/272/246.md +38 -3
- package/docs/zh/03-/346/217/222/344/273/266contributes/350/247/204/350/214/203.md +20 -2
- package/docs/zh/16-/345/221/275/345/220/215/350/247/204/350/214/203.md +1 -1
- package/docs/zh/plugin.schema.json +20 -1
- package/package.json +1 -1
|
@@ -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
|
|
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/` (
|
|
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
|
|
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
|
|
|
@@ -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 |
|
|
@@ -29,11 +29,13 @@
|
|
|
29
29
|
|
|
30
30
|
| 事实 | 说明 |
|
|
31
31
|
|------|------|
|
|
32
|
-
| **契约
|
|
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/`(
|
|
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
|
-
|
|
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 时)
|
|
@@ -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` | 宿主自己也以「插件」身份注册(壳通用 /
|
|
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` | 亮暗模式、强调色、菜单样式、悬停提示 |
|
|
@@ -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
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@linkdesk/plugin-docs",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.36",
|
|
4
4
|
"description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"files": [
|