create-ax-trusted-plugin

可信(internal)插件脚手架:一条命令生成一个基于 @ax-npm/host-trusted-sdk-v4 的可信插件骨架 (ESM 直出 activate + 自带 Vue + 自定义元素面板 + host.ts 指令出口 + 自有能力 token(SSOT)

• 调 map.flyTo + 遥测订阅 + 共享文案/样式/px→vw 适配;dev 走裸 vite,原生 sourcemap、无构建步)。

脚手架本身已发公网 npm,生成这步零配置;生成出的工程才走私有源(192.168.1.209 GitLab)拉 @ax-npm/* 依赖,届时只需一个 GITLAB_TOKEN(无需手建任何 .npmrc,工程自带)。

用法

# 交互式(缺参数会提示输入 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 选一行):

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/bottom-center/left-center/right-center/center。

生成内容

template/ 经占位替换(__ID__/__TITLE__/__ANCHOR__)后落地: src/{index.ts,Panel.vue,state.ts,host.ts,tokens.ts,i18n.ts,assets/assets.d.ts,locales/*}、 manifest.config.ts(清单源:trust:internal、entry:main.js)、vite.config.ts(一行调 trustedPluginConfig 预设)、 postcss.config.cjs(px→vw)、package.json、tsconfig.json、.npmrc、.gitignore、README.md。

要点(与 ax-plugins/ 下 func-panel / head-info / hud / aircraft / land-route-edit 等在产插件保持一致):

• 组件拿不到 ctx,上行指令走 src/host.ts(activate 里 bindHost(ctx),组件直接 host.execute(...)), 下行数据走 src/state.ts 共享响应式状态 —— 取代旧式 window 事件桥。
• 自有能力在 src/tokens.ts 用 defineCommand 定义 token,register/contributes/uses 都引 token, 不手抄字符串(类型化 API 下手抄字符串编译不过)。
• 能力 token 与 payload 类型都从 SDK import:host-trusted-sdk 1.2.0 起整体转出 capability-kit 的插件作者面(FCS_EVENTS/STAGE_EVENTS/FcsBasicTelemetry/…),模板因此不再 dependency @ax-npm/capability-kit-v4。可换能力(地图等)的 token 不走 SDK 中转,由该能力自己的契约包 提供 —— 模板默认带 @ax-npm/map-contract-v4(演示 MAP_COMMANDS.FLY_TO),不用地图删掉即可。
• 共享包三件套(在产插件都在用):@ax-npm/shared-i18n-v4 公用飞控文案(与自家私有文案合并进 同一 vue-i18n,t() 两边 key 都有补全)、@ax-npm/plugin-ui-v4 表单样式 .axf-*(SFC <style> 里 不带 scoped 的构建期 @import,规则内联进 shadow root)、postcss-px-to-viewport-8-plugin 按 1920 基准把 px 换算成 vw(高分屏适配)。用不上的删依赖与对应 import 即可。
• 清单 passthrough: true 时,Shadow DOM 内不透明实体须显式 pointer-events: auto (生成的面板靠 .root 透明层 + .axf-panel 自带 auto 两层示范),否则整块面板不接事件。

发布(维护者)

脚手架包发公网 npm(publishConfig 已指向 registry.npmjs.org、access: public):

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 不可路由,非机密),发公网后会公开可见。