asset-import

资产导入

如果文件可能已导入，请先检查 browse_assets。

同机编辑器导入（首选）

1. 使用 browserHandoff.url 或 editorUrl 打开目标项目。保持该项目恰好有一个编辑器标签页处于打开状态，并确保它与 Shell 位于同一台机器／网络命名空间中。远程沙盒的 localhost 并非用户的 localhost。
2. 使用 PATH 中的 Node，根据实际编辑器 URL 的源启动捆绑的服务器：

node <this-skill-dir>/scripts/serve-local-media.mjs --origin <editor-origin> /path/to/source.mp4

调用 MCP 时，使用主机的后台进程支持让此进程保持运行。它会输出一行 JSON，并在 900 秒后自动退出。它只通过环回 URL 提供列出的文件，无需访问令牌。URL 使用公开的 chatcut-local-media-v1 路径前缀，以兼容现有编辑器。仍支持旧版带令牌前缀的 URL；JSON 的 token 字段包含的是此公开前缀，而非凭据。

3. 在一次 import_media 调用中导入多个文件：{"action":"from_editor","files":[...]}。将打印出的 imports 数组中每个文件的 assetId、url、filename 和 sizeBytes 复制到 files 中，并省略其逐文件的 action。每个 URL 可以来自不同的运行中辅助程序。每次调用发送 1–16 个文件；数量更多时，分批连续提交，每批 16 个。最多并发处理 8 个文件；编辑器会将每个文件直接流式传输到本地存储，因此下载一开始就会显示带传输进度的卡片。环回传输没有特定的文件大小上限。原先的顶层单文件参数仍然有效。
4. 检查 results 中的每个条目：成功的条目包含 ok:true 和 status:"locally_imported"；失败的条目包含 error。结果保留输入顺序，并包含 assetId 和 filename，同时提供顶层的 succeeded／failed 计数。仅使用相同的资产 ID 重试失败的文件。成功表示编辑器已保存本地字节并在本地注册了该资产。所有文件成功后再停止辅助程序。继续保持编辑器打开，以便完成服务器同步、后台上传和转录。
5. 使用返回的资产 ID 进行时间线操作。处理转录／字幕前，先等待 track_progress target:"transcription"。浏览器可渲染的时间线会延后原始文件上传；仅限云端或不受支持的时间线则会自动上传。在等待 target:"upload" 前先检查 browse_assets；延后的上传并未开始。需要云端文件字节时，使用编辑器的 Upload 操作，并保留相同的资产 ID。如果服务器同步仍在进行，请重试资产查找。

超时时，检查 browse_assets 并使用相同的 assetId 重试；导入可能仍在进行中，重试会从中断处继续下载，而不是从头开始。即使重启辅助程序导致 URL 发生变化，也要保留相同的 ID。不要盲目启动第二次导入。如果提示允许编辑器使用浏览器本地网络权限。如果编辑器无法连接辅助程序，或桥接不可用，请使用备用方案。主机策略拒绝并不意味着可以尝试其他传输途径。

进行视觉分析时，请直接在本地检查可读取的原始文件，而不是等待云端上传。导入原始源资产；不要将编辑内容扁平化为本地预渲染文件。

重新关联现有素材

对于缺失的本地媒体，保留现有素材及其时间线引用：

1. 从 browse_assets 获取现有的 assetId，并找到对应的原始源文件。
2. 使用上文中的同一个环回辅助程序提供该文件。
3. 使用辅助程序的 url、filename 和 sizeBytes 调用 import_media，但将 action 设为 "relink_from_editor"，并将生成的 assetId 替换为现有的 assetId。 对于多个文件，使用相同的 files 数组格式，并在每个条目中填入现有的素材 ID。
4. 等待状态变为 status: "locally_relinked" 后再停止辅助程序。上传或转录仍可能在进行中；请保持编辑器打开。

重新关联时总会读取提供的文件，即使编辑器已缓存字节数据也不例外。媒体类型必须匹配。请使用对应的原始文件，而不是其他替代片段：重新关联会保留现有的编辑和转录内容。如果编辑器中缺少目标素材，请等待项目同步完成后重试。重新关联失败时，不得退回到创建新素材的做法。

上传辅助程序备用方案

对于远程沙盒、编辑器不可用或浏览器连接受阻的情况：

1. 调用 import_media，传入 {"action":"create_session"}。
2. 在前台运行捆绑的辅助程序，使用返回的令牌和端点，并且最多提供四个路径：

node <this-skill-dir>/scripts/upload-media.mjs --token <token> --endpoint <endpoint> /path/to/source.mp4

请根据此技能的路径解析脚本。不要安装 Node，也不要用手写的上传或转码命令替代辅助程序。MCP OAuth 应保留在 MCP 客户端内部；只有短期有效的导入令牌会传给辅助程序。批量处理超过四个文件时，每四个文件都需要新建一个会话。

辅助程序会提前注册占位项，但会在上传完成后才输出最终 JSON。读取 imports[].result.assetId。如果发生错误并包含 retry，请获取新会话并重新运行返回的参数，以继续处理同一素材。

如果主机策略禁止传输，请停止操作并请用户通过编辑器上传或授予权限。不要绕过限制。公共 URL 可在本地下载，然后通过上文对应的路径导入。