@volcengine/amk-editor-assistant

@volcengine/amk-editor-assistant

面向 Web 应用的智能视频剪辑集成 SDK，提供 Assistant 与 AMK Editor 联动、工程会话绑定、素材引用和 编辑结果同步能力。

安装

npm install @volcengine/amk-editor-assistant react react-dom

快速开始

import { createAmkEditorAssistant } from "@volcengine/amk-editor-assistant";
import "@volcengine/amk-editor-assistant/styles.css";

const getEditorHeaders = async () => ({
  Authorization: `Bearer ${await getEditorToken()}`,
});

const sdk = createAmkEditorAssistant({
  container: document.querySelector("#amk-editor-assistant")!,
  projectId: "your-project-id",
  endpoint: "https://your-amk-api.example.com",
  getHeaders: getEditorHeaders,

  assistant: {
    model: "your-model-endpoint-id",
    runtime: {
      runtimeUrl: "https://your-assistant-runtime.example.com",
      getHeaders: async () => ({
        Authorization: `Bearer ${await getAssistantToken()}`,
      }),
    },
    onIntegrationError: (error) => {
      console.error("AMK Editor Assistant 初始化或同步失败", error);
    },
  },
});

await sdk.whenReady();

// 页面卸载时释放资源。
sdk.destroy();

挂载节点需要具有明确的宽高：

#amk-editor-assistant {
  width: 100%;
  height: 100vh;
}

配置

createAmkEditorAssistant(options) 接收 AMK Editor 配置，并增加 Assistant 与左右布局配置。

基础配置

参数	类型	必填	说明
container	HTMLElement	是	SDK 挂载节点
projectId	string	是	当前 AMK 工程 ID
endpoint	string	是	AMK Editor 与工程接口地址
getHeaders	AmkEditorGetHeaders	否	AMK 请求发送前动态获取并透传请求头
assistant	AmkEditorAssistantConfig	是	Assistant 配置
layout	AmkEditorAssistantLayoutOptions	否	Assistant 与编辑器的左右布局配置

其余编辑器能力，例如 material、storage、decode、header、interaction 和 theme，与 @volcengine/amk-editor 的配置保持一致。

Assistant 配置

参数	类型	必填	说明
model	string | AmkEditorAssistantSelectableModel[] | AmkEditorAssistantModelGroup[]	是	单个模型值、扁平模型列表，或按用途分组的模型列表
runtime	AssistantRuntimeConfig	否	Assistant Runtime 地址与请求头配置
onIntegrationError	(error: unknown) => void	否	接收初始化和联动过程中的错误

SDK 不对外要求 auth。AMK 链路通过外层 getHeaders 配置请求头，Assistant 链路通过 assistant.runtime.getHeaders 或 assistant.runtime.headers 配置请求头。两条链路相互独立，可以复用同一个 getHeaders 函数，也可以使用不同的地址和凭据。

未配置 assistant.runtime 时，Runtime 地址会回退到外层 endpoint；外层 getHeaders 不会自动复制给 Assistant，如需共用请求头，请显式将同一个函数同时传给两处。

多模型选择

传入模型数组后，输入框底部会显示模型选择器：

assistant: {
  model: [
    {
      value: "model-endpoint-a",
      name: "Model A",
      default: true,
    },
    {
      value: "model-endpoint-b",
      name: "Model B",
    },
  ],
}

最多可设置一个 default: true。SDK 会在浏览器本地保存用户最近一次选择；缓存中的模型 value 仍存在于当前 列表时优先恢复，否则使用默认项，未设置默认项时使用第一项。

需要同时展示多个用途（例如对话模型、工具参数模型）时，可以传入分组模型列表。每组使用稳定的 key。title、description、icon、panelHeader 以及模型的 name、description 均支持字符串或 React 组件。首组的当前模型作为 Assistant 的活动推理模型；其余组的当前选择会去重汇总为 preferMultiModalModels，并通过 onModelChange 事件返回完整变化。

assistant: {
  model: [
    {
      key: "chat",
      title: "对话模型",
      description: "负责理解需求并生成回复",
      panelHeader: "请选择对话模型",
      models: [
        { value: "chat-model-a", name: "Chat A", default: true },
        { value: "chat-model-b", name: "Chat B" },
      ],
    },
    {
      key: "tool",
      title: "工具参数模型",
      description: "负责生成结构化工具参数",
      panelHeader: "请选择工具参数模型",
      multiple: true,
      models: [
        { value: "tool-model-a", name: "Tool A", default: true },
        { value: "tool-model-b", name: "Tool B", default: true },
      ],
      selectedRenderer: (models) => `已选 ${models.length} 个模型`,
    },
  ],
  onModelChange: (event) => {
    // 扁平模式收到模型对象；分组模式收到完整的 group/model/models/value/selection 快照。
    console.info(event);
  },
}

单选分组最多设置一个 default: true；多选分组可设置多个，未设置时默认选择第一项。分组选择同样优先恢复 浏览器本地缓存，缓存只恢复仍存在于当前分组的模型 value。首组必须至少包含一个模型；其他分组可为空， 选择器会展示空状态。

Composer 自定义 Action 与请求参数

业务可以通过 assistant.composer.actions 添加场景、多模态模型等控件。Action 上下文提供草稿操作，以及 patchMediaKitPromptVariables，用于动态更新下一次请求中的 promptVariables.mediakit：

assistant: {
  model: "inference-model-endpoint",
  composer: {
    actions: [{
      key: "multimodal-model-selector",
      render: ({ patchMediaKitPromptVariables }) => (
        <MultimodalModelSelector
          onChange={(endpoint) => {
            patchMediaKitPromptVariables({
              multimodal_endpoint: endpoint,
            });
          }}
        />
      ),
    }],
  },
}

Patch 值必须兼容 JSON；传入 undefined 会删除对应业务字段。model、project_id 和 media_output_destination 由 SDK 管理，不能通过该方法覆盖。

composer.actions 也可以传入函数。函数会在 SDK 内置 Action 全部生成后收到完整列表，可统一隐藏、 重排、包装或替换当前及后续新增的内置插件。以下示例隐藏自动生成的模型选择器：

import {
  AMK_EDITOR_ASSISTANT_MODEL_SELECTOR_ACTION_KEY,
  createAmkEditorAssistant,
} from "@volcengine/amk-editor-assistant";

createAmkEditorAssistant({
  // ...
  assistant: {
    model: models,
    composer: {
      actions: (actions) =>
        actions.filter(
          (action) =>
            action.key !== AMK_EDITOR_ASSISTANT_MODEL_SELECTOR_ACTION_KEY,
        ),
    },
  },
});

数组形式的 composer.actions 仍用于添加带稳定 AMK 上下文的业务控件；函数形式则接管最终 Action 列表。AssistantModelSelectorPlugin 也由本包直接导出，调用方无需另外安装或引入底层 Assistant 包。

布局配置

layout: {
  initialWidthPercent: 37.5,
  minAssistantWidth: 320,
  minEditorWidth: 640,
  resizable: true,
  initialHeaderVisible: true,
  initialPanelToggleVisible: true,
  // defaultHiddenPanel: "assistant",
  onPanelVisibilityChange: ({ assistantOpen, editorOpen }) => {
    console.log({ assistantOpen, editorOpen });
  },
}

layout 只控制本 SDK 的左右分栏，不会透传给 Assistant 或 AMK Editor。 onPanelVisibilityChange 在面板状态发生变化后触发，初始渲染时不触发。

欢迎页由 Velo 的空会话状态统一管理。通过 assistant.agent.welcome 提供业务首页，首条消息发送后 Velo 会自动切换到标准对话，不需要读取消息 DOM、历史数量或素材数量：

assistant: {
  model: "your-model-endpoint-id",
  agent: {
    welcome: <BusinessWelcome />,
  },
}

素材能力

素材上传和业务资产库接入沿用 AMK Editor 的 material 配置。例如：

material: {
  onUploadFile: (file) => uploadOneFile(file),
  onUploadUrlMaterial: (urls) => importUrls(urls),
  onUploadFromSystem: () => openAssetLibrary(),
}

配置相应能力后，Assistant 输入区会提供素材导入入口。导入成功的素材先进入当前工程素材库，再作为素材引用 添加到对话。用户也可以通过输入框的 @ 入口引用当前工程已有素材，或从编辑器时间线将选中元素添加到对话。

联动行为

• Assistant 运行期间，编辑器进入只读状态，避免编辑操作与 Agent 修改互相覆盖。
• Assistant 运行结束后，SDK 自动刷新工程，使编辑器展示最新的素材和剪辑结果。
• 编辑器初始化、保存或刷新期间，Assistant 保留输入内容，但暂时禁止发送。
• SDK 自动解析当前工程绑定的会话，接入方无需维护 threadId。
• 工程上下文会自动传给 Assistant，包括 projectId 以及可选的媒体输出位置。

实例方法

await sdk.whenReady();

const editor = sdk.getEditor();

sdk.destroy();

方法	说明
whenReady()	等待工程加载和编辑器挂载完成
getEditor()	获取底层 AmkEditor 实例；调用前应等待 whenReady()
setLayoutChromeVisibility()	动态显示或隐藏 Header 与分栏按钮
destroy()	销毁 Assistant、编辑器及相关监听器；可重复调用

注意事项

• SDK 仅支持浏览器环境，创建实例时 container 必须是已存在的 HTMLElement。
• getHeaders 适合返回短期凭据：SDK 会在发起请求时调用，不缓存返回值。
• 不要在浏览器代码中放置长期 AK/SK 或其他服务端密钥。
• 切换 projectId 时，请销毁旧实例并使用新配置创建实例。