@volcengine/amk-editor 0.0.2-beta.1 → 0.0.3

package/README.md

@@ -51,6 +51,9 @@ editor.requestMaterialImport('local', {
 
 // 从服务端重新拉取当前工程，并热更新素材与 Track（不写入撤销历史）。
 await editor.refreshProject();
+
+// 查询由编辑器操作创建的异步任务；复用相同的 endpoint 和 getHeaders。
+const exportTask = await editor.getTask('your-task-id');
 ```
 页面卸载时销毁：
 ```ts
@@ -62,15 +65,19 @@ editor.destroy();
 - 产物是单文件 ESM。依赖里的 AMD `define(["./core"])` 已在构建时剔除，避免 Next.js / webpack 误解析不存在的 `dist/core.js`。
 - `getHeaders` 可选，每次请求前都会重新调用；SDK 不解析、不缓存、不改写返回值，仅将其合并到发往 `endpoint` 的工程、素材、tools、tasks、导出等请求中。闭包内 Token 更新会自动用于下一次请求。
 - 本地上传、URL 导入由业务回调完成。返回的素材必须带业务主键 `source_material_id`，不必填写 `material_id`。
-- 播放地址、封面、雪碧图可能有时效。通过 `onRefreshPlayInfo` 返回新的访问地址。
+- 播放地址、封面、雪碧图可能有时效。通过 `onRefreshPlayInfo` 返回新的访问地址；补丁按 `material_id`、`source_material_id`、无标识时数组顺序依次匹配，未返回的字段保持原值。
 - 可选实现 `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` 的全局布局重置会穿透进来，把顶栏或左侧分类挤扁。

package/dist/amk-editor.d.ts

@@ -10,12 +10,18 @@ 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?;
     private readonly apiClient;
     private readonly ready;
+    private readonly bootstrapAbortController;
+    private destroyed;
     private projectName?;
     private editorRevision;
     private projectHydrated;
@@ -25,6 +31,11 @@ export declare class AmkEditor {
     private emptyTrackSaveBlocked;
     private savedMaterials;
     private saveQueue;
+    /** 最近一次 GET 或成功 PUT 后的服务端 editor 深比较基线。 */
+    private latestEditorFingerprint;
+    private latestEditorHasTrack;
+    /** 正在等待或执行的 editor 文档快照，用于合并高频重复事件。 */
+    private readonly pendingEditorSaveFingerprints;
     private projectRefreshInFlight?;
     private pendingSaveCount;
     private readonly asrPollingControllers;
@@ -50,6 +61,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 首帧轮询。 */
@@ -59,6 +72,10 @@ export declare class AmkEditor {
     /** 所有 TOS 素材共用一个刷新定时器，避免按素材创建大量 timer。 */
     private tosSignedUrlRefreshTimer?;
     private tosSignedUrlRefreshInFlight?;
+    /** 同一轮播放地址刷新合并 materialId，并串行执行各批次，避免并发覆盖轨道和 revision。 */
+    private readonly pendingPlayInfoRefreshes;
+    private playInfoRefreshBatchScheduled;
+    private playInfoRefreshQueue;
     private readonly handleVisibilityChange;
     private readonly handleTrackChanged;
     private readonly handleEditParamChanged;
@@ -69,6 +86,15 @@ export declare class AmkEditor {
     getI18n(): AmkI18nInstance;
     /** 通用工具调用：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
@@ -106,13 +132,19 @@ export declare class AmkEditor {
      * @param materialIdOrIds 单个 material_id、material_id 列表；省略则刷新当前全部有 material_id 的素材
      */
     refreshPlayInfo(materialIdOrIds?: string | string[]): Promise<MaterialItem | MaterialItem[] | undefined>;
+    private flushPlayInfoRefreshBatch;
     private refreshPlayInfoInternal;
+    /**
+     * 异步初始化入口：并行加载工程与预设，完成数据归一化后再挂载编辑器，
+     * 最后注册运行期的 URL 刷新和页面可见性监听。destroy() 可随时中断该流程。
+     */
     private bootstrap;
     /** 内置拉取工程：project + materials + editor → 归一化 → 组装 initialData。 */
     private resolveAndApplyProject;
     /**
      * 初始化时批量 refresh 素材（完整素材列表交给业务方），
-     * 再把轨道元素里的 URL 回填到最新值，完成后回写 editor 文档。
+     * 再把轨道元素里的 URL 回填到当前运行时。仅 UserData 变化不回写 editor 文档；
+     * Source 等真实协议字段变化时才保存。
      */
     private refreshProjectOnInit;
     /** TOS 私有桶签名刷新优先，宿主刷新回调随后可继续覆盖播放信息。 */
@@ -122,6 +154,7 @@ export declare class AmkEditor {
      * URL 是运行时数据：保存工程，但不产生撤销步骤。
      */
     private applyTrackMaterialUrls;
+    private resolveTosSignedResourceUrls;
     private getExpiringTosMaterialIds;
     private scheduleTosSignedUrlRefresh;
     private refreshExpiringTosUrls;
@@ -130,6 +163,7 @@ export declare class AmkEditor {
     mount(): VeVeditorInstance | undefined;
     private mountVeVeditor;
     destroy(): void;
+    private assertNotDestroyed;
     private resolveConfig;
     /** 与 VeVeditor 同一套顶层扁平资源字段：boolean 面板开关 + 内部 xgplayer 组装 */
     private resolveVeVeditorOptions;
@@ -142,6 +176,7 @@ export declare class AmkEditor {
      */
     private deleteMaterial;
     private queueEditorSave;
+    private setLatestEditorSnapshot;
     private confirmAbnormalEmptyTrackSave;
     private enqueueEditorSaveWithCurrentEditParam;
     /**
@@ -149,6 +184,10 @@ export declare class AmkEditor {
      * 适配只作用于即将提交给导出接口的 editParam 副本，不写回工程或当前预览。
      */
     private submitExport;
+    private startExportTaskStatusPolling;
+    private refreshLatestExportTasks;
+    private loadLatestExportTasks;
+    private clearExportTaskPolling;
     private attach;
     private detach;
     private clearAsrPollingTimers;
@@ -252,6 +291,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,6 +1,8 @@
 import type { AmkEditorGetHeaders } from '../types';
 export type AmkApiClientOptions = {
     endpoint: string;
+    /** 当前工程 ID，用于统一注入 tools 请求的 callback_args。 */
+    projectId?: string;
     /** 每次请求前动态获取并原样透传给客户业务代理的请求头。 */
     getHeaders?: AmkEditorGetHeaders;
     /** 调用 tools 接口时写入请求体的产物存储目标，例如 `tos://bucket`。 */
@@ -16,13 +18,25 @@ export type AmkInvokeToolParams = {
 };
 export declare class AmkApiClient {
     private readonly baseUrl;
+    private readonly projectId?;
     private readonly getHeaders?;
     private readonly mediaOutputDestination?;
+    private readonly taskToolNames;
+    private readonly terminalTaskReports;
+    private syncTaskSequence;
     constructor(options: AmkApiClientOptions);
     getBaseUrl(): string;
     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
@@ -31,6 +45,14 @@ 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>;

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

@@ -10,4 +10,6 @@ export type PresetLibraryItem = {
     default?: boolean;
 };
 export type PresetLibrary = Partial<Record<PresetLibraryResourceKey, PresetLibraryItem[]>>;
-export declare function fetchPresetLibrary(client: Pick<AmkApiClient, 'requestJson'>, resources: PresetLibraryResourceKey[]): Promise<PresetLibrary>;
+export declare function fetchPresetLibrary(client: Pick<AmkApiClient, 'requestJson'>, resources: PresetLibraryResourceKey[], options?: {
+    signal?: AbortSignal;
+}): Promise<PresetLibrary>;

package/dist/api/project.d.ts

@@ -8,8 +8,12 @@ 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 fetchAmkProjectMaterials(client: EditingApiClient, projectId: string, options?: {
+    signal?: AbortSignal;
+}): Promise<MaterialItem[]>;
+export declare function fetchAmkProject(client: EditingApiClient, projectId: string, options?: {
+    signal?: AbortSignal;
+}): Promise<LoadedAmkProject>;
 export declare function updateAmkProjectName(client: EditingApiClient, projectId: string, projectName: string): Promise<void>;
 /**
  * POST 一批新素材到 AMK 工程。

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

@@ -0,0 +1,15 @@
+import { type TaskPollingController } from './task-polling';
+export declare const EXPORT_TASK_POLL_INTERVAL_MS = 5000;
+export declare const EXPORT_TASK_VISIBLE_WINDOW_MS: number;
+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;
+/** 服务端仍查最新 10 条，前端只展示提交时间位于最近 24 小时内的任务。 */
+export declare function filterRecentExportTasks<T extends Record<string, unknown>>(items: T[], now?: number): T[];
+export declare function startExportTaskPolling(options: {
+    taskId: string;
+    getTask: (taskId: string) => Promise<unknown>;
+    onStatusChange: (status: ExportTaskPollingStatus, payload?: unknown) => void | Promise<void>;
+    onError?: (error: unknown) => void | Promise<void>;
+}): TaskPollingController;

package/dist/header.d.ts

@@ -9,9 +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;
     /** 传入则展示关闭按钮 */
@@ -20,11 +24,27 @@ 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'>;
+    /** 任务提交时间；历史任务来自任务列表接口的 submitted_at。 */
+    submittedAt?: string;
+    /** 服务端返回的任务进度（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";