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

package/README.md

@@ -13,17 +13,11 @@ const editor = new AmkEditor({
   container,
   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',
-      };
-    },
-  },
+  // 可选：每次请求前动态获取，SDK 不解析或改写返回的 Header。
+  getHeaders: async () => ({
+    Authorization: `Bearer ${await getLatestToken()}`,
+    'X-Customer-Id': 'your-customer-id',
+  }),
   material: {
     onUploadMaterial: async files => {
       // 上传到业务存储后返回素材列表，每项必须带 source_material_id
@@ -42,12 +36,24 @@ const editor = new AmkEditor({
   },
 });
 
-// 运行时替换鉴权逻辑，后续所有 AMK 请求立即使用新的 Header。
-editor.setAuth({
-  getHeaders: () => ({ Authorization: 'Custom new-token' }),
+
+// 外部工具栏可复用素材面板的同一套导入弹窗与入库链路。
+editor.requestMaterialImport('local'); // 本地文件选择 + 本地上传确认弹窗
+editor.requestMaterialImport('url'); // URL 上传弹窗
+editor.requestMaterialImport('system'); // 业务资产库回调
+
+// 只有这个外部调用触发的导入成功后才回调；编辑器自身的导入按钮不会触发它。
+editor.requestMaterialImport('local', {
+  onMaterialsImported: materials => {
+    console.log('本次已入库素材', materials);
+  },
 });
-// 清除鉴权 Header。
-editor.setAuth(null);
+
+// 从服务端重新拉取当前工程，并热更新素材与 Track（不写入撤销历史）。
+await editor.refreshProject();
+
+// 查询由编辑器操作创建的异步任务；复用相同的 endpoint 和 getHeaders。
+const exportTask = await editor.getTask('your-task-id');
 ```
 页面卸载时销毁：
 ```ts
@@ -55,8 +61,27 @@ editor.destroy();
 ```
 ## 接入说明
 - `projectId`、`endpoint` 必填。`endpoint` 指向你的业务代理。
-- `auth` 可选，用于浏览器访问客户代理时附加自定义请求头。SDK 不约定 Token 格式或 Header 名称，只会将 `getHeaders` 返回的内容原样合并到工程、素材、tools、tasks、导出等全部 AMK 请求中。运行期间可通过 `setAuth()` 替换，传入 `null` 或 `undefined` 可清除。
+- `theme` 默认 `light`。未传或传入其他值时按浅色渲染；只有显式 `theme: 'dark'` 才走暗色。
+- 产物是单文件 ESM。依赖里的 AMD `define(["./core"])` 已在构建时剔除，避免 Next.js / webpack 误解析不存在的 `dist/core.js`。
+- `getHeaders` 可选，每次请求前都会重新调用；SDK 不解析、不缓存、不改写返回值，仅将其合并到发往 `endpoint` 的工程、素材、tools、tasks、导出等请求中。闭包内 Token 更新会自动用于下一次请求。
 - 本地上传、URL 导入由业务回调完成。返回的素材必须带业务主键 `source_material_id`，不必填写 `material_id`。
 - 播放地址、封面、雪碧图可能有时效。通过 `onRefreshPlayInfo` 返回新的访问地址。
+- 可选实现 `onMaterialsImported`：素材成功入库后回调已合并 `material_id` 的列表；可用于把新素材挂到对话草稿。失败或取消不会触发。
 - 可选实现 `onPersistExtractUrls`：把抽帧得到的临时地址转存为业务长期地址，并随 `materialPatch` 写回自定义存储字段。
 - 可选配置 `export.qualityEnhancement: true` 以在导出弹窗展示「视频画质增强」；默认不展示。
+- 可选配置 `header.mount` 为外部 DOM 节点，将顶栏渲染到该节点（而不是编辑器内部），便于宿主做全宽顶栏；`header.show: false` 仍可完全隐藏顶栏。
+- 可选配置 `header.onTitleUpdateSuccess`：工程名 PATCH 成功后回调 `{ projectId, title }`。保存成功前编辑器继续展示旧名称；保存失败不会修改编辑器标题，也不会触发回调。
+- 可选配置 `header.exportTaskList: false` 隐藏导出任务列表入口；默认开启。关闭后不会展示任务列表按钮，也不会启动导出任务列表查询与轮询。
+- `requestMaterialImport(type, options?)` 返回是否成功触发已配置入口；`local`、`url`、`system` 分别要求存在本地上传能力、`onUploadUrlMaterial`、`onUploadFromSystem`。外部入口不会复制上传逻辑，仍走素材面板相同的回调、TOS 签名、素材入库与元信息处理。可选的 `options.onMaterialsImported` 只对这一次外部触发有效，编辑器自身的导入按钮不会调用它。
+- `toolbar.customItems` 的只读态不会自动置灰。需要禁用时在该项 `disabled({ readonly })` 里自行返回 true（例如 `disabled: ({ readonly }) => readonly`）。录音中仍会全局锁定自定义项。内置 ASR 按钮在只读时仍会禁用。
+- `refreshProject()` 会等待当前保存队列结束，再重新拉取工程、刷新临时播放地址并热更新素材与 Track；远端 Track 不会写入本地撤销历史，也不会被自动保存回服务端。
+- `getTask(taskId, options?)` 查询 `GET /api/v1/tasks/{task_id}`，复用编辑器初始化时的 `endpoint` 与 `getHeaders`；`options.signal` 可在宿主任务卡卸载时取消轮询请求。
+- 配置 `projectId` 后，API Client 会把 `invokeTool`、`invokeSyncTool` 的成功响应以及 `getTask` 的轮询结果，以 schema v2 best-effort 上报到 `POST /api/v1/editing/projects/{project_id}/tasks`。记录包含 `task_id`、`tool_name`、同步/异步模式、状态、原始请求和响应；台账写入失败只输出 warning，不会让已经成功的 AMK 调用失败。轮询上报会省略 `request.input`，避免覆盖首次提交保存的请求参数。
+- mediakit-studio `dev` 当前只提供上述任务台账写接口，尚无任务列表/详情 GET 接口。因此编辑器顶栏的导出记录仍只保留当前页面会话；如需刷新后读取历史导出列表，需要服务端补充按工程查询任务的接口。
+## 样式隔离
+SDK 会随 `import '@volcengine/amk-editor'` 自动注入样式，导航栏、左侧分类、素材网格的布局由 SDK 自己负责。**接入方不必再写补丁 CSS 才能让界面正常显示。**
+编辑器挂在普通 DOM（`#track-video-editor`）里，不是 Shadow DOM。宿主页面里针对 `section` / `nav` / `aside` 的全局布局重置会穿透进来，把顶栏或左侧分类挤扁。
+请避免：
+- 对 `section`、`nav`、`aside` 写全局 `display` / `flex` / `height` / `margin` 规则。
+- 用 `#track-video-editor nav { ... }` 这类按标签名锁定内部节点。同名标签在编辑器里用途不同，一条规则会同时打到顶栏和分类栏。
+如需约束编辑器尺寸，只设置挂载容器或 `#track-video-editor` 本身的 `width` / `height` / `min-height`。

package/dist/amk-editor.d.ts

@@ -1,5 +1,5 @@
 import './veveditor.css';
-import type { AmkEditorAuthConfig, AmkEditorOptions, AmkExportRequestResult, AmkProjectSnapshot, MaterialItem, VeVeditorInstance } from './types';
+import type { AmkMaterialImportType, AmkMaterialImportRequestOptions, AmkEditorOptions, AmkExportRequestResult, AmkProjectSnapshot, MaterialItem, VeVeditorInstance } from './types';
 import { type AmkI18nInstance } from './i18n';
 import { type AmkInvokeToolParams } from './api/client';
 export declare class AmkEditor {
@@ -10,6 +10,11 @@ export declare class AmkEditor {
     private layout?;
     private exportModal?;
     private exportRequestInFlight?;
+    private readonly exportTaskPollingControllers;
+    private readonly exportTaskPollingTokens;
+    private exportTasks;
+    private exportTaskListRequest?;
+    private importActions?;
     private asrProgressModal?;
     private confirmModal?;
     private emptyTrackConfirmInFlight?;
@@ -24,6 +29,7 @@ export declare class AmkEditor {
     private emptyTrackSaveBlocked;
     private savedMaterials;
     private saveQueue;
+    private projectRefreshInFlight?;
     private pendingSaveCount;
     private readonly asrPollingControllers;
     /** 当前前台 ASR 会话；取消、关闭或销毁后直接丢弃，不写入工程 JSON。 */
@@ -48,6 +54,8 @@ export declare class AmkEditor {
     private readonly thumbnailErrorInFlight;
     /** 前端抽帧封面缓存（不落盘）：key = materialKey，value = dataURL */
     private readonly posterCache;
+    /** 本次会话签名 URL 对应的原始 TOS 身份，供产物落盘时保留重签依据。 */
+    private readonly tosIdentityBySignedUrl;
     /** 同一 URL 的封面抽帧只执行一次，避免初始化与上传回调重复请求。 */
     private readonly posterCaptureInFlight;
     /** 销毁编辑器时中断尚未完成的前端抽帧或 AMK 首帧轮询。 */
@@ -65,21 +73,46 @@ 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>;
+    /**
+     * Queries an asynchronous AMK task through the editor's configured endpoint
+     * and headers. Intended for host UI cards that track tasks created by editor
+     * operations such as {@link requestExport}.
+     */
+    getTask<T = unknown>(taskId: string, options?: {
+        headers?: Record<string, string>;
+        signal?: AbortSignal;
+    }): 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>;
+    /**
+     * 从外部工具栏打开 AMK Editor 已配置的素材导入入口。
+     * 本地、URL、资产库均复用素材面板中的同一套弹窗、回调和入库链路。
+     * @returns 当前入口存在且已触发时返回 true；未配置或尚未挂载时返回 false。
+     */
+    requestMaterialImport(type: AmkMaterialImportType, options?: AmkMaterialImportRequestOptions): boolean;
     /**
      * 获取工程全量参数（materials + editParam + projectName）。
      * 从 VeVeditor 当前素材/草稿快照读取；未挂载时回落内置拉取到的快照。
      */
     getProject(): AmkProjectSnapshot;
+    /**
+     * 从 Editing 工程接口重新拉取完整素材列表。
+     * 与 `getProject()` 的当前编辑器快照不同，该方法每次都会请求服务端，
+     * 适合素材引用面板等必须包含最新导出产物的场景。
+     */
+    fetchProjectMaterials(): Promise<MaterialItem[]>;
+    /**
+     * 重新拉取服务端工程，并把最新素材与 Track 热更新到当前编辑器。
+     * 用于 Agent 完成远端编辑后刷新右侧预览；不会产生撤销记录，也不会把回灌事件再次保存到服务端。
+     */
+    refreshProject(): Promise<AmkProjectSnapshot>;
+    private refreshProjectFromServer;
     /**
      * 刷新素材播放信息（按需触发，如播放前 / 初始化）。
      * - TOS 直传素材会先使用临时 STS 重签私有对象 URL
@@ -104,6 +137,7 @@ export declare class AmkEditor {
      * URL 是运行时数据：保存工程，但不产生撤销步骤。
      */
     private applyTrackMaterialUrls;
+    private resolveTosSignedResourceUrls;
     private getExpiringTosMaterialIds;
     private scheduleTosSignedUrlRefresh;
     private refreshExpiringTosUrls;
@@ -131,6 +165,10 @@ export declare class AmkEditor {
      * 适配只作用于即将提交给导出接口的 editParam 副本，不写回工程或当前预览。
      */
     private submitExport;
+    private startExportTaskStatusPolling;
+    private refreshLatestExportTasks;
+    private loadLatestExportTasks;
+    private clearExportTaskPolling;
     private attach;
     private detach;
     private clearAsrPollingTimers;
@@ -181,10 +219,14 @@ export declare class AmkEditor {
      * POST 远端素材库 → 按 sprite/poster 判断发起抽帧并 PUT 更新。
      */
     private ingestImportedMaterials;
+    /**
+     * 通知宿主素材已入库。抽帧仍在后台进行，不阻塞对话引用。
+     */
+    private notifyMaterialsImported;
     /**
      * 本地上传 / URL 上传完成后，将新素材 POST 到 Editing API。
-     * addSketchItems 已写入面板；此处确保远端持久化，并把 Editing API
-     * 返回的 material_id 记到面板（业务不用传这个字段；不覆盖本地 source / kid / 预览字段）。
+     * 先确保远端持久化并合并 Editing API 返回的 material_id；成功后调用方
+     * 才写入素材面板（业务不用传 material_id；不覆盖本地 source / kid / 预览字段）。
      */
     private persistUploadedMaterials;
     private isHttpUrl;
@@ -230,6 +272,8 @@ export declare class AmkEditor {
      */
     private ensureMaterialExtractTasks;
     private createExtractFramesTask;
+    /** AMK 转存到私有 TOS 后，任务产物需先重签才能用于浏览器预览。 */
+    private signTaskOutputUrls;
     private startSpritePolling;
     private startPosterPolling;
     private buildSpriteFromExtractResult;

package/dist/api/client.d.ts

@@ -1,8 +1,10 @@
-import type { AmkEditorAuthConfig } from '../types';
+import type { AmkEditorGetHeaders } from '../types';
 export type AmkApiClientOptions = {
     endpoint: string;
-    /** 客户业务代理鉴权；返回的自定义请求头会随每次请求动态获取。 */
-    auth?: AmkEditorAuthConfig;
+    /** 当前工程 ID，用于统一注入 tools 请求的 callback_args。 */
+    projectId?: string;
+    /** 每次请求前动态获取并原样透传给客户业务代理的请求头。 */
+    getHeaders?: AmkEditorGetHeaders;
     /** 调用 tools 接口时写入请求体的产物存储目标，例如 `tos://bucket`。 */
     mediaOutputDestination?: string;
 };
@@ -16,15 +18,25 @@ export type AmkInvokeToolParams = {
 };
 export declare class AmkApiClient {
     private readonly baseUrl;
-    private auth?;
+    private readonly projectId?;
+    private readonly getHeaders?;
     private readonly mediaOutputDestination?;
+    private readonly taskToolNames;
+    private readonly terminalTaskReports;
+    private syncTaskSequence;
     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 createSyncTaskId;
+    private rememberTaskTool;
+    private reportTaskObservation;
     private mergeToolParams;
+    /**
+     * callback_args 约定以 JSON 字符串传输。保留调用方已有字段，并统一补充
+     * project_id，避免各个工具调用点重复组装且漏传。
+     */
+    private mergeCallbackArgs;
     /**
      * 查询异步任务：GET /api/v1/tasks/{task_id}
      * @see https://docs.volcengine.com/docs/6448/2278532
@@ -33,12 +45,19 @@ export declare class AmkApiClient {
         headers?: Record<string, string>;
         signal?: AbortSignal;
     }): Promise<T>;
+    /** 查询当前工程任务台账；服务端按 submitted_at 倒序返回。 */
+    listProjectTasks<T = unknown>(options?: {
+        toolNames?: string[];
+        page?: number;
+        pageSize?: number;
+        includeTotal?: boolean;
+        signal?: AbortSignal;
+    }): Promise<T>;
     requestJson<T = unknown>(path: string, options?: {
         method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
         headers?: Record<string, string>;
         body?: unknown;
         signal?: AbortSignal;
     }): Promise<T>;
-    private resolveAuthHeaders;
 }
 export declare function createAmkApiClient(options: AmkApiClientOptions): AmkApiClient;

package/dist/api/preset-library.d.ts

@@ -5,6 +5,8 @@ export type PresetLibraryItem = {
     name: string;
     icon_url: string;
     package_url: string;
+    /** 滤镜分类；无显式 categories 时 SDK 按 tag 聚合侧栏（值即分类名）。 */
+    tag?: string;
     default?: boolean;
 };
 export type PresetLibrary = Partial<Record<PresetLibraryResourceKey, PresetLibraryItem[]>>;

package/dist/api/project.d.ts

@@ -8,6 +8,7 @@ export type SavedAmkEditor = {
     revision: number;
     editParam: Record<string, unknown>;
 };
+export declare function fetchAmkProjectMaterials(client: EditingApiClient, projectId: string): Promise<MaterialItem[]>;
 export declare function fetchAmkProject(client: EditingApiClient, projectId: string): Promise<LoadedAmkProject>;
 export declare function updateAmkProjectName(client: EditingApiClient, projectId: string, projectName: string): Promise<void>;
 /**

package/dist/export-modal.d.ts

@@ -34,7 +34,7 @@ type SelectOption<T extends string> = {
 export declare const QUALITY_TOOLTIP = "AI MediaKit \u753B\u8D28\u589E\u5F3A\u96C6\u6210\u667A\u80FD\u8D85\u5206\u3001\u63D2\u5E27\u3001\u753B\u9762\u589E\u5F3A\u3001\u81EA\u9002\u5E94\u9510\u5316\u3001\u8272\u5F69\u589E\u5F3A\u7B49 30+ \u9AD8\u8D28\u91CF\u7B97\u6CD5\uFF0C\u7ED3\u5408\u81EA\u7814\u89C6\u9891\u5185\u5BB9\u7406\u89E3\u4E0E\u667A\u80FD\u8C03\u5EA6\uFF0C\u6309\u573A\u666F\u81EA\u52A8\u62E9\u4F18\u8C03\u7528\uFF0C\u5168\u9762\u63D0\u5347\u89C6\u9891\u753B\u8D28\u3002";
 export declare function getBaseResolutions(t: AmkI18nInstance['t']): SelectOption<ExportVideoParams['resolution']>[];
 /** 画质增强开启后的分辨率：不含原画；大模型版不含 4K */
-export declare function getEnhancedResolutions(t: AmkI18nInstance['t'], enhancementVersion?: ExportVideoParams['enhancementVersion']): SelectOption<ExportVideoParams['resolution']>[];
+export declare function getEnhancedResolutions(_t: AmkI18nInstance['t'], enhancementVersion?: ExportVideoParams['enhancementVersion']): SelectOption<ExportVideoParams['resolution']>[];
 /** 当前模式下合法分辨率；非法时回落到默认项 */
 export declare function normalizeExportResolution(params: Pick<ExportVideoParams, 'qualityEnhancement' | 'enhancementVersion' | 'resolution'>, t?: AmkI18nInstance['t']): ExportVideoParams['resolution'];
 export declare function getEnhancementVersions(t: AmkI18nInstance['t']): SelectOption<ExportVideoParams['enhancementVersion']>[];
@@ -54,7 +54,7 @@ export declare function createDefaultExportVideoParams(videoName: string): Expor
 /** 导出帧率合法区间（含端点） */
 export declare const EXPORT_FRAME_RATE_MIN = 15;
 export declare const EXPORT_FRAME_RATE_MAX = 120;
-/** 将导出帧率钳制到 15～120；非法输入回落 30 */
+/** 将导出帧率钳制到 15～120；非法输入回落 24 */
 export declare function normalizeExportFrameRate(frameRate: unknown): number;
 export declare function toggleQualityEnhancement(params: ExportVideoParams, enabled: boolean): ExportVideoParams;
 export declare function createExportModal(options: CreateExportModalOptions): ExportModalController;

package/dist/export-task-polling.d.ts

@@ -0,0 +1,12 @@
+import { type TaskPollingController } from './task-polling';
+export declare const EXPORT_TASK_POLL_INTERVAL_MS = 5000;
+export type ExportTaskPollingStatus = 'polling' | 'success' | 'failed';
+export declare function resolveExportTaskPollingStatus(payload: unknown): ExportTaskPollingStatus;
+export declare function resolveExportTaskProgress(payload: unknown): number | undefined;
+export declare function resolveExportTaskOutputUrl(payload: unknown): string | undefined;
+export declare function startExportTaskPolling(options: {
+    taskId: string;
+    getTask: (taskId: string) => Promise<unknown>;
+    onStatusChange: (status: ExportTaskPollingStatus, payload?: unknown) => void | Promise<void>;
+    onError?: (error: unknown) => void;
+}): TaskPollingController;

package/dist/header.d.ts

@@ -9,7 +9,13 @@ export interface CreateAmkEditorLayoutOptions {
     title: string;
     theme?: 'light' | 'dark';
     showHeader: boolean;
+    /** 是否展示导出任务列表入口，默认开启。 */
+    showExportTaskList?: boolean;
+    /** When set, append the header here instead of inside the editor root. */
+    headerMount?: HTMLElement;
     onExport: () => void;
+    /** 导出任务列表每次从关闭变为展开时触发。 */
+    onExportTasksOpen?: () => void | Promise<void>;
     /** 传入则展示返回按钮 */
     onBack?: () => void;
     /** 传入则展示关闭按钮 */
@@ -18,10 +24,25 @@ export interface CreateAmkEditorLayoutOptions {
     t?: AmkI18nInstance['t'];
 }
 export type AmkSaveStatus = 'saving' | 'saved';
+export type AmkExportTaskStatus = 'idle' | 'polling' | 'success' | 'failed';
+export type AmkExportTaskListItem = {
+    taskId: string;
+    name: string;
+    format: 'mp4' | 'mp3';
+    status: Exclude<AmkExportTaskStatus, 'idle'>;
+    /** 服务端返回的任务进度（0-100）；没有进度时使用不定长动画。 */
+    progress?: number;
+    /** 是否已在当前页面触发过浏览器下载。 */
+    downloaded?: boolean;
+    outputUrl?: string;
+};
 export interface AmkEditorLayout {
     root: HTMLDivElement;
     workspace: HTMLDivElement;
+    setTitle: (title: string) => void;
     setSaveStatus: (status: AmkSaveStatus) => void;
+    setExportTasks: (tasks: AmkExportTaskListItem[]) => void;
+    openExportTasks: () => void;
     destroy: () => void;
 }
 export declare function resolveHeaderTitle(options: ResolveHeaderTitleOptions): string;

package/dist/i18n/keys.d.ts

@@ -16,6 +16,21 @@ export declare const AMK_I18N_KEYS: {
         readonly saving: "amk.header.saving";
         readonly saved: "amk.header.saved";
         readonly exportVideo: "amk.header.exportVideo";
+        readonly exportTasks: "amk.header.exportTasks";
+        readonly exportTaskTooltip: "amk.header.exportTaskTooltip";
+        readonly exportTaskPolling: "amk.header.exportTaskPolling";
+        readonly exportTaskSuccess: "amk.header.exportTaskSuccess";
+        readonly exportTaskFailed: "amk.header.exportTaskFailed";
+        readonly exportTaskEmpty: "amk.header.exportTaskEmpty";
+        readonly exportTaskDownloadReady: "amk.header.exportTaskDownloadReady";
+        readonly exportTaskDownload: "amk.header.exportTaskDownload";
+        readonly exportTaskDownloadAgain: "amk.header.exportTaskDownloadAgain";
+        readonly exportTaskDownloading: "amk.header.exportTaskDownloading";
+        readonly exportTaskDownloadFailed: "amk.header.exportTaskDownloadFailed";
+        readonly exportTaskDownloadCorsHint: "amk.header.exportTaskDownloadCorsHint";
+        readonly exportTaskView: "amk.header.exportTaskView";
+        readonly exportTaskVideo: "amk.header.exportTaskVideo";
+        readonly exportTaskAudio: "amk.header.exportTaskAudio";
         readonly titleRuleEmpty: "amk.header.titleRuleEmpty";
         readonly titleRuleMaxLength: "amk.header.titleRuleMaxLength";
         readonly titleRuleCharset: "amk.header.titleRuleCharset";

package/dist/import-actions.d.ts

@@ -1,4 +1,4 @@
-import type { MaterialItem, SystemMaterialItem } from './types';
+import type { AmkMaterialImportType, AmkMaterialImportRequestOptions, MaterialItem, SystemMaterialItem } from './types';
 import type { AmkI18nInstance } from './i18n';
 interface MountImportActionsOptions {
     /** AMKEditor 自己的浮层容器；按钮仍挂在 VeVeditor 提供的工具栏插槽中。 */
@@ -7,9 +7,18 @@ interface MountImportActionsOptions {
     onUploadMaterial?: (files: File[]) => Promise<MaterialItem[]> | MaterialItem[];
     onUploadUrlMaterial?: (urls: string[]) => Promise<MaterialItem[]> | MaterialItem[];
     onUploadFromSystem?: () => Promise<SystemMaterialItem[] | undefined | null> | SystemMaterialItem[] | undefined | null;
-    onMaterialsImported: (materials: SystemMaterialItem[]) => void | Promise<void>;
+    onMaterialsImported: (materials: SystemMaterialItem[]) => MaterialItem[] | Promise<MaterialItem[]>;
     t?: AmkI18nInstance['t'];
 }
+/**
+ * 素材面板按钮与外部入口共用的控制器。保留可调用的 cleanup 形态，兼容已有
+ * `renderImportActions` 挂载协议；外部入口通过 trigger 复用完全相同的导入链路。
+ */
+export type ImportActionsController = (() => void) & {
+    hasAction: (type: AmkMaterialImportType) => boolean;
+    trigger: (type: AmkMaterialImportType, options?: AmkMaterialImportRequestOptions) => boolean;
+    destroy: () => void;
+};
 /** AMK 独立拥有素材导入 UI 与业务回调，VeVeditor 仅提供挂载容器和标准数据写入 API。 */
-export declare function mountImportActions(container: HTMLElement, options: MountImportActionsOptions): () => void;
+export declare function mountImportActions(container: HTMLElement, options: MountImportActionsOptions): ImportActionsController;
 export {};

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, AmkEditorAuthConfig, AmkEditorStorageConfig, AmkEditorUploadSTSCredentials, AmkEditorConfig, AmkEditorDecodeOptions, AmkEditorExportConfig, AmkEditorHeaderConfig, AmkEditorInternalConfig, AmkExportRequestResult, AmkProjectSnapshot, ExportVideoParams, MaterialConfig, MaterialItem, PersistExtractUrlsResult, RecommendedExtractStorageFields, SystemMaterialItem, Theme, VeVeditorInstance, } from './types';
+export type { AmkEditorOptions, AmkEditorStorageConfig, AmkEditorUploadSTSCredentials, AmkEditorConfig, AmkEditorDecodeOptions, AmkEditorExportConfig, AmkEditorGetHeaders, AmkEditorHeaderConfig, AmkEditorHeaderTitleUpdateSuccess, AmkEditorInternalConfig, AmkMaterialImportType, AmkMaterialImportRequestOptions, AmkExportRequestResult, AmkProjectSnapshot, ExportVideoParams, MaterialConfig, MaterialItem, PersistExtractUrlsResult, RecommendedExtractStorageFields, SystemMaterialItem, Theme, VeVeditorInstance, } from './types';