@linkdesk/plugin-docs 0.1.28 → 0.1.30

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/00-readme.md CHANGED
@@ -28,6 +28,8 @@
28
28
  | **Look up the API** (what can I call) | [01-plugin-api-contract §3](01-plugin-api-contract.md) (the entry table for the three API surfaces) | → the SDK package README cheatsheet / `linkdesk.d.ts` |
29
29
  | **Use the UI parts the shell provides** | [19-component-cheatsheet](19-component-cheatsheet.md) | → [05-ui-conventions](05-ui-conventions.md) |
30
30
  | **Look up a specific field** | [06-plugin-json-spec](06-plugin-json-spec.md) | → `plugin.schema.json` (IDE completion) |
31
+ | **Choose my plugin's images** (which file does what: icon-bar glyph / marketplace identity / README cover) | [06-plugin-json-spec §The marketplace image marketIcon](06-plugin-json-spec.md) | → [17-region-map §the three-image model](17-region-map.md) |
32
+ | **Put images / videos in my README** (what the marketplace Details tab shows) | [12-readme-media-contract](12-readme-media-contract.md) | — |
31
33
  | **Package / share / list** | [04-distribution-format](04-distribution-format.md) | → [steps 8–9 in 13](13-development-guide.md) |
32
34
  | **Where to put the project, how to name the repo** | [15-multi-repo-and-local-workspace](15-multi-repo-and-local-workspace.md) | → [16-naming-conventions](16-naming-conventions.md) |
33
35
 
@@ -154,6 +154,8 @@ Author-side notes on install/uninstall/update/reinstall are in [02 plugin lifecy
154
154
  Content changes require a version bump → rebuild and republish → user runs checkUpdates/update
155
155
  ```
156
156
 
157
+ > Publishing from CI / a non-interactive shell (env token, `--yes`, the expired-PAT 401 trap) → [13-development-guide Step 9](13-development-guide.md).
158
+
157
159
  ---
158
160
 
159
161
  ## 8. Comparison with VS Code
@@ -222,6 +222,29 @@ publish's target repo = your project's git remote `origin` (publishing to **your
222
222
  >
223
223
  > When you still need to run `git init` yourself: you generated with `--no-git`, or the project was generated **inside another git repo** (in which case the scaffold deliberately skips creating a nested repo, following `cargo new` semantics).
224
224
 
225
+ **Publishing from CI / non-interactive shells (AI agents included)**
226
+
227
+ Two steps want you at the keyboard in an interactive run — both have non-interactive answers:
228
+
229
+ | Interactive step | Non-interactive answer |
230
+ |:--|:--|
231
+ | The GitHub token prompt | Set the `LINKDESK_GITHUB_TOKEN` env var (below) |
232
+ | The `[y/N]` "publish this?" confirmation | Pass `--yes` (or preview first with `--dry-run`) |
233
+
234
+ `publish` finds the token in this order: **①** env `LINKDESK_GITHUB_TOKEN` → **②** the SDK config file (`linkdesk-sdk/config.json` under your OS config directory — written automatically the first time you published from an interactive terminal) → **③** a masked interactive prompt. Without a token in a non-interactive shell, publish **fails immediately** with a message telling you to set the env var — it does not hang.
235
+
236
+ ```bash
237
+ LINKDESK_GITHUB_TOKEN=ghp_xxx npm run publish -- --yes # one-off, inside a script
238
+ ```
239
+
240
+ ```yaml
241
+ # GitHub Actions — expose the stored secret to the step
242
+ env:
243
+ LINKDESK_GITHUB_TOKEN: ${{ secrets.LINKDESK_GITHUB_TOKEN }}
244
+ ```
245
+
246
+ > 🔔 **A 401 that means "expired", not "wrong":** publish talks to the GitHub REST API with a **classic PAT** (repo scope). If publishing suddenly fails with 401 while everything else on the machine still works, the usual culprit is an **expired PAT** — create a fresh one and update the env var or the config file.
247
+
225
248
  **How to know you did it right**
226
249
  Step one: your `.linkdesk-plugin` asset shows up on the GitHub Release. Step two: once your entry is in the official catalog, **on a clean machine (default configuration, no marketplace sources added)** it can be found in the marketplace, installed, and updated — that's the criterion for "listing complete".
227
250
 
@@ -59,7 +59,7 @@
59
59
 
60
60
  ---
61
61
 
62
- ## 3. Three Things People Mix Up Most
62
+ ## 3. Things People Mix Up Most
63
63
 
64
64
  ### ① Icon Bar ≠ tab: two plugin shapes
65
65
 
@@ -73,6 +73,16 @@ A plugin has **two paths** to being seen. Don't mix them up:
73
73
  > **entryless is the recommended path for sidebar-only plugins** — no need to write an empty `src/index.tsx` just to earn an icon.
74
74
  > Conversely: `appearsIn.tabBar: true` **requires** an `entry` (tabs are rendered by the entry component).
75
75
 
76
+ **What clicking the Icon Bar icon actually does, by declaration** (two shell consumers read the same click independently — one opens tabs, one switches the sidebar):
77
+
78
+ | Declaration | Clicking the icon does |
79
+ |:--|:--|
80
+ | `entry` + `appearsIn: { iconBar: "top", tabBar: true }` | **Opens (or focuses) a tab** — the classic shape, nothing else to declare |
81
+ | `entry` + `appearsIn: { iconBar: "top" }` — no `tabBar`, no sidebar container | **Nothing** — the icon is display-only. `iconBar` alone never opens a tab; add `tabBar: true` for that |
82
+ | No `entry` + sidebar container + `appearsIn: { iconBar: "top" }` | **Switches to your sidebar container**; clicking the same icon again collapses/expands the sidebar — entryless never opens a tab |
83
+ | `entry` + `tabBar: true` + sidebar container | The sidebar switch always happens; the tab opens **only when `appearsIn.sidePanel` is not declared** — declare `sidePanel: true` to keep the click sidebar-only |
84
+ | Top-level `statusBar[]` | Never goes through the Icon Bar at all — entries render directly in the Status Bar, and clicking one runs that entry's own `onClick` command |
85
+
76
86
  **Three cases where you don't get an icon** (none of them are bugs — they're by design):
77
87
  - You don't declare `appearsIn.iconBar` (**opt-in** — no declaration, no icon)
78
88
  - Data plugins (language packs / themes / icon themes, anything without a sidebar container)
@@ -92,6 +102,16 @@ The sidebar holds two layers, **container → view**: the container is a "channe
92
102
 
93
103
  When the shell renders with `PoolSectionStack` it **automatically** wraps your component in a collapsible header. Just return the **content**; wrap it yourself and you get a double header.
94
104
 
105
+ ### ④ Three images, three jobs: `icon` / `marketIcon` / `cover`
106
+
107
+ | Image | Where it shows up | The one rule that bites |
108
+ |:--|:--|:--|
109
+ | `icon` | Icon Bar / tab bar / [+] menu / welcome page | **The Icon Bar force-tints it** — draw a single-colour line glyph, a coloured image turns into a blob |
110
+ | `marketIcon` | Marketplace list row + detail-page header | The coloured identity image; omit it and the market falls back to `icon` |
111
+ | `cover` | README description area only | Not a manifest field — put the file in `resources/` and reference it from `README.md` |
112
+
113
+ Full rules → [06-plugin.json Spec §The marketplace image marketIcon](06-plugin-json-spec.md) · [12-README Media Contract](12-readme-media-contract.md).
114
+
95
115
  ---
96
116
 
97
117
  ## 4. Minimal Declaration Snippet for Each Region
@@ -28,6 +28,8 @@
28
28
  | **查 API**(能调什么) | [01-插件API契约 §三](01-插件API契约.md)(三处 API 面的入口表) | → SDK 包内 README 速查表 / `linkdesk.d.ts` |
29
29
  | **用壳提供的 UI 零件** | [19-组件速查](19-组件速查.md) | → [05-插件UI写法规约](05-插件UI写法规约.md) |
30
30
  | **查某个字段** | [06-plugin.json规范](06-plugin.json规范.md) | → `plugin.schema.json`(IDE 补全) |
31
+ | **选插件的几张图**(哪个文件管哪:图标栏剪影 / 市场身份图 / README 封面) | [06-plugin.json规范 §marketIcon](06-plugin.json规范.md) | → [17-区域地图 三图模型](17-区域地图.md) |
32
+ | **README 里放图/视频**(市场详情页说明区显示什么) | [12-README说明区媒体契约](12-README说明区媒体契约.md) | — |
31
33
  | **打包 / 给别人装 / 上架** | [04-插件分发格式](04-插件分发格式.md) | → [13 第 8–9 步](13-插件开发指南.md) |
32
34
  | **工程放哪、仓怎么起名** | [15-多仓开发与本地工作区](15-多仓开发与本地工作区.md) | → [16-命名规范](16-命名规范.md) |
33
35
 
@@ -154,6 +154,8 @@ my-plugin/
154
154
  内容变更必 bump version → 重 build 重发 → 用户 checkUpdates/update
155
155
  ```
156
156
 
157
+ > 在 CI / 非交互终端里发布(env token、`--yes`、PAT 过期 401 那个坑)→ [13-插件开发指南 第 9 步](13-插件开发指南.md)。
158
+
157
159
  ---
158
160
 
159
161
  ## 八、与 VS Code 对照
@@ -169,6 +169,8 @@ useEffect(() => {
169
169
 
170
170
  **❌ 反模式(红字):** `document.addEventListener("keydown", ...)` / `window.addEventListener("keydown", ...)` = **全局劫持**——绕过分区前提,插件有活动会话时劫持全池同键(串口 F2 曾劫持文件树 F2)。**`tabIndex` + 容器 `onKeyDown` 才是焦点分区正解**;非焦点元素不触发,可加 `tabIndex={0}` 承接。
171
171
 
172
+ 🔴 **这条反模式有腿了(2026-09-20,SDK 0.1.46 起)**:`linkdesk-plugin-sdk lint` 的 `linkdesk/no-global-key-listener` 腿机械拦截 window/document 的 keydown/keyup **字面量**监听,报错文案直接给正解与豁免写法。确需全局抓键的正当形态(如快捷键录制器要 capture 抓原始键)走标准 disable 注释+理由——判据本身无白名单。
173
+
172
174
  **注意:** 轨道二键**不进快捷键设置面板**——面板只显示 KeybindingRegistry 绑定(轨道一)。这是设计取舍(注册即吞池,见 4.1),不是 bug。
173
175
 
174
176
  ### 4.3 剪贴板三选一通道表
@@ -532,6 +534,8 @@ monaco 当前背景不透明、只二态跟随(亮/暗)是**过渡态绕开
532
534
  (`@linkdesk/ui`)的样式、以及**所有已加载插件**的样式——**类名是全局标识符**。你写下一个类名,
533
535
  就等于占用了这个名字;别人也用这个名字,两边的样式就会落到同一个元素上。
534
536
 
537
+ 🔴 **引用侧也有腿了(2026-09-20,SDK 0.1.46 起)**:TSX `className` **字面量**里引用的本插件前缀类名,必须能在本仓 CSS(含 scoped 规则)里找到定义——`linkdesk/no-reserved-class-name` 家族新判据机械把关。头号根因 = CSS 块注释里写 `--text-*/` 这类文本:`*/` 把注释**提前闭合**,残渣黏住下一条规则把它整条吞掉(生态首例,样式静默丢失零报错);文案列三种常见根因(拼错/漏 import/注释吞规则)。动态拼接(模板插值 / clsx / 变量)跳过并计数。
538
+
535
539
  **三条纪律:**
536
540
 
537
541
  1. **给自己的元素起的类名,必须以 `pluginId` 加连字符开头**——`settings-*`、`editor-*`、`file-tree-*`……
@@ -222,6 +222,29 @@ publish 的目标仓库 = 你工程的 git remote `origin`(发布到**你自
222
222
  >
223
223
  > 什么时候仍需自己 `git init`:生成时带了 `--no-git`,或工程被生成在**另一个 git 仓里**(那时脚手架按 `cargo new` 语义刻意不建嵌套仓)。
224
224
 
225
+ **在 CI / 非交互终端里发布(AI 代理同理)**
226
+
227
+ 交互跑发布有两步要你碰键盘——各有非交互解法:
228
+
229
+ | 交互步骤 | 非交互解法 |
230
+ |:--|:--|
231
+ | GitHub token 掩码输入 | 设环境变量 `LINKDESK_GITHUB_TOKEN`(见下) |
232
+ | 「发布以上内容?[y/N]」确认 | 带 `--yes`(或先 `--dry-run` 预览) |
233
+
234
+ token 的取值顺序:**①** 环境变量 `LINKDESK_GITHUB_TOKEN` → **②** SDK 配置档(你系统配置目录下的 `linkdesk-sdk/config.json`——第一次在交互终端跑 publish 时自动写入)→ **③** 交互式掩码输入。非交互终端里找不到 token 时,publish **立即报错**并提示设环境变量——不会挂住干等。
235
+
236
+ ```bash
237
+ LINKDESK_GITHUB_TOKEN=ghp_xxx npm run publish -- --yes # 脚本里一次性用
238
+ ```
239
+
240
+ ```yaml
241
+ # GitHub Actions——把存的 secret 注入该步骤
242
+ env:
243
+ LINKDESK_GITHUB_TOKEN: ${{ secrets.LINKDESK_GITHUB_TOKEN }}
244
+ ```
245
+
246
+ > 🔔 **401 多半是「到期」,不是「填错」:** publish 走 GitHub REST API,用**经典 PAT**(repo 权限)。如果发布突然 401 而机器上别的一切正常,头号嫌疑是 **PAT 过期**——新造一个,更新环境变量或配置档。
247
+
225
248
  **怎么知道做对了**
226
249
  第一步:GitHub Release 上出现你的 `.linkdesk-plugin` 资产;第二步:官方目录出现你的条目后,**在一台干净机器(默认配置、不加任何市场源)**上市场里搜得到、能装、能更新——这才是「上架完成」的判据。
227
250
 
@@ -59,7 +59,7 @@
59
59
 
60
60
  ---
61
61
 
62
- ## 三、最容易搞混的三件事
62
+ ## 三、最容易搞混的几件事
63
63
 
64
64
  ### ① 图标栏 ≠ 标签页:两种插件形态
65
65
 
@@ -73,6 +73,16 @@
73
73
  > **entryless 是侧栏专用插件的推荐路径**——不用为了"凑一个图标"去写一个空的 `src/index.tsx`。
74
74
  > 反过来:`appearsIn.tabBar: true` **必须**配合 `entry`(标签页靠 entry 组件渲染)。
75
75
 
76
+ **不同声明组合下,点图标栏图标实际会发生什么**(壳里有两个消费者各自独立响应同一次点击——一个管开标签页,一个管切侧栏):
77
+
78
+ | 声明 | 点图标之后 |
79
+ |:--|:--|
80
+ | `entry` + `appearsIn: { iconBar: "top", tabBar: true }` | **直接开(或聚焦)标签页**——经典形态,无需额外声明 |
81
+ | `entry` + `appearsIn: { iconBar: "top" }`——无 `tabBar`、也无侧栏容器 | **什么都不发生**——图标纯展示。只声明 `iconBar` 图标不会开标签页,要开得加 `tabBar: true` |
82
+ | 无 `entry` + 侧栏容器 + `appearsIn: { iconBar: "top" }` | **切到你的侧栏容器**;再点同一个图标 = 折叠/展开侧栏——entryless 永不开标签页 |
83
+ | `entry` + `tabBar: true` + 侧栏容器 | 切侧栏总会发生;标签页**只在未声明 `appearsIn.sidePanel` 时才开**——声明 `sidePanel: true` 可让点击只切侧栏 |
84
+ | 顶层 `statusBar[]` | 根本不经过图标栏——条目直接渲染在状态栏,点击跑条目自己的 `onClick` 命令 |
85
+
76
86
  **拿不到图标的三种情况**(都不是 bug,是设计):
77
87
  - 不声明 `appearsIn.iconBar`(**opt-in**——不写就没有图标)
78
88
  - 数据插件(语言包 / 主题 / 图标主题这类没有侧栏容器的)
@@ -92,6 +102,16 @@
92
102
 
93
103
  壳用 `PoolSectionStack` 渲染时**自动**给你的组件包上折叠头。你返回**内容**就行,包了就是双层折叠头。
94
104
 
105
+ ### ④ 三张图三种职责:`icon` / `marketIcon` / `cover`
106
+
107
+ | 图 | 出现在哪 | 最容易咬人的那条规则 |
108
+ |:--|:--|:--|
109
+ | `icon` | 图标栏 / 标签栏 / `[+]` 菜单 / 欢迎页 | **图标栏会强制单色染色**——要画单色线稿剪影,放彩色图会糊成一团 |
110
+ | `marketIcon` | 市场列表行 + 详情页头部 | 彩色身份图;不声明则市场回落用 `icon` |
111
+ | `cover` | 只住 README 说明区 | 不是 manifest 字段——文件放 `resources/`,从 `README.md` 里引用 |
112
+
113
+ 完整规则 → [06-plugin.json规范 §marketIcon](06-plugin.json规范.md) · [12-README说明区媒体契约](12-README说明区媒体契约.md)。
114
+
95
115
  ---
96
116
 
97
117
  ## 四、每个区域的最小声明片段
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.28",
3
+ "version": "0.1.30",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——`docs/03-插件制造` 的发布产物:从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [