create-linkdesk-plugin 0.1.9 → 0.1.11

package/README.md

@@ -21,7 +21,7 @@ The generated project has **the same shape as an official plugin** — README /
 ```
 my-cool-plugin/
 ├── plugin.json           # plugin manifest (JSONC: comments + trailing commas allowed, sectioned example fields, VS Code $schema validation)
-├── package.json          # scripts: dev / dev:real / build / publish / validate / lint / verify / test
+├── package.json          # deps: @linkdesk/ui (resolves the shell's current version line) · scripts: dev / dev:real / build / publish / validate / lint / verify / test
 ├── tsconfig.json         # jsx: react-jsx + window.linkdesk.* types (@linkdesk/plugin-sdk)
 ├── AGENTS.md             # what this project is + the iron rules + where the docs are (for your AI assistant)
 ├── .gitignore            # node_modules / dist / *.linkdesk-plugin

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-linkdesk-plugin",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "LinkDesk 插件脚手架——`npm create linkdesk-plugin@latest my-cool-plugin` 一行生成你的第一个插件项目（对标 yo code）。",
   "type": "module",
   "bin": {

package/template/README.md

@@ -28,7 +28,7 @@ You do not need to pre-create empty folders (git does not track them). **Create
 | `src/styles/` | **Multiple** CSS files — keep them together here (a single file next to the entry is fine too) | When needed |
 | `src/__tests__/` | Unit tests (run `npm i -D vitest` yourself if you want them — the scaffold does not preinstall test tooling) | When needed |
 
-> 🔴 **Shared things do not belong here** — components/hooks reused across plugins come from `@linkdesk/ui` (the public package the shell provides). **Do not write a second copy inside your plugin.** Only logic that belongs to this plugin stays local.
+> 🔴 **Shared things do not belong here** — components/hooks reused across plugins come from `@linkdesk/ui` (the public package the shell provides; it is already declared in `package.json` as `"latest"`, which resolves to the shell's current version line when you install — pin it to a specific shell version if you need a floor). The shell supplies that one instance at runtime, so **do not import its css** and **do not write a second copy inside your plugin**. Only logic that belongs to this plugin stays local.
 > 🔴 **Assets always live in `resources/` — no loose images in the plugin root.** What gets into the install package is what is **referenced by the README** or **declared by `icon` / `marketIcon`**; the directory name itself has no magic.
 
 ## Three rules for this plugin

package/template/package.json

@@ -4,6 +4,9 @@
   "private": true,
   "description": "{{displayName}}——LinkDesk 插件（由 create-linkdesk-plugin 生成）",
   "type": "module",
+  "dependencies": {
+    "@linkdesk/ui": "latest"
+  },
   "scripts": {
     "dev": "linkdesk-plugin-sdk dev",
     "dev:real": "linkdesk-plugin-sdk dev --real",

package/template/plugin.json

@@ -11,6 +11,8 @@
   // ── 插件身份 ──
   // 🔴 插件 ID：**显式声明**。它是安装目录名 / 卸载墓碑 / 更新对账的唯一键，**发布后永不可变**。
   // 它与插件所在的目录名**无关**（目录可以随便改）——所以别拿目录名当它的替身。
+  // ⚠️ 且**不得以 `ldk-` 开头**：`ldk-` 是宿主与共享组件的命名空间，而你在 index.css 里的
+  //    类名前缀正是由它派生（`<pluginId>-你的类名`）——以 `ldk-` 开头 = 把自己的名字落进宿主空间。
   "pluginId": "{{pluginName}}",
   "name": "{{displayName}}", // 显示名——标签页 / 插件详情等 UI 出现处
   "version": "0.1.0", // 语义化版本 x.y.z——市场更新比较靠它；+1 时务必同笔补 CHANGELOG.md 的新段

package/template/src/index.css

@@ -1,30 +1,33 @@
-/* {{displayName}} 样式示例（`npm run lint` 会照着下面三条查）。
-   三条纪律：
-   · 颜色一律 var(--xxx)，禁硬编码 hex——用户换主题时你的插件要跟着变；
-   · 字号一律 var(--font-size-*)——用户调全局字号时它才跟着缩放，裸 px 不会；
-   · padding / margin / gap 走 4px 节奏（4 的倍数）。 */
-
-.starter {
-  padding: 24px;
-  font-family: inherit;
-}
-
-.starter__title {
-  margin: 0 0 8px;
-  color: var(--text);
-}
-
-.starter__text {
-  margin: 0 0 4px;
-  color: var(--text-muted);
-}
-
-.starter__hint {
-  margin: 0;
-  color: var(--text-muted);
-  font-size: var(--font-size-xs);
-}
-
-.starter__hint code {
-  font-family: var(--font-mono, monospace);
-}
+/* {{displayName}} 样式示例（`npm run lint` 会照着下面四条查）。
+   四条纪律：
+   · 颜色一律 var(--xxx)，禁硬编码 hex——用户换主题时你的插件要跟着变；
+   · 字号一律 var(--font-size-*)——用户调全局字号时它才跟着缩放，裸 px 不会；
+   · padding / margin / gap 走 4px 节奏（4 的倍数）；
+   · 类名一律以 {{pluginName}}- 开头——插件视图里宿主、共享组件与**所有已加载插件**的
+     CSS 在同一张样式表里，裸类名（如 .starter）是全局标识符，会和别人的同名规则
+     互相覆盖（不报错、只是长得不对）。 */
+
+.{{pluginName}}-starter {
+  padding: 24px;
+  font-family: inherit;
+}
+
+.{{pluginName}}-starter__title {
+  margin: 0 0 8px;
+  color: var(--text);
+}
+
+.{{pluginName}}-starter__text {
+  margin: 0 0 4px;
+  color: var(--text-muted);
+}
+
+.{{pluginName}}-starter__hint {
+  margin: 0;
+  color: var(--text-muted);
+  font-size: var(--font-size-xs);
+}
+
+.{{pluginName}}-starter__hint code {
+  font-family: var(--font-mono, monospace);
+}

package/template/src/index.tsx

@@ -1,35 +1,35 @@
-/**
- * {{displayName}}——LinkDesk 插件主视图（由 create-linkdesk-plugin 生成）。
- *
- * 视图插件契约（作者文档 01-plugin-api-contract.md）：壳以 { isActive, tabId?, sourceId? }
- * 渲染本文件 default 导出的组件：
- *   - isActive  本标签当前是否聚焦。keep-alive 下非聚焦标签仍在渲染，isActive 只用于
- *               gate「聚焦才跑」的副作用（如自动保存），切勿用它整块 blank 掉内容。
- *   - tabId     本标签页 id。
- *   - sourceId  上下文数据（文件路径 / 数据源等），编辑器类插件用它定位内容。
- *
- * 样式：LinkDesk 主题色一律走 CSS 变量 var(--xxx)（见 index.css 示例），禁硬编码 hex。
- * 文案：用 t() 读——key 就是中文原文，英文译文放 i18n/en.json（见作者文档 05-ui-conventions.md）。
- * 壳已 external react/react-dom/react-i18next/i18next——构建不会打进包，插件工程无需 npm i 它们。
- */
-
-import { useTranslation } from "react-i18next";
-import "./index.css";
-
-export default function HelloPlugin(_props: { isActive?: boolean; tabId?: string; sourceId?: string }) {
-  const { t } = useTranslation();
-
-  return (
-    <div className="starter">
-      <h2 className="starter__title">{t("插件跑起来了 ✨")}</h2>
-      <p className="starter__text">{t("这是你的第一个 LinkDesk 插件。")}</p>
-      <p className="starter__hint">
-        <code>src/index.tsx</code> {t("是插件本体——改它，浏览器预览即时刷新。")}
-      </p>
-      <p className="starter__hint">
-        <code>npm run build</code> {t("打包出分发文件，可装进 LinkDesk 或发布到市场。")}
-      </p>
-      <p className="starter__hint">{t("目录该放哪、发布怎么做，都写在 README.md 里。")}</p>
-    </div>
-  );
-}
+/**
+ * {{displayName}}——LinkDesk 插件主视图（由 create-linkdesk-plugin 生成）。
+ *
+ * 视图插件契约（作者文档 01-plugin-api-contract.md）：壳以 { isActive, tabId?, sourceId? }
+ * 渲染本文件 default 导出的组件：
+ *   - isActive  本标签当前是否聚焦。keep-alive 下非聚焦标签仍在渲染，isActive 只用于
+ *               gate「聚焦才跑」的副作用（如自动保存），切勿用它整块 blank 掉内容。
+ *   - tabId     本标签页 id。
+ *   - sourceId  上下文数据（文件路径 / 数据源等），编辑器类插件用它定位内容。
+ *
+ * 样式：LinkDesk 主题色一律走 CSS 变量 var(--xxx)（见 index.css 示例），禁硬编码 hex。
+ * 文案：用 t() 读——key 就是中文原文，英文译文放 i18n/en.json（见作者文档 05-ui-conventions.md）。
+ * 壳已 external react/react-dom/react-i18next/i18next——构建不会打进包，插件工程无需 npm i 它们。
+ */
+
+import { useTranslation } from "react-i18next";
+import "./index.css";
+
+export default function HelloPlugin(_props: { isActive?: boolean; tabId?: string; sourceId?: string }) {
+  const { t } = useTranslation();
+
+  return (
+    <div className="{{pluginName}}-starter">
+      <h2 className="{{pluginName}}-starter__title">{t("插件跑起来了 ✨")}</h2>
+      <p className="{{pluginName}}-starter__text">{t("这是你的第一个 LinkDesk 插件。")}</p>
+      <p className="{{pluginName}}-starter__hint">
+        <code>src/index.tsx</code> {t("是插件本体——改它，浏览器预览即时刷新。")}
+      </p>
+      <p className="{{pluginName}}-starter__hint">
+        <code>npm run build</code> {t("打包出分发文件，可装进 LinkDesk 或发布到市场。")}
+      </p>
+      <p className="{{pluginName}}-starter__hint">{t("目录该放哪、发布怎么做，都写在 README.md 里。")}</p>
+    </div>
+  );
+}