长视频续拍工坊 wxsimon2022/metaontic-video

MetaOnticVideo：DeepSeek Harness AI 视频创作插件

用 Seedance 2.0 / Mini / Fast 多段续拍，制作超过 15 秒的 AI 视频。 从自然语言需求开始，完成脚本与分镜审核、文生视频或图生视频、逐段预览、断点续做和 FFmpeg 本地合并。

MetaOnticVideo 是 DeepSeek Harness 的 AI 视频创作插件。借助 Seedance 2.0 视频续拍、参考图、脚本审核、分段预览、可恢复生成和本地 FFmpeg 合并，制作超过 15 秒的视频。

安装与 Key 配置 · 使用说明书 PDF · 下载正式版 · English · 更新记录 · Gitee 镜像

用 Seedance 2.0 制作超过 15 秒的视频

Seedance 2.0 系列单次生成上限为 15 秒。MetaOnticVideo 把全片拆成首段生成和后续视频续拍：例如 30 秒规划为 15 + 15 秒，60 秒规划为四段 15 秒。每段完成后先交付预览，用户确认后再继续，最后合并为完整视频，并保留原始分段。

默认全片规划上限为 120 秒、最多 10 段，实际分段由模型与时长决定。超过 15 秒的部分靠多次模型调用完成；续拍会尽量保持主体、声音和剧情衔接，但实际连续性仍需逐段验收。

| 使用需求 | 插件如何完成 |
| 文生视频 / Text-to-video | 用自然语言描述主题，审核脚本后提交生成 |
| 图生视频 / Image-to-video | 使用参考图、首帧或首尾帧组织视频画面 |
| 长视频 / Video continuation | 用上一段视频续拍，支持过渡描述与逐段审核 |
| 脚本与分镜 | 展示完整脚本、镜头示意图与费用预估，确认后制作 |
| 暂停后继续 | 使用原任务与断点恢复，避免重复生成已完成分段 |
| 本地交付 | 优先展示合并成片，再按段号交付原始视频文件 |

支持 MetaOntic AI、服务端领 Key、火山引擎直连。当前设置页提供 Seedance 2.0 Mini / Fast 视频模型，清晰度支持 480P、720P；Seedream 图片处理须另行确认并单独计费。

三步开始使用

1. 在 DeepSeek Harness 的插件页安装 MetaOnticVideo，参见安装说明。
2. 选择 MetaOntic AI，在 ai.bileego.com 注册获取 Key，填写对应视频／图片 Key 并保存。
3. 新建会话 → 模式选择 → 视频创作助手，发送需求；先看脚本与分镜，再确认费用和制作。

示例需求：

做一条30秒的民勤蜜瓜介绍视频，16:9横屏，480P。
主角站在瓜田里自我介绍，再蹲下轻拍蜜瓜，中文同期声与环境声，不加字幕。
先展示完整脚本、分镜示意图和费用预估，我确认后再生成。

常见问题

Seedance 2.0 如何生成 30 秒或 60 秒视频？

靠多段视频续拍与本地合并完成。首段没有视频输入，后续续拍使用上一段完整视频，费用按各次实际调用计算；脚本审核先展示全片预估，完成后查询支持渠道的实际结算。

支持文生视频、图生视频和已有视频续拍吗？

支持。新视频可从文字、参考图、首帧或首尾帧开始；已有视频续拍需要上游可访问的视频地址，不能直接把本地路径作为视频输入。具体素材能力取决于模型与接入渠道。

视频清晰度在哪里选择？

在对话的脚本阶段确认 480P 或 720P，后续分段沿用已确认清晰度。插件设置中选择模型、画幅与声音，清晰度不在设置页配置。

分镜示意图和真人参考图处理会调用图片模型吗？

分镜示意图默认在本地绘制，不调用付费图片模型。真人参考图需要转换为非真人风格时，先取得用户同意，再调用 Seedream；展示处理结果并审核后才用于视频，图片与视频分别计费。

生成中断后需要从头重做吗？

先按任务 ID 查询，或使用原 resumeDir 继续；已完成分段可恢复交付。请求结果不明时停止自动重发，核对原渠道记录后再处理，避免重复提交。

使用与开发导航

- 安装、Key 申请与使用教程
- 插件安装 · 接入方式 · 长视频与逐段预览
- 图片与素材 · FFmpeg 与设置页 · 更新插件
- 本地开发热加载 · 发布规范 · 请求日志
- 问题反馈 · MIT License

脚本与续拍过渡

续拍方式由已审核脚本决定，不在插件设置页配置，也不通过 video_config 保存全局 mode。每次生成/延长按脚本传入 mode 或过渡描述；旧配置残留 mode 不影响新任务，恢复任务保留已记录参数及原请求。

脚本先定义人物、道具和场景主体，再按事件顺序写镜头；逐段提示词采用主体、动作、场景、光影、镜头、风格、画质与约束八要素。景别、视角与运镜分别描述，单镜尽量一种运镜，不按分镜数量增加付费任务。
每个续拍段在审核材料中增加「过渡画面描述」：视频1 的接缝状态 → 过渡动作/镜头 → 本段起始事件 → 声音交接。video_generate.segmentPrompts 对应条目可附单行 【过渡画面】...，优先于通用 transitionDescription；video_extend 可直接传该参数。仅进入提示词，不向上游新增不支持的参数；暂停续做沿用描述，已经提交的任务不因描述改变重新提交。

直接使用「向前/向后延长视频1」，不写「参考视频1」。明确切镜时按已审核描述切换景别，未明确时保持连续，不保证完全消除接缝跳变。官方多视频轨道补全与当前逐段单视频续拍不同，插件不会为转场擅自额外生成视频。

当前能力

| 能力 | 行为 |
| 生成视频 | 文生视频、参考图、首帧或首尾帧生视频 |
| 模型时长 | Seedance 2.0 / Fast / Mini 单次 4–15 秒；2.5 单次 4–30 秒 |
| 长视频 | 超过模型上限时首段生成、后续续拍；每段完成先交付预览，确认后用 resume 继续 |
| 保存成果 | 默认下载本地；多段生成先交付合并成片，再依次交付第一段、第二段及后续分段 |
| 视频延长 | 以公网视频为输入，向前或向后延长，支持暂停续做 |
| 任务查询 | 根据任务 ID 查询进度，查询失败不等于生成失败 |
| 导演预设 | 创意完善、按内容选择风格、脚本与口语改稿、两道确认、生成与验收 |
| 设置页 | 接入方式、模型、更多设置、额度与记录、版本及更新内容 |

视频清晰度可选 480P、720P，在脚本阶段由用户明确确认。设置页暂时隐藏 2.5 候选，代码保留其识别、30 秒上限和参数兼容；已有配置不会自动改成 2.0。
全片规划上限为 120 秒、最多 10 段；显式缩短每段时长时，可规划的最大总时长也会降低。

安装

需要 DeepSeek Harness 桌面端。插件运行环境要求 Node.js 20+，桌面端提供运行环境。

在「插件 → 添加插件」中使用以下地址之一：

github:wxsimon2022/metaontic-video
git+https://gitee.com/hackloop/metaontic-video.git

也可在终端安装：

dsh plugin --profile desktop add "git+https://gitee.com/hackloop/metaontic-video.git"

从本地源码安装：

npm install
npm run build
dsh plugin --profile desktop add /你的路径/metaontic-video

本地安装链接源码目录；启用下述本地热加载后，执行 npm run build 即可更新工具与界面，无需反复重启。Gitee 安装地址必须带 git+ 前缀。

选择接入方式

打开「插件 → 已安装插件 → MetaOnticVideo → 查看」。

| 接入方式 | 配置 | 费用与记录 |
| MetaOnticVideo | 邮箱验证码登录，由服务端写入 Key 与连接信息 | 展示服务端额度、使用记录；按中转规则预估费用 |
| MetaOntic AI | 仅填写 Key，无需登录；使用与服务端模式相同的中转地址与接口 | 脚本审核提供双方案基础估价；不核对额度、不显示额度或使用记录，按实际调用计费 |
| 火山引擎直连 | 填写自己的火山方舟 API Key，选择已开通模型并保存 | 脚本审核提供双方案基础估价，插件路线按官方价、不套中转折扣；不查询或判断余额，按实际调用计费 |

火山直连模式使用北京区域官方接口 https://ark.cn-beijing.volces.com/api/v3，隐藏服务端登录、额度和使用记录。
创建任务成功只说明已受理；查询到 succeeded 且取得视频地址才算生成成功。

保存时只保留当前接入方式的连接配置：火山直连清除服务端与 MetaOntic AI 凭据和中转配置；MetaOntic AI 清除服务端登录与火山凭据，保留共用中转地址；服务端模式清除两个手填 Key。
模型、输出和合并等通用设置保留。切回另一种方式时，需要重新登录或填写 Key。
保存通过宿主 mutate 接口一次原子写入配置与非当前渠道的空凭据，避免继承旧 Key 或逐字段重载打断；宿主拒绝整批写入时明确提示失败。保存只清理本插件字段，不删除宿主 profile 或其他插件配置。

开始制作

助手先评估方案完整度：不完善时先询问是否需要协助完善；已有明确完善授权时不重复询问是否完善，但方向不明确时仍须先询问方向并等待答复。完整方案保留原意，只润色表达与整理分镜，涉及剧情、角色或结尾变更时先征得同意。缺省时长、画幅可用默认值，不因此要求完善方案。

选择「视频创作助手」预设，或直接在对话中说明创意：

帮我做一段15秒的家庭生活短片，父亲嘴上嫌女儿回来晚，实际一直给她留着热饭。
竖屏，真实自然，中文同期声，不要字幕和配乐。

也可以只说「猫咪上班」或「给咖啡杯拍条广告」。助手会先判断方案完整度：模糊点子先询问是否需要完善，同意后才补充故事与脚本；完整方案只润色和整理，不擅自改变剧情。用户已说「你发挥」或「帮我完善」时不重复询问是否完善；方向尚不明确时仍须先询问方向。

用户要求协助完善创意时，方向不明确应先询问并等待答复，不自行决定方向或补写剧情。

时长与画幅未指定时默认 15 秒、9:16，清晰度在脚本阶段由用户确认 480P 或 720P。风格、对白、音乐与镜头按题材选择，并在脚本中说明；生活短剧、产品展示、风景与动画采用不同表达，没有必要就不加对白，字幕未指定不加。用户指定优先。

脚本先讲故事，再展示规格、主体、时间与画面/对白安排。可以直接说「更搞笑一点」「少点对白」「换个结尾」，助手会保留满意部分并改稿。创意讨论不提交生成任务；仅在方案不完善且未授权时询问是否完善。
单次上限内的一镜到底或少量切镜均在一次生成中完成，不按分镜数增加调用。

每次脚本审核前，先用只读 video_estimate 展示「火山官方方案」和「MetaOnticVideo插件方案」两项人民币基础估价，写在脚本最后的「费用预估」一节并随完整脚本展示，列明模型、分段、分组倍率与价格日期。续拍计入上一段视频输入，最低用量补足尚未计入；图片处理、重试与独立配音另计，实际以账单为准。超过 15 秒的官方参照采用 2.5，超过 30 秒也如实分段；未知模型或画幅不猜价。手填 Key 未核实分组时不默认套用折扣。试算不会调用模型或扣费，也不改变脚本审核和制作确认两道流程。
每次脚本审核前，无论单段还是多段，都会交付当前版镜头参考示意图；需要分段生成时，另展示每段的时长、内容和衔接方案。示意图不代表成片效果，不额外调用付费出图模型。改稿同步更新方案与示意图；实际视频仍逐段预览并确认续做。

新视频需要两道确认：

1. 展示脚本，包含画面风格、人物、镜头与时间安排、完整对白，等待审核。
2. 审核通过后单独确认是否开始制作，之后才调用生成工具。

审核前必须实际展示当前版完整脚本；保存文件或只给路径不算展示。有文件展示工具时先展示并等待完成，再单独弹审核窗；展示失败时在正文贴出完整脚本。修改脚本后重新展示当前版，并再次弹出脚本审核窗口；当前版通过后再单独确认费用与制作，旧版同意不沿用。提问工具不可用时才退回文字确认。已有视频延长无需完整脚本，但要先确认方向、内容、时长和制作费用。

助手根据内容选择喜剧、情绪、商品、知识或氛围结构；先明确人物目标与故事变化，再写动作和自然对白。
脚本留足停顿与反应时间，不强行套反转。制作文件保存在 video-projects/<slug>/，包括脚本、提示词与镜头记录。

长视频与逐段预览

2.0 生成20秒时，通常规划为15+5秒；2.5 生成20秒可一次直出。

1. 写好全片脚本与逐段执行提示词。
2. 生成第一段，先下载交付预览。
3. 返回 paused: true、resumeDir、remainingSeconds。
4. 用户确认继续后，将原 resumeDir 传给同一个工具的 resume 参数。
5. 续拍下一段并交付当前累计成片；仍有剩余则再次暂停，直到完成。

同一个暂停目录同时只允许一次续做，避免重复提交。已完成的分段不重复生成。
新增视频的多段计划必须提供与计划等长的 segmentPrompts，每条只包含本段新增动作和对白；不把完整剧本重复传给模型。
旧暂停记录未保存逐段提示词时，需补齐提示词后继续，不要从头生成。

生成中断或查询超时时，先检查已返回的任务 ID 和分段成果。任务可能仍在上游执行，不要直接重复提交。

续做恢复：任务提交后保存任务ID，每段成功后立即更新进度。停止等待不等于取消上游任务；返回 pendingTaskId 时使用原工具的 resume 查询并接回进度。下载或合并失败时，同一恢复目录先重试交付；已完成进度再次读取不重复生成。续做默认保留 merge 等交付选项，模型或渠道变化需先取得用户确认；待查询任务必须使用原配置。新视频续做目标总时长仍不超过120秒。

成果与原始分段

默认输出到会话工作目录下的 metaontic-video/，设置页不提供输出目录输入框。

- videoPath：本地成片路径。
- segmentsDir：原始分段目录；合并后始终保留。
- segments[].localPath：每个已下载分段路径。
- resumeDir：续做时使用的暂停目录。
- actualSeconds：合并后探测到的实际时长（有该字段时）。

文件名包含生成时间与规划秒数；实际时长可能因模型输出、裁剪和转场而略有差异，以媒体探测结果为准。
显式传入 merge: false 时只返回上游链接，不下载分段，需在链接失效前自行转存。

图片与素材

referenceImages 支持公网 URL、Base64、本机图片路径及 latest / latest:2 最近上传图片简写。
本地图片单张限制为8 MB，支持 jpg/jpeg/png/webp/bmp/gif/tiff；会按指定画幅适配。

| 输入 | 火山直连 | 服务端中转 |
| 参考图 | 2.0 最多9张，2.5最多30张 | 2.0 最多9张，2.5最多30张；按顺序全部提交，需中转兼容原生角色格式 |
| 首帧 / 首尾帧 | firstFrameUrl / lastFrameUrl，尾帧必须搭配首帧 | 由中转模型支持情况决定 |
| 首尾帧与参考图混用 | 提交前拒绝，需选择一种模式 | 同样在提交前拒绝 |
| 官方素材 ID | 支持 asset:// 图片和视频素材 | 依赖中转兼容情况 |

素材编号按实际提交顺序引用，不要引用未提交的图、音频或视频。
三种接入方式都检查请求体不超过64 MB；多张内联图片过大时改用公网 URL，火山直连也可用素材 ID。
中转模式沿用 /doubao/api/v3/contents/generations/tasks 的顶层 content 数组，每张参考图显式标记 role: reference_image；不因图片数量自动改作首尾帧，也不自动添加第三方 reference_mode 或改为 image_urls。一至多张均使用同一格式，实际支持情况取决于中转站部署版本及渠道。上游拒绝时不自动丢图或换格式重试。

视频续拍使用上游可访问的视频 URL，不能直接传本地路径。
含人脸续拍应使用同一上游账号的受信原始素材，避免改用本地裁剪上传版本破坏来源识别。

提示词与接缝处理

脚本供用户审核，模型执行提示词要精简：主体标签 → 本段动作与对白 → 场景光线 → 运镜 → 声音与必要限制。

- 2.0 按镜头序号或动作先后组织内容，不依赖精确秒点。
- 2.5 可使用本段从0秒开始的连续整数秒区间，避免内容超载。
- 续拍直接写「向后延长视频1」或「向前延长视频1」，只输出新增事件，不回放上段结尾。
- 每段明确起始状态、结束状态和交接动作，完整台词结束后再分段。

依据火山2.0指南，默认每处接缝裁前段尾部6帧、后段头部1帧，按实际帧率换算，随后直接拼接。
裁剪仅处理副本，原始分段保留；2.5不默认套用该经验规则。
这用于缓解接缝回退，不保证消除模型重演的整句对白。

「更多设置」中的 seamTrimSeconds 可覆盖默认策略：

| 值 | 行为 |
| 留空 | 2.0使用上述官方建议；2.5不主动裁剪 |
| 0 | 关闭接缝裁剪 |
| 0.5,0 | 仅裁第二段开头0.5秒，第三段不裁；替代默认头尾裁剪 |

手动值范围0–3秒。先预览接缝，不在词句中间下刀；裁剪音视频同步，不补静帧或慢放凑时长。
未启用接缝裁剪时，默认直接拼接，避免交叉淡化造成短暂重影；也可选择重编码后直接拼接。旧配置中的 seamless 会兼容为直接拼接。当前不提供画面或音频交叉淡化，旧 bgmFadeSeconds 不生效；原始分段始终保留，旧 keepSegments 不再控制删除。手动或默认裁剪均保留所选合并方式。

更新检测并行查询 GitHub、Gitee 及备用镜像；任意来源发现比本机新的版本立即提醒，另一个来源失败不影响结果。所有来源失败时自动检查静默处理。

ffmpeg 与设置页

多段本地合并需要 ffmpeg，媒体探测需要 ffprobe。设置页不再常驻安装提示卡片；需要合并但环境缺失时仍会提示处理。

macOS
brew install ffmpeg

Windows
winget install --id Gyan.FFmpeg -e

验证 ffmpeg -version ffprobe -version

可让助手用 video_setup 检查；只有确认安装后才执行安装。自定义安装位置可在更多设置填写二进制路径。

设置页的「更多设置」默认折叠，内含合并与输出、运行参数。
修改后点击「保存」；登录区位于接入方式下，重置入口位于设置页底部。
「重置插件」会清除本插件保存的配置和登录状态，恢复默认值。

生成等待界面

视频工具卡片在审批通过且实际执行后显示等待动画、已等待时间和估算进度，准备参数和等待审批时不显示进度。5 秒视频预计等待 120 秒，15 秒预计等待 150 秒，其他时长线性推算；无时长时默认 180 秒。执行期间即使到 99% 仍保持流动动效；确认成功后才显示 100%，失败或停止后结束动画。
进度基于等待时间估算，不是上游实际完成比例；卡片重新挂载时等待计时可能重置。
第一段返回后，助手应先展示本次分段视频，再等待用户确认续做。
服务端模式的使用记录在页面可见时每 60 秒刷新，窗口重新聚焦时刷新，并显示最近刷新时间；MetaOntic AI 和火山直连不查询服务端记录。

工具

| 工具 | 用途 |
| video_generate | 新视频生成、逐段预览、暂停续做及合并 |
| video_extend | 已有视频向前 / 向后延长，逐段预览及续做 |
| video_status | 按任务 ID 查询实际状态与结果 |
| video_setup | 检查或经授权安装 ffmpeg |
| video_config | 查看或修改插件配置；A模式服务端 Key 不允许手填 |

常见问题

| 问题 | 处理 |
| 火山鉴权失败 | 检查 API Key、模型开通情况及火山接口错误；插件不能判断火山余额 |
| 服务端额度不足 | 查看 A模式额度和记录，按服务端提示处理 |
| 查询失败 / 超时 | 用任务 ID 复查；不要把查询失败当作任务未生成 |
| expired | 上游任务已超时，按终态返回，不继续轮询 |
| 长视频只生成了一段 | 正常逐段预览，确认后用 resume 继续 |
| 接缝动作回退 / 重复 | 对照原始分段，按实际重复范围裁剪；重演对白时可能需重新续拍 |
| 图片模式冲突 | 直连时参考图与首尾帧二选一，尾帧不可单独使用 |
| 新版界面未出现 | 本地链接先构建，等待热加载；仅宿主明确要求时重启 |

视频完成后的实际费用

MetaOnticVideo 和 MetaOntic AI 接入在视频生成或续拍完成后，使用同一视频 Key 只读查询中转消费日志，按任务 ID 提取最终结算额度及实际金额，并显示逐段费用与合计。暂停预览时仅统计已生成部分，部分任务未结算时只显示已结算小计；日志尚未返回、无权限或网络失败显示待结算 / 待查询，不影响视频交付。可用 video_status 携带原任务 ID 补查，不重新生成。不会把预扣金额、估价或账户余额差当作真实消耗，最终结算额度也不会与预扣重复相加。图片转换及额外重做费用不包含在当前视频任务合计中。火山直连不执行此中转账单查询。

本地开发热加载

Harness 默认启用 HMR 配置重载，但不监听本地插件源码。对于链接源码目录的安装，可在对应 profile 的 cordis.patch.yml 中配置 hmr 条目，监听已构建的宿主入口：

- id: hmr
disabled: false
config:
base: /你的路径/metaontic-video
root: [index.js]

base 使用本机插件目录绝对路径，仅配置在本机 profile，不写入插件发布配置。已有 HMR 配置时合并调整，保留其他项目的监听需求。配置由运行中的宿主加载；之后修改 TypeScript 并执行 npm run build，宿主入口热替换，客户端通过宿主 Client HMR 更新。构建失败先修复，不通过重启解决语法错误。package.json 的依赖或加载入口变化可能仍需按宿主提示重新安装或重启；插件规则变化在现有对话的下一轮请求生效，旧确认窗口需重新发起。正在生成视频时先等任务返回，再构建或更新，避免热替换中断当前调用；已有任务按任务 ID 查询或续做，勿重复提交。

v3.11.3 更新内容

优化

- 视频模型与图片模型分别分组，共用开关和共用 Key 位于模型上方，独立 Key 归入对应模型。
- 登录区移至接入方式下方，重置入口移至设置页底部，统一配置区的标签、间距与对齐。
- 画面比例与声音设置使用并排卡片和清晰的声音开关，窄窗口自动上下排列。
- 更多设置按画面、视频合并、查询与等待、本地工具分组；成对参数对齐，工具路径占整行，帮助说明归入对应分组。
- 完善宽窄窗口及明暗主题布局，同步中英文文案、真实指南配图和使用说明书 PDF。

更新插件

底部版本卡片始终显示本机当前版本及其包内更新内容，更新时间显示该版本的发布时间，与「检查于」时间分别显示；检查更新仅检测远端版本，不替换当前版本说明。
版本检测优先使用 Gitee，失败时回退标签列表与 GitHub 文件镜像；本地缓存减少重复请求。
在线更新需再次确认，由宿主执行重装并优先热加载；仅返回 restart-required 时提示重启。现有对话下一轮读取最新插件规则，不因普通规则、界面或工具更新要求重启或新建对话；预设身份等宿主创建时固定的属性不追溯改写。

开发与验证

源码入口为 src/index.ts（宿主装配）和 src/client.ts（浏览器装配）；功能按职责拆分：

src/
├── config.ts # 配置定义、默认值与公共常量 ├── tools/ # 生成、续拍、查询、环境检查、配置工具 ├── providers/ # 渠道解析、Seedance 请求、网络轮询与结果类型 ├── workflow/ # 分段规划、费用审批、暂停续做、执行信号 ├── media/ # 参考图处理、下载、FFmpeg 与合成 ├── prompts/ # 生成提示词与动态操作规则 ├── utils/ # 校验、错误转换、文件、JSON 与日志 ├── client/ # 设置、登录、更新、进度、样式与界面字典 └── locale/ # 插件元信息字典根目录 index.js、client.js 和 locale/.json 是构建产物，修改 TypeScript 后重新构建。宿主源码中的本地模块统一打包进 index.js，浏览器模块统一打包进 client.js，插件安装与热加载入口保持不变。
元信息文案在 src/locale/，导演预设在 cordis.patch.yml，脚本与提示词指南在 skills/video-director/。

npm install
npm run build
node --test tests/.test.mjs
npm pack --dry-run

npm run build 包含类型检查、文案生成和两端打包。测试覆盖模型时长、图片角色、配置保存、进度显示，以及三个渠道的模拟生成、查询、暂停续做和续拍链路；模拟测试不调用付费服务，不能替代真实生成或界面验收。

发布规范

只有用户明确提出「发版」时才执行发布。平时开发、修复和验证不因改动完成而自动更新版本号、改写 releaseNotes、创建版本标签、推送发布或创建 Release 或上传发布包。

收到发版指令后，先以最近一次已发布版本为起点，检查此后的提交和当前工作区，汇总所有尚未发布的逻辑改动；按新增、优化、修复整理成一份完整的更新内容，先向用户展示，再核对源码、构建产物、README、CHANGELOG、releaseNotes 和标签说明一致，最后按下述步骤一次发版。不能只总结最后一次修改，也不能遗漏此前积累的未发布改动。

仅发布正式版，使用 X.Y.Z 并设置 releaseNotes.prerelease: false。两仓 Release、附注标签、说明及插件包须保持一致，不再提供预发布渠道。正式发布须汇总从最近正式版以来的全部变化，包括此前已验证的改动，不覆盖历史标签。

插件版本卡片只保留「检查更新」和更新到最新正式版。过滤草稿与预发布，仅远端版本严格高于本机时显示更新入口，二次确认后安装对应 Release 成品包；Gitee 不可用时仅尝试同版 GitHub 附件。不提供历史版本选择、同版本重装或降级，不回退默认分支，也不先卸载现有插件。

版本采用语义化版本号：修复用patch，新增兼容功能用minor，不兼容变更用major。

每次发布必须：

1. 更新 package.json 的版本及 releaseNotes，其 version 必须与包版本一致，items 写用户能理解的变更；将 CHANGELOG.md 的未发布内容整理到对应版本，记录日期并同步完整更新说明。
2. 同步更新根目录 MetaOnticVideo使用说明书.md，逐项核对本次全部变更涉及的配置、操作步骤、默认行为及常见问题，删除过时说明，确保指南与当前版本一致；指南仅面向用户使用，不得加入插件版本号、适用版本、版本更新内容、更新日志、发布说明或发布核对记录；配图也遵守此约定。适用版本和本次核对结果仅记录在 docs/engineering/release-<版本>.md，更新内容统一放在 CHANGELOG、README 的更新区及包内 releaseNotes。未完成指南同步不得发布。
3. 同步锁文件，构建并执行相关验证，检查打包清单，确认包含更新后的操作指南。
4. 提交源码、构建产物与说明。
5. 创建附注标签（annotated tag），包含版本标题、变更分类及验证结果。
6. 推送分支和标签到 GitHub、Gitee，两个仓库都创建 Release 并上传同一插件包，再检查发布工作流结果。

标签说明统一格式如下；只保留本次适用分类，验证结果必须据实填写：

MetaOnticVideo v<版本>

新增
- 面向用户的新增能力

优化
- 行为或体验变化

修复
- 修复的问题

验证
- 构建、测试及实际验证结果
- 未验证的范围（如未进行付费生成）

将说明保存到UTF-8文件，例如 /tmp/metaontic-video-release.txt，再执行：

将 <版本> 换成实际版本号
git tag -a "v<版本>" -F /tmp/metaontic-video-release.txt
git push origin master "v<版本>"
git show --no-patch "v<版本>"

当前 origin 配置有GitHub与Gitee两个推送地址；其他开发环境须自行核对 git remote -v，确保两边均已推送。
v 标签会触发 GitHub Actions 构建插件包并上传到 GitHub Release。不要为补写说明强制覆盖已经公开的旧标签；从下次发布起采用附注标签。

插件包下载

版本包在 GitHub Releases 或 Gitee Releases 下载，文件名为 metaontic-video-<版本>.tgz。不再向 npm 注册表发布，无需配置 NPM_TOKEN 或 Trusted Publishing。

v 标签触发完整构建与测试，通过后使用 GitHub 自动令牌上传插件包，并使用仓库 Actions Secret GITEE_TOKEN 创建 Gitee Release 和上传同一插件包。该密钥应具有 hackloop/metaontic-video 的发布权限；缺失或上传失败时工作流明确报错，不将单仓成功报告为双仓成功。手动运行工作流时须选择与包版本匹配的标签。

本机打包可执行 npm pack --pack-destination /tmp。需要目录安装时，将 .tgz 解压后使用其中的 package 目录：

mkdir metaontic-video-plugin
tar -xzf metaontic-video-<版本>.tgz -C metaontic-video-plugin
dsh plugin --profile desktop add ./metaontic-video-plugin/package

推送后的更新总结规范

每次推送后必须提供以下信息，且与 package.json 的 releaseNotes 和附注标签一致：

版本：vX.Y.Z 提交：短提交号推送：GitHub / Gitee 各自是否成功，附注标签是否成功

更新内容：
- 新增：用户可以使用的新能力
- 优化：变化后的交互或行为
- 修复：解决的具体问题

验证：实际执行的构建、测试和打包检查限制：未进行的付费生成、界面验收等发布状态：源码与标签已推送 / 打包工作流已触发 / Release 插件包已验证

只保留本次适用的更新分类。未核实 Release 附件时不能写「插件包上传成功」；部分仓库推送失败时明确列出，不能笼统称全部成功。
发布前检查工作区差异，确认本次提交范围；完成后报告实际提交号。

官方资料与反馈

- 创建视频生成任务 API
- Seedance 2.0 教程
- Seedance 2.0 提示词指南
- Seedance 2.5 提示词指南
- GitHub 问题反馈
- Gitee 镜像

模型一致性、口型和接缝效果以实际预览为准；具体 API 能力与插件已开放的设置可能不同。

请求日志

创建与查询视频任务会写入 ~/.dsh/logs/metaontic-video/YYYYMMDD/requests.jsonl（目录日期使用本机时间；设置 DSH_HOME 时跟随该目录）。
每次请求都有独立 requestId，记录开始、完成或失败事件，以及接入方式、模型、时长、素材数量、HTTP 状态、耗时、任务 ID 和上游请求 ID（接口提供时）。
统计 operation=create_task 且 event=request_started 可核对插件尝试提交的次数；query_task 只表示查询，不能算新增生成。
开始后没有结束日志可能是进程退出；网络错误也不能证明上游未受理，先复查任务与上游记录。
日志不记录 API Key、请求体、完整提示词、Base64 或签名视频链接。日志按日保留，未自动清理。

独立浏览器样式预览

运行 npm install 后，执行 npm run preview，打开 <http://127.0.0.1:4174>。
直接复用 src/client.ts 的设置页与生成进度卡片，修改源码后浏览器自动刷新，无需安装插件或重新构建。

顶部可切换服务端已登录/未登录、MetaOntic AI、火山直连、请求失败场景，以及明暗主题、宽窄屏和中英文；可模拟保存失败。进度卡片支持生成、延长、成功与失败状态。
配置快照方便核对交互，刷新后恢复模拟初始值。所有请求均由预览页拦截，不连接真实服务、不生成视频、不写入 Harness 配置；请使用模拟 Key。
主题变量模拟宿主环境，最终样式仍以 Harness 中实际呈现为准。
可用 PREVIEW_PORT=4175 npm run preview 更换端口。

普通更新提示：打开插件设置页时后台检查新版本，发现更新后在顶部提示，可选择「立即更新」或「稍后再说」。安装前仍需确认；稍后处理不影响继续使用，同一版本不再显示顶部提醒，底部版本卡片仍可更新。手动「检查更新」可重新显示提醒，更高版本出现时再次提示。更新检查不会自动安装或限制生成。

真人参考图与图片模型（MetaOnticVideo、MetaOntic AI 接入）

设置页分别选择「视频模型」和「图片模型」。图片模型支持 doubao-seedream-5-0-260128（默认）和 doubao-seedream-5-0-pro-260628，沿用当前 MetaOnticVideo / MetaOntic AI 的地址；MetaOnticVideo 固定共用登录下发的 Key；MetaOntic AI 默认开启「图片模型与视频模型共用 Key」，关闭后需单独填写「图片模型 Key」，图片提交、查询与取件均使用该独立 Key，视频仍使用原 Key，通过异步任务接口调用：POST /v1/tasks/doubao 提交，GET /v1/tasks/{task_id} 轮询，成功后 GET /v1/tasks/{task_id}/artifacts 取图片地址；轮询与取件不含通道名，不使用同步备选接口。

助手根据图片或用户说明判断真人参考图；无法看图时先澄清。真人图先确定动画、卡通或插画等非真人风格，说明图片调用单独计费，经确认后调用 video_prepare_image，展示并核对处理结果，再把返回的 imageUrl 用作视频参考图或首尾帧。处理失败、结果仍像真人时停止，不回退到原真人图；非真人图片直接使用。此流程由助手按动态规则执行，不是像素级自动真人检测。火山直连暂未接入此预处理工具。

MetaOnticVideo、MetaOntic AI 视频调用若在提交或查询终态返回明确的真人/人脸限制，插件会单独询问是否将本次参考图转为非真人二维动画风格并重试视频一次，同时说明图片处理与视频重试分别计费。仅用户明确允许后转换；每张图片的任务与结果独立保存，完成后返回 review_required 并展示处理后的全部参考图。用户核对并确认后，使用原 resumeDir 和 referenceImagesReviewed=true 续做，最多重试视频一次；恢复进度不会再次转换已完成图片。拒绝、取消、无法确认或转换失败均停止，不使用原图重试。普通审核拒绝、网络错误、状态未知与超时不触发转换；仅有参考视频而没有图片时提示更换素材。

图片请求使用 image 数组、size=2048x2048、n=1。图片任务默认最多等待 300 秒，取消、超时或查询失败会在错误中保留图片 task_id，可用 video_prepare_image(taskId=...) 查询与取件，不重新提交。敏感内容或计价错误直接报告，不自动去掉参考图或降级重试。

恢复与提交核对

清晰度不在插件设置页配置；脚本阶段由用户选择 480P 或 720P，生成时显式传入 resolution；费用预估使用所选清晰度。分段续做的制作确认、费用预估和生成均沿用已确认清晰度；恢复已提交的任务继续使用原请求参数。
提交超时或响应缺少任务 ID 时，插件返回 submission_unknown 和 submissionId，停止自动重发。用 media_submission 查询本机记录，在原渠道核对后关联原任务 ID；只有用户明确确认渠道没有创建任务，才允许解除防重。此工具本身不生成媒体。图片任务查询使用 video_prepare_image(taskId=...)；独立图片生成的相同请求优先复用已知任务，确需新图时指定不同 seed。

任务开始时固定本次连接配置，修改设置仅影响后续调用。恢复未完成任务需要原接入方式、地址和 Key。

脚本整理时需要用户明确确认视频清晰度，目前提供 480P / 720P 两种选择。本次需求已明确指定则直接记录，不重复询问。确认后写入脚本，并在制作确认中展示，按该值生成；未回答或取消时不开始制作。普通改稿保留已确认清晰度，改变清晰度须重新确认。

生成参数按「接入与密钥 → 模型配置 → 画面与声音」分组。MetaOntic AI 模式的模型配置组顶部先选择是否共用 Key，共用时按「共用 Key → 视频模型 → 图片模型」排列，不共用时按「视频模型 → 视频模型 Key → 图片模型 → 图片模型 Key」排列；MetaOnticVideo 模式的模型配置仅显示视频模型和图片模型，不展示 Key 或共用方式；视频模型和图片模型分别分组，画幅和声音并排显示，窄窗口自动改为单列。图片独立 Key 仅在关闭共用后显示；火山直连隐藏图片相关字段。视频清晰度仍在脚本阶段确认。

Key 共用规则：MetaOnticVideo 接入固定共用登录下发的 Key，模型配置中不显示 Key、Key 状态或共用开关；仅 MetaOntic AI 接入可以选择共用或分别填写视频模型 Key、图片模型 Key。MetaOnticVideo 忽略旧配置中残留的独立图片 Key。

服务端接入的额度卡片在「刷新额度」右侧提供「人工充值」，点击后弹出企业微信客服二维码页面；支持关闭、Esc 退出，并提供直接打开客服页的链接。

对白发音校对

脚本审核前检查易误读词、数字与缩写；脚本/字幕保留正确原文，必要时另列发音文本。分段提示词仅带本段完整台词，明确语言、说话人和先后顺序，预留停顿与结尾；生成及续拍请求包含对白执行约束。参见 发音与吐字规范。

原生声音生成不能保证逐字准确。结果须实际试听，无法试听时明确待核听；误读片段的付费重做须另获同意，不自动重试。独立配音与后期替换可作为严格准确性需求的制作方案，当前插件未实现自动配音或口型修复。

阶段耗时

同一日志记录 stage_started / stage_finished，以 spanId 配对，含 startedAt、finishedAt、elapsedMs、outcome，工具调用通过 callId 关联。自动覆盖插件工具总耗时、视频轮询等待、分段下载/探测、接缝准备、合并与真实费用查询；HTTP请求沿用request日志的elapsedMs。脚本设计、示意图、展示与用户审核等待由助手调用无费用 video_stage 标记边界。审核等待单独统计；标记间墙钟耗时包含调度，不等于模型纯推理时间。中断只有开始无结束时按未完成处理；热重载丢失的标记返回unavailable，不伪造耗时。日志不可写不影响生成，不重提任务。

续拍估价统一口径：首段无视频输入，参考图/首尾帧也不改变此档位；后续续拍有视频输入，用上一段完整视频时长加本段输出时长计token，采用含视频输入单价。脚本末尾逐段展示档位、输入/输出时长、单价及金额；恢复制作确认读取上一段时长，外部输入视频时长未核实时不猜价。

脚本审核会核对本轮分镜图登记与正文内嵌：present成功不等于已展示，卡片在轮次结束后出现；须先发图片正文，再单独打开审核问题，缺失时拦截并提示补展示。检查基于当前插件加载后观察到的会话事件，不追溯旧窗口。