create-linkdesk-plugin 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Encaron
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,39 +1,55 @@
-# create-linkdesk-plugin
-
-LinkDesk 插件脚手架——一行命令生成你的第一个插件项目（对标 `yo code`）。
-
-```bash
-npm create linkdesk-plugin my-cool-plugin
-```
-
-不带名字则交互式询问：
-
-```bash
-npm create linkdesk-plugin
-```
-
-## 生成什么
-
-```
-my-cool-plugin/
-├── plugin.json          # 插件清单（JSONC：可注释/尾逗号，字段分节示范，VS Code $schema 校验）
-├── package.json         # scripts: dev / build / validate；依赖 @linkdesk/plugin-sdk
-├── tsconfig.json        # jsx: react-jsx + window.linkdesk.* 类型（@linkdesk/plugin-sdk）
-├── .vscode/settings.json # plugin.json 按 jsonc 识别（注释不标红）
-├── src/
-│   ├── index.tsx        # 视图组件 default 导出——壳以 { isActive, tabId?, sourceId? } 渲染
-│   └── index.css        # 样式示例——主题色走 var(--xxx)
-└── i18n/
-    └── en.json
-```
-
-然后：
-
-```bash
-cd my-cool-plugin
-npm install
-npm run build     # 产出 <pluginId>.linkdesk-plugin——可装进 LinkDesk / 发布
-```
-
-> 说明：插件作者工作流（dev 热预览 / build / 发布全链路）的完整文档见
-> [00-第三方作者旅程](../../docs/02-Electron架构/E6_插件生态与发布/05-文档与发布/00-第三方作者旅程.md)。
+# create-linkdesk-plugin
+
+LinkDesk 插件脚手架——一行命令生成你的第一个插件项目（对标 `yo code`）。
+
+```bash
+npm create linkdesk-plugin my-cool-plugin
+```
+
+不带名字则交互式询问：
+
+```bash
+npm create linkdesk-plugin
+```
+
+## 生成什么
+
+生成物的形状**与官方插件一致**——README / CHANGELOG / resources / i18n 一个不少：
+
+```
+my-cool-plugin/
+├── plugin.json           # 插件清单（JSONC：可注释/尾逗号，字段分节示范，VS Code $schema 校验）
+├── package.json          # scripts: dev / dev:real / build / publish / validate / lint
+├── tsconfig.json         # jsx: react-jsx + window.linkdesk.* 类型（@linkdesk/plugin-sdk）
+├── .gitignore            # node_modules / dist / *.linkdesk-plugin
+├── README.md             # 说明——市场「详情」页签的数据源 + 目录契约表
+├── CHANGELOG.md          # 更新日志——市场「更改日志」页签的数据源
+├── .vscode/settings.json # plugin.json 按 jsonc 识别（注释不标红）
+├── resources/
+│   └── icon.svg          # 图标占位图——换成你自己的
+├── src/
+│   ├── index.tsx         # 视图组件 default 导出——壳以 { isActive, tabId?, sourceId? } 渲染
+│   └── index.css         # 样式示例——颜色 / 字号走 var(--xxx)，间距走 4px 节奏
+└── i18n/
+    └── en.json           # 英文译文（key = 中文原文；不建 zh.json）
+```
+
+> **不预建空文件夹**（git 本来也不记录空目录）——「东西该放哪」写在生成的 `README.md` 的目录契约表里，
+> 用文字说清比用空夹暗示更清楚。
+
+## 命令
+
+```bash
+cd my-cool-plugin
+npm install
+
+npm run dev        # 浏览器热重载预览（改代码即时生效）
+npm run dev:real   # 真机环——直写 {userData}/plugins/<id> + CDP reload（真 IPC / 串口 / LSP 类插件用）
+npm run validate   # 校验 plugin.json
+npm run build      # 产出 <pluginId>.linkdesk-plugin——可装进 LinkDesk / 发布
+npm run lint       # 门禁自检（硬编码颜色 / 字号 / 间距网格 / eslint 规则）
+npm run publish    # 一键发布（建 GitHub Release + 上传 + 更新 catalog）
+```
+
+> 说明：插件作者工作流（dev 热预览 / build / 发布全链路）的完整文档见
+> [00-第三方作者旅程](../../docs/02-Electron架构/E6_插件生态与发布/05-文档与发布/00-第三方作者旅程.md)。

package/index.js

@@ -1,111 +1,136 @@
-#!/usr/bin/env node
-/**
- * create-linkdesk-plugin——LinkDesk 插件脚手架 CLI（纯 Node，零依赖，对标 yo code）。
- *
- * 用法：
- *   npm create linkdesk-plugin my-cool-plugin   # 直接给名字（kebab-case，非交互）
- *   npm create linkdesk-plugin                  # 不带参数 → 交互式询问插件名
- *
- * 行为：把同目录 template/ 复制到 <cwd>/<name>，把占位符替换成真实值，打印下一步提示。
- * 占位符：{{pluginName}} {{displayName}} {{author}}（递归替换所有模板文件）。
- *
- * 生成产物契约：见 docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/01-create-linkdesk-plugin脚手架.md。
- */
-import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
-import { spawnSync } from "node:child_process";
-import { createInterface } from "node:readline";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const TEMPLATE_DIR = join(dirname(fileURLToPath(import.meta.url)), "template");
-
-/** kebab-case——同时满足插件 id / viewsContainers key / npm 包名惯例（SAFE_PLUGIN_ID 的形状子集） */
-const NAME_RE = /^[a-z][a-z0-9-]*$/;
-
-/** my-cool-plugin → My Cool Plugin */
-function toDisplayName(name) {
-  return name
-    .split("-")
-    .map((s) => (s ? s[0].toUpperCase() + s.slice(1) : s))
-    .join(" ");
-}
-
-/** 作者默认值 = git config user.name；读不到（无 git/无配置）→ "you"（作者生成后自改） */
-function gitUserName() {
-  try {
-    const r = spawnSync("git", ["config", "user.name"], { encoding: "utf8", timeout: 3000 });
-    const v = (r.stdout || "").trim();
-    return v || "you";
-  } catch {
-    return "you";
-  }
-}
-
-/** 交互式单问——返回去除首尾空白的答案 */
-function ask(question) {
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  return new Promise((resolve) => {
-    rl.question(question, (answer) => {
-      rl.close();
-      resolve(answer.trim());
-    });
-  });
-}
-
-function replacePlaceholders(file, values) {
-  let text = readFileSync(file, "utf8");
-  for (const [key, value] of Object.entries(values)) {
-    text = text.split(`{{${key}}}`).join(value);
-  }
-  writeFileSync(file, text);
-}
-
-/** 递归替换目录内全部文件（模板全是文本文件，无需跳过二进制） */
-function walkReplace(dir, values) {
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    const full = join(dir, entry.name);
-    if (entry.isDirectory()) walkReplace(full, values);
-    else replacePlaceholders(full, values);
-  }
-}
-
-async function main() {
-  let name = (process.argv[2] || "").trim();
-  if (!name) {
-    name = await ask("插件名（kebab-case，如 my-cool-plugin）: ");
-  }
-  name = name.trim();
-  if (!NAME_RE.test(name)) {
-    console.error(`✖ 插件名须为 kebab-case（小写字母/数字/连字符），收到：${JSON.stringify(name)}`);
-    process.exit(1);
-  }
-
-  const target = join(process.cwd(), name);
-  if (existsSync(target) && readdirSync(target).length > 0) {
-    console.error(`✖ ${name}/ 已存在且非空——换个名字，或清空后重跑`);
-    process.exit(1);
-  }
-
-  mkdirSync(target, { recursive: true });
-  cpSync(TEMPLATE_DIR, target, { recursive: true });
-
-  const values = { pluginName: name, displayName: toDisplayName(name), author: gitUserName() };
-  walkReplace(target, values);
-
-  console.log("");
-  console.log(`✔ ${name}/ 已创建`);
-  console.log("");
-  console.log("  接下来：");
-  console.log(`    cd ${name}`);
-  console.log("    npm install");
-  console.log("    npm run validate   # 校验 plugin.json（$schema / 字段 / i18n 文件）");
-  console.log("    npm run build      # 产出 <pluginId>.linkdesk-plugin，可装进 LinkDesk / 发布");
-  console.log("");
-  console.log("  编辑 plugin.json 的 name / description / author，src/index.tsx 是你的插件本体。");
-  console.log("  更多插件能力（侧栏视图 / 命令 / 设置 / 协议……）见 docs/03-插件制造/ 与 plugin.schema.json。");
-}
-
-main().catch((err) => {
-  console.error(err);
-  process.exit(1);
-});
+#!/usr/bin/env node
+/**
+ * create-linkdesk-plugin——LinkDesk 插件脚手架 CLI（纯 Node，零依赖，对标 yo code）。
+ *
+ * 用法：
+ *   npm create linkdesk-plugin my-cool-plugin   # 直接给名字（kebab-case，非交互）
+ *   npm create linkdesk-plugin                  # 不带参数 → 交互式询问插件名
+ *
+ * 行为：把同目录 template/ 复制到 <cwd>/<name>，把占位符替换成真实值，打印下一步提示。
+ * 占位符：{{pluginName}} {{displayName}} {{author}} {{date}}（递归替换所有模板文件）。
+ *   {{date}} 注入 CHANGELOG.md 的初始段标题——格式必须是 `## v<版本>（YYYY-MM-DD）`，
+ *   那是市场「更改日志」页签切段的解析依据（见 docs/02-Electron架构/.../插件规范化层/02）。
+ *
+ * 生成产物契约：见 docs/02-Electron架构/E6_插件生态与发布/02-插件开发工具链/01-create-linkdesk-plugin脚手架.md。
+ */
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { createInterface } from "node:readline";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const TEMPLATE_DIR = join(dirname(fileURLToPath(import.meta.url)), "template");
+
+/** kebab-case——同时满足插件 id / viewsContainers key / npm 包名惯例（SAFE_PLUGIN_ID 的形状子集） */
+const NAME_RE = /^[a-z][a-z0-9-]*$/;
+
+/** 本地日期 YYYY-MM-DD（不用 toISOString——那是 UTC，跨时区会差一天） */
+function todayLocal() {
+  const d = new Date();
+  const p = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+
+/** my-cool-plugin → My Cool Plugin */
+function toDisplayName(name) {
+  return name
+    .split("-")
+    .map((s) => (s ? s[0].toUpperCase() + s.slice(1) : s))
+    .join(" ");
+}
+
+/** 作者默认值 = git config user.name；读不到（无 git/无配置）→ "you"（作者生成后自改） */
+function gitUserName() {
+  try {
+    const r = spawnSync("git", ["config", "user.name"], { encoding: "utf8", timeout: 3000 });
+    const v = (r.stdout || "").trim();
+    return v || "you";
+  } catch {
+    return "you";
+  }
+}
+
+/** 交互式单问——返回去除首尾空白的答案 */
+function ask(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function replacePlaceholders(file, values) {
+  let text = readFileSync(file, "utf8");
+  for (const [key, value] of Object.entries(values)) {
+    text = text.split(`{{${key}}}`).join(value);
+  }
+  writeFileSync(file, text);
+}
+
+/** 递归替换目录内全部文件（模板全是文本文件，无需跳过二进制） */
+function walkReplace(dir, values) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) walkReplace(full, values);
+    else replacePlaceholders(full, values);
+  }
+}
+
+async function main() {
+  let name = (process.argv[2] || "").trim();
+  if (!name) {
+    name = await ask("插件名（kebab-case，如 my-cool-plugin）: ");
+  }
+  name = name.trim();
+  if (!NAME_RE.test(name)) {
+    console.error(`✖ 插件名须为 kebab-case（小写字母/数字/连字符），收到：${JSON.stringify(name)}`);
+    process.exit(1);
+  }
+
+  const target = join(process.cwd(), name);
+  if (existsSync(target) && readdirSync(target).length > 0) {
+    console.error(`✖ ${name}/ 已存在且非空——换个名字，或清空后重跑`);
+    process.exit(1);
+  }
+
+  mkdirSync(target, { recursive: true });
+  cpSync(TEMPLATE_DIR, target, { recursive: true });
+
+  // 🔥 模板里存的是 `gitignore`（无点），生成时才改名为 `.gitignore`。
+  // 原因：**npm 打包恒定丢弃名为 `.gitignore` 的文件**（npm-packlist 排除表；实测
+  // `template/.gitignoreprobe` 与 `template/probe.txt` 都能进 tarball，唯独 `.gitignore` 不能）。
+  // 若模板里直接放 `.gitignore`，仓内生成（读模板目录）一切正常，**但发布后的
+  // `npm create linkdesk-plugin` 生成的工程会没有 .gitignore**——作者第一次 `git add .`
+  // 就把 node_modules/ 和 dist/ 全提交了。生成物契约见 check-scaffold.mjs 断言 8。
+  const tplGitignore = join(target, "gitignore");
+  if (existsSync(tplGitignore)) renameSync(tplGitignore, join(target, ".gitignore"));
+
+  const values = {
+    pluginName: name,
+    displayName: toDisplayName(name),
+    author: gitUserName(),
+    date: todayLocal(),
+  };
+  walkReplace(target, values);
+
+  console.log("");
+  console.log(`✔ ${name}/ 已创建`);
+  console.log("");
+  console.log("  接下来：");
+  console.log(`    cd ${name}`);
+  console.log("    npm install");
+  console.log("    npm run dev        # 浏览器热重载预览（改代码即时生效）");
+  console.log("    npm run validate   # 校验 plugin.json（$schema / 字段 / i18n 文件）");
+  console.log("    npm run build      # 打包出 <pluginId>.linkdesk-plugin，可装进 LinkDesk / 发布");
+  console.log("");
+  console.log("  然后：先读 README.md —— 目录该放哪、三条纪律、怎么发布都在里面。");
+  console.log("  plugin.json 的 name / description / author 是你的身份信息，src/index.tsx 是插件本体。");
+  console.log("  完整插件能力（侧栏视图 / 命令 / 设置 / 协议……）见 docs/03-插件制造/。");
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

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

package/template/.vscode/settings.json

@@ -1,5 +1,8 @@
-{
-  "files.associations": {
-    "plugin.json": "jsonc"
-  }
-}
+{
+  // 让 VS Code 按 JSONC 解析 plugin.json —— 它允许 // 注释与尾逗号（对标 VS Code 自己的 package.json）。
+  // 没有这一行，VS Code 会按严格 JSON 解析，本模板 plugin.json 里的注释会被标成满屏红波浪线。
+  // 这只是编辑器提示，不影响运行：LinkDesk 与 SDK 本来就按 jsonc 解析。
+  "files.associations": {
+    "plugin.json": "jsonc"
+  }
+}

package/template/CHANGELOG.md

@@ -0,0 +1,11 @@
+# 更新日志
+
+<!-- 写法约定（别改格式——LinkDesk 市场按它切段）：
+     · 段标题固定 `## v<版本>（<日期>）`，版本号必须与 plugin.json 的 version 逐字相同。
+     · 每次在 plugin.json 里 +1 版本号，就必须在同一笔加上对应的新段——只改版本不写段，
+       市场里这一版会显示「此版本未提供变更说明」。
+     · 从新到旧排列，最新的一段在最上面。 -->
+
+## v0.1.0（{{date}}）
+
+- 初始版本

package/template/README.md

@@ -0,0 +1,48 @@
+# {{displayName}}
+
+> 一句话：这个插件做什么。（写在最上面——LinkDesk 市场的「详情」页签显示的就是本文件）
+
+<!-- 有场景封面时，把图放到 resources/cover.svg，再取消下面这行的注释：
+![{{displayName}} 场景封面](resources/cover.svg) -->
+
+## 怎么用
+
+安装后在 LinkDesk 里怎么打开、点哪里、看到什么。写清楚「第一次用的人怎么走通」。
+
+## 目录说明——东西该放哪
+
+不必预建空文件夹（git 也不记录空目录）。**到需要时再建，位置按下表。**
+
+| 路径 | 放什么 | 什么时候有 |
+|:--|:--|:--|
+| `plugin.json` | 插件清单 | **必有** |
+| `README.md` | 说明——市场**详情**页签的数据源 | 强烈建议 |
+| `CHANGELOG.md` | 更新日志——市场**更改日志**页签的数据源 | 强烈建议 |
+| `resources/` | 资产：`icon.svg` / `cover.svg` / README 里引用的图 | 有图就有 |
+| `i18n/` | `en.json`（key = 中文原文；**不建 zh.json**） | 有 UI 文案就有 |
+| `themes/` · `languages/` · `snippets/` | 数据型插件的载荷 | 数据型才有 |
+| `src/index.tsx` | 入口（`plugin.json` 的 `entry`） | 视图插件必有 |
+| `src/views/` | 侧栏 / 面板视图组件（`contributes.views` 的 render 指向的文件） | 有视图时 |
+| `src/components/` | 本插件内部复用的组件 | 需要时 |
+| `src/services/` | 域逻辑 / IPC 封装 / 数据层 | 需要时 |
+| `src/styles/` | **多份** CSS 时统一放这（单份且与入口同夹也可） | 需要时 |
+| `src/__tests__/` | 单元测试（要测就自己 `npm i -D vitest`，脚手架不预装） | 需要时 |
+
+> 🔴 **共享的东西不进这里**——跨插件复用的组件 / hook 走 `@linkdesk/ui`（壳提供的公共包），**不要在插件里再写一份**；只属于本插件的域逻辑才留本地。
+> 🔴 **资产一律住 `resources/`，插件根不放散图**——能进安装包的是**被 README 引用过**或**被 `icon` / `marketIcon` 声明过**的文件，目录名本身没有魔法。
+
+## 写这个插件的三条纪律
+
+1. **颜色走主题变量**——CSS 里一律 `var(--xxx)`，**禁硬编码 hex**。理由：LinkDesk 支持整套主题替换，写死颜色 = 换主题后你的插件不跟着变。
+2. **UI 文案走 `t()`**——`t("中文原文")`，英文放 `i18n/en.json`，**不建 `zh.json`**（中文 key 自带兜底）。**只加你真的用 `t()` 读过的 key**——没人读的 key 是死 key。代码标识符（`src/index.tsx` 这类）不是文案，别包进 `t()`。
+3. **插件身份只来自 `plugin.json` 的声明字段**——需要什么能力就声明什么字段（`contributes` / `tabBehavior` / `icon` …），**不要靠目录名或文件位置让别人猜你的插件是什么**。
+
+## 发布
+
+```bash
+npm run publish     # 建 GitHub Release + 上传 .linkdesk-plugin + 更新 catalog
+```
+
+首次发布需要 GitHub token（跑一次会引导你填，存在本机）。只预览不动作：`npm run publish -- --dry-run`。
+
+> 完整作者文档见 LinkDesk 仓库的 `docs/03-插件制造/`（API 契约 / 生命周期 / contributes / 分发 / UI 写法规约）。

package/template/gitignore

@@ -0,0 +1,8 @@
+# 依赖
+node_modules/
+
+# 构建中间产物（可随时 npm run build 重建）
+dist/
+
+# 分发包——由 GitHub Release 承载，不进你的源码仓
+*.linkdesk-plugin

package/template/i18n/en.json

@@ -1,3 +1,7 @@
-{
-  "hello": "Hello from LinkDesk!"
-}
+{
+  "插件跑起来了 ✨": "Your plugin is running ✨",
+  "这是你的第一个 LinkDesk 插件。": "This is your first LinkDesk plugin.",
+  "是插件本体——改它，浏览器预览即时刷新。": "is the plugin itself — edit it and the browser preview refreshes live.",
+  "打包出分发文件，可装进 LinkDesk 或发布到市场。": "produces the distributable bundle — install it into LinkDesk or publish it to the marketplace.",
+  "目录该放哪、发布怎么做，都写在 README.md 里。": "Where things go and how to publish are all in README.md."
+}

package/template/package.json

@@ -1,17 +1,20 @@
-{
-  "name": "{{pluginName}}",
-  "version": "0.1.0",
-  "private": true,
-  "description": "{{displayName}}——LinkDesk 插件（由 create-linkdesk-plugin 生成）",
-  "type": "module",
-  "scripts": {
-    "dev": "linkdesk-plugin-sdk dev",
-    "build": "linkdesk-plugin-sdk build",
-    "validate": "linkdesk-plugin-sdk validate"
-  },
-  "devDependencies": {
-    "@linkdesk/plugin-sdk": "^0.1.0",
-    "@types/react": "^18.3.12",
-    "typescript": "^5.6.3"
-  }
-}
+{
+  "name": "{{pluginName}}",
+  "version": "0.1.0",
+  "private": true,
+  "description": "{{displayName}}——LinkDesk 插件（由 create-linkdesk-plugin 生成）",
+  "type": "module",
+  "scripts": {
+    "dev": "linkdesk-plugin-sdk dev",
+    "dev:real": "linkdesk-plugin-sdk dev --real",
+    "build": "linkdesk-plugin-sdk build",
+    "publish": "linkdesk-plugin-sdk publish",
+    "validate": "linkdesk-plugin-sdk validate",
+    "lint": "linkdesk-plugin-sdk lint"
+  },
+  "devDependencies": {
+    "@linkdesk/plugin-sdk": "^0.1.0",
+    "@types/react": "^18.3.12",
+    "typescript": "^5.6.3"
+  }
+}

package/template/plugin.json

@@ -1,38 +1,41 @@
-{
-  // ─────────────────────────────────────────────────────────────────────────
-  //  LinkDesk 插件清单 plugin.json（由 create-linkdesk-plugin 生成）
-  //
-  //  · 本文件是 JSONC：可写注释、可尾逗号（LinkDesk 与 SDK 都按 jsonc 解析，对标 VS Code package.json）。
-  //  · 完整字段以 plugin.schema.json 为准——VS Code 读 $schema 自动补全 + 校验。
-  //  · $schema 指向本工程 node_modules/@linkdesk/plugin-sdk 随包拷贝（npm install 后生效）。
-  // ─────────────────────────────────────────────────────────────────────────
-  "$schema": "./node_modules/@linkdesk/plugin-sdk/schemas/plugin.schema.json",
-
-  // ── 插件身份 ──
-  "pluginId": "{{pluginName}}", // 全局唯一 ID（kebab-case）——安装目录 / 寻址 / 命令前缀都按它
-  "name": "{{displayName}}", // 显示名——标签页 / 插件详情等 UI 出现处
-  "version": "0.1.0", // 语义化版本 x.y.z——发布更新比较靠它，改了要 +1
-  "description": "{{displayName}}——我的第一个 LinkDesk 插件", // 一句话描述（插件详情页展示）
-  "author": "{{author}}", // 作者名
-
-  // ── 入口（视图插件 = 此文件 default 导出一个 React 组件）──
-  "entry": "src/index.tsx",
-
-  // ── 出现位置：可作为主区标签页打开 ──
-  "appearsIn": { "tabBar": true },
-  "tabBehavior": { "singleton": true }, // 全局只开一个实例，避免重复标签
-
-  // ── 贡献点（contributes：全部可选，按需增删）──
-  "contributes": {
-    // 自带翻译：key=语言码, value=相对插件根的 JSON 文件。UI 文案用 t() 读这里；无需 zh.json——中文 key 原文自带兜底。
-    "i18n": { "en": "i18n/en.json" },
-    // ── 需要「侧栏 / 底部面板 / 辅助侧栏」分区视图时：取消注释，在 src/views/ 放对应组件，
-    //    容器 key 与 view id 用你的 pluginId 做前缀防撞（对标 plugins/panel-demo）──
-    // "viewsContainers": { "{{pluginName}}-sidebar": { "title": "{{displayName}}", "location": "sidebar" } },
-    // "views": {
-    //   "{{pluginName}}-sidebar": [
-    //     { "id": "main", "title": "{{displayName}}", "render": "src/views/MainView.tsx", "order": 0 }
-    //   ]
-    // }
-  },
-}
+{
+  // ─────────────────────────────────────────────────────────────────────────
+  //  LinkDesk 插件清单 plugin.json（由 create-linkdesk-plugin 生成）
+  //
+  //  · 本文件是 JSONC：可写注释、可尾逗号（LinkDesk 与 SDK 都按 jsonc 解析，对标 VS Code package.json）。
+  //  · 完整字段以 plugin.schema.json 为准——VS Code 读 $schema 自动补全 + 校验。
+  //  · $schema 指向本工程 node_modules/@linkdesk/plugin-sdk 随包拷贝（npm install 后生效）。
+  // ─────────────────────────────────────────────────────────────────────────
+  "$schema": "./node_modules/@linkdesk/plugin-sdk/schemas/plugin.schema.json",
+
+  // ── 插件身份 ──
+  // 插件 ID 默认就是插件目录名（{{pluginName}}），所以这里不写。仅当「目录名要改、但安装身份
+  // 不能变」时才取消下面这行的注释——它是覆盖值，不是必填项。
+  // "pluginId": "{{pluginName}}",
+  "name": "{{displayName}}", // 显示名——标签页 / 插件详情等 UI 出现处
+  "version": "0.1.0", // 语义化版本 x.y.z——市场更新比较靠它；+1 时务必同笔补 CHANGELOG.md 的新段
+  "description": "{{displayName}}——我的第一个 LinkDesk 插件", // 一句话描述（插件详情页展示）
+  "author": "{{author}}", // 作者名
+  "icon": "resources/icon.svg", // 图标——图标栏 / 标签页 / 市场里显示的就是它（resources/icon.svg 是占位图，换成你的）
+
+  // ── 入口（视图插件 = 此文件 default 导出一个 React 组件）──
+  "entry": "src/index.tsx",
+
+  // ── 出现位置：可作为主区标签页打开 ──
+  "appearsIn": { "tabBar": true },
+  "tabBehavior": { "singleton": true }, // 全局只开一个实例，避免重复标签
+
+  // ── 贡献点（contributes：全部可选，按需增删）──
+  "contributes": {
+    // 自带翻译：key=语言码, value=相对插件根的 JSON 文件。UI 文案用 t() 读这里；无需 zh.json——中文 key 原文自带兜底。
+    "i18n": { "en": "i18n/en.json" },
+    // ── 需要「侧栏 / 底部面板 / 辅助侧栏」分区视图时：取消注释，在 src/views/ 放对应组件，
+    //    容器 key 与 view id 用你的 pluginId 做前缀防撞（对标 plugins/panel-demo）──
+    // "viewsContainers": { "{{pluginName}}-sidebar": { "title": "{{displayName}}", "location": "sidebar" } },
+    // "views": {
+    //   "{{pluginName}}-sidebar": [
+    //     { "id": "main", "title": "{{displayName}}", "render": "src/views/MainView.tsx", "order": 0 }
+    //   ]
+    // }
+  },
+}

package/template/resources/icon.svg

@@ -0,0 +1,23 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="48" height="48" viewBox="0 0 48 48">
+  <!-- ⚠️ 占位图——请替换成你自己插件的图标（同名同位置覆盖即可，plugin.json 的 icon 已指向本文件）。
+       写法与官方插件一致：界面里以 <img src="linkdesk://<id>/resources/icon.svg"> 显示，
+       是独立文档 ⇒ 不能用 var(--xxx)（解析不到），颜色必须自含实色。 -->
+  <defs>
+    <linearGradient id="phi_bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#64748B"/>
+      <stop offset="1" stop-color="#334155"/>
+    </linearGradient>
+    <linearGradient id="phi_glass" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="#FFFFFF" stop-opacity="0.28"/>
+      <stop offset="1" stop-color="#FFFFFF" stop-opacity="0.02"/>
+    </linearGradient>
+  </defs>
+  <!-- 中性灰品牌块：刻意不设计成有含义的图形——它的意思是「这里还没有图」 -->
+  <rect x="0" y="0" width="48" height="48" rx="10" fill="url(#phi_bg)"/>
+  <rect x="0" y="0" width="48" height="48" rx="10" fill="url(#phi_glass)"/>
+  <!-- 虚线框 + 加号 = 「把你的图放这儿」 -->
+  <rect x="13" y="13" width="22" height="22" rx="5" fill="none"
+        stroke="#FFFFFF" stroke-opacity="0.9" stroke-width="2"
+        stroke-dasharray="4 3" stroke-linecap="round"/>
+  <path d="M24 19.5v9M19.5 24h9" stroke="#FFFFFF" stroke-width="2.4" stroke-linecap="round"/>
+</svg>

package/template/src/index.css

@@ -1,23 +1,30 @@
-/* {{displayName}} 样式示例——LinkDesk 主题色一律走 var(--xxx)，禁硬编码 hex。
-   布局/字号这类结构值用普通 px（不违反）；颜色/语义类才必须走主题变量。 */
-
-.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: 12px;
-}
+/* {{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);
+}

package/template/src/index.tsx

@@ -1,29 +1,35 @@
-/**
- * {{displayName}}——LinkDesk 插件主视图（由 create-linkdesk-plugin 生成）。
- *
- * 视图插件契约（E5.8，见 docs/03-插件制造/01-API契约.md）：壳以 { isActive, tabId?, sourceId? }
- * 渲染本文件 default 导出的组件：
- *   - isActive  本标签当前是否聚焦。keep-alive 下非聚焦标签仍在渲染，isActive 只用于
- *               gate「聚焦才跑」的副作用（如自动保存），切勿用它整块 blank 掉内容。
- *   - tabId     本标签页 id。
- *   - sourceId  上下文数据（文件路径 / 数据源等），编辑器类插件用它定位内容。
- *
- * 样式：LinkDesk 主题色一律走 CSS 变量 var(--xxx)（见 index.css 示例），禁硬编码 hex。
- * UI 文案规范化后用 t()（react-i18next，壳提供）读 i18n/en.json——见 05-UI写法规约.md。
- * 壳已 external react/react-dom/react-i18next/i18next——构建不会打进包，插件工程无需 npm i 它们。
- */
-
-import "./index.css";
-
-export default function HelloPlugin(_props: { isActive?: boolean; tabId?: string; sourceId?: string }) {
-  return (
-    <div className="starter">
-      <h2 className="starter__title">{{displayName}} 跑起来了 ✨</h2>
-      <p className="starter__text">这是你的第一个 LinkDesk 插件。</p>
-      <p className="starter__hint">
-        编辑 <code>src/index.tsx</code> 即可看到变化；<code>npm run build</code> 打包出{" "}
-        <code>.linkdesk-plugin</code> 分发文件。
-      </p>
-    </div>
-  );
-}
+/**
+ * {{displayName}}——LinkDesk 插件主视图（由 create-linkdesk-plugin 生成）。
+ *
+ * 视图插件契约（E5.8，见 docs/03-插件制造/01-API契约.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写法规约.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>
+  );
+}

package/template/tsconfig.json

@@ -1,14 +1,14 @@
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "strict": true,
-    "noEmit": true,
-    "jsx": "react-jsx",
-    "lib": ["ES2020", "DOM", "DOM.Iterable"],
-    "types": ["@linkdesk/plugin-sdk"],
-    "skipLibCheck": true
-  },
-  "include": ["src"]
-}
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "types": ["@linkdesk/plugin-sdk"],
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}