@linkdesk/plugin-docs 0.1.56 → 0.1.58

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.
@@ -34,7 +34,7 @@
34
34
  └──────────────────────────────────────┘
35
35
  ```
36
36
 
37
- - **ViewContainer** = 侧栏/面板的一个"频道"。点图标栏切换。如 `explorer` / `marketplace` / `serial-monitor` / `panel-demo`。
37
+ - **ViewContainer** = 侧栏/面板的一个"频道"。点图标栏切换。如 `explorer` / `marketplace` / `serial-monitor`,或你自己的 `<pluginId>`。
38
38
  - **View** = 容器里的一个可折叠 section。如 `folders` / `sessions` / `settings`。
39
39
  - **任何插件** 都可以往别人的容器里注册 view。容器的主人不知道、不关心。
40
40
  - **渲染位置由 `location` 决定**:`"sidebar"` → 左侧栏 SidebarZone;`"panel"` → 底部面板 PanelZone(标签栏切换视图);`"auxiliarybar"` → 右侧辅助侧栏 RightSidebarZone——⚠ **壳当前未接线(不渲染,区域 dormant)**:声明 auxiliarybar 容器/视图 = 无表面不可见。第三方侧栏/面板需求请用 `"sidebar"`/`"panel"`。所有区都用同一个 `PoolSectionStack` 渲染 view(SidebarSection 自动包裹)。
@@ -81,7 +81,7 @@
81
81
  | `hideIfEmpty` | ❌ | boolean | 无活跃 view 时自动隐藏。默认 `false` |
82
82
  | `order` | ❌ | number | 同位置容器排序。小值靠前 |
83
83
  | `icon` | ❌ | string | 容器图标——覆盖插件自身图标 |
84
- | `mergeHeaderWhenSingle` | ❌ | boolean | 容器内只有一个 view 时,隐藏 view 折叠头——标题合并到容器 header。对标 VS Code `mergeViewWithContainerWhenSingleView`(`panel-demo` 侧栏容器即用此模式) |
84
+ | `mergeHeaderWhenSingle` | ❌ | boolean | 容器内只有一个 view 时,隐藏 view 折叠头——标题合并到容器 header。对标 VS Code `mergeViewWithContainerWhenSingleView`(只装一个 view 的侧栏容器即用此模式) |
85
85
 
86
86
  ### views 字段(全表)
87
87
 
@@ -121,7 +121,7 @@
121
121
 
122
122
  **widget 字段:** `id`(唯一)、`command`(点击执行的命令 ID)、`args`(可选——`executeCommand(command, args)` 单个位置参数透传)、`icon`(codicon 类名,如 `"codicon-add"`)、`title`(tooltip/aria-label/无 icon 时的文本)、`items`(dropdown/split 的备选条目 `{ label, command, args }`)。
123
123
 
124
- ### 真实示例——panel-demo(官方验证插件)
124
+ ### 实例——声明 titleActions 的面板视图
125
125
 
126
126
  ```json
127
127
  {
@@ -133,20 +133,20 @@
133
133
  {
134
134
  "type": "split",
135
135
  "id": "add-log",
136
- "command": "panel-demo.addLog",
136
+ "command": "demo-plugin.addLog",
137
137
  "icon": "codicon-add",
138
138
  "title": "添加演示日志",
139
139
  "args": { "level": "info", "text": "主按钮——添加信息日志" },
140
140
  "items": [
141
- { "label": "添加信息", "command": "panel-demo.addLog", "args": { "level": "info" } },
142
- { "label": "添加警告", "command": "panel-demo.addLog", "args": { "level": "warn" } },
143
- { "label": "添加错误", "command": "panel-demo.addLog", "args": { "level": "error" } }
141
+ { "label": "添加信息", "command": "demo-plugin.addLog", "args": { "level": "info" } },
142
+ { "label": "添加警告", "command": "demo-plugin.addLog", "args": { "level": "warn" } },
143
+ { "label": "添加错误", "command": "demo-plugin.addLog", "args": { "level": "error" } }
144
144
  ]
145
145
  },
146
146
  {
147
147
  "type": "icon",
148
148
  "id": "clear-log",
149
- "command": "panel-demo.clearLog",
149
+ "command": "demo-plugin.clearLog",
150
150
  "icon": "codicon-clear-all",
151
151
  "title": "清空输出"
152
152
  }
@@ -159,17 +159,17 @@
159
159
  `titleActions` 声明的 `command` 执行真相源 = **池侧命令注册表**(`executeCommand` 池侧优先、壳 IPC fallback)。命令 handler 在 view 组件里注册:
160
160
 
161
161
  ```tsx
162
- // DemoOutputView.tsx(panel-demo 真实写法)
162
+ // DemoOutputView.tsx
163
163
  useEffect(() => {
164
164
  const api = window.linkdesk?.commands;
165
165
  api?.registerCommand?.(
166
- "panel-demo.addLog",
166
+ "demo-plugin.addLog",
167
167
  (args?: { level?: LogLevel; text?: string }) => {
168
168
  addLine(args?.level ?? "info", args?.text ?? "");
169
169
  },
170
170
  // 池侧 registerCommand 注册——when 交给声明制;when:"false" = 纯程序化命令不进命令面板(titleActions 专属)
171
171
  );
172
- api?.registerCommand?.("panel-demo.clearLog", () => clearLines());
172
+ api?.registerCommand?.("demo-plugin.clearLog", () => clearLines());
173
173
  }, []);
174
174
  ```
175
175
 
@@ -246,21 +246,21 @@ await window.linkdesk.panel.reveal("demo-output"); // 聚焦底部面板的 dem
246
246
  - 面板已显示 → 切换聚焦
247
247
  - `viewId` 不在 panel 容器 → **no-op**(不报错)
248
248
 
249
- **完整面板容器示例——panel-demo:**
249
+ **完整面板容器示例——同一个插件同时声明面板容器与侧栏容器:**
250
250
 
251
251
  ```json
252
252
  {
253
253
  "contributes": {
254
254
  "viewsContainers": {
255
- "panel-demo": { "title": "面板演示", "location": "panel" },
256
- "panel-demo-sidebar": { "title": "面板演示", "location": "sidebar" }
255
+ "demo-plugin": { "title": "面板演示", "location": "panel" },
256
+ "demo-plugin-sidebar": { "title": "面板演示", "location": "sidebar" }
257
257
  },
258
258
  "views": {
259
- "panel-demo": [
259
+ "demo-plugin": [
260
260
  { "id": "demo-output", "title": "输出", "render": "src/views/DemoOutputView.tsx", "order": 0, "titleActions": [/* §三 */] },
261
261
  { "id": "demo-todo", "title": "待办", "render": "src/views/DemoTodoView.tsx", "order": 1 }
262
262
  ],
263
- "panel-demo-sidebar": [
263
+ "demo-plugin-sidebar": [
264
264
  { "id": "demo-sidebar", "title": "侧栏演示", "render": "src/views/DemoSidebarView.tsx", "order": 0, "titleActions": [/* §三 */] }
265
265
  ]
266
266
  }
@@ -103,7 +103,7 @@ SDK `publish` 要从它**切段**填目录条目,所以**段标题格式有约
103
103
 
104
104
  > 🔥 **2026-09-14**。本节回答一个此前从没被写下来的问题:**插件源码住在哪个仓库?** 本地目录怎么摆、仓库怎么建 → [15-多仓开发与本地工作区](15-多仓开发与本地工作区.md)。
105
105
 
106
- 1. **源码真相源 = 插件自己的仓库**(`github.com/<owner>/<repo>`),**不是壳仓**。壳仓内的 `plugins/` 只允许两类东西:**夹具**(不发货的 demo,如 `panel-demo`)与**构建产物**(`bundled-plugins/<id>.linkdesk-plugin`)。
106
+ 1. **源码真相源 = 插件自己的仓库**(`github.com/<owner>/<repo>`),**不是壳仓**。壳仓内的 `plugins/` 只允许两类东西:**夹具**(不发货的临时 demo)与**构建产物**(`bundled-plugins/<id>.linkdesk-plugin`)。
107
107
  2. **壳仓 `bundled-plugins/<id>.linkdesk-plugin` 的语义 = 出厂发货用的种子快照**,其版本由 `bundled-plugins.lock.json` 记账(第 7.4 轮产出)。它**不是源码的第二份拷贝**——源码改了必须回插件仓改,改完走发布链路刷新种子。
108
108
  3. **从源码到用户桌面的链路**:插件仓 → `npm run build` → `<id>.linkdesk-plugin`(zip)→ GitHub Release asset → catalog 条目 → 用户安装。**没有一步经过壳仓。**
109
109
  4. **插件身份(id)永不可变**;显示名(`name`)可改;仓库名可改——三分规则与全部命名判据 → [16-命名规范](16-命名规范.md)。
@@ -113,11 +113,12 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
113
113
  | 宿主配置键 | `app.language` | 界面语言 |
114
114
  | 宿主配置键 | `app.osIntegration.dirMenu`、`app.osIntegration.fileAssoc`、`app.osIntegration.fileMenu` | 系统集成(右键菜单、文件关联) |
115
115
  | 宿主配置键 | `app.update.mode`、`app.update.showReleaseNotes` | 更新通道 |
116
+ | 宿主配置键 | `app.storage.cacheDir`、`app.storage.openCacheDir` | 缓存目录——设置「通用 → 存储」**一行**(打开缓存目录按钮 + 右侧同排只读路径)。⚠️ `cacheDir` 已退役、**不再声明**(设置行案 D3 合并),名字照旧保留(不腾位),登记见 `scripts/host-reserved.json` 的 `retired[]` |
116
117
  | 宿主配方 id | `dark`、`light` | `app.theme` 的**兜底取值**。⚠️ `light` 另有一张**证照**:官方 `theme-defaults` 是宿主亮兜底的官方实现者,只有它有权声明这个 id |
117
118
  | 宿主配色 id | `dark-fallback`、`light` | `app.themeColor` 与配色来源空间的兜底取值 |
118
119
  | 宿主图标主题 id | `default` | `app.iconTheme` 的保底取值 |
119
120
  | 宿主外观哨兵值 | `followTheme` | 混搭来源的「跟随主题」哨兵——**它不是 id**,别拿一个插件 id 去顶它 |
120
- | 宿主专用旗子(插件**禁设**) | `activeEditor`、`editorCount`、`editorHasSelection`、`inputFocus`、`settingsSlotFilled`、`sidebarPosition`、`updateActionable`、`updateButtonLabel` | 你在运行时经 IPC 设它,宿主会 `console.error` **点名你**(值照写:旗子是状态不是注册,运行时拿不到「谁是先者」) |
121
+ | 宿主专用旗子(插件**禁设**) | `activeEditor`、`editorCount`、`editorHasSelection`、`inputFocus`、`settingsActiveIsBuiltin`、`settingsSlotFilled`、`sidebarPosition`、`updateActionable`、`updateButtonLabel` | 你在运行时经 IPC 设它,宿主会 `console.error` **点名你**(值照写:旗子是状态不是注册,运行时拿不到「谁是先者」) |
121
122
  | 宿主公开约定旗子(插件**可设**) | `settingKey`、`settingFollowTheme`、`settingModified`、`settingResetsToDefault` | 这 4 个是**公开约定面**:官方 `settings` 插件写、宿主命令的 `when` 读——照约定用,别改语义 |
122
123
 
123
124
  **怎么自查**(你自己的仓里就能跑):装上 `@linkdesk/plugin-sdk` 后,你仓里的 `verify` 会跑四条归属腿
@@ -371,11 +371,12 @@
371
371
  "enum": { "type": "array" },
372
372
  "enumDescriptions": { "type": "object", "description": "enum value → display name mapping" },
373
373
  "description": { "type": "string" },
374
- "uiHint": { "type": "string", "description": "Settings editor rendering hint. SettingsView picks the control from the hint. An unknown hint falls back to the default rendering for its type — no error is thrown. The value is an open string, so third parties may declare new hint names." },
375
- "renderHint": { "type": "string", "description": "Rendering hint for special rows — \"action\" renders a button (its text comes from description, clicking runs actionCommand); \"readonly\" renders a read-only status line whose value comes from executing statusCommand. Open string — an unknown hint falls back to the default rendering for the type." },
376
- "actionCommand": { "type": "string", "description": "Command executed when an \"action\" button is clicked — a shell command id or one of your own (resolved when clicked)" },
374
+ "title": { "type": "string", "description": "Row display name — the short human-readable label shown as the settings row name and on the marketplace features tab (optional — omitted = the settings row falls back to showing the configuration key). Value convention matches description: the Chinese source text IS the i18n key; English translations go in your plugin's i18n/en.json. Keep it a noun phrase (≤12 characters, drop the plugin-name prefix); rows with renderHint \"action\" take a verb-phrase name instead (it reads as a button label)." },
375
+ "uiHint": { "type": "string", "description": "Settings editor rendering hint — SettingsView picks the control from the hint. Known hints: slider, fontSize, color, fontFamily, file, directory, image, segmented, fontTone, accentSource, themePicker, select, stringList. A hint the installed renderer does not know is shown read-only — the current value plus a tooltip saying the declared control is unsupported (no editable fallback control, no error thrown). The value is an open string, so third parties may declare new hint names." },
376
+ "renderHint": { "type": "string", "description": "Rendering hint for special rows — \"action\" renders a button (its text comes from description, clicking runs actionCommand); \"readonly\" renders a read-only status line whose value comes from executing statusCommand; \"color\" renders a read-only color row (swatch + value). \"readonly\"/\"action\" are shorthands meaning the row's primary control IS the status line/button: statusCommand and actionCommand may also be declared alongside any primary control, rendering as companions to its right ([primary control][companion button][companion readonly]). Known hints: readonly, action, color. An unknown hint is shown read-only (current value + explanatory tooltip). Open string." },
377
+ "actionCommand": { "type": "string", "description": "Command executed when an \"action\" button is clicked — a shell command id or one of your own (resolved when clicked). May be declared alongside any primary control: it then renders as a companion button to the right of that control, with its text taken from description." },
377
378
  "actionDisabledAll": { "type": "array", "description": "Disable the \"action\" button while every entry matches the current configuration value (omit the field entirely — or pass an empty list — to keep the button always enabled)", "items": { "type": "object", "required": ["key", "value"], "properties": { "key": { "type": "string" }, "value": {} }, "additionalProperties": false } },
378
- "statusCommand": { "type": "string", "description": "Command whose return value (a string) is shown by a \"readonly\" status line — the value comes from the command, not from configuration storage, so a status row can show live runtime state. Shell command id or one of your own." },
379
+ "statusCommand": { "type": "string", "description": "Command whose return value (a string) is shown by a \"readonly\" status line — the value comes from the command, not from configuration storage, so a status row can show live runtime state. The settings view polls it (every 3s by default; polling pauses while the window is hidden). Shell command id or one of your own. The command must be cheap, idempotent and side-effect free — it may be called repeatedly in the background. May be declared alongside any primary control: it then renders as a companion read-only line to the right of that control. Without a primary control, declare renderHint \"readonly\" so the status line becomes the row's main control." },
379
380
  "monoOnly": { "type": "boolean", "description": "Monospace only — meaningful only with uiHint \"fontFamily\". true/omitted = list monospace families only (editor fonts); false = all families (UI fonts)." },
380
381
  "minimum": { "type": "number", "description": "Numeric lower bound — applies when type is number (range of the slider/numeric control)" },
381
382
  "maximum": { "type": "number", "description": "Numeric upper bound — applies when type is number (range of the slider/numeric control)" },
@@ -59,6 +59,8 @@
59
59
  | `texture` / `textureOpacity` | (写入 per-surface 背景族) | 可平铺纹理图资产路径与不透明度 | 不写 |
60
60
 
61
61
  > ⚠️ **大面积 `blur` 是 GPU 负担**——用得越克制越流畅。
62
+ >
63
+ > 🔴 **两个「玻璃不透明度」不是一个旋钮**(作者最容易撞的一处):本域的 `opacity`(→ `--glass-opacity`)是**这只主题自带的玻璃材质**有多厚;**用户在设置里**调的「玻璃不透明度」(`app.glassOpacity` → `--glass-surface-alpha`)是**玻璃表面的合成比例**(`color-mix(… calc(var(--glass-surface-alpha) * 100%) …)`)。两者相乘、各自生效——想调「玻璃感」先看清自己在调哪一个。
62
64
 
63
65
  ### `font` —— 字体
64
66
 
@@ -80,6 +82,8 @@
80
82
  > 🔴 **`mask` 是数字(0–1),不是颜色字符串**——要指定遮罩颜色用 `maskColor`。
81
83
  > ([11-主题制作](https://github.com/Encaron/linkdesk/blob/electron/docs/11-主题制作.md) 的满配示例里曾把它写成 `rgba(...)`,与 schema 不符,已订正。)
82
84
 
85
+ > 🔴 **背景面这一组键建议写全**:`--bg-window` · `--bg-card` · `--bg-input` · `--bg-titlebar` · `--bg-toolbar` · `--bg-side-panel` · `--bg-icon-bar` · `--bg-selection`(各色面/栏的底色)。玻璃化的表面由引擎按**锚点**派生一份 `*-solid` 兜底色——**缺哪个键就按锚点算**,观感未必是你要的(「顶栏当一块独立岛」这类配方尤其明显)。只想改一两处没问题,但别在没看清派生规则时整组漏掉。
86
+
83
87
  ---
84
88
 
85
89
  ## 三、`colorways[].colors` —— 颜色 token 怎么起名
@@ -103,6 +107,14 @@
103
107
  **全集在哪**:壳的默认主题 token 全表 = 仓库 `src/index.css` 的 `:root`(近百个)。
104
108
  **只想改几个就写几个**——没写的继承基线(浅色主题继承浅底、深色继承深底)。
105
109
 
110
+ 🔴 **图标色是壳算的,主题给不了**:`icon-active` **不是有效键**——壳从不读它,写了既不报错也不生效(图标墨色由壳按当前主题的**文字色**自动派生,深浅与用户「文字极性」都会跟着翻;想影响图标,改文字色/极性)。
111
+
112
+ > `icon-inactive` 是**有效**的,但语义只有一处:**欢迎页「非激活图标」的用色**。图标栏不读它。
113
+
114
+ 🔴 **挂了背景照片,标题栏/状态栏文字的可读性归你**(2026-10-03 拍板):标题栏菜单与状态栏的文字读的是 **`--text-secondary`**,**壳不会替你自动调它**——因为这两处是作者正式在用的色,引擎不夺作者的最终发言权。实测把照片挂上后,这两处对比度只有 **1.90 / 2.67**(无障碍标准线 3:1)——**偏暗的照片上深色次要文字会糊掉**。⇒ 用 `background.image` 的主题**自己**保证这两处看得清:抬高 `text-secondary` 的明度,或加大 `mask`。**图标栏不在此列**(那里的墨色由壳接管,见上一条)。
115
+
116
+ ⚠️ **键名写错不报错、也不生效**:colorway 的键是**逐键直通**的(壳把 `"bg-window"` 原样写成 `--bg-window`,**没有白名单校验**)——`icon-actve` 这种手误既不会红、也不会有任何作用,只会在真机上「怎么没变化」。**新加或改动键之前**先查壳的变量契约:[02-变量契约](https://github.com/Encaron/linkdesk/blob/electron/02-Electron架构/归一化基建/外观主题化/02-变量契约.md)(或仓库 `src/index.css` 的 `:root`)。
117
+
106
118
  > ⚠️ **别指望改 `--accent` 就完事**:有些控件故意读自己的 token(例如开关的 `--toggle-on-bg`)而不是 `--accent`——设计上就是让它们可以不同步。要精确控制就去读那个控件实际用的变量。
107
119
 
108
120
  ---
package/package.json CHANGED
@@ -1,20 +1,20 @@
1
- {
2
- "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.56",
4
- "description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
- "type": "module",
6
- "files": [
7
- "docs",
8
- "README.md"
9
- ],
10
- "engines": {
11
- "node": ">=18.0.0"
12
- },
13
- "keywords": [
14
- "linkdesk",
15
- "plugin",
16
- "docs",
17
- "authoring"
18
- ],
19
- "license": "MIT"
20
- }
1
+ {
2
+ "name": "@linkdesk/plugin-docs",
3
+ "version": "0.1.58",
4
+ "description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
+ "type": "module",
6
+ "files": [
7
+ "docs",
8
+ "README.md"
9
+ ],
10
+ "engines": {
11
+ "node": ">=18.0.0"
12
+ },
13
+ "keywords": [
14
+ "linkdesk",
15
+ "plugin",
16
+ "docs",
17
+ "authoring"
18
+ ],
19
+ "license": "MIT"
20
+ }