# agent **Repository Path**: MrShanDev/agent ## Basic Information - **Project Name**: agent - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-23 - **Last Updated**: 2026-10-30 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 角色工坊 · 全火山视频人物替换工作台 可本地运行的中文网页软件，采用 FastAPI、SQLite 持久化编排、火山方舟 / MediaKit、TOS 和 FFmpeg。前端无需 Node 构建，不加载外部 CDN，不使用本地 AI 模型或第三方推理服务。 **当前默认入口为单页自动生成前流程**：上传原视频与新人有声视频，确认授权并点击开始后自动处理；仅人物不确定时弹窗选择。已用真实素材完成云端分析、音频分离、ASR、真实参考整理和配音对齐的实测。`VIDEO_GENERATION_ENABLED=false` 保持关闭，尚未提交本轮视频生成或验收最终换人画质。原有精确 Mask 与正式渲染工具保留在高级区。 ## 单页自动流程（2026-10-24） - `/#workflow` 上传两段视频，任意顺序均可；按时间命名，刷新保留素材和已确认的本次授权。未开始处理时，两栏均支持移除和重新上传；移除只清空当前选择，保留另一栏及历史素材。视频按实际画面比例完整预览，PC／平板／窄屏自动重排，成片预览跟随原片。 - 顶部提供新建项目、开始／继续、暂停、历史项目。上传后点击开始才启动云端分析。暂停在当前步骤结束并保存结果后生效，已提交的云任务继续完成；继续时跳过已完成步骤。 - 历史项目并排保留原视频、新人物视频、成品视频三种预览，点击可独立播放，横竖比例跟随视频实际尺寸。成片可下载；未完成生成时显示“暂无成片”。封面只从相应视频用本地 FFmpeg 提取，不使用原片冒充成片。人物参考可展开查看，支持载入项目。二次创作建立独立待开始项目，只复用两段视频和相应授权；不复制人物选择、分析、配音、Mask、验收或生成任务，不改变原项目。点击开始后重新分析，可重新选择替换人物。 - 创建接口支持 `replacement_id`、`auto_process=true`、`authorization_confirmed=true` 和 `client_request_id`。同一创建键返回已有项目，避免网络重试重复创建付费处理流程。 - 服务端 `run_automatic` 识别人物并按需等待选择；`select_person` 确认后由服务端接续检查新人、准备参考与声音。离开或刷新页面不停止后台任务。仅明确的单一主画面人物且没有不确定项时自动选择。 - 自动准备使用真实参考，至少一张通过检查即可；不自动补图、不凑四视图、不调用可选 Mask。六项生成前步骤完成后停在生成前，不创建渲染任务，不自动勾选人工试听或图片验收。 - 服务中断保留步骤与云任务关联；用户继续时复用已完成步骤和已知任务，不自动重投结果未知的提交。普通界面显示实际步骤与告警，原始报告、单步排查和精确 Mask 工具收在高级区。 - 当前仍未开放一键正式视频渲染。原有高级渲染入口保留音轨、参考及 Mask 条件检查；本轮不改动其授权门槛，也不解除 2.5 提交锁。 本轮验证见 [单页流程实测报告](docs/testing/单页自动流程实测-2026-10-24.md)。自动化测试：`.venv/bin/python -m pytest -q`；前端草稿与比例回归：`node --test tests/test_ui_helpers.cjs`。 ## 当前整个人物替换规则与生成控制 2026-10-24 用户确定整个人物外观统一采用新人：面部、发型、衣物、耳环、戒指、手表、手套、项链、眼镜及可见鞋袜；动作、原片时序、场景、光照、其他人物和遮挡关系保留。原片与新人各自逐项记录 present／absent／unknown 和真实帧证据；未知不当作没有，不能凭职业或常识补齐。 选定目标头像增加单人头部定位与裁剪复核。五轮独立流程再以干净头像、完整原片和双头像比较对应目标，防止理发师与顾客同处一个头像时错选。全片描述词与来源表带哈希，创建生成批次时固化快照，所有分段使用相同文本和真实参考。 单页已接入分段全选／部分选择、480p／720p／1080p、实际云任务状态和逐段可放大视频预览。生成后增加逐项外观抽帧检查，不一致或未知结果保留预览并停止合格成片拼接，不自动重新计费生成。这些生成分支只做隔离假云响应与真实 FFmpeg 集成测试，**2.5 真实生成仍为零，不能宣称换人画质或配饰保持已验收**。 语速校正使用已保存全篇 TTS，分级保音高变速、近零尾静音测量、实际样本数和句尾保护检查；保留非目标时段原声，包括音乐人声，不把背景音乐描述当成台词。通过这些检查不等于听感或口型合格。所有编排由独立 Python 服务执行。 当前实测报告见 [整个人物外观、生成控制与五轮复测](docs/testing/整个人物外观与五轮复测-2026-10-24.md)。下方高级 Mask 流程与早期测试说明为历史能力记录；默认单页流程不要求 Mask 或四视图，且不自动补图。 ## 启动 ### 独立后台运行（macOS / Linux） 运行时仅需要项目 Python 环境、FFmpeg、火山云服务凭证与网络，不依赖 Codex、ChatGPT、MCP 或浏览器自动化工具。macOS 可双击项目根目录的 `启动角色工坊.command`：它启动独立后台服务，再用默认浏览器打开工作台。启动终端退出、关闭操作页面或开发工具，不会停止已启动的后台服务。 ```sh .venv/bin/python scripts/studio_service.py start .venv/bin/python scripts/studio_service.py status .venv/bin/python scripts/studio_service.py stop ``` 启动器使用独立进程会话，重复启动复用同一实例；运行记录与日志存放在 `data/runtime/`，不含密钥副本。进程只监听本机。此模式没有设置开机自启；重启电脑后重新启动，或使用下方容器部署方式。 素材检查、人物判断、声音复核、云任务查询及步骤推进由服务端执行。页面只提交素材、显示结果和必要的选人操作。无法确定的说话人物、重叠人声、权限或提交结果未知等情况会在软件里阻止继续，不要求聊天软件接管，也不会伪造通过结果。退出后台服务、关机或网络故障仍会影响处理；恢复时保留进度并按软件提示继续，已知云任务不会自动重复提交。 独立运行与关闭操作页实测见 [独立运行核查报告](docs/testing/独立运行核查-2026-10-24.md)。Seedance 2.5 保持禁用，独立运行不会解除生成锁。 ### 前台运行 / 首次安装 推荐 Python 3.11 / 3.12；FFmpeg 和 FFprobe 须在 PATH 中。macOS 自带 Python 3.9 的 LibreSSL 可能不满足新版 TOS SDK 的 TLS 依赖，建议使用较新 Python。 ```sh python3 -m venv .venv .venv/bin/pip install -r requirements.txt cp .env.example .env chmod +x start.sh ./start.sh ``` 打开 [本地工作台](http://127.0.0.1:8787)。未配置密钥也可上传素材、建立草稿及分片规划；启动付费任务前会检查配置。 容器方案：填写 `.env` 后运行 `docker compose up --build -d`。容器必须设置 `APP_TOKEN`，因为宿主机访问可能不表现为容器内的回环地址。当前环境尚未验证 Docker 构建。 ## 已实现 - 素材库、四角度人物参考、逐帧 Mask、独立音轨上传及真实媒体校验。 - 20 秒 / 8 秒分片，0.5 秒上下文重叠，最终沿用原片宽高并统一为 24 fps；按用户确认的切点分镜，避免短尾片和重复时长。 - TOS 私有对象与 24 小时签名 HTTPS URL，不向不支持的接口发送 `tos://`。 - 视觉模型提取一次全局外观描述，所有分片及重试共享相同提示词。 - Seedance 2.5 官方异步编辑契约、云任务 ID 持久化、低频后台查询及可选回调触发查询。 - RGB Mask 限域合成及边缘羽化。黑色保护区取自原片，编码仍会带来像素差异。 - 三个时间点的视觉辅助质检、最多两次自动渲染重试、人工审核、人工追加重试上限。 - 含同源配音的分片预览和全片审核预览，人工通过后正式合成并保存 TOS。 - 丢弃所有模型音轨；最终仅混入全局新人配音、纯背景音和可选保留人声。 - MediaKit 人声 / 背景分离及结果导入。全部人声单独标记，禁止误选为保留人声。 - 项目详情、事件日志、审核记录、暂停 / 继续、未知提交人工核对、成片与 JSON 报告下载。 ## 尚待接入 | 能力 | 首版处理方式 | 原因 | | --- | --- | --- | | 自动跟踪与逐帧分割 | 上传已有 Mask | 原方案的 track-segment 契约未得到官方文档确认 | | 说话人识别及目标音源分离 | 上传独立保留人声 | 说话人标签不能拆分重叠音源 | | 音色训练与全局 TTS | 导入一次生成并对齐的完整配音 | 需确认账号的复刻产品、授权与接口 | | 全帧身份及唇形检测 | 抽帧辅助检查与人工播放复核 | 视觉置信评分不是人脸嵌入相似度或唇形检测 | | 自动首尾姿态对齐 | 重叠上下文、原时间轴裁切及人工复核 | 尚未接入经验证的姿态对齐能力 | 不会使用模拟结果冒充成功。官方来源和方案差异见 [接口核验记录](docs/api-verification.md)。 ## 使用步骤 1. 将 ARK Key、TOS 配置、实际开通的 Vision 模型 / 端点 ID 填入服务端 `.env` 并重启。辅助分离功能另外需要 MediaKit Key。 2. 上传原片、同宽高同时间轴的黑白 Mask，以及正面 / 左侧 / 右侧 / 低头四张不同参考图。 3. 上传与原片同长的全局新人配音、纯背景音和可选的其他人物保留人声。音轨从原片时间零开始，保留静音间隔，时长误差不能超过 0.12 秒。背景音不得包含原人物人声；保留人声不得包含待替换人物。 4. 创建项目并描述目标人物，填写镜头切点与约束。不足 4 秒的独立镜头需预处理，不会跨镜头补帧。 5. 点击“启动云端任务（付费）”。配置存在不代表已开通权限或有配额，实际以火山响应为准。 6. 检查质检、日志与分片预览；自动重试耗尽后人工处理。追加重试仍会计费，每分片最多六次提交。 7. 播放全片审核预览，检查身份、服饰、遮挡、接缝和口型，填写复核记录后导出。 全局音频同源只保证音频来源一致，**不保证模型口型必然精确同步**。TTS 说话时长若不同，需先对齐全局时间轴再导入。对重叠说话，用 ASR 时间戳裁掉 B 的声音会误伤 A，不能作为正确分离方案。 ## 数据、部署与恢复 完整选项见 `.env.example`。密钥只在服务端，不发给页面。`data/` 存放 SQLite、上传工作副本和中间缓存。处理时素材及最终成片上传 TOS，**当前不是无本地落盘的直传架构**。备份需同时包含数据库和文件目录；`.env`、`data/` 均不入 Git。 默认仅监听本机。远程部署须设置强随机 `APP_TOKEN`，配置 HTTPS 和访问限制。当前为单空间、单令牌，无多租户认证隔离，不应作为开放公网多用户 SaaS。 必须只运行一个 Uvicorn worker、一个实例。当前支持单实例重启恢复，尚无分布式任务租约；不能直接通过增加 workers 扩容。 暂停只暂停本地调度，已经提交的云任务仍会执行并可能计费。视频提交超时或中断时不会自动重投；请核对官方控制台，绑定已创建的任务 ID；确认未创建时填写核对记录，再恢复提交。 可选设置 `PUBLIC_BASE_URL` 和高熵 `CALLBACK_SECRET` 启用回调。回调只触发服务端查询，不信任回传产物 URL。启动脚本关闭访问日志，避免记录回调密钥。未配置回调时后台定期查询，浏览器关闭不会停止执行。 ## 验证 ```sh .venv/bin/pip install -r requirements-dev.txt .venv/bin/python -m pytest -q node --check app/static/app.js ``` 测试覆盖时间轴与镜头边界、配置与授权校验、接口访问保护、防止未知状态重投、Seedance 正式请求格式、重试上限，以及真实 FFmpeg 编码集成。集成测试在临时目录使用合成色块、Mask、多频音轨，仅在测试中替换云响应，验证保护区不混入生成画面、正式导出须经过审核、模型音频不会混入最终音轨。 这些测试不代表云端权限、真人身份保持或口型效果已验收。真实火山账号与授权短视频仍是云端联调的必要条件。 详细接口和状态机见 [开发说明](docs/development.md)。 ## 生成前准备工作台 新增左侧“生成前准备”入口，可直接对原视频与新人参考视频执行前处理和云端检查，不要求先提供 Mask、独立音轨来创建完整生成任务。报告区分“已通过的基础检查”和“正式生成尚缺的条件”，可查看源片段及关键帧，下载结构化报告。 桌面“视频重构”目录的“素材01.MP4 → 发型师01.mp4”已登记为实际准备案例。使用真实 TOS 上传、签名回读和可用视觉模型完成前处理；没有提交 Seedance 生成。完整效果和缺失条件以工作台报告为准，之前未联调的说明不再适用于这些已经单独实测的前处理环节；视频生成本身仍未实测。 ## 连续人物替换流程 “新建项目”进入原片 → 人物候选选择 → 新人有声视频初检 → 真实参考提取 / 用户确认 → 统一分析 → Seedance 2.5 生成条件检查。当前参考策略为 `real_only`，已取消 AI 自动补图：只使用新人视频真实帧和用户上传的参考，至少一张通过检查即可分析，其他角度可选补充。 `SEEDREAM_MODEL` 保留用于其他图像功能，人物参考流程不再调用补图。历史合成参考停用时保留档案，并使依赖旧参考的全局分析失效；不会重做已经完成的声音处理。历史补图实测仅作为开发记录，不代表当前采用的素材。 2026-10-24 已接入真实 MediaKit 与豆包语音凭证。原片与新人参考视频均可提交人声/背景音分离，完成后识别带说话人标签的台词。任务 ID、提交意图和产物保存到工作流，提交超时不会自动重投。ASR 返回的时长差异及末句越界会保留为告警，不直接作为对齐配音验收通过。已用新人分离干声完成一次复刻 2.0 训练和五次全篇 TTS 实测；音频仍需试听、人物对应确认及全局时间对齐，指定人物的逐帧实例 Mask 仍缺正式接口。Seedance 生成保持锁定。 ## 生成前五轮实测模式 默认 `VIDEO_GENERATION_ENABLED=false`。工作流生成入口、任务启动、渲染调度、Cloud 提交及底层视频 POST 均有拦截；保持此值即可在实测存储、视觉和 FFmpeg 时禁止提交 Seedance。只有明确进入正式视频生成阶段后才配置为 true 并重启，网页不能切换这个开关。 人物替换页增加“素材分析与声音体检”，不要求先确认四视图。它读取真实采样帧，提取原始混合音轨，测量响度、近满幅样本、静音比例与时长，并提供试听。它不将这些轨道注册为独立人声、背景音或新人配音。播放期间自动刷新不会重建播放器。 五轮真实前处理审计（会上传 TOS 和调用付费视觉接口，`--test-views` 还会请求 Seedream；始终禁止视频生成）： ```sh .venv/bin/python -m app.audit --source /absolute/source.mp4 --replacement /absolute/replacement.mp4 --test-views ``` 结果保存在 `data/audits/preflight-*/report.json`，每轮保留独立流程、真实 HTTP 状态、耗时、人物候选、声音指标和时间轴验证。所有 21 个原片分片的验证使用 540×960 预览尺寸，不能代表正式分辨率与替换效果验收；音频逐样本比对全局原始混合轨的对应区间，补足段必须静音。音轨分离、ASR、克隆、全局配音及目标实例 Mask 尚不可用时会单独记录阻塞。五轮成功仅说明该样本本轮可运行环节通过，不构成所有输入和云服务永不失败的保证。 ## MediaKit 新增步骤实测 人物替换页新增云端音频处理区，可试听原片和新人样片分离后的全部人声与背景音，并查看说话人标签、台词和时间轴告警。全部人声不自动登记为保留人声，未试听的背景音不自动成为最终混音输入。更换新人视频前必须核对尚未结束或状态未知的云任务。 `.venv/bin/python -m app.audio_audit --workflow <已完成首轮音频处理的流程ID>` 会沿用首轮真实任务，并额外提交四轮独立分离/ASR任务，补齐五轮实测；这是付费云端测试，不会训练音色或提交视频生成。报告保存在 `data/audits/mediakit-*/` 并附到原流程。 ## 声音复刻与补图实测 `VOICE_API_KEY` 使用豆包语音自己的密钥，`VOICE_SPEAKER_ID` 使用已购买的复刻 2.0 槽位。`app.voice_control` 只开放官方只读查询，不能购买、续费或激活资源。`app.voice` 通过官方 V3 注册音色及一次提交全篇文本的 HTTP 流式合成，将顺序 PCM 数据合为一条 WAV；必须收到终止成功码，才发布完整候选文件。没有自动重试付费提交。 `.venv/bin/python -m app.voice_audit --workflow <流程ID>` 仅用于已准备 `voice_training_candidate` 的工作流：先经官方查询验证从未训练的预付费 2.0 空槽位，训练一次，再独立提交五次全篇候选。已有审计记录时拒绝重跑，不能覆盖已有音色。当前实测以 ASR 标签 1 的台词作为待核对草稿，不据此确认人物关系；五次合成分别为 101.238、98.225、96.690、96.233、91.423 秒，且字级时间戳为空，均不能直接作为原片 78.134 秒的已对齐配音。报告和试听文件附在工作台，不自动登记为最终配音。 `.venv/bin/python -m app.view_audit --workflow <流程ID> --rounds 5` 为独立 Seedream 补图实测。三个缺失角度分别生成单图并辅助筛查，首个通过候选附到工作流，始终保留合成来源和未人工确认状态。`SEEDREAM_TIMEOUT_SECONDS=240` 只延长图片请求等待时间；超时结果保持未知并停止后续提交，不自动重投。历史审计保留，不以追加测试覆盖失败。 语音时间戳接入修正：官方复刻 2.0 单向流使用 `audio_params.enable_subtitle=true`，旧 `enable_timestamp` 仅适用于 1.0。`app.voice_recheck` 可在此前五轮请求均有确定结果后复用已有训练音色进行一次新的五轮验证，保留原审计，不重新训练。实际修正后五轮均返回 387 个字级时间戳，文本与提交草稿完全一致；各轮 42 段完成候选映射，其中 6–10 段变速比例需复核，仍未完成原片配音对齐或人物/声音确认。五轮补图中，三个角度均通过的完整轮次为 3/5，两轮低头候选未通过；另有一次历史超时结果未知，未自动重投。上述记录不等于正式生成验收。 ## 系统自动准备工作流 页面自动准备在新人初检与使用授权确认后，由应用后台依次完成声音体检、素材分析、MediaKit分离/ASR、真实参考整理、统一视觉分析、原片音画联合台词复核、声音复刻、全篇TTS与逐句对齐混音候选。缺失侧脸或低头角度不再触发图片生成。不依赖审计脚本向项目写入结果。独立步骤失败会保存原因，其余可用步骤继续；不确定的人物声音对应、重叠说话、未知付费提交不会被自动放行。 MediaKit 会按已保存的任务ID自动查询并进入ASR阶段。服务重启后只恢复已知状态的音频链路，未知提交不重投。新人干声以规范PCM指纹关联 `voice_profiles`，只使用官方查询确认未训练的已购买复刻2.0槽位；同一干声不重复训练，不自动购买资源。TTS整篇只提交一次，流式PCM合并后校验字级字幕，按原片逐句起止位置生成一份全局新人配音，并保留其他人物原声与背景，输出全长混音试听。过大变速、混合人声等仍会阻止处理或标注待试听。 “系统人物台词复核”同时提供逐句试听、说话人物/台词/时间编辑；原始ASR告警和系统音画复核分开记录。系统准备可在人工视图确认前完成分析，人工验收标记不会由模型代填。正式音轨须试听确认后才登记到素材库并自动选择，四视图、音轨及精确人物Mask验收仍保护正式生成。生成锁不会随自动准备解除。系统完成自动准备后生成 `system-preparation-report.json`，包含工作流步骤、实际模型结果及未满足条件。 上传表单使用按项目隔离的草稿保留名称、选择及复核输入；自动刷新不再清空上传后的素材选择。测试中使用临时素材验证完整声音工作流、音色复用、未知提交保护、其他人物人声保护及精确音频长度。 ## 指定人物 Mask 与系统五轮入口（2026-10-24） 新增 `LAS_API_KEY` 和 LAS 官方 `las_spatial_perception@v1` 接口。页面可启动所选人物可见头部的实例分割，保护原片服饰、手、工具和其他人物；使用原片分辨率、24fps输出时间轴，按切点拆分且单段不超过288帧，满足官方高帧率每请求最多360帧的限制。不将人物框当Mask，不使用低帧率插值填补。逐帧检查源帧序号、时间戳、COCO RLE、分辨率、面积、实例数量和轨迹，再用实际Mask叠加图做辅助筛查。全部分段通过后生成完整黑白Mask与预览，仍须用户播放确认才登记生成素材。RLE解码与FFmpeg是确定性媒体处理，没有引入本地AI模型。 提交意图、已知任务ID、拒绝记录和原始manifest均持久化。未知提交不自动重投；明确HTTP拒绝且没有任务ID的请求有独立重试入口。中间编码使用临时文件，完成后原子替换。系统保存 `person-mask-report.json`，实际覆盖、错误和人工验收状态不会用模拟成功代替。 **当前实际账号阻塞**：LAS密钥有效；真实分割提交返回 HTTP400、`Operator.InvalidId`，错误为“该算子已受限，您的账号不在白名单中”。尚无本案例真实Mask产物，不能宣称精确Mask已验收。须先申请北京区空间感知调用白名单，再通过页面继续验证。 真实Mask联调完成后，可在页面启动“五轮系统独立实测”。应用后台每轮新建独立工作流，重新检测并匹配用户已选人物，初检新人，执行声音体检、素材分析、MediaKit、四视图、统一分析、声音复刻/音色复用及全篇配音对齐、逐帧Mask。每轮保留独立结果和失败记录，汇总为 `five-round-preflight-report.json`；失败轮不会自动替换为成功轮。当前因Mask权限阻塞，这五轮尚未启动。代码测试的替代云响应不计作真实云端五轮。 五轮入口要求 `VIDEO_GENERATION_ENABLED=false`，且首轮真实Mask候选已生成。系统不代填视图、音频或Mask人工验收，不提交Seedance 2.5。 官方契约：[空间感知](https://docs.volcengine.com/docs/LakeAIService/spatial-perception?lang=zh)、[LAS API Key](https://docs.volcengine.com/docs/LakeAIService/APIKeyManagement?lang=zh)。 ### 视频生成通道（2026-10-24更新） 可用`VIDEO_PROVIDER=kk0606`选择用户指定的Top1ai按秒接口；设置`KK0606_BASE_URL=https://api.lk888.ai/api/v3/anmiao`和独立的`KK0606_API_KEY`。分析、语音及TOS仍用原火山配置。保持`VIDEO_GENERATION_ENABLED=false`，只开启`MANUAL_VIDEO_GENERATION_ENABLED=true`时，软件停在请求摘要，必须由用户确认本次付费后才能提交。新通道按整数秒准备媒体，历史任务固定原平台，不自动转投。[接入说明](docs/testing/Top1ai按秒视频通道接入-2026-10-24.md)。 ### 画面与后端声音分开处理 新项目默认 `VIDEO_AUDIO_MODE=backend_dub`：Seedance 仅接收无声原片、真实新人参考图和画面提示词，不传参考音频。火山复刻/TTS逐句生成新人声音，按原时间轴对齐后与其他人物原声和背景混合；模型返回声音全部剥离，再接入后端固化混音。原片分离目前为人声/背景两轨，重叠说话必须先解决独立分离，不能保证凭时间裁剪保留顾客原声。音色与口型仍须试听验收。 现有项目可在“声音方式”切换，需重新完成声音与请求准备；不会改写历史批次。生成后的播放器提供当前预览版本的声音/口型验收，全部分段通过后本地拼接完整视频。详见 [开发与验证记录](docs/testing/画面与后端配音解耦-2026-10-25.md)。 ### 自动口型与 1080p 成片 在项目的“自动口型与1080p成片”区域点击“自动识别并生成全部镜头”。确认一次视觉分析和口型生成费用后，应用后台会自动分析所有已生成镜头，保存可处理范围，调用火山 MediaKit 生成口型，保护手/工具经过嘴前的画面，并下载保存结果、合并 1080p 全片。无须逐段填写时间或运行外部脚本。 - 复用当前项目的视觉模型、`MEDIAKIT_API_KEY` 和新人配音；原画面与音轨保留。插图、其他人物、低置信度及过短片段保留原画面，界面展示原因。 - 可选本地手/嘴部几何检查：安装 `requirements-lip-guard.txt`，运行 `.venv/bin/python scripts/install_lip_guard.py` 下载 Google 官方模型。缺少本地模型时使用视觉观察的保守遮挡保护。 - 每次分析及生成均保存请求状态。服务重启会继续已确认的批次，已有云任务仅查询；提交结果未知时暂停，不自动重投。素材、目标人物或配音变化后不能继续旧任务。 - 最终文件保存在该项目本地目录，界面提供预览与下载。1080p 导出采用本地放大、轻度锐化与高质量编码，并不等于原生 1080p 或 AI 超分辨率。 实现入口：`app/lip_auto.py`；应用接口：`POST /api/workflows/{id}/lip-sync/auto`（start/resume）。