@linkdesk/plugin-docs 0.1.39 → 0.1.40

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.
@@ -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 as of M2 `AI#21`; each has a **non-mouse command counterpart**, so an AI/script never has to drag): ① `sidebarAction({ action: "setSidebarWidth", width })` — the same path the main-sidebar divider drag commits through (shell `useSubscriptions` → `LayoutEngine.resizeZone`, clamped by the dock declaration, 170–600) → commands `workbench.action.setSidebarWidth(width)` / `…resetSidebarWidth` (back to the 280 default); ② `tabAction({ action: "updateSplitSizes", branchIndex, sizes })` — where a split divider drag commits (shell `useTabManager.updateSplitSizes` → the SplitNode tree) → command `workbench.action.resetSplitSizes` (**every** branch back to 50/50); ③ the event `events.emit("panel:resize", { height })` — where dragging the bottom panel's top handle commits (the shell consumer routes **axis-aware**: for a panel with `edge ∈ {left,right}` it uses the width axis `resizeZone`, for `top/bottom` the height axis `resizeZoneHeight`) → commands `workbench.action.setPanelSize(size)` / `…resetPanelSize`. ⚠️ These three are **pool infrastructure** (used by the Zone dividers themselves), **not** a linkage mechanism plugins should call — to change the layout, use the commands above (`window.linkdesk.commands.executeCommand`) and ⛔ do not emit the pool-internal channels directly (the event names carry no plugin prefix, and how the shell routes them is an implementation detail). |
86
+ | **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)`** (M2 `AI#20`) — the **non-mouse path** for floating-panel geometry: set position/size precisely (omitted fields keep their current value, `null` resets to the default centered card; no-op when no panel is open). Out-of-range values are clamped by **the same bounds as dragging** (`MIN_HEIGHT` / right-edge limit / 6 px inset). Read back via the command `workbench.action.getFloatingPanelBounds` (returns the last settled geometry). |
88
+ | **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. Four things every command should get right
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,7 @@ 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
+ - [ ] Streams have a **pull** read-back path (cursor-based — ⛔ not a subscription) plus a water-level read
106
127
  - [ ] 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
128
  - [ ] I walked these actions through **without a mouse** (keyboard / Command Palette) and every step was reachable
108
129
 
@@ -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` 分派。其中四条是「**拖一下**」的等价通道(M2 `AI#21`/`AI#50` 起在本文档登记;①–③ 每条**另有非鼠标命令出口**,AI/脚本不必真拖):① `sidebarAction({ action: "setSidebarWidth", width })` = 主侧栏分隔线拖拽落地的同一条路(壳 `useSubscriptions` → `LayoutEngine.resizeZone`,钳制随 dock 声明 170–600)→ 命令 `workbench.action.setSidebarWidth(width)` / `…resetSidebarWidth`(回默认 280);② `tabAction({ action: "updateSplitSizes", branchIndex, sizes })` = 分屏分隔线拖拽落地(壳 `useTabManager.updateSplitSizes` → SplitNode 树)→ 命令 `workbench.action.resetSplitSizes`(**所有**分支回 50/50);③ 事件 `events.emit("panel:resize", { height })` = 底部面板顶部手柄拖高落地(壳消费处**轴感知**路由:面板 `edge ∈ {left,right}` 走宽轴 `resizeZone`,`top/bottom` 走高轴 `resizeZoneHeight`)→ 命令 `workbench.action.setPanelSize(size)` / `…resetPanelSize`;④ `sidebarAction({ action: "reorder", containerId, viewId, newIndex })` = 侧栏视图拖拽排序落地的同一条路(壳侧重排容器/视图并持久化;M2 `AI#50` 起在本文档登记——**只有池 API 出口、无宿主命令**:池侧代码可用,外部 AI(CLI/MCP)暂不可达)。⚠️ 前三条是**池基础设施**(Zone 分隔线自用),**不是插件该调的联动手段**——插件要动布局请走上面那些命令(`window.linkdesk.commands.executeCommand`),⛔ 别直接发池内部通道(事件名不带插件前缀,且壳侧怎么路由是实现细节)。 |
86
+ | **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)`**(M2 `AI#20`)——悬浮面板几何的**非鼠标路径**:精确设定位置/大小(省略的字段保持现值,`null` = 回默认居中大卡;面板未开 → no-op)。越界值按**与拖拽同一套边界**钳制(`MIN_HEIGHT` / 右侧上限 / 6px 内边距)。读数走 `commands.getCommands()` 侧的 `workbench.action.getFloatingPanelBounds`(返回最近一次落定几何)。 |
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,10 @@ 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
+ - [ ] 流式数据的读回路是**游标式拉取**(⛔ 不是订阅)+ 一条水位读数
102
129
  - [ ] 自测:装进软件 → 命令面板里搜得到 → 命令清单里看得见 `description`/`params` → 调一次生效**且界面同步变化**
103
130
  - [ ] 我在**没有鼠标**的情况下走过一遍这些动作(键盘/命令面板),确认每一步都到得了
104
131
 
@@ -116,14 +143,15 @@ useEffect(() => {
116
143
 
117
144
  ---
118
145
 
119
- ## 七、常驻纪律(2026-09-29 立 · `AI#49`)
146
+ ## 七、常驻纪律(2026-09-29 立)
120
147
 
121
148
  - 🔴 **这不是一次性交付**:此后**每个新功能 / 新插件**都必须满足「**① 每个用户动作至少一条非鼠标路径;② 业务动作注册为命令,且注册 meta 带 `description` + `params`**」——壳侧的同一句话已进**壳仓库的硬约束 26**(内部工程规范,此处不指向)。理由:**破洞会随迭代重生**(AI 友好化系列的缘起,就是一个老功能里的隐藏门控卡住了 AI)。
122
149
  - **机械自查两条**(写完跑一遍,⛔ 别肉眼过):`npm run audit:plugin-commands`(**只报不拦**——报「有视图声明却零命令」与「整批缺 description」)· `npm run manual:build`(宿主命令手册索引的逐字节漂移门禁;插件命令**不需要**进它,运行期 `getCommands()` 查得到即可)。
123
150
  - **验收同样与物理指针无关**:测命令走命令 / API(或 CLI / MCP),⛔ 不拿「截图 → 猜坐标点击」当验证手段;**只出现在指针下的面**(悬停按钮那类)用「**先取元素、再落到元素自身**」的元素锚定方式验——⛔ 不按窗口位置推算坐标(推算出来的坐标换个窗口设置就错位)。
124
- - ⚠️ **两条实录坑**(2026-09-29 会话 13 验收踩到,写在这省后人一轮):
125
- 1. **注册时机**——在**视图组件挂载时**才 `registerCommand` 的插件,**没开过视图时外部 AI 在命令清单里看不到你的命令**(调了报 `EUNKNOWN`)⇒ 能在 activate 期注册就别拖到 mount(账 = 生长格 `AI#54`)。
126
- 2. **参数形状**——`params` 是**具名**的,执行面却按**位置**透传 ⇒ 调用方照「具名对象」调会**静默无效**(`ok=true` 却没做事);今天的正解 = 调用方按 `params` **顺序平铺**传参,壳侧兼容在账(生长格 `AI#52`)。
151
+ - ⚠️ **三条实录坑**(2026-09-29 会话 13 验收踩到,写在这省后人一轮):
152
+ 1. **注册时机**——在**视图组件挂载时**才 `registerCommand` 的插件,**没开过视图时外部 AI 在命令清单里看不到你的命令**(调了报 `EUNKNOWN`)⇒ 能在 activate 期注册就别拖到 mount。
153
+ 2. **参数形状**——`params` 是**具名**的,执行面**原先**只按**位置**透传 ⇒ 调用方照「具名对象」调会**静默无效**(`ok=true` 却没做事)。**已修**(2026-09-29):命令桥那条缝(`exec` 与池内 `executeCommand` 共用)现在把**单个具名对象**按 `params` 声明顺序展开——位置平铺照旧可用,两种写法都对。⚠️ 展开的窄口:**恰好 1 个对象实参** + 该命令**声明了 ≥2 个 `params`** + 键名**至少命中一个**;`params` ≤1 的命令不展开(那个对象本就是它的合法实参)。
154
+ 3. **返回值**——handler **什么都不回**时,外部只看得到信封的 `ok:true`,于是「**跑了但没做事**」(目标不存在 / 前提不成立 / 参数缺失)与「**真做了**」在 AI 眼里**同形**,只能靠截图与反复试探去猜。**规矩**:命令要做事就**回一张回执**——做成了 `{ ok: true }`;**没做事但不是故障**回 `{ ok: true, noop: true, reason: "<字面量>" }`(例如 `"single-tab"` / `"max-depth"` / 目标不存在);**这次调用本身有问题**回 `{ ok: false, noop: true, reason }`(例如缺参数 / 宿主没注册)。`reason` 必须是**可分辨的字面量**,⛔ 不用「其它」兜底。壳内置的两条分屏命令已按此立样板——**你的 handler 返回值就是 AI 读到的答案**。
127
155
 
128
156
  ---
129
157
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.39",
3
+ "version": "0.1.40",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [