@linkdesk/plugin-docs 0.1.67 → 0.1.68

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.
@@ -24,6 +24,37 @@ Break any of these and your plugin **installs but then breaks** (it can even tak
24
24
 
25
25
  ---
26
26
 
27
+ ## Before You Add Anything — Three Placement Questions (shell, shared component, or plugin?)
28
+
29
+ **What to do**: for every new control / action / utility function, **answer these three questions before you write code** — getting the layer wrong costs you building it twice and then moving it.
30
+
31
+ ```
32
+ Q1 Whose data does it consume?
33
+ └ Host declarations (plugin list / file-association contribution / settings / theme · icon · keybinding) ⇒ shell or shared component, regardless of how many consumers exist today ⇒ done
34
+ └ The plugin's own private data ⇒ go to Q2
35
+ Q2 Will it be rendered in ≥2 places / used by other plugins?
36
+ └ Yes ⇒ an @linkdesk/ui shared component
37
+ └ No ⇒ plugin-private (only now is private allowed; add a comment saying why it is private)
38
+ Q3 Is it an action (something AI / CLI / another plugin must be able to trigger)?
39
+ └ Yes ⇒ a shell command + an @linkdesk/plugin-sdk helper (⛔ never a plugin-internal function / event)
40
+ ```
41
+
42
+ **How to know you got it right**: look it up in the table.
43
+
44
+ | Nature of the capability | Where it belongs | Precedent / counter-example |
45
+ |:--|:--|:--|
46
+ | A view / control consuming host declarations | **Shell or shared component** | ✅ `PluginCard` (the host's plugin list); ❌ the open-with panel (originally lived inside a plugin) |
47
+ | A UI block rendered in ≥2 places | **Shared component** | ✅ `Button`, `PluginCard` |
48
+ | Serves only the plugin's own private data, rendered only by that plugin | **Plugin-private** (comment: "private · reason") | ✅ `BinaryNotice` (presenting a decision belongs to the plugin being backed up) |
49
+ | An action AI / CLI / another plugin must trigger | **Shell command + SDK helper** | ✅ the `workbench.action.*` family |
50
+ | A pure utility function (normalization, parsing) | Shell core or a toolkit (**defined once**) | ✅ `normalizeExt` (⛔ never copy one into a plugin) |
51
+
52
+ > 🔴 **"Put it in the plugin first, share it once a second consumer shows up" is not an option** — it is the reversed reading this project has abolished (D10 is about *not pre-building shared pieces for needs that do not exist yet*; it says nothing about *which layer an already-needed capability belongs to*).
53
+ > The **presentation** of host declarations (the open-with panel, the settings renderer, plugin cards) always comes from the shell or a shared component ⇒ plugins only **declare contribution points**, they never render someone else's list.
54
+ > Details → [05-ui-conventions](05-ui-conventions.md) (shared components and context menus) + [19-component-cheatsheet](19-component-cheatsheet.md).
55
+
56
+ ---
57
+
27
58
  ## Step 1: Generate the Project Skeleton
28
59
 
29
60
  **What to do**
@@ -24,6 +24,37 @@
24
24
 
25
25
  ---
26
26
 
27
+ ## 加东西之前——落位三问(这东西该住壳、共享件,还是插件?)
28
+
29
+ **做什么**:任何新控件 / 新动作 / 新工具函数,**先走这三问再动笔**——放错层的代价是「做两遍,再搬一次」。
30
+
31
+ ```
32
+ Q1 它消费谁的数据?
33
+ └ 宿主声明(插件清单 / 文件关联贡献点 / 配置项 / 主题 · 图标 · 键位) ⇒ 壳或共享件,与「现在有几个消费者」无关 ⇒ 结束
34
+ └ 插件自己的私有数据 ⇒ 进 Q2
35
+ Q2 它要不要被 ≥2 处渲染 / 被别的插件用到?
36
+ └ 是 ⇒ @linkdesk/ui 共享件
37
+ └ 否 ⇒ 插件私有(此时才允许私有;并写「私有」的理由注释)
38
+ Q3 它是不是一个动作(要能被 AI / CLI / 别的插件触发)?
39
+ └ 是 ⇒ 壳命令 + @linkdesk/plugin-sdk helper(⛔ 别做成插件内部函数 / 事件)
40
+ ```
41
+
42
+ **怎么知道做对了**:查表。
43
+
44
+ | 能力的性质 | 该住哪 | 先例 / 反例 |
45
+ |:--|:--|:--|
46
+ | 消费宿主声明的视图 / 控件 | **壳 或 共享件** | ✅ `PluginCard`(宿主清单);❌ 打开方式面板(原住在插件里) |
47
+ | 被 ≥2 处渲染的 UI 块 | **共享件** | ✅ `Button`、`PluginCard` |
48
+ | 只服务本插件私有数据、只被本插件渲染 | **插件私有**(注释写「私有 · 理由」) | ✅ `BinaryNotice`(判定的呈现归被兜底的插件) |
49
+ | 要能被 AI / CLI / 别插件触发的动作 | **壳命令 + SDK helper** | ✅ `workbench.action.*` 家族 |
50
+ | 纯函数工具(归一化、解析) | 壳 core 或工具包(**一处定义**) | ✅ `normalizeExt`(⛔ 别在插件里抄一份) |
51
+
52
+ > 🔴 **「先放插件、等第二个再共享」不是一条路**——它是本项目已废止的反向用法(D10 管的是「别为还不存在的需求提前造共享件」,不管「已经有人要的能力该住哪层」)。
53
+ > 宿主声明的**呈现**(打开方式面板、设置页渲染器、插件卡)一律由壳或共享件提供 ⇒ 插件只**声明贡献点**,⛔ 不在插件里渲染别人的清单。
54
+ > 细节点哪一篇 → [05-插件UI写法规约](05-插件UI写法规约.md)(共享件与右键菜单)+ [19-组件速查](19-组件速查.md)。
55
+
56
+ ---
57
+
27
58
  ## 第 1 步:生成项目骨架
28
59
 
29
60
  **做什么**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@linkdesk/plugin-docs",
3
- "version": "0.1.67",
3
+ "version": "0.1.68",
4
4
  "description": "LinkDesk 插件作者文档(离线包)——作者面文档树的发布产物(英文 `docs/03-plugin-authoring` 在包根、中文 `docs/03-插件制造` 在 `zh/`):从零学会做一个插件(导览 / 三档动线 / 区域地图 / 组件速查 / 主题 / API 入口)。",
5
5
  "type": "module",
6
6
  "files": [