ai/docs/work-sync/05_AI流水线/AI_PIPELINE_V1.md

AI 流水线与 Provider 设计 V1

文档状态：当前有效
基线日期：2026-07-15
目的：说明当前 AI 请求如何选择、执行、记录、回退和进入业务资产。

1. 设计目标

• 业务不直接绑定单一厂商 SDK。
• 每次调用可解释、可审计、可计费、可重试。
• 同步和异步 Provider 使用统一日志与业务结果。
• 用户指定的模型和参数不被静默替换。
• Prompt 模板、实验请求和原样透传有明确边界。
• AI 失败不会破坏已经确认的业务资产。

2. Provider 类型

当前目录覆盖：

• TextProvider
• NovelProvider
• ImageProvider
• VideoProvider
• VoiceProvider
• MusicProvider
• EmbeddingProvider
• ModerationProvider
• LipSyncProvider（抽象存在，真实配置当前关闭）

数据库当前有 112 个 Provider 配置，其中真实配置 101 个、启用 64 个；Mock 配置 11 个、启用 10 个。全局 AI_PROVIDER_MODE 当前仍为 mock，但业务显式选择真实 Provider 时会产生真实调用。

3. 调用选择

一次调用可能同时受到以下输入影响：

1. 用户明确选择的 provider_code。
2. 项目级模型偏好。
3. 用户级模型偏好。
4. 业务模块默认 Provider。
5. Provider 启停、优先级、能力和成本限制。
6. AI Router 的业务评分与回退规则。

当前 AI Router 主要用于真人视频，不是全平台统一路由。后续必须固定一套明确优先级，并在调用详情展示：请求选择、路由原因、实际 Provider、实际模型和回退链。

4. 请求生命周期

flowchart LR
  Input[业务输入] --> Build[构建请求]
  Build --> Preflight[参数/能力/素材 URL/成本预检]
  Preflight --> Config[解析 ProviderConfig]
  Config --> Submit[同步执行或异步提交]
  Submit --> Log[ProviderLog]
  Log --> Poll[异步轮询/回调]
  Poll --> Normalize[结果归一]
  Normalize --> Asset[Asset / VideoClip / 文本版本]
  Normalize --> QC[质量评估]
  QC --> Pass{通过?}
  Pass -- 否 --> Retry[同模型重试/回退/人工介入]
  Pass -- 是 --> Done[业务确认]

4.1 请求构建

请求快照至少保存：

• 业务类型和关联项目/分镜/角色。
• 原始输入与最终 Prompt。
• 公共模板版本和是否旁路模板。
• 模型、比例、时长、分辨率、种子等参数。
• 参考素材的资产 ID、顺序和用途。
• 预估成本和用户确认条件。

4.2 Preflight

提交前检查：

• Provider 是否启用且类型匹配。
• 参数是否在模型能力范围。
• 参考图数量、格式、大小和顺序。
• 外部 Provider 能否访问临时素材 URL。
• 账户额度和项目成本上限。
• 原生音频、首尾帧、多图参考等能力是否真实支持。
• 实验请求是否要求禁止模板注入。
• 新生产任务的画幅是否为唯一允许值16:9。
• S+ Kling Omni 镜头的每个出场角色是否绑定质检分不低于90的已审批视频角色元素。
• Omni 的图片、视频与元素组合是否满足数量和互斥限制；无参考视频时图片与元素合计不超过7。

4.3 结果归一

不同 Provider 的任务 ID、状态、URL、用量和错误格式必须转换为平台统一结构，再写入业务资产。临时 URL 不是最终资产，需下载到私有存储并保存来源信息。

5. Prompt 管理

Prompt 分为四层：

1. 业务事实：剧本、角色、场景、动作和台词。
2. 公共质量模板：画质、一致性、可用性和负向约束。
3. Provider 适配：模型特有参数与表达。
4. 本次覆盖：用户人工修改或严格原样提交。

优先级为“本次明确覆盖 > 已确认业务事实 > 公共模板 > Provider 默认”。公共模板不得改变台词、人物、镜头时长或参考图集合。

人物三视图已具备“主锚点参考”和“本次唯一角色描述覆盖”两种模式，并将视觉质检问题沉淀为后续优化经验。经验只能以版本化、可审阅方式进入公共模板，避免单个角色的专用词污染全局。

Kling 正式镜头不再重复大段描述已锁定角色五官。平台从不可变 Generation Plan 读取 CharacterProviderBinding 快照，把真实 element_id 写入 element_list，再在 Prompt 中使用与数组顺序一致的 <<<element_n>>> 标记。角色元素控制身份和绑定声线，镜头 Prompt 控制本次动作、表演、空间、台词与摄影。

S+ 结构化写路径新增阶段 Prompt Builder。Source Analyst、Adaptation Showrunner、Episode Planner 的公共模板与项目数据分离，运行时只注入不可变来源快照、已确认父合同和上一集状态。Writer 输出完整合同；Reviewer 只输出问题与结构化修复差异，不静默重写正文。用户可以在调用 Provider 前预览最终阶段 Prompt；Phase 2 默认不提供一键付费生成入口。

6. 任务与队列

6.1 队列

novel_queue / parse_queue / story_queue / character_queue
episode_queue / script_queue / storyboard_queue / image_queue
audio_queue / subtitle_queue / video_queue / qc_queue
review_queue / analytics_queue

6.2 平台任务状态

pending / running / success / failed / retrying
cancelled / manual_required / skipped

数据库中仍有历史 completed，需要迁移或兼容，不应继续产生新值。

6.3 执行模式

Worker 消费 BullMQ 后，通过受密钥保护的内部 API 委托 backend 执行。这样可复用业务逻辑，但也意味着 backend 必须能承受 Worker 回调并保持幂等。

6.4 已知覆盖缺口

以下任务在通用 Worker 映射中没有 Provider 执行器，可能被标记为 skipped：

• long_memory_generate
• subtitle_generate
• live_action_keyframe_generate
• live_action_video_render
• analytics_event

部分能力目前由同步 Service 完成，因此应选择：补齐 Worker 执行器，或从异步任务目录移除并明确同步语义。video_render 当前映射到 VideoProvider，与 FFmpeg 成片合成的命名也需要拆分。

7. 重试与回退

重试策略按错误性质区分：

错误	处理
参数/素材不可用	不盲目重试，返回可修复原因
限流/临时网络故障	指数退避重试
异步任务超时	先核对外部任务，避免重复扣费
质量不达标	同模型定向重试，必要时回退其他模型
多次失败	manual_required，保留全部候选和日志

回退不可静默发生。UI 应展示实际使用模型和回退原因。

8. 成本与额度

• ProviderConfig 保存成本规则和能力配置。
• ProviderLog 保存本次调用的估算/实际成本、耗时和状态。
• QuotaAccount、QuotaLog 支持冻结、释放和扣减。
• 数据库历史 cost_actual 可能混有不同币种/规则，只能技术对账，不能直接作为财务总额。
• 真实支付仍为 mock，不能把订单模型描述成生产支付闭环。

提交付费任务建议采用：

预估 -> 冻结额度 -> 执行 -> 按实际结算 -> 释放差额

异步任务重试必须复用或核验外部任务 ID，避免重复扣费。

9. 日志与审计

每次 AI 调用应能回答：

• 谁、在哪个项目、为了哪个业务对象调用？
• 用户请求了什么 Provider/模型？
• 系统为何选择实际 Provider/模型？
• 最终提交了什么参数和参考素材？
• 是否注入模板、是否回退、重试了几次？
• 外部任务 ID、耗时、状态和错误是什么？
• 产生了哪些资产，哪一个被选择？
• 估算成本、实际成本和额度变化是什么？

API Key、JWT、数据库密码和临时签名参数不能进入可下载日志或 Work 文档。

10. 新 Provider 接入清单

1. 明确能力类型、模型和区域。
2. 定义请求 DTO、参数范围和默认值。
3. 实现鉴权、提交、轮询/回调、取消和结果归一。
4. 处理文本、二进制和临时 URL 输入。
5. 定义成本规则和币种。
6. 增加 preflight 与错误分类。
7. 增加 mock、单元测试和至少一次真实小额冒烟。
8. 在 Provider Lab 验证参数透传。
9. 验证日志不泄露密钥。
10. 更新本文件、CHANGELOG 和项目状态文档。

11. 当前优先级

P0

• 修复 Provider/Seedance 相关测试与真实策略不一致。
• 对齐运行进程与最新构建。

P1

• 固化模型选择优先级和路由解释。
• 补齐素材 URL preflight。
• 清理历史 running/failed 日志和任务积压。
• 补齐队列执行映射与任务命名。

P2

• 将 AI Router 扩展为可选的平台统一入口。
• 建立 Provider 契约测试和录制回放测试。
• 统一成本币种和财务口径。