@linkdesk/plugin-docs 0.1.27 → 0.1.29

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
 
@@ -106,6 +106,7 @@ All three are declared in the schema (see [03-contributes](03-contributes-spec.m
106
106
  - `minAppVersion` — checked at load time (not satisfied → toast + skip)
107
107
  - **Mechanical gate (SDK lint)**: consuming `@linkdesk/ui` at runtime ⇒ `plugin.json` must declare `minAppVersion` ≥ `0.2.13` (the UI re-anchor version — vendor supply of shared components exists only from that shell onward; `import type` is exempt as compile-time-erased). Enforced by `linkdesk-plugin-sdk lint` (`check-ui-min-app-version`), no disable exit
108
108
  - `requires` — runtime dependency orchestration applies (missing dependency → suspend as PENDING + cycle fail-loud + cascading uninstall in reverse topological order, see [02 §4](02-plugin-lifecycle.md))
109
+ - **Auto-install at install time (shell-side, opt-in via the request)**: when the install request carries a catalog source URL (the marketplace passes the listing's source), missing `requires` dependencies are installed automatically **inside the same install job** — inline and recursive, no second concurrency slot; a failing dependency fails the parent job (naming the dependency) and rolls back the parent's extracted files so a retry starts clean. Already-installed dependencies are skipped; disabled ones are never auto-enabled. Declaring `requires` is all an author does — no shell changes needed
109
110
  - `permissions` — declaring them informs the user; the authorization model is still pending
110
111
 
111
112
  ---
@@ -153,6 +154,8 @@ Author-side notes on install/uninstall/update/reinstall are in [02 plugin lifecy
153
154
  Content changes require a version bump → rebuild and republish → user runs checkUpdates/update
154
155
  ```
155
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
+
156
159
  ---
157
160
 
158
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
 
@@ -106,6 +106,7 @@ my-plugin/
106
106
  - `minAppVersion` —— 加载期校验(不满足 → toast + 跳过)
107
107
  - **机械门禁(SDK lint)**:运行时消费 `@linkdesk/ui` ⇒ `plugin.json` 必须声明 `minAppVersion` ≥ `0.2.13`(重锚号——共享组件的集中供给自这一版才存在;`import type` 编译期擦除、豁免)。由 `linkdesk-plugin-sdk lint` 判红(`check-ui-min-app-version`),无豁免出口
108
108
  - `requires` —— 运行期依赖编排生效(缺依赖挂起 PENDING + 环 fail-loud + 连带卸载逆拓扑,见 [02 §四](02-插件生命周期.md))
109
+ - **安装期自动装依赖(壳侧,随请求启用)**:安装请求携带来源市场目录时(市场插件随请求带条目来源 URL),`requires` 里缺失的依赖会在**同一个安装任务内**自动先装——内联递归、不占第二个并发槽;某个依赖失败 ⇒ 父任务失败并指名依赖,且父插件本次解压产物自动回滚、重试干净可用。已装的依赖跳过;禁用的**不自动启用**。作者只需声明 `requires`,无需为壳做任何适配
109
110
  - `permissions` —— 声明即用户知情,授权模型待 E6
110
111
 
111
112
  ---
@@ -153,6 +154,8 @@ my-plugin/
153
154
  内容变更必 bump version → 重 build 重发 → 用户 checkUpdates/update
154
155
  ```
155
156
 
157
+ > 在 CI / 非交互终端里发布(env token、`--yes`、PAT 过期 401 那个坑)→ [13-插件开发指南 第 9 步](13-插件开发指南.md)。
158
+
156
159
  ---
157
160
 
158
161
  ## 八、与 VS Code 对照
@@ -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.27",
3
+ "version": "0.1.29",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——`docs/03-插件制造` 的发布产物:从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [