@linkdesk/plugin-docs 0.1.34 → 0.1.35

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.
@@ -473,7 +473,7 @@ Your translation file is **one flat layer of keys**, and everyone writes into th
473
473
 
474
474
  🔴 **Why this is advice and not a requirement**: **an i18n key may legitimately live in the app-level dictionary**. The official `settings` plugin has 254 `t()` call sites and **not a single key of its own in its repo** — they all live in `lang-defaults`' `zh.json` / `en.json`. Inside your plugin repo there is only your own `i18n/*.json` — **you cannot see the shell's dictionary, nor any other plugin** — so "your key collided with someone" is **never decidable from your own repo**. Making it a blocker means guaranteed false positives, and false positives invalidate the rules that should really block. ⇒ **It is a yellow light, not a red one.**
475
475
 
476
- **How much overlap actually exists today** (told plainly, not exaggerated): the keys declared by the 18 official plugins (414 of them) overlap the `lang-defaults` keys in **65 places**, and **3 of those already have divergent translations** — for example `命令`, where the shell says `Command` while `serial-monitor` says `Commands`. **When both are written into the same dictionary, which one the user actually sees depends on plugin load order.**
476
+ **How much overlap actually exists** (told plainly, not exaggerated — the counts below are a **measurement**, taken when the roster was 18 official plugins, not a live figure): those plugins declared **414 keys**, **65 of which overlap** the `lang-defaults` keys, and **3 of those already have divergent translations** — for example `命令`, where the shell says `Command` while `serial-monitor` says `Commands`. **When both are written into the same dictionary, which one the user actually sees depends on plugin load order.**
477
477
 
478
478
  ⚠️ **Runtime behaviour**: when an overwrite happens the shell emits a `console.warn` naming the **key + language + writer**:
479
479
 
@@ -781,7 +781,7 @@ useEffect(() => {
781
781
 
782
782
  **Four boundaries**: ① it only governs the **first open** — an existing tab is still focused and an already-open panel still toggles shut; changing the form afterwards keeps using the two old paths ("Open in main window" / "Open in Floating Panel"); ② `formKey` and `defaultForm` are **mutually exclusive** (both declared ⇒ schema validation fails — one form from two sources); ③ a typo'd `formKey` / a key that was never registered ⇒ falls back to `defaultForm` (neither = previous behaviour) plus one warning — it **never fails silently**; ④ declaring `"defaultForm": "tab"` on a plugin with no tab form (`appearsIn.tabBar` + `entry`) falls back to the floating panel rather than silently doing nothing.
783
783
 
784
- **The first declarer = settings** (`core.openSettings`, Ctrl+, opens the panel, and `settings.openForm` lets the user change it inside the "Settings plugin" group); **the second declarer, used as a validation vehicle = the `floating-panel-demo` test plugin** (a tab-style view; end-to-end validation of replacement + the right-click return path + unload no-op).
784
+ **Currently the only declarer = settings** (`core.openSettings`, Ctrl+, opens the panel, and `settings.openForm` lets the user change it inside the "Settings plugin" group). The mechanism itself is generic and is validated end-to-end (replacement + the right-click return path + unload no-op) — nothing stops you from becoming the second declarer.
785
785
 
786
786
  ---
787
787
 
@@ -51,8 +51,8 @@ my-plugin/
51
51
 
52
52
  | Source root | Location | Form | HMR | Who lives here |
53
53
  |------|------|------|:--:|------|
54
- | **The plugin's own repo** | GitHub `Encaron/linkdesk-plugin-<id>` (local clones land under `E:\linkdesk-plugins\official\<id>\`) | source + SDK build (`npm run build` → `<id>.linkdesk-plugin`) | ✅ (`linkdesk-plugin-sdk dev`) | **all 18 shipped plugins**—one repo each, and the only source of truth for their source |
55
- | **Shell repo fixtures** | `<shell repo>/plugins/<id>/` (`env.appPluginsDir`) | source + Vite on-the-fly compilation | ✅ (`npm run dev` hot reload) | only the two remaining **dev fixtures**: `panel-demo` / `floating-panel-demo` (not shipped, not in the zip) |
54
+ | **The plugin's own repo** | GitHub `Encaron/linkdesk-plugin-<id>` (local clones land under `E:\linkdesk-plugins\official\<id>\`) | source + SDK build (`npm run build` → `<id>.linkdesk-plugin`) | ✅ (`linkdesk-plugin-sdk dev`) | **every shipped plugin** (16 today)—one repo each, and the only source of truth for their source |
55
+ | **Shell repo fixtures** | `<shell repo>/plugins/<id>/` (`env.appPluginsDir`) | source + Vite on-the-fly compilation | ✅ (`npm run dev` hot reload) | only the remaining **dev fixture**: `panel-demo` (not shipped, not in the zip) |
56
56
  | **Installed state** | `{userData}/plugins/<id>/` | pre-built bundle unpacked from the zip | ❌ (changing the package means rebuild + reinstall/rematerialize) | every plugin installed on the user's machine |
57
57
 
58
58
  > 🔴 **Why a shipped plugin's source can't be kept in both places**: as soon as the shell repo and the plugin repo each hold a copy, changing one leaves the other stale, and **no gate can detect the divergence** (the content-fingerprint gate only covers zip contents, not source) ⇒ the source of truth must be unique. What the shell repo keeps are **artifacts** (`bundled-plugins/*.linkdesk-plugin`) and **documentation archives**, not source.
@@ -60,7 +60,7 @@ my-plugin/
60
60
  > **Real-device loop exception (author dev):** in the installed state, changing a package requires "rebuild + reinstall/rematerialize", which in **every author real-device verification** scenario means the one-shot-cycle pain of WPF v2. The real-device loop automates it—an SDK rebuild in seconds + a **direct write** into `{userData}/plugins/<id>` (same-disk overwrite semantics, effective on reload) becomes the cycle, and the author still never touches the shell. The distribution zip's "don't modify your own bundle" discipline is unchanged (that is the package for end users). Design archive → [author real-device debugging loop](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/04-作者真机调试环.md).
61
61
 
62
62
  > **Uninstall semantics (after 2026-09-05):** uninstalling an installed plugin = **delete the `{userData}/plugins/<id>/` directory + settle the ledger entry** (no longer a move into `.disabled/`); only app plugins uninstalled from a repo source tree get moved to the `plugins/.disabled/` graveyard (recoverable via reinstall). The sole owner of the ledger `installed-plugins.json` = the renderer-side PluginInstallService; boot only reads its `removed` marker to avoid accidental restoration.
63
- > 🔵 **Cross-check conclusion (does the `.disabled/` graveyard still have consumers):** **the mechanism remains, with no object at present**. The consumers are alive—`src/pluginLoader/loader.ts` reads it (`reinstallPlugin` / the uninstall toast's "undo" / cross-restart orphan cleanup all treat `env.appPluginsDir/.disabled` as the single authoritative surface). But `env.appPluginsDir` = the shell repo's `plugins/`, and the 18 shipped plugins have moved out ⇒ only the two fixtures remain there, and **there is no longer any "app plugin uninstalled from a repo source tree"**. ⇒ The mechanism is **retained** (it is part of the in-repo plugin dev path; removing it would touch three places in the loader plus the main-process scan surface, so risk outweighs benefit), but **don't** treat it as a revocable-uninstall channel for shipped plugins anymore.
63
+ > 🔵 **Cross-check conclusion (does the `.disabled/` graveyard still have consumers):** **the mechanism remains, with no object at present**. The consumers are alive—`src/pluginLoader/loader.ts` reads it (`reinstallPlugin` / the uninstall toast's "undo" / cross-restart orphan cleanup all treat `env.appPluginsDir/.disabled` as the single authoritative surface). But `env.appPluginsDir` = the shell repo's `plugins/`, and the shipped plugins have moved out ⇒ only the one fixture remains there, and **there is no longer any "app plugin uninstalled from a repo source tree"**. ⇒ The mechanism is **retained** (it is part of the in-repo plugin dev path; removing it would touch three places in the loader plus the main-process scan surface, so risk outweighs benefit), but **don't** treat it as a revocable-uninstall channel for shipped plugins anymore.
64
64
 
65
65
  ---
66
66
 
@@ -757,7 +757,7 @@ button { border: none; }
757
757
 
758
758
  **Why it is worth remembering**: the host itself has **17** such "anchorless selectors" (`*` resets / `html`·`body` / `[data-theme]` / `*:focus-visible` / the scrollbar family / `input[type="number"]`·`select`)—they are a **deliberate shared baseline** that plugins rely on (and may override). Precisely because they exist, **your anchorless selector will hit them**: write `button { }` and the host's buttons plus every other plugin's buttons change with it.
759
759
 
760
- **Migration**: **zero instances today**—a full re-check of the 18 official plugins plus the in-repo fixtures (the "anchorless S2 / cross-party S3" columns of `npm run audit:plugin-prefix -- --all`) is **0** ⇒ **you have nothing to change**; this rule is **preventive**.
760
+ **Migration**: **zero instances today**—a full re-check of the official plugins plus the in-repo fixture (the "anchorless S2 / cross-party S3" columns of `npm run audit:plugin-prefix -- --all`) is **0** ⇒ **you have nothing to change**; this rule is **preventive**.
761
761
 
762
762
  > 🔧 **Maintainer note (authors may skip)**: the rule text (R0 scope / R1 host baseline / R2 / R3) plus the decision formulas and negative controls live in `docs/02-Electron架构/E6_插件生态与发布/01-插件独立构建/样式命名空间归一化/32-任务-选择器形态轴门禁与落地.md`; the host side is guarded by criteria ⑩⑪ of `scripts/check-css-namespace.mjs` (plus the runtime mirror on axis ④ of the probe), and the plugin side by the **fourth and fifth criteria** of the SDK's `check-css-namespace` leg (`checks/selector-form.ts` for S2/S3, and `checks/keyframe-refs.ts` for dangling keyframe references—the latter in place since **2026-09-18**, SDK `≥ 0.1.37`).
763
763
 
@@ -62,7 +62,7 @@ The `README.md` in the plugin root directory is displayed in the **"Details" tab
62
62
 
63
63
  ## 6. Live exemplars (copy them and you can't go wrong)
64
64
 
65
- - The READMEs of the 8 official plugins that already embed scene covers are ready-made models: `editor` / `file-tree` / `serial-monitor` / `settings` / `python` / `theme-terminal` / `theme-aurora-glass` / `lang-defaults` (plus the first real third-party plugin, `hello-linkdesk`). The `![…](resources/cover.svg)` at the top of their READMEs is the standard way to write a cover.
65
+ - The READMEs of the 8 official plugins that already embed scene covers are ready-made models: `editor` / `file-tree` / `serial-monitor` / `settings` / `python` / `theme-terminal` / `theme-aurora-glass` / `lang-defaults`. The `![…](resources/cover.svg)` at the top of their READMEs is the standard way to write a cover.
66
66
  - In-page `<video>` / cover link-out examples: the serial-monitor README's git history commits `2f9a52c6b` (real in-page playback) and `8c9d71551` (fullscreen fix) each carry a complete `<video>` / `<a><img></a>` example from the manual testing of that moment, reverted once verified — look at those two commits if you want to copy a complete example.
67
67
 
68
68
  ---
@@ -11,7 +11,7 @@
11
11
 
12
12
  ```
13
13
  E:\linkdesk-plugins\
14
- ├─ official\ ← your own plugins (the 18 official ones + later new plugins)
14
+ ├─ official\ ← your own plugins (the official ones + later new plugins)
15
15
  │ ├─ file-tree\
16
16
  │ └─ settings\
17
17
  └─ third-party\ ← other people's plugins (cloned to study / fork)
@@ -62,7 +62,7 @@ Benchmarked against the empirically verified VS Code position (`ms-vscode.cpptoo
62
62
 
63
63
  **Where you clone a plugin project and what the directory is called have no effect on plugin identity** — a plugin repo is self-contained, and the shell only recognizes the Release URL and the catalog; it **does not recognize local paths at all**. ⇒ The local directory structure can be rearranged at any time, with zero risk.
64
64
 
65
- Live evidence: the source repos of the two plugins `hello-linkdesk` and `first-run-setup` sit flat outside the container and still build, publish, get listed, and install/uninstall normally in the installed app. All 18 official plugins are the same way today (each in its own independent repo).
65
+ Live evidence: all 16 official plugins work this way today — each source repo sits flat outside the container (one independent repo per plugin) and still builds, publishes, gets listed, and installs/uninstalls normally in the installed app.
66
66
 
67
67
  ✅ **So "renaming a directory" is already safe today**: plugin identity = the top-level `pluginId` field (which must be declared explicitly and cannot be changed after publication), **and it has nothing to do with the directory name**.
68
68
 
@@ -117,7 +117,7 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
117
117
  | Criterion | Grade | Judged by | What happens |
118
118
  |:--|:--:|:--|:--|
119
119
  | The `set` name ∈ **segment ① host-only** | 🔴 **red** | SDK leg `linkdesk/no-unowned-context-key` | Your lint reports red by name; the **runtime second net** adds a `console.error` at the `contextKey:set` bridge — but 🔴 **the value is still written, not rejected** (see below) |
120
- | **New** flag's first segment isn't your `pluginId` | 🟡 yellow (advisory) | SDK leg | Reported with `suggested` = the same name with only the first segment swapped (`zzzFlag` → `my-plugin.zzzFlag`). 23 flags across the 18 official repos break this rule; the shell migrates them centrally — **write new ones by the rule** |
120
+ | **New** flag's first segment isn't your `pluginId` | 🟡 yellow (advisory) | SDK leg | Reported with `suggested` = the same name with only the first segment swapped (`zzzFlag` → `my-plugin.zzzFlag`). 23 flags across the official repos break this rule; the shell migrates them centrally — **write new ones by the rule** |
121
121
  | The `set` name ∈ **segment ② convention face** | 🟠 **not judged** | Registered only | Legal, but see above: that's the gear menu's spot — don't overwrite it |
122
122
 
123
123
  > **Why "taking a host-only flag" is red while "missing your prefix" is only yellow**: taking a host-only flag does **real harm** (it replaces host state, and neither side errors); whereas "missing the prefix" has 23 counterexamples in existing code, so a blanket rule would break shipped plugins on the spot. Different grades = different tolerance, not "the more important rule is written stricter".
@@ -473,7 +473,7 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
473
473
 
474
474
  🔴 **为什么这是建议而不是强制**:**i18n 键可以合法住在应用级字典**。官方 `settings` 插件的 254 处 `t()` 调用,**一个键都不在它自己的仓里**(全住 `lang-defaults` 的 `zh.json` / `en.json`)。插件仓里只有你自己的 `i18n/*.json`——**看不到宿主的字典,也看不到其余插件**,所以「你的键撞了别人」在你自己仓里**永远判不出来**。把它做成拦截 = 必然误报,而误报会让真正该拦的规则失效。⇒ **它是黄灯,不是红灯。**
475
475
 
476
- **今天真实存在多少重合**(如实告诉你,不夸大):官方 18 个插件声明的键(414 个)与 `lang-defaults` 的键有 **65 条重合**,其中 **3 条译文已经不一致**——例如 `命令`,宿主给的是 `Command`,而 `serial-monitor` 给的是 `Commands`。**两条都写进同一本字典时,用户看到的究竟是哪一条,取决于插件加载顺序。**
476
+ **真实存在多少重合**(如实告诉你,不夸大——下面的数是**一次测量**,取当时官方 18 只的名单,不是活读数):官方插件声明了 **414 个键**,其中与 `lang-defaults` 的键 **65 条重合**,而这 65 条里 **3 条译文已经不一致**——例如 `命令`,宿主给的是 `Command`,而 `serial-monitor` 给的是 `Commands`。**两条都写进同一本字典时,用户看到的究竟是哪一条,取决于插件加载顺序。**
477
477
 
478
478
  ⚠️ **运行时行为**:发生覆盖时宿主会 `console.warn` 出声,点明**键名 + 语言 + 写入者**:
479
479
 
@@ -781,7 +781,7 @@ useEffect(() => {
781
781
 
782
782
  **四条边界**:① 只管**第一次打开**——已有标签页仍聚焦、面板开着再点仍按开关键关掉,打开之后想换形态照旧走「在主窗口中打开」/「在悬浮面板中打开」两条老路;② `formKey` 与 `defaultForm` **互斥**(同时写 ⇒ schema 校验红:一个形态两个来源);③ `formKey` 写错字 / 没注册那个键 ⇒ 降级 `defaultForm`(都没有 = 原行为)+ 出声一条 warn——**不静默失效**;④ 声明 `"defaultForm": "tab"` 但插件没有标签页形态(`appearsIn.tabBar` + `entry`)⇒ 落回悬浮面板,不静默无动作。
783
783
 
784
- **首批声明者 = settings**(`core.openSettings` Ctrl+, 弹面板,`settings.openForm` 在「设置插件」组里让用户改);**第二声明者验证载体 = `floating-panel-demo`** 测试插件(标签页型视图,端到端验证替换 + 右键回程 + 卸载 no-op)。
784
+ **当前唯一声明者 = settings**(`core.openSettings` Ctrl+, 弹面板,`settings.openForm` 在「设置插件」组里让用户改)。机制本身是通用的,且已端到端验证过(替换 + 右键回程 + 卸载 no-op)——你随时可以成为第二个声明者。
785
785
 
786
786
  ---
787
787
 
@@ -51,8 +51,8 @@ my-plugin/
51
51
 
52
52
  | 代码根 | 位置 | 形态 | HMR | 谁住这里 |
53
53
  |------|------|------|:--:|------|
54
- | **插件自己的仓** | GitHub `Encaron/linkdesk-plugin-<id>`(本地克隆落在容器目录 `E:\linkdesk-plugins\official\<id>\`) | 源码 + SDK build(`npm run build` → `<id>.linkdesk-plugin`) | ✅(`linkdesk-plugin-sdk dev`) | **18 只发货插件全部**——一只一个仓,源码真相源只此一处 |
55
- | **壳仓夹具** | `<壳仓>/plugins/<id>/`(`env.appPluginsDir`) | 源码 + Vite 即时编译 | ✅(`npm run dev` 热更) | 只剩两只**开发夹具**:`panel-demo` / `floating-panel-demo`(不发货、不进 zip) |
54
+ | **插件自己的仓** | GitHub `Encaron/linkdesk-plugin-<id>`(本地克隆落在容器目录 `E:\linkdesk-plugins\official\<id>\`) | 源码 + SDK build(`npm run build` → `<id>.linkdesk-plugin`) | ✅(`linkdesk-plugin-sdk dev`) | **全部发货插件**(今天 16 只)——一只一个仓,源码真相源只此一处 |
55
+ | **壳仓夹具** | `<壳仓>/plugins/<id>/`(`env.appPluginsDir`) | 源码 + Vite 即时编译 | ✅(`npm run dev` 热更) | 只剩一只**开发夹具**:`panel-demo`(不发货、不进 zip) |
56
56
  | **安装态** | `{userData}/plugins/<id>/` | zip 解出的预构建 bundle | ❌(改包需重 build + 重装/重物化) | 用户机器上所有已装插件 |
57
57
 
58
58
  > 🔴 **为什么发货插件的源码不能两边都留一份**:一旦壳仓与插件仓各有一份,改了这头那头不变,而**没有任何门禁能发现分叉**(内容指纹门禁只管 zip 内容,不管源码)⇒ 真相源必须唯一。壳仓留下的两样是**产物**(`bundled-plugins/*.linkdesk-plugin`)与**文档档案**,不是源码。
@@ -60,7 +60,7 @@ my-plugin/
60
60
  > **真机环例外(作者 dev):** 安装态改包需「重 build + 重装/重物化」在**作者每次真机验证**场景 = WPF v2 一次性循环痛苦。真机环自动化它——SDK 秒级重建 + **直写** `{userData}/plugins/<id>`(同盘覆盖语义,reload 即生效)成循环,作者仍不碰壳。分发 zip 的「不自改 bundle」纪律不变(那是给终用户的包)。设计档案 → [04-作者真机调试环.md](https://github.com/Encaron/linkdesk/blob/electron/docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/04-作者真机调试环.md)。
61
61
 
62
62
  > **卸载语义(2026-09-05 后):** 安装态插件卸载 = **删 `{userData}/plugins/<id>/` 目录 + 账本销账**(不再是 `.disabled/` 移入);只有 repo 源码树里的 app 插件卸载才移 `plugins/.disabled/` 坟场(可 reinstall 恢复)。账本 `installed-plugins.json` 唯一 owner = 渲染进程 PluginInstallService,boot 只读它的 `removed` 标记防误恢复。
63
- > 🔵 **核对结论(`.disabled/` 坟场还有没有消费者)**:**机制仍在、当前无对象**。消费者是活的——`src/pluginLoader/loader.ts` 读它(`reinstallPlugin` / 卸载 toast 的「撤销」/ 跨重启孤儿清理都以 `env.appPluginsDir/.disabled` 为唯一权威面)。但 `env.appPluginsDir` = 壳仓 `plugins/`,而 18 只发货插件已外移 ⇒ 那里只剩两只夹具,**没有「在 repo 源码树里被卸载的 app 插件」了**。⇒ 机制**保留**(它是仓内插件 dev 路径的一部分,删它要动 loader 三处 + 主进程扫描面,风险大于收益),但**不要**再把它当成发货插件的可撤销卸载通道。
63
+ > 🔵 **核对结论(`.disabled/` 坟场还有没有消费者)**:**机制仍在、当前无对象**。消费者是活的——`src/pluginLoader/loader.ts` 读它(`reinstallPlugin` / 卸载 toast 的「撤销」/ 跨重启孤儿清理都以 `env.appPluginsDir/.disabled` 为唯一权威面)。但 `env.appPluginsDir` = 壳仓 `plugins/`,而发货插件已外移 ⇒ 那里只剩一只夹具,**没有「在 repo 源码树里被卸载的 app 插件」了**。⇒ 机制**保留**(它是仓内插件 dev 路径的一部分,删它要动 loader 三处 + 主进程扫描面,风险大于收益),但**不要**再把它当成发货插件的可撤销卸载通道。
64
64
 
65
65
  ---
66
66
 
@@ -759,7 +759,7 @@ button { border: none; }
759
759
  共享基线**,插件一直在依赖它们(也可以覆写)。正因为它们存在,**你的无锚选择器一定会命中它们**:
760
760
  你写 `button { }`,宿主的按钮、其他插件的按钮,全都会跟着变。
761
761
 
762
- **迁移**:**今天 0 存量**——官方 18 只插件 + 壳内夹具全量复核(`npm run audit:plugin-prefix -- --all`
762
+ **迁移**:**今天 0 存量**——官方插件 + 壳内夹具全量复核(`npm run audit:plugin-prefix -- --all`
763
763
  的「无锚 S2 / 跨方 S3」两列)都是 **0** ⇒ **你不需要改任何东西**;这条规矩是**预防性**的。
764
764
 
765
765
  > 🔧 **维护者注(作者可跳过)**:规则正文(R0 口径 / R1 宿主基线 / R2 / R3)与判定式、负控见
@@ -62,7 +62,7 @@
62
62
 
63
63
  ## 六、活的样板(照抄不会错)
64
64
 
65
- - 官方 8 只已嵌场景封面的插件 README = 现成范本:`editor` / `file-tree` / `serial-monitor` / `settings` / `python` / `theme-terminal` / `theme-aurora-glass` / `lang-defaults`(另有首个第三方真插件 `hello-linkdesk`)。看它们 README 顶部那张 `![…](resources/cover.svg)` 就是封面标准写法。
65
+ - 官方 8 只已嵌场景封面的插件 README = 现成范本:`editor` / `file-tree` / `serial-monitor` / `settings` / `python` / `theme-terminal` / `theme-aurora-glass` / `lang-defaults`。看它们 README 顶部那张 `![…](resources/cover.svg)` 就是封面标准写法。
66
66
  - 页内 `<video>` / 封面外链写法:串口监视器 README 的 git 历史 commit `2f9a52c6b`(页内真播)与 `8c9d71551`(全屏修复)各带一段当时手测用的完整 `<video>` / `<a><img></a>` 示例,验完即撤——要抄完整写法可看那两次提交。
67
67
 
68
68
  ---
@@ -11,7 +11,7 @@
11
11
 
12
12
  ```
13
13
  E:\linkdesk-plugins\
14
- ├─ official\ ← 你自己的插件(官方 18 只 + 后续新插件)
14
+ ├─ official\ ← 你自己的插件(官方那些 + 后续新插件)
15
15
  │ ├─ file-tree\
16
16
  │ └─ settings\
17
17
  └─ third-party\ ← 别人的插件(clone 下来学习/二开的)
@@ -62,7 +62,7 @@ E:\linkdesk-plugins\
62
62
 
63
63
  **插件工程 clone 到哪、目录叫什么,都不影响插件身份**——插件仓是自足的,壳只认 Release URL 与 catalog,**不认本地路径**。⇒ 本地目录结构随时可重排,零风险。
64
64
 
65
- 活证据:`hello-linkdesk` 与 `first-run-setup` 两只插件的源码仓平铺在容器外,照样构建、发布、上架、被安装版正常装卸。官方 18 只现在也全是这样(各自独立一仓)。
65
+ 活证据:官方 16 只现在全是这样——每只的源码仓平铺在容器外(各自独立一仓),照样构建、发布、上架、被安装版正常装卸。
66
66
 
67
67
  ✅ **所以「改目录名」这件事今天已经安全**:插件身份 = 顶层 `pluginId` 字段(必须显式声明,发布后不可改),**与目录名无关**。
68
68
 
@@ -117,7 +117,7 @@ node_modules/@linkdesk/plugin-sdk/schemas/host-reserved.json
117
117
  | 判据 | 分级 | 谁判 | 会发生什么 |
118
118
  |:--|:--:|:--|:--|
119
119
  | `set` 的名字 ∈ **段① 宿主专用** | 🔴 **红** | SDK 腿 `linkdesk/no-unowned-context-key` | 作者仓里 lint 报红点名;**运行时第二道网**在 `contextKey:set` 过桥处补一条 `console.error`,但 🔴 **值照写、不拒绝**(见下) |
120
- | **新**旗子第一段不是本仓 `pluginId` | 🟡 黄(建议) | SDK 腿 | 报点带 `suggested` = 只换第一段的新名(`zzzFlag` → `my-plugin.zzzFlag`)。存量官方 18 仓有 23 个旗子不合此规,迁移由壳侧统一执行——**新旗子请照规矩写** |
120
+ | **新**旗子第一段不是本仓 `pluginId` | 🟡 黄(建议) | SDK 腿 | 报点带 `suggested` = 只换第一段的新名(`zzzFlag` → `my-plugin.zzzFlag`)。存量官方仓有 23 个旗子不合此规,迁移由壳侧统一执行——**新旗子请照规矩写** |
121
121
  | `set` 的名字 ∈ **段② 约定面** | 🟠 **不判** | 只登记 | 合法,但见上:那是齿轮菜单的位置,别去覆盖 |
122
122
 
123
123
  > **为什么"占宿主专用"是红、"没带自己前缀"只是黄**:占专用旗子有**真害**(顶替宿主状态,两侧都不报错);而"没带前缀"在存量里有 23 个反例,一刀切会把既有插件当场弄坏。分级不同 = 容忍度不同。
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.34",
4
- "description": "LinkDesk 插件作者文档(离线包)——`docs/03-插件制造` 的发布产物:从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
3
+ "version": "0.1.35",
4
+ "description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [
7
7
  "docs",