@linkdesk/plugin-docs 0.1.39 → 0.1.41
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 +2 -2
- package/docs/21-command-ification-spec.md +89 -1
- package/docs/zh/01-/346/217/222/344/273/266API/345/245/221/347/272/246.md +2 -2
- 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 +56 -5
- package/package.json +1 -1
|
@@ -83,9 +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
|
|
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**" (all registered here; 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). |
|
|
87
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 |
|
|
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)`**
|
|
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)`** — 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). |
|
|
89
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 |
|
|
90
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) |
|
|
91
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>` |
|
|
@@ -67,7 +67,7 @@ useEffect(() => {
|
|
|
67
67
|
|
|
68
68
|
---
|
|
69
69
|
|
|
70
|
-
## 3.
|
|
70
|
+
## 3. Five things every command should get right
|
|
71
71
|
|
|
72
72
|
1. **`id` carries your own prefix**: `<pluginId>.<action>` (e.g. `demo-notes.addNote`).
|
|
73
73
|
Both AI and users list "what can this plugin do" by **prefix** — an id without one gets attributed to somebody else.
|
|
@@ -77,6 +77,26 @@ useEffect(() => {
|
|
|
77
77
|
Callers build `executeCommand(id, ...params)` straight from it and **never have to read your source to guess arguments**.
|
|
78
78
|
4. **State must be readable back.** Once a command changes state, provide a separate read path (a list/query command, or
|
|
79
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
|
+
5. **Read streams back by pulling, with a cursor** (serial receive / logs / progress) — ⛔ never hand the caller a subscription.
|
|
81
|
+
External callers (`linkdeskctl` / MCP) are **request/response**: a `onData(cb)` is something they cannot hold — the callback would have
|
|
82
|
+
to live across process boundaries, nobody reconnects it after a drop, and whatever was missed is silently gone. The right shape is a
|
|
83
|
+
**pull** (example: the `serial-monitor` plugin's `readSince` / `receiveStatus`):
|
|
84
|
+
|
|
85
|
+
- **Signature**: `<plugin>.<area>Since(since, limit, …filters)` — `since` is the **cursor** ("how far I have read"), returning
|
|
86
|
+
`{ items, cursor, lost }`: `cursor` is the seq of the **last item returned**, to be passed back verbatim on the next call;
|
|
87
|
+
`lost` is how many items have already rolled out of your retention buffer. ⚠️ The cursor is a **global position**, not "the Nth
|
|
88
|
+
item" — a filter narrows the **returned items** only, while the cursor still advances; otherwise switching filters would make the
|
|
89
|
+
caller re-read or starve.
|
|
90
|
+
- **Keep a retention buffer — not just the one behind the UI.** The UI chain is usually **drain-on-consume** (thrown away after
|
|
91
|
+
render) and tied to the **view lifetime**, while the caller's first leg often happens with **no view open** ⇒ stand up a
|
|
92
|
+
**module-level** sink (subscribe at entry top level, keep an N-item ring log). ⚠️ Shell events give **each subscriber its own
|
|
93
|
+
channel** (`events.on` registers one `ipcRenderer.on` per subscriber), so your module-level subscription does **not** steal the
|
|
94
|
+
view's events — both chains coexist safely; say so in a comment for whoever reads the code next.
|
|
95
|
+
- **Add a water-level read** (`<plugin>.<area>Status()`: cursor / oldest seq / count / capacity / per-source counts) so the caller can
|
|
96
|
+
tell "not open" from "open but silent" from "you fell behind (`lost > 0`)" before deciding whether to pull.
|
|
97
|
+
- **Receipts, per the house rules**: no new data is not a failure — `{ ok: true, noop: true, reason: "no-new-data" }`; bad arguments,
|
|
98
|
+
or a cursor past the end (e.g. the UI reloaded and seq restarted at 0 while the caller still holds an old cursor) ⇒
|
|
99
|
+
`{ ok: false, noop: true, reason: … }`, handing back a **usable cursor**. ⛔ Never lump every case into "empty array + `ok:true`".
|
|
80
100
|
|
|
81
101
|
---
|
|
82
102
|
|
|
@@ -103,6 +123,11 @@ useEffect(() => {
|
|
|
103
123
|
- [ ] Each has a real handler registered pool-side (`registerCommand`), with `unregisterCommands(pluginId)` on `unmount`
|
|
104
124
|
- [ ] Buttons/menu items and the command handler call **the same** action function (not two implementations)
|
|
105
125
|
- [ ] Anything that changes state also has a **read-back** path (list/query)
|
|
126
|
+
- [ ] The reply **distinguishes three states**: done / not done but not a failure / the call itself is wrong (`reason` is a distinguishable literal)
|
|
127
|
+
- [ ] An **addressed command** (one taking a target id) that cannot find its target **refuses honestly and lists what exists** — ⛔ it never falls back to "the active one / the first one"
|
|
128
|
+
- [ ] A **read command** reports "empty" and "could not read" **separately** (⛔ never report "unknown" as an empty array)
|
|
129
|
+
- [ ] A toggle/flip command's reply carries the **value read back after the change** (`field` / `previous` / `value`)
|
|
130
|
+
- [ ] Streams have a **pull** read-back path (cursor-based — ⛔ not a subscription) plus a water-level read
|
|
106
131
|
- [ ] 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
132
|
- [ ] I walked these actions through **without a mouse** (keyboard / Command Palette) and every step was reachable
|
|
108
133
|
|
|
@@ -122,6 +147,69 @@ useEffect(() => {
|
|
|
122
147
|
|
|
123
148
|
---
|
|
124
149
|
|
|
150
|
+
## 7. Standing discipline (established 2026-09-29)
|
|
151
|
+
|
|
152
|
+
- 🔴 **This is not a one-off delivery**: from here on, **every new feature / new plugin** must satisfy
|
|
153
|
+
"**① every user action has at least one non-mouse path; ② business actions are registered as commands, and the
|
|
154
|
+
registration meta carries `description` + `params`**". The same sentence is hard constraint 26 in the shell repo
|
|
155
|
+
(internal engineering rule, not linked here). Why: **holes grow back with each iteration** — the whole AI-friendliness
|
|
156
|
+
effort started from a hidden gate in an old feature that blocked an AI.
|
|
157
|
+
- **Two mechanical self-checks** (run them, ⛔ do not eyeball it): `npm run audit:plugin-commands`
|
|
158
|
+
(**reports, never blocks** — flags "a view is declared but there are zero commands" and "a whole batch lacks
|
|
159
|
+
`description`") · `npm run manual:build` (byte-for-byte drift gate on the host-command manual index; plugin commands
|
|
160
|
+
**do not** need to enter it — being visible to `getCommands()` at runtime is enough).
|
|
161
|
+
- **Verification is equally pointer-independent**: test commands through commands / APIs (or CLI / MCP), ⛔ never
|
|
162
|
+
"screenshot → guess coordinates → click"; for faces that exist **only under the pointer** (hover buttons), use
|
|
163
|
+
element anchoring ("grab the element, then act on the element itself") — ⛔ do not derive coordinates from window
|
|
164
|
+
position (those coordinates break under a different window layout).
|
|
165
|
+
- ⚠️ **Three pitfalls from real runs** (hit during acceptance on 2026-09-29, written down to save the next person a round):
|
|
166
|
+
1. **Registration timing** — if you only `registerCommand` when the **view component mounts**, an external AI
|
|
167
|
+
**cannot see your commands** in the command list when the view was never opened (invoking one raises `EUNKNOWN`)
|
|
168
|
+
⇒ if you can register at activate time, do not defer it to mount.
|
|
169
|
+
2. **Parameter shape** — `params` are **named**, while the execution face **originally** passed arguments **positionally**
|
|
170
|
+
⇒ a caller following the named-object form **silently did nothing** (`ok=true` with no effect). **Fixed**
|
|
171
|
+
(2026-09-29): the command bridge seam (shared by `exec` and pool-side `executeCommand`) now expands a **single
|
|
172
|
+
named object** in declared `params` order — positional spreading still works; both forms are correct. ⚠️ The
|
|
173
|
+
narrowing: **exactly one object argument** + the command **declares ≥2 `params`** + at least one key **matches**;
|
|
174
|
+
commands with ≤1 `params` are not expanded (that object is legitimately its argument).
|
|
175
|
+
3. **Return value** — when the handler **returns nothing**, an outside caller only sees the envelope's `ok:true`, so
|
|
176
|
+
"**ran but did nothing**" (target missing / precondition unmet / argument missing) and "**actually did it**" look
|
|
177
|
+
**identical** to an AI, which then has to guess via screenshots and retries. **Rule**: if a command does work,
|
|
178
|
+
**return a receipt** — done: `{ ok: true }`; **not done but not a failure**: `{ ok: true, noop: true, reason: "<literal>" }`
|
|
179
|
+
(e.g. `"single-tab"` / `"max-depth"` / target missing); **this call itself is wrong**:
|
|
180
|
+
`{ ok: false, noop: true, reason }` (e.g. missing argument / host not registered). `reason` must be a
|
|
181
|
+
**distinguishable literal**, ⛔ never a catch-all "other". The two built-in split commands already set the example —
|
|
182
|
+
**your handler's return value is the answer the AI reads**.
|
|
183
|
+
|
|
184
|
+
- 🔴 **Failure and addressing shapes** (established 2026-09-29; a standing convention alongside the three
|
|
185
|
+
pitfalls above, with precedents from the host config-write command and the serial plugin's session addressing):
|
|
186
|
+
1. **Read commands, and write commands that an outside caller addresses: bad arguments report in the payload, ⛔ never
|
|
187
|
+
by throwing.** A throw travels through the shell's `runCommand` catch → `reportError` → a **user-visible red toast**,
|
|
188
|
+
and "the caller wrote a bad argument" is something **the user can do nothing about** right then (a slap in the face
|
|
189
|
+
helps nobody). The uniform shape is `{ ok: false, noop: true, reason: "<literal>", error: "<one sentence for humans>" }`
|
|
190
|
+
— `reason` for code to branch on, `error` for humans/AI to read; when reporting "not found", **list what exists**
|
|
191
|
+
(⛔ do not make the caller ask again). ⚠️ **Be honest about the split, do not flatten it**: the older batch of
|
|
192
|
+
commands that "a human can click in a menu / context menu" (arguments filled in by the UI, so a bad argument can
|
|
193
|
+
only be a real bug) **keep throwing**. Both shapes coexisting is **intentional**: ⛔ do not convert old commands to
|
|
194
|
+
payloads, and do not write new ones as throws.
|
|
195
|
+
2. **If you name it, you must know the name**: a command taking a target id (`sessionId` / `tabId` / `key` / `uri` …)
|
|
196
|
+
**must hit when given one** — on a miss return `{ ok: false, noop: true, reason: "bad-…", error }` and list the
|
|
197
|
+
**available** candidates, ⛔ **never silently fall back** to "the active one / the first one": that produces
|
|
198
|
+
"**the books look fine, but a different object was changed**" — exactly the shape this effort keeps eradicating
|
|
199
|
+
(and the hardest to debug when several objects coexist). Only the default (no id given) uses the old
|
|
200
|
+
"active → first" semantics.
|
|
201
|
+
3. **Read commands: empty ≠ failure, and "cannot read" ≠ empty.** An empty read honestly returns
|
|
202
|
+
`{ ok: true, count: 0, … }`; an unreadable one (underlying error / that face not registered) returns
|
|
203
|
+
`{ ok: false, noop: true, reason: "read-failed" }` with the cause. "There is none" and "I do not know" call for
|
|
204
|
+
**opposite** responses (plug a device / change arguments vs. check drivers / permissions); blending them is the
|
|
205
|
+
"answered nothing but looked like an answer" defect — the very shape this effort keeps eradicating.
|
|
206
|
+
4. **Toggle/flip commands return the value read back**: `{ field, previous, value }` (`value` read **after** the change).
|
|
207
|
+
⛔ Do not let the caller infer state from the command title, the schema default, or its own intent — especially since
|
|
208
|
+
**titles change with state** (dynamic titles); using one as a reading is **guaranteed wrong** (that is precisely how
|
|
209
|
+
the external AI misjudged the 0.2.25 retest).
|
|
210
|
+
|
|
211
|
+
---
|
|
212
|
+
|
|
125
213
|
**Related:** [03-contributes-spec](03-contributes-spec.md) §3.1 (every `contributes.commands` field) ·
|
|
126
214
|
[07-plugin-to-plugin-communication](07-plugin-to-plugin-communication.md) (calling another plugin's command) ·
|
|
127
215
|
[14-data-pipeline-command-conventions](14-data-pipeline-command-conventions.md) (naming conventions for data pipeline commands)
|
|
@@ -83,9 +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`
|
|
86
|
+
| **pool(壳×池意图通道)** | 池→壳的**上行意图**只有两条伞形方法(`pool.sidebarAction(action)` / `pool.tabAction(action)`),载荷按 `action` 分派。其中四条是「**拖一下**」的等价通道(四条都在本文档登记在案;①–③ 每条**另有非鼠标命令出口**,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 })` = 侧栏视图拖拽排序落地的同一条路(壳侧重排容器/视图并持久化——**只有池 API 出口、无宿主命令**:池侧代码可用,外部 AI(CLI/MCP)暂不可达)。⚠️ 前三条是**池基础设施**(Zone 分隔线自用),**不是插件该调的联动手段**——插件要动布局请走上面那些命令(`window.linkdesk.commands.executeCommand`),⛔ 别直接发池内部通道(事件名不带插件前缀,且壳侧怎么路由是实现细节)。 |
|
|
87
87
|
| **serial** | **多口路由:** 打开/关闭/动作定向接口的 `portName` **可选**——缺省 = 唯一打开口(0 口抛「串口未打开」;≥2 口抛「多串口已打开,请指定 portName」;**失败可见,不静默**)。三推流通道(`onData`/`onStats`/`onSystem`)载荷**对象化**带 `portName` 路由键(`SerialDataPayload`/`SerialStatsPayload`/`SerialSystemPayload`)——订阅方按**会话口**过滤(key=portName 是通用路由键模式:谁消费谁过滤,壳不代收)。每标签页仍单口,会话-端口绑定在插件侧 |
|
|
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)
|
|
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)`**——悬浮面板几何的**非鼠标路径**:精确设定位置/大小(省略的字段保持现值,`null` = 回默认居中大卡;面板未开 → no-op)。越界值按**与拖拽同一套边界**钳制(`MIN_HEIGHT` / 右侧上限 / 6px 内边距)。读数走 `commands.getCommands()` 侧的 `workbench.action.getFloatingPanelBounds`(返回最近一次落定几何)。 |
|
|
89
89
|
| **hotExit** | 崩溃恢复专用——脏内容落盘 `%APPDATA%/linkdesk/hot-exit/`(主进程路径约定单源,插件零直写);保存/关闭标签页后调 `clear` 删备份 |
|
|
90
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 永不落地) |
|
|
91
91
|
| **appearance** | `revealStorage` 打开外观存储目录(`userData/appearance`)——主进程解析路径并 `shell.openPath` 开资源管理器**内容**(非 `showItemInFolder` 高亮单文件);目录缺省也建(打开即见存储位置,空目录合法),`openPath` 失败抛错 fail-loud。返回 `Promise<void>` |
|
|
@@ -61,10 +61,16 @@ useEffect(() => {
|
|
|
61
61
|
|
|
62
62
|
> ⚠️ **只声明不注册 handler** = 命令面板里有、点了没反应(no-op + 诊断 warn)。
|
|
63
63
|
> 声明面给出的是**元数据**(placeholder),handler 才是真的能跑。
|
|
64
|
+
>
|
|
65
|
+
> ⚠️ **注册在视图 `mount` 里的命令("视图态命令")照样要写进 `contributes.commands`。**
|
|
66
|
+
> 没开过那个视图时,这类命令在壳注册表里**根本不存在** ⇒ 外部 AI 的 `describe` 看不到、`exec` 调不了;
|
|
67
|
+
> **声明面是壳侧唯一的可发现性来源**:壳从清单算出"已声明、尚未注册"那批,单列给 AI
|
|
68
|
+
> (`describe` 的 `commandsPending`,每条带"先开哪个视图"那一步),撞上时 `exec` 的 `EUNKNOWN`
|
|
69
|
+
> 正文也给同一步。⛔ 别指望 AI 自己"先撞一次报错 → 猜要开视图 → 再试"。(2026-09-29 壳侧落地)
|
|
64
70
|
|
|
65
71
|
---
|
|
66
72
|
|
|
67
|
-
##
|
|
73
|
+
## 三、命令要写全的五件事
|
|
68
74
|
|
|
69
75
|
1. **`id` 带自己的前缀**:`<pluginId>.<动作>`(如 `demo-notes.addNote`)。
|
|
70
76
|
AI 与用户都靠**前缀**一次列出"这只插件能做什么"——不带前缀的 id 会被算到别人头上。
|
|
@@ -72,8 +78,27 @@ useEffect(() => {
|
|
|
72
78
|
别写「clearSession 命令」。缺这一句,你的命令在 AI 眼里只剩一个 id。
|
|
73
79
|
3. **`params` 逐位写清**(`name` / `type` / `required` / `description`)。
|
|
74
80
|
调用方照 `params` 拼 `executeCommand(id, ...params)`,**不必读你的源码猜参数**。
|
|
81
|
+
⇒ 也可以给**一个具名对象**(键名照 `name`)——壳侧在命令桥上按声明顺序展开(已落地)。
|
|
75
82
|
4. **状态要能读回来**。命令改了状态之后,另有一条读的路(列表/查询命令,或 `configuration.get()`)——
|
|
76
83
|
"做完验一遍"是自动化与 AI 的基本动作,没有读的路它只能盲目重试。
|
|
84
|
+
5. **流式数据(串口接收 / 日志 / 进度)用「游标式拉取」读回来**——⛔ 别给调用方开订阅。
|
|
85
|
+
外部调用方(`linkdeskctl` / MCP)是**一问一答**的:给它一个 `onData(cb)` 它守不住——回调要跨进程常驻、
|
|
86
|
+
断线没人重连、错过的那段无声丢掉。正确形状是**拉取**(样例:`serial-monitor` 插件的 `readSince` / `receiveStatus`):
|
|
87
|
+
|
|
88
|
+
- **签名**:`<plugin>.<域>Since(since, limit, …过滤)`——`since` = **游标**("我已经读到哪了"),
|
|
89
|
+
回 `{ items, cursor, lost }`:`cursor` = 本次**最后一条**的序号,调用方下一轮**原样回传**;
|
|
90
|
+
`lost` = 因你的保留缓冲滚动而**已经读不到**的条数。⚠️ 游标是**全局面上的位置**、不是"第几条"——
|
|
91
|
+
过滤(按来源 / 标签)只筛**返回项**、游标照旧前进;否则调用方换个过滤条件就会重复读或饿死。
|
|
92
|
+
- **留一份保留式缓冲,别只靠界面那份**:界面那条链多半**消费即清**(渲染完就丢)且**跟视图寿命**,
|
|
93
|
+
而调用方的第一腿常发生在**没有视图在场**的时候 ⇒ 另立一个**模块级** sink(入口顶层订阅,
|
|
94
|
+
保留 N 条环形日志)。⚠️ 壳的事件是**每个订阅者一条独立通道**(`events.on` 逐订阅者挂 `ipcRenderer.on`),
|
|
95
|
+
你的模块级订阅**不会抢走**视图的事件——两条链并存是安全设计,写句注释告诉下一个读代码的人。
|
|
96
|
+
- **再给一条水位读数**(`<plugin>.<域>Status()`:游标 / 最老一条 / 条数 / 容量 / 每来源条数)——
|
|
97
|
+
让调用方能分辨「**没开**」「开了但**没数据**」「**你落后了**(`lost > 0`)」,再决定拉不拉。
|
|
98
|
+
- **回执照房规诚实**:没有新数据 ≠ 失败——`{ ok: true, noop: true, reason: "no-new-data" }`;
|
|
99
|
+
参数错、或游标跑到头(如界面重载后序号从 0 重来、调用方还攥着旧游标)=
|
|
100
|
+
`{ ok: false, noop: true, reason: … }`,并把**可用的游标**一并递回去。
|
|
101
|
+
⛔ 别用「空数组 + `ok:true`」把所有情况糊成一种。
|
|
77
102
|
|
|
78
103
|
---
|
|
79
104
|
|
|
@@ -97,8 +122,14 @@ useEffect(() => {
|
|
|
97
122
|
- [ ] 每一条都写了 `description`(一句人话,写意图——AI 就靠它选命令)
|
|
98
123
|
- [ ] 带参数的都写了 `params`(`name` 照 handler 实参名、`type` 四值、必填标 `required`)
|
|
99
124
|
- [ ] 每一条都在池侧注册了真 handler(`registerCommand`),且 `unmount` 时 `unregisterCommands(pluginId)`
|
|
125
|
+
- [ ] **视图态命令**(在视图 `mount` 里才注册的那些)也写进了 `contributes.commands`——没开视图时 AI 只能从声明面看到它
|
|
100
126
|
- [ ] 按钮/菜单项与命令 handler 调**同一个**动作函数(不是两份实现)
|
|
101
127
|
- [ ] 改了状态的东西,另有**读回来**的路(列表/查询)
|
|
128
|
+
- [ ] 命令回执**三态**分得开:做了 / 没做但不是故障 / 这次调用有问题(`reason` 是可分辨的字面量)
|
|
129
|
+
- [ ] **点名的命令**(带目标 id)找不到目标时**如实拒并列出可用清单**,⛔ 没回退到「活跃/第一个」
|
|
130
|
+
- [ ] **读命令**把「空读数」与「读不出来」分开报(⛔ 不把「不知道」报成空数组)
|
|
131
|
+
- [ ] 翻转/开关类命令的回执带**改完读回来的值**(`field`/`previous`/`value`)
|
|
132
|
+
- [ ] 流式数据的读回路是**游标式拉取**(⛔ 不是订阅)+ 一条水位读数
|
|
102
133
|
- [ ] 自测:装进软件 → 命令面板里搜得到 → 命令清单里看得见 `description`/`params` → 调一次生效**且界面同步变化**
|
|
103
134
|
- [ ] 我在**没有鼠标**的情况下走过一遍这些动作(键盘/命令面板),确认每一步都到得了
|
|
104
135
|
|
|
@@ -116,14 +147,34 @@ useEffect(() => {
|
|
|
116
147
|
|
|
117
148
|
---
|
|
118
149
|
|
|
119
|
-
## 七、常驻纪律(2026-09-29
|
|
150
|
+
## 七、常驻纪律(2026-09-29 立)
|
|
120
151
|
|
|
121
152
|
- 🔴 **这不是一次性交付**:此后**每个新功能 / 新插件**都必须满足「**① 每个用户动作至少一条非鼠标路径;② 业务动作注册为命令,且注册 meta 带 `description` + `params`**」——壳侧的同一句话已进**壳仓库的硬约束 26**(内部工程规范,此处不指向)。理由:**破洞会随迭代重生**(AI 友好化系列的缘起,就是一个老功能里的隐藏门控卡住了 AI)。
|
|
122
153
|
- **机械自查两条**(写完跑一遍,⛔ 别肉眼过):`npm run audit:plugin-commands`(**只报不拦**——报「有视图声明却零命令」与「整批缺 description」)· `npm run manual:build`(宿主命令手册索引的逐字节漂移门禁;插件命令**不需要**进它,运行期 `getCommands()` 查得到即可)。
|
|
123
154
|
- **验收同样与物理指针无关**:测命令走命令 / API(或 CLI / MCP),⛔ 不拿「截图 → 猜坐标点击」当验证手段;**只出现在指针下的面**(悬停按钮那类)用「**先取元素、再落到元素自身**」的元素锚定方式验——⛔ 不按窗口位置推算坐标(推算出来的坐标换个窗口设置就错位)。
|
|
124
|
-
- ⚠️
|
|
125
|
-
1. **注册时机**——在**视图组件挂载时**才 `registerCommand` 的插件,**没开过视图时外部 AI 在命令清单里看不到你的命令**(调了报 `EUNKNOWN`)⇒ 能在 activate 期注册就别拖到 mount
|
|
126
|
-
2. **参数形状**——`params`
|
|
155
|
+
- ⚠️ **三条实录坑**(2026-09-29 会话 13 验收踩到,写在这省后人一轮):
|
|
156
|
+
1. **注册时机**——在**视图组件挂载时**才 `registerCommand` 的插件,**没开过视图时外部 AI 在命令清单里看不到你的命令**(调了报 `EUNKNOWN`)⇒ 能在 activate 期注册就别拖到 mount。
|
|
157
|
+
2. **参数形状**——`params` 是**具名**的,执行面**原先**只按**位置**透传 ⇒ 调用方照「具名对象」调会**静默无效**(`ok=true` 却没做事)。**已修**(2026-09-29):命令桥那条缝(`exec` 与池内 `executeCommand` 共用)现在把**单个具名对象**按 `params` 声明顺序展开——位置平铺照旧可用,两种写法都对。⚠️ 展开的窄口:**恰好 1 个对象实参** + 该命令**声明了 ≥2 个 `params`** + 键名**至少命中一个**;`params` ≤1 的命令不展开(那个对象本就是它的合法实参)。
|
|
158
|
+
3. **返回值**——handler **什么都不回**时,外部只看得到信封的 `ok:true`,于是「**跑了但没做事**」(目标不存在 / 前提不成立 / 参数缺失)与「**真做了**」在 AI 眼里**同形**,只能靠截图与反复试探去猜。**规矩**:命令要做事就**回一张回执**——做成了 `{ ok: true }`;**没做事但不是故障**回 `{ ok: true, noop: true, reason: "<字面量>" }`(例如 `"single-tab"` / `"max-depth"` / 目标不存在);**这次调用本身有问题**回 `{ ok: false, noop: true, reason }`(例如缺参数 / 宿主没注册)。`reason` 必须是**可分辨的字面量**,⛔ 不用「其它」兜底。壳内置的两条分屏命令已按此立样板——**你的 handler 返回值就是 AI 读到的答案**。
|
|
159
|
+
|
|
160
|
+
- 🔴 **失败与寻址的形状**(2026-09-29 立;与上面三条并列的常驻约定,判例来自宿主设置写入命令与串口插件的会话寻址命令):
|
|
161
|
+
1. **读命令、以及「由外部点名」的写命令:坏参出在载荷里,⛔ 不抛异常**。抛出去经壳的 `runCommand` catch →
|
|
162
|
+
`reportError` → 弹一张**用户可见的红色 toast**,而「调用方参数写错」这件事**用户当场什么也做不了**(糊脸无益)。
|
|
163
|
+
统一形状 `{ ok: false, noop: true, reason: "<字面量>", error: "<给人读的一句>" }`——`reason` 给代码分支,
|
|
164
|
+
`error` 给人/给 AI 读懂;报「找不到」时**顺手把现有哪些列出来**(⛔ 别让调用方再来问一次)。
|
|
165
|
+
⚠️ **诚实分档、别一刀切**:老一批「人在菜单/右键里点得到」的命令(实参由界面填,坏参只可能是真 bug)
|
|
166
|
+
**保留抛异常**。两种形状并存是**有意**的:⛔ 别顺手把老命令改成载荷,也别把新命令写成抛异常。
|
|
167
|
+
2. **点名就要认名字**:带目标 id 的命令(`sessionId` / `tabId` / `key` / `uri` …)**给了就必须命中**——
|
|
168
|
+
找不到回 `{ ok: false, noop: true, reason: "bad-…", error }` 并列出**可用清单**,
|
|
169
|
+
⛔ **不静默回退**到「活跃的那个 / 第一个」:那会造出「**账面无错、其实改了别的对象**」——
|
|
170
|
+
本系列反复消灭的就是这个形状(多对象并存时它最难查)。缺省(没给 id)才走「活跃 → 第一个」的老语义。
|
|
171
|
+
3. **读命令:空 ≠ 失败,问不出来 ≠ 空**。空读数如实回 `{ ok: true, count: 0, … }`;
|
|
172
|
+
读不出来(底层报错 / 那个面没注册)回 `{ ok: false, noop: true, reason: "read-failed" }` 并带上原因——
|
|
173
|
+
「没有」与「不知道」的处置**相反**(前者插设备/换参数,后者查驱动/权限),糊成一种就是
|
|
174
|
+
「答不上却看着像答了」——本系列反复消灭的就是这个形状。
|
|
175
|
+
4. **翻转/开关类命令的回执带回读值**:给 `{ field, previous, value }`(`value` 是**改完读回来的**)。
|
|
176
|
+
⛔ 别让调用方从命令标题、schema 默认值或自己的意图反推状态——尤其**标题会随状态变**(动态标题那类),
|
|
177
|
+
把它当读数用**必错**(外部 AI 0.2.25 复测里那条误判就是这么来的)。
|
|
127
178
|
|
|
128
179
|
---
|
|
129
180
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@linkdesk/plugin-docs",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.41",
|
|
4
4
|
"description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"files": [
|