@volcengine/amk-editor 0.0.1-beta.4 → 0.0.2-beta.0

package/README.md

@@ -1,139 +1,62 @@
 # @volcengine/amk-editor
-
-AMK 场景官方接入包：发布构建会内联底层编辑器运行时 UMD 与样式。公网业务方/demo **只需安装本包**，无需安装或访问内部编辑器包。弹层挂载使用 React 18/19 的 `createRoot`（兼容 React 19，不再使用已弃用的 `ReactDOM.render`）。
-
-## License
-
-AMK Editor SDK 是火山引擎 AI MediaKit 的商业配套软件。使用本 SDK 需要获得有效的火山引擎商业授权，具体条款参见 [LICENSE](./LICENSE)。商业授权咨询请联系 `service@volcengine.com`。
-
-本 SDK 使用的第三方开源组件仍分别适用其各自的许可证，第三方许可证不因本商业许可证而被替代。
-
+火山引擎 AI MediaKit 官方 Web 视频编辑器 SDK。
+## 安装
+```bash
+npm install @volcengine/amk-editor
+```
+需要 React 18 或 19。使用本 SDK 须获得有效的火山引擎商业授权，条款见 [LICENSE](./LICENSE)。
+本 SDK 使用的第三方开源组件仍分别适用其各自的许可证。
+## 快速开始
 ```ts
 import { AmkEditor } from '@volcengine/amk-editor';
-
 const editor = new AmkEditor({
   container,
-  projectId: 'xxx',
-  endpoint: 'https://your-proxy.example.com',
-  getLicenseUrl: 'https://license.example.com',
+  projectId: 'your-project-id',
+  endpoint: 'https://your-backend.example.com',
+  // 可选：自定义客户代理服务所需的请求头，SDK 不约定鉴权格式并会原样透传。
+  auth: {
+    getHeaders: async () => {
+      const response = await fetch('/api/session-token');
+      const { token } = await response.json();
+      return {
+        Authorization: `Bearer ${token}`,
+        'X-Customer-Id': 'your-customer-id',
+      };
+    },
+  },
   material: {
-    // 本地上传：入参 File[]，返回 MaterialItem[]；每项必须带 source_material_id，不必传 material_id
-    onUploadMaterial: async files => [],
-    // URL 上传：入参 string[]（弹窗内逗号/换行分隔），返回契约同上
-    onUploadUrlMaterial: async urls => [],
+    onUploadMaterial: async files => {
+      // 上传到业务存储后返回素材列表，每项必须带 source_material_id
+      return [];
+    },
+    onUploadUrlMaterial: async urls => {
+      return [];
+    },
     onRefreshPlayInfo: async materials =>
       materials.map(item => ({
         material_id: item.material_id, // 仅用于匹配，不要改写
-        url: '...', // 业务方按自己字段映射
-        // 以下 key 名只是推荐示例；使用自定义字段时读取自己的字段即可。
-        poster: item.poster_storage_key ? 'https://signed-poster-url' : item.poster,
-        sprite: item.sprite_storage_keys
-          ? { ...item.sprite, storeurls: ['https://signed-sprite-url'] }
-          : item.sprite,
+        url: '...',
+        poster: item.poster,
+        sprite: item.sprite,
       })),
-    // 抽帧临时链转存成长效地址（可选）；URL 和 key 会一起写回素材
-    onPersistExtractUrls: async ({ kind, urls, material }) => {
-      const result = await persistToBusinessStorage({ kind, urls, material });
-      return {
-        urls: result.urls,
-        // SDK 会把 materialPatch 原样合并并写回素材；字段名由业务决定。
-        materialPatch:
-          kind === 'poster'
-            ? { poster_storage_key: result.storageKeys[0] }
-            : { sprite_storage_keys: result.storageKeys },
-      };
-    },
   },
 });
 
-// 两种上传返回素材后，SDK 统一：
-// 1. addSketchItems → 素材面板
-// 2. createAmkMaterials → POST 远端仓库，并把服务端返回的 material_id 记到面板
-// 3. ensureMaterialExtractTasks → 缺/过期 poster/sprite 时抽帧；临时链上屏后可后台转存再 PUT
-
-// 转存完成后素材会保存：
-// - poster + poster_storage_key（推荐字段，可自定义）
-// - sprite.storeurls + sprite_storage_keys（推荐字段，可自定义）
-// 下一次 onRefreshPlayInfo 会收到这些 key，业务可据此重新生成有时效的访问 URL。
-// SDK 不读取上述两个 key，也不把它们当作固定 Schema。业务也可以返回：
-// materialPatch: {
-//   biz_storage: { poster_key: '...', sprite_keys: ['...'] },
-// }
-// 只需在 onRefreshPlayInfo 中按同一套自定义结构读取即可。
-
-// 导出：invokeTool('vibe-editing-common', { edit_param, callback_args? })
-// 开启画质增强时附带 callback_args（JSON 字符串），供代理后续调增强：
-// - standard/professional → { tool:"enhance-video", tool_version, resolution, fps }
-// - large-model → { tool:"enhance-video-generative", resolution, fps }
-// SDK 不负责增强任务本身。
-
-// 工程会从 {endpoint}/api/v1/editing/projects/{projectId} 加载并自动保存。
-// 通用 MediaKit 工具仍通过 POST {endpoint}/api/v1/tools/{toolName} 调用。
-await editor.invokeTool({
-  toolName: 'asr-subtitles',
-  params: {
-    input: {
-      type: 'video',
-      url: 'https://example.com/demo.mp4',
-    },
-  },
+// 运行时替换鉴权逻辑，后续所有 AMK 请求立即使用新的 Header。
+editor.setAuth({
+  getHeaders: () => ({ Authorization: 'Custom new-token' }),
 });
+// 清除鉴权 Header。
+editor.setAuth(null);
 ```
-
-## 构建
-
-先构建 SDK，再构建本包：
-
-```bash
-pnpm build-veveditor
-pnpm --filter @volcengine/amk-editor run build
-```
-
-产物位于 `dist/index.js`（含 veveditor 运行时）与 `dist/veveditor.css`（样式 side-effect）。
-
-- `projectId` / `endpoint` 均为必传；鉴权密钥留在业务服务端，由 `endpoint` 代理注入
-- 发布包不声明底层编辑器为运行时依赖；底层编辑器和 `video-editor` 已在构建阶段内联到 `dist/index.js`，类型声明也不依赖内部包。
-- 发布前必须使用 `npm pack --dry-run` 检查 tarball；公网用户只需要能访问 npm 公网源和业务方提供的 `endpoint`。
-
-## Editing API 对接
-
-初始化时，AMK Editor 会组合以下接口：
-
-- `GET /api/v1/editing/projects/:project_id`
-- `GET /api/v1/editing/projects/:project_id/materials`
-- `GET /api/v1/editing/projects/:project_id/editor`
-
-编辑过程中按资源分别写回：
-
-- 标题变更：`PATCH /projects/:project_id`
-- 素材变更：`PUT/DELETE /projects/:project_id/materials`
-- 剪辑参数变更：`PUT /projects/:project_id/editor`
-
-Editor 保存携带服务端 `revision`，SDK 内部串行提交保存请求，避免同一页面内的并发保存互相覆盖。素材身份字段分工：
-
-- `source_material_id`：业务必填主键。POST / PUT 请求体、DELETE 都用它；DELETE body 为 `{ source_material_ids: string[] }`
-- `material_id`：Editing API 自己生成的服务端 id。业务方不用传，传了也不会入库；SDK 只在 POST 成功后把返回值记到面板，供轨道内部关联
-- `source`：VeVEditor 轨道 `Source` / 加密 vid 等资源标识。Editing API 请求体里的 `source` 是 origin url，与面板 `source` 不是同一语义
-
-服务端响应缺少 `source` 时，加载工程仅使用 `material_id` 作为 `source` fallback。
-
-浏览器不应持有 AMK API Key。`endpoint` 应指向业务代理，由代理向 Editing API 注入：
-
-```http
-Authorization: Bearer <AMK_API_KEY>
-```
-
-`amkeditordemo` 默认使用与 Editing API 契约一致的内存 mock。联调真实服务时，在启动 demo 的服务端环境设置：
-
-```bash
-EDITING_API_UPSTREAM='https://your-editing-api.example.com' \
-AMK_API_KEY='<your-api-key>' \
-VITE_AMK_PROJECT_ID='<existing-project-id>' \
-pnpm --dir packages/amkeditordemo/fe dev
-```
-
-卸载时销毁：
-
+页面卸载时销毁：
 ```ts
 editor.destroy();
 ```
+## 接入说明
+- `projectId`、`endpoint` 必填。`endpoint` 指向你的业务代理。
+- `auth` 可选，用于浏览器访问客户代理时附加自定义请求头。SDK 不约定 Token 格式或 Header 名称，只会将 `getHeaders` 返回的内容原样合并到工程、素材、tools、tasks、导出等全部 AMK 请求中。运行期间可通过 `setAuth()` 替换，传入 `null` 或 `undefined` 可清除。
+- 本地上传、URL 导入由业务回调完成。返回的素材必须带业务主键 `source_material_id`，不必填写 `material_id`。
+- 播放地址、封面、雪碧图可能有时效。通过 `onRefreshPlayInfo` 返回新的访问地址。
+- 可选实现 `onPersistExtractUrls`：把抽帧得到的临时地址转存为业务长期地址，并随 `materialPatch` 写回自定义存储字段。
+- 可选配置 `export.qualityEnhancement: true` 以在导出弹窗展示「视频画质增强」；默认不展示。

package/dist/amk-editor.d.ts

@@ -1,5 +1,5 @@
 import './veveditor.css';
-import type { AmkEditorOptions, AmkProjectSnapshot, MaterialItem, VeVeditorInstance } from './types';
+import type { AmkEditorAuthConfig, AmkEditorOptions, AmkExportRequestResult, AmkProjectSnapshot, MaterialItem, VeVeditorInstance } from './types';
 import { type AmkI18nInstance } from './i18n';
 import { type AmkInvokeToolParams } from './api/client';
 export declare class AmkEditor {
@@ -9,6 +9,7 @@ export declare class AmkEditor {
     private editor?;
     private layout?;
     private exportModal?;
+    private exportRequestInFlight?;
     private asrProgressModal?;
     private confirmModal?;
     private emptyTrackConfirmInFlight?;
@@ -31,8 +32,18 @@ export declare class AmkEditor {
     private readonly asrStartingElementIds;
     /** sprite 抽帧任务轮询：key = material_id / source */
     private readonly spritePollingControllers;
+    private readonly posterPollingControllers;
+    /** TOS 上传完成前的素材面板占位：key = source_material_id。 */
+    private readonly tosUploadPlaceholders;
     /** 同一素材的封面/雪碧图转存结果串行写回，避免自定义字段互相覆盖。 */
     private readonly materialPatchQueues;
+    /** 等待批量落盘的素材；同一素材在窗口内只保留合并后的最新状态。 */
+    private readonly pendingMaterialPatches;
+    /** 包含等待中和提交中的最新本地状态，用于合并跨批次的并发字段。 */
+    private readonly latestMaterialPatches;
+    private materialPatchBatchTimer?;
+    /** 批次串行提交，避免先发批次晚返回后覆盖更新批次。 */
+    private materialPatchFlushQueue;
     /** 同一素材的 sprite 失败只处理一次，避免多个缩略图同时 403 重复建任务。 */
     private readonly thumbnailErrorInFlight;
     /** 前端抽帧封面缓存（不落盘）：key = materialKey，value = dataURL */
@@ -43,6 +54,10 @@ export declare class AmkEditor {
     private readonly posterCaptureControllers;
     /** 启动时加载的内置预设资源，供编辑器面板和 ASR 字幕复用。 */
     private presetLibrary;
+    /** 所有 TOS 素材共用一个刷新定时器，避免按素材创建大量 timer。 */
+    private tosSignedUrlRefreshTimer?;
+    private tosSignedUrlRefreshInFlight?;
+    private readonly handleVisibilityChange;
     private readonly handleTrackChanged;
     private readonly handleEditParamChanged;
     constructor(options: AmkEditorOptions);
@@ -50,8 +65,16 @@ export declare class AmkEditor {
     whenReady(): Promise<this>;
     getEditor(): VeVeditorInstance | undefined;
     getI18n(): AmkI18nInstance;
+    /** 替换后续 AMK 请求使用的鉴权 Header 提供器；传入 null/undefined 可清除。 */
+    setAuth(auth?: AmkEditorAuthConfig | null): void;
     /** 通用工具调用：POST /api/v1/tools/{toolName} */
     invokeTool<T = unknown>(options: AmkInvokeToolParams): Promise<T>;
+    /**
+     * Opens the existing export modal and resolves after the user confirms or cancels.
+     * Intended for Agent frontend tools (`request_export_task`). Header export still
+     * uses `open()` + direct submit and is unchanged.
+     */
+    requestExport(): Promise<AmkExportRequestResult>;
     /**
      * 获取工程全量参数（materials + editParam + projectName）。
      * 从 VeVeditor 当前素材/草稿快照读取；未挂载时回落内置拉取到的快照。
@@ -59,11 +82,13 @@ export declare class AmkEditor {
     getProject(): AmkProjectSnapshot;
     /**
      * 刷新素材播放信息（按需触发，如播放前 / 初始化）。
-     * - 未配置 `material.onRefreshPlayInfo`：直接从当前素材库返回匹配项，不发请求
-     * - 配置后：把完整素材列表传给业务方，业务方返回要覆盖的字段（url / sprite / poster 等）
+     * - TOS 直传素材会先使用临时 STS 重签私有对象 URL
+     * - 配置 `material.onRefreshPlayInfo` 后，宿主可继续覆盖播放字段
+     * - 两者都未配置时直接返回当前素材，不发请求
      * @param materialIdOrIds 单个 material_id、material_id 列表；省略则刷新当前全部有 material_id 的素材
      */
     refreshPlayInfo(materialIdOrIds?: string | string[]): Promise<MaterialItem | MaterialItem[] | undefined>;
+    private refreshPlayInfoInternal;
     private bootstrap;
     /** 内置拉取工程：project + materials + editor → 归一化 → 组装 initialData。 */
     private resolveAndApplyProject;
@@ -72,8 +97,20 @@ export declare class AmkEditor {
      * 再把轨道元素里的 URL 回填到最新值，完成后回写 editor 文档。
      */
     private refreshProjectOnInit;
+    /** TOS 私有桶签名刷新优先，宿主刷新回调随后可继续覆盖播放信息。 */
+    private refreshMaterialTargets;
+    /**
+     * 将重签后的素材 URL 按 material_id 同步到轨道节点并重建媒体节点。
+     * URL 是运行时数据：保存工程，但不产生撤销步骤。
+     */
+    private applyTrackMaterialUrls;
+    private getExpiringTosMaterialIds;
+    private scheduleTosSignedUrlRefresh;
+    private refreshExpiringTosUrls;
+    private readonly handlePreviewNodeRefresh;
     private resolveAndApplyPresetLibrary;
-    mount(): VeVeditorInstance;
+    mount(): VeVeditorInstance | undefined;
+    private mountVeVeditor;
     destroy(): void;
     private resolveConfig;
     /** 与 VeVeditor 同一套顶层扁平资源字段：boolean 面板开关 + 内部 xgplayer 组装 */
@@ -119,6 +156,26 @@ export declare class AmkEditor {
     private finishAsrAndCreateTextTrack;
     private startAsrPolling;
     private startAsrTask;
+    private resolveLocalFileType;
+    private createTosUploadPlaceholder;
+    /** 资产库选中后立即展示 0% 上传占位卡片，写入素材库成功后再切换为完成态。 */
+    private addSystemTosImportPlaceholders;
+    private removeTosUploadPlaceholders;
+    private hasTosUploadPlaceholders;
+    private uploadTosMaterials;
+    private extractToolResult;
+    private requirePositiveNumber;
+    private waitForToolTask;
+    private probeAsyncMetadata;
+    private prepareTosMaterial;
+    /** 将业务资产库的原始条目归一化为 SDK 素材；TOS 地址随后由 SDK 自行签发。 */
+    private normalizeSystemMaterial;
+    /**
+     * 资产库选择的 TOS 条目：同步签发播放 URL 并补齐基础元信息。
+     * 入参应为已 normalize 的素材；poster/sprite 在正式素材入库后后台处理。
+     */
+    private prepareSystemTosMaterials;
+    private ingestTosImportedMaterials;
     /**
      * 本地 / URL 上传入库后的统一收口：
      * POST 远端素材库 → 按 sprite/poster 判断发起抽帧并 PUT 更新。
@@ -132,6 +189,11 @@ export declare class AmkEditor {
     private persistUploadedMaterials;
     private isHttpUrl;
     private resolveDisplayPoster;
+    /**
+     * DataURL 已上屏时保留到本次会话结束，HTTP poster 只负责落库。
+     * 没有前端预览或当前缓存也是 HTTP 时，才切换到新的 HTTP 地址。
+     */
+    private cachePersistedPosterForDisplay;
     private withDisplayPosters;
     private blobToDataUrl;
     /** AMK 视频抽帧：指定第 0 帧并轮询任务结果。 */
@@ -140,9 +202,13 @@ export declare class AmkEditor {
     private captureVideoPosterFromFrontend;
     private isThumbnailFrontendDecodeEnabled;
     /**
-     * 封面只做运行时刷新，不写素材/工程：
-     * - enableThumbnailDecode=true：优先前端 Range + WebCodecs，失败再 AMK 第 0 帧兜底
-     * - 默认 false：只走 AMK SpecifiedFrames 第 0 帧接口
+     * 浏览器先解一帧仅作会话展示（DataURL 不落库）。
+     * 正式封面仍由 AMK 接口返回的 HTTP URL 负责持久化。
+     */
+    private previewPosterFromFrontend;
+    /**
+     * 正式封面只走 AMK 抽帧接口；返回可落库的 HTTP URL。
+     * 前端预览由 {@link previewPosterFromFrontend} 并行触发。
      */
     private captureVideoPosterFromUrl;
     /**
@@ -159,24 +225,30 @@ export declare class AmkEditor {
      * 统一入口：初始化 / 本地上传 / URL 上传拿到素材后，按 sprite/poster 判断是否抽帧。
      * - sprite / poster 缺失或 auth_key 过期：重新抽帧
      * - http 结果：先临时链上屏/PUT；若配置 onPersistExtractUrls 则后台转存换链
-     * - 前端 dataURL 不落盘
-     * - enableThumbnailDecode=true：跳过 sprite 接口，封面优先前端解码
+     * - 封面：浏览器可并行解一帧作会话预览（DataURL 不落盘）；正式封面始终走 AMK 接口 URL 落库
+     * - enableThumbnailDecode=true：跳过 sprite 接口，轨道缩略图走前端解码
      */
     private ensureMaterialExtractTasks;
     private createExtractFramesTask;
     private startSpritePolling;
+    private startPosterPolling;
     private buildSpriteFromExtractResult;
     private extractFirstSnapshotUrl;
     /**
-     * 时间轴 sprite 真实请求失败后的兜底：不解析 URL 的签名格式，直接以 Image.onerror 为准。
-     * 先让业务通过 onRefreshPlayInfo 更新素材；刷新后仍没有新的 sprite，再重新抽帧。
+     * 时间轴 sprite / 素材库 poster 真实请求失败后的兜底：不解析 URL 的签名格式，直接以 Image.onerror 为准。
+     * 先让业务通过 onRefreshPlayInfo 更新素材；刷新后仍没有新地址，再重新抽帧。
      */
     private handleThumbnailError;
+    /** 兼容时间轴元素与素材库 sketch 项，定位失败资源所属素材。 */
+    private resolveMaterialFromThumbnailError;
     private findMaterialByKey;
     private applyMaterialToPanel;
     private enqueueMaterialPatch;
     private patchMaterialRemote;
+    private flushPendingMaterialPatches;
     private clearSpriteTimer;
     private clearSpritePollingTimers;
+    private clearPosterTimer;
+    private clearPosterPollingTimers;
 }
 export declare function createAmkEditor(options: AmkEditorOptions): AmkEditor;

package/dist/api/client.d.ts

@@ -1,17 +1,30 @@
+import type { AmkEditorAuthConfig } from '../types';
 export type AmkApiClientOptions = {
     endpoint: string;
+    /** 客户业务代理鉴权；返回的自定义请求头会随每次请求动态获取。 */
+    auth?: AmkEditorAuthConfig;
+    /** 调用 tools 接口时写入请求体的产物存储目标，例如 `tos://bucket`。 */
+    mediaOutputDestination?: string;
 };
 export type AmkInvokeToolParams = {
     toolName: string;
     params?: Record<string, unknown>;
+    /** 默认注入配置的产物存储目标；纯探测类工具应设为 false。 */
+    includeMediaOutputDestination?: boolean;
     headers?: Record<string, string>;
     signal?: AbortSignal;
 };
 export declare class AmkApiClient {
     private readonly baseUrl;
+    private auth?;
+    private readonly mediaOutputDestination?;
     constructor(options: AmkApiClientOptions);
     getBaseUrl(): string;
+    /** 替换后续请求使用的鉴权 Header 提供器；传入 null/undefined 可清除。 */
+    setAuth(auth?: AmkEditorAuthConfig | null): void;
     invokeTool<T = unknown>(options: AmkInvokeToolParams): Promise<T>;
+    invokeSyncTool<T = unknown>(options: AmkInvokeToolParams): Promise<T>;
+    private mergeToolParams;
     /**
      * 查询异步任务：GET /api/v1/tasks/{task_id}
      * @see https://docs.volcengine.com/docs/6448/2278532
@@ -26,5 +39,6 @@ export declare class AmkApiClient {
         body?: unknown;
         signal?: AbortSignal;
     }): Promise<T>;
+    private resolveAuthHeaders;
 }
 export declare function createAmkApiClient(options: AmkApiClientOptions): AmkApiClient;

package/dist/assets/import-menu-chevron-down.svg

@@ -0,0 +1,3 @@
+<svg preserveAspectRatio="none" overflow="visible" style="display: block;" width="7.74994" height="4.24997" viewBox="0 0 7.74994 4.24997" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path id="Vector (Stroke)" d="M7.10984 0.109835C7.25628 -0.0366117 7.49366 -0.0366116 7.64011 0.109835C7.78656 0.256282 7.78656 0.493662 7.64011 0.640108L4.14011 4.14011C4.06978 4.21043 3.97443 4.24997 3.87497 4.24997C3.77552 4.24997 3.68016 4.21043 3.60983 4.14011L0.109835 0.640108C-0.0366116 0.493662 -0.0366117 0.256282 0.109835 0.109835C0.256282 -0.0366116 0.493662 -0.0366117 0.640108 0.109835L3.87497 3.3447L7.10984 0.109835Z" fill="#101013"/>
+</svg>

package/dist/assets/import-menu-local.svg

@@ -0,0 +1,3 @@
+<svg preserveAspectRatio="none" overflow="visible" style="display: block;" width="12" height="12" viewBox="0 0 12 12" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path id="Vector (Stroke)" d="M1.07402e-06 8.58474V7.84615C1.07402e-06 7.59125 0.206639 7.38461 0.461539 7.38461C0.71644 7.38461 0.923078 7.59125 0.923078 7.84615V8.58474C0.923078 9.10926 0.923257 9.47494 0.946515 9.75961C0.969334 10.0389 1.012 10.1994 1.07392 10.3209C1.20667 10.5814 1.41856 10.7933 1.67909 10.9261C1.80063 10.988 1.96111 11.0307 2.24039 11.0535C2.52506 11.0767 2.89074 11.0769 3.41527 11.0769H8.58474C9.10926 11.0769 9.47494 11.0767 9.75962 11.0535C10.0389 11.0307 10.1994 10.988 10.3209 10.9261C10.5814 10.7933 10.7933 10.5814 10.9261 10.3209C10.988 10.1994 11.0307 10.0389 11.0535 9.75961C11.0767 9.47494 11.0769 9.10926 11.0769 8.58474V7.84615C11.0769 7.59125 11.2836 7.38461 11.5385 7.38461C11.7934 7.38461 12 7.59125 12 7.84615V8.58474C12 9.09402 12.0006 9.50376 11.9736 9.83473C11.9461 10.1711 11.8875 10.4664 11.7482 10.7398C11.5269 11.174 11.174 11.5269 10.7398 11.7482C10.4664 11.8875 10.1711 11.9461 9.83474 11.9736C9.50376 12.0006 9.09402 12 8.58474 12H3.41527C2.90598 12 2.49624 12.0006 2.16527 11.9736C1.82889 11.9461 1.53357 11.8875 1.26022 11.7482C0.825997 11.5269 0.47305 11.174 0.251804 10.7398C0.112532 10.4664 0.0539263 10.1711 0.0264434 9.83473C-0.000595874 9.50376 1.01767e-06 9.09402 1.07402e-06 8.58474ZM5.53846 7.84615V1.57572L3.2494 3.86478C3.06916 4.04503 2.777 4.04503 2.59676 3.86478C2.41651 3.68454 2.41651 3.39238 2.59676 3.21214L5.67368 0.135216L5.74399 0.077524C5.81925 0.0273516 5.90821 1.16544e-07 6 0C6.12241 0 6.23977 0.0486612 6.32632 0.135216L9.40324 3.21214C9.58349 3.39238 9.58349 3.68454 9.40324 3.86478C9.223 4.04503 8.93084 4.04503 8.7506 3.86478L6.46154 1.57572V7.84615C6.46154 8.10105 6.2549 8.30769 6 8.30769C5.7451 8.30769 5.53846 8.10105 5.53846 7.84615Z" fill="#101013"/>
+</svg>

package/dist/assets/import-menu-system-arrow.svg

@@ -0,0 +1,3 @@
+<svg preserveAspectRatio="none" overflow="visible" style="display: block;" width="4.41019" height="5.64103" viewBox="0 0 4.41019 5.64103" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path id="Vector (Stroke)" d="M1.74355 1.57572V5.17949C1.74355 5.43439 1.95019 5.64103 2.20509 5.64103C2.45999 5.64102 2.66663 5.43439 2.66663 5.17949V1.57572L3.62236 2.53145C3.8026 2.71169 4.09476 2.71169 4.275 2.53145C4.45525 2.35121 4.45525 2.05905 4.275 1.87881L2.53141 0.135216C2.44486 0.0486612 2.3275 0 2.20509 0C2.11331 0 2.02434 0.0273516 1.94908 0.077524L1.87877 0.135216L0.135181 1.87881C-0.0450605 2.05905 -0.0450605 2.35121 0.135181 2.53145C0.315423 2.71169 0.607583 2.71169 0.787825 2.53145L1.74355 1.57572Z" fill="#101013"/>
+</svg>

package/dist/assets/import-menu-system-cloud.svg

@@ -0,0 +1,3 @@
+<svg preserveAspectRatio="none" overflow="visible" style="display: block;" width="13.0093" height="9.54572" viewBox="0 0 13.0093 9.54572" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path id="Vector" d="M0.721682 6.03213C0.52041 5.42761 0.459347 4.78521 0.54312 4.15359C0.626893 3.52197 0.853304 2.9177 1.2052 2.38655C1.5571 1.85539 2.02527 1.41128 2.57422 1.08786C3.12318 0.764439 3.73855 0.570185 4.3737 0.519811C5.00886 0.469438 5.64715 0.564267 6.24022 0.797115C6.8333 1.02996 7.36561 1.39472 7.79684 1.86377C8.22806 2.33282 8.54689 2.89384 8.72918 3.50436H9.80292C10.3821 3.5043 10.9459 3.69051 11.4111 4.0355C11.8763 4.38049 12.2183 4.86596 12.3864 5.42019C12.5545 5.97443 12.5399 6.56804 12.3447 7.11334C12.1496 7.65863 11.9344 8.0263 11.119 8.57093C10.3036 9.11555 7.8181 9.03484 7.8181 9.03484" stroke="black" stroke-width="1.01333" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/dist/assets/import-menu-url.svg

@@ -0,0 +1,3 @@
+<svg preserveAspectRatio="none" overflow="visible" style="display: block;" width="12.9997" height="12.9998" viewBox="0 0 12.9997 12.9998" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path id="Vector (Stroke)" d="M2.2056 5.58315C2.40085 5.38809 2.71742 5.38803 2.91263 5.58315C3.10783 5.77836 3.10772 6.09491 2.91263 6.29018L1.78633 7.41649C0.737757 8.46506 0.737873 10.165 1.78633 11.2134C2.8348 12.2618 4.53519 12.2618 5.58385 11.2134L6.70885 10.0877C6.90402 9.89237 7.22053 9.89192 7.41589 10.0871C7.61124 10.2822 7.61106 10.5987 7.41589 10.7941L6.29154 11.9204H6.29089C4.85194 13.3591 2.51846 13.3598 1.0793 11.921C-0.359868 10.482 -0.359663 8.14842 1.0793 6.70946L2.2056 5.58315ZM8.39896 3.89435C8.59424 3.69931 8.91081 3.69916 9.10599 3.89435C9.30115 4.08954 9.30101 4.40611 9.10599 4.60138L4.60143 9.10594C4.40622 9.30104 4.08964 9.301 3.8944 9.10594C3.69918 8.91071 3.69925 8.59417 3.8944 8.39891L8.39896 3.89435ZM6.70951 1.07925C8.14865 -0.359805 10.4814 -0.359693 11.9204 1.07925C13.3595 2.51826 13.3595 4.85116 11.9204 6.29018L10.7948 7.41649C10.5996 7.61156 10.283 7.61163 10.0878 7.41649C9.89259 7.22128 9.89266 6.90473 10.0878 6.70946L11.2134 5.58315L11.3085 5.48289C12.2608 4.42893 12.2292 2.80199 11.2134 1.78628C10.1648 0.737765 8.46506 0.73782 7.41654 1.78628L6.29024 2.91193C6.09497 3.10719 5.77846 3.1072 5.5832 2.91193C5.38805 2.71665 5.38797 2.40012 5.5832 2.2049L6.70951 1.07925Z" fill="#101013"/>
+</svg>

package/dist/export-modal-view.d.ts

@@ -5,7 +5,8 @@ export interface ExportModalViewProps {
     videoName: string;
     visible: boolean;
     t: AmkI18nInstance['t'];
+    showQualityEnhancement?: boolean;
     onConfirm: (params: ExportVideoParams) => Promise<void> | void;
     onClose: () => void;
 }
-export declare function ExportModalView({ videoName, visible, t, onConfirm, onClose, }: ExportModalViewProps): React.ReactElement;
+export declare function ExportModalView({ videoName, visible, t, showQualityEnhancement, onConfirm, onClose, }: ExportModalViewProps): React.ReactElement;

package/dist/export-modal.d.ts

@@ -5,12 +5,27 @@ export interface CreateExportModalOptions {
     videoName: string;
     onConfirm: (params: ExportVideoParams) => Promise<void> | void;
     t?: AmkI18nInstance['t'];
+    /** 是否展示「视频画质增强」。默认不展示。 */
+    showQualityEnhancement?: boolean;
 }
 export interface ExportModalController {
     open: () => void;
     close: () => void;
     destroy: () => void;
+    /**
+     * Opens the modal and waits for the user to confirm or cancel.
+     * Confirmed results are returned to the caller and do not invoke `onConfirm`
+     * (callers such as Agent tools own the submit path). Header `open()` still
+     * uses `onConfirm` for the direct-export path.
+     */
+    request: () => Promise<ExportModalRequestResult>;
 }
+export type ExportModalRequestResult = {
+    status: 'confirmed';
+    params: ExportVideoParams;
+} | {
+    status: 'cancel';
+};
 type SelectOption<T extends string> = {
     label: string;
     value: T;

package/dist/i18n/keys.d.ts

@@ -23,6 +23,8 @@ export declare const AMK_I18N_KEYS: {
     readonly import: {
         readonly local: "amk.import.local";
         readonly url: "amk.import.url";
+        readonly system: "amk.import.system";
+        readonly action: "amk.import.action";
     };
     readonly localUpload: {
         readonly title: "amk.localUpload.title";

package/dist/import-actions-dropdown-view.d.ts

@@ -0,0 +1,15 @@
+import React from 'react';
+export interface ImportDropdownAction {
+    key: string;
+    label: string;
+    onSelect: () => void;
+}
+export interface ImportActionsDropdownViewProps {
+    actions: ImportDropdownAction[];
+    label: string;
+}
+/**
+ * “导入”是固定的操作入口，而非表单选择值：菜单项点击后只触发对应回调。
+ * selection="none" 同时确保组件不会维护选中态或展示勾选图标。
+ */
+export declare function ImportActionsDropdownView({ actions, label, }: ImportActionsDropdownViewProps): React.ReactElement;

package/dist/import-actions.d.ts

@@ -1,4 +1,4 @@
-import type { MaterialItem } from './types';
+import type { MaterialItem, SystemMaterialItem } from './types';
 import type { AmkI18nInstance } from './i18n';
 interface MountImportActionsOptions {
     /** AMKEditor 自己的浮层容器；按钮仍挂在 VeVeditor 提供的工具栏插槽中。 */
@@ -6,7 +6,8 @@ interface MountImportActionsOptions {
     uploadAccept?: string;
     onUploadMaterial?: (files: File[]) => Promise<MaterialItem[]> | MaterialItem[];
     onUploadUrlMaterial?: (urls: string[]) => Promise<MaterialItem[]> | MaterialItem[];
-    onMaterialsImported: (materials: MaterialItem[]) => void;
+    onUploadFromSystem?: () => Promise<SystemMaterialItem[] | undefined | null> | SystemMaterialItem[] | undefined | null;
+    onMaterialsImported: (materials: SystemMaterialItem[]) => void | Promise<void>;
     t?: AmkI18nInstance['t'];
 }
 /** AMK 独立拥有素材导入 UI 与业务回调，VeVeditor 仅提供挂载容器和标准数据写入 API。 */

package/dist/index.d.ts

@@ -4,4 +4,4 @@ export type { AmkApiClientOptions, AmkInvokeToolParams } from './api/client';
 export type { PresetLibrary, PresetLibraryItem, PresetLibraryResourceKey, } from './api/preset-library';
 export { AMK_I18N_KEYS, createAmkI18n, tAmk, getGlobalAmkI18n, setGlobalAmkI18n, } from './i18n';
 export type { AmkI18nInstance, AmkI18nOptions, Locale, LocaleMessages, Messages, } from './i18n';
-export type { AmkEditorOptions, AmkEditorConfig, AmkEditorDecodeOptions, AmkEditorHeaderConfig, AmkEditorInternalConfig, AmkProjectSnapshot, ExportVideoParams, MaterialConfig, MaterialItem, PersistExtractUrlsResult, RecommendedExtractStorageFields, Theme, VeVeditorInstance, } from './types';
+export type { AmkEditorOptions, AmkEditorAuthConfig, AmkEditorStorageConfig, AmkEditorUploadSTSCredentials, AmkEditorConfig, AmkEditorDecodeOptions, AmkEditorExportConfig, AmkEditorHeaderConfig, AmkEditorInternalConfig, AmkExportRequestResult, AmkProjectSnapshot, ExportVideoParams, MaterialConfig, MaterialItem, PersistExtractUrlsResult, RecommendedExtractStorageFields, SystemMaterialItem, Theme, VeVeditorInstance, } from './types';