MetaOnticVideo — DeepSeek Harness AI 视频创作插件
MetaOnticVideo：DeepSeek Harness AI 视频创作插件
用 Seedance 2.0 / Mini / Fast 多段续拍，制作超过 15 秒的 AI 视频。 从自然语言需求开始，完成脚本与分镜审核、文生视频或图生视频、逐段预览、断点续做和 FFmpeg 本地合并。
MetaOnticVideo is an AI video creation plugin for DeepSeek Harness. Create videos longer than 15 seconds with Seedance 2.0 video continuation, reference images, script review, segment previews, resumable generation and local FFmpeg merging.
安装与 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 图片处理须另行确认并单独计费。
三步开始使用
- 在 DeepSeek Harness 的插件页安装 MetaOnticVideo，参见安装说明。
- 选择 MetaOntic AI，在 ai.bileego.com 注册获取 Key，填写对应视频／图片 Key 并保存。
- 新建会话 → 模式选择 → 视频创作助手，发送需求；先看脚本与分镜，再确认费用和制作。
示例需求：
做一条30秒的民勤蜜瓜介绍视频，16:9横屏，480P。
主角站在瓜田里自我介绍，再蹲下轻拍蜜瓜，中文同期声与环境声，不加字幕。
先展示完整脚本、分镜示意图和费用预估，我确认后再生成。
常见问题
Seedance 2.0 如何生成 30 秒或 60 秒视频？
通过多段视频续拍与本地合并完成。首段无视频输入，后续续拍使用上一段完整视频，费用按各次实际调用计算；脚本审核先展示全片预估，完成后查询支持渠道的实际结算。
支持文生视频、图生视频和已有视频续拍吗？
支持。新视频可从文字、参考图、首帧或首尾帧开始；已有视频续拍需要上游可访问的视频地址，不能直接把本地路径作为视频输入。具体素材能力取决于模型与接入渠道。
视频清晰度在哪里选择？
在对话的脚本阶段确认 480P 或 720P，后续分段沿用已确认清晰度。插件设置中选择模型、画幅与声音，清晰度不在设置页配置。
分镜示意图和真人参考图处理会调用图片模型吗？
分镜示意图默认在本地绘制，不调用付费图片模型。真人参考图需要转换为非真人风格时，先取得用户同意，再调用 Seedream；展示处理结果并审核后才用于视频，图片与视频分别计费。
生成中断后需要从头重做吗？
先按任务 ID 查询，或使用原 resumeDir 继续；已完成分段可恢复交付。请求结果不明时停止自动重发，核对原渠道记录后再处理，避免重复提交。
Windows 安装提示「不是有效的插件包」怎么办？
安装框要填的是 .tgz 成品文件路径，不是文件夹路径。解压 ZIP 后如果把 MetaOnticVideo-Windows 外层文件夹或 package 资料目录填进去，就会出现这个提示；请改填该 .tgz 的完整路径，层级以实际解压位置为准（常见为两层同名文件夹，例如 D:\software\MetaOnticVideo-Windows-数字版本号\MetaOnticVideo-Windows\metaontic-video-数字版本号.tgz），建议右键复制文件地址。
不想在本机找路径时，也可以直接粘贴 .tgz 附件的下载链接（GitHub 或 Gitee 均可，形如 https://gitee.com/hackloop/metaontic-video/releases/download/v数字版本号/metaontic-video-数字版本号.tgz），效果与填写本地文件路径相同；这类在线安装地址必须以 .tgz 结尾，.zip 附件、package 文件夹和发布页网址都只能用于本地安装。要复制的是附件下载链接，不是发布页网址，也不要选 Source code；Gitee 请打开发布页 https://gitee.com/hackloop/metaontic-video/releases，不要用会直接下载源码包的 /releases/latest。
安装报 ERR_PNPM_MISSING_TARBALL_INTEGRITY 怎么办？
安装日志里出现 its lockfile entry has no "integrity" field 时，问题不在插件包，而在 DeepSeek Harness 插件安装目录里遗留的 pnpm-lock.yaml：这条 .tgz 地址的记录缺少校验值，pnpm 为保证安装内容未被篡改会直接拒绝，换在线地址、换本地 .tgz 路径或重装旧版本都会一样失败。插件运行时会每 2 秒检查该文件，发现本插件这类记录（含旧版本留下的、已经没人引用的残记录）就删掉并留一份 pnpm-lock.yaml.metaontic-backup-时间 备份，更新失败后还会等清理完成自动重试，所以已经装上插件的情况下通常无需人工干预。插件还没装上、后台没有这个清理动作时，完全退出 Harness，删除该目录下的 pnpm-lock.yaml（Windows：C:\Users\<用户名>\.dsh\profiles\desktop\pnpm-lock.yaml；macOS：~/.dsh/profiles/desktop/pnpm-lock.yaml；设置了 DSH_HOME 时在其下的 profiles/desktop），再重新安装一次即可，安装器会重新生成该文件。只删 pnpm-lock.yaml，不要删同目录的 package.json。
使用与开发导航
脚本与续拍过渡
续拍方式由已审核脚本决定，不在插件设置页配置，也不通过 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+，桌面端提供运行环境。
Windows 与 macOS 均推荐安装正式版 .tgz 成品包，避免依赖 Git 拉取：
- 打开 GitHub 最新正式版 或 Gitee 发布页。
- 复制附件
metaontic-video-<版本>.tgz 的下载链接，在「插件 → 添加插件」中粘贴安装；在线安装的地址必须以 .tgz 结尾，不要使用 Source code、仓库地址或 .zip 附件。
- 也可下载后解压，通过本地目录安装其中的
package 文件夹。
终端安装同样使用实际 .tgz 附件链接：
dsh plugin --profile desktop add "复制的.tgz附件下载链接"
若 Windows 报 ERR_PNPM_GIT_RESOLVE_FAILED，改用上述成品包来源；无需修改全局 Git 配置或关闭供应链检查。详细步骤见使用说明书。
从本地源码安装：
npm install
npm run build
dsh plugin --profile desktop add /你的路径/metaontic-video
本地安装链接源码目录；启用下述本地热加载后，执行 npm run build 即可更新工具与界面，无需反复重启。源码安装仅用于开发，普通用户使用正式版成品包。
选择接入方式
打开「插件 → 已安装插件 → 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插件方案”两项人民币基础估价，写在脚本最后的“费用预估”一节并随完整脚本展示，列明模型、分段、分组倍率与价格日期。续拍计入上一段视频输入，最低用量补足尚未计入；图片处理、重试与独立配音另计，实际以账单为准。官方参照一律采用 Seedance 2.5（一段按 30 秒计，不足 30 秒的尾段也按 30 秒），超过 30 秒也如实分段；未知模型或画幅不猜价。手填Key未核实分组时不默认套用折扣。试算不会调用模型或扣费，也不改变脚本审核和制作确认两道流程。
每次脚本审核前，无论单段还是多段，都会交付当前版镜头参考示意图；需要分段生成时，另展示每段的时长、内容和衔接方案。示意图不代表成片效果，不额外调用付费出图模型。改稿同步更新方案与示意图；实际视频仍逐段预览并确认续做。
新视频需要两道确认：
- 展示脚本，包含画面风格、人物、镜头与时间安排、完整对白，等待审核。
- 审核通过后单独确认是否开始制作，之后才调用生成工具。
审核前必须实际展示当前版完整脚本；保存文件或只给路径不算展示。有文件展示工具时先展示并等待完成，再单独弹审核窗；展示失败时在正文贴出完整脚本。修改脚本后重新展示当前版，并再次弹出脚本审核窗口；当前版通过后再单独确认费用与制作，旧版同意不沿用。提问工具不可用时才退回文字确认。已有视频延长无需完整脚本，但要先确认方向、内容、时长和制作费用。
助手根据内容选择喜剧、情绪、商品、知识或氛围结构；先明确人物目标与故事变化，再写动作和自然对白。
脚本留足停顿与反应时间，不强行套反转。制作文件保存在 video-projects/<slug>/，包括脚本、提示词与镜头记录。
长视频与逐段预览
2.0 生成20秒时，通常规划为15+5秒；2.5 生成20秒可一次直出。
- 写好全片脚本与逐段执行提示词。
- 生成第一段，先下载交付预览。
- 返回
paused: true、resumeDir、remainingSeconds。
- 用户确认继续后，将原
resumeDir 传给同一个工具的 resume 参数。
- 续拍下一段并交付当前累计成片；仍有剩余则再次暂停，直到完成。
同一个暂停目录同时只允许一次续做，避免重复提交。已完成的分段不重复生成。
新增视频的多段计划必须提供与计划等长的 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_estimate | 脚本审核前的只读双方案估价与逐段费用明细 |
video_prepare_image | 经授权处理真人参考图，展示转换结果后再用于视频 |
video_generate | 新视频生成、逐段预览、暂停续做及合并 |
video_extend | 已有视频向前 / 向后延长，逐段预览及续做 |
video_status | 按任务 ID 查询实际状态与结果 |
video_setup | 检查或经授权安装 ffmpeg |
video_config | 查看或修改插件配置；服务端领 Key 模式不允许手填该 Key |
media_submission | 核对提交不明的原任务，避免重复提交 |
video_stage | 记录脚本、示意图、展示与审核等待的阶段耗时；脚本保存为 script.md 后由插件自动结束脚本设计一段 |
故障排查
| 问题 | 处理 |
|---|
| 火山鉴权失败 | 检查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.13.13 更新内容
优化
- 命中上面这条报错时不再直接放弃——更新会等后台清理完成自动重试，用户不用自己数着秒再点一次；仍然失败才提示手动删除锁文件。中英文提示同步改为「每 2 秒自动清理 + 自动重试」。
- 使用说明书、README 与工程规范同步这次排查结论与处理方式：说明该报错与插件包、操作系统无关，不是 Windows 文件占用问题，先等自动清理与重试，仍失败再完全退出 Harness 删除安装目录下的 pnpm-lock.yaml 后重装；说明书配图与 PDF 已随正文重新导出。
修复
- Windows 在线更新反复失败、报 ERR_PNPM_MISSING_TARBALL_INTEGRITY 的问题。安装目录的 pnpm-lock.yaml 里只要留着一条本插件缺少校验值的远程包记录（包括旧版本留下的、已经没人引用的记录），pnpm 就会拒绝整次安装。插件现在按「本插件所有远程记录里哪些拿不到合法校验值」来判断，profile 根目录、下级目录与同级的临时 staging 目录里的锁文件都会检查，检查间隔由 10 秒缩短到 2 秒，坏记录连同依赖声明一起清掉、其他依赖和带校验值的正常记录不动，改前文件另存为 pnpm-lock.yaml.metaontic-backup-时间。
v3.13.12 更新内容
优化
- 脚本设计阶段的耗时统计改由插件自动结束——完整脚本保存为 script.md 后自动闭合该段计时并写入 script_saved 日志，不再依赖模型手动调用结束，阶段耗时统计更准确；脚本不是用写文件工具保存时仍按原方式补结束。
- 新增维护者清理命令 npm run clean:releases（默认只演练），按同一份计划回收两个仓库的历史标签、发行版与发行版附件，最新正式版始终保留；并配套每周演练工作流，只有确认后才真正删除。
修复
- 发布时 Gitee 上传成品包偶发 HTTP 400 会让整次发布中断；现在失败会带出服务端返回正文，先复查附件表是否已收完，再按退避自动重试，减少人工重跑。
v3.13.11 更新内容
优化
- 更新失败命中这条报错时，不再对同一地址重试三次、也不切换到另一个镜像源（这两种做法实测都同样失败，只会让用户白等），直接给出针对性提示：等待十几秒后再点一次「更新到最新正式版」，仍失败时再按提示手动删除 pnpm-lock.yaml；只有插件还没装上、后台还没有该清理动作时才需要手动处理。
- 使用说明书与 README 同步写明自动清理与备份文件的位置，并说明这条报错与插件包、操作系统无关，避免继续把它当成 Windows 文件占用问题去排查。
修复
- 在线或本地安装报 ERR_PNPM_MISSING_TARBALL_INTEGRITY（安装目录的 pnpm-lock.yaml 里留着一条缺 integrity 的远程 tgz 记录，pnpm 因此拒绝整次安装）时，插件现在会在后台自己清掉本插件这条坏记录：加载时检查一次、之后每 10 秒复查，改前把原文件另存为同目录下的 pnpm-lock.yaml.metaontic-backup-时间，其他依赖和带校验值的正常记录一律不动，清理后更新即可继续，不再需要用户手动删除该文件。
v3.13.10 更新内容
新增
- 新增测试包分发通道，在仓库执行
npm run pack:test -- 版本号-后缀 就会自动构建、运行单元测试、打出测试版 .tgz、上传到 https://video.mybfs.cn/test/，并核对线上文件与本地 sha256 一致后输出可直接转发的安装地址，未发布的改动可以先给他人试用。
优化
- 测试包不占正式发布页，只改包内版本号，不提交、不打标签、不建 Release，核心版本号压在当前正式版之下，其他人仍会正常收到正式版更新提示；脚本结束后把包内版本号与构建产物还原为正式版本，不会把测试版本带进正式包。
- README 发布章节与工程维护经验补充测试包通道的用法、线上目录和回退方式；
/test/ 目录禁止缓存与搜索引擎收录，测试者用正式版 .tgz 地址重装即可回到正式版。
v3.13.9 更新内容
优化
- 使用说明书、README 与 Windows 压缩包教程统一写明在线安装只认以 .tgz 结尾的成品附件地址，并给出本版本可直接复制的 Gitee 与 GitHub 地址；MetaOnticVideo-Windows 压缩包、解压出的 package 文件夹、发布页网址和 Source code 只能用于本地安装，粘贴到在线安装框会提示「不是有效的插件包」。
- Windows 压缩包图文教程第 4 步同步补充在线安装地址要求，图文版与文本版内容一致；使用说明书 PDF 重新导出后随包发布。
修复
- 安装报 ERR_PNPM_MISSING_TARBALL_INTEGRITY（提示 lockfile 记录缺少 integrity 字段）时，换在线地址、换本地 .tgz 路径或重装旧版本都会一样失败；使用说明书、README 与 Windows 压缩包教程新增处理方法：完全退出 DeepSeek Harness，删除插件安装目录下的 pnpm-lock.yaml 后重新安装，安装器会重建该文件，已保存的插件设置不受影响。
- 在线安装填入 ZIP、package 文件夹、发布页网址或 Source code 时只提示「不是有效的插件包」，用户难以判断原因；三处文档现在都写明只认以 .tgz 结尾的附件地址，并给出可直接复制的真实地址。
v3.13.8 更新内容
优化
- 费用预估里的“火山官方方案”统一按 Seedance 2.5 计算，一段按 30 秒计，不足 30 秒的尾段也按 30 秒计，不再按剩余秒数折半；超过 30 秒如实按分段列出。
- 使用说明书里的成品下载地址更新为本版本，Gitee 与 GitHub 两条 .tgz 地址可直接复制粘贴安装。
- 发布流程新增校验，使用说明书里的成品地址必须与本次发布版本一致，不一致直接失败，避免指南长期指向旧版本。
修复
- 多段视频交付时合并成片没有排在第一个位置的问题；现在成片固定排在最前，助手若把分段放在成片前面，插件会拦下这次展示并让他把成片挪到第一位重发，不会因此少给成片或分段。
v3.13.7 更新内容
优化
- Gitee 流水线补全为完整的构建校验：向 master 推送、发起面向 master 的 PR 或推送标签时，自动准备环境、安装依赖、执行构建与单元测试，并把 tgz 与 Windows 成品包放进流水线制品供下载核对。
- Gitee 构建机不再依赖预装环境：Node 20 由流水线自行下载（老镜像自动改用 glibc 兼容版），Windows 成品包所需的 Python 3 也会按需安装；缺失时日志给出明确提示，不再静默跳过。
- Gitee 流水线按标签运行时核对标签与包内版本是否一致，不一致立即失败，保证成品与标签对应；同时新增 ci- 开头的演练标签，可随时验证按标签运行的流程，演练不产生发布件。
v3.13.6 更新内容
优化
- 使用说明书精简为面向使用的基础流程，移除角色参考图风格清单等细节条目；角色图的选择、单独计费、展示审核与真人限制转换流程仍在正文保留。
- Windows 安装说明补充可直接复制粘贴的成品地址，写明 Gitee 与 GitHub 两个来源，并说明发布新版本后如何替换地址中的版本号。
v3.13.5 更新内容
新增
- Windows 安装说明新增“直接粘贴成品下载地址”的安装方式，压缩包教程里写出本版本真实的 Gitee 与 GitHub .tgz 附件地址，复制粘贴即可安装，不必先把文件下载到本机。
优化
- 安装路径示例按真实解压结果修正（常见为两层同名文件夹），并建议右键 .tgz 选择“复制文件地址”获取完整路径，避免手打后填成文件夹路径。
修复
- 安装指引中的下载入口统一为发布页地址，并说明 Gitee 的 releases/latest 会直接下载源码包、Source code 不是插件成品，避免把源码包当成安装文件。
v3.13.4 更新内容
优化
- Windows 安装教程第 3、4 步补充“安装框要文件路径、不要文件夹路径”，常见问题新增“提示不是有效的插件包”条目；使用说明书 1.3 节同步更新并重新导出 PDF。
修复
- 修正 Windows 安装指引。安装框要填 .tgz 成品文件路径，填入解压后的 MetaOnticVideo-Windows 外层文件夹或 package 资料目录会提示“不是有效的插件包”；现在压缩包教程、使用说明书与 README 都写明这一点，并在常见问题给出该提示的排查方法。
- Gitee 附件上传超时由 60 秒延长到 5 分钟，并在上传超时后复查附件是否已存在且大小一致，避免 Windows ZIP 等较大成品被误判为发布失败、导致镜像发布页缺少附件。
v3.13.3 更新内容
新增
- 一键发布脚本，运行 npm run release -- X.Y.Z 即可完成整轮发布；也可双击 Windows 的 release.cmd 或 Mac 的 release.command 按提示输入版本号。
- 一键发布支持 --dry-run 只检查计划，不写文件、不改版本、不提交、不联网；支持 --resume 在同一版本下续跑未完成的发布，不覆盖已有标签。
优化
- 一键发布会先显示待发布范围与更新说明，再更新版本号与锁文件、同步 README 与 CHANGELOG 及包内更新说明，然后构建、测试、打包、提交、打附注标签、推送双仓、等待双平台安装检查与附件上传，最后输出发布页、tgz 安装地址和 Windows ZIP 下载地址。
- 构建改用跨平台脚本 scripts/build.mjs，去掉此前依赖命令替换的写法，Windows 与 macOS 都能直接构建插件、客户端与语言文件。
- Windows 安装资料包内的图文教程重写为六步操作（解压 ZIP → 找到 .tgz → 复制完整路径 → 粘贴到「添加插件」→ 填 Key 保存 → 开始创作），并给出安装成功的判断标志与可折叠的常见问题；网页版与文本版内容一致。
- 使用说明书补充 Windows 本地安装要点，明确新安装填写 .tgz 文件路径、package 目录只用于查看资料或恢复旧安装，从界面粘贴路径时需删除两端的英文双引号。
修复
- Windows 安装资料包内的「先读我」文本改用 CRLF 行尾，用记事本打开不再整段挤在一行。
v3.13.2 更新内容
修复
- 立即更新前读取真实安装来源，本地目录链接安装停止直接替换，避免触发外部目录异常；不卸载、不清目录、不重置Key。
- 安装来源无法核实、查询失败或元信息异常时停止更新，不继续调用安装器。
优化
- tgz成品及仓库安装保留在线更新入口；补充本地目录用户的恢复与迁移限制说明。
- 双平台发布检查增加真实成品包升级，验证语言资源、原安装文件、配置与任务记录；增加目录链接与异常来源回归测试。
v3.13.1 更新内容
修复
- Windows安装资料ZIP内置原始tgz，改为安装成品文件，由安装器管理插件文件，减少对外部解压目录的依赖。
优化
- 补充旧安装目录变空、locale缺失的完整目录恢复步骤，保留Key、配置及任务记录，不先卸载或重置。
- Windows ZIP采用固定时间戳并附SHA-256校验，重复打包一致，确保跨仓同步使用相同附件。
新增
- 建立Windows/macOS兼容开发规范，发布前自动在双平台验证成品安装、中文空格路径、语言资源、技能、指南及源文件移走后的加载。
v3.13.0 更新内容
新增
- 角色参考图支持真人写实，风格建议第一位；按用户明确选择生成，保留独立费用确认和图片审核，上游拒绝不自动重画。
- 提供Windows安装资料ZIP，包含插件成品、中文图文安装教程与完整使用说明书，免Git拉取即可本地安装。
修复
- 纯文生视频提交前强制询问角色图方案；未回答、取消、交互不可用或记录失败时停止提交，选择先出图时不直接提交视频。
优化
- 同一会话及脚本规格保留明确选择，已有参考图与断点恢复不重复询问，不修改或重提已有任务。
- 完善Windows、Mac安装、Key配置、在线更新及错误排查教程，同步说明书、PDF及内置规则。
v3.12.1 更新内容
修复
- 纯文生视频在提交前强制询问角色图方案，不再仅依赖助手提示词；未回答、取消、交互不可用或记录失败时停止提交，不默认跳过。
- 用户选择先生成角色图时停止纯文生请求并转入出图及审核；选择直接文生后才继续原视频费用与制作确认。
优化
- 同一会话和脚本规格保留明确选择，重复尝试不重复询问；已有参考图和断点恢复不重问，不改动或重提已提交任务。
- 同步使用说明书、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。
每次发布必须：
- 更新
package.json 的版本及 releaseNotes，其 version 必须与包版本一致，items 写用户能理解的变更；将 CHANGELOG.md 的未发布内容整理到对应版本，记录日期并同步完整更新说明。
- 同步更新根目录
MetaOnticVideo使用说明书.md，逐项核对本次全部变更涉及的配置、操作步骤、默认行为及常见问题，删除过时说明，确保指南与当前版本一致；指南里写死的 .tgz 成品地址（Gitee 与 GitHub 各一条）同步改为本次版本，发布脚本会校验不一致直接失败；指南仅面向用户使用，不得加入插件版本号、适用版本、版本更新内容、更新日志、发布说明或发布核对记录；配图也遵守此约定。适用版本和本次核对结果仅记录在 docs/engineering/release-<版本>.md，更新内容统一放在 CHANGELOG、README 的更新区及包内 releaseNotes。未完成指南同步不得发布。
- 同步锁文件，构建并执行相关验证，检查打包清单，确认包含更新后的操作指南。
- 提交源码、构建产物与说明。
- 创建附注标签（annotated tag），包含版本标题、变更分类及验证结果。
- 推送分支和标签到 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；Windows安装资料包为 MetaOnticVideo-Windows-<版本>.zip，附带图文教程、完整PDF及SHA-256校验文件。ZIP解压后安装其中tgz成品文件，package目录仅作资料及旧目录恢复；ZIP本身不要粘贴到插件安装框。不再向 npm 注册表发布，无需配置 NPM_TOKEN 或 Trusted Publishing。
v* 标签触发完整构建与测试，通过后使用 GitHub 自动令牌上传插件包，并使用仓库 Actions Secret GITEE_TOKEN 创建 Gitee Release 和上传同一插件包。该密钥应具有 hackloop/metaontic-video 的发布权限；缺失或上传失败时工作流明确报错，不将单仓成功报告为双仓成功。手动运行工作流时须选择与包版本匹配的标签。
某次发布只补齐镜像时，手动运行 sync-gitee 工作流并填写对应标签；它从 GitHub Release 取回该版本的 .tgz、Windows ZIP 及校验文件，逐个补传到 Gitee 发布页并核对大小，不会覆盖或改动已有附件。
Gitee 侧另有一条 Gitee Go 流水线（.workflow/MetaOnticVideo.yml）：向 master 推送、发起面向 master 的 PR 或推送 v* 标签时，在 Gitee 构建机上安装依赖、构建并运行单元测试，再校验版本元数据；每次运行都会打出成品并作为该次流水线的制品留存，可在 Gitee 的流水线运行结果页直接下载：metaontic-video-<版本>.tgz 总会生成，Windows 包 MetaOnticVideo-Windows-<版本>.zip 及配套 .sha256 需要构建机上有 Python 3（没有时会自动尝试安装，仍不可用时跳过并在日志中提示，此时 Windows 成品以正式发布页附件和校验文件为准）。标签触发时还会核对 v<版本> 标签与 package.json 里的版本是否一致，不一致直接失败，保证成品按标签出。想在发版前演练一次按标签的流程，可以打以 ci- 开头的演练标签（如 ci-test）：它同样触发构建与打包，但跳过标签与版本的强校验，制品只作演练用。这条流水线只生成成品，不发布版本：GitHub 与 Gitee 的 Release 成品始终由 publish 工作流按 v* 标签产出，避免两处各打一份包导致成品不一致。流水线不依赖 Gitee 下拉里提供的版本：构建机上没有可用 Node 时，它会自己从 npmmirror 下载 Node 20（按 glibc 自动选择官方构建或 glibc 2.17 兼容版），并缓存到 ~/.local/node；因此免费构建机即使镜像较旧也能跑通。
本机打包可执行 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 附件时不能写“插件包上传成功”；部分仓库推送失败时明确列出，不能笼统称全部成功。
发布前检查工作区差异，确认本次提交范围；完成后报告实际提交号。
定期清理历史标签与发行版（维护者）
历史版本会不断累积标签、Release 和发行版附件，插件只对外提供最新正式版，因此可以定期回收旧版本。清理脚本同时处理 GitHub 与 Gitee，先演练、后删除：
npm run clean:releases
npm run clean:releases -- --apply
默认只打印清理计划，加 --apply 才真正删除；发行版与标签各保留最近 10 个，演练标签等不符合 v* 模式的标签默认忽略。常用参数：
--keep <n>：保留最近 n 个正式版发行版，默认 10；小于 1 会被拒绝。--keep-tags <n>：保留最近 n 个标签，默认与 --keep 相同；两条保留线取并集，避免只推过标签没建发行版的版本被误删。--max-age-days <n>：只清理 n 天以前发布的版本，新版本本次不动，适合先小步试跑。--patterns 'v*,ci-*'：参与清理的标签模式，默认 v*；加 ci-* 可一并回收演练标签。--keep-prerelease：额外保留最新的预发布，默认连同其他预发布一起删除。--prune-assets：删除保留版本里不属于该版本的残留附件（例如旧命名或手动上传的文件），执行前会重新读取远端实际列表。--host github|gitee|all：只清理其中一个仓库，默认两个都清理。--json：以 JSON 输出计划，便于日志归档。
不管参数怎么配，最新正式版、当前 package.json 版本、以及 README、使用说明书、CHANGELOG、工程经验里 .tgz 下载地址引用过的版本都会保留，避免现成链接失效；演练会同时给出预计释放的附件体积，便于对照 Gitee 配额。
删除顺序是先附件、再 Release、最后标签，两个仓库与本地同名标签同步处理；单个仓库缺发行版时只删标签。待删标签取远端标签列表（git ls-remote）与 Gitee 标签接口的并集，只在 Gitee 推过的标签同样进计划。GitHub 标签用 gh api 删除；Gitee 开放接口只有标签的读取与创建、没有删除端点，所以 Gitee 标签靠带 GITEE_TOKEN 的 HTTPS 推送删除引用（令牌只从环境变量读取，不进入命令行与日志）。脚本只删除计划内的对象，失败项会汇总后非零退出，可重复执行。
需要长期无人值守时可启用 .github/workflows/clean-releases.yml：它每周运行一次，默认只演练；在仓库变量里设置 CLEANUP_APPLY=true（或手动运行工作流并勾选 apply）才会按同一计划删除，keep 可在手动运行时指定。Gitee 的读取、删除以及标签的 HTTPS 推送删除都需要 Actions Secret GITEE_TOKEN，GitHub 侧使用工作流自带令牌。
官方资料与反馈
模型一致性、口型和接缝效果以实际预览为准；具体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 标记边界。脚本设计一段以脚本保存为 script.md 为终点：插件监听会话里的写文件调用，落盘即用 source: script_saved 收口并另记 script_saved（路径、新建或改写、字节数、字数、脚本版本），助手不必再补一次 video_stage finish；此后画分镜、看图、提问不再计入脚本设计耗时。审核等待单独统计；标记间墙钟耗时包含调度，不等于模型纯推理时间。中断只有开始无结束时按未完成处理；热重载丢失的标记返回unavailable，不伪造耗时。日志不可写不影响生成，不重提任务。
续拍估价统一口径：首段无视频输入，参考图/首尾帧也不改变此档位；后续续拍有视频输入，用上一段完整视频时长加本段输出时长计token，采用含视频输入单价。脚本末尾逐段展示档位、输入/输出时长、单价及金额；恢复制作确认读取上一段时长，外部输入视频时长未核实时不猜价。
脚本审核会核对本轮分镜图登记与正文内嵌：present成功不等于已展示，卡片在轮次结束后出现；须先发图片正文，再单独打开审核问题，缺失时拦截并提示补展示。检查基于当前插件加载后观察到的会话事件，不追溯旧窗口。
续拍持续使用最初角色参考图
每段续拍同时提交上一段视频和最初角色参考图。可用characterReferenceImages指定已审核图片；未指定时沿用首段参考图或首帧，续拍中统一作为reference_image。图片顺序及归一化结果保存到断点，暂停恢复继续沿用；真人转换经同意、结果审核并成功重试后，后续使用转换图，不重复出图。没有初始图片时不自动生成角色图，仍按纯视频续拍；已提交任务使用原请求查询，不为加图重新提交。固定参考有助于稳定形象，不能保证完全消除漂移。
纯文生视频可先生成角色图
未提供参考图且需要固定角色外形时，助手先询问是否生成角色参考图，说明图片单独计费。拒绝则保留纯文生方案；同意并确认非真人风格后，使用Seedream按文字生成角色图，展示、审核后才用于首段及后续续拍。图片审核不替代脚本审核与视频制作确认；已完成角色图按taskId查询，不自动重画。该图片调用支持服务端及MetaOntic AI接入，火山直连可使用用户已准备的图片。
安装与运行依赖
插件宿主入口已打包所需Schema库及运行依赖，成品包无需额外安装运行时npm依赖。曾配置本地开发HMR时，须将加载目标恢复到当前已安装插件目录；安装新包不会自动删除用户自行配置的本地加载覆盖。第三方许可见THIRD_PARTY_NOTICES.md。
角色图选择由提交前代码执行：新建无图视频必须取得明确选择；选择直接文生后继续原视频费用审批，选择先出角色图则暂停该次视频提交，先完成出图与审核。跳过、取消、交互失败或记录失败不默认同意。相同会话和脚本规格保留明确选择；已有参考图或断点恢复不重新询问，不重提已有任务。
角色参考图风格建议依次为真人写实、二维动画、卡通、插画；文生角色图可显式设置characterType=realistic生成真人写实。默认沿用非真人类型，真人限制转换仍只用非真人风格；所有出图均需费用同意及结果审核，上游拒绝不自动重画。
开发与发布需遵守Windows/macOS兼容规范。上传正式版前必须通过双平台成品安装检查；自动检查不替代桌面GUI实机验证。
更新前会核对实际安装来源。本地目录链接安装会停止直接在线替换；来源未知或元信息异常也停止，不清目录或配置。tgz成品与仓库安装继续支持在线更新。旧目录已空需先恢复完整内容，不能靠重复点击更新修复；此前已失效或被错误迁移的加载路径仍需单独核对。
一键发布脚本（Windows / Mac）
首次在开发环境安装 Node.js、Git、GitHub CLI、Python 3，并执行 gh auth login；两个仓库的推送权限及 GitHub Actions 的 GITEE_TOKEN 需先配置好。它们仅用于开发发布，插件用户不需要安装。
发布前把 说明模板 复制为根目录 release-plan.json，填写本次全部尚未发布的更新条目及具体指南核对结果，删除占位文字。同步使用说明书、配图和 PDF。此本地计划文件不会提交到仓库。
只检查计划、不修改文件或发布：
npm run release -- 3.13.3 --dry-run
也可双击根目录 release.cmd（Windows），或双击 release.command（Mac；也可运行 bash release.command），按提示输入版本号。它们会执行正式发布，不是预览；需要先准备好 release-plan.json。
一键正式发布（示例版本号需改为实际目标）：
npm run release -- 3.13.3
脚本显示待发布范围与说明，更新版本、锁文件和发布元数据，构建、测试、打包、创建提交及附注标签，先推送 Gitee 再推送 GitHub，等待双平台安装/升级检查及正式附件上传，最后输出发布页、.tgz 安装地址和 Windows ZIP 下载地址。使用说明书不写入版本记录。失败立即停止，不强推或覆盖旧标签。
发布文件已提交但上传中断时，保留同一版本续跑：
npm run release -- 3.13.3 --resume
也可指定 --notes /你的实际路径/说明.json、--branch master、--github https://github.com/wxsimon2022/metaontic-video.git、--gitee https://gitee.com/hackloop/metaontic-video.git。默认使用当前双仓 SSH 443 地址；Gitee 目标与当前 CI 镜像配置绑定，修改项目归属前需同步 CI，不会静默发布到其他仓库。
脚本依赖事先写好的完整说明，不能自动判断业务变化或代替指南审核。GitHub 已上传但 Gitee 超时时，会明确报告未全部完成，使用 --resume 重试，不要重新递增版本。
测试包（发给他人试用，不进发布页）
要验证还没发布的改动时，用测试版版本号打一个包，脚本会自动构建、跑测试、打出 .tgz、上传到线上目录，再核对线上包与本地一致：
npm run pack:test -- 3.13.9-test.1
版本号必须是 X.Y.Z-后缀 形式，核心版本号压在当前正式版之下；只改包内版本号，不提交、不打标签、不建 Release，因此不影响其他人的正式版，测试者之后仍会收到下一次正式版的更新提示。脚本结束后会把 package.json、锁文件和构建产物还原成正式版本。
上传完成后直接给出安装地址，形如 https://video.mybfs.cn/test/metaontic-video-3.13.9-test.1.tgz，发给测试者粘进「插件 → 添加插件」即可；目录页 https://video.mybfs.cn/test/ 可看到历史测试包。加 --no-upload 只出本地包，用 --out <目录> 换输出目录；上传目标可用 PACK_TEST_SERVER、PACK_TEST_DIR、PACK_TEST_URL 覆盖。该目录由 moyubang 仓库的 deploy/nginx/video.mybfs.cn.conf 提供，刻意放在代码部署目录之外，deploy.sh 的 rsync --delete 不会清掉已上传的测试包。测试者用正式版 .tgz 地址重装即可回到正式版。
