EarthSDK3 Assets

EarthSDK3 资源管理插件，支持自动检测并适配 Vite、Webpack、Rspack 等主流构建工具。

安装

npm install earthsdk3-assets

特性

• 🔍 自动检测构建工具 - 根据项目依赖自动选择对应插件
• ⚡ 支持 Vite - 原生 ESM，极速开发体验
• 📦 支持 Webpack - 兼容 Webpack 5.x
• 🚀 支持 Rspack - 字节跳动出品，Webpack API 兼容
• 💾 增量下载 - 智能缓存，只下载变更资源
• 🎯 零配置 - 开箱即用，自动注入脚本
• 📁 不污染项目 - 开发模式不创建物理文件
• 🌐 内网环境支持 - 网络不可用时自动使用本地缓存
• ⚙️ 灵活配置 - 支持自定义资源路径
• 📂 自定义资产 - 通过 customAssets/ 目录附带本地资源，构建时自动拷贝到输出目录

使用方法

自动检测（推荐）

插件会自动检测你项目使用的构建工具：

Vite 项目

// vite.config.ts
import earthsdkAssets from 'earthsdk3-assets';

export default {
    plugins: [
        earthsdkAssets()
    ]
};

Webpack 项目

// webpack.config.js
const earthsdkAssets = require('earthsdk3-assets');

module.exports = {
    plugins: [
        earthsdkAssets()
    ]
};

Rspack 项目

// rspack.config.js
const earthsdkAssets = require('earthsdk3-assets');

module.exports = {
    plugins: [
        earthsdkAssets()
    ]
};

手动指定构建工具

如果自动检测失败，可以强制指定：

// Vite
import earthsdkAssets from 'earthsdk3-assets';
export default {
    plugins: [earthsdkAssets({ forceTool: 'vite' })]
};

// Webpack
const earthsdkAssets = require('earthsdk3-assets');
module.exports = {
    plugins: [earthsdkAssets({ forceTool: 'webpack' })]
};

// Rspack
const earthsdkAssets = require('earthsdk3-assets');
module.exports = {
    plugins: [earthsdkAssets({ forceTool: 'rspack' })]
};

自定义配置

// Vite 示例
import earthsdkAssets from 'earthsdk3-assets';

export default {
    plugins: [
        earthsdkAssets({
            forceTool: 'vite',
            assetsPath: 'custom/assets',           // 资源文件拷贝路径，默认为 'earthsdk3-assets'
            scriptSrc: './custom/assets/earthsdk3-assets.js'  // script 标签路径
        })
    ]
};

子路径导入

也可以直接导入特定构建工具的插件：

// Vite
import earthsdkAssets from 'earthsdk3-assets/vite';

// Webpack
const earthsdkAssets = require('earthsdk3-assets/webpack');

// Rspack
const earthsdkAssets = require('earthsdk3-assets/rspack');

自定义资产目录 (customAssets)

customAssets/ 是位于包根目录的本地自定义资产目录，用于存放不参与远程下载、由用户自行维护的资源（例如项目专属的图片、模型、配置等）。

• 开发模式：通过虚拟路径直接访问，URL 为 /earthsdk3-assets/customAssets/...（Vite 中间件按需返回；Webpack/Rspack 将目录加入编译产物）。
• 生产模式：构建时将整个 customAssets/ 目录递归拷贝到 dist/earthsdk3-assets/customAssets/，且不依赖远程清单——即使资源清单缺失或内网无法下载，自定义资产仍会正常拷贝。
• 发布：customAssets/ 已包含在 package.json 的 files 字段中，会随包发布到 npm。

目录内容可任意组织（支持多级子目录），例如：

earthsdk3-assets/
└── customAssets/
    ├── logo.png
    └── models/
        └── demo.glb

访问时对应路径为 /earthsdk3-assets/customAssets/logo.png、/earthsdk3-assets/customAssets/models/demo.glb，开发与生产环境路径一致。

skills 目录 (copySkills)

skills/ 是位于包根目录的 agent 文档目录，包含 SKILL.md 与对象/类型参考文档，供 earthsdk-ui / MCP agent 通过 fetchSkill 等工具查询 EarthSDK3 对象用法（参考路径如 ${earthsdk3-assets-script-dir}/skills/earthsdk3-usage/）。

• 默认不拷贝：copySkills 默认为 false，构建时不将 skills/ 拷贝到输出目录。不使用 agent 的项目无需配置，构建产物更精简。
• 需要 agent 时开启：earthsdkAssets({ copySkills: true })，构建时会将整个 skills/ 目录递归拷贝到 outDir/earthsdk3-assets/skills/。
• 开发模式：Vite 通过虚拟路径按需提供（不落盘），Webpack/Rspack 仅在 copySkills: true 时将该目录加入编译产物。

⚠️ 破坏性变更：此前的版本无条件拷贝 skills/。升级后若项目依赖 agent 读取 skills，必须显式配置 copySkills: true，否则打包产物中将缺少该目录。

// 需要 agent 技能文档时
import earthsdkAssets from 'earthsdk3-assets';
export default {
    plugins: [
        earthsdkAssets({
            copySkills: true
        })
    ]
};

配置选项

| 选项 | 类型 | 默认值 | 说明 | |------|------|--------|------| | forceTool | 'vite' \| 'webpack' \| 'rspack' \| 'vue-cli' | 自动检测 | 强制指定构建工具 | | assetsPath | string | 'earthsdk3-assets' | 资源文件拷贝到输出目录的路径 | | scriptSrc | string | './earthsdk3-assets/earthsdk3-assets.js' | 注入到 HTML 的 script 标签 src 属性 | | copySkills | boolean | false | 是否将 skills/ 目录拷贝到构建输出目录（供 agent 使用） |

工作原理

开发模式

1. 资源下载 - 从远程服务器下载 EarthSDK3 所需的静态资源到 node_modules/earthsdk3-assets/
2. 智能缓存 - 使用 MD5 校验，只下载变更的文件
3. 虚拟路径服务 - 开发服务器提供 /earthsdk3-assets/* 路径的资源服务，不创建物理文件
4. HTML 注入 - 自动在 HTML 中注入 <script src="./earthsdk3-assets/earthsdk3-assets.js">

生产模式

1. 资源拷贝 - 构建时根据资源清单将资源拷贝到 dist/earthsdk3-assets/ 目录
2. 自定义资产附带拷贝 - 将本地 customAssets/ 目录递归拷贝到 dist/earthsdk3-assets/customAssets/（不依赖远程清单，离线/内网环境同样生效）
3. HTML 注入 - 自动在 HTML 中注入脚本引用

内网环境支持

当项目从外网拷贝到内网环境后，如果无法访问远程资源服务器：

1. 插件会检测本地缓存文件是否存在
2. 如果缓存存在，使用本地缓存继续运行
3. 如果缓存不存在，抛出异常

目录结构

earthsdk3-assets/
├── src/
│   ├── core/
│   │   ├── downloadAssets.js     # ESM 版本资源下载核心逻辑
│   │   ├── downloadAssets.cjs    # CommonJS 版本
│   │   ├── copyAssets.js         # ESM 版本文件拷贝工具
│   │   └── copyAssets.cjs        # CommonJS 版本
│   ├── plugins/
│   │   ├── vite.js               # Vite 插件 (ESM)
│   │   ├── webpack.cjs           # Webpack 插件 (CommonJS)
│   │   └── rspack.cjs            # Rspack 插件 (CommonJS)
│   ├── index.js                  # ESM 入口（自动检测）
│   ├── index.cjs                 # CommonJS 入口
│   └── index.d.ts                # TypeScript 类型声明
├── glb/                          # 下载的 GLB 模型资源
├── img/                          # 下载的图片资源
├── customAssets/                 # 本地自定义资产目录（不参与远程下载，构建时附带拷贝到输出目录）
├── skills/                       # agent 文档目录（默认不拷贝，需配置 copySkills: true）
├── earthsdk3-assets.js           # 资源加载器脚本（远程下载）
├── .assets-version               # 版本缓存文件
├── .assets-manifest.json         # 资源清单缓存
└── package.json

构建工具检测优先级

插件按以下顺序检测构建工具：

1. Vite - 检查 vite 依赖或 vite.config.* 文件
2. Rspack - 检查 @rspack/core 依赖或 rspack.config.* 文件
3. Vue CLI - 检查 @vue/cli-service 依赖（基于 Webpack 5）
4. Webpack - 检查 webpack 依赖或 webpack.config.* 文件

注意事项

• Webpack/Rspack 项目需要安装 html-webpack-plugin 或 @rspack/plugin-html 以支持 HTML 脚本注入
• Vue CLI 项目内置 html-webpack-plugin，无需额外安装
• 所有构建工具插件均为可选依赖，未使用的构建工具不会引起报错
• 开发模式下资源通过虚拟路径访问，不创建物理文件到项目目录
• 生产模式下资源会根据清单文件拷贝到构建输出目录，customAssets/ 目录也会附带拷贝（不依赖清单）
• 内网环境下如果已有缓存，即使无法访问外网也能正常运行

许可证

ISC