create-ax-trusted-plugin 1.0.1

package/README.md

@@ -0,0 +1,43 @@
+# @ax-npm/create-trusted-plugin
+
+可信(internal)插件**脚手架**:一条命令生成一个基于 `@ax-npm/host-trusted-sdk-v4` 的可信插件骨架
+(Module Federation remote + 共享 Vue + `activate(ctx)` + 自定义元素面板 + 调 `map.flyTo` + 遥测订阅)。
+
+## 用法
+```bash
+# 交互式(缺参数会提示输入 id/标题/锚点)
+npm create @ax-npm/trusted-plugin@latest my-panel
+
+# 非交互(传参)
+npm create @ax-npm/trusted-plugin@latest my-panel -- --title "我的面板" --anchor top-right
+```
+等价于直接跑 bin:`node bin/index.mjs my-panel --title "我的面板" --anchor top-right`。
+
+生成 `my-panel/` 后:
+```bash
+cd my-panel
+export GITLAB_TOKEN=<读权限 PAT>
+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`。
+
+## 发布(维护者)
+```bash
+export GITLAB_TOKEN=<写权限 PAT>
+npm publish   # publishConfig → GitLab 项目 1243
+```
+源码仓:GitLab 项目 1244。

package/bin/index.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// @ax-npm/create-trusted-plugin —— 可信(internal)插件脚手架。
+// 用法:
+//   npm create @ax-npm/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('  export GITLAB_TOKEN=<读权限 PAT>');
+    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);
+});

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "create-ax-trusted-plugin",
+  "version": "1.0.1",
+  "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"
+  }
+}

package/template/README.md

@@ -0,0 +1,28 @@
+# __ID__
+
+可信(internal)插件:经 Module Federation 融入宿主进程、共享宿主 Vue、拿完整 `ctx`。
+由 `@ax-npm/create-trusted-plugin` 脚手架生成。
+
+## 开发
+```bash
+export GITLAB_TOKEN=<读权限 PAT>
+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。

package/template/_gitignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+*.tgz

package/template/_npmrc

@@ -0,0 +1,4 @@
+# 安装 @ax-npm/* 走局域网 GitLab(192.168.1.209)实例端点(scope == 顶级群组 ax-npm)。
+# token 用环境变量注入:export GITLAB_TOKEN=<read_package_registry PAT>
+@ax-npm:registry=http://192.168.1.209/api/v4/packages/npm/
+//192.168.1.209/api/v4/packages/npm/:_authToken=${GITLAB_TOKEN}

package/template/index.html

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

package/template/manifest.json

@@ -0,0 +1,18 @@
+{
+  "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
+  }
+}

package/template/package.json

@@ -0,0 +1,28 @@
+{
+  "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\"",
+    "typecheck": "vue-tsc --noEmit"
+  },
+  "dependencies": {
+    "@ax-npm/host-trusted-sdk-v4": "^1.0.0",
+    "vue": "^3.4.0"
+  },
+  "devDependencies": {
+    "@ax-npm/host-dev-v4": "^1.0.4",
+    "@originjs/vite-plugin-federation": "^1.3.5",
+    "@vitejs/plugin-vue": "^5.0.0",
+    "concurrently": "^9.0.0",
+    "pinia": "^2.1.7",
+    "typescript": "^5.4.0",
+    "vite": "^5.2.0",
+    "vue-tsc": "^2.0.0"
+  }
+}

package/template/serve.mjs

@@ -0,0 +1,77 @@
+#!/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 + ' 调试');
+});

package/template/src/Panel.vue

@@ -0,0 +1,71 @@
+<script setup lang="ts">
+// 可信插件 UI:作为带 Shadow DOM 的自定义元素挂载。仅渲染共享状态 + 触发演示动作;
+// 能力接线在 activate(ctx) 里完成,经 window 事件桥回(自定义元素拿不到 ctx)。
+import { state } from './state';
+
+function ping() {
+  window.dispatchEvent(new CustomEvent('__ID__:ping'));
+}
+function flyTo() {
+  window.dispatchEvent(new CustomEvent('__ID__:flyto'));
+}
+</script>
+
+<template>
+  <div class="panel">
+    <div class="title">__TITLE__</div>
+    <p class="hint">可信插件 · 经 Module Federation 融入宿主 · 共享 Vue</p>
+
+    <div class="row">
+      <button @click="ping">调用自有能力 ping</button>
+      <span class="val">{{ state.lastPing || '—' }}</span>
+    </div>
+
+    <div class="row">
+      <button @click="flyTo">map.flyTo 北京</button>
+      <span class="val">{{ state.flyToNote || '—' }}</span>
+    </div>
+
+    <div class="tele">
+      <div class="tele-h">遥测 telemetry:fcs.basic</div>
+      <div v-if="state.telemetry" class="tele-b">
+        lon {{ state.telemetry.pos_lon ?? '—' }} ·
+        lat {{ state.telemetry.pos_lat ?? '—' }} ·
+        alt {{ state.telemetry.pos_alt ?? '—' }}
+      </div>
+      <div v-else class="tele-b muted">等待遥测…</div>
+    </div>
+  </div>
+</template>
+
+<style>
+.panel {
+  box-sizing: border-box;
+  height: 100%;
+  padding: 12px 14px;
+  font: 13px/1.5 system-ui, sans-serif;
+  color: var(--color-text, #e6edf3);
+  background: var(--color-surface, rgba(20, 26, 33, 0.82));
+  border: 1px solid var(--color-border, rgba(255, 255, 255, 0.12));
+  border-radius: 10px;
+  backdrop-filter: blur(8px);
+}
+.title { font-weight: 600; font-size: 14px; }
+.hint { margin: 4px 0 10px; opacity: 0.7; font-size: 11px; }
+.row { display: flex; align-items: center; gap: 8px; margin-bottom: 8px; }
+button {
+  cursor: pointer;
+  padding: 4px 10px;
+  border-radius: 6px;
+  border: 1px solid var(--color-border, rgba(255, 255, 255, 0.18));
+  background: var(--color-accent, #2f6feb);
+  color: #fff;
+  font-size: 12px;
+}
+button:hover { filter: brightness(1.08); }
+.val { font-variant-numeric: tabular-nums; opacity: 0.9; }
+.tele { margin-top: 10px; padding-top: 8px; border-top: 1px dashed var(--color-border, rgba(255, 255, 255, 0.12)); }
+.tele-h { font-size: 11px; opacity: 0.7; margin-bottom: 2px; }
+.tele-b { font-variant-numeric: tabular-nums; }
+.muted { opacity: 0.5; }
+</style>

package/template/src/index.ts

@@ -0,0 +1,41 @@
+// 可信插件入口(打成 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 注册的命令/事件由运行时自动回收。
+}

package/template/src/state.ts

@@ -0,0 +1,16 @@
+// activate(ctx) 与 Panel 自定义元素之间的共享响应式状态。
+// 二者 import 同一模块 → 同一宿主 vue reactive(MF 共享,单例),activate 更新即触发 Panel 重渲染。
+import { reactive } from 'vue';
+
+export interface FcsBasic {
+  pos_lon?: number;
+  pos_lat?: number;
+  pos_alt?: number;
+  [k: string]: unknown;
+}
+
+export const state = reactive({
+  lastPing: '',
+  telemetry: null as FcsBasic | null,
+  flyToNote: '',
+});

package/template/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "forceConsistentCasingInFileNames": true,
+    "types": []
+  },
+  "include": ["src", "vite.config.ts"]
+}

package/template/vite.config.ts

@@ -0,0 +1,33 @@
+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,
+  },
+});