create-ax-trusted-plugin 1.0.4 → 1.0.6

package/README.md

@@ -1,55 +1,56 @@
-# create-ax-trusted-plugin
-
-可信(internal)插件**脚手架**:一条命令生成一个基于 `@ax-npm/host-trusted-sdk-v4` 的可信插件骨架
-(Module Federation remote + 共享 Vue + `activate(ctx)` + 自定义元素面板 + 调 `map.flyTo` + 遥测订阅)。
-
-> 脚手架本身已发**公网 npm**,生成这步**零配置**;生成出的工程才走私有源(`192.168.1.209` GitLab)拉
-> `@ax-npm/*` 依赖,届时只需一个 `GITLAB_TOKEN`(无需手建任何 `.npmrc`,工程自带)。
-
-## 用法
-```bash
-# 交互式(缺参数会提示输入 id/标题/锚点)
-npm create ax-trusted-plugin@latest my-panel
-
-# 非交互(传参)
-npm create ax-trusted-plugin@latest my-panel -- --title "我的面板" --anchor top-right
-```
-等价于直接跑 bin:`node bin/index.mjs my-panel --title "我的面板" --anchor top-right`。
-
-生成 `my-panel/` 后(把 `GITLAB_TOKEN` 换成你的只读 PAT,按所用 shell 选一行):
-```bash
-cd my-panel
-export GITLAB_TOKEN=<读权限 PAT>           # bash / git-bash
-# $env:GITLAB_TOKEN="<读权限 PAT>"        # PowerShell
-# set GITLAB_TOKEN=<读权限 PAT>           # cmd
-npm install
-npm run dev
-```
-
-## 参数
-| 参数 | 说明 | 默认 |
-|---|---|---|
-| `<id>`(位置参数) | 插件 id,小写短横线 | 必填(缺则提示) |
-| `--title` | 面板标题 | 由 id 推导 |
-| `--anchor` | 浮层锚点 | `top-right` |
-
-锚点可选:`top-left/top-right/top-center/bottom-left/bottom-right/left-center/right-center/center`。
-
-## 生成内容
-`template/` 经占位替换(`__ID__`/`__TITLE__`/`__ANCHOR__`/`__FED_NAME__`)后落地:`src/{index.ts,Panel.vue,state.ts}`、
-`manifest.json`(trust:internal)、`vite.config.ts`(federation remote)、`serve.mjs`(dev 静态源)、`package.json`、
-`tsconfig.json`、`.npmrc`、`.gitignore`、`README.md`。
-
-## 发布(维护者)
-脚手架包发**公网 npm**(`publishConfig` 已指向 `registry.npmjs.org`、`access: public`):
-```bash
-npm login --registry https://registry.npmjs.org/   # 首次
-npm publish --otp=<6位验证码>                       # npm 强制 2FA,验证码来自验证器 App
-```
-- 若提示包名被占,改 `package.json` 的 `name`(及随之的 `npm create <name>` 用法)。
-- 自动化/CI 免输码:在 npm 生成「可绕过 2FA 的 Granular Access Token」,
-  以 `//registry.npmjs.org/:_authToken=<token>` 注入后 `npm publish`。
-
-> 注意:`template/` 内仍引用私网地址 `192.168.1.209`(RFC1918 不可路由,非机密),发公网后会公开可见。
-
-源码仓:GitLab 项目 1244。
+# create-ax-trusted-plugin
+
+可信(internal)插件**脚手架**:一条命令生成一个基于 `@ax-npm/host-trusted-sdk-v4` 的可信插件骨架
+(默认「形态一」:ESM 直出 `activate` + 自带 Vue + 自定义元素面板 + 调 `map.flyTo` + 遥测订阅;
+dev 走裸 `vite`,原生 sourcemap、无构建步)。
+
+> 脚手架本身已发**公网 npm**,生成这步**零配置**;生成出的工程才走私有源(`192.168.1.209` GitLab)拉
+> `@ax-npm/*` 依赖,届时只需一个 `GITLAB_TOKEN`(无需手建任何 `.npmrc`,工程自带)。
+
+## 用法
+```bash
+# 交互式(缺参数会提示输入 id/标题/锚点)
+npm create ax-trusted-plugin@latest my-panel
+
+# 非交互(传参)
+npm create ax-trusted-plugin@latest my-panel -- --title "我的面板" --anchor top-right
+```
+等价于直接跑 bin:`node bin/index.mjs my-panel --title "我的面板" --anchor top-right`。
+
+生成 `my-panel/` 后(把 `GITLAB_TOKEN` 换成你的只读 PAT,按所用 shell 选一行):
+```bash
+cd my-panel
+export GITLAB_TOKEN=<读权限 PAT>           # bash / git-bash
+# $env:GITLAB_TOKEN="<读权限 PAT>"        # PowerShell
+# set GITLAB_TOKEN=<读权限 PAT>           # cmd
+npm install
+npm run dev
+```
+
+## 参数
+| 参数 | 说明 | 默认 |
+|---|---|---|
+| `<id>`(位置参数) | 插件 id,小写短横线 | 必填(缺则提示) |
+| `--title` | 面板标题 | 由 id 推导 |
+| `--anchor` | 浮层锚点 | `top-right` |
+
+锚点可选:`top-left/top-right/top-center/bottom-left/bottom-right/left-center/right-center/center`。
+
+## 生成内容
+`template/` 经占位替换(`__ID__`/`__TITLE__`/`__ANCHOR__`)后落地:`src/{index.ts,Panel.vue,state.ts}`、
+`manifest.json`(trust:internal、entry:main.js)、`vite.config.ts`(形态一 lib 构建 + dev 市场源桥)、
+`package.json`、`tsconfig.json`、`.npmrc`、`.gitignore`、`README.md`。
+
+## 发布(维护者)
+脚手架包发**公网 npm**(`publishConfig` 已指向 `registry.npmjs.org`、`access: public`):
+```bash
+npm login --registry https://registry.npmjs.org/   # 首次
+npm publish --otp=<6位验证码>                       # npm 强制 2FA,验证码来自验证器 App
+```
+- 若提示包名被占,改 `package.json` 的 `name`(及随之的 `npm create <name>` 用法)。
+- 自动化/CI 免输码:在 npm 生成「可绕过 2FA 的 Granular Access Token」,
+  以 `//registry.npmjs.org/:_authToken=<token>` 注入后 `npm publish`。
+
+> 注意:`template/` 内仍引用私网地址 `192.168.1.209`(RFC1918 不可路由,非机密),发公网后会公开可见。
+
+源码仓:GitLab 项目 1244。

package/bin/index.mjs

@@ -1,112 +1,111 @@
-#!/usr/bin/env node
-// create-ax-trusted-plugin —— 可信(internal)插件脚手架(发布于公网 npm)。
-// 用法:
-//   npm create ax-trusted-plugin <id> [-- --title "标题" --anchor top-right]
-//   node bin/index.mjs <id> --title "标题" --anchor top-right
-// 把 template/ 复制到 <id>/,按 id/title/anchor 做占位替换(dotfile 以 _ 前缀存放,生成时改名)。
-import { readdir, readFile, writeFile, mkdir, stat } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { dirname, join, resolve, relative } from 'node:path';
-import { createInterface } from 'node:readline/promises';
-
-const here = dirname(fileURLToPath(import.meta.url));
-const TEMPLATE = resolve(here, '..', 'template');
-
-const ANCHORS = [
-  'top-left', 'top-right', 'top-center',
-  'bottom-left', 'bottom-right',
-  'left-center', 'right-center', 'center',
-];
-
-function parseArgs(argv) {
-  const out = { _: [] };
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a.startsWith('--')) out[a.slice(2)] = argv[++i] ?? '';
-    else out._.push(a);
-  }
-  return out;
-}
-
-function toTitle(id) {
-  return id.replace(/[-_]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
-}
-
-async function prompt(rl, q, def) {
-  if (!process.stdin.isTTY) return def;
-  const ans = (await rl.question(`${q}${def ? ` (${def})` : ''}: `)).trim();
-  return ans || def;
-}
-
-// 复制 + 占位替换 + dotfile 改名(_gitignore→.gitignore、_npmrc→.npmrc)。
-async function scaffold(srcDir, destDir, vars) {
-  await mkdir(destDir, { recursive: true });
-  for (const name of await readdir(srcDir)) {
-    const src = join(srcDir, name);
-    const s = await stat(src);
-    const outName = name === '_gitignore' ? '.gitignore' : name === '_npmrc' ? '.npmrc' : name;
-    const dest = join(destDir, outName);
-    if (s.isDirectory()) {
-      await scaffold(src, dest, vars);
-    } else {
-      let body = await readFile(src, 'utf8');
-      for (const [k, v] of Object.entries(vars)) body = body.split(k).join(v);
-      await writeFile(dest, body);
-    }
-  }
-}
-
-async function main() {
-  const args = parseArgs(process.argv.slice(2));
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    let id = args._[0] || args.id;
-    if (!id) id = await prompt(rl, '插件 id(小写短横线,如 my-panel)', '');
-    id = String(id || '').trim().toLowerCase();
-    if (!/^[a-z][a-z0-9-]*$/.test(id)) {
-      console.error('✗ 非法 id:须小写字母开头,仅含小写字母/数字/短横线。');
-      process.exit(1);
-    }
-
-    const title = args.title || (await prompt(rl, '面板标题', toTitle(id)));
-    let anchor = args.anchor || (await prompt(rl, `锚点(${ANCHORS.join('/')})`, 'top-right'));
-    anchor = String(anchor).trim();
-    if (!ANCHORS.includes(anchor)) {
-      console.error(`✗ 非法 anchor:${anchor}。可选:${ANCHORS.join(', ')}`);
-      process.exit(1);
-    }
-
-    const destDir = resolve(process.cwd(), args.dir || id);
-    if (existsSync(destDir)) {
-      console.error(`✗ 目标已存在:${destDir}`);
-      process.exit(1);
-    }
-
-    const vars = {
-      __ID__: id,
-      __TITLE__: title,
-      __ANCHOR__: anchor,
-      __FED_NAME__: id.replace(/[^a-zA-Z0-9]/g, '_'),
-    };
-    await scaffold(TEMPLATE, destDir, vars);
-
-    const rel = relative(process.cwd(), destDir) || '.';
-    console.log(`\n✓ 已生成可信插件:${rel}`);
-    console.log('\n下一步:');
-    console.log(`  cd ${rel}`);
-    console.log('  # 设只读 PAT(按所用 shell 选一行):');
-    console.log('  export GITLAB_TOKEN=<读权限 PAT>      # bash / git-bash');
-    console.log('  $env:GITLAB_TOKEN="<读权限 PAT>"     # PowerShell');
-    console.log('  set GITLAB_TOKEN=<读权限 PAT>        # cmd');
-    console.log('  npm install');
-    console.log('  npm run dev   # build:watch + 静态托管 + host-dev,浏览器调试\n');
-  } finally {
-    rl.close();
-  }
-}
-
-main().catch((e) => {
-  console.error(e);
-  process.exit(1);
-});
+#!/usr/bin/env node
+// create-ax-trusted-plugin —— 可信(internal)插件脚手架(发布于公网 npm)。
+// 用法:
+//   npm create ax-trusted-plugin <id> [-- --title "标题" --anchor top-right]
+//   node bin/index.mjs <id> --title "标题" --anchor top-right
+// 把 template/ 复制到 <id>/,按 id/title/anchor 做占位替换(dotfile 以 _ 前缀存放,生成时改名)。
+import { readdir, readFile, writeFile, mkdir, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve, relative } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const TEMPLATE = resolve(here, '..', 'template');
+
+const ANCHORS = [
+  'top-left', 'top-right', 'top-center',
+  'bottom-left', 'bottom-right',
+  'left-center', 'right-center', 'center',
+];
+
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) out[a.slice(2)] = argv[++i] ?? '';
+    else out._.push(a);
+  }
+  return out;
+}
+
+function toTitle(id) {
+  return id.replace(/[-_]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+async function prompt(rl, q, def) {
+  if (!process.stdin.isTTY) return def;
+  const ans = (await rl.question(`${q}${def ? ` (${def})` : ''}: `)).trim();
+  return ans || def;
+}
+
+// 复制 + 占位替换 + dotfile 改名(_gitignore→.gitignore、_npmrc→.npmrc)。
+async function scaffold(srcDir, destDir, vars) {
+  await mkdir(destDir, { recursive: true });
+  for (const name of await readdir(srcDir)) {
+    const src = join(srcDir, name);
+    const s = await stat(src);
+    const outName = name === '_gitignore' ? '.gitignore' : name === '_npmrc' ? '.npmrc' : name;
+    const dest = join(destDir, outName);
+    if (s.isDirectory()) {
+      await scaffold(src, dest, vars);
+    } else {
+      let body = await readFile(src, 'utf8');
+      for (const [k, v] of Object.entries(vars)) body = body.split(k).join(v);
+      await writeFile(dest, body);
+    }
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    let id = args._[0] || args.id;
+    if (!id) id = await prompt(rl, '插件 id(小写短横线,如 my-panel)', '');
+    id = String(id || '').trim().toLowerCase();
+    if (!/^[a-z][a-z0-9-]*$/.test(id)) {
+      console.error('✗ 非法 id:须小写字母开头,仅含小写字母/数字/短横线。');
+      process.exit(1);
+    }
+
+    const title = args.title || (await prompt(rl, '面板标题', toTitle(id)));
+    let anchor = args.anchor || (await prompt(rl, `锚点(${ANCHORS.join('/')})`, 'top-right'));
+    anchor = String(anchor).trim();
+    if (!ANCHORS.includes(anchor)) {
+      console.error(`✗ 非法 anchor:${anchor}。可选:${ANCHORS.join(', ')}`);
+      process.exit(1);
+    }
+
+    const destDir = resolve(process.cwd(), args.dir || id);
+    if (existsSync(destDir)) {
+      console.error(`✗ 目标已存在:${destDir}`);
+      process.exit(1);
+    }
+
+    const vars = {
+      __ID__: id,
+      __TITLE__: title,
+      __ANCHOR__: anchor,
+    };
+    await scaffold(TEMPLATE, destDir, vars);
+
+    const rel = relative(process.cwd(), destDir) || '.';
+    console.log(`\n✓ 已生成可信插件:${rel}`);
+    console.log('\n下一步:');
+    console.log(`  cd ${rel}`);
+    console.log('  # 设只读 PAT(按所用 shell 选一行):');
+    console.log('  export GITLAB_TOKEN=<读权限 PAT>      # bash / git-bash');
+    console.log('  $env:GITLAB_TOKEN="<读权限 PAT>"     # PowerShell');
+    console.log('  set GITLAB_TOKEN=<读权限 PAT>        # cmd');
+    console.log('  npm install');
+    console.log('  npm run dev   # 裸 vite(市场源,原生 sourcemap) + host-dev 真宿主,浏览器调试\n');
+  } finally {
+    rl.close();
+  }
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

package/package.json

@@ -1,28 +1,27 @@
-{
-  "name": "create-ax-trusted-plugin",
-  "version": "1.0.4",
-  "description": "可信(internal)插件脚手架:一条命令生成一个基于 @ax-npm/host-trusted-sdk-v4 的可信插件骨架(Module Federation remote + 共享 Vue + activate(ctx))。用法:npm create ax-trusted-plugin <id>。生成器本身无机密,公网可装;生成出的工程仍走私有源拉 @ax-npm/* 依赖。",
-  "type": "module",
-  "license": "MIT",
-  "keywords": [
-    "create-ax-trusted-plugin",
-    "scaffold",
-    "module-federation",
-    "vue",
-    "plugin"
-  ],
-  "bin": {
-    "create-ax-trusted-plugin": "bin/index.mjs"
-  },
-  "files": [
-    "bin",
-    "template"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org/",
-    "access": "public"
-  }
-}
+{
+  "name": "create-ax-trusted-plugin",
+  "version": "1.0.6",
+  "description": "可信(internal)插件脚手架:一条命令生成一个基于 @ax-npm/host-trusted-sdk-v4 的可信插件骨架(默认形态一:ESM 直出 activate + 自带 Vue,dev 裸 vite 原生 sourcemap)。用法:npm create ax-trusted-plugin <id>。生成器本身无机密,公网可装;生成出的工程仍走私有源拉 @ax-npm/* 依赖。",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "create-ax-trusted-plugin",
+    "scaffold",
+    "vue",
+    "plugin"
+  ],
+  "bin": {
+    "create-ax-trusted-plugin": "bin/index.mjs"
+  },
+  "files": [
+    "bin",
+    "template"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/template/README.md

@@ -1,30 +1,33 @@
-# __ID__
-
-可信(internal)插件:经 Module Federation 融入宿主进程、共享宿主 Vue、拿完整 `ctx`。
-由 `create-ax-trusted-plugin` 脚手架生成。
-
-## 开发
-```bash
-export GITLAB_TOKEN=<读权限 PAT>           # bash / git-bash
-# $env:GITLAB_TOKEN="<读权限 PAT>"        # PowerShell(别用 set / %VAR%)
-# set GITLAB_TOKEN=<读权限 PAT>           # cmd
-npm install
-npm run dev   # build:watch + serve(:5174) + host-dev(:5173)
-```
-浏览器打开 `http://localhost:5173`,锚点出现「__TITLE__」面板。改代码 → 自动重建 → 刷新浏览器。
-
-> ⚠️ 可信插件不能用 `vite dev`(federation dev 不产可加载 remoteEntry),故用 `build --watch` + 静态托管。
-
-## 构建 / 上架
-```bash
-npm run build   # → dist/assets/remoteEntry.js
-```
-把 `dist/` + `manifest.json` 部署到静态源,在宿主市场 `plugins.json` 登记本插件 id 即可加载。
-
-## 关键约定
-- federation:`exposes:{'./plugin':'./src/index.ts'}` + `shared:['vue','pinia']`(**别设 requiredVersion**)。
-- `manifest.entry` = `assets/remoteEntry.js`,`mfExpose` 与 exposes key 一致(`./plugin`)。
-- 提供能力须命名空间化(`__ID__/...`)且在 `contributes.capabilities` 声明;消费走 `uses.capabilities`。
-- 插件间不互相 import,只走 `ctx.commands` / `ctx.events`。
-
-完整说明见 `@ax-npm/host-trusted-sdk-v4` 的 README。
+# __ID__
+
+可信(internal)插件「形态一」:模块直接 `export activate`,壳 `import` 即用;进程内拿完整 `ctx`。
+Vue 打进本插件 bundle(与宿主/其它插件隔离)。由 `create-ax-trusted-plugin` 脚手架生成。
+
+## 开发
+```bash
+export GITLAB_TOKEN=<读权限 PAT>           # bash / git-bash
+# $env:GITLAB_TOKEN="<读权限 PAT>"        # PowerShell(别用 set / %VAR%)
+# set GITLAB_TOKEN=<读权限 PAT>           # cmd
+npm install
+npm run dev   # concurrently: vite(:5174,市场源) + host-dev 真宿主(:5173)
+```
+浏览器打开 `http://localhost:5173`,锚点出现「__TITLE__」面板。**改代码 → 刷新浏览器即生效**(原生 sourcemap)。
+
+> dev 走裸 `vite`:`vite.config.ts` 的 `hostSourceBridge` 把单插件服务伪装成市场源,
+> `/<id>/main.js` 实时转译 `src/index.ts`。多插件并行各自 `vite --port 5175/5176/…`。
+
+## 构建 / 上架
+```bash
+npm run build   # → dist/main.js(+ main.js.map)
+```
+把 `dist/main.js`(+ `.map`)+ `manifest.json` 部署到静态源,在宿主市场 `plugins.json` 登记本插件 id(及 `baseUrl`)即可加载。
+
+## 关键约定
+- 入口 `src/index.ts` 必须 `export function activate(ctx)`(可选 `elementTag`/`deactivate`);`manifest.entry`=`main.js`。
+- `vue({customElement:true})` 把样式注入 shadow root;Vue 自带打包,不与宿主共享。
+- 提供能力须命名空间化(`__ID__/...`)且在 `contributes.capabilities` 声明;消费(含**调自己提供的能力**)须在 `uses.capabilities` 声明——contributes 与 uses 是两道独立门,`execute` 一律过 uses 闸。
+- 插件间不互相 import,只走 `ctx.commands` / `ctx.events`。
+
+> 需要多个可信插件**共享单例** Vue / 跨边界共享响应式 store,或要省 Vue 体积时,才回退「形态二」
+> (Module Federation):`vite.config` 改用 `@originjs/vite-plugin-federation`、`manifest` 加 `mfExpose`、
+> dev 走 `vite build --watch` + 静态托管。详见 `@ax-npm/host-trusted-sdk-v4` 的 README 与《三角色开发方法.md》。

package/template/manifest.json

@@ -1,18 +1,17 @@
-{
-  "id": "__ID__",
-  "version": "0.1.0",
-  "trust": "internal",
-  "host": "^1.0.0",
-  "entry": "assets/remoteEntry.js",
-  "mfExpose": "./plugin",
-  "activationEvents": ["onStartup"],
-  "contributes": { "capabilities": ["__ID__/ping"] },
-  "uses": { "capabilities": ["map.flyTo"] },
-  "component": {
-    "anchor": "__ANCHOR__",
-    "width": 320,
-    "height": 220,
-    "title": "__TITLE__",
-    "visible": true
-  }
-}
+{
+  "id": "__ID__",
+  "version": "0.1.0",
+  "trust": "internal",
+  "host": "^1.0.0",
+  "entry": "main.js",
+  "activationEvents": ["onStartup"],
+  "contributes": { "capabilities": ["__ID__/ping"] },
+  "uses": { "capabilities": ["map.flyTo", "__ID__/ping"] },
+  "component": {
+    "anchor": "__ANCHOR__",
+    "width": 320,
+    "height": 220,
+    "title": "__TITLE__",
+    "visible": true
+  }
+}

package/template/package.json

@@ -1,30 +1,27 @@
-{
-  "name": "__ID__",
-  "version": "0.1.0",
-  "private": true,
-  "type": "module",
-  "description": "可信(internal)插件:经 Module Federation 融入宿主进程、共享 Vue、拿完整 ctx。只依赖 @ax-npm/host-trusted-sdk-v4。",
-  "scripts": {
-    "build": "vue-tsc --noEmit && vite build",
-    "build:watch": "vite build --watch",
-    "serve": "node serve.mjs",
-    "dev": "vite build && concurrently -k -n build,serve,host -c blue,magenta,green \"vite build --watch\" \"node serve.mjs\" \"host-dev --plugin http://localhost:5174\"",
-    "dev:electron": "vite build && concurrently -k -n build,serve,host -c blue,magenta,green \"vite build --watch\" \"node serve.mjs\" \"host-dev --electron --plugin http://localhost:5174\"",
-    "typecheck": "vue-tsc --noEmit"
-  },
-  "dependencies": {
-    "@ax-npm/host-trusted-sdk-v4": "^1.0.2",
-    "vue": "^3.4.0"
-  },
-  "devDependencies": {
-    "@ax-npm/host-dev-v4": "^1.0.7",
-    "@originjs/vite-plugin-federation": "^1.3.5",
-    "@vitejs/plugin-vue": "^5.0.0",
-    "concurrently": "^9.0.0",
-    "electron": "^39.0.0",
-    "pinia": "^2.1.7",
-    "typescript": "^5.4.0",
-    "vite": "^5.2.0",
-    "vue-tsc": "^2.0.0"
-  }
-}
+{
+  "name": "__ID__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "可信(internal)插件「形态一」:ESM 直出 activate,壳 import 即用、Vue 自带打包(隔离)、拿完整 ctx。dev 走裸 vite(原生 sourcemap、无构建步)。只依赖 @ax-npm/host-trusted-sdk-v4。",
+  "scripts": {
+    "build": "vue-tsc --noEmit && vite build",
+    "serve": "vite",
+    "dev": "concurrently -k -n plugin,host -c blue,green \"vite\" \"host-dev --plugin http://localhost:5174\"",
+    "dev:electron": "concurrently -k -n plugin,host -c blue,green \"vite\" \"host-dev --electron --plugin http://localhost:5174\"",
+    "typecheck": "vue-tsc --noEmit"
+  },
+  "dependencies": {
+    "@ax-npm/host-trusted-sdk-v4": "^1.0.2",
+    "vue": "^3.4.0"
+  },
+  "devDependencies": {
+    "@ax-npm/host-dev-v4": "^1.0.7",
+    "@vitejs/plugin-vue": "^5.0.0",
+    "concurrently": "^9.0.0",
+    "electron": "^39.0.0",
+    "typescript": "^5.4.0",
+    "vite": "^5.2.0",
+    "vue-tsc": "^2.0.0"
+  }
+}

package/template/src/index.ts

@@ -1,41 +1,44 @@
-// 可信插件入口(打成 MF remote 的 expose './plugin')。
-// 宿主经容器协议加载本模块后调 activate(ctx),据 elementTag + manifest.component 挂自定义元素。
-import { definePluginElement, type PluginCtx } from '@ax-npm/host-trusted-sdk-v4';
-import Panel from './Panel.vue';
-import { state, type FcsBasic } from './state';
-
-export const elementTag = definePluginElement(Panel, { tag: 'plugin-__ID__' });
-
-export function activate(ctx: PluginCtx) {
-  // ① 提供能力:id 须命名空间化 + 在 manifest.contributes.capabilities 声明。
-  ctx.commands.register('__ID__/ping', async () => 'pong @ ' + new Date().toLocaleTimeString());
-
-  // ② 订阅宿主遥测(广播)。
-  ctx.events.on('telemetry:fcs.basic', (p) => {
-    state.telemetry = p as FcsBasic;
-  });
-
-  // ③ Panel 是自定义元素,拿不到 ctx;经 window 事件把用户动作桥回 activate 作用域。
-  window.addEventListener('__ID__:ping', async () => {
-    state.lastPing = String(await ctx.commands.execute('__ID__/ping'));
-  });
-  window.addEventListener('__ID__:flyto', async () => {
-    try {
-      // 调宿主地图能力(需在 manifest.uses.capabilities 声明 map.flyTo)。
-      await ctx.commands.execute('map.flyTo', 116.397, 39.908);
-      state.flyToNote = '已飞至北京';
-    } catch (e) {
-      state.flyToNote = '失败:' + (e instanceof Error ? e.message : String(e));
-    }
-  });
-
-  return {
-    elementTag,
-    onVisible() {},
-    onHidden() {},
-  };
-}
-
-export function deactivate() {
-  // 仅收自有资源;经 ctx 注册的命令/事件由运行时自动回收。
-}
+// 可信插件入口「形态一」:本模块直接导出 activate/elementTag(manifest.entry → main.js)。
+// 宿主 loader `import(url)` 命中「直出 activate」分支,调 activate(ctx),据 elementTag +
+// manifest.component 挂自定义元素。(业务代码与形态二一致,只差打包/加载方式。)
+import { definePluginElement, type PluginCtx } from '@ax-npm/host-trusted-sdk-v4';
+import Panel from './Panel.vue';
+import { state, type FcsBasic } from './state';
+
+export const elementTag = definePluginElement(Panel, { tag: 'plugin-__ID__' });
+
+export function activate(ctx: PluginCtx) {
+  // ① 提供能力:id 须命名空间化 + 在 manifest.contributes.capabilities 声明。
+  //    注意:contributes(提供)与 uses(调用)是两道独立门——execute 走 uses 闸,**调自己
+  //    register 的能力也要在 manifest.uses.capabilities 声明**(见下方 ③ 的 __ID__/ping)。
+  ctx.commands.register('__ID__/ping', async () => 'pong @ ' + new Date().toLocaleTimeString());
+
+  // ② 订阅宿主遥测(广播)。
+  ctx.events.on('telemetry:fcs.basic', (p) => {
+    state.telemetry = p as FcsBasic;
+  });
+
+  // ③ Panel 是自定义元素,拿不到 ctx;经 window 事件把用户动作桥回 activate 作用域。
+  window.addEventListener('__ID__:ping', async () => {
+    state.lastPing = String(await ctx.commands.execute('__ID__/ping'));
+  });
+  window.addEventListener('__ID__:flyto', async () => {
+    try {
+      // 调宿主地图能力(需在 manifest.uses.capabilities 声明 map.flyTo)。
+      await ctx.commands.execute('map.flyTo', 116.397, 39.908);
+      state.flyToNote = '已飞至北京';
+    } catch (e) {
+      state.flyToNote = '失败:' + (e instanceof Error ? e.message : String(e));
+    }
+  });
+
+  return {
+    elementTag,
+    onVisible() {},
+    onHidden() {},
+  };
+}
+
+export function deactivate() {
+  // 仅收自有资源;经 ctx 注册的命令/事件由运行时自动回收。
+}

package/template/vite.config.ts

@@ -1,33 +1,83 @@
-import { defineConfig } from 'vite';
-import vue from '@vitejs/plugin-vue';
-import federation from '@originjs/vite-plugin-federation';
-
-// 可信插件构建:打成 Module Federation remote。
-// - vue({ customElement: true }):SFC 以自定义元素模式编译,样式自动进 shadow root。
-// - federation exposes './plugin' → src/index.ts(导出 activate/elementTag);
-//   shared ['vue','pinia'] 让本插件对 vue/pinia 的引用运行时复用宿主单例。
-//   **不要给 shared 设 requiredVersion**(宿主按首个注册版本提供,无需精确匹配)。
-// 产物 dist/assets/remoteEntry.js 即 manifest.entry 指向的容器。
-//
-// 可信插件**不能**用 vite dev 调试(federation dev 不产可加载 remoteEntry),
-// 故走 `vite build --watch` + 静态托管 dist(见 serve.mjs / package.json dev)。
-export default defineConfig({
-  plugins: [
-    vue({ customElement: true }),
-    federation({
-      name: '__FED_NAME__',
-      filename: 'remoteEntry.js',
-      exposes: { './plugin': './src/index.ts' },
-      shared: ['vue', 'pinia'],
-    }),
-  ],
-  build: {
-    target: 'esnext',
-    outDir: 'dist',
-    // 不清空 outDir:`vite build --watch` 每次重建都会先清空再写,留下一个 remoteEntry.js
-    // 缺失的窗口;若浏览器在该窗口请求 remoteEntry 就会 404、插件激活失败。保留旧产物、
-    // 原地覆盖可消除该窗口(产物文件名带 hash,残留旧 chunk 无害)。
-    emptyOutDir: false,
-    minify: false,
-  },
-});
+import { defineConfig } from 'vite';
+import vue from '@vitejs/plugin-vue';
+import { fileURLToPath, URL } from 'node:url';
+import { readFileSync } from 'node:fs';
+
+// 可信插件「形态一」(ESM 直出 activate)构建。与「形态二」(Module Federation 容器)对比:
+// - 形态一:本模块 import(url) 后**直接导出 activate/elementTag**,壳 loader 命中直出分支。
+//   Vue 打进 bundle(自带依赖,与宿主/其它插件隔离 —— 宿主升级 Vue 波及不到本插件)。
+// - 形态二:打成 federation remoteEntry,运行时与宿主**共享单例** Vue/Pinia。
+// 只经 ctx 交互的内部插件用形态一**功能零损失**,且换来:dev 走裸 `vite`(实时转译、原生
+// sourcemap、无构建步),build 产单文件 `main.js`。仅当需要跨边界共享响应式 store / 省体积
+// 到单份 Vue 时才回退形态二(见 README 与《三角色开发方法.md》)。
+//
+// vue({ customElement: true }):SFC 以自定义元素模式编译,样式自动注入 shadow root,
+// 故无独立 CSS 产物,单个 main.js 即完整插件。
+
+const MANIFEST = JSON.parse(
+  readFileSync(fileURLToPath(new URL('./manifest.json', import.meta.url)), 'utf-8'),
+) as { id: string };
+const PLUGIN_ID = MANIFEST.id;
+
+// —— dev 桥:让「单插件 vite 服务」对外长得像宿主的插件市场源 ——
+// 宿主(LocalRegistry)会请求 /plugins.json、/<id>/manifest.json、/<id>/<entry>。
+// 这里:① /plugins.json = [{ id }];② 把 /<id>/* 重写回 /*(插件本体在根目录);
+//        ③ manifest.entry 是 `main.js`(生产构建产物),dev 无此产物 → 把对它的请求
+//           顶替为 `src/index.ts`,由 vite 实时转译(原生 sourcemap、无构建步)。
+// 这样单跑 `vite` 即可被 harness/host-dev 当市场源加载,改代码刷新即生效。
+function hostSourceBridge() {
+  return {
+    name: 'host-source-bridge',
+    configureServer(server: {
+      middlewares: { use: (fn: (req: any, res: any, next: () => void) => void) => void };
+    }) {
+      server.middlewares.use((req, res, next) => {
+        const url = (req.url || '').split('?')[0];
+        if (url === '/plugins.json') {
+          res.setHeader('content-type', 'application/json');
+          res.setHeader('access-control-allow-origin', '*');
+          res.end(JSON.stringify([{ id: PLUGIN_ID }]));
+          return;
+        }
+        // /<id>/xxx → /xxx(去掉宿主加的 id 前缀)
+        if (req.url === `/${PLUGIN_ID}` || req.url === `/${PLUGIN_ID}/`) {
+          req.url = '/';
+        } else if (req.url && req.url.startsWith(`/${PLUGIN_ID}/`)) {
+          req.url = req.url.slice(PLUGIN_ID.length + 1);
+        }
+        // 形态一 dev:把 main.js 入口请求顶替为可实时转译的源文件。
+        if ((req.url || '').split('?')[0] === '/main.js') req.url = '/src/index.ts';
+        next();
+      });
+    },
+  };
+}
+
+export default defineConfig({
+  plugins: [vue({ customElement: true }), hostSourceBridge()],
+  server: {
+    // 活跃集多插件并行时用 `vite --port 5175/5176/…` 覆盖,一份多源 plugins.json 列各端口。
+    port: 5174,
+    strictPort: true,
+    // 宿主(:5180 / app://)跨源拉清单/manifest/入口模块,需放开 CORS。
+    cors: { origin: '*' },
+  },
+  build: {
+    target: 'esnext',
+    outDir: 'dist',
+    emptyOutDir: true,
+    // 源码级调试可信插件产物:留 sourcemap、不混淆。
+    sourcemap: true,
+    minify: false,
+    // library 模式:入口导出(activate/elementTag/deactivate)即模块导出,壳 import(url) 直出。
+    lib: {
+      entry: fileURLToPath(new URL('./src/index.ts', import.meta.url)),
+      formats: ['es'],
+      fileName: () => 'main.js',
+    },
+    rollupOptions: {
+      // 保住入口导出签名,别被当可执行 chunk 摇掉 activate。
+      preserveEntrySignatures: 'strict',
+    },
+  },
+});

package/template/index.html

@@ -1,6 +0,0 @@
-<!doctype html>
-<html>
-  <head><meta charset="utf-8" /><title>__ID__ (build entry)</title></head>
-  <!-- 仅作 federation 构建入口;宿主实际加载的是 assets/remoteEntry.js 容器,不是本页。 -->
-  <body></body>
-</html>

package/template/serve.mjs

@@ -1,77 +0,0 @@
-#!/usr/bin/env node
-// 零依赖静态服务:把构建产物 dist/ 对外伪装成「宿主插件源」。
-// 宿主会请求 /plugins.json、/<id>/manifest.json、/<id>/assets/remoteEntry.js…
-// 配合 host-dev --plugin http://localhost:5174 调试。改代码 → vite build --watch 自动重建 → 刷新浏览器。
-import { createServer } from 'node:http';
-import { readFile, stat } from 'node:fs/promises';
-import { readFileSync, existsSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { dirname, join, normalize, extname, resolve } from 'node:path';
-
-const here = dirname(fileURLToPath(import.meta.url));
-const DIST = resolve(here, 'dist');
-const MANIFEST = JSON.parse(readFileSync(resolve(here, 'manifest.json'), 'utf8'));
-const ID = MANIFEST.id;
-const PORT = Number(process.env.PORT || 5174);
-// 真正决定「插件就绪」的产物 = manifest.entry 指向的 remoteEntry。
-// /plugins.json 的就绪信号必须以它为准,否则 host-dev 会在 dist 尚未产出(或 watch 重建
-// 清空 dist 的窗口内)就判定就绪并开浏览器,导致 remoteEntry 404、插件激活失败。
-const REMOTE_ENTRY = resolve(DIST, MANIFEST.entry || 'assets/remoteEntry.js');
-
-const MIME = {
-  '.js': 'text/javascript; charset=utf-8',
-  '.mjs': 'text/javascript; charset=utf-8',
-  '.json': 'application/json; charset=utf-8',
-  '.css': 'text/css; charset=utf-8',
-  '.html': 'text/html; charset=utf-8',
-  '.svg': 'image/svg+xml',
-  '.map': 'application/json; charset=utf-8',
-};
-
-createServer(async (req, res) => {
-  res.setHeader('access-control-allow-origin', '*');
-  const url = (req.url || '/').split('?')[0];
-
-  if (url === '/plugins.json') {
-    // 产物未就绪(首次构建未完成 / watch 重建窗口)时回 503,让 host-dev 的就绪轮询继续等。
-    if (!existsSync(REMOTE_ENTRY)) {
-      res.writeHead(503, { 'content-type': MIME['.json'], 'retry-after': '1' });
-      return res.end(JSON.stringify({ error: 'building', detail: 'remoteEntry 未就绪,等 vite build 完成' }));
-    }
-    res.writeHead(200, { 'content-type': MIME['.json'] });
-    return res.end(JSON.stringify([{ id: ID }]));
-  }
-
-  let rel = url;
-  if (rel === `/${ID}` || rel === `/${ID}/`) rel = '/';
-  else if (rel.startsWith(`/${ID}/`)) rel = rel.slice(ID.length + 1);
-
-  if (rel === '/manifest.json') {
-    res.writeHead(200, { 'content-type': MIME['.json'] });
-    return res.end(JSON.stringify(MANIFEST));
-  }
-
-  let file = normalize(join(DIST, rel));
-  if (file !== DIST && !file.startsWith(DIST + (process.platform === 'win32' ? '\\' : '/'))) {
-    res.writeHead(403);
-    return res.end('forbidden');
-  }
-  try {
-    const s = await stat(file);
-    if (s.isDirectory()) file = join(file, 'index.html');
-  } catch {
-    res.writeHead(404);
-    return res.end('not found (dist 未就绪? 等 vite build --watch 首次完成)');
-  }
-  try {
-    const body = await readFile(file);
-    res.writeHead(200, { 'content-type': MIME[extname(file).toLowerCase()] || 'application/octet-stream' });
-    res.end(body);
-  } catch {
-    res.writeHead(404);
-    res.end('not found');
-  }
-}).listen(PORT, () => {
-  console.log(`[__ID__] 插件源 → http://localhost:${PORT} (id=${ID})`);
-  console.log('[__ID__] 配合 host-dev --plugin http://localhost:' + PORT + ' 调试');
-});