@linkdesk/plugin-docs 0.1.41 → 0.1.43
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 +1 -1
- package/docs/03-contributes-spec.md +8 -0
- package/docs/16-naming-conventions.md +25 -0
- package/docs/zh/03-/346/217/222/344/273/266contributes/350/247/204/350/214/203.md +6 -0
- package/docs/zh/16-/345/221/275/345/220/215/350/247/204/350/214/203.md +20 -0
- package/package.json +1 -1
|
@@ -83,7 +83,7 @@ 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.
|
|
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. Four of those are the equivalent of "**just drag it**" (all four registered in this document; ①–③ each also 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`; ④ `sidebarAction({ action: "reorder", containerId, viewId, newIndex })` — the same path a sidebar-view drag-reorder commits through (the shell reorders containers/views and persists it — **pool API outlet only, no host command**: usable from pool-side code, not yet reachable by an external AI (CLI/MCP)). ⚠️ The first 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
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 |
|
|
@@ -157,6 +157,14 @@ useEffect(() => {
|
|
|
157
157
|
| `settingItemGear` | the gear on a setting row (on row hover in the Settings Editor) |
|
|
158
158
|
| `viewTitleContext` | right-click on a sidebar view title (collapse/reset position/views in the same group) |
|
|
159
159
|
|
|
160
|
+
> 🔴 **The second column above is the slot id's *value*—copy the lowerCamelCase spelling.** ⛔ Never write the
|
|
161
|
+
> **member name** of the host constants table (`MenuBar` / `FileContext` and friends): the host registry has no such
|
|
162
|
+
> key, so those menu items **never appear**, silently, on both paths (this declarative table and imperative
|
|
163
|
+
> `menu.registerItems`). The SDK gate `linkdesk/no-menu-slot-case` catches this class (criterion: differs from a
|
|
164
|
+
> host value **by letter case only** ⇒ red; `@linkdesk/plugin-sdk` 0.1.56 onward). This is not hypothetical: the
|
|
165
|
+
> official file-tree plugin once wrote the member names `MenuBar` / `FileContext` where slot values belong, and its
|
|
166
|
+
> entire "File" menu **vanished for over two months** with no error reported anywhere.
|
|
167
|
+
|
|
160
168
|
**Menu item fields:**
|
|
161
169
|
|
|
162
170
|
| Field | Required | Description |
|
|
@@ -194,6 +194,31 @@ watching it for you).
|
|
|
194
194
|
- **Host definition set unreadable** ⇒ the leg reports "**unverified**" instead of "0 issues"—that means a broken
|
|
195
195
|
install; reinstall `@linkdesk/plugin-sdk`.
|
|
196
196
|
|
|
197
|
+
### 7.7 A menu slot's name is its **value**, not its member name (from `@linkdesk/plugin-sdk` 0.1.56)
|
|
198
|
+
|
|
199
|
+
Every menu slot id the host recognizes is **lowerCamelCase**: `menuBar` / `fileContext` / `cardContext` /
|
|
200
|
+
`panelViewContext`… When you read host source you will also see a different spelling—`MENU_SLOTS.MenuBar`,
|
|
201
|
+
`MENU_SLOTS.FileContext`—those are the **member names** of a constants table, **not** the slot values. Writing a
|
|
202
|
+
member name where a slot id belongs (`registerItems("MenuBar", …)`, `contributes.menus: { "FileContext": … }`,
|
|
203
|
+
`<ContextMenu menuId={"FileContext"} />`) **produces no error at all**: the host registry has no such key, so those
|
|
204
|
+
menu items **never appear**—silently, on both the declarative and the imperative path.
|
|
205
|
+
|
|
206
|
+
> Not hypothetical: file-tree lost its whole "File" menu this way for over two months, with no gate ever reporting
|
|
207
|
+
> it (no such criterion existed at the time).
|
|
208
|
+
|
|
209
|
+
- **The criterion (one rule, zero false positives)**: a slot id that differs from a host slot **value only by
|
|
210
|
+
letter case** ⇒ red. ⛔ "Unknown id" is **not** judged—`MenuId` is an open string and inventing your own
|
|
211
|
+
registration point is legal; what can be condemned is the case-only variant, which has no legitimate use.
|
|
212
|
+
- **The fix**: use the lowerCamelCase value (`MenuBar` → `menuBar`, `FileContext` → `fileContext`)—and change
|
|
213
|
+
**both sides in the same commit**, since the registering side and the consuming side (`ContextMenu`'s `menuId`)
|
|
214
|
+
must agree.
|
|
215
|
+
- **The host list ships with the package**: `schemas/host-menu-slots.json` (`entries: [{ key, value }]`—`key` is
|
|
216
|
+
the member name, `value` is what you must write). Leg id = `linkdesk/no-menu-slot-case`.
|
|
217
|
+
- **List unreadable** ⇒ the leg reports "**unverified**" and red (⛔ never counts as 0 issues); reinstall
|
|
218
|
+
`@linkdesk/plugin-sdk`.
|
|
219
|
+
- **Informed bypass**: `// eslint-disable-next-line linkdesk/no-menu-slot-case -- reason`—though a legitimate
|
|
220
|
+
deviation for this criterion essentially does not exist, so do not read it as permission.
|
|
221
|
+
|
|
197
222
|
---
|
|
198
223
|
|
|
199
224
|
> **← Index:** [00-readme](00-readme.md) · **Related:** [15-multi-repo-and-local-workspace](15-multi-repo-and-local-workspace.md) · [06-plugin-json-spec](06-plugin-json-spec.md) · [plugin-source-externalization/09-naming-conventions.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md) (decision rationale)
|
|
@@ -157,6 +157,12 @@ useEffect(() => {
|
|
|
157
157
|
| `settingItemGear` | 设置项齿轮(Settings Editor 行 hover) |
|
|
158
158
|
| `viewTitleContext` | 侧栏视图 title 右键(折叠/重置位置/视图同组) |
|
|
159
159
|
|
|
160
|
+
> 🔴 **上表第二列是槽位 id 的「值」,照抄小驼峰**——⛔ 别写宿主常量表的**成员名**(`MenuBar` / `FileContext`
|
|
161
|
+
> 那一套):成员名在宿主注册表里查不到,你那批菜单项会**静默不出现**,两条注册路径(本表声明式 +
|
|
162
|
+
> `menu.registerItems` 命令式)都不报错。SDK 门禁 `linkdesk/no-menu-slot-case` 判这一类(判据:与宿主值
|
|
163
|
+
> **仅差大小写** ⇒ 红;`@linkdesk/plugin-sdk` 0.1.56 起)。这不是假想的事故:官方 file-tree 插件曾把
|
|
164
|
+
> `MenuBar` / `FileContext` 这两个成员名当槽位值写下,整个「文件」菜单**消失两个多月**而没有任何报错。
|
|
165
|
+
|
|
160
166
|
**菜单项字段:**
|
|
161
167
|
|
|
162
168
|
| 字段 | 必需 | 说明 |
|
|
@@ -192,6 +192,26 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
|
|
|
192
192
|
- **知情绕行**:`// eslint-disable-next-line linkdesk/no-reserved-class-name -- 理由`(与命名空间腿同一 id)。
|
|
193
193
|
- **宿主定义集读不到** ⇒ 判据报「**未核验**」而不是「0 处通过」——那是包不完整,重装 `@linkdesk/plugin-sdk`。
|
|
194
194
|
|
|
195
|
+
### 7.7 菜单槽位的名字是**值**,不是成员名(`@linkdesk/plugin-sdk` 0.1.56 起)
|
|
196
|
+
|
|
197
|
+
宿主认的菜单槽位 id 一律**小驼峰**:`menuBar` / `fileContext` / `cardContext` / `panelViewContext`…
|
|
198
|
+
而你读宿主源码时会看到另一套写法——`MENU_SLOTS.MenuBar`、`MENU_SLOTS.FileContext`——那是**常量表的成员名**,
|
|
199
|
+
**不是**槽位值。把成员名当槽位写下去(`registerItems("MenuBar", …)`、`contributes.menus: { "FileContext": … }`、
|
|
200
|
+
`<ContextMenu menuId={"FileContext"} />`)**不会报任何错**:宿主注册表里查不到这个键 ⇒ 你那些菜单项
|
|
201
|
+
**永远不出现**,声明式与命令式两条路径都一样静默。
|
|
202
|
+
|
|
203
|
+
> 这不是假想:file-tree 曾因此丢了整个「文件」菜单两个多月,期间没有一道门禁报过(因为当时判据不存在)。
|
|
204
|
+
|
|
205
|
+
- **判据(一条,零假红)**:槽位 id 与宿主某个槽位**值仅大小写不同** ⇒ 红。⛔ 「未知 id」**不判**——
|
|
206
|
+
`MenuId` 是开放字符串,你自造注册点合法;能判死的是「只差大小写」这一种,它没有任何正当用途。
|
|
207
|
+
- **修法**:换成小驼峰值(`MenuBar` → `menuBar`、`FileContext` → `fileContext`);**读写同笔**——
|
|
208
|
+
注册侧与消费侧(`ContextMenu` 的 `menuId`)必须用同一个值。
|
|
209
|
+
- **宿主名单随包下发**:`schemas/host-menu-slots.json`(`entries: [{ key, value }]`,`key` 是成员名、
|
|
210
|
+
`value` 是你要写的值)。腿 id = `linkdesk/no-menu-slot-case`。
|
|
211
|
+
- **名单读不到** ⇒ 报「**未核验**」并红(⛔ 不当成 0 处通过);重装 `@linkdesk/plugin-sdk`。
|
|
212
|
+
- **知情绕行**:`// eslint-disable-next-line linkdesk/no-menu-slot-case -- 理由`——但这个判据的合法偏离形态
|
|
213
|
+
基本不存在,别把它当许可。
|
|
214
|
+
|
|
195
215
|
---
|
|
196
216
|
|
|
197
217
|
> **← 索引:** [00-README](00-README.md) · **相关:** [15-多仓开发与本地工作区](15-多仓开发与本地工作区.md) · [06-plugin.json规范](06-plugin.json规范.md) · [插件源码外移层/09-命名规范.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/插件源码外移层/09-命名规范.md)(决策论证)
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@linkdesk/plugin-docs",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.43",
|
|
4
4
|
"description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"files": [
|