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

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
@@ -68,9 +71,13 @@ editor.destroy();
 - 可选配置 `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,6 +10,10 @@ 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?;
@@ -50,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 首帧轮询。 */
@@ -69,6 +75,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
@@ -122,6 +137,7 @@ export declare class AmkEditor {
      * URL 是运行时数据：保存工程，但不产生撤销步骤。
      */
     private applyTrackMaterialUrls;
+    private resolveTosSignedResourceUrls;
     private getExpiringTosMaterialIds;
     private scheduleTosSignedUrlRefresh;
     private refreshExpiringTosUrls;
@@ -149,6 +165,10 @@ export declare class AmkEditor {
      * 适配只作用于即将提交给导出接口的 editParam 副本，不写回工程或当前预览。
      */
     private submitExport;
+    private startExportTaskStatusPolling;
+    private refreshLatestExportTasks;
+    private loadLatestExportTasks;
+    private clearExportTaskPolling;
     private attach;
     private detach;
     private clearAsrPollingTimers;
@@ -252,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,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/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,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,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";