@byteplus/amk-editor-assistant 1.0.1 → 1.0.2

package/README.md

@@ -1,422 +1,104 @@
 # @byteplus/amk-editor-assistant
 
-面向 Web 应用的 AI 智能剪辑 SDK，在同一页面集成自然语言助手与多轨道剪辑器，支持工程会话绑定、
-素材引用、AI 编辑结果同步与手动精修。完整的代理示例、接口路径和接入流程请参阅
-[Web 智能剪辑 SDK 集成指南](https://docs.volcengine.com/docs/Intelligentprocessing/WebSmartClipSDKIntegrationGuide?lang=zh)。
+An AI video editing SDK for web applications. Combine a conversational assistant with a multitrack editor to import media, reference clips in chat, apply AI edits, and make manual adjustments.
 
-本包内置 BytePlus AMK Editor。上方火山文档仅供公共 API 参考；业务代理、区域和服务可用性请使用 BytePlus 对应配置。
+## Prerequisites
 
-## 接入前准备
+- Enable BytePlus AI MediaKit and obtain an API key. Prepare inference and media understanding models available in your service region.
+- Create an editing project on your server and pass its `project_id` to the browser.
+- Implement a backend proxy that checks user and project permissions, injects the API key, and forwards editor and assistant requests. Preserve streaming assistant responses.
+- Use a browser environment with React / React DOM 18.2 or 19. Give the mounting container an explicit width and height.
 
-1. 开通 AI MediaKit，取得 API Key；在BytePlus 对应的模型服务准备推理模型 Endpoint ID，并按需准备音频、视觉理解模型 Endpoint ID，完成跨服务授权。
-2. **在服务端**创建剪辑工程，将返回的 `project_id` 作为前端的 `projectId`。不要在浏览器代码中存放 AI MediaKit API Key 或BytePlus 对应的模型服务密钥。
-3. 实现业务代理（例如 `/api/amk-proxy`）：验证用户与工程权限，在服务端注入 AI MediaKit API Key，转发剪辑器和助手两条链路。助手执行可能返回流式响应，代理须透传响应流。具体路径白名单和服务端示例见上述集成指南。
-
-## 安装
+## Install and initialize
 
 ```bash
 npm install @byteplus/amk-editor-assistant react react-dom
 ```
 
-## 快速开始
-
-准备一个有明确宽高的挂载容器，然后初始化 SDK：
-
 ```ts
-import { createAmkEditorAssistant } from "@byteplus/amk-editor-assistant";
-import "@byteplus/amk-editor-assistant/styles.css";
+import { createAmkEditorAssistant } from '@byteplus/amk-editor-assistant';
+import '@byteplus/amk-editor-assistant/styles.css';
 
-// 由业务实现：获取访问自身代理的短期凭证，而非 AI MediaKit API Key。
-const getBusinessHeaders = async () => ({
-  Authorization: `Bearer ${await getYourShortLivedBusinessToken()}`,
-});
+const container = document.getElementById('editor');
+if (!container) throw new Error('Editor container not found');
 
-const container = document.getElementById("amk-editor-assistant");
-if (!container) throw new Error("找不到 SDK 挂载节点");
+// Implement this callback using your application's authentication.
+const getHeaders = async () => ({
+  Authorization: `Bearer ${await getBusinessToken()}`,
+});
 
 const sdk = createAmkEditorAssistant({
   container,
-  projectId: "your-project-id", // 服务端创建的工程 ID
-  endpoint: "/api/amk-proxy", // 两条链路共用的业务代理前缀
-  getHeaders: getBusinessHeaders, // 剪辑器请求头
-  i18n: { locale: "en-US" }, // 可改为 zh-CN，会默认同步给 Assistant
+  projectId: 'your-project-id',
+  endpoint: '/api/amk-proxy',
+  getHeaders,
+  i18n: { locale: 'en-US' },
   assistant: {
-    model: "ep-inference-model", // 必填：推理模型 Endpoint ID
-    // 可选：理解视频、图片、音频等媒体内容时使用
-    preferMultiModalModels: ["ep-audio-model", "ep-visual-model"],
-    runtime: {
-      getHeaders: getBusinessHeaders, // Assistant 请求头；地址由 endpoint 自动派生
-    },
-    onIntegrationError: (error) => {
-      console.error("智能剪辑 SDK 初始化或同步失败", error);
-    },
+    model: 'your-inference-model-id',
+    preferMultiModalModels: ['your-audio-model-id', 'your-visual-model-id'],
+    runtime: { getHeaders },
+    onIntegrationError: (error) => console.error(error),
   },
 });
 
 await sdk.whenReady();
-
-// 离开页面时释放资源；在 React 中也应放入 useEffect 的清理函数。
-window.addEventListener("pagehide", () => sdk.destroy(), { once: true });
-```
-
-例如以下挂载节点和样式：
-
-```html
-<div id="amk-editor-assistant"></div>
-<style>
-  #amk-editor-assistant {
-    width: 100%;
-    height: 100vh;
-  }
-</style>
-```
-
-`getYourShortLivedBusinessToken()` 是由接入方实现的示例函数；若代理使用其他鉴权方式，应按实际情况配置两条链路的请求头。SDK 基于同一个 `endpoint` 自动追加剪辑器和 Assistant 的 API 路径，无需单独配置 `runtimeUrl`。示例中的 `ep-*` 均为占位值，请替换为实际的BytePlus 对应的模型服务 Endpoint ID。
-
-### 验证接入
-
-- 页面应同时出现 AI 助手和剪辑器，并加载指定 `projectId` 的工程。
-- 检查两条代理请求的路径和鉴权；长期 API Key 只能留在服务端。
-- 发送一条编辑指令，确认工程结果刷新；尝试素材导入、刷新后恢复会话，并在页面卸载时调用 `destroy()`。
-
-### 请求链路
-
-以 `endpoint: "/api/amk-proxy"` 为例：
-
-| 链路    | 浏览器请求路径示例                                                       | 请求头配置                     |
-| ------- | ------------------------------------------------------------------------ | ------------------------------ |
-| 剪辑器  | `/api/amk-proxy/api/v1/editing/projects/...`（还可能请求工具、任务接口） | 顶层 `getHeaders`              |
-| AI 助手 | `/api/amk-proxy/api/v1/studio/agents/copilotkit`（还有会话查询接口）     | `assistant.runtime.getHeaders` |
-
-业务代理应只剥离自身前缀，再将完整 `/api/v1/...` 路径转发给 AI MediaKit，并在服务端注入长期密钥；不要把浏览器携带的业务 Token 直接当作上游 API Key。参见[官方代理示例](https://docs.volcengine.com/docs/Intelligentprocessing/WebSmartClipSDKIntegrationGuide?lang=zh)。
-
-## 配置
-
-`createAmkEditorAssistant(options)` 接收 AMK Editor 配置，并增加 Assistant 与左右布局配置。
-
-### 基础配置
-
-| 参数         | 类型                              | 必填 | 说明                                   |
-| ------------ | --------------------------------- | ---- | -------------------------------------- |
-| `container`  | `HTMLElement`                     | 是   | SDK 挂载节点                           |
-| `projectId`  | `string`                          | 是   | 当前 AMK 工程 ID                       |
-| `endpoint`   | `string`                          | 是   | Editor 与 Assistant 共用的业务代理前缀 |
-| `getHeaders` | `AmkEditorGetHeaders`             | 否   | 剪辑器请求发送前动态获取请求头         |
-| `assistant`  | `AmkEditorAssistantConfig`        | 是   | Assistant 配置                         |
-| `layout`     | `AmkEditorAssistantLayoutOptions` | 否   | Assistant 与编辑器的左右布局配置       |
-| `i18n`       | `AmkI18nOptions`                  | 否   | 语言与文案覆盖，默认 `en-US`           |
-
-其余编辑器能力，例如 `material`、`storage`、`decode`、`header` 和 `interaction`，与
-`@byteplus/amk-editor` 的配置保持一致。顶层 `theme` 同时应用于 Editor 和 Assistant，支持
-`"light"` 和 `"dark"`；未配置时默认为 `"light"`。
-
-顶层 `i18n` 除传给 Editor 外，也用于本 SDK 自带的按钮、菜单和弹窗展示文案，
-例如“添加到对话”；其 `locale` 也会默认传给 Assistant（包括 VeloAssistant）。
-只配置 `assistant.locale` 时，Editor 和本 SDK 的文案也会默认使用该语言；
-两处都显式配置时各自生效，都不配置时默认 `en-US`。
-业务自行传入的模型名称、场景名称、输入框占位符等文案不会自动翻译，应由业务按语言传入。
-语言配置不会修改工具入参、返回值或发送给 Agent 的素材内容。
-配置格式与 AMK Editor 一致：
-
-```ts
-createAmkEditorAssistant({
-  // 其余必填配置略
-  i18n: {
-    locale: "en-US",
-    // 可选：使用 amk.assistant.* 键覆盖 Assistant 文案
-    messageOverrides: {
-      "amk.assistant.timeline.addToConversation": "Add clip to chat",
-    },
-  },
-});
-```
-
-未配置时默认使用中文文案；`assistant.timelineLabels.addToConversation` 仍可单独覆盖按钮标题。
-
-### Assistant 配置
-
-| 参数                     | 类型                                                                              | 必填 | 说明                                                                       |
-| ------------------------ | --------------------------------------------------------------------------------- | ---- | -------------------------------------------------------------------------- |
-| `model`                  | `string \| AmkEditorAssistantSelectableModel[] \| AmkEditorAssistantModelGroup[]` | 是   | 单个推理模型值、扁平列表或分组模型列表                                     |
-| `preferMultiModalModels` | `string[]`                                                                        | 否   | 多模态理解模型 Endpoint ID 列表；需要理解音频、视频或图片时配置            |
-| `maasModel`              | `string \| readonly string[]`                                                     | 否   | 生成模型的真实 wire modelId（低层强制值）；通常由 `maasModel` 分组自动选择 |
-| `mcp.tools`              | `readonly string[]`                                                               | 否   | MCP Server 内部工具原名，经 TCC 绑定到 `x-mcp-tools-override`              |
-| `mcp.editDenyTools`      | `readonly string[]`                                                               | 否   | MCP Server 内部工具原名，经 TCC 绑定到编辑黑名单 override Header           |
-| `runtime`                | `AssistantRuntimeConfig`                                                          | 否   | Assistant Runtime 的请求头配置；地址由顶层 `endpoint` 派生                 |
-| `locale`                 | `string`                                                                          | 否   | Assistant 展示语言；默认沿用顶层 `i18n.locale`                             |
-| `agentId`                | `string`                                                                          | 否   | Agent ID，默认 `mediakit-editor-sdk-agent`                                 |
-| `onIntegrationError`     | `(error: unknown) => void`                                                        | 否   | 接收初始化和联动过程中的错误                                               |
-
-SDK 不对外要求 `auth`。AMK 链路通过外层 `getHeaders` 配置请求头，Assistant 链路通过
-`assistant.runtime.getHeaders` 或 `assistant.runtime.headers` 配置请求头。两条链路相互独立，可以复用同一个
-`getHeaders` 函数，也可以使用不同的地址和凭据。
-
-`assistant.runtime.runtimeUrl` 是完整的 Runtime 地址覆盖；省略时使用
-`${endpoint}/api/v1/studio/agents`。外层 `getHeaders` **不会**自动复制给 Assistant，
-如需共用请求头，请显式将同一个函数同时传给两处。`preferMultiModalModels` 可直接配置一个或多个
-理解模型；仅配置单个推理模型字符串时不会展示模型选择器。
-
-### MCP 工具配置
-
-```ts
-createAmkEditorAssistant({
-  container,
-  projectId: "your-project-id",
-  endpoint: "/api/amk-proxy",
-  assistant: {
-    model: "ep-inference-model",
-    mcp: {
-      tools: ["probe_video_metadata"],
-      editDenyTools: ["export_project"],
-    },
-    runtime: { getHeaders: getBusinessHeaders },
-  },
-});
-```
-
-两项配置使用目标 MCP Server 的内部工具原名，以 Server 工具目录为准：
-
-| SDK 字段                      | 请求字段 `mediakit.*` | TCC 绑定的 MCP Header            |
-| ----------------------------- | --------------------- | -------------------------------- |
-| `assistant.mcp.tools`         | `mcp_tools`           | `x-mcp-tools-override`           |
-| `assistant.mcp.editDenyTools` | `mcp_edit_deny_tools` | `x-mcp-edit-deny-tools-override` |
-
-每项独立去除名称首尾空格、去重并编码成 JSON 数组字符串。名称须匹配 `^[A-Za-z0-9_-]{1,64}$`，**每项** JSON 最大 8192 字节，两项合计可以超过 8192 字节。一项未传、类型或名称非法、超限时，仅省略该项请求字段，不影响另一有效项，也不抛出配置异常。非法名单不保留部分有效名称；合法 `[]` 原样发送为字符串 `"[]"`。
-
-`assistant.mcp.tools` 也接受 API 风格的横杠名称：例如 `probe-video-metadata` 会在去重前转换成 `probe_video_metadata`，两种写法混用时只发送一次。`assistant.mcp.editDenyTools` 不做横杠转换，继续使用内部工具原名。
-
-两个请求字段由 `assistant.mcp` 独占，通用 Prompt Variables 的同名值被移除，Composer 的 `patchMediaKitPromptVariables` 也不能覆盖。目标 Agent 的 TCC Profile 须通过 `request_props` 将 `mcp_tools` 和 `mcp_edit_deny_tools` 声明为可选字符串（各自 `max_length: 8192`），并将以下片段**增量合并**至相应 MCP Server 的现有 `header_bindings`。保留鉴权、工程、产物、多模态模型等已有绑定，不要用该片段整体替换原配置：
-
-SDK 异常字段在发送前已省略，实现按项回退。直接绕过 SDK 提交请求字段时，Runtime 仍执行原有校验；非字符串、超过长度限制或包含 CRLF 的 wire 值会返回 HTTP 400。
-
-```json
-{
-  "header_bindings": {
-    "x-mcp-tools-override": "${mediakit.mcp_tools}",
-    "x-mcp-edit-deny-tools-override": "${mediakit.mcp_edit_deny_tools}"
-  }
-}
-```
-
-原有静态 `x-mcp-tools`、`x-mcp-edit-deny-tools` 和 `x-mcp-domains` 保留不动；Runtime 使用已有通用 TCC 绑定转发 JSON，不增加工具筛选业务逻辑。先部署支持这些 override Header 的 MCP Server，再配置目标 Profile 并接入 SDK。
-
-覆盖与回退由 MCP Server 分别处理。缺失或非法的某一 override 只回退该项原 Header / 环境配置。`tools: []` 显式覆盖本项为空，延续原 `x-mcp-tools` 空值行为，仍可能使用 `MCP_TOOLS` 环境默认值并结合 domains 过滤，**不表示禁用所有 MCP 工具**。`editDenyTools: []` 清空编辑黑名单。原 Header 的选择语义延续，这不是严格的全局工具白名单；共享工具、domains、服务端授权和实际可用性继续由 MCP Server 决定，Runtime Profile 中已有的 MCP `tool_filter` 也仍会限制最终工具集合，`frontendTools` 按原配置生效。
-
-### 多模型选择
-
-传入模型数组后，输入框底部会显示模型选择器：
-
-```ts
-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
-组件。`key: "model"` 的当前模型作为 Assistant 的活动推理模型，`key: "maasModel"` 的单选或多选结果会自动作为平调模型注入 `agentContext`，`key: "preferMultiModalModels"` 及其他辅助组的当前选择会去重汇总为 `preferMultiModalModels`；各组顺序不影响映射。为兼容旧配置，缺少 `model` key 时首个非保留组仍作为活动推理模型。无有效缓存时，显式传入的 `assistant.maasModel` 会在当前 `maasModel` 分组内匹配，未匹配则使用配置的默认项；没有默认项时保持未选择。请保持 `model`（分组数组）与 `preferMultiModalModels` 的引用稳定（使用模块级常量或 `useMemo`），避免内联新建对象导致选择被反复重置。所有选择都会通过 `onModelChange` 事件返回完整变化。
-
-```ts
-assistant: {
-  model: [
-    {
-      key: "model",
-      title: "推理模型",
-      description: "理解指令并规划剪辑任务",
-      panelHeader: "请选择推理模型",
-      models: [
-        { value: "ep-inference-a", name: "推理模型 A", default: true },
-        { value: "ep-inference-b", name: "推理模型 B" },
-      ],
-    },
-    {
-      key: "preferMultiModalModels",
-      title: "多模态理解模型",
-      description: "理解图片、视频和音频素材",
-      panelHeader: "请选择理解模型",
-      multiple: true,
-      models: [
-        { value: "ep-audio-model", name: "音频理解模型", default: true },
-        { value: "ep-visual-model", name: "视觉理解模型", default: true },
-      ],
-      selectedRenderer: (models) => `已选 ${models.length} 个模型`,
-    },
-    {
-      key: "maasModel",
-      title: "生成模型",
-      multiple: true,
-      models: [
-        { value: MaasModelId.Seedream5Pro, name: "Seedream 5.0 Pro", description: "生图" },
-        { value: MaasModelId.Seedance25, name: "Seedance 2.5", description: "生视频" },
-        { value: MaasModelId.SeedAudio1, name: "Seed Audio 1.0", description: "生音频" },
-      ],
-    },
-  ],
-  onModelChange: (event) => {
-    // 扁平模式收到模型对象；分组模式收到完整的 group/model/models/value/selection 快照。
-    console.info(event);
-  },
-}
-```
-
-单选分组最多设置一个 `default: true`；多选分组可设置多个；`maasModel` 分组未设置默认项时保持未选择，其他分组默认选择第一项。分组选择同样优先恢复
-浏览器本地缓存，缓存只恢复仍存在于当前分组的模型 `value`（比较时自动忽略首尾空白）。`model` 分组必须至少包含一个模型；其他分组可为空，
-选择器会展示空状态。各分组顺序不影响 `model`、`preferMultiModalModels`、`maasModel` 的映射。显式
-`assistant.maasModel` 仅在命中某个 `maasModel` 分组内模型时生效；未命中时使用该组配置的 `default`；没有默认项时保持未选择。
-
-`MaasModelId` 从 `@byteplus/amk-editor-assistant` 根入口导入，与底层 SDK 共用目录。其枚举值是不带 `doubao-`、`dola-`、`dreamina-` 等品牌前缀的 canonical model ID。MaaS 分组与其他分组写法相同，只需额外提供 `region`；模型 `value` 在 TypeScript 中约束为 `MaasModelId`，SDK 内部按地区和模型族补充 provider 前缀。运行时对 JavaScript、旧数据或类型断言传入的目录外非空字符串保持容错，已经包含 provider 前缀的 wire ID 保持原值。模型名称和能力标签由宿主提供。旧 MaaS 缓存不在当前选项内时自动失效；没有配置默认项时保持未选择。未选择或清空选择时，MaaS context 的 `value` 为 `""`；description 直接声明用户尚未选择模型，要求 Agent 不调用相关 MaaS 工具，并在回复中请用户先选择或提供模型；不得猜测模型 ID 或使用默认模型。已选择模型时，description 要求 Agent 先确认所选模型支持当前生成类型；没有兼容模型或无法确认能力时不调用工具，并请用户选择兼容模型。例如，只有生图模型时不执行生视频任务；多个所选模型均支持当前任务时，按 context `value` 中的顺序使用第一个兼容模型。
-
-直接组装 `key: "maasModel"` 的分组可通过 `region` 指定地区，省略时默认使用 `cn`。显式 `assistant.maasModel` 只用于低层强制场景，必须是真实 wire modelId 或 modelId 数组。Seedance 2.1 及 2.x Pro 尚无核实的官方 ID，因此未加入推荐目录，但宿主仍可自行配置。国内音频沿用既有 MaaS ID，未实测生成请求。
-
-### Composer 自定义 Action 与请求参数
-
-业务可以通过 `assistant.composer.actions` 添加场景、多模态模型等控件。Action 上下文提供草稿操作，以及
-`patchMediaKitPromptVariables`，用于动态更新下一次请求中的 `promptVariables.mediakit`：
-
-```tsx
-assistant: {
-  model: "inference-model-endpoint",
-  composer: {
-    actions: [{
-      key: "multimodal-model-selector",
-      render: ({ patchMediaKitPromptVariables }) => (
-        <MultimodalModelSelector
-          onChange={(endpoint) => {
-            patchMediaKitPromptVariables({
-              multimodal_endpoint: endpoint,
-            });
-          }}
-        />
-      ),
-    }],
-  },
-}
+// Call sdk.destroy() when the page or component is unmounted.
 ```
 
-Patch 值必须兼容 JSON；传入 `undefined` 会删除对应业务字段。`model`、`project_id` 和
-`media_output_destination` 由 SDK 管理，不能通过该方法覆盖。
+Replace the project and model identifiers with values from your BytePlus account. Implement `getBusinessToken()` in your application. Keep API keys and permanent access keys on your server.
 
-`composer.actions` 也可以传入函数。函数会在 SDK 内置 Action 全部生成后收到完整列表，可统一隐藏、
-重排、包装或替换当前及后续新增的内置插件。以下示例隐藏自动生成的模型选择器：
+## Configuration
 
-```tsx
-import {
-  AMK_EDITOR_ASSISTANT_MODEL_SELECTOR_ACTION_KEY,
-  createAmkEditorAssistant,
-} from "@byteplus/amk-editor-assistant";
+| Option | Description |
+| --- | --- |
+| `container` | Required. An existing `HTMLElement` |
+| `projectId` | Required. Cloud editing project ID |
+| `endpoint` | Required. Backend proxy prefix; the SDK appends API paths |
+| `getHeaders` | Editor request headers callback; supports asynchronous results |
+| `assistant.model` | Required. Inference model ID, model list, or grouped model list |
+| `assistant.preferMultiModalModels` | Model IDs for audio, video, and image understanding |
+| `assistant.runtime.getHeaders` | Assistant request headers callback; configure separately |
+| `assistant.runtime.runtimeUrl` | Optional separate assistant endpoint; defaults to `${endpoint}/api/v1/studio/agents` |
+| `assistant.onModelChange` | Model selection change callback |
+| `assistant.onIntegrationError` | Initialization and editor synchronization error callback |
+| `assistant.mcp.tools` | Optional tool selection configuration; requires server support and remains subject to server permissions |
+| `assistant.mcp.editDenyTools` | Optional editing tool deny list using server tool names |
+| `i18n` | Language and message overrides; defaults to `en-US`, also supports `zh-CN` |
+| `theme` | `light` or `dark`; defaults to `light` |
+| `layout` | Panel widths, resizing, and panel visibility |
+| `material` | Callbacks for file uploads, URL imports, and your asset library |
+| `storage` | Upload destination and temporary credentials callback |
 
-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 包。
+Editor `getHeaders` is not copied to the assistant. Set `assistant.runtime.getHeaders` explicitly. The default configuration uses one backend proxy prefix for both request paths. The BytePlus Editing API upstream is `https://mediakit.ap-southeast-1.bytepluses.com`. Use `runtimeUrl` if your assistant service has a separate endpoint. Use credentials, projects, models, and storage from the same brand and region.
 
-### 布局配置
+### Models and language
 
-```ts
-layout: {
-  initialWidthPercent: 37.5,
-  minAssistantWidth: 320,
-  minEditorWidth: 640,
-  resizable: true,
-  initialHeaderVisible: true,
-  initialPanelToggleVisible: true,
-  // defaultHiddenPanel: "assistant",
-  onPanelVisibilityChange: ({ assistantOpen, editorOpen }) => {
-    console.log({ assistantOpen, editorOpen });
-  },
-}
-```
+Model options use `{ value, name, default? }`. Grouped options use `{ key, title, models, multiple? }`. Use `model` for inference, `preferMultiModalModels` for understanding, and `maasModel` for generation. Set the generation group's `region` to your service region; the default is `cn`. Keep model list references stable to avoid resetting selection.
 
-`layout` 只控制本 SDK 的左右分栏，不会透传给 Assistant 或 AMK Editor。
-`onPanelVisibilityChange` 在面板状态发生变化后触发，初始渲染时不触发。
+`i18n.locale` is passed to the assistant by default. Provide your own translated model names and custom text. Override SDK messages through `i18n.messageOverrides` using `amk.assistant.*` keys.
 
-欢迎页由 Velo 的空会话状态统一管理。通过 `assistant.agent.welcome` 提供业务首页，首条消息发送后 Velo 会自动切换到标准对话，不需要读取消息 DOM、历史数量或素材数量：
+### Media and storage
 
-```tsx
-assistant: {
-  model: "your-model-endpoint-id",
-  agent: {
-    welcome: <BusinessWelcome />,
-  },
-}
-```
+Use `material.onUploadFile`, `material.onUploadUrlMaterial`, and `material.onUploadFromSystem` for your upload and asset library integration. Users can reference media through `@` or the timeline's “Add to conversation” action. Project results synchronize after AI editing completes.
 
-## 素材能力
+For built-in VOD uploads, configure both `storage.media_output_destination` and `storage.getUploadSTS`:
 
-素材上传和业务资产库接入沿用 AMK Editor 的 `material` 配置。例如：
+| Option | Value |
+| --- | --- |
+| `storage.media_output_destination` | `vod://<space>`; use the space name without a media ID or directory |
+| `storage.getUploadSTS` | Return `AccessKeyId`, `SecretAccessKey`, `SessionToken`, `ExpiredTime`, and `CurrentTime` as strings |
 
-```ts
-material: {
-  onUploadFile: (file) => uploadOneFile(file),
-  onUploadUrlMaterial: (urls) => importUrls(urls),
-  onUploadFromSystem: () => openAssetLibrary(),
-}
-```
+Issue temporary credentials on your server with upload, publish, and playback query permissions for the target space. The SDK resolves and refreshes playback URLs. Custom file upload callbacks take precedence over built-in uploads. Original media URLs must support CORS.
 
-Assistant 会把完整的 `material` 配置原样交给 AMK Editor，不包装上传或播放地址刷新回调。
-临时素材识别、转存、并发控制、替换与失败重试均由 AMK Editor 负责。
-
-配置相应能力后，Assistant 输入区会提供素材导入入口。导入成功的素材先进入当前工程素材库，再作为素材引用
-添加到对话。用户也可以通过输入框的 `@` 入口引用当前工程已有素材，或从编辑器时间线将选中元素添加到对话。
-
-`sync_materials` 写入 MediaKit 生成素材后，Assistant 只调用一次 AMK Editor 的 `refreshMaterials()`，使 Agent
-已插入的素材立即显示；AMK Editor 随后自行处理其中的临时素材。编辑器首次加载、临时 HTTP/HTTPS 地址转存、
-客户播放信息隔离和原位替换均遵循 AMK Editor 的行为，Assistant 不再维护平行的扫描或替换状态机。
-
-## 联动行为
-
-- Assistant 运行期间，编辑器进入只读状态，避免编辑操作与 Agent 修改互相覆盖。
-- Assistant 运行结束后，SDK 自动刷新工程，使编辑器展示最新的素材和剪辑结果。
-- 编辑器初始化、保存或刷新期间，Assistant 保留输入内容，但暂时禁止发送。
-- SDK 自动解析当前工程绑定的会话，接入方无需维护 `threadId`。
-- 工程上下文会自动传给 Assistant，包括 `projectId` 以及可选的媒体输出位置。
-
-## 实例方法
-
-```ts
-await sdk.whenReady();
-
-const editor = sdk.getEditor();
-
-sdk.destroy();
-```
+BytePlus currently does not forward `media_output_destination` to AMK for cloud output transfer. Configuring VOD storage enables built-in local uploads and playback resolution; it does not automatically transfer AI-generated cloud outputs to your space. Use your own integration for storage capabilities outside this flow.
 
-| 方法                          | 说明                                                  |
-| ----------------------------- | ----------------------------------------------------- |
-| `whenReady()`                 | 等待工程加载和编辑器挂载完成                          |
-| `getEditor()`                 | 获取底层 `AmkEditor` 实例；调用前应等待 `whenReady()` |
-| `setLayoutChromeVisibility()` | 动态显示或隐藏 Header 与分栏按钮                      |
-| `destroy()`                   | 销毁 Assistant、编辑器及相关监听器；可重复调用        |
+## Instance methods
 
-## 注意事项
+| Method | Description |
+| --- | --- |
+| `whenReady()` | Wait for the project and editor to load |
+| `getEditor()` | Get the editor instance after initialization |
+| `setLayoutChromeVisibility()` | Update header and panel toggle visibility |
+| `destroy()` | Release resources and event listeners |
 
-- SDK 仅支持浏览器环境，创建实例时 `container` 必须是已存在的 `HTMLElement`。
-- `getHeaders` 适合返回短期凭据：SDK 会在发起请求时调用，不缓存返回值。
-- 不要在浏览器代码中放置长期 AK/SK 或其他服务端密钥。
-- 切换 `projectId` 时，请销毁旧实例并使用新配置创建实例。
+Destroy the previous instance before switching projects. In React, call `destroy()` in your effect cleanup.

package/dist/chunks/{DZTsnYdF.js → 0ao3sINM.js}

@@ -1,4 +1,4 @@
-import { d as a, r as t } from "./dwdop78j.js";
+import { d as a, r as t } from "./RWy6DQbo.js";
 const e = `<svg xmlns="http://www.w3.org/2000/svg" width="40" height="40" fill="none" viewBox="0 0 40 40"><path fill="#1664ff" d="M4 12.385V27.62c0 5.47 4.435 9.905 9.905 9.905h12.19c5.47 0 9.905-4.434 9.905-9.905V14.293a9.9 9.9 0 0 0-3.174-7.267l-2.06-1.908a9.9 9.9 0 0 0-6.73-2.638H13.905C8.435 2.48 4 6.914 4 12.385"/><path fill="#fff" d="M5.453 12.554A8.554 8.554 0 0 1 14.006 4h7.563a4.99 4.99 0 0 1 4.835 3.767 4.99 4.99 0 0 0 3.72 3.64l.239.054a5.39 5.39 0 0 1 4.182 5.251v10.735A8.554 8.554 0 0 1 25.991 36H14.006a8.554 8.554 0 0 1-8.553-8.553z"/><path fill="#1664ff" d="M16.972 17.25a.75.75 0 0 1 .642 1.136l-3.289 5.483h2.647a.75.75 0 0 1 0 1.5H13a.75.75 0 0 1-.643-1.136l3.29-5.483H13a.75.75 0 0 1 0-1.5zm2.56 7.37V18a.75.75 0 1 1 1.5 0v6.62a.75.75 0 0 1-1.5 0m7.942-4.635c0-.682-.553-1.235-1.236-1.235h-1.897v2.472h1.897c.683 0 1.236-.554 1.236-1.237m1.5 0a2.736 2.736 0 0 1-2.736 2.737h-1.897v1.897a.75.75 0 0 1-1.5 0V18a.75.75 0 0 1 .75-.75h2.647a2.736 2.736 0 0 1 2.736 2.735"/></svg>
 `, f = {
   name: "type-zip-state-default",