四个入口，一条流水线：如意智影的多入口架构取舍
如意智影同时需要 WebUI、API、CLI 和 Agent Skill。最直接的做法是让每个入口"自己把事情做完"，但这样一来，脚本、配音、字幕、素材和合成规则会被复制四次。
我沿源码重新追了一遍调用链，最后保留的不是四套流水线，而是四种入口语义和一条核心流水线。这篇只讨论这个工程取舍，以及它没有解决什么。
工程场景与决策冲突
WebUI 要响应交互，API 要快速返回任务 ID，CLI 要用退出码服务自动化，Agent Skill 要给智能体一个可重复调用的操作契约。把四者做成同一种调用方式并不合理。
但脚本、音频、字幕、素材和成片的含义不能随入口变化。否则一个字幕修复要改四处，一次默认值调整会产生四种结果。
方案拆解与关键权衡
如意智影把共享边界收敛为：
VideoParams：统一输入和默认值；app.services.task.start：统一任务编排；- 任务状态与制品目录：统一进度、失败阶段和结果引用。
text
WebUI / API / CLI / Skill
↓
VideoParams
↓
task.start
↓
脚本 → 音频 → 字幕 → 素材 → 合成 → 制品这比"所有入口都调用同一个函数"更严格。真正的契约还包括默认值、状态语义和制品结构。
实现链路与最小示例
四个入口首先把输入转换成统一参数，再进入相同编排函数。入口可以异步提交或同步等待，但不改变阶段顺序和结果结构。
WebUI 为什么需要后台执行
Streamlit 交互会触发脚本重运行，长任务不能依赖一次按钮回调活到最后。WebUI 因此只收集参数、提交任务并轮询状态，还要在任务期间锁定运行配置。它解决的是交互一致性，不是视频生成本身。
API 为什么不能等待成片
API 控制器完成校验和登记后就应返回任务 ID。任务管理器在后台调用相同的 task.start。如果控制器开始下载素材或调用 FFmpeg，协议层就变成了第二套业务层。
CLI 为什么是 Agent 的好边界
CLI 能稳定表达文件预检、退出码和 JSON 结果，还能用 stop_at 在脚本、音频或字幕阶段停止。Agent Skill 因此不直接导入内部模块，而是通过子进程复用 CLI，并把最终目标固定到完整视频。
代价也很明确：CLI 契约必须兼容，错误输出必须机器可读，Skill 还要处理进程超时和结果清单缺失。
失败语义必须由核心收敛
多入口最隐蔽的问题是"后台已经崩了，前台仍显示处理中"。核心编排需要在阶段边界写状态，把未预期异常收敛成统一失败，并保留失败阶段。入口只负责翻译：WebUI 显示提示，API 返回状态，CLI 给非零退出码。
没有选择的两条路
第一条是复制四套业务流程。它最容易起步，也最容易漂移。
第二条是让所有入口直接依赖内部 Python 服务。它减少一层调用，却让 Agent、脚本和外部集成绑死内部模块，重构成本更高。
当前方案选择薄适配层：接受少量入口代码，换取核心行为只有一个事实源。
一组可复用的契约测试
不必让四个入口各生成一次完整视频。更经济的测试分三层：
- 入口测试：同一输入能否映射成等价
VideoParams； - 流水线测试：阶段顺序、停止点、失败状态和制品是否正确；
- 跨入口契约测试：默认值、状态枚举和结果结构是否一致。
完整成片测试只保留少量关键路径，避免把外部供应商费用和网络波动带进每次回归。
可复用检查清单
- 多个入口是否提供同一种业务能力？
- 参数默认值是否只有一个事实源？
- 入口是否只做校验、转换和展示？
- 核心编排能否记录阶段、停止和失败？
- 状态与制品结构能否被所有入口解释？
- Agent 是否复用稳定 CLI/API，而不是内部实现？
- 是否有轻量健康检查提前发现 FFmpeg、存储和配置问题？
证据、限制与自动化边界
结论来自 2026-08-21 的如意智影源码、架构文档与测试静态核对，源码快照为 f702ae8a7d37a244786b700f640e0b40fa2a3f2c。本轮没有重新调用付费供应商，也没有完成一次新的全链路成片，因此不能把它写成线上性能或成功率结论。
自动化只复用稳定 CLI/API 契约，不把静态源码核对写成新一次线上成片验收。
收束
如果你也维护 Web、API、CLI 或 Agent 多入口系统，你会优先统一参数、任务状态，还是制品契约？欢迎分享实际踩坑。
发布前门禁
正文已减少背景重复，重点保留工程取舍、实现边界和可复用清单；没有添加未经验证的数据结论或内容实验结论。