superx-ext

superx-ext 是 SuperX 扩展的开发、构建、验证和发布 CLI。它把扩展源码编译成 SuperX 可加载的运行资产，并在发布前生成隔离 staging 做真实加载验证。

基本流程

npm install
npm run build
superx-ext build .
superx-ext verify-release .
superx-ext publish .

常用命令：

• superx-ext create extension <id>：创建完整扩展 starter（公开 npm 包默认不内置 preview 宿主）。
• superx-ext create user-extension <id>：创建轻量用户扩展，可直接放入 SuperX 用户扩展目录；默认生成 tools，可用 --features tools,parts,app 指定能力。
• superx-ext create preview <name>：创建本地 preview 宿主（仅内部源码仓库可用，公开 npm 包不发布 preview 模板源码）。
• superx-ext build .：编译当前扩展。
• superx-ext build . --install：先执行 npm install --ignore-scripts --no-audit --no-fund，再编译。
• superx-ext prepare-runtime .：为 tools 生成外置运行时依赖。
• superx-ext verify-release .：从发布 staging 隔离加载扩展，验证发布包可用。
• superx-ext publish .：构建 staging、校验、打包并上传。

superx-ext create extension <id> 生成的模板内置 npm run verify-release。需要验证 native/npm 包、二进制或关键执行路径时，在根 manifest.json 添加 release.smokeTest。

superx-ext create user-extension <id> 更适合 SuperX Agent 或自动化工具按需生成扩展，例如：

superx-ext create user-extension my-tool --features tools,parts
superx-ext create user-extension my-app --features tools,app --app-activations direct

自动化场景可以传 JSON，并用 --json 获取结构化结果：

superx-ext create user-extension my-tool \
  --payload-file payload.json \
  --json

npm 约定

SuperX 扩展统一使用 npm。扩展根目录提交 package-lock.json，不需要 pnpm-workspace.yaml，也不需要在 package.json 固定 packageManager。

资产子目录仍然可以有自己的 package.json，但依赖统一由扩展根目录安装。模板里的子资产脚本会回到根目录执行：

{
  "scripts": {
    "build": "npm --prefix .. run build",
    "dev": "npm --prefix .. run dev"
  }
}

依赖策略

默认策略：普通第三方依赖直接打进 tools/dist/index.mjs。开发者按正常 Node/Vite 心智写代码：

import { PDFDocument } from 'pdf-lib'

并把包写入 tools/package.json.dependencies。构建时，superx-ext build 会把普通依赖打进 dist，发布包不会再要求 SuperX 主程序解析这些依赖。

只有这些包应该显式外置：

• native 包或带平台二进制的包，例如 sharp
• 依赖 install script、optional platform package、wasm、worker 或大资源目录的包
• 运行时必须保留原始包目录结构的包
• 明显不适合内联进单个 JS bundle 的大包

外置依赖仍然先声明在 dependencies，再写入 superx.tools.externalDependencies：

{
  "name": "my-extension-tools",
  "private": true,
  "type": "module",
  "dependencies": {
    "@pdf-lib/fontkit": "^1.1.1",
    "pdf-lib": "^1.17.1",
    "pdfjs-dist": "^5.7.284"
  },
  "superx": {
    "tools": {
      "externalDependencies": ["pdfjs-dist"]
    }
  }
}

上例中：

• pdf-lib 和 @pdf-lib/fontkit 是普通依赖，默认打进 tools/dist/index.mjs
• pdfjs-dist 是外置依赖，发布 staging 会包含真实 tools/node_modules/pdfjs-dist

外置运行时依赖

发布 staging 时，superx-ext 不从源码目录复制 tools/node_modules，也不裁剪 pnpm symlink 结构。它会创建一个临时最小 npm 包，只包含 superx.tools.externalDependencies，然后执行：

npm install --omit=dev --include=optional --no-audit --no-fund

关键规则：

• 不使用 --omit=optional，因为很多 native/binary 包依赖 optional platform package。
• 不使用 --ignore-scripts，因为 sharp、ffmpeg-static 等包可能需要 install script 准备二进制。
• 临时包只包含显式 external 的依赖，普通依赖不会重复进入 runtime node_modules。
• 如果源码目录已有对应包的已安装版本，发布器优先用该精确版本生成临时 npm 包；否则使用 tools/package.json.dependencies 中的版本范围。
• 生成后复制真实扁平 node_modules 到 staging 的 tools/node_modules。

这个模型和 Electron 扩展/桌面应用的常见做法一致：普通 JS bundle，native/binary 依赖保留真实 node_modules。

源码压缩与发布边界

superx-ext build 对运行代码做源码级压缩：

• app 和 parts 使用 Vite，默认 minify: 'esbuild'
• tools 使用 Rolldown，默认 minify: true
• 默认关闭 sourcemap

市场发布不是把扩展源码目录原样压缩上传，而是先生成白名单 staging。发布 staging 只复制运行时文件，并过滤 dist 里的 .map、.d.ts、.ts、.tsx、.vue 等开发/源码辅助文件。

扩展自有代码在发布包里应该只有压缩后的运行时代码和必要资源。tools/node_modules 按第三方 npm 包原样部署，可能包含依赖包自带的类型文件、源码或 sourcemap；这不属于扩展源码泄露边界。

发布 staging 内容

发布 staging 会包含：

• 根 manifest.json
• tools/dist
• tools/manifest.json
• tools/package.json
• tools/node_modules，仅当工具声明 superx.tools.externalDependencies 时由 npm isolated install 生成
• parts/*/dist
• parts/*/manifest.json
• app/dist
• app/manifest.json
• skills
• bin
• mcp / mcps

verify-release 会从 staging 加载工具资产。如果有 tools/manifest.json 但加载不到任何工具，会直接失败。

发布 smoke test

verify-release 默认保持轻量，只检查发布 staging 可加载。对依赖 native/npm 包或动态执行路径的扩展，可以在根 manifest.json 中声明最小 smoke 脚本：

{
  "release": {
    "smokeTest": "scripts/release-smoke.mjs"
  }
}

superx-ext verify-release 和 superx-ext publish 会在 staging 加载通过后执行：

node scripts/release-smoke.mjs <stagingDir>

同时设置：

• SUPERX_EXTENSION_DIR：扩展源码目录
• SUPERX_RELEASE_STAGING_DIR：发布 staging 目录

smoke 脚本只做 1-2 个关键执行验证，例如生成临时文件再读回结果。完整集成测试不要塞进发布 smoke。

二进制文件

纯 JS/npm 依赖适合放在 tools/package.json.dependencies，默认打包进 tools/dist/index.mjs。平台二进制适合放在扩展 bin/ 下，并在 manifest.json.runtime.binaries 中声明。

推荐目录：

bin/
  darwin-arm64/
    tool-name
  win32-x64/
    tool-name.exe
  linux-x64/
    tool-name

工具运行时应根据 process.platform 和 process.arch 选择对应二进制。不要在工具里猜测不存在的旧路径。

开发者建议

• 小型纯 JS 依赖：只声明到 tools/package.json.dependencies，默认打包。
• 大型 JS 依赖：先尝试默认打包；只有确实不适合打包时，再加入 superx.tools.externalDependencies。
• native npm 依赖：声明到 dependencies，并加入 superx.tools.externalDependencies；需要跨平台时验证每个平台的发布包。
• native/npm 包、二进制或动态执行路径：添加最小 release.smokeTest，用 staging 真实执行关键路径。
• 独立官方二进制：放 bin/<platform>-<arch>/，不要放进 node_modules。
• 不要写扩展专属脚本搬运 node_modules，统一走 superx-ext verify-release 和 superx-ext publish。

故障排查

externalDependencies 未声明在 dependencies：

tools/package.json 中 superx.tools.externalDependencies 声明了未在 dependencies 中出现的依赖: pdfjs-dist

处理方式：外置依赖必须同时出现在 dependencies 中。

npm 不可用：

未找到可用的 npm。请先安装 Node.js/npm，SuperX 扩展发布需要用 npm 生成外置运行时依赖。

处理方式：安装 Node.js/npm，或确认 npm 在 PATH 中。

外置包安装后缺失：

npm install 未生成外置运行时依赖: sharp

处理方式：确认依赖名和版本正确，不要禁用 optional dependencies 或 install scripts。

发布包加载不到工具：

发布 staging 中存在 tools/manifest.json，但没有加载到任何工具

处理方式：先运行 superx-ext build .，再运行 superx-ext verify-release .。如果仍失败，检查 tools/dist/index.mjs 是否导出 defineExtension(...)。