@linkdesk/plugin-docs 0.1.66 → 0.1.67
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.
|
@@ -87,7 +87,7 @@ async function list(): Promise<FileEntry[]> {
|
|
|
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 |
|
|
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) |
|
|
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). **`openExternal(url)` is the controlled external-link face** — it hands a URL to the system's default program (four whitelisted protocols; anything else is refused on the spot); see the "External links" paragraph at the end of this section |
|
|
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>` |
|
|
92
92
|
| **app** | `app.getVersion` = the host software version (`Promise<string>`, read-only) — the only runtime source = Electron `app.getVersion` (a single point in `package.json`, 02 §2.3); **the entry point for comparing the main software version** (consumed by marketplace minAppVersion and the update check). The shell also has a private `getProductInfo` extension (the data source for the about page's 8 fields — not in the contract, so pool plugins can't call it) |
|
|
93
93
|
| **tabs** | **Cross-window resource event wiring:** `updateLabelBySourceId(sourceId, label)` / `closeBySourceId(sourceId)` = **whole-window broadcast semantics** — the resource holder's tab updates/closes in the main window and in every detached window; `sourceId` is the globally unique resource identity (file path/session id), and a change to it is a global fact (the wiring **does not require the caller to be in the same window as the tab** — a detached window's tab updates the moment the sidebar renames or deletes the resource, matching VS Code). `focusBySourceId(sourceId)` = **routed by originating window** (a view action that focuses one specific window, not a global fact). **No new APIs** — it reuses existing surfaces; this behavior contract is guaranteed by the whole-window broadcast |
|
|
@@ -107,6 +107,8 @@ async function list(): Promise<FileEntry[]> {
|
|
|
107
107
|
| `workspace:changed` | `{ rootPath }` | The user opens/switches a folder |
|
|
108
108
|
| `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"`) |
|
|
109
109
|
|
|
110
|
+
**External links (`shell.openExternal`)** — when a plugin wants the user's browser / mail client / some registered-protocol desktop app to open a URL, call `window.linkdesk.shell.openExternal(url)` (returns `Promise<void>`). ⛔ **Don't use `window.open`**: inside the pool, `window.open` is denied across the board by the shell — whitelisted protocols are handed to the system, everything else never creates a window, and a bare Electron window is never produced. **Only four protocols can be opened**: `http:`, `https:`, `mailto:`, `vscode:` (`vscode:` is the sample of a "constant-registered protocol" — VS Code writes that protocol into the registry at install time, and the host merely **hands it over**; it does not know whether the other side is installed, and when it isn't, Windows itself offers "How do you want to open this?"). **Anything else is refused** — `file:` (pointing external input at an arbitrary local path) and `javascript:` / `data:` (executing external input as a script) are explicitly refused; a refusal means this Promise **rejects** (it is not silent), so callers should catch it and tell the user something. To read or write local files, use `workspace` / `filesystem` — ⛔ don't route around through the OS shell. The complete whitelist lives in [16-naming-conventions](16-naming-conventions.md) §7, row "Allowed external protocols (openExternal)" — adding a protocol is a **public-surface decision** (change the host constant and regenerate the ledger); it is not something a plugin can open up by itself.
|
|
111
|
+
|
|
110
112
|
### 3.3 Read Surfaces — the machine-readable outlet for "what is open / what is waiting"
|
|
111
113
|
|
|
112
114
|
§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**).
|
|
@@ -99,6 +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
|
+
| Allowed external protocols (openExternal) | `http`、`https`、`mailto`、`vscode` | The plugin-facing `shell.openExternal(url)` admits only these four protocols the host **recognizes** (`vscode:` is the sample of a constant-registered protocol; a third-party editor works the same way — add a line if you need it). A protocol outside the table means your request is **refused on the spot** (the Promise rejects; it is not silent) — adding one is a public-surface decision (change the shell constant and regenerate the ledger). ⚠️ `file:` / `javascript:` / `data:` are **explicitly refused**; don't try them |
|
|
102
103
|
| Host pseudo plugin id | `app`、`appearance`、`ai-bridge`、`file-associations` | The host registers as a "plugin" too (shell core / appearance / AI integration / default-open-with 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
104
|
| 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
105
|
| Host config key | `app.theme`、`app.themeColor`、`app.themeColorMode`、`app.iconTheme` | Theme and colours — taking it overwrites the theme the user is currently using |
|
|
@@ -87,7 +87,7 @@ async function list(): Promise<FileEntry[]> {
|
|
|
87
87
|
| **serial** | **多口路由:** 打开/关闭/动作定向接口的 `portName` **可选**——缺省 = 唯一打开口(0 口抛「串口未打开」;≥2 口抛「多串口已打开,请指定 portName」;**失败可见,不静默**)。三推流通道(`onData`/`onStats`/`onSystem`)载荷**对象化**带 `portName` 路由键(`SerialDataPayload`/`SerialStatsPayload`/`SerialSystemPayload`)——订阅方按**会话口**过滤(key=portName 是通用路由键模式:谁消费谁过滤,壳不代收)。每标签页仍单口,会话-端口绑定在插件侧 |
|
|
88
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
|
-
| **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
|
|
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 永不落地)。**`openExternal(url)` 受控外链**——把 URL 交系统默认程序打开(白名单四条协议,表外当场拒),详见本节末尾「外部链接」段 |
|
|
91
91
|
| **appearance** | `revealStorage` 打开外观存储目录(`userData/appearance`)——主进程解析路径并 `shell.openPath` 开资源管理器**内容**(非 `showItemInFolder` 高亮单文件);目录缺省也建(打开即见存储位置,空目录合法),`openPath` 失败抛错 fail-loud。返回 `Promise<void>` |
|
|
92
92
|
| **app** | `app.getVersion` = 宿主软件版本号(`Promise<string>`,只读)——唯一运行时来源 = Electron `app.getVersion`(`package.json` 单点,02 §2.3);**主软件版本比对入口**(市场 minAppVersion 与更新检查都消费它)。壳内另有 `getProductInfo` 私有扩展(关于页 8 字段数据源,不在契约——池插件不可调) |
|
|
93
93
|
| **tabs** | **跨窗资源事件联动:** `updateLabelBySourceId(sourceId, label)` / `closeBySourceId(sourceId)` = **全窗广播语义**——资源持有者在主窗与全部脱出窗的标签页同步更新/关闭;`sourceId` 为全局唯一资源身份(文件路径/会话 id),变更即全局事实(联动**不依赖调用方与标签页同窗**——脱出窗标签随侧栏改名/删除即时联动,对标 VS Code)。`focusBySourceId(sourceId)` = **按来源窗路由**(视图动作,聚焦到具体某窗,非全局事实)。**无新 API**——复用既有面,此行为契约由全窗广播保证 |
|
|
@@ -107,6 +107,8 @@ async function list(): Promise<FileEntry[]> {
|
|
|
107
107
|
| `workspace:changed` | `{ rootPath }` | 用户打开/切换文件夹 |
|
|
108
108
|
| `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"`)里面 |
|
|
109
109
|
|
|
110
|
+
**外部链接(`shell.openExternal`)**——插件要让用户的浏览器 / 邮件客户端 / 某个已注册协议的桌面程序打开一个 URL 时,用 `window.linkdesk.shell.openExternal(url)`(返回 `Promise<void>`)。⛔ **别用 `window.open`**:池里的 `window.open` 被壳统一 deny——白名单协议转交系统、其余一律不出窗,绝不落裸 Electron 窗。**能开的协议只有四条**:`http:`、`https:`、`mailto:`、`vscode:`(`vscode:` 是「常量登记的已注册协议」样例——VS Code 安装时把该协议写进注册表,宿主只负责**转交**,**不感知**对方装没装;没装时由 Windows 自己弹「如何打开」)。**其余一律被拒**——`file:`(把外部输入指向本地任意路径)、`javascript:` / `data:`(把外部输入当脚本执行)是明确拒绝的形态;被拒 = 这个 Promise **reject**(不静默),调用方该接住并给用户一个说法。要读写本地文件走 `workspace` / `filesystem`,⛔ 别借 OS 壳绕一圈。完整白名单见 [16-命名规范](16-命名规范.md) §七 的「受控 openExternal 协议白名单」行——要新增一条协议 = 一次**公共面决策**(改宿主常量并重跑账),不是插件自己开得动的。
|
|
111
|
+
|
|
110
112
|
### 3.3 读取面——「现在有什么 / 在等什么」的机器出口
|
|
111
113
|
|
|
112
114
|
§3.1/§3.2 讲的是**操作面**(插件能做什么);本节讲**读取面**(插件/AI 能**读到**什么)。
|
|
@@ -101,6 +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
|
+
| 受控 openExternal 协议白名单 | `http`、`https`、`mailto`、`vscode` | 插件面 `shell.openExternal(url)` 只放行这四条**宿主承认**的协议(`vscode:` = 常量登记的已注册协议样例,第三方编辑器同理,要开就加一行)。表外的协议,你的请求会被**当场拒**(Promise reject,不静默)——要加一条 = 一次公共面决策(改壳常量 + 重跑账)。⚠️ `file:` / `javascript:` / `data:` 是**明确拒绝**的形态,别试 |
|
|
104
105
|
| 宿主伪 pluginId | `app`、`appearance`、`ai-bridge`、`file-associations` | 宿主自己也以「插件」身份注册(壳通用 / 外观 / AI 接入 / 默认打开方式分区;原「更新」组 2026-09-26 并入「通用」,`update` 已退役登记)⇒ 用这些 id 会被当成宿主自己;其名下配置键(`ai.*`)同样受保护区管辖 |
|
|
105
106
|
| 宿主配置键 | `app.schemaVersion` | 配置的**内部版本标志**(设置界面里看不到、也没有注册过)——占它会让迁移记账错乱,用户数据看着丢 |
|
|
106
107
|
| 宿主配置键 | `app.theme`、`app.themeColor`、`app.themeColorMode`、`app.iconTheme` | 主题与配色——占它 = 直接顶掉用户当前选的主题 |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@linkdesk/plugin-docs",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.67",
|
|
4
4
|
"description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"files": [
|