我需要安装哪些包

虽然仓库里有 13 个公开包，但做剪辑产品时通常只需要直接依赖三个。不要一开始就把所有底层包加进应用。

普通剪辑产品

{
  "dependencies": {
    "@aelionsdk/sdk": "1.2.0",
    "@aelionsdk/export": "1.2.0"
  },
  "devDependencies": {
    "@aelionsdk/vite-plugin": "1.2.0"
  }
}

它们分别解决：

包	什么时候会直接用到
@aelionsdk/sdk	创建 Project 和 Session，注册素材，连接 Canvas，播放，编辑和启动导出
@aelionsdk/export	创建内存或 OPFS Sink；定义远程导出适配器
@aelionsdk/vite-plugin	可选；让 Vite 正确打包 Renderer/Export Worker 和 AudioWorklet

非 Vite 宿主只安装 runtime 依赖，并按安装与工程配置 显式部署 runtimeAssets；不需要安装或模拟 Vite 插件。

业务组件里大部分导入都应该来自 @aelionsdk/sdk：

import {
  Aelion,
  ProductionMediaProvider,
  attachPreviewCanvas,
  createComposition,
  createProject,
} from '@aelionsdk/sdk';

模板和程序化成片优先使用 createComposition()；需要探测并导入真实媒体或操作 Schema 级实体时使用 createProject()。两者生成相同的 Project v1 文档，可以加载到 同一个 Session。

只有创建导出落盘目标时，才会直接使用 @aelionsdk/export：

import { OpfsSeekableSink, SeekableMemorySink } from '@aelionsdk/export';

开发 Material

如果你要制作 Filter、Transition、Effect 或 Generator，再增加：

{
  "dependencies": {
    "@aelionsdk/material-sdk": "1.2.0"
  }
}

这个包用于定义参数、搭建声明式 Graph、校验和生成 Material package。应用在运行时仍然通过 @aelionsdk/sdk 加载和使用 Material。

什么时候才需要底层包

以下场景可能需要直接使用引擎层：

• 你正在开发另一种宿主，而不是常规 Web 编辑器；
• 你需要自定义媒体容器、缓存或 RangeReader；
• 你要直接研究 Project 校验、事务或 Render IR；
• 你在为 AelionSDK 本身贡献代码。

包	提供的底层接口
@aelionsdk/core	时间换算、Diagnostic、JSON 类型和通用错误
@aelionsdk/project-schema	Project v1 类型、Schema 校验和 canonical JSON
@aelionsdk/transaction	编辑命令、事务、revision、undo/redo
@aelionsdk/render-ir	把 Project 编译成渲染执行图
@aelionsdk/media	RangeReader、MP4/WebM 索引、解码、缓存和代理选择
@aelionsdk/audio	PCM 混音、AudioWorklet 时钟和音频传输
@aelionsdk/renderer-worker	WebGL2/WebGPU 合成和 Worker 协议
@aelionsdk/capability	GPU、codec、音频和存储能力探测
@aelionsdk/material-compiler	Material Graph 校验和 GPU 程序编译

直接依赖这些包意味着你要自己管理版本兼容和资源生命周期。能通过 Session 完成的功能，不需要绕过 @aelionsdk/sdk。

版本和导入规则

• 一个应用内的所有 @aelionsdk/* 包使用完全相同的版本；
• 只从 package exports 导入，不使用 /src 或 /dist 路径；
• 版本升级时审阅 API Snapshot 和 CHANGELOG；
• 升级后至少重新跑一次媒体导入、预览、编辑和目标导出格式。

高层创作从使用 Composition API 创作开始。 每个包的主要导出见包与入口参考，单个函数和类型签名见侧栏中的 API Reference。