@linkdesk/plugin-docs 0.1.47 → 0.1.48
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/06-plugin-json-spec.md +2 -0
- package/docs/10-building-a-settings-plugin.md +1 -1
- package/docs/11-authoring-themes.md +1 -0
- package/docs/16-naming-conventions.md +1 -1
- package/docs/zh/06-plugin.json/350/247/204/350/214/203.md +2 -0
- package/docs/zh/10-/345/246/202/344/275/225/351/200/240/344/270/200/344/270/252/350/256/276/347/275/256/346/217/222/344/273/266.md +1 -1
- package/docs/zh/11-/344/270/273/351/242/230/345/210/266/344/275/234.md +1 -0
- package/docs/zh/16-/345/221/275/345/220/215/350/247/204/350/214/203.md +1 -1
- package/package.json +1 -1
|
@@ -419,6 +419,8 @@ do not need it (`icon` *is* the identity image).
|
|
|
419
419
|
|
|
420
420
|
> **opt-IN — without declaring `appearsIn.iconBar` there is no icon of yours in the icon bar.** The old `iconLocation` default of `"top"` (opt-OUT — the editor got squeezed into the icon bar even without declaring anything) has been deprecated; it is now controlled declaratively by `appearsIn.iconBar` (`"top"` = the upper icon group, `"bottom"` = the fixed bottom group).
|
|
421
421
|
|
|
422
|
+
> 🔴 **`"bottom"` is a geometric position, not "the gear"** (corrected 2026-09-30): the bottom-left gear is a **shell-owned button** (the icon-bar layout's `owned` field) and has nothing to do with any plugin's declaration. Declaring `"bottom"` merely puts your icon in that bottom group, and clicking it **opens your own tab as usual** — the old "clicking a bottom icon opens the gear menu" behaviour has been removed (background: `docs/04-软件更新/待抉择池/齿轮归属与底部图标位/`).
|
|
423
|
+
|
|
422
424
|
**Two paths to an icon:**
|
|
423
425
|
|
|
424
426
|
| Path | Prerequisite | Description |
|
|
@@ -25,7 +25,7 @@ Follow the official settings plugin (= the `plugin.json` in **the settings plugi
|
|
|
25
25
|
// omit core — uninstallable; core: true means the UI has no uninstall button (an anti-mistake-deletion flag, not a category)
|
|
26
26
|
"factoryRole": "settings", // ① the key — declares you are a member of the "settings set" family
|
|
27
27
|
"entry": "src/index.tsx", // tab entry (appearsIn.tabBar requires entry)
|
|
28
|
-
"appearsIn": { "
|
|
28
|
+
"appearsIn": { "tabBar": true }, // ⛔ don't declare iconBar — the bottom-left gear belongs to the shell (bottom is a position, not the gear)
|
|
29
29
|
"tabBehavior": { "singleton": true }, // singleton — switching won't open a duplicate if it's already open
|
|
30
30
|
"contributes": {
|
|
31
31
|
"viewsContainers": {
|
|
@@ -152,6 +152,7 @@ theme-liquid-glass/
|
|
|
152
152
|
- Applying: `setRecipe`/`setColorway`, or writing the `app.theme` configuration directly.
|
|
153
153
|
- Events: `theme:changed` (the payload carries tokens) for live reactions.
|
|
154
154
|
- Mix-and-match: your theme automatically shows up among the mix-and-match sources in the settings page according to the domains it contributes (`RecipeMeta.domains`), with **zero extra work for the author**.
|
|
155
|
+
- Provenance: the theme card and the command palette mark **who provides** each recipe (shell built-in fallback = "Shell built-in", plugin-contributed = the plugin name) — that line is driven by `RecipeMeta.source`, and the plugin name comes from `plugin.json`'s `name`, with **zero extra work for the author**.
|
|
155
156
|
|
|
156
157
|
## 5. Migration (existing theme plugins — decision F: zero backward compatibility)
|
|
157
158
|
|
|
@@ -115,7 +115,7 @@ The table below is **reconciled name by name** against it (gate `scripts/check-r
|
|
|
115
115
|
| Host colorway id | `dark-fallback`、`light` | Fallback values of `app.themeColor` and of the colorway source space |
|
|
116
116
|
| Host icon theme id | `default` | The fallback value of `app.iconTheme` |
|
|
117
117
|
| Host appearance sentinel | `followTheme` | The "follow the theme" sentinel of a mix source — **it is not an id**, so don't try to shadow it with a plugin id |
|
|
118
|
-
| Host-only context key (plugins **must not** set) | `activeEditor`、`editorCount`、`editorHasSelection`、`inputFocus`、`sidebarPosition`、`updateActionable`、`updateButtonLabel` | Set one of these at runtime over IPC and the host logs a `console.error` **naming you** (the value is still written: these are state, not registrations, so the runtime cannot tell who came first) |
|
|
118
|
+
| Host-only context key (plugins **must not** set) | `activeEditor`、`editorCount`、`editorHasSelection`、`inputFocus`、`settingsSlotFilled`、`sidebarPosition`、`updateActionable`、`updateButtonLabel` | Set one of these at runtime over IPC and the host logs a `console.error` **naming you** (the value is still written: these are state, not registrations, so the runtime cannot tell who came first) |
|
|
119
119
|
| Shared-contract context key (plugins **may** set) | `settingKey`、`settingFollowTheme`、`settingModified`、`settingResetsToDefault` | These four are a **public contract**: the official `settings` plugin writes them, host commands read them in `when` clauses — use them as specified, don't change their meaning |
|
|
120
120
|
|
|
121
121
|
**How to check yourself** (from your own repo): once `@linkdesk/plugin-sdk` is installed, your repo's `verify` runs four ownership legs (command ids / config keys / appearance ids / context keys); whichever one you violate is reported with its location plus the suggested fix, **"should start with `<pluginId>.`"**.
|
|
@@ -416,6 +416,8 @@ my-plugin/
|
|
|
416
416
|
|
|
417
417
|
> **opt-IN——不声明 `appearsIn.iconBar` = 图标栏没有你的图标。** 曾经的 `iconLocation` 默认 `"top"`(opt-OUT——编辑器没声明也挤进图标栏)已被废弃,现在由 `appearsIn.iconBar` 声明式控制(`"top"` = 上部图标组,`"bottom"` = 底部固定组)。
|
|
418
418
|
|
|
419
|
+
> 🔴 **`"bottom"` 只是几何位置,不是「齿轮」**(2026-09-30 订正):左下角那颗齿轮是**壳自带按钮**(图标栏布局的 `owned` 字段),与任何插件的声明无关。插件声明 `"bottom"` 只是把自己的图标放进底部那一组,点击**照常开自己的标签页**——旧的「点底部图标弹齿轮菜单」行为已废除(背景见 `docs/04-软件更新/待抉择池/齿轮归属与底部图标位/`)。
|
|
420
|
+
|
|
419
421
|
**两条路拿到图标:**
|
|
420
422
|
|
|
421
423
|
| 路径 | 前提 | 说明 |
|
|
@@ -25,7 +25,7 @@
|
|
|
25
25
|
// 不填 core —— 可卸载;core: true 则 UI 无卸载按钮(防误删旗标,非类别)
|
|
26
26
|
"factoryRole": "settings", // ① 关键——声明自己是"设置套"的一份子
|
|
27
27
|
"entry": "src/index.tsx", // 标签页入口(appearsIn.tabBar 需要 entry)
|
|
28
|
-
"appearsIn": { "
|
|
28
|
+
"appearsIn": { "tabBar": true }, // ⛔ 别声明 iconBar——左下齿轮是壳自带的(bottom 只是位置,不是齿轮)
|
|
29
29
|
"tabBehavior": { "singleton": true }, // 单例——切换时已开就不重复开
|
|
30
30
|
"contributes": {
|
|
31
31
|
"viewsContainers": {
|
|
@@ -151,6 +151,7 @@ theme-liquid-glass/
|
|
|
151
151
|
- 应用:`setRecipe`/`setColorway` 或直接写 `app.theme` 配置。
|
|
152
152
|
- 事件:`theme:changed`(payload 带 tokens),做实时联动。
|
|
153
153
|
- 混搭:你的主题按贡献的域(`RecipeMeta.domains`)自动出现在设置页混搭来源里,**作者零额外工作**。
|
|
154
|
+
- 来源标注:主题卡片与命令面会标出**这条配方是谁提供的**(壳内置兜底 =「壳自带」,插件贡献 = 插件名——数据源就是 `RecipeMeta.source`);插件名自动取 `plugin.json` 的 `name`,**作者零额外工作**。
|
|
154
155
|
|
|
155
156
|
## 5. 迁移(现有主题插件——决策 F:零向后兼容)
|
|
156
157
|
|
|
@@ -117,7 +117,7 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
|
|
|
117
117
|
| 宿主配色 id | `dark-fallback`、`light` | `app.themeColor` 与配色来源空间的兜底取值 |
|
|
118
118
|
| 宿主图标主题 id | `default` | `app.iconTheme` 的保底取值 |
|
|
119
119
|
| 宿主外观哨兵值 | `followTheme` | 混搭来源的「跟随主题」哨兵——**它不是 id**,别拿一个插件 id 去顶它 |
|
|
120
|
-
| 宿主专用旗子(插件**禁设**) | `activeEditor`、`editorCount`、`editorHasSelection`、`inputFocus`、`sidebarPosition`、`updateActionable`、`updateButtonLabel` | 你在运行时经 IPC 设它,宿主会 `console.error` **点名你**(值照写:旗子是状态不是注册,运行时拿不到「谁是先者」) |
|
|
120
|
+
| 宿主专用旗子(插件**禁设**) | `activeEditor`、`editorCount`、`editorHasSelection`、`inputFocus`、`settingsSlotFilled`、`sidebarPosition`、`updateActionable`、`updateButtonLabel` | 你在运行时经 IPC 设它,宿主会 `console.error` **点名你**(值照写:旗子是状态不是注册,运行时拿不到「谁是先者」) |
|
|
121
121
|
| 宿主公开约定旗子(插件**可设**) | `settingKey`、`settingFollowTheme`、`settingModified`、`settingResetsToDefault` | 这 4 个是**公开约定面**:官方 `settings` 插件写、宿主命令的 `when` 读——照约定用,别改语义 |
|
|
122
122
|
|
|
123
123
|
**怎么自查**(你自己的仓里就能跑):装上 `@linkdesk/plugin-sdk` 后,你仓里的 `verify` 会跑四条归属腿
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@linkdesk/plugin-docs",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.48",
|
|
4
4
|
"description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"files": [
|