产品总览：罗根智能体 9.0 是什么#

罗根智能体是一套「AI 帮你做口播短视频」的工具。客户只要选一个行业 / 选题或贴一条爆款视频链接，系统就能按顺序帮他完成：

1. 文案：找近期爆款选题，仿写或原创一篇口播文案，并做 AI 法务审查（查违禁词）。
2. 配音：用系统音色或客户自己克隆的声音，把文案读出来（TTS，即「文字转语音」）。
3. 数字人：用客户的照片（图片数字人）或视频形象（视频数字人），生成「本人对着镜头说这段配音」的口播视频。
4. 剪辑：9.0 主推「剪辑手法」（按大 V 风格全自动剪辑包装，后台叫 HyperFrames），可加背景音乐、画中画；也可「不剪辑，直接用口播视频」。
5. 标题与封面：AI 写标题和话题标签，生成封面。
6. 发布：一键复制标题话题 + 下载封面和成片，客户自己到抖音等平台发布（软件不会替客户直接发布）。

另外有「一键成片 / 一键产出视频」：文案定好后，选好音色、形象、剪辑手法，系统自动跑完配音 → 数字人 → 剪辑 → 封面，停在发布页等客户确认。

两个客户端

• PC 客户端：Windows（x64）/ macOS（仅 Apple 芯片 arm64）桌面软件，程序名「罗根智能体应用9.0」。
• 微信小程序：「罗根智能体」，功能是 PC 的精简版（见下一节差异表）。

两端账号通用（同一个手机号 / 邮箱），但同一时间只能在一台设备上登录（见「多设备登录」）。

重要背景（客服必读）

• 9.0 的 PC 界面是「在线页面」：安装包启动后加载服务器上的页面，所以大部分功能更新不用重装，只会弹「应用更新」提示让客户刷新。
• 两端都不显示积分余额、没有充值入口。积分查询、调整都在后台做。
• 两端都没有「任务中心 / 作品库」页面，只有当前这一条创作流程（草稿存在本机）。查历史任务要用后台「任务中心」。
• 账号由后台开通：新号码没开通就收不到验证码。

功能地图：PC 端与小程序对照#

PC 端（顶栏 7 个图标导航）

旧的左侧菜单 9.0 已取消，改为顶栏图标。

导航解锁规则：有文案才能进配音；有配音才能进数字人；有数字人视频才能进剪辑和标题封面；有封面才能进发布。

• 悬停提示：未登录「登录后使用{菜单名}」；处理中「{菜单名} · 正在处理，暂时不能切换」；未解锁「{菜单名} · 完成上一步后可用」。

顶栏右侧：

• 账户按钮「账户与设置」：已登录显示账号和「账号已连接」，未登录显示「尚未登录」「登录后同步你的创作资源」；菜单项「登录账号」「设置」「清空正在编辑」「退出登录」。
• 窗口按钮：刷新（5 秒冷却，成功提示「刷新完成」）、最小化、全屏、关闭；F11 全屏，Esc 退出全屏。
• 软件只能开一个，再双击图标只会把已开的窗口调出来。
• 窗口最小宽度 1280。小屏笔记本可能显示不全。

小程序

没有底部导航栏，也没有「我的」页（2026-10-28 删除，`` 提交）。页面只有：

• 首页「罗根智能体」：「你做哪个行业？」，搜索框「搜索行业，或粘贴视频链接」，入口「前往工作台」。
• 关键词搜索（爆款选题）、单视频对标（支持抖音、快手、小红书、视频号链接）。
• 工作台「智能体」：6 步流程 ① 文案 ② 配音 ③ 数字人 ④ 剪辑 ⑤ 标题封面 ⑥ 发布，每步左上角「返回」打开「全部步骤」菜单。
• 编辑成片（改字幕、替换素材）、全屏播放、登录页、协议网页。

两端差异

一条视频的完整流程与后台服务#

流程（PC 按钮原文）

1. 文案：首页输入行业 → 选选题 → 「仿写」或「原创」→ 进入文案预览，可改字、「AI 法务审查」→ 「前往配音」或「一键产出视频」。
2. 配音：选音色 →「开始配音」→「配音成品」可「调整情绪 / 重新配音 / 下载音频」→「前往生成数字人」。
3. 数字人：选「图片数字人 / 视频数字人」→ 选形象 →「生成口播视频」→「前往剪辑」。
4. 剪辑：选剪辑手法 →「开始剪辑」→「成片剪好了，看看效果吧。」。
5. 标题与封面：「生成标题」→ 选封面风格 →「封面已生成」→「前往发布」。
6. 发布：「确认无误，复制信息发布」→ 弹「复制信息去发布」→「现在可以前往对应平台发布。」。

改上游会清空下游：例如换文案会提示「使用新的文案仿写将清除已生成的音频、数字人视频…，是否继续？」；小程序重新配音会提示「重新生成配音将清除已生成的数字人、剪辑…，是否继续？」。

服务清单

所有请求都先经过统一网关，再转给后面的服务。luogen-deploy 仓库目前是空模板，没有服务清单，下表根据网关路由表和各仓库 README 整理。

账号登录#

在哪里

• PC：右上角账户按钮 →「登录账号」，或未登录时点任何顶栏图标。先弹免责函，点「确认」后才出现登录框。
• 小程序：首页点搜索或「前往工作台」时，未登录会先弹「用户告知与免责函」，点「同意，去登录」进入登录页。

登录方式

只有「手机号 + 验证码」和「邮箱 + 验证码」两种。没有密码登录，没有微信一键登录 / 扫码登录。

PC 登录框：

• 标题「欢迎登录」，切换「手机号登录 / 邮箱登录」；按钮「发送验证码」→「请稍后 (60s)」→「再次发送 (Ns)」；勾选「我已阅读并同意《用户协议》和《隐私政策》」；按「登录」后显示「验证中...」。
• 框底固定写着：「注意：首次登录需群内联系客服激活账号；」「否则无法收到验证码！！！」。

小程序登录页：

• 标题「登录以后，开始做你的爆款。」；按钮「获取验证码」→「正在发送…」→「重新发送(59s)」；切换「用邮箱登录 / 用手机号登录」；左上角「先逛逛」（回首页）。
• 提示：「首次登录需要在群里联系客服开通账号，否则收不到验证码。」
• 验证码页「输入 6 位验证码。」，输满 6 位自动登录。

规则

登录有效期

• 服务端登录会话 7 天，从登录时刻算起，到期必须重新登录。
• 客户端本地另有 10 天有效期。实际以服务端 7 天为准。
• 后台续费 / 重置卡密 / 重购激活后，旧登录会失效，客户需重新登录（会话和卡密绑定）。
• PC 登录后每 60 秒查一次账号状态，发现被封 / 过期会弹后端提示然后退出登录。

多设备登录

• 单设备登录：新设备登录成功时，服务端已经把其他所有设备踢下线。PC 和小程序也算两台设备，不能同时登录。
• 被踢的一方下次操作时，PC 弹「登录状态已失效，请重新登录」并自动弹出登录框；小程序提示「登录已过期，请重新登录」并跳登录页。
• PC 登录时如果踢掉了别的设备，会弹「多设备登录提醒」：「检测到您已在其他设备登录，是否要登出其他设备？」，按钮「是 / 否」。
• 选「是」：提示「已成功登出其他设备」。
• 选「否」：提示「您选择了保持其他设备登录，当前登录已取消」。注意：此时其他设备其实已经被服务端踢掉了，选「否」等于两边都没登录，客户需要在想用的设备上重新登录。

封禁、禁用、到期

会导致账号被自动封禁的后台操作：订单标记「已退款」、订单 / 账号「换绑」（原账号被封）、后台手动封禁、风控拉黑。

退出登录

• PC：账户按钮 →「退出登录」→ 确认框「退出登录后将返回登录状态，是否继续？」→「退出登录」。只清本机登录，草稿不清。
• 小程序：10-28 起没有退出登录入口。要换号只能在 PC 或另一台设备登录把它挤下线，或等登录过期；也可以在微信里删除小程序后重进（会清本地登录，属推断）。
• 注销账号：两端都没有，服务端也没有注销接口。客户要求注销需走后台封禁 / 人工处理。

常见问题

• 收不到验证码：① 账号是否已开通（后台查不到这个号就是没开）；② 是否已封禁 / 过期；③ 1 分钟内只能发 1 次；④ 短信被手机拦截；⑤ 邮箱看垃圾箱。
• 验证码对的但登录失败（PC）：检查手机号是不是带了空格 / +86。
• 老是被踢下线：账号在别的设备（含小程序）登录了，单设备限制。
• 续费后被要求重新登录：正常，续费会换新卡密。

免责声明与协议弹窗#

用户告知与免责函

• PC：标题「【罗根智能体】用户告知与免责函」，每次点「登录账号」或未登录点导航都会弹；不能点外部关闭；按钮「取消 / 确认」。因登录失效弹出的登录框不再弹免责函。
• 小程序：标签「使用须知」，标题「用户告知与免责函」，按钮「同意，去登录」。
• 三条正文（两端相同）：
• 01 免责声明：「您在上传、创建数字人及声音时，须确保行为合法并拥有相应权利。您的所有使用行为及后果均由其自身承担，与软件开发者无关。严禁将本软件用于任何违法或侵权用途。」
• 02 版权归属：「通过本软件生成的数据作品，其知识产权归您所有。但您需保证作品的合法性，并独立承担由此产生的一切责任，开发者不承担任何连带责任。」
• 03 服务与退款：「软件账号一经开通，即视为服务启动，将产生相应的算力及服务器成本费用，因此无法提供全额退款。具体费用核算标准，请咨询官方客服。」

用户协议 / 隐私政策

• 登录时必须勾选。PC 不勾选提示「请认真阅读服务条款并同意条款」；小程序提示「请阅读并同意服务条款」。
• 协议网页 11-02 起改指向 luogen 域名（PC 提交），地址已配置。

声纹授权协议（小程序上传音色时）

上传音色必须勾选《声纹授权协议》，弹窗按钮「不同意 / 同意并授权」。详细见配音篇。

小程序更新 / 版本过低

• 「版本更新」：「已为您更新小程序，点击确定重启生效」，按钮「稍后 / 确定」；失败「更新失败，请手动清理缓存重试」。
• 鸿蒙版微信基础库过低：「微信版本过低」。

会员、积分与额度#

两套账户体系

| — | | — | 旧体系（不限量） | 新体系（SVIP 积分） | |---|---|---| | 怎么计费 | 有效期内不限量使用，不扣积分 | 每次用功能扣积分 | | 有效期 | 卡密到期时间控制 | 同样有到期时间 | | 排队优先级 | 按 VIP 等级（VIP4 至尊 > VIP3 高级 > VIP2 标准 > VIP1 基础 > Normal 免费） | 固定 SVIP 通道，最高优先 | | 后台位置 | 用户与体系 → 不限量用户 | 用户与体系 → 新体系用户 |

VIP 等级只影响排队先后，不影响每日次数。代码里没有每日次数限制（「VIP4 每 5 小时 12 个」之类只是规划，未实现，`/docs/2026-10-11-用户任务时段限流与临时降级规划）。

积分在客户端的展示

• 两端都不显示积分余额、流水，也没有充值入口。唯一能看到积分的地方：深度训练 / 定制训练按钮上的消耗数，例如 PC「开始训练（消耗N积分）」。
• 积分不足时客户端没有专门弹窗，直接显示后端的「积分不足」或「可用积分不足」。
• 客户问余额：客服去后台「计费中心 → 用户积分账户」查询告知。

各功能消耗（默认值，以后台「功能积分规则」为准）

扣减与返还规则

1. 提交时先冻结：从「可用积分」挪到「冻结积分」。
2. 成功才真正扣：任务完成 → 冻结的积分转为已消耗。
3. 失败 / 取消 / 超时自动返还：冻结积分退回可用。
4. 文案类（同步接口）在网关做同样的「先冻结、成功扣、失败退」。
5. 提交时被系统拒绝（排队已满等）不冻结（36`）。
6. 冻结超过 24 小时不会自动退，要在后台「异常巡检」人工释放。
7. 积分本身没有过期；会员有效期单独由到期时间控制。

定制数字人额度（训练次数）

• 每个用户有「定制数字人额度」，后台可单独设置，没设置按默认策略，策略都没命中按 0。
• 删除已训练的形象不会返还额度。
• PC 提示：「暂无训练额度」「暂无深度训练额度，请联系管理员」「训练额度已用完，请联系管理员」；取消训练时「取消后这次训练不会继续，已用掉的额度可能不会退回。确定取消吗？」。
• 小程序提示：「额度已用完」「无定制额度，请联系客服」。

并发限制（同时能跑几个任务）

• 同一账号同一类服务同时只能有 1 个任务在处理：已有任务在跑时再提交，提示「您已有任务正在处理中，请等待完成后再提交」；如果旧任务还在排队，会自动取消旧任务、以新提交为准。
• 网关按服务限并发（默认每用户：配音 1、数字人 1、画中画 2、文案 1、字幕 1、视频处理 1），后台可调。
• 同样参数 1 秒内重复提交会被拦：「请求重复，请稍后再试」。

充值、退款

• 没有在线充值 / 支付。开通、续费都是后台操作（订单登记 / 生成卡密）。
• 退款在后台「订单管理 → 一键退款」登记，确认后账号会被自动封禁（见后台管理）。
• 免责函写明「无法提供全额退款」。

PC 客户端设置、更新、日志与安装#

设置

账户按钮 →「设置」。只有一项：「下载目录」（「生成的音频、视频与封面默认保存在这里」），按钮「选择文件夹」「恢复默认」「取消」「保存」。

• 默认是系统「下载」文件夹；设置的文件夹被删了会自动回到默认。
• 设置保存在用户数据目录下。

版本与更新

• 没有安装包自动更新，也没有强制更新（没有 electron-updater）。
• 界面是在线页面，每 5 分钟检查一次，有新版右上角弹「应用更新」「应用已更新至最新版本，请刷新页面后继续使用。」按钮「刷新页面」；同一版本只提醒一次。
• 如果是安装包本身要升级，只能让客户重新下载安装（代码中无提示文案）。
• 查版本号：界面上不显示。macOS 顶部菜单「关于 罗根智能体应用9.0」可看「版本: x.x.x」；Windows 看不到菜单。当前版本号 9.0.0（提交，10-27）。

日志与缓存位置

• 软件不写日志文件（10-27 起控制台也不打印，提交）。客服不要让客户「找日志文件」。
• 能收集的排障信息：报错截图、时间、手机号；剪辑失败时小程序可「导出全文」；后台「统计中心 → 崩溃日志」能看到客户端自动上报的错误。
• Windows 打不开时，技术同事可用 在桌面生成 luogen-launch-diagnostics-<电脑名>-<时间>.txt。
• 用户数据目录（登录信息、草稿、设置、浏览器缓存）：
• Windows：%APPDATA%\luogen-ai
• macOS：~/Library/Application Support/luogen-ai（推断）
• `。以客户电脑实际存在的目录为准。
• 安装目录（Windows）：通常 %LOCALAPPDATA%\Programs\罗根智能体应用9.0，程序「罗根智能体应用9.0.exe」。
• 没有「清理缓存」功能。只能「清空正在编辑」（清草稿）；彻底重置需关闭软件后删除用户数据目录（会丢登录和草稿）。

安装常见问题

任务与队列#

客户在哪里看进度

两端都没有任务列表。生成时全屏进度遮罩显示标题、百分比和阶段文字：

• PC：「正在生成配音」「正在生成数字人视频」「智能剪辑」「正在生成封面」；排队时显示「准备中」（11-02 起排队统一叫「准备中」，提交）。
• 小程序：数字人「排队中 / 正在准备数字人生成资源 / 正在合成形象与配音」；剪辑「排队中，正在等待风格剪辑资源」。
• 图片数字人 PC 进度条是模拟的：前 10 分钟走到 88%，然后停在 88% 等结果，卡在 88% 不代表卡死。

任务状态（后台任务中心看到的）

流转：排队中 → 处理中 → 已完成 / 失败 / 超时；排队中或处理中都可能 → 已取消（docs/2026-10-09-status返回值语义核对:9-49）。

为什么要排队

• 机器（GPU / 出片机）有限，都忙时任务排队。会员等级高的优先拉取，但低等级也不会一直饿着。
• 排队太多会直接拒收：机器全忙且已有约 10 个任务在等，新提交会被拒：「当前服务暂不可安全接单，请稍后重试」。没有能处理该会员等级的机器时也会这样。被拒时不扣积分。
• 剪辑手法出片机只接 SVIP / VIP4–VIP1 任务，不接 Normal（免费）等级（`` 提交，10-21）。

超时

• 处理中超过 15 分钟没有任何进度更新，系统判定卡死并结束。
• PC 数字人最多等 2 小时，之后提示「数字人生成任务等待超时，请稍后在任务中心查看处理结果」——客户端并没有「任务中心」，客服遇到请到后台任务中心按用户查。

失败重试

• 失败不会自动重试。客户重新点「重新生成 / 重新配音 / 换种剪辑手法」即可，积分已自动退回。
• 只有机器掉线时，任务才会被自动重新派给其他机器。
• 后台可对失败 / 超时任务人工「重试」。

取消

• PC 剪辑时遮罩上有「取消任务」；小程序配音可「取消配音」；数字人生成没有取消按钮。
• 排队中取消立即生效；处理中取消要等机器停下来，可能显示「取消请求已提交，请稍后确认最终状态」。
• 取消后积分自动返还。

关掉软件 / 刷新后任务会怎样

• 任务在服务器上继续跑，草稿记住任务号。重新打开会自动接着查进度，遮罩按钮变「取消恢复」。
• 小程序重新进工作台也会自动恢复；任务失效时提示「上次的配音任务已失效，请重新配音」等。
• 小程序重新登录会清空本机草稿；PC 退出登录不清草稿。

常见问题

• 一直「准备中」：高峰期排队，耐心等；超过 30 分钟仍不动，记下手机号、时间、哪一步，转技术查队列。
• 提示「当前服务暂不可安全接单」：排队已满，过几分钟再提交，积分没扣。
• 提示「您已有任务正在处理中」：同类任务一次只能跑一个，等上一个完成。
• 失败后积分少了吗：没有，失败 / 取消 / 超时都自动退。若后台流水显示仍在「冻结中」超过 2 小时，转技术或在后台人工释放。

统一网关的错误与限流#

网关是什么

是所有请求的「总门卫」：先看登录是否有效，再看是否操作太频繁、是否重复提交，然后转给具体服务。所有接口统一返回 {"code": 数字, "msg": "提示", "data": ...}，客户看到的大多是 msg。

错误码含义（code）

限流规则（默认值，后台风控可调）

• 按用户（未登录按 IP）统计：非查询类请求每分钟 3 次，通用兜底每分钟 100 次。超了提示「请求过于频繁，请稍后重试。」
• 5 分钟内触发 3 次限流 → 自动拉黑，同时踢下线；拉黑时长 30 分钟起，每次翻倍，最长 7 天。客户看到「访问受限：请求过于频繁，已被暂时限制。请在{N}秒后重试。」
• 解除：后台「风控中心 → 黑名单管理」移除，或「配置管理 → 手动解除接口锁定」。

出片机网关 对客户的影响#

是什么

9.0 的「剪辑手法」不在云端 GPU 上跑，而是在公司内网的一组 Mac 出片机上跑。 是管这组出片机的「调度员」：每 15 秒检查一次出片机是否健康，把云端队列里的剪辑任务领下来派给最空闲的那台，再把成片回报给云端（15-100`）。

• 编辑成片时会优先回到原来出片的那台，速度更快（10-28，提交）。
• 所有出片机同时最多 3 个在上传成片，其余排队（11-04，:5-16`）。

对客户的影响

• 出片机全部离线 / 公司网络断：新提交的剪辑被拒「当前服务暂不可安全接单，请稍后重试」；已排队的任务等恢复后继续；正在处理的任务可能 15–30 分钟后以超时失败，积分退回（推断，见待技术确认）。
• 打开剪辑手法列表、编辑成片时网关连不上出片机：「HyperFrames 服务暂时不可用，请稍后重试」或「本地 Gateway 不可用；提交状态需按 task_id 查询」。
• 失败不会自动重试，客户需重新剪辑。
• 剪辑失败提示格式可能是「错误码: 原因」，例如「ASR_FAILED: …」（语音识别失败）。

常见问题

• 大面积客户反馈剪辑失败 / 一直准备中：很可能是出片机或公司网络问题，立即转技术，附上反馈的时间段和几个手机号。

后台管理（客服 / 售后常用）#

后台名称「罗根智能体管理后台」，用户名 + 密码登录。页面带当前登录人水印，截图外发前注意。按钮能否点取决于账号权限，没有权限会被跳到「个人中心」。

查用户

用户与体系 → 不限量用户（旧体系）或 新体系用户（积分体系）。搜索框「搜索账号（user_id/手机号/邮箱）」可直接搜手机号。

• 一个页搜不到，去另一个体系页再搜（两个页只显示各自体系的用户）。
• 状态标签：已封禁 / 已禁用 / 到期 / 正常。
• 「查看详情」（眼睛图标）可看：基本信息、到期时间、定制数字人额度、封禁 / 解封原因、操作日志（含每次计费）、登录设备、登录记录、积分面板。
• 「更多 → 导出数据」导出的 CSV 含卡密，属于敏感信息，不要外发。

调整有效期 / VIP

• 延长或缩短到期时间：不限量用户页 → 行「更多操作」→「更新卡密」→「延长天数」填正数延长、负数扣减（「0 仅改 VIP；正数延长；负数扣减。」）。到期前续费从原到期日顺延，已过期从今天算。操作后客户需重新登录。
• 只改 VIP 等级：「设置VIP」（「仅改 VIP，不动有效期。」），可批量。
• 注意：Auth 接口如果带了天数会「从今天重新计算有效期」，不在原日期顺延；后台「设置VIP」不传天数，安全。

调整积分（新体系）

• 用户详情 → 积分面板 →「调整积分」：「积分变更」正数加分、负数扣分（不能为 0，± 以内），备注最多 255 字，按钮「确认调整」。
• 或 计费中心 → 用户积分账户：输入 user_id「查询」→「更多操作 → 调整积分 / 批量调整积分」（批量每次最多 500 人）。
• 旧体系用户不能直接调分，需先「切到新体系」（「不限量用户不支持直接调分，请先切到新体系」）。
• 查扣费明细：积分面板「冻结记录」「积分流水」（变更类型：冻结 / 扣减 / 返还 / 人工调整）。
• 冻结积分没退：计费中心 → 异常巡检 →「人工释放」（「会返还冻结积分，请确认任务已失败或无法回收。」）。
• 修改定制数字人额度：用户详情 →「定制数字人额度」→「修改额度」。

封禁 / 解封 / 下线

• 封禁：行「更多操作 →封禁用户」，「封禁原因」必填（≤500 字），立刻踢下线。
• 解封：「解封用户」，「解封原因」必填。换绑后被封的旧账号不能直接解封。
• 重购激活：针对已封禁 / 禁用账号，按最高可用 VIP 和默认时长（默认 18 个月）重新激活。
• 强制下线某台设备：用户与体系 → 设备管理（有二次确认），或用户详情「登录设备」页签（没有二次确认，点了直接下线）。后台没有「解绑设备 / 重置设备数」功能，也不需要（单设备登录，新设备登录自动踢旧的）。

换绑（客户换手机号）

行「更多操作 → 账号换绑」：「新账号继承 VIP 与有效期，原账号自动封禁。」只有账号正常时才能换绑。订单管理里也有「换绑」。

查任务

工作台 → 任务中心：按「服务」「派发通道」「任务状态」「用户 ID」筛选。

• 服务名对照：TTS语音合成 / TTS服务-v3（配音）、数字人、数字人训练、图片数字人、字幕特效、画中画、视频BGM、视频LUT、最终成片、特效包装-9.0（= 剪辑手法 HyperFrames）、封面图服务等。
• 点「详情」看「失败原因 / 取消原因 / 超时原因」、开始完成时间、重试次数。
• 可「取消」（排队中 / 处理中，不可恢复）、「重试」（失败 / 超时）。
• 没有单独的任务号搜索框，见待技术确认。
• 运行中心 → 死信队列：最终失败的任务，可看错误信息、重试、删除（删除不可恢复）。

退款 / 订单

业务中心 → 订单管理：可按订单号 / 手机号 / 激活账号 / 微信昵称等搜索。

• 「一键退款」：填退款金额（默认 = 实付金额 − 已用计费汇总）、退款原因。警示「确认后将把订单状态改为已退款，并自动封禁该订单当前激活账号。」 后台只登记退款状态并封号，真实退款需另走支付渠道。
• 「一键激活」：为延迟激活的订单开通账号。
• 订单状态：正常 / 售后中 / 已退款。

查日志

• 统计中心 → 审计日志：「登录日志」（按账号查登录成功失败、IP、设备）、「操作日志」（选「用户操作」+ 操作人 ID 可看客户每次用了什么功能）。「全量校准 / 区间校准」按钮客服不要点。
• 统计中心 → 崩溃日志：客户端自动上报的报错，可按提交人 ID 查。

风控解封

客户提示「访问受限…」：风控中心 → 黑名单管理 搜手机号 / 用户 ID / IP →「移除」；或 风控中心 → 配置管理 → 手动操作 →「手动解除接口锁定」。

注意事项

• 退款、换绑都会自动封号（换绑封的是原账号）。
• 续费 / 重置卡密 / 重购激活后客户要重新登录。
• 删除数字人形象不返还定制额度。
• 后台没有声音 / 形象审核功能。
• 「操作日志计费配置」菜单实际打开的是风控配置页。

客户端通用报错的处理思路#

没有日志文件可收集，转技术时一律收集：手机号 / 账号、发生时间（精确到分钟）、哪个端（PC Windows / PC Mac / 小程序）、哪一步、完整报错截图，有的话附后台任务 ID。

近期变更（平台）#

待技术确认（平台）#

1. 登录会话是否就是「登录后固定 7 天必须重登」（代码里到期时间不随使用延长）。
2. 会员到期但登录会话还没过期的客户，网关是否会拦截（统一校验不检查到期）。
3. 积分用户使用剪辑手法（HyperFrames）、图片数字人时怎么计费：这两项不在默认积分规则表里，按代码可能报「当前任务未配置积分规则」。
4. 冻结超过 24 小时的积分是否有自动返还，目前只看到人工释放。
5. 后台任务中心能否按任务 ID / 手机号搜索（只有「用户 ID」和「Worker ID」框）。
6. 出片机全部离线时，客户实际看到的提示和等待时长（本文为代码推断）。
7. 9.0 客户端的一键成片是客户端逐步调用，还是走。
8. 队列拒收（503）的提示原文能否透传到客户端，还是变成「服务器错误，请稍后重试」。
9. 代码中存在一个测试用固定验证码逻辑，需确认生产环境已关闭。
10. 小程序没有退出登录入口，客户想换账号的官方处理方式。
11. macOS 用户数据目录名是否为 luogen-ai。
12. 网关重复提交拦截返回 403 还是 409（代码 403，文档写 409）。

文案功能总览#

9.0 的文案从哪里来

9.0 把文案入口精简成「先搜行业找爆款，再仿写或原创」这一条主线。客户拿到文案的方式只有以下几种：

（PC 来源类型定义：/；小程序：/）

9.0 已经没有的功能（客户问到时如实回答）

• IP 档案、行业档案、档案选题生成、「定制我的行业」：9.0 已下线。PC 端在 10-26 去掉了档案选择步骤和档案选题生成（提交；/ 注释「旧记录里的第 1、2 页（档案选择、生成文案）已经停用」）；小程序在 10-27 删除了「IP 管理」「行业素材」页面（提交）。现在与「IP」最接近的是人设（见「人设（我的口吻）」）。
• 一句话 AI 写文案、润色、扩写、缩写、改风格按钮、热点话题生成：PC 和小程序都找不到这些入口。「换写法」只在原创文案上有（PC「换个写法」）。后端仍保留旧接口（如），但 9.0 客户端不调用。
• 「保存文案」按钮：没有。文案自动保存在本机草稿里，并在开始配音时自动记入「历史文案」（见「历史文案与文案裂变」）。

后台是谁在处理

• 客户端所有文案请求先到 （网关，负责登录校验、扣点、限流后转发），再转到 （文案服务，负责搜索、调用大模型写文案、提取视频文案、法务审查）。
• 大模型：一种能写文字的 AI。文案服务默认用 deepseek-v4.1-flash，失败时依次换豆包 lite、豆包 mini、qwen3.7-flash，每个模型最多等 25 秒，一次请求总共最多 180 秒。四个都失败时提示「文案模型暂时不可用，请稍后重试」。
• ASR（语音识别）：把视频里的说话声转成文字，用于「提取视频文案」和「查看原文案」。用的是阿里百炼 Fun-ASR。

点数与会员（汇总）

只对「积分计费用户」扣点（billing_mode=points 的用户；老的不限量账户不扣）。生成失败、超时会自动退点。

搜索次数配额（重要）：关键词搜索 / 追加选题有按会员等级的次数限制，窗口为滚动 24 小时、只算成功的搜索、命中缓存不算次数。网关风控配置里的默认值是：普通用户（Normal）0 次、VIP 1-2 级 每 24 小时 5 次、VIP 3 级及以上不限。线上实际值以后台「风控配置 → copywriting_tikhub_policy」为准（见待技术确认）。次数用完时提示「今日访问次数已达上限，请稍后再试」。

字数规则（汇总）

• 文案最多 750 字（9.0 新规则，原 1000 字）：PC 编辑框 maxlength 750，AI 生成结果超出时静默截断到 750 字。小程序输入框 maxlength 750，外部带进来的文案超过时提示「文案最多750字」并截断。
• AI 生成的字数一般在 300-520 字左右：爆款仿写通常 300-480 字、最多 520；原创（选写法）要求 330-520 字；裂变 220-830 字；视频对标仿写超过 970 字会被再压缩。
• 视频对标的原文案框最多 3000 字（小程序 /），后台要求对标原文 至少 20 字、最多 12000 字。
• 法务审查最多 10000 字（实际文案只有 750 字，基本碰不到）。
• PC 文案页底部显示「预计口播约 N 秒」，按每秒 4.5 字估算。9.0 去掉了「N 字」显示（PC 提交、小程序提交，11-03）。

行业关键词搜索（找近 30 天爆款选题）#

在哪里

• PC 端：软件打开后的默认首页就是行业搜索页（路由 /ip-management-industry），顶部导航第一个「行业搜索」。页面标题「告诉我你的赛道，」「我帮你做内容。」。
• 小程序：首页「你做哪个行业？」/「我把你行业近期爆款整理出来。」，搜索后进入「关键词搜索」页（标题「近 30 天\n谁在被点赞」）。

怎么操作

1. 在搜索框输入行业或产品关键词（PC 占位「输入行业关键词或热门视频链接，按回车」；小程序占位「搜索行业，或粘贴视频链接」），回车 / 搜索。输入的是视频链接时会自动转到「提取视频文案」流程。
2. 等待结果。PC 进度条依次显示「正在检索「关键词」相关视频」→「按点赞筛选近 30 天爆款」→「整理原文案」（进度是模拟的，最高停在 92%）；小程序显示「正在整理近 30 天被点赞最多的内容…」。
3. 看榜单：按点赞从高到低排。PC 列「排名 / 选题 / 热度 / 点赞」，热度 = 本条点赞 ÷ 本批最高点赞 × 100，一万以上显示成「17.46w」。小程序显示「共 N 条 · 按点赞从高到低」。
4. 点选一条，可「查看原文案」（PC）/「原文案」（小程序），再点「仿写」或「原创」。
5. 不满意可点「再追加一批选题」/「追加选题」（小程序），同一关键词继续往下找；没有新的了显示「已经到底了」。
6. 返回按钮「换个行业」回到搜索首页。

历史搜索

• 点搜索框会展开历史搜索：PC 最多 10 条（标题「历史搜索」），小程序最多 5 条（每条写「最近搜过」）。输入时会按关键词联想（260 毫秒防抖）。
• PC 第一次出结果时自动弹三步新手引导「输入行业，按回车」「点选一条选题」「仿写，或者原创」。

查看原文案

• PC 选中选题时自动预读原文案，弹窗「原文案 ORIGINAL COPY」，可「复制全文」。读不到时显示「这条视频暂时没有可读取的原文案。」。
• 小程序弹层「原文案」，按钮「复制原文」「仿写」「原创」；读不到时显示「原视频已下架，请重新选择」。
• 后台：原文案是把抖音视频下载、转音频、语音识别得到的。搜索返回后后台才开始逐条处理（并发 4），所以刚搜完立刻点开可能还在处理中（状态「素材处理中」「正文转写中」）。

限制与规则

• 数据来源只有抖音：先取「抖音热榜按关键词过滤」，不足 10 条再用抖音搜索补。默认筛选时长 1-5（推测为 1-5 分钟视频）。
• 「近 30 天」是界面文字；客户端没有传时间筛选参数。
• 关键词 1-200 字；关键词不能是 undefined、null 之类的无效词。
• 同一关键词 24 小时内有缓存，命中缓存不消耗搜索次数。
• 追加：每次默认 20 条，去掉已经显示过的；必须先搜索过才能追加。
• 次数配额见「文案功能总览 → 点数与会员」。搜索、追加功能可被后台整体关闭，关闭时提示「当前功能暂未开放」。

后台处理

网关 POST （追加/append、原文/content、历史/history`）→ 文案服务 TikSearch（调用第三方 TikHub 抖音数据接口，超时 60 秒）。PC 单次请求最多等 30 秒。

常见问题

• 「今日访问次数已达上限，请稍后再试」：搜索次数用完。普通用户默认 0 次（等于不能搜），VIP1-2 默认 24 小时 5 次。滚动 24 小时，不是过 0 点就恢复。换已经搜过的关键词（命中缓存）不扣次数。
• 搜不到结果（「没有找到「xxx」的近期爆款」）：让客户换更具体的行业或产品名。
• 原文案读不到 / 显示「原视频已下架」：可能视频确实下架，也可能后台还在转写，稍等再点一次；纯音乐视频没有人声也读不到。
• PC 搜索报「请求超时，请稍后重试」：PC 只等 30 秒，首次搜冷门词可能超过，稍后重搜（第二次多半走缓存）。

人设（我的口吻）#

在哪里

• PC 端：点选题的「原创」→「选个写法」弹窗中的「用谁的口吻」区，按钮「新建人设」。
• 小程序：关键词搜索页上方「我的人设」，按钮「管理/完成」、「添加」。

能做什么

人设是一句「我是谁」的介绍（行业、年限、地点、做什么），原创和仿写时 AI 会按这个口吻写，代替 9.0 之前的 IP 档案。

限制与规则

• 小程序占位示例「例如：10 年服装店老板，在杭州开了 3 家店」，参考「6 年私教，专带产后修复」「宝妈做母婴社群」「县城开了 8 年火锅店」。
• 没有人设时用默认口吻（PC「还没有人设，将用默认口吻；也可以先新建一个。」）。再点一次已选中的人设 = 取消选择。
• 两端共用同一份人设数据（接口），所以 PC 上写的超过 100 字的人设在小程序也能看到。
• 删除人设：PC 确认框「删除后不可恢复，确定删除这个人设吗？」；小程序「确定要删除这条人设吗？」。

仿写爆款文案#

在哪里

• PC：行业搜索榜单右侧详情或原文案弹窗里的「仿写 / 沿用原文结构」。
• 小程序：选中一条后底部「仿写 REWRITE」，或原文案弹层里的「仿写」。

怎么操作

点「仿写」→ 等待生成 → 结果自动进入文案页（PC 进入「文案预览」；小程序先显示结果，可直接改字，点「确认使用」进入工作台）。

限制与规则

• 以这条爆款视频的正文为底稿改写，沿用原文结构；一般 300-480 字，最多 520 字。
• 原文还没转写好时不能仿写（后端返回处理中；小程序会提示「原视频已下架，请重新选择」）。
• 质量检查不通过时不会失败，会返回带提醒的草稿让客户自己改。
• 网关不扣点；有每用户并发限制（同一用户同时只能跑 1 个生成，若后台启用了并发配置）。

耗时与等待界面

• 后台一次请求最多 180 秒（多数十几秒到几十秒，无实测数据）。
• PC：遮罩标题「正在仿写」，阶段文字「拆解原文结构 → 提炼爆点节奏 → 逐段仿写 → 润色成稿」，进度是模拟的，最高 95%；没有取消按钮。PC 单次请求只等 30 秒（/ 使用默认 30 秒客户端），若后端返回「处理中」再每 3 秒查一次、最多 60 次（约 3 分钟），超时提示「文案生成超时，请稍后重试」。
• 小程序：全屏「正在仿写」，有「取消生成」按钮（只是不再等结果，后台照样在生成）。

结果页（小程序）

结果标签「仿写结果」，底部「共 N 字」「可直接点文字修改」，按钮「关闭，重新选择」「确认使用」。点「确认使用」会清空工作台里原有的配音、数字人等草稿并从文案步骤开始。

PC 覆盖提示

已经做过配音、数字人等后再生成新文案，PC 会弹确认框「使用新的文案仿写将清除已生成的{音频、数字人视频…}，是否继续？」。

原创文案（选写法 + 选口吻）#

在哪里

• PC：选题详情「原创 / 选写法 · 选口吻」→ 弹窗「选个写法 ORIGINAL」「挑一种写法，我按你的人设来写」。文案预览页的「换个写法」也会打开它。
• 小程序：底部「原创 ORIGINAL」→ 弹层「选个写法」「挑一种写法，我按你的人设来写」。

怎么操作

1. 选一种写法（必选）：解题型「先摆问题，再一步步给解法」、推荐型「清单式安利，看完就想囤」、揭秘型「讲内幕、造反差，勾好奇」、案例型「真人真事，加上完整过程」、疑问型「连环设问，逼出共鸣」（写法列表由后台下发，后台可配，读取失败时 PC 用这 5 种兜底）。
2. 在「用谁的口吻」里选一个人设，或不选（默认口吻）。
3. 点「开始生成」。

限制与规则

• 以爆款视频的标题为选题，按选中写法重新写，要求 330-520 字。原文需人工核验时仍可生成，但会带「参考文案存在待核验内容」类提醒。
• 视频没有标题时不能原创（「当前素材缺少可用 title，无法生成风格仿写文案」）。
• 网关不扣点；并发限制同仿写。
• 等待界面：PC「正在原创」，阶段「理解选题结构 → 套用「X」写法 → 代入「X」口吻 → 润色成稿」；小程序「正在原创」「按「人设」的口吻写…」。耗时、超时同「仿写爆款文案」。

提取视频文案 / 单视频对标#

在哪里

• PC：在行业搜索页同一个搜索框里粘贴视频链接后回车。弹窗「视频文案 VIDEO COPY」「按这条视频的文案仿写」。
• 小程序：在首页或关键词搜索页粘贴链接，会自动打开「单视频对标」页并开始提取。页面标题「把这条视频的文案\n拿过来仿写。」，说明「粘贴抖音、快手、小红书、视频号的分享链接，先把原文案提取出来，改一改再仿写成你的。」。

怎么操作

1. 粘贴视频分享链接或分享口令（整段口令也行，系统会自动抽出链接）。小程序有「粘贴」按钮，链接框最多 500 字。
2. 点「提取文案」（小程序）/ 回车（PC）。PC 显示「正在打开视频链接」→「正在提取视频文案」。
3. 提取出的原文案显示在可编辑框里，可以先改。提取失败也可以手动把文案贴进框里继续（PC 占位「没有提取到文案时，也可以把文案粘贴在这里。」）。
4. 点「开始仿写」，生成后进入文案页。这条路径不带人设、不能选写法。

提取记录（小程序独有）

• 单视频对标页下方「提取记录」，只显示最近 10 条，点一条可回填链接和原文，垃圾桶可删除。
• PC 没有提取记录入口。

限制与规则

• 支持哪些平台：代码没有平台白名单，由第三方解析服务（ALAPI）决定；只对抖音短链做了特别兼容。界面写的是抖音、快手、小红书、视频号；图文作品和直播不支持。
• 视频文件不能超过 200MB；没有时长限制。
• 原文案框最多 3000 字；仿写要求原文 20-12000 字；仿写结果超过 970 字会自动压缩，前端最多 750 字。
• 同一个链接提取过会走缓存，第二次很快（「文案提取成功（命中缓存）」）。
• 点数：提取视频文案默认 6 点（积分用户，失败退回）；对标仿写网关不扣点。

后台处理与耗时

• 提取：网关 `POST → 文案服务：解析真实视频地址（30 秒）→ 下载（最多 180 秒）→ 转音频（最多 240 秒）→ 上传 → 语音识别（最多 600 秒）。短视频一般几十秒内，长视频可能几分钟。
• 仿写：`POST，一次请求，后台最多 180 秒。
• 客户端等待上限：PC 提取和仿写都只等 30 秒，超过就提示「请求超时，请稍后重试」；小程序以微信 3 分钟网络超时为准。
• 失败时提示带错误码，如「链接已失效或作品不可见（VC-203）」，含义见报错表。

常见问题

• 提取失败：先看提示后面的 VC 码（详见「报错说明大全」）。最常见：链接复制不全（VC-101/102）、作品已删或私密（VC-203）、图文作品（VC-205）、纯音乐无人声（VC-504）。处理办法：重新复制分享链接，或让客户直接把文案粘贴进框里仿写。
• PC 提取长视频报超时：PC 只等 30 秒，后台其实可能还在跑。稍等一两分钟用同一个链接再提取一次（会命中缓存），或换小程序提取。
• PC 出现英文「Request failed with status code 4xx/5xx」：PC 对 HTTP 错误没有中文翻译，这是提取接口返回了错误码（如 422 作品不可见、503 解析繁忙），按小程序同链接测试或转技术。

文案预览与编辑（文案步骤）#

在哪里

• PC：顶部导航「爆款文案」→「文案预览」页。生成完成会自动跳到这里。
• 小程序：工作台第一步，大标题「先把要说的\n文案定下来。」。

能做什么

• 直接点正文修改（PC 悬停提示「点击修改文案」，小程序「点文字可以直接修改」），最多 750 字。
• PC 右上「历史文案」「复制全文」；小程序「文案记录」「AI 法务审查」。
• PC「生成依据」卡：显示这篇是「原创 · 写法」「仿写」「视频仿写」「历史文案」还是「手动编辑」，并提供「再生成一版」「换个写法」（只有原创/仿写能换写法；手动编辑的不能再生成，copy 来源逻辑 /）。
• 下一步：PC「前往配音」，或「一键产出视频」；小程序「下一步：配音」或「一键成片」。没有文案时不能下一步（PC「先写一篇文案，再来配音」；小程序按钮置灰 / 「请先生成文案」）。
• 页面写有「内容由AI生成，仅供参考」。

注意

• 文案改了以后，已经生成的配音会作废（小程序；PC 用「再生成 / 换写法 / 替换风险词」等方式改文案时会弹「修改文案将清除已生成的…，是否继续？」）。
• 有任务在处理中时不能改：「当前任务正在处理中，请等待完成后再修改工作流内容」。
• 一键成片不会写文案，只用当前文案往下做配音 → 数字人 → 剪辑 → 标题封面 → 停在发布页。

历史文案与文案裂变#

在哪里

• PC：文案预览页右上「历史文案」→ 弹窗「历史文案 HISTORY」。
• 小程序：文案步骤「文案记录」→ 弹层。

怎么操作

• PC：点一行直接换成这篇（「已换成这篇历史文案」）；每行有「裂变」按钮（以这篇为底稿，换个角度再写一篇）；可删除。每行标「原创」或「仿写」，正在用的标「当前」。
• 小程序：只能「选一篇做「文案裂变」，AI 会换个角度再写一篇。」选中后点「文案裂变」；可删除。滑到底自动加载下一页（每页 20 条）。

什么文案会进历史（重要）

• 仿写 / 原创 / 视频仿写 / 裂变生成的文案，在点「生成配音」或一键成片开始配音时才会自动保存进历史（finalize-save 接口，失败不提示）。
• 小程序上 AI 文案手动改过字后再配音，很可能不会进历史（改字会清掉保存凭据）；手动输入的文案也不会进历史。小程序弹层原话也说明「仿写并配过音的文案才会记在这里」。
• 只生成、没去配音的文案不会出现在历史里。

裂变规则

• 裂变方式（换痛点 / 换场景 / 换切入点）由程序随机选，客户不能选。
• 220-830 字；一次请求，后台最多 180 秒；PC 只等 30 秒。网关不扣点。
• 等待文字：PC「正在裂变」（读取历史文案 → 换一个切入角度 → 逐段重写 → 润色成稿）；小程序「正在进行文案裂变...」。

AI 法务审查（违禁词检测）#

在哪里

• PC：文案预览页工具卡「AI 法务审查」「检查违禁词与敏感表述」。
• 小程序：文案步骤「AI 法务审查」按钮。

怎么操作 / 结果

• PC：点击后横幅「AI 法务审查中，正在比对违禁词库…」。
• 有风险：「发现 N 处风险表述，仅供参考，点标记可单独替换」，正文风险词高亮，悬停看原因和建议词，可点单个替换或「全部替换」。
• 无风险：「审查通过，未发现违禁词」。
• 审查只是建议，不改也能前往配音。
• 小程序：等待遮罩「正在做 AI 法务检查」。
• 通过：「文案合规，可以放心用」「没有发现违规用词，可以直接去配音。」
• 有风险：「发现 N 处风险用词」「已经按建议替换好了，可以直接采用审查后的文案。」，列出每个风险词（类型 · 高/中/低风险、原因、「建议改成：…」），按钮「依然用原文」「采用审查后的文案」。选「依然用原文」要二次确认「确定坚持使用原文案吗？违规内容导致的一切后果需要自行承担。」。

后台怎么查

网关 `POST → 文案服务四步：

1. 违禁词库匹配：用后台「违禁词库」里所有启用的词（后台可增删改、启停，字段有类型、等级 high/medium/low、范围 法律/平台/规范、替换词）。
2. AI 语义检查：找出词库里没有的问题表述，如「投资收益夸大承诺」「排名绝对化」「医疗功效夸大」。
3. 合并结果，给出替换词：法律类只用词库配置的替换词（没有就用 ）；其他类优先 AI 建议，其次词库，最后兜底（如「较为优质」「相关表述」）。替换词从候选里随机选一个*。
4. AI 把替换稿润色通顺后再复查一遍。

限制

• 最多 10000 字（实际文案只有 750 字）。
• 点数：默认 4 点 / 次（积分用户）。同一篇已通过且没改过时，PC 再点会提示「已审查过，可直接前往配音」，不会重复审。
• 有每用户并发限制（若后台启用）。

常见问题

• 审查结果每次不一样：AI 语义检查和替换词随机，结果会有差异，属正常。
• 某个词明明合规却被标出 / 违规词没查出：违禁词库由后台维护，收集词和截图转技术（或运营）调整词库。
• 审查结果仅供参考：最终合规责任在客户，客服不要承诺「审查通过就一定不会违规」。

近期变更（文案）#

待技术确认（文案）#

1. 搜索次数配额线上值：网关代码默认普通用户 0 次、VIP1-2 每 24 小时 5 次，文案服务默认关闭配额。线上后台「copywriting_tikhub_policy」实际配置是多少？若普通用户真是 0 次，所有普通用户一搜就报「今日访问次数已达上限」。
2. PC 30 秒超时偏短：PC 的仿写 / 原创 / 视频对标仿写 / 裂变 / 视频提取 / 搜索都用 30 秒客户端超时，而后台生成最多 180 秒、视频提取可达数分钟。生成慢时 PC 会报「请求超时，请稍后重试」，但后台可能已生成（视频提取还可能已扣点）。是否需要调长？
3. PC 对 HTTP 错误无中文翻译：PC 遇到非 2xx（如视频提取 422/503/504、风控 429/403）可能直接显示英文「Request failed with status code xxx」，10-24 加的「视频文案提取失败，请稍后再试」在 10-26 重构时被删（提交）。需确认 PC 实际显示的是后端 msg 还是英文。
4. 积分不足提示：网关返回 HTTP 200 + code 400 + msg「积分不足」。客户端按 code 判断时会显示该 msg，具体界面待真机确认。
5. 小程序实际超时：请求层设 50 分钟，manifest 微信全局 3 分钟，以哪个为准待真机确认。
6. 小程序查看原文案时后台「处理中」：tiksearch/content 在转写中返回 processing，小程序可能直接显示「原视频已下架」，PC 显示「暂时读不到原文案」，是否会误导客户？
7. 小程序法务审查旧字段：工作台在弹窗前读旧字段 reviewed_content 自动替换；若后端仍返回旧格式，点「依然用原文」无法恢复原文。确认线上返回格式。
8. 小程序成功码判断：页面多处用 code === 200 判断成功，若后端返回 0 会误报失败（关键词搜索、法务审查、裂变、写法列表）。
9. 视频对标支持平台：完全依赖第三方 ALAPI，快手、小红书、视频号（尤其是不带链接的视频号口令）能否提取需实测。
10. 对标仿写结果是否进历史：取决于 by-benchmark 接口是否返回 save_payload。
11. 生成耗时：代码只有上限（180 秒），没有平均耗时数据，需要从线上日志统计。
12. 视频提取的两个入口： 扣 6 点无并发限制， 不扣点有并发限制；两端客户端都用前者，确认是否符合计费预期。

配音功能总览#

几个名词

• 配音 / TTS：TTS 是「文字转语音」的意思，就是把文案念成一段音频。罗根里叫「配音」。
• 音色：配音时用谁的声音。音色列表里有两类：客户自己上传的「我的音色」，和公司后台上传、所有客户都能用的「官方 / 系统音色」（后台叫「公开音色」）。
• 声音克隆：客户上传或录制一小段自己的声音，系统就能用这个声音念任何文案。罗根的克隆是「零样本克隆」——不需要训练、上传完马上能用（93）。
• 配音引擎 v2 / v3：后台有两套配音引擎：
• v2（整篇配音）：整篇文案一次合成一条音频，可以选「整篇情绪」和语速。9.0 PC 端和小程序当前默认都用 v2。
• v3（分段配音，也叫 dots.tts）：把文案按句切成多段分别合成，可以逐句改字、改语气，最后「合成成品」时才定语速和音量。代码里已经做好，但默认关闭，要技术改配置并重新发版才会切换。
• 同一时间一个客户端只会用其中一套引擎，界面也跟着变（按钮、提示不同），下文分别标出「v2 时」「v3 时」。

在哪里

• PC 端：智能体工作台左侧步骤栏「配音合成」。页面标题「配音合成」，左上「返回文案」。必须先有文案才能进入，否则提示「请先完成文案，再进入配音」。
• 小程序：首页进入「智能体」，流程第 2 步「配音」，页面大标题「用你的声音 来表达这篇内容。」。

页面构成

后台处理：所有配音请求都经过 （统一网关） 转给 （配音服务）；v2 任务走 （任务队列） 排队，再由 GPU 机器上的 worker 合成。v3 走网关 转给 里独立的 tts-jobs 服务。

选择音色（我的音色 / 系统音色）#

在哪里

• PC：配音合成页左栏「选择音色」。
• 小程序：配音步骤「我的音色 · N」列表。
• 一键成片弹窗里也能选音色（小程序：/），小程序「创作工作台」宽屏右栏也有「选择音色」面板，列表为空时按钮「去克隆音色」。

能做什么、怎么操作

1. 列表里点一行即选中，选中的行显示「使用中」（PC）/ 圆点选中（小程序）。
2. 点行首的 ▶ 可以试听这个音色（见「音色试听」）。试听不需要先选中。
3. 音色多时可以搜索：PC 输入框「搜索音色」，按 Esc 清空，搜不到显示「没有找到匹配的音色」；小程序点放大镜。
4. 列表第二行显示上传时间：「刚刚上传」（10 分钟内）/「N 小时前上传」/「10月26日上传」。小程序里官方音色显示「系统音色」。
5. 打开页面时如果还没选，会自动选列表第一个；之前选的音色被删了，会清空选择。
6. 已经配好音后再换音色：PC 弹提示「已切换为「xx」，点「重新配音」生效」，成品卡标题旁出现「音色已更换 · 点此重新配音」。已配好的音频不会自动变。

限制与规则

• 音色列表 = 客户自己上传的音色 + 所有官方（公开）音色。每次最多取 100 个。
• 官方音色只有超级管理员能上传。
• PC 端不区分官方音色和自己的音色，两者都显示在同一列表里，也都显示删除按钮；小程序会把官方音色标「系统音色」并且不让删。
• 正在配音时不能切换音色（按钮被锁）。

常见问题

• 列表是空的：PC 显示「先上传一段你的声音」引导卡；小程序显示「还没有音色，先上传一段你的声音」。如果连官方音色都没有，说明加载失败或后台未配置官方音色，先让客户刷新/重进。
• 弹「加载音色列表失败」：网络或配音服务问题，让客户重试；持续出现转技术。

声音克隆（上传音色）#

在哪里

• PC：配音页左栏底部「上传音色」，或左栏标题旁「N 个 · 管理」→ 打开「声音克隆 / 音色资产管理」弹窗，有两个标签「上传音色」「音色列表」。
• 小程序：配音页「上传音色」→ 底部面板「克隆你的声音」，副标题「安静环境下读 10 秒，效果最好。」，可以选「现场录音」或「上传音频」。一键成片面板里也有「克隆音色」入口。

PC 端操作步骤

1. 填「音色名称」，最多 20 个字，提示示例「例如：我的声音 · 口播版」。
2. 「音频样本」：拖拽音频到虚线框，或点击选择文件。框下写着「7–15 秒 · 50MB 以内 · wav / mp3 / m4a」。
3. 选中后客户端先在本地检查：格式、大小（<50MB）、时长（7～15 秒）。
4. 通过后显示一条「正在上传并检测音质…」进度条，随后显示文件名、时长 · 大小 · 格式和绿色「音质良好」标签，可以试听样本、「替换」、删除。

• 注意：这里的进度条和「音质良好」都是界面效果，并没有真的上传或检测音质，真正上传发生在点「保存音色」时。客户说「明明显示音质良好却效果差」时，不能以此为依据。

5. 勾选「我确认拥有该声音的合法使用授权」。
6. 点「保存音色」，按钮变「正在创建音色…」。成功后弹窗关闭、列表刷新、新音色自动选中，提示「音色「xx」已创建并选中」；如果当前已有配音成品，会追加「，点「重新配音」生效」。
7. 按钮置灰时悬停提示原因：「请先填写音色名称」「请先上传音频样本」「请勾选使用授权」。

弹窗里的录音建议（原文）：「安静环境，无背景音乐」「正常语速，情绪自然」「只包含你一个人的声音」。

PC 端没有现场录音功能，只能上传文件。

小程序操作步骤

1. 打开面板时音色名称自动填「我的声音 01」（按已有数量编号），可改。
2. 二选一：

• 现场录音：屏幕显示一段朗读稿「照着读这段话：这段时间天气不错，晚上散散步，吹吹风，听听音乐，心情好了不少，真舒服啊！」，按住说话、松开结束；最长自动录 15 秒，录音格式 mp3、16kHz 单声道。录完显示「录好了 · N 秒」，可试听、「重录」；时长不在 7–15 秒提示「时长需要 7–15 秒，请重录」/「录音时长需要 7–15 秒」。首次录音需授权麦克风，拒绝过会弹「需要麦克风权限」。
• 上传音频：从微信聊天记录里选文件（chooseMessageFile，只能选聊天里收到过的文件），只支持 mp3 / wav / m4a，不超过 50MB。界面写「时长需要 7–15 秒」，但小程序上传文件时并不检查时长（见「待技术确认」）。

3. 勾选「我已阅读并同意《声纹授权协议》」，点协议名可看全文（「同意并授权」/「不同意」）。
4. 点「开始克隆」，显示「正在学习你的音色…」和进度；中途可点「取消」中断上传。
5. 成功提示「音色已保存」，面板关闭，新音色自动选中。

限制与规则（以代码为准）

• 后台收到文件后：非 wav 会转成 16kHz 单声道 wav；如果配置了语音识别（ASR），会自动识别样本里说的话作为「参考文字」一起保存，识别失败会拒绝创建。
• 点数：上传音色本身代码里没有扣点数的逻辑（未见计费规则）。
• 耗时：一般几秒到十几秒（上传 + 格式转换 + 识别文字）；网关上传超时由后台配置，具体值待技术确认。

后台处理

PC / 小程序 → `POST →：校验格式 → 转码 → 大小检查 → ASR 识别参考文字 → 上传云存储 → 写入音色表。v2 和 v3 共用同一张音色表，克隆一次两套引擎都能用。

常见问题

• PC 报「音频时长需在 7 至 15 秒之间，请重新上传」，但客户的音频确实是 7～15 秒：PC 端把后台返回的所有「HTTP 400」错误都显示成这句话。实际原因多半是：① 文件是 aac / ogg / flac / wma（PC 允许选，后台不收）；② 文件超过 10MB；③ 文件损坏无法转码；④ 名称重复但没被识别出来。处理：让客户把音频转成 mp3 或 wav、10MB 以内 再传。
• 报「音色名称已存在，请使用其他名称」：换个名字。
• 克隆出来的声音不像 / 有杂音：样本要安静、无背景音乐、只有一个人说话、正常语速；建议重新录一段干净的 10 秒左右样本再克隆。PC 上的「音质良好」只是界面展示，不代表真实检测结果。
• 小程序选不到文件：小程序只能从微信聊天记录里选，先把音频发到自己的微信（如文件传输助手）再选。
• 删除音色：PC 在「音色列表」标签点垃圾桶，确认框「删除后不能恢复，用到它的配音不受影响。确定删除音色「xx」？」；小程序点「管理」→ 叉号，确认框「确定删除「xx」吗？删除后不能恢复。」。已经生成的配音不受影响。

音色试听#

在哪里 / 怎么用

• 音色列表每行前的 ▶（PC 悬停提示「试听」/「停止试听」）。再点一次停止。同一时间只播一个，开始配音时会自动停止试听。
• 试听播放的是这个音色当初上传的原始样本，不是用它念文案的效果。
• PC 克隆弹窗里选好样本后也可以点 ▶ 试听本地样本。
• 小程序在 iPhone 上第一次播放会提示「如无声音，请检查 iPhone 静音键与系统音量」。

常见失败

• 「该音色暂无试听音频」（PC）/「该音色暂无试听资源」（小程序）：音色记录里没有样本地址。
• 「试听音频加载失败」/「试听失败」：网络或样本文件打不开。
• 详见报错表。

合成配音（开始配音）#

在哪里

• PC：配音合成页「开始配音」大按钮，副标题「用「音色名」的声音合成 · 约 m:ss」，没选音色时显示「先在左边上传或选择一个音色」。
• 小程序：配音页底部「开始配音」，下方小字提示为什么按不了（如「先回到文案写好内容」「先在「更多设置」里选一个整篇情绪」）。
• 一键成片也会自动走配音这一步。

操作步骤（v2，当前默认）

1. 确认有文案、选好音色、选好整篇情绪、调好语速。
2. 点「开始配音」。如果之前已经生成过数字人视频、剪辑、封面等后续结果，会弹确认「重新生成音频将清除已生成的数字人视频、…，是否继续？」（小程序文案为「重新生成配音将清除已生成的…，是否继续？」/）。
3. 进入全屏进度：PC 标题「正在生成配音」，文字「正在提交配音任务…」→「正在准备配音资源」（排队）→「正在合成整篇配音…」；小程序「正在配音」，排队时「排队中，正在等待配音资源」，合成时「正在合成整篇配音 · N%」。
4. 完成后：PC 进度消失，右侧变成「配音成品」卡；小程序自动弹出「配音已完成」面板。
5. 下一步：PC 点「前往生成数字人」（「带着这条配音，生成数字人口播视频」）；小程序点「前往数字人」。

v3（分段配音）时的不同

• 提交后服务端立刻按句切段（每段约 20 秒以内、最多 100 段），各段并行合成，进度显示「已完成 N/M 段（x%）」，全部完成后自动「合成成品」。
• PC 全屏进度按百分比显示一串阶段文字，如「正在逐句合成拟真人声」「正在拼接全部分段并统一响度」。这些阶段文字只是按进度百分比轮换的说明，不代表后台真实在做哪一步。
• 分段失败会自动重试一次；仍失败时页面显示「已完成 N/M 段，K 段失败」和「重试失败段」按钮。
• 同一个账号同时只能有一个正在合成的 v3 任务；新任务会先「正在停止上一次配音…」。
• 小程序 v3 进度页有「取消配音」按钮，确认文案「取消后本次配音不能恢复，需要重新开始配音。确定取消？」。v2 没有取消功能（PC、小程序都没有）。

限制与规则

• 文案长度：文案页最多 750 字，所以配音文案最多 750 字。后台上限：v2 5000 字、v3 10 万字。
• 预计时长：客户端按「字数 ÷ (5.4 × 语速)」秒估算，例如 300 字、1.0 倍速约 56 秒。这只是估算。
• 特殊符号：前端「特殊字符拦截」开关默认关闭，表情符号等会直接交给后台；开启时提示「文案包含暂不支持配音的特殊符号，请删除或替换后重试。（检测到：…）」。
• 点数：积分制（SVIP 点数）账号每次 v2 配音任务默认扣 10 点，后台「点数价格规则」可改。积分制账号不能使用 v3，会报「当前账号暂不支持分段配音」。
• 排队：v2 按会员等级进入不同优先级队列。
• 耗时：
• v2：客户端每 3 秒（小程序 2 秒）查一次进度，最长等 1 小时才判定超时。实际合成时长取决于排队和文案长度，代码中无固定值（待技术确认典型耗时）。
• v3：每段排队超过 10 分钟、或单段执行超过 5 分钟判定失败。
• 配音期间 PC 整页被遮罩锁住，不能操作；遮罩上没有取消按钮。

后台处理

• v2：客户端 POST （文案、音色 ID、情绪、语速）→ 网关注入用户和会员等级 → 任务队列 → GPU worker（IndexTTS2 模型）合成 → 上传云存储 → 客户端轮询 任务号} 拿到音频地址。worker 失败时，失败原因可能写成「任务处理失败（步骤: TTS推理）」这类带步骤名的句子。
• v3：POST 建任务 → 服务端切段派发 → 客户端通过实时推送（SSE，一种服务器主动推消息的连接）收到每段结果 →POST /jobs/{id}/merge` 合成成品。

常见问题

• 一直卡在「正在准备配音资源」/「排队中」：GPU 队列繁忙。等几分钟；超过 10 分钟无变化，记录时间、手机号转技术。
• 报「请选择整篇情绪」或「暂无可用情绪，请刷新重试」：情绪列表没加载出来，在情绪弹层点刷新；仍不行转技术。
• 报「未找到所选音色，请重新选择音色」：音色已被删除或列表过期，重新选一个。
• 报「请求参数验证失败」：通常是文案超长或参数异常，缩短文案后重试，仍报转技术。
• 配好的成品播放报「音频预览加载失败，请重新生成后重试」：音频链接失效或网络问题，点「重新配音」。

整篇情绪（v2）与逐句语气（v3）#

v2：整篇情绪（当前默认）

• 在哪里：PC 语速旁的「情绪 xx」按钮（悬停「选择整篇情绪」），以及成品卡下方「调整情绪」（副标题「整篇表达 · 重新配音」），打开「整篇情绪 / 给整篇文案，选一种表达」弹窗。小程序在「更多设置」→「整篇情绪」胶囊。
• 可选情绪：由后台「情感参考」音频决定，代码示例为「自然、伤心、嫌弃、害怕、平静、生气、高兴」，「自然」排第一。PC 默认选第一个，小程序默认选「自然」。
• 规则：情绪作用于整篇；改情绪后要点「按此情绪重新配音」或「重新配音」才生效，PC 成品卡会提示「设置已更改 · 点此重新配音」。弹窗底部提示「需要改字？回到文案页编辑后，再重新配音。」。
• 拖入本地音频时不能调情绪：「本地音频不能调整情绪，在线配音后可用」。

v3：逐句调整（「调整情绪」弹窗，仅 PC）

• 在哪里：成品卡「调整情绪」（副标题「逐句改字 · 调语气」）。弹窗标题「逐句调整，只重新合成改过的句子」，说明「点文字可以改字，点语气可从下拉中选择；其余句子保持不变。」。
• 能做什么：
• 改字：点某句文字进入编辑，改完点「确定并重新合成」，只重新合成这一句。成功提示「第 N 句已重新合成」，失败提示「第 N 句修改未生效，已保留原来的声音」。
• 选语气：每句可选「自然 / 热情 / 沉稳 / 亲切 / 激昂 / 温柔」。
• 统一语气：底部「统一语气」一次给全部句子设同一语气；「全部恢复原样」清除所有改动。
• 恢复原样：改过的句子显示「已修改」，点两次（第二次显示「再点一次恢复原样」）恢复最初的声音，不需要重新合成。
• 播放单句、「重新生成这句」（失败句）、「刷新状态」。
• 限制：一次最多改 20 处；不能输入 < 或 >；引号要用中文“”；源文字+指令+新文字合计约 499 个模型单位，改太多会提示「改动较长，可能超出单次修改上限」；改动大时建议「回文案页修改后重新配音」；单段音频超过 30 秒不能编辑。
• 改句子后成品会变成「成品待更新」，关闭弹窗后自动重新合成成品；如果已有数字人视频，会先确认「修改配音分段将清除已生成的…，是否继续？」。
• 小程序没有逐句编辑（10-30 已去掉分段修改，见近期变更）。
• 停顿：9.0 界面里没有手动加停顿的功能（10-24 已从编辑器去掉）。句与句之间由后台自动加约 0.35 秒停顿。

语速与音量#

语速

• PC：滑杆 0.5×（慢）～2.0×（快），每格 0.1，中间标「1.0× 正常」；拖动时只改显示，松手才生效。小程序：刻度尺，同样 0.5～2.0、0.1 一档。
• v2：语速在合成时生效，提示「整篇配音使用此语速」；配好后再改语速，提示「重新配音后生效」。
• v3：语速在「合成成品」时生效，配好后改语速 PC 自动更新成品，提示「即时生效，无需重新合成」；小程序点「重新生成」时只重新合成成品，不重新整篇配音。

音量（仅 v3）

• PC：「音量 1.0×」下拉，可选 0.6× / 0.8× / 1.0× / 1.2×，提示「超过 1.0× 可能出现破音」。
• 小程序：「更多设置」→「音量」滑块 0.5～2.0，提示「在合成成品时生效，超过 1.0× 可能出现破音」。
• v2（当前默认）界面没有音量调节。

多音字与读音纠正#

客户端

• PC 和小程序都没有让客户自己纠正读音的功能。客户反馈某个字读错时，由公司在管理后台统一配置。

后台：管理后台「语音策略 → 多音字管理」

• 菜单位置： 左侧「语音策略」→「多音字管理」，有两个标签「v3 读音映射」「旧版规则（v2）」。
• v2 规则（当前默认引擎用这个）：填「原文」和「替换文」，配音前把原文直接替换成替换文。替换文可以写成带声调数字的拼音（如 qiao4牌），留空表示这段文字不朗读（如让「——」不读）。区分大小写（ai、AI 是两条）。改完约 10 秒内生效，不用重启。
• v3 读音映射：原文 → 读法，读法只能用带声调符号的小写拼音（如 shuì服），不支持数字声调；只对改完之后新提交的任务生效。
• 两套规则互不通用，切换引擎时要分别配置。
• 注意：替换是「无条件子串替换」，原文尽量写完整的词，否则会误伤其他地方（例如把「好」全部换掉）。

常见问题

• 客户反馈「某个词读错」：记录原文、正确读法、客户用的是哪段文案，转后台管理员在多音字管理里加规则；加完让客户重新配音。
• 数字、日期读法：v2 会先把完整日期（如 2026-05-08）读成「二零二六年五月八日」（「替换顺序」）。

配音结果：试听、下载与保存#

PC

• 成品卡「配音成品」：播放 / 暂停、点波形跳转、键盘左右键前后 5 秒；右上显示「音色 · 情绪 · 语速× · 时长」。
• 三张操作卡：「调整情绪」「重新配音」「下载音频」。下载会弹系统保存框「保存音频」，成功提示「音频已保存」。v3 成品待更新时下载置灰「成品更新后才能下载」。
• 格式：v2 一般为 wav（后台生成），下载卡显示扩展名（MP3 / WAV 等）。

小程序

• 配完自动弹出「配音已完成」面板，也可以从页面顶部「试听配音」卡片打开。
• 下载：小程序里音频不能存相册，会先「正在准备配音文件」然后调起「发送给微信好友/文件传输助手」；不支持时走普通下载。

保存

• 配音结果（音频链接、任务号、所用音色/情绪/语速）自动保存在当前作品草稿里，下次打开草稿会恢复；任务还没完成时会自动接着查。
• 如果切换了引擎版本，旧草稿里的配音：有在线音频地址就保留；否则提示「旧配音任务版本不匹配，请手动重新配音」。
• 改了文案（文案页编辑）会清除已配好的音频，需要重新配音。
• 音频文件存在云存储，客户端没有「我的配音」历史列表。

用自己的音频代替配音（仅 PC，有限制）#

• 入口：PC 配音合成页没有按钮，只能把音频文件直接拖到配音页任意位置。支持 .mp3 .wav .m4a .aac .ogg .flac .wma，不是音频提示「请上传音频文件」。
• 拖入后可以在成品卡里播放、下载，但这段音频只在本机，不会上传到服务器。
• 不能用来生成数字人：下一步按钮会变成「生成在线配音 / 数字人需要在线配音，用选中的音色合成一条」；也不能调整情绪（「本地音频不能调整情绪，在线配音后可用」/「本地音频不能逐句调整，在线配音后可用」）。
• 小程序没有此功能。
• 结论：9.0 里客户无法用自己录好的整段音频直接驱动数字人。客户有此需求时，建议用声音克隆+配音；如确需支持，转产品/技术确认。

近期变更（配音）#

• 2026-11-04 小程序：提示统一为纯文字提示和全局等待遮罩。
• 2026-11-03 后台：v2 多音字映射修复——worker 中不生效的问题修复、完整日期先读再替换、替换文留空可删除文字。
• 2026-11-03 小程序：v2 配音的恢复、失败提示修复，整篇情绪默认选「自然」。
• 2026-11-02 PC：语速改为可拖动滑杆（0.5～2.0×），音色列表可拖动滚动；小程序配音切换到 v2，默认情绪「自然」。
• 2026-11-01 PC/小程序：新增可切换的 v2 整篇配音引擎及配套界面，默认改回 v2（v3 分段编辑界面保留但默认不显示）。
• 2026-10-30 后台：v3 合成改用完整编辑模型，提升首次合成音质；修复合成成品调语速/音量失败；小程序去掉分段修改、新增音色搜索。
• 2026-10-29 PC：配音页按新设计重做（左音色列表、右文案/成品卡、三张操作卡）。
• 2026-10-26 PC：配音进度遮罩显示 v3 排队状态；克隆弹窗写明真实样本限制（7–15 秒）。
• 2026-10-25 后台：v3 支持自定义多音字与符号读音（管理后台「v3 读音映射」）。
• 2026-10-24 后台：公开（官方）音色只有超级管理员能上传，修复普通用户可创建公开音色的问题；PC v3 编辑可同时改字和语气、支持恢复原样，去掉停顿编辑。
• 2026-10-13～10-23 PC：上线 v3 分段配音和逐句情绪编辑（后续 11-01 默认关闭）。
• 2026-09-28 后台：上传音色时自动识别并保存参考文字（ASR）。

待技术确认（配音）#

1. 生产环境实际用哪套引擎：PC 与小程序代码默认 v2，是否有构建变量 VITE_TTS_API_VERSION 在正式包里改成 v3？客服需要知道客户看到的是哪套界面。
2. PC 克隆上传的格式/大小与后台不一致：PC 允许 aac/ogg/flac/wma 和 50MB，后台只收 wav/mp3/m4a、10MB。且 PC 把所有 HTTP 400 都显示成「音频时长需在 7 至 15 秒之间，请重新上传」，会误导客户。是否修正？
3. 小程序上传文件不检查时长，后台也默认不检查（enable_voice_duration_check=False），超长样本会被接受；是否有效果影响、是否要补检查？
4. PC 端官方音色可以点删除，后台会拒绝（403「无权限删除该音色」），PC 可能显示英文「Request failed with status code 403」。实际表现待确认。
5. v2 典型合成耗时（例如 300 字 / 1000 字大约多久）和排队规则，代码中无固定值。
6. 点数：v2 每次配音默认 10 点是否为线上实际配置；失败是否退点；上传音色是否计费。
7. 积分制账号无法使用 v3（BILLING_UNSUPPORTED），如果将来切 v3，积分客户会全部无法配音。
8. 声纹协议写「删除音色会同步清除模型数据」，但后台删除音色只删数据库记录、云存储文件保留。合规口径待确认。
9. 每个账号最多能克隆多少个音色、是否有每日次数限制——代码中未见。
10. 小程序音色名称是否有长度上限（输入框未设 maxlength，后台 v2 未见限制，v3 为 1–64 字）。
11. PC 拖入本地音频不能用于数字人，是否为预期设计（界面无任何提示说明此入口）。

数字人功能总览与三种方式对比#

先弄懂几个词

• 数字人 / 口播视频：把客户的配音（上一步「配音」生成的音频）和一个人物形象合在一起，生成「这个人在对着镜头说这段话」的视频。
• 形象：用来生成口播视频的人物素材。可以是一张照片（图片数字人），也可以是一段真人视频（视频数字人）。
• 口型同步（对口型）：让画面里人物的嘴型跟着配音动，看起来像真的在说话。
• 训练：用客户上传的一段较长视频，专门为这个人做一个「专属模型」，让口型和神态更像本人。只有「深度训练（小程序叫定制训练）」需要训练，其他两种上传后马上能用。

三种方式（客户能选的）

数字人这一步页面顶部有两个大类：图片数字人、视频数字人；视频数字人下面再分 免训练 和 深度训练。小程序里叫法不同：分段只有「图片数字人 / 视频数字人」两项，深度训练在小程序叫「定制训练 / 定制数字人」，从「…」菜单的「定制专属形象」进入。

PC 和小程序的主要差异（汇总）

• PC 支持「双镜头」（正脸 + 侧脸两段视频）上传视频形象；小程序已移除双镜头（提交记录 2026-10-21「移除数字人双镜头上传的死代码」）。
• 深度训练的素材时长提示不一致：PC 写「1–3 分钟」，小程序写「建议3~5分钟，且必须大于30秒」，并且小程序会拦截 ≤30 秒或 >5 分钟的视频；PC 前端不检查时长，由后台检查（30 秒～600 秒）。详见「上传素材训练自己的数字人形象（深度训练 / 定制训练）」。
• 小程序上传视频只能「从相册选择」，不能现场拍摄。
• 小程序首次上传视频前要先同意《隐私政策》。
• 图片数字人排队已满的提示语不同：PC「当前使用人数较多，请稍后重试」，小程序「当前排队数量到达上限，请稍后重试」。
• PC 有「搜索形象」输入框；小程序点放大镜打开「搜索形象」面板。
• 形象名称长度：PC 最多 16 个字；小程序最多 20 个字（照片），视频名称输入框最多 30 个字。

数字人这一步在哪里、怎么用#

在哪里

• PC：智能体工作台的第 4 步「数字人」（配音之后、剪辑之前）。页面标题「数字人」，左上角返回按钮提示「返回配音」。
• 小程序：智能体主流程里的「数字人」步骤，大标题「用你的形象，帮你出镜做视频。」，返回按钮「回到配音」。宽屏（平板/PC 微信）右栏有「选择数字人」列表。
• 一键成片：PC「一键产出」弹窗里也有「数字人」一栏，可选「图片数字人 / 视频数字人」、形象、剪辑气口、添加美颜。一键弹窗里没有「深度训练」分页。

操作步骤（PC）

1. 先在「配音」步骤生成好配音。没配音时页面右上角显示「尚未配音，可先挑选形象」，生成按钮下方小字「请先完成配音」。
2. 顶部选「图片数字人」或「视频数字人」；选视频数字人时，再选「免训练」或「深度训练」。
3. 在「01 选择形象」这一排里点一个形象（双击可看大图）。最左边的按钮是新增：图片数字人叫「上传照片」，免训练叫「上传视频」，深度训练叫「训练新形象」（额度用完时显示「暂无训练额度」并带锁）。
4. 「02 额外需求 / 细节处理」：

• 图片数字人：可选「更换背景」「更换服装」（可选，不选也能生成）。
• 视频数字人：「剪辑气口」（自动剪掉多余的停顿和呼吸声）、「添加美颜」（轻度磨皮和提亮，不改变脸型）两个开关。

5. 点「生成口播视频」。按钮下方会显示「约 时长 · 形象名」。生成时全屏进度遮罩，完成后自动弹出「数字人成片」，可「下载」「重新生成」「前往剪辑」。
6. 生成过之后，按钮变成「重新生成」「查看成片」，页面顶部有「上次成片 · 点击查看」。

操作步骤（小程序）

1. 「我的形象」区域横排选形象；右侧有放大镜（搜索）、「上传形象」（定制模式下为「定制训练」，额度用完显示「额度已用完」）、「…」菜单（「定制专属形象 / 改用普通视频数字人」「刷新形象列表」「删除已生成的视频」）。
2. 下方「额外需求」（图片）或「细节处理」（视频/定制）同 PC。
3. 点「生成口播视频」；生成后可「重新生成」（会先确认：「会用当前选的形象和设置重新生成，现在的口播视频会被替换。确定吗？」）或「前往剪辑」。
4. 生成完自动弹出「口播视频已生成」面板，点封面全屏播放，可「下载成片」「前往剪辑」。

生成过程中客户看到的进度文字

• 遮罩小字随进度变化（PC 与小程序相同）：「正在解析配音节奏与音素特征」→「正在定位数字人面部关键点」→「正在对齐口型与语音时间轴」→「正在驱动唇形与面部表情」→「正在生成自然的神态与微表情」→「正在逐帧渲染数字人画面」→「正在增强面部与牙齿细节」→「正在校验音画同步与唇形精度」→「正在合成音视频轨道」→「正在编码导出高清成片」。这些只是按百分比切换的展示文字，不代表后台真的在做这一步。
• 排队时显示「正在准备数字人生成资源」，副标题「排队中」。

限制与规则（通用）

• 必须先有配音：没有时提示「请先生成音频」。
• 配音只在本地、没有在线地址时：提示「需要重新生成音频以获取在线链接」。
• 换形象会清掉已生成的数字人视频和后续剪辑结果，PC 会弹「重新设计形象」确认。
• 生成中不能换形象。
• 客户端等待上限 2 小时（含排队）：超过后提示「数字人生成任务等待超时，请稍后在任务中心查看处理结果」。后台任务不一定失败，可以去任务中心看。
• 每 3 秒查询一次进度；连续 5 次查询失败就报错「查询任务状态连续失败 5 次，请检查网络连接或稍后重试」。图片数字人断网时查询失败不计数（提交 2026-09-24）。

后台处理

• 图片数字人：（图片口播服务），经统一网关转发。
• 视频数字人（免训练 + 深度训练生成）：（视频数字人服务），经统一网关转发。
• 深度训练：（训练服务），经统一网关转发。
• 三者都通过 queue-manager（任务队列）排队。

图片数字人#

在哪里

• PC：数字人步骤顶部「图片数字人」页签。品牌配置可关闭（默认开启），关闭后看不到这个页签。默认进入数字人步骤时选中的就是图片数字人（提交 2026-09-17）。
• 小程序：数字人步骤分段「图片数字人」。

能做什么

用一张照片 + 配音，生成这个人对着镜头说话的视频。还可以先给照片「更换背景」「更换服装」，再用换好的图生成。

上传照片（新建图片形象）

• PC：点形象排最左的「上传照片」，弹窗标题「上传你的照片」，副标题「一张清晰正脸照，就能生成会说话的你。」。
• 拍摄要求（原文）：「支持 JPG / PNG / WEBP，单张 10MB 以内」「清晰正脸，光线均匀效果更好」「建议竖版 9:16，人物占画面一半以上」。
• 起个名字：最多 16 个字，不能和已有形象重名。
• 点「保存形象」，成功提示「形象「名字」已保存」。
• 小程序：「上传形象」→ 面板「上传形象」，页签「上传 / 管理」；提示「正脸、光线均匀、无遮挡，效果最好。」「JPG / PNG，10MB 以内」。可从相册或拍照选。名称最多 20 个字，同名提示「图片名称已存在」。成功提示「数字人保存成功」。
• 规则（前端检查）：只收 JPG、PNG、WEBP，≤10MB。
• 后台也接受 BMP、GIF，但客户端不让选。
• 照片分辨率：前后台都没有最低/最高分辨率检查；上传的照片会按手机拍摄方向自动转正（b9，2026-11-01）。

系统形象 / 我的形象

• 图片形象列表只显示「用户形象」（asset_type=1）。
• 公共形象（is_public）不能删除，自己的可以删。PC 在形象右上角垃圾桶删除，确认语「删除后不能恢复，已生成的视频不受影响。确定删除形象「名字」吗？」；小程序在「管理」页签删除，确认语「确定删除“名字”吗？删除后无法恢复。」。
• 删除只删记录，存储里的图片文件保留（docs/图片形象接口）。

更换背景 / 更换服装

• 入口：选中照片形象后，「02 额外需求」里的「更换背景」「更换服装」卡片。没选照片时提示「先选一个照片形象」/「请先选择图片形象」（小程序）。
• 弹窗标题：背景「让形象更贴合场景」，服装「给形象换一身衣服」；副标题「五官、发型与姿态会尽量保持不变」。
• 三种方式选一：

1. 背景库 / 服装库（挑现成的）：系统模板 + 自己上传过的素材；自己上传的可以删。系统自带背景模板 8 个、服装模板 4 个（/migrations/005_image_asset_template_seed.sql:12-57）。
2. 上传背景 / 上传服装（用自己的图）：PC 文件框只让选 JPG / PNG，≤10MB；建议背景「竖版、无人物」，服装「平铺或挂拍，背景干净」。小程序提示「JPG / PNG / WEBP，10MB 以内，上传后会放进素材库」。
3. 自定义（文字描述）：至少 4 个字，最多 120 字（小程序 /）。

• 点「替换背景 / 替换服装」，等待中显示「正在更换背景 / 正在更换服装」，成功提示「背景已更换 / 服装已更换」。PC 单次最多等 5 分钟。后台按顺序尝试多家 AI 出图服务，每家 90～180 秒超时。
• 两步链：可以先换背景再换服装（或反过来）；关掉上面一步只退回上一步结果，关掉下面一步会连带清掉上面一步。
• 换完的图只用于这次生成，不会自动存成新形象。
• 切换到视频数字人时会提示「切换后数字人形象会退回原图，已更换的背景和服装都会丢掉。确定切换吗？」。

生成

• 提交：配音地址 + 照片地址（换过背景/服装就用换好的图）。没有其他可调参数，客户不能选清晰度。
• 进度条：前 10 分钟从 0% 匀速走到 88%，之后停在 88% 等后台；后台真实进度 ≥88% 时才按真实进度显示；排队期间进度条不走（小程序同）。所以「卡在 88%」是正常现象，不是卡死。

限制与规则

• 配音时长：前后台都没有上限/下限；后台把音频切成每段 20 秒分段生成，再拼起来。配音越长，耗时越长。
• 清晰度：固定竖屏 480×832、25 帧；后台开启「超分」（把画面放大变清晰的处理）时输出 1080×1920。超分默认关闭，是否开启看部署。
• 口型：由 AI（InfiniteTalk 模型）根据配音生成嘴型和表情，提示词固定为「人物自然说话，表情稳定，动作自然，清晰真实」。
• 排队：服务排队数量超过上限时拒绝新任务（生产阈值约 10 个，:29），客户看到「当前使用人数较多，请稍后重试」/「当前排队数量到达上限，请稍后重试」（小程序）。被拒的任务不会稍后自动补跑（f7，2026-11-03）。
• 点数：按代码，队列按服务名计费的列表里没有图片数字人，即代码层面不扣积分（待技术确认运营后台是否另有配置）。
• 结果保存：成片存到对象存储，链接有效期约 10 年；服务器本地缓存 72 小时后清理（不影响已上传的成片）。

后台处理：接收任务 → 排队 → 下载照片和配音 → 按 20 秒一段交给 ComfyUI（AI 出视频的工具）生成 → 拼接 → （可选）超分 → 上传成片。单段生成超时 30 分钟。耗时代码里没写明，PC 前端按「10 分钟左右」设计进度条。

常见问题

• 进度一直 88%：正常，后台还在做，长配音更久；最多等 2 小时，超时后去任务中心看结果。
• 提示当前使用人数较多 / 排队数量到达上限：服务忙，过几分钟再点生成；不扣点。
• 换背景失败 / 提示「AI 图片生成超时，请稍后重试」：AI 出图服务慢或忙，稍后重试，或换「背景库」里的现成图。
• 提示「媒体替换服务额度不足，请联系管理员」：公司这边的 AI 出图账号额度不足，直接转技术。
• 照片上传后人物歪了：11-01 之后已自动按拍摄方向转正；更早上传的可删除重传。
• 效果不好（脸变形、嘴型不自然）：换一张正脸、光线均匀、人物占画面一半以上、竖版 9:16 的照片。

视频数字人（免训练）#

在哪里

• PC：「视频数字人」→「免训练」。
• 小程序：分段「视频数字人」。

上传视频形象

• PC：点「上传视频」，弹窗标题「上传你的视频」，副标题「上传一段口播视频，保存后即可直接使用。」。
• 拍摄要求（原文）：「支持 MP4 / MOV / AVI / MKV / WEBM，1GB 以内」「1 分钟以内的竖屏正脸口播片段」「画面稳定，人物占画面一半以上」。
• 镜头：「单镜头 / 双镜头」，双镜头「需要分别录制正脸和侧脸」，要分别上传「正脸视频」「侧脸视频」。
• 起名最多 16 字，不能重名。点「保存形象」，保存时显示「正在上传素材… / 正在解析形象… / 即将完成…」（这是估算进度）。
• 小程序：「上传形象」→「上传一段视频」，提示「正面对着镜头说话，光线均匀，30 秒以内。」；只能「从相册选择」；首次上传要同意隐私政策。
• 前端检查：格式 MP4 / MOV / AVI / MKV / WEBM（PC）；大小 PC <1GB、小程序 ≤1000MB。PC 还会试读视频，读不出来提示「视频无法解码，请换一个视频文件」。
• 时长：PC 文案写「1 分钟以内」、小程序写「30 秒以内」，但两端前端都不检查时长；后台允许最长 10 分钟（见下）。

系统形象 / 我的形象

• 列表同时包含公共形象（系统形象）和自己的形象（include_public 由品牌配置决定，默认 true）。
• 免训练页签只显示类型为「reference」的形象；深度训练页签只显示「custom_train」类型。
• 公共形象不能删；自己的形象 PC 用垃圾桶删除，小程序在「管理」页签删除（确认语「确定要删除这个视频吗？」）。

生成选项

• 「剪辑气口」：自动剪掉多余的停顿和呼吸声。
• 「添加美颜」：轻度磨皮和提亮，不改变脸型（提交参数名是 beautify_teeth，即美化牙齿）。
• 两个开关默认都是打开。

后台对上传视频的检查

• 时长 ≤600 秒（10 分钟），大小 ≤1024MB；没有最短时长要求。超出提示「正脸视频时长不能超过600秒」「参考视频大小不能超过1024MB」等。
• 人脸检测：抽 30 帧，正脸视频至少 70% 的帧要能检测到人脸，侧脸视频至少 50%。不达标提示「正脸视频人脸检测失败: 人脸检测率过低 (xx%，要求至少70%)」。
• 帧率高于 25 会降到 25，非标准编码会自动转码，所以上传后「正在解析形象…」可能比较久。
• 名称重复提示「模型名称已存在」。

生成时的限制与规则

• 配音时长上限 5 分钟（300 秒），超过会在生成时失败。客户看到的失败原因可能只是「任务处理失败，请稍后重试」，见报错表。配音超过 5 分钟请分成几段做。
• 清晰度：输出跟随形象视频的分辨率，最大 2560×1440（竖屏 1440×2560），超过会缩小，低分辨率不会放大；后台有「统一转 1080」的开关，默认关闭。客户不能选清晰度。形象视频拍得越清楚，成片越清楚。
• 口型同步：用 LSTM 口型模型 + 中文语音特征驱动嘴型；「添加美颜」开时用带牙齿美化的模型。双镜头形象会在配音停顿处在正脸 / 侧脸之间切换，侧脸失败时自动只用正脸。
• 生成时每一帧都要能找到人脸，找不到会失败（报「Face not detected」类错误）。
• 同一用户同时只能跑 1 个数字人生成任务（网关配置，线上以运营配置为准），多点会提示「您已有 1 个任务在处理中，预计还需 N 秒」。
• 后台单个任务最长 2 小时（7200 秒）。
• 积分：积分制账号每次默认 50 积分，与配音时长无关；成功才扣，失败退回。

后台处理

网关 → 队列 → 工作进程：读取形象（深度训练形象用专属模型）→ 口型推理 → 编码（剪气口）→ 上传成片。后台进度：初始化 0–5%，预处理 5–15%，口型推理 15–90%，编码 90–97%，上传 97–100%。成片上传后就不能再取消。耗时代码里没写明（待技术确认）。

常见问题

• 上传视频提示人脸检测失败：视频里人脸不够清楚或很多帧没露脸（低头、侧身、出画、遮挡）。让客户拍正脸、人物占画面一半以上、全程露脸。
• 配音很长，生成失败：视频数字人配音上限 5 分钟，把文案拆成几段分别生成。
• 成片不清楚：成片清晰度跟形象视频走，换一段 1080P 以上的形象视频。
• 提示「您已有 1 个任务在处理中」：等上一条生成完再点。
• 双镜头效果不对：检查侧脸视频是否清楚露脸（侧脸要求 50% 帧有脸），不行改用单镜头。

上传素材训练自己的数字人形象（深度训练 / 定制训练）#

在哪里

• PC：「视频数字人」→「深度训练」→ 形象排最左「训练新形象」，弹窗「训练你的专属数字人」。没有额度时按钮显示「暂无训练额度」，点击提示「暂无深度训练额度，请联系管理员」。
• 小程序：「…」→「定制专属形象」切到定制模式，再点「定制训练」；面板有「提交训练 / 训练任务」两个页签。没额度提示「无定制额度，请联系客服」（或「…请联系运营人员」，看品牌）。

操作步骤（PC）

弹窗顶部四步：「上传素材 → 素材质检 → 模型训练 → 完成」。

1. 上传素材：选视频（「1–3 分钟 · MP4 / MOV · 1GB 以内」），起名（≤16 字），点「下一步：素材质检」。
2. 素材质检：逐项显示视频时长、分辨率、人脸检测、光线环境、音频质量、嘴部遮挡，然后「6 项全部通过，可以开始训练」。注意：这一步是前端演示，只有时长和分辨率是真读出来的，其他几项一定显示通过，并没有真正检测。真正的检查在后台训练时做，所以「质检全过但训练失败」是可能的。
3. 点「开始训练（消耗X积分）」（积分制账号才显示积分）。先上传（「正在上传训练视频…」「上传完成后开始训练，请不要关闭窗口」），再提交。
4. 模型训练：显示百分比和阶段「数据预处理 / 面部建模 / 口型驱动训练 / 渲染校准」、「预计剩余约 N 分钟 · 训练在云端进行，关闭窗口不影响进度」。可以点「后台训练，先去做别的」（提示「已转为后台训练，完成后会提醒你」）或「取消训练」。阶段名和剩余时间是按 20 分钟估算的，不是真实值。
5. 完成：「训练完成」「「名字」已加入深度训练形象…」，点「立即使用」。训练中的形象会在形象排里显示「准备中 / 训练中 + 百分比」，每 30 秒刷新；完成时提示「「名字」训练完成，可以使用了」，失败时提示「「名字」训练没有成功，可以换一段素材再试」。

操作步骤（小程序）

1. 「提交训练」页签：填「定制形象名称」，「点击上传视频」（只能从相册选），提示「视频时长建议3~5分钟，且必须大于30秒，建议使用 mp4 或 mov 格式」。
2. 点「提交训练」，提交中提示「正在上传训练视频 / 正在提交训练任务」「请不要离开当前页面」，成功提示「训练任务已提交」。
3. 「训练任务」页签：提示「训练约需 30 分钟，请您耐心等待」，可「刷新」「查看进度」「取消训练」；状态显示「已完成 / 训练中 / 排队中 / 超时 / 失败 / 已取消」。

素材要求

给客户的拍摄建议（综合）：竖屏 9:16、1080P 以上；全程只有本人一张脸、正对镜头、开头第一秒就要露脸；光线均匀；环境安静、不加背景音乐；嘴部不要被话筒或手挡住；一镜到底不剪辑；时长 1～5 分钟最稳（两端都满足）。

训练耗时、次数、审核

• 耗时：代码里没有固定耗时；PC 按 20 分钟估算，小程序写「约需 30 分钟」。后台单步无进展超过 30 分钟算卡死，总时长上限 72 小时。训练服务同时只跑 1 个训练，排队的多时会更久。
• 次数（训练额度）：每个账号有「定制数字人额度」，由管理员在后台设置；额度为 0 时网关拒绝（「定制数字人额度已用完」）。
• 点数：积分制账号每次训练默认 200 积分，提交时冻结，成功才扣，失败 / 取消 / 超时退回。PC 取消时提示「已用掉的额度可能不会退回」——额度是否退回待技术确认。
• 审核：代码里没有人工审核环节；提交后直接进入训练。
• 防刷：训练服务每个来源每分钟最多 10 次提交。
• 训练完成后自动注册成「深度训练」形象，出现在「深度训练」页签（小程序在定制模式列表）。注册失败会每 5 分钟重试，最多 24 次，仍失败则任务失败。

后台处理

网关 上传视频（由 先检查格式、大小、时长、人脸，不合格当场拒绝）→ 提交到队列（任务号以 dh-train_ 开头）→ 训练服务：准备（下载、检查大小/时长/人脸）→ 规格标准化 → 预处理（抽人脸、抽声音特征）→ 训练 → 导出模型 → 注册为形象（/docs/训练服务说明:50-61）。进度：准备 5–28%，预处理 32–49%，训练 50–100%。

常见问题

• 质检全通过，上传或训练却失败：PC 质检是演示，真实检查在后台。看失败原因（见报错表），多数是：时长不足 30 秒或超过 10 分钟、AVI/MKV 格式不收、人脸可见帧不足 90%、视频没声音、视频编码读不出来。
• 小程序提示「视频时长不能超过5分钟」，但 PC 能传：两端规则不同。小程序上限 5 分钟，后台上限 10 分钟；建议客户剪到 1～5 分钟。
• 训练很久没动：训练服务一次只训一个，排队时显示「准备中 / 排队中」；超过 72 小时会失败。转技术时提供任务号（dh-train_ 开头）。
• 训练完成了但列表里没有：可能处于「登记形象」阶段（显示 99%），后台会自动重试；刷新形象列表，仍没有就转技术。
• 没有额度：需要管理员在后台给账号加「定制数字人额度」。

形象管理（系统形象 / 我的形象）#

列表与选择

• 三类形象各自一排：图片形象、免训练视频形象、深度训练形象；切换页签会记住各自上次选的形象。
• 系统形象（公共形象）：所有用户都能看到，不能删除。PC 是否显示由品牌配置 includePublicModels 决定（默认显示）。
• 我的形象：客户自己上传或训练的，可删除（深度训练形象在客户端不能删）。
• 搜索：PC 输入框「搜索形象」，找不到时「没有找到匹配的形象」；小程序「搜索形象」面板，找不到时「没有找到相关形象，换个名字试试」。
• 形象图片加载失败时显示默认人像图标，不影响使用。

命名规则

• PC 名称 ≤16 字；小程序照片形象 ≤20 字，视频形象输入框 ≤30 字。
• 重名：PC 提示「数字人形象名称已存在，请使用其他名称」；小程序照片提示「图片名称已存在」。

删除

• 删除形象不影响已经生成的视频（PC 确认语原文）。
• 删除后不可恢复。

生成时长、清晰度、口型同步、耗时与点数汇总#

积分规则说明：只有「积分制（svip_points + points 计费）」账号才扣积分，老的不限量账号不扣。异步任务提交时先冻结积分，任务完成才真正扣除，失败 / 取消 / 超时退回。默认价格可在运营后台改，客户端按后台价格显示。

近期变更（数字人）#

• 2026-11-03：图片数字人排队满时提交被拒，不再稍后自动补跑。
• 2026-11-03：PC 形象排滚动时「上传」按钮固定在最左。
• 2026-11-01：上传照片按拍摄方向自动转正。
• 2026-10-29：PC 数字人页面按新设计重做，新增「搜索形象」，新增上传 / 深度训练 / 换背景服装弹窗新样式。
• 2026-10-29：小程序数字人成片点封面打开全屏播放。
• 2026-10-28：小程序主流程 UI 重构，数字人页改新样式，生成进度小字与 PC 一致。
• 2026-10-26～29：换背景/换服装接入更多 AI 出图服务（阿里云百炼、hyhawang），失败自动换下一家。
• 2026-10-21：小程序移除双镜头上传。
• 2026-10-14：深度训练导出模型失败不再「假成功」；形象登记失败会自动重试。
• 2026-10-08：PC 图片数字人服务繁忙（503）时提示「当前使用人数较多，请稍后重试」。
• 2026-09-22：换背景/换服装改为两步链；替换超时放宽到 5 分钟；数字人生成等待上限统一为 2 小时；图片数字人新手引导上线。
• 2026-09-21/22：图片数字人排队时进度条不再前进（PC、小程序）。
• 2026-09-16：图片数字人按 20 秒一段生成长配音。
• 2026-09-17：数字人步骤默认选中图片数字人。
• 2026-09-09～10：图片数字人「更换背景 / 更换服装」上线，含系统背景/服装模板。

待技术确认（数字人）#

1. 图片数字人是否扣积分：代码中队列计费表没有 image-to-talk，运营后台是否另有规则？
2. 图片数字人线上是否开启超分（VSR_ENABLED），即成片是 480×832 还是 1080×1920？
3. 图片数字人一条口播通常要多久（按配音时长）？PC 进度条按 10 分钟设计。
4. 深度训练素材时长：PC 文案「1–3 分钟」、小程序「建议 3~5 分钟、≤5 分钟」、后台 30 秒～10 分钟，以哪个为准？是否统一文案？
5. 深度训练取消后，训练额度是否退回（PC 文案写「可能不会退回」）？
6. 深度训练真实耗时（PC 估 20 分钟、小程序写 30 分钟）。
7. 免训练视频形象：文案写「1 分钟以内」（PC）/「30 秒以内」（小程序），后台实际允许到 10 分钟，以哪个为准？
8. PC 深度训练的「素材质检」是演示，是否计划接真实检测？目前客户会误以为已通过检查。
9. 图片数字人进度提示里的「连接 ComfyUI …」是否会把内部地址展示给客户？
10. 图片数字人音频读取失败时，失败原因原文带有「Worker 安装 ffmpeg/ffprobe…」等开发提示，是否需要改成客户能看懂的话？
11. 训练失败原因里可能直接显示后台日志片段（英文或「[warn] face not found」等），客服是否需要统一话术？
12. 一键成片弹窗只有「图片数字人 / 视频数字人」，不能选深度训练形象，是否符合预期？
13. 视频数字人失败原因：后台状态接口的脱敏规则会把大部分失败原因变成「任务处理失败，请稍后重试」，客服难以判断原因，是否需要保留常见原因（如配音超 5 分钟、找不到人脸）？
14. 视频数字人生成一条口播的典型耗时（按配音时长）？
15. 同一用户数字人生成并发数线上实际配置（YAML 为 1）？

剪辑手法是什么、怎么出片#

能做什么

• 给数字人口播视频（或客户自己的竖屏口播）一键套上一种剪辑手法。后台自动完成以下几件事：
• 识别口播，生成逐句底部字幕
• 按内容挑选每段的场景效果（列举 / 数字 / 对比 / 金句等）
• 按这段话提炼画面文字
• 配图：先从视频素材库找真实视频，找不到就 AI 生图
• 需要时抠出人物
• 加转场和特效音，渲染成 1080×1920 竖屏成片。
• 出片时会随机配一首背景音乐：剪辑手法任务完成后，再跑一个混音任务（小程序）。
• 成片可以「我要编辑」：改文字、换图片 / 视频、拖动位置，然后再次生成（见「出片后编辑」）。
• 9.0 新增：10-21 起 PC 端剪辑手法改用 HyperFrames，小程序 10-27 切换。旧的「自定义包装」「达芬奇调色」10-29 已下线，现在只有全自动一种（小程序）。

后台怎么处理（大致流程）

客户端 → （要登录）→ 排队服务 Queue → 内网 派给空闲的 HyperFrames 服务机 → 出片后把地址回传 Queue → 客户端每 3 秒查一次进度。

每一步在做什么、大概多久

进度条上的小字是按百分比轮换的固定文案，和后台真实步骤不是一一对应的（小程序）。客户说「卡在某句话」不代表卡在那一步，要看后台步骤。

• 整单总时限 45 分钟，超过就失败。
• 网络类错误自动重试：单个请求先重试 3 次；整条任务最多执行 2 次，第二次只补做没完成的步骤。
• 同一条视频 3 小时内换手法重新生成会更快：同一台服务机复用下载、识别、抠像结果。
• 剪辑过程中没有取消按钮，PC 和小程序都没有（小程序）。

参考文案自动校正多音字（11-03 / 11-04 新增）

• 出片时客户端会把当前文案页的文案作为「参考文案」（standardScript）一起发给后台；文案为空就不带（小程序；PC 提交）。
• 后台把识别出的字和文案逐字对齐，时间用识别的，字用文案的，修正多音字、同音字和产品名（如「限制」被识别成「县制」）。底部字幕、画面文字都用校正后的字。
• 某句口播和文案对不上（数字人改了词、加了句、没念），这句保留识别原文，不会硬套。所以客户改了文案但没重新生成数字人，字幕仍以口播实际念的为准。
• 文案最多 50000 字。
• 「不剪辑」插画中画时，句子列表里看到的是没校正的原文，出片时才校正，所以成片字幕可能和句子列表有个别字不同（小程序 识别时都没带文案）。

常见问题

• 「暂不支持宽屏视频，请上传竖屏视频」：只支持竖屏口播（小程序）。
• 成片没有剪辑手法效果、也没字幕，只有原视频：后台没听到人声（静音、纯音乐），会按原视频出片，任务警告 NO_SPEECH。让客户检查口播视频是否有声音。
• 画面里有和口播无关的示例图 / 示例文字：某些素材位生图失败或文字没写好，用了模板示例（警告 TEMPLATE_IMAGES_PARTIAL / TEMPLATE_SAMPLE_MEDIA / TEMPLATE_CONTENT_SKIPPED）。小程序编辑页会提示「还有 N 张示例图片没换，换成你自己的」。让客户用「我要编辑」换掉，或重新生成。
• 字幕有错别字：先确认文案页有文案（有文案才会校正）；同音字以外的错误（如口播本身念错）不会改。
• 提交时提示「您已有任务正在处理中，请等待完成后再提交」：同一账号的剪辑手法任务正在处理时不能再交新的；旧任务还在排队时，新提交会自动取消旧任务。
• 生成很久：先看是不是高峰期排队（后台任务列表看状态）。超过 45 分钟会自动失败。

选择剪辑手法（风格墙 / 全部风格 / 样片预览）#

在哪里

• PC：工作流「智能剪辑」步骤，大标题「用大V的视频风格，帮你剪视频。」（91）。没有数字人视频就进入会提示「请先生成数字人视频，再进入风格剪辑」。
• 小程序：工作台「剪辑」步骤，标题同上。
• 一键成片弹窗里也有一行「剪辑」/「剪辑手法」可选（小程序），没有预览。

PC 端界面

• 剪辑手法墙：
• 三行卡片斜着循环滚动，鼠标停在哪行哪行就停
• 卡片显示封面、编号、名称、分类，选中打勾
• 底部提示「悬停查看 · 点击选中，再点取消 · 点 ▶ 预览」（68）。
• 编号取模板 id 去掉 vt，如 vt04 显示「04」。注意：和后台名称里的「VTxx」不是同一个编号，见下一节。
• 全部风格：墙右下角按钮「全部风格 N」（title「查看全部剪辑手法」）。
• 弹窗标题「全部剪辑手法」，副标题「共 N 种 · 选中后自动返回」
• 点一张就选中并关闭。11-01 新增（提交）。
• 样片预览：卡片上 ▶（「预览剪辑手法」）打开 9:16 样片循环播放，左上「No.{编号} · {名称}」。
• 按钮「再看看」「用这个手法」；选中后提示「已选择「{名称}」」
• 样片打不开显示「样片加载失败」。
• 开始剪辑：大按钮「开始剪辑」，下方小字「已选 No.xx · 名称」或「先在上方选一种剪辑手法」。没选就点，提示「先选一种剪辑手法」。
• 列表加载中显示「正在获取剪辑手法…」；为空或出错显示「暂时没有可用的剪辑手法」和「重新加载」按钮。

小程序界面

• 「热门剪辑手法」轮播，最多显示 10 个。
• 卡片下方显示所选手法的名称和简介。几种状态：
• 未选：「点一张卡片，选一种剪辑手法」
• 加载中：「剪辑手法加载中…」
• 失败：「{错误}，点这里重试」（56-66）。
• 「更多剪辑手法 N」打开底部弹层「全部剪辑手法」，网格展示编号、名称、简介和 ▶ 预览，底部「确认剪辑手法」（67-80, :131-154）。
• 预览为全屏样片，按钮「关闭」「用这个手法」（181-205）。

差异与规则

• 贴牌版（其他品牌的软件 / 小程序）：
• 风格列表按品牌分类取（请求带 category），封面换成不带我们模特的版本（小程序）
• 不能预览样片，没有 ▶（小程序）。11-03 / 11-04 改动。
• 列表加载后仍没选中时，自动选列表第一个；列表为空时提示「暂无可用的风格剪辑，请稍后重试」（小程序）。
• 列表的名称、简介、封面、预览、排序、上下架都在后台数据库表 clip_templates 里维护，改表即生效，不用发版。客户看到的名称以接口返回为准。
• 后台标 editable=false 的手法，成片页不显示「我要编辑」（小程序）。

33 个剪辑手法一览#

• 来源：出片服务 （名称、简介）和 （带编号的完整名称 label、分类）。
• 这两个文件只是初始数据，线上以数据库表 clip_templates 为准（on _说明）。
• 分类全部为「口播」。

编号对照：

• 「模板 id」：出片时用的 id，PC 卡片上显示的编号就是它去掉 vt（如 vt21 → 21）
• 「对外编号」：后台 label 里的 VTxx（如 vt21 的 label 是「VT10 · 夜城时讯」）。
• 两个编号不一样，客户报「No.21」时要先确认是哪个口径。

（没有 vt06、vt08、vt16、vt17、vt26、vt29，这些编号没有对应模板。）

出片后编辑（改文字、换素材、拖动、再次生成）#

在哪里

• PC：成片页「我要编辑」→ 编辑器，顶栏标题「编辑成片」。
• 小程序：成片页「我要编辑」→ 编辑页 （10-28 新增）。
• 只有剪辑手法成片、且该手法可编辑时才有「我要编辑」。不剪辑 / 画中画成片没有「我要编辑」（小程序）。

能改什么

• 改文字：画面上的大字 / 标签文字。
• 1–200 字（后端）
• 超过建议字数时提示「超过建议的 N 字，字号会自动缩小」，不拦截；后台按比例缩小字号，最小约原来的 35%。
• 换图片 / 视频：从共享素材库选，或上传新素材（11-03 起和画中画共用一个素材库，PC 提交）。规则：
• 透明贴纸位只能放 PNG：「透明贴纸位 · 只能放 PNG 图片」
• 其他位置可放图片或视频，比例不同会居中裁切铺满
• 视频去掉声音，比显示时间长只用开头，短了循环
• 客户端限制视频 0.5–60 秒、≤200MB（小程序 , 600-643）。后端本身不限时长，以客户端为准。
• 拖动 / 缩放：
• 有虚线框的元素可以单独拖动、四角缩放、方向键微调
• 也可以整个场景一起拖（10-23 / 10-24 新增）
• 拖出画面会被拉回；铺满画面的背景只能换素材不能拖。
• 背景音乐（编辑器里）：可以换曲、调音量 10%–100%、关闭、上传自己的音乐。只改背景音乐不重新渲染，只重新混音，很快。
• 不能改：
• 底部逐句字幕（按口播自动生成）
• 口播人物
• 场景顺序和时长。
• 有撤销 / 重做（PC 支持键盘快捷键）。PC 编辑器有「画面 / 文字 / 图片素材 / 视频素材 / 背景音乐」五个 tab，小程序有「字幕 / 图片素材 / 视频素材 / 背景音乐」。

保存流程

1. 点「确认修改」（PC）或保存（小程序），先做「编辑前检查」，显示「检查修改…」：

• 有不合规的修改：在对应元素上标红，提示「{片段名}：{后台原文}」或「有修改不符合要求，请调整后再保存」
• 只有会自动处理的提醒：弹「提交前确认」，正文「以下修改会由系统自动处理：」加列表，按钮「继续提交 / 返回修改」（小程序）。

2. 已有标题封面等后续成果时会确认是否清除（PC 动作名「按编辑重新渲染成片」；小程序「保存修改会重新生成成片，已生成的封面将被清除，是否继续？」）。
3. 提交后生成一个新任务，进度遮罩标题「视频修改中」，副标题「共 N 处修改」。

• 再次生成跳过下载、识别、抠像、写文字、配素材，只套用修改、渲染、上传，比首次出片快很多
• 排队也最优先。

4. 新成片也有自己的可编辑工程，可以继续编辑，所有版本都保留。

限制

• 可编辑工程只保留 1 小时（从出片完成算），过期后只能重新出片。提示原文：
• PC：「可编辑工程已过期（出片后保留 1 小时），请重新生成风格剪辑后再编辑」
• 小程序：「可编辑工程已过期（出片后保留 1 小时），请重新剪辑后再编辑」
• 时长由后台配置决定。
• 编辑次数不限，客户端和后端都没有次数限制；每次再生成都从新成片起算 1 小时。
• 刚出片的几秒到几十秒工程还在准备：打开编辑会自动每 3 秒重试，最多 10 次（约 30 秒），还不行提示「可编辑工程还在准备，请稍后再打开编辑」（小程序）。
• 上一次拖动有部分没生效时提示「上一次编辑中有部分拖动没有完全生效，可以在编辑器里接着调整」/「上次调整的位置有一部分没有完全生效」（小程序）。对应后台警告 LAYOUT_SKIPPED。
• 编辑也是一个剪辑手法任务，同样受「同一账号同时只能有一个任务在处理」限制。

常见问题

• 「我要编辑」按钮不见了：工程已过期（超过 1 小时）或失效，或这是画中画 / 不剪辑成片，或该手法不可编辑。只能重新生成。
• 换的素材生成后没生效 / 任务失败：素材地址打不开或文件坏了（EDIT_MEDIA_DOWNLOAD_FAILED / INVALID_EDIT）。让客户重新上传素材再试。
• 文字变得很小：超过建议字数自动缩字号，让客户精简文字。

不剪辑：普通字幕 + 按句插入画中画#

在哪里

• PC：剪辑手法墙下方小按钮「不剪辑，直接用口播视频」，打开弹窗，有「背景音乐」「画中画」两个 tab。
• 弹窗标题「不剪辑，直接用口播视频」，副标题「画中画和背景音乐都可以不加」。
• 小程序：剪辑页「不剪辑，直接用口播视频」，打开整页「直接用口播视频」，tab 同上。
• 11-03 新增（PC /；小程序同期）。

能做什么、怎么操作

1. 打开「画中画」tab，后台先识别口播，列出每一句（「正在识别口播里的句子…」「视频越长等得越久，可以先在左边选素材」）。
2. 在「我的素材」里选或上传一个图片 / 视频，再点右边（小程序是下面）的句子「放入」。

• 连着的句子放同一素材会合成一段
• 再点一次取消
• 点已放了别的素材的句子会换成当前素材（小程序）。

3. 选不选背景音乐都可以，点「开始插入画中画」或「开始生成」。
4. 成片效果：

• 原视频不剪辑、不加剪辑手法
• 加上逐句普通字幕，一行约 16 个字，长句在标点处分段
• 选中那几句的时间里，画面换成客户的素材，全屏铺满，盖住口播人物
• 口播声音和字幕保留，素材自带的声音去掉
• 不加特效音（, 426-432）。
• 一段画中画都不放时，就是原片（可选混背景音乐），不加字幕。小程序没识别出句子时提示「没有识别到句子，这次只能加背景音乐」。

素材要求（以客户端为准）

• 格式：jpg、png、webp 图片，或 mp4、mov 视频（小程序 , 136-146）。
• 图片 ≤10MB；视频 ≤300MB 且 ≤15 秒（产品 11-03 定）。后端单个素材上限写的是 200MB，因客户端限 15 秒，正常不会超。
• 最多 20 段，段与段不能重叠。

素材和句子长短不一样时怎么处理

• 图片：这几句话期间一直静止显示。
• 视频比这几句话长：只用开头一段。
• 视频比这几句话短：后端 11-03 起从头循环播放（提交）。客户端提示语还写着「视频比这段话短，播完停在最后一帧」（小程序），以后端循环为准，提示语待改（见待技术确认）。
• 比例不同：居中裁掉多出部分，铺满 1080×1920。

HDR 视频（iPhone 拍的视频）

• iPhone 默认拍 HDR（HLG），以前插进去会让成片变成 HEVC 编码、校验失败整单失败。
• 11-04 起后台自动先转成普通 SDR，客户不用处理（提交）。
• 如果客户反映 11-04 之前插 iPhone 视频失败，现在可以重试。

限制与规则

• 识别结果和放好的素材不保存，关掉弹窗 / 页面就要重新放：小程序会确认「关掉这一页？已放的 N 段画中画不会保存，关掉就要重新放。」。
• 识别后数字人视频变了，提示「口播视频已经变了，请关掉弹窗重新打开画中画」。
• 识别请求最多等 300 秒（小程序）。
• 画中画成片不能再编辑（客户端没开放「先出片再插画中画」）。要改只能重新打开「不剪辑」重新放。
• 素材下载不了 / 文件坏了时，这段画中画被跳过、照常出片，后台只记警告 PIP_SKIPPED，客户端不提示，客户会看到「有一段没加上」。

常见问题

• 某段画中画没出现：多半是素材地址失效或格式坏了被跳过。让客户删掉该素材重新上传，再生成。技术可在任务详情 warnings 里看到具体句子和原因。
• 「句子没识别出来」：口播没声音，或识别服务暂时失败（「语音识别失败，请稍后重试」），点「重新识别」。
• 视频素材传不上：检查格式（只收 mp4、mov）、大小（≤300MB）和时长（≤15 秒）。

剪辑手法 / 画中画：限制与规则汇总#

剪辑手法：失败提示怎么看#

客户看到的报错从哪来

• 提交时就报错：多为网关 / 排队服务的中文提示，如「您已有任务正在处理中，请等待完成后再提交」「积分不足」「HyperFrames 服务暂时不可用，请稍后重试」。
• 生成到一半失败：
• PC 通知「智能剪辑生成失败: {原因}」「画中画生成失败: {原因}」
• 小程序弹窗「智能剪辑失败」，里面有任务ID、状态、错误信息，可点「导出全文」。
• 失败原因原本是「错误码: 说明」，客户端只显示冒号后面的说明。说明大多是后台英文原文，例如：
• video duration 312.4s exceeds 300s：视频超过 5 分钟
• video download failed with HTTP 403：视频地址打不开。

完整对照见「报错说明大全」章节。

• 成片出来了但效果有问题：不算失败，后台在任务的 warnings 里记降级原因（如 NO_SPEECH、PIP_SKIPPED、TEMPLATE_IMAGES_PARTIAL），客户端不显示，只能由技术查任务详情。

转技术时收集什么

• 客户手机号 / 账号、发生时间（精确到分钟）、截图（含完整报错文字）
• 小程序失败弹窗里的任务ID（hf_ 开头），可以让客户点「导出全文」发过来
• PC 没有直接显示任务号，可按账号 + 时间在后台管理「特效包装-9.0」任务里找
• 所选剪辑手法名称，是首次出片、编辑再生成还是插画中画
• 技术排查位置：HyperFrames 统计页（任务列表、每步用时和错误）、任务详情接口 GET /v1/render-jobs/{任务号}/detail。

近期变更（剪辑手法与画中画）#

待技术确认（剪辑手法与画中画）#

1. 扣点规则：

• 积分计费表里没有 hyperframes-render
• 积分账号提交时按 / 可能报「当前任务未配置积分规则」。

剪辑手法首次出片、编辑再生成、画中画到底扣不扣、扣多少、失败是否退？ 2. 画中画视频比句子短：后端是循环播放，客户端提示仍写「播完停在最后一帧」（小程序），是否改提示语？ 3. 画中画素材上限：客户端视频 300MB，后端检查口径 200MB，以哪个为准？ 4. PIP_SKIPPED 不提示：画中画素材被跳过时，客户端是否要提示客户换素材？客户端映射的 PIP_DOWNLOAD_FAILED在后端不会成为任务失败码（素材失败只跳过），这条映射实际上不会出现。 5. 识别句子不带参考文案：句子列表和成片字幕可能有个别字不同，是否有意？ 6. 典型用时：典型口播（30 秒 / 1 分钟 / 3 分钟）首次出片总用时、渲染用时、背景音乐混音用时，请技术从统计页给出数字补进说明书。 7. 编辑前检查超时：内网 直接代理的读超时是 60 秒。后台单个素材检查约 15 秒、多个素材并行，一般不会超，是否需要兜底？ 8. 排队等待时间：Queue 层是否有任务总超时（timeout 状态）、超时多久？客户端轮询没有总超时。 9. 编号口径：PC 卡片显示模板 id 号（如 21），后台 label 是对外编号（VT10）。客服应按哪个口径记录？小程序卡片上显示的是哪个编号？

9.0 剪辑包装总览（先读这一节）#

一句话说明

9.0 把旧版「剪辑包装」的一堆独立开关（字幕样式、特效字幕、网感大字/MG、达芬奇调色 LUT、自定义包装模式、旧版画中画）全部收进了「剪辑手法」：客户只需要选一种剪辑手法点「开始剪辑」，字幕、花字、动效、转场都由这个手法自动生成；剪完后系统再随机配一首背景音乐。不想剪辑的客户可以走「不剪辑，直接用口播视频」，只加背景音乐和/或自己放画中画。

9.0 里还有 / 已经没有的功能

工作流顺序（PC 与小程序相同）

文案 → 配音 → 数字人 → 智能剪辑（剪辑手法 / 不剪辑）→ 标题与封面 → 发布。

• PC 剪辑页顶栏标题是「智能剪辑」，编辑成片时变成「编辑成片」。
• 「智能剪辑」页成片出来后，右下按钮「生成标题封面」进入下一步。

后台由谁处理（9.0 实际链路）

点数（会员点数）

• 客户端在这些页面不显示点数（小程序规范明确“前端不显示积分”；PC 剪辑/封面/背景音乐弹窗里也没有点数显示）。
• 后台按任务扣点，默认价格（后台可改，以「点数规则」后台为准）：背景音乐任务 async_video_bgm 默认 10 点；标题与话题 sync_copy_title_tags 默认 3 点；旧版画中画 async_pip 25 点、旧版特效字幕 12 点、旧版渲染 async_generate_render 30 点、LUT 10 点（9.0 已不再触发）。
• 风格剪辑 / 画中画（HyperFrames）走网关统一提交逻辑“计费、幂等”，但默认价格表里没有 hyperframes-render，具体扣多少见「待技术确认」。封面生成接口不在网关同步计费规则里，推测不单独扣点，待确认。

剪辑气口（去停顿 / 去卡顿）#

在哪里

• PC：数字人步骤，选「视频数字人」时出现开关「剪辑气口 — 自动剪掉多余的停顿和呼吸声」；一键成片弹窗「数字人」区也有「剪辑气口」勾选。
• 小程序：一键成片面板「剪辑气口 — 自动剪掉多余的停顿和呼吸声」；数字人步骤同样有（avatar 组详述）。
• 图片数字人没有这个开关（图片数字人改为“换背景/换服装”）。

能做什么

AI 检测口播里的停顿、换气，把空白片段剪掉，视频更紧凑。默认开启。 在一键成片弹窗里取消勾选时，会弹出确认框「确认取消剪辑气口功能」，说明“取消此功能后，生成的视频将保留所有原始停顿，可能影响视频的流畅度和观看体验。”，按钮「保留此功能」/确认取消。数字人步骤里的开关直接切换，不弹确认。

后台处理

作为参数 silence_check 随数字人生成任务一起提交，由 在生成数字人视频后做静音剪辑。不单独计费、不单独出任务，耗时计入数字人生成。

常见问题

• “视频里还有停顿/卡顿”：先确认生成时开关是否开着（草稿里会记）；关着要重新生成数字人。
• “声音和嘴型被剪得不连贯”：剪辑气口会剪掉停顿，个别换气处可能显得紧；可关闭开关重新生成数字人对比。

剪辑出片流程与进度（剪辑手法出片的周边行为）#

剪辑手法的选择、样片预览由 clipstyle 组说明，这里只写出片过程中客户会看到的进度、限制和失败。

在哪里 / 怎么操作

PC「智能剪辑」页：标题「用大V的视频风格，帮你剪视频。」，在风格墙选一种手法 → 点「开始剪辑」（按钮下小字显示「已选 No.xx · 手法名」或「先在上方选一种剪辑手法」）。没选就点会提示「先选一种剪辑手法」。 小程序同名页面，按钮「开始剪辑」，出片后「重新剪辑」/「生成标题封面」。

出片顺序（后台两个任务串行）

1. 先检查数字人视频是否竖屏；横屏弹窗「暂不支持宽屏视频，请上传竖屏视频」。探测最多等 15 秒，探测失败不拦截。
2. 若已有下游结果（成片、封面等），先弹确认：「重新生成风格剪辑将清除已生成的…，是否继续？」。
3. 随机挑一首当前曲库里能播放的背景音乐（每次出片都重新随机）；曲库没有可用曲目时提示「当前背景音乐不可用，本次将继续生成无 BGM 成片」。
4. 提交风格剪辑任务（HyperFrames）→ 每 3 秒查一次进度（首次等 2 秒），前端没有总超时，一直等到成功/失败。
5. 剪好后自动加背景音乐（见「背景音乐」）。
6. 完成后显示 100% 停 1 秒再关遮罩，进入成片页「成片剪好了，看看效果吧。」。

进度遮罩文案（客户截图对照）

• 标题：首次剪辑「正在剪辑」，编辑后重渲染「视频修改中」，只加音乐「正在添加背景音乐」，画中画「正在插入画中画」。副标题写「No.04 · 手法名 · 分类」/「共 N 处修改」/「更换背景音乐」/「N 段画中画 · 曲名」。
• 排队时：「正在准备风格剪辑资源」/「正在准备混音资源」/「正在准备画中画资源」。
• 剪辑阶段按进度依次显示：正在载入口播视频与风格模板 → 正在解析语音节奏与字幕时间轴 → 正在编排分镜结构与转场节奏 → 正在适配画面素材与版式布局 → 正在生成字幕花字与动态效果 → 正在合成画面层次与镜头运动 → 正在逐帧渲染风格化画面 → 正在校准字幕与音画同步 → 正在编码输出风格剪辑成片。
• 混音阶段：正在分析视频情绪与剪辑节奏 → 正在裁切配乐并适配视频时长 → 正在平衡人声与配乐音量 → 正在完成混音并导出成片。
• 遮罩上的「取消任务」按钮只在旧版任务/草稿恢复时出现（「取消恢复」/「取消任务」）。

完成提示（右上角通知）

「智能剪辑成功！」；剪好但没配上音乐时标题「部分完成」：「成片已生成，背景音乐未添加」。

限制

• 只支持竖屏口播视频（见上）。
• 渲染服务限制：口播视频 ≤300 秒、≤2GB（`出片服务/）。
• 同一时间只能跑一个剪辑任务：「风格剪辑正在生成，请勿重复提交」。

耗时

前端不限时；渲染卡住 3 分钟服务端会自动重跑渲染、可重试错误自动重试一次（出片服务/,513）。具体时长与视频长度相关，见 clipstyle 组。

背景音乐（选择 / 上传 / 音量 / 更换 / 去掉）#

在哪里

• 剪辑出片时：自动随机配一首，不需要选（「背景音乐每次随机搭配」）。
• 成片页：「换一首背景音乐」/「加一首背景音乐」按钮（没有可编辑工程的成片显示这个）；剪辑手法成片则在「我要编辑」→ 编辑成片的「背景音乐」页签里换。
• 不剪辑：剪辑页底部「不剪辑，直接用口播视频」→ 弹窗「背景音乐」页签。
• 小程序：成片页「换背景音乐」→ 底部面板「背景音乐」；「不剪辑」是整页。

能做什么、怎么操作（PC 弹窗）

• 弹窗标题「选择背景音乐」或「不剪辑，直接用口播视频」，说明「保留原片画面，只混一条背景音乐」/「画中画和背景音乐都可以不加」。
• 选项：「不加背景音乐」（保留原片声音，之后也能在成片页添加）；曲库列表（显示为「音乐 01」「音乐 02」…，自己上传的显示名字/「我的音乐」，点 ▶ 试听）；「上传我的音乐」；音量 + / −。
• 曲目旁状态：「试听中」「已选」「当前使用」「我的音乐」。
• 确认按钮文案随选择变化：「开始添加背景音乐」「更换背景音乐」「添加背景音乐」「使用原片」「开始生成」「开始插入画中画」。
• 自己上传的音乐可删除：确认框「删除背景音乐 — 删除「xx」后，曲库里不再保留这首音乐。」。系统内置曲目不能删。
• 编辑成片里点喇叭可「关闭背景音乐」，提示「已关闭背景音乐，确认修改后生效」。

限制与规则

• 音量：10%–100%，每次 ±10%，默认 20%。
• 上传格式：客户端允许 mp3、wav、m4a、aac，提示「只支持 mp3、wav、m4a、aac 格式的音乐」。注意：服务端只接受 .mp3 .wav .flac .m4a 且文件类型必须是音频，aac 会被拒绝「不支持的音频格式」。
• 名字最长 24 字，和曲库重名时自动改名；小程序重名加「（我的）」。
• 上传文件大小：客户端/服务端未见明确上限，受网关上传超时影响（待确认）。
• 上传的音乐只有本人可见（is_public=0）。
• 小程序上传音乐只能从微信聊天记录里的文件选（uni.chooseMessageFile），不能从手机文件夹直接选。
• 只换背景音乐不需要重新剪辑，在“无背景音乐版成片”上重新混音。
• 「换一首」不指定曲目时随机换一首，并尽量避开当前这首。
• 换音乐会清除已生成的封面等下游产物，先弹确认「更换背景音乐将清除已生成的…，是否继续？」。

后台处理

客户端 POST （视频地址 + 曲目 id/地址 + 音量）→ 校验登录、解析曲目地址 → 提交到 queue-manager 的video-bgm队列 → 的 worker 用 FFmpeg 混音、上传 OSS → 客户端每 3 秒查一次bgm/status`。单步 FFmpeg 超时 600 秒，单机最多同时处理 3 个。一般十几秒到一两分钟（以视频长度和排队为准，代码无固定值）。

小程序差异

• 小程序轮询有总次数上限，超过后报「背景音乐任务处理超时」；失败状态会自动重试，连续 5 次失败才报「BGM生成失败」。
• 小程序面板按钮：「完成」「去掉背景音乐」「按新音量重新混音」「换成这首」；选项「使用我的音乐 — 存进我的音乐，下次也能用」「无背景音乐 — 只保留人声」。

常见问题

• 「暂时没有可用的背景音乐」：曲库接口没取到/曲目都没有播放地址。点「重新加载」；仍不行转技术（曲库服务或 OSS 问题）。
• 上传 aac 后报「不支持的音频格式」：让客户转成 mp3 再传（客户端放行了 aac，但服务端不收）。
• 「上传成功，曲库刷新较慢，请重新打开弹窗选择」：上传成功但列表 8 秒内没刷出来，关掉弹窗重开即可。
• 「后台实际使用的BGM与当前选择不一致，请刷新BGM列表后重试」：曲库里的曲目已被换/删，刷新后重选。
• 剪辑成功但音乐没加上：成片照常保留（无背景音乐版），可在成片页再点「加一首背景音乐」。

画中画（自定义画中画，9.0 新版）#

在哪里

• PC：智能剪辑页底部「不剪辑，直接用口播视频」→ 弹窗切到「画中画」页签。
• 小程序：「不剪辑，直接用口播视频」整页 → 「画中画」页签。
• 剪辑手法成片不能插画中画；画中画只用于“不剪辑”的口播原片（`出片服务/）。

怎么操作

1. 打开画中画页签，左边「我的素材」自动加载，右边「口播句子」自动识别（「正在识别口播里的句子…视频越长等得越久，可以先在左边选素材」）。
2. 在左边选一个素材（或上传），再点右边的句子把素材放进去；连着的句子放同一个素材会合成一段；再点一次取消。
3. 可同时选背景音乐（或不加），点「开始生成」/「开始插入画中画」。
4. 出片：普通逐句字幕 + 画中画一次出片，再按选择混背景音乐。成片页标题「画中画加好了，看看效果吧。」。

规则与限制

• 画中画全屏铺满（1080×1920，比例不同居中裁切），盖住口播人物，字幕仍显示在上面；视频素材不带声音（出片服务/,440）。
• 视频素材比这段话短→播完停在最后一帧/循环；比这段话长→只用前面一段（客户端提示「视频比这段话短，播完停在最后一帧」「视频比这段话长，只用前 X 秒」）。
• 最多 20 段，提示「最多放 20 段画中画」。
• 上传限制（客户端，产品 11-03 定）：图片 jpg/png/webp ≤10MB；视频 mp4/mov ≤300MB 且 ≤15 秒。注意服务端默认配置是图片 ≤3MB、视频 ≤100MB、0.5–15 秒，若生产未改配置，3–10MB 图片或 100–300MB 视频会在上传时被服务端拒绝（见待确认）。
• 口播视频换过（重新生成数字人）后，要关掉弹窗重新打开画中画，否则提示「口播视频已经变了，请关掉弹窗重新打开画中画」。
• 识别结果和放好的素材不保存，关掉弹窗/页面要重新放（小程序关页提示「已放的 N 段画中画不会保存，关掉就要重新放。」）。
• 句子识别接口超时 300 秒，35 秒视频约 5 秒返回（`出片服务/）。

后台处理

句子识别：出片：（plainSubtitles: true + 句子 + pip 列表），均由 HyperFrames 渲染服务处理，进度查询同剪辑手法。旧版 只提供“我的素材”的存取。

常见问题

• 「画中画素材下载失败，换个素材再试」：渲染机下载不到素材。换素材或重新上传。
• 成片里某几句没有画中画：服务端遇到打不开/损坏的素材会跳过那一段、任务照常成功（记 PIP_SKIPPED 警告），9.0 客户端不提示这个警告（出片服务/,513；客户端只处理 layoutWarnings）。让客户换该素材重新出片。
• 「画中画已加好，背景音乐添加失败: …」：画中画成片已保留，可在成片页再加音乐。
• 「句子没识别出来」/「语音识别失败，请稍后重试」：点「重新识别」；多次失败转技术。

素材库（我的素材）#

在哪里

• 画中画页签左侧「我的素材」。
• 编辑成片里替换图片/视频时弹出「替换素材 — 点一下就替换」。
• 两处共用同一个素材库：「上传的素材会存进素材库，画中画也能用。」。
• 小程序：画中画面板「我的素材」、编辑成片的素材面板。小程序上传从相册或拍摄选。

能做什么

• 按「全部 / 视频 / 图片」筛选；上传（显示「上传中 xx%」）；删除（确认框「删除素材 — 删除…后，素材库里不再保留它（已放进的 N 句也会去掉 / 用到它的片段会换回原素材）。」）。
• 编辑成片替换时，不符合要求的素材鼠标悬停显示原因，不能选；上传后不符合时提示「已存进素材库，但…」。
• 编辑成片里换视频：任意长短都可，长了只用开头、短了循环，去掉声音，≤200MB（`出片服务/）。

限制

同「画中画」上传限制（客户端图片 10MB、视频 300MB/15 秒；服务端默认 3MB/100MB，支持图片 .jpg .jpeg .png .gif .webp .bmp，视频 .mp4 .mov .avi .mkv .flv .wmv）。

后台处理

（列表/删除）、（上传）→ →：存 OSS、记录素材。

常见问题

• 「素材列表没拿到」→ 点「重新加载」。
• 上传报「图片文件过大: x.xxMB，最大允许 3.0MB」/「视频文件过大…」/「视频时长过长…」：服务端限制比客户端说明更严，按服务端提示压缩后再传，并反馈技术。
• 「素材已上传，但接口没有返回公网地址」：上传成功但没拿到地址，重新打开再选；反复出现转技术。

编辑成片中的背景音乐与素材替换（边界说明）#

剪辑手法成片页有「我要编辑」，进入「编辑成片」可改文字、拖动、换图片/视频素材、换背景音乐（clipstyle 组详述文字和拖拽）。本组相关要点：

• 可编辑工程出片后只保留 1 小时，过期提示「可编辑工程已过期（出片后保留 1 小时），请重新生成风格剪辑后再编辑」。
• 刚出片时工程还在准备：「可编辑工程还在准备，请稍后再打开编辑」。
• 只改背景音乐不重新渲染，只重新混音；改了文字/素材会重新渲染，并清除已生成封面（小程序提示「保存修改会重新生成成片，已生成的封面将被清除，是否继续？」`/）。
• 编辑里上传的「我的音乐」只用在这条视频（PC 注释“只用在这条视频，不进曲库”），但实际仍调用同一个上传接口，见待确认。
• 返回时有未保存修改：「返回后本次修改不会保存，确定返回成片？」按钮「放弃并返回」/「继续编辑」。
• 小程序编辑页是单独页面，入口成片页「我要编辑」。

成片预览#

• PC：成片页右侧 9:16 播放器，左上标「成片」，右上「下载」按钮；剪辑页右上「上次成片 — 手法名 · 点击查看」可回到上次成片。成片页「换种剪辑手法」回到风格墙。
• 小程序：成片页内嵌播放，点开全屏播放页 （/on 子包）。播放失败提示「成片暂时无法播放，请稍后重试」。
• 发布页也会再展示一次封面和成片（见「发布」）。

标题与封面#

在哪里

• PC：剪辑成片页点「生成标题封面」进入「标题与封面。」页。
• 小程序：同名步骤。

01 标题与话题

• 输入框「写下标题和话题，或让 AI 帮你写」，第一行是标题，后面写 #话题。
• 「生成标题」/「换一个」（小程序「重新生成」）调用 AI 生成。要求文案 ≥10 字，否则「文案不能少于10个字」。按次扣点（默认 3 点，见总览）。

02 封面：两种方式（页签「风格选择」/「自定义封面」）

风格选择（模板封面）

1. 点一张风格卡片，或「更多风格」看全部；不选则随机挑一个。
2. 点「生成封面」：系统先截取数字人视频的第一帧作为底图（注意不是剪辑后的成片），再把标题（话题 # 之前的文字）和模板交给 AI 画封面。
3. 生成后弹出「封面已生成」，可「下载封面」「前往发布」。

• 两次生成间隔至少 5 秒，否则「请N秒后生成」（小程序同 `/）。
• 接口超时 360 秒；遮罩进度条是模拟进度（每 200ms 逼近 95%），成功跳 100%。

自定义封面（人物定制）

1. 人物图片：默认用当前数字人形象，可「上传人物图片」/「更换图片」（建议正脸半身照）；图片 ≤20MB，必须是图片文件。
2. 「背景与风格」描述至少 4 个字，例如「暖色台灯下的书房，柔和侧光，电影感」。
3. 需要已有标题。点「生成封面」，生成后直接作为发布用封面。

• 输出固定 1152×1536（3:4）竖图。

后台处理

• 截帧：。
• 模板封面：按配置依次尝试多家生图服务商（默认 qwen → gpt → xlinks），一家失败自动换下一家，最坏耗时为各家之和；结果存 OSS。
• 人物定制封面：。
• 网关等待上限默认 900 秒，客户端 360 秒。

小程序差异

• 小程序截帧源依次取：数字人视频 → 成片 → …；进度条「正在生成封面」。
• 人物图片按钮「上传图片」「用当前数字人形象」。

常见问题

• 「获取数字人视频第一帧失败，无法生成标题封面。」：数字人视频地址失效或截帧服务异常；重新生成数字人或稍后再试，反复失败转技术。
• 「内容安全校验未通过」：标题或人物图片被生图服务判为不合规，改标题/换图片。
• 「模型调用繁忙，请稍后重试」：生图服务限流，过几分钟再试。
• 封面里人物和成片不一样：模板封面用的是数字人原片第一帧，属正常。
• 换配音/数字人/剪辑后封面被清空：上游变了下游会清除，需重新生成封面。

一键成片（一键产出视频）#

在哪里

• PC：文案预览页「一键产出视频」，弹窗标题「这篇文案，直接做成视频」。
• 小程序：底部面板「一键成片 — 选好这三样，剩下的交给 AI。」。

需要客户选什么

• 配音：音色、语速、情绪。
• 数字人：图片数字人 / 视频数字人、形象；视频数字人可勾「剪辑气口」「添加美颜」。
• 剪辑：剪辑手法（背景音乐随机搭配）。
• 底部「完成后停在发布页，确认后再发布」「取消」「开始生成」；小程序「开始一键成片」，没选会提示「先选一个音色」「先选一个形象」「先选一种剪辑手法」。

流程

依次：配音 → 数字人 → 剪辑（剪辑手法 + 随机背景音乐）→ 标题与封面 → 停在发布页。确认时就挑好一首背景音乐，全程用这一首。完成提示「视频生成完成，请在发布步骤复制发布信息并下载素材」。

• 标题封面这一步失败不阻断流程（至少标题或封面有一个成功即可）。
• 点数：分别按配音、数字人、背景音乐、标题等各自任务扣点，一键本身不额外收费（客户端未见单独计费；待确认）。

后台处理

PC 与小程序都是客户端按顺序调用各步骤接口，不经过后台的 （该服务 9.0 客户端未调用， 描述的“文案/TTS/数字人/LUT/PIP/字幕/BGM/总装”编排属旧方案）。因此中途关掉客户端/小程序会中断，重新打开靠草稿续跑（见「草稿恢复」）。

常见问题

• 「请先生成或填写文案内容」：没有文案不能一键。
• 「已取消一键生成流程」：客户在遮罩上取消了。
• 小程序「一键生成已中断，请重新生成」/「一键任务配置已失效，请重新生成」：重新进入后无法续跑，需重新一键。

草稿恢复（编辑历史）#

存在哪里、何时保存

• PC：保存在本机客户端本地存储（键 intelligent_agent_draft、当前页 intelligent_agent_current_page），每次有改动自动保存，没有过期时间。
• 小程序：保存在微信小程序本地缓存（键 intelligent_agent_workflow_draft_v1）。
• 草稿不在服务器上：换电脑、重装客户端、清缓存、换手机/删小程序都会丢；PC 和小程序之间不同步。

恢复时客户看到什么

• 打开智能体自动恢复，右上提示「编辑历史已恢复」；读取失败提示「恢复编辑历史失败」并清空草稿。
• 上次关闭时还在跑的任务（剪辑、背景音乐、画中画、封面）会自动接着查进度：「正在恢复背景音乐任务...」等；遮罩上有「取消恢复」，取消后提示「已取消恢复当前任务，并清空对应草稿任务ID」。
• 一键成片中断的会从中断阶段继续。
• 旧版本草稿：调色任务不再恢复；旧版单独字幕任务提示「旧版字幕任务无法继续，请在风格剪辑里重新生成」；8.x 的剪辑任务仍可查 / effect-packaging-v2 进度恢复。

清空草稿

• PC 发布页「清空草稿，从头再来」/工作台清空：确认框「确定要清空当前正在编辑的内容吗？此操作不可恢复。」→「确定清空」，成功「已清空」。
• 小程序发布页「清空草稿，从头再来」→「确认操作 — 此操作将重置所有已生成的信息，是否继续？」。

常见问题

• “之前做的视频不见了”：草稿只存本机，只能恢复最近一条工作流；之前下载过的成片在客户电脑下载目录里。成片在 OSS 上一般仍可访问，但客户端没有作品列表（待确认是否有后台可查）。
• 恢复后提示某任务“已被服务器取消/失败”：该步骤需重新生成。

下载导出#

PC

• 下载入口：成片页播放器右上「下载」、封面结果「下载封面」、发布页「确认无误，复制信息发布」（同时下载封面和成片）。
• 弹出系统保存对话框（「保存最终成片」「保存 BGM 视频」等，文件类型 MP4），完成后通知「视频下载完成 — 文件已保存至：…」并带「打开文件所在位置」。
• 同一个视频再次下载会提醒「重复下载提醒 — xx已下载过，继续下载会产生重复文件。是否仍要下载？」。
• 客户端下载失败会退回浏览器方式下载，此时提示「视频下载已开始」，在浏览器下载记录里看。
• 文件名取视频地址里的文件名。

小程序

• 保存到手机相册，需要「保存到相册」权限：「权限提示 — 需要开启“保存到相册”权限，才能将封面和视频保存到相册，是否前往授权？」。
• 视频 >180MB 不在小程序内下载，提示「为保证视频清晰度，文件较大，因平台限制超过 200MB 的文件无法直接下载，请复制链接至浏览器下载，感谢理解！」（代码阈值 180MB，文案写 200MB）。
• 下载 30 秒无进展判超时「下载超时，请重试」。

常见问题

• PC「视频下载失败，请稍后重试」：网络或链接失效；重试，或在成片页播放确认视频能播。
• 小程序「下载域名未配置」：小程序后台没把视频/图片域名加到 downloadFile 合法域名，属配置问题，转技术；临时让客户「复制链接」到浏览器下载。
• 小程序保存相册失败：检查是否拒绝了相册权限（设置里开启）。

发布（复制信息发布）#

在哪里 / 能做什么

• PC：发布页「发布前，再确认一遍。」展示封面（9:16）、标题、话题、成片，按钮「修改标题与封面」「确认无误，复制信息发布」「清空草稿，从头再来」。
• 点「确认无误，复制信息发布」：复制标题和话题到剪贴板 → 下载封面 → 下载成片 → 弹窗「复制信息去发布」：已为你准备好发布文案和素材…现在可以前往对应平台发布。
• 9.0 没有一键发布到抖音/视频号等平台的功能，客户需自己到平台上传。
• 小程序：同样「确认无误，复制信息发布」，复制标题（「标题已复制」）并把封面和视频保存到相册，完成「已复制视频信息并完成下载，可前往发布。」。没有成片时显示「还没有成片 — 先完成前面的步骤，生成最终视频后再来发布。」「去剪辑」。

下载的是哪条视频

最终成片（有背景音乐优先，否则剪辑成片，否则数字人视频）。

后台编排：一条成片怎么拆成父任务 / 子任务#

9.0 实际情况（客户最常遇到）

9.0 的一条成片在后台是几个独立任务按顺序串起来，由客户端负责串联，没有一个统一的“父任务”：

1. 配音任务（tts）→ 2. 数字人任务（digital-human，含剪辑气口）→ 3. 剪辑任务（任务号形如 hf_年月日时分秒_8位字母数字）或画中画任务（同为 HyperFrames）→ 4. 背景音乐任务（video-bgm）→ 5. 封面（同步接口，不排队）。

• 任意一步失败，前面的结果都保留，只需重做失败的那一步（如“成片已生成，背景音乐未添加”）。
• 客服排查时请客户提供：账号手机号、出问题的时间、截图（含遮罩副标题/错误文字），技术按时间在任务后台查 hf_ 剪辑任务号和 BGM 任务号。

旧版（8.x）父/子任务编排：「effect-packaging-v2」

9.0 客户端不再新建这种任务，只在旧草稿续跑时查询状态；但后台和管理后台仍有这类任务，技术排障会提到，客服了解即可（1-40`）：

• 父任务：一条特效包装成片，状态（status）为 queued 排队 / processing 处理中 / completed 完成 / failed 失败 / cancelled 已取消；阶段（stage）依次 created 已创建 → preparing 准备 → material_generating 生成素材 → composing 拼装 → rendering 渲染 →。
• 子任务（step）：
• prepare:subtitle 识别口播并生成字幕/特效字幕（自己）
• prepare:template-plan 规划模板
• material:pip:slot:N 每段画中画素材（调用）
• material:bgm 背景音乐、material:lut 调色（调用，可提前并行）
• compose:manifest 拼装渲染清单
• render:submit / render:wait 交给 渲染字幕特效层
• render:finalize:submit / render:finalize:wait 交给 做最终总装（叠加音乐等）。
• 子任务状态：完成 / 失败 / 取消 / skipped 跳过 / waiting_callback 等待下游回调。
• 失败传播：任一阻塞性子任务失败，父任务就判失败；有子任务被取消，父任务判取消。同一请求 120 秒内重复提交会复用同一任务。
• 管理员可在后台取消 effect-packaging-v2 父任务。

渲染服务对客户的影响

• 9.0 新成片全部由 HyperFrames 渲染（本地 Mac 渲染机集群，clipstyle 组详述）：队列满时提交会被拒（429 QUEUE_FULL），客户看到提交失败，稍后再试；渲染卡住 3 分钟自动重跑（出片服务/,509,561）。
• ****（GTE 模式出片服务，Python 编排 + 的 Rust/Skia GPU 渲染引擎 + FFmpeg 合成）是 8.x「风格剪辑」的渲染器，9.0 只用于恢复旧草稿里的未完成任务。若 服务下线，旧草稿续跑会失败并提示重新生成。
• ****（Remotion 字幕特效渲染）只被 旧链路调用，9.0 客户端不直接接触。
• 渲染输出固定 1080×1920 竖屏（`出片服务/；旧链路同 RENDER_QUALITY_PROFILE 说明）。

近期变更（剪辑包装 / 封面 / 发布）#

待技术确认（剪辑包装 / 封面 / 发布）#

1. HyperFrames 剪辑 / 画中画 / 编辑重渲染的扣点：网关注释说复用统一提交逻辑“计费”，但默认价格表无 hyperframes-render，实际每次扣多少点？编辑后重渲染是否再扣？
2. 素材上传限制前后端不一致：客户端写图片 ≤10MB、视频 ≤300MB； 默认配置图片 ≤3MB、视频 ≤100MB。生产是否已通过环境变量调大？
3. 背景音乐 aac：客户端允许 aac，服务端只收 mp3/wav/flac/m4a，aac 会报「不支持的音频格式」，是否需要改一边？自定义音乐上传大小上限是多少？
4. 画中画 PIP_SKIPPED：素材打不开时服务端静默跳过该段，客户端不提示，是否需要加提示？
5. 剪辑进行中取消：PC 遮罩“取消任务”对 HyperFrames 任务调用的是旧 effect-packaging-v2 取消接口，服务端剪辑任务是否真的被取消、点数是否退回？
6. 编辑成片里上传的「我的音乐」：注释说“只用在这条视频，不进曲库”，但调用的是曲库上传接口，实际是否会出现在曲库？
7. 封面是否扣点：thumbnail 接口不在网关同步计费规则里，是否免费？
8. 作品/历史成片：9.0 客户端没有作品列表，客户丢草稿后成片能否由后台按账号找回？成片 OSS 链接保留多久？
9. 小程序大文件阈值代码为 180MB，弹窗文案写 200MB，以哪个为准对外说明？
10. 一键成片在中途失败时已扣的点数（配音、数字人）是否退还。