AutoClip 简化进度系统（Simple Progress System）实现指南：固定阶段 + 轮询驱动的稳定进度方案

音视频AI 应用后端前端【免费下载链接】autoclipAutoClip : AI-powered video clipping and highlight generation · 一款智能高光提取与剪辑的二创工具项目地址https://gitcode.com/GitHub_Trending/autoc/autoclip点击查看免费下载导读AutoClipAI 智能高光提取与剪辑工具在视频素材下载、AI 字幕生成、语义分析、片段定位、导出封装的整条二创流水线上需要一个既稳定又直观的进度反馈机制。本文以仓库文档 docs/SIMPLE_PROGRESS_SYSTEM.md 为骨架结合backend/services/simple_progress.py、backend/services/simple_pipeline_adapter.py与frontend/src下的 Zustand Store、进度条、项目卡片等源码实现完整讲解这套基于固定阶段 固定权重 HTTP 轮询的简化进度系统你将掌握其设计理念、六阶段权重模型、百分比计算公式、Redis/SQLite 双存储与自动降级机制、三个 REST API、前后端接入方法以及故障处理、性能优化与从旧系统迁移的完整路径。一、设计背景为什么需要一个做笨做稳的进度系统在早期版本的 AutoClip 中进度同步依赖复杂的订阅机制与 WebSocket 推送。WebSocket 虽然实时性强但带来了连接管理、断线重连、消息丢失补偿、多进程广播等一系列运维与调试成本对于进度这种可以接受短暂延迟、不能接受错误的信息来说复杂度与收益并不成正比。简化进度系统Simple Progress System的核心理念是**做笨做稳**不追求毫秒级实时改用前端定时轮询 HTTP API 获取快照天然容忍网络抖动不搞动态阶段树用 6 个固定阶段 固定权重描述整条流水线逻辑一眼可读不依赖常驻连接后端把进度快照写入 Redis或自动降级 SQLite前端随时可以拉取每个阶段只发一次事件整条流水线最多 6 次进度事件把消息量压到最小。这套方案在 docs/SIMPLE_PROGRESS_SYSTEM.md 中被定义为基于做笨做稳理念的简化进度同步系统使用固定阶段 固定权重来驱动进度不再依赖复杂的订阅机制。二、系统架构总览整套系统分为后端与前端两大部分各司其职、依赖单一链路清晰[流水线执行进程] [API Server] [前端浏览器] │ │ │ │ emit_progress() │ │ ├──────────────────────────────► ProgressStore 写入快照 │ │ │ (Redis Hash / SQLite 表) │ │ │ │ │ │ GET /api/v1/simple-progress │ │ │◄──────────────────────────────┤ │ │ /snapshot?project_ids │ │ │ │后端组件组件文件职责核心进度服务backend/services/simple_progress.py阶段定义与权重计算、进度快照存储Redis/SQLite、事件发布、进程内监听器API 接口backend/api/v1/simple_progress.py提供快照批量查询、单个查询、阶段配置查询三个 REST 端点流水线适配器backend/services/simple_pipeline_adapter.py将进度上报接入现有六步流水线自动在阶段切换时发送事件前端组件组件文件职责状态管理frontend/src/stores/useSimpleProgressStore.tsZustand 状态管理、轮询启动/停止、进度数据缓存、终态自动停机进度条组件frontend/src/components/SimpleProgressBar.tsx单个项目进度显示以及批量模式的BatchProgressBar项目卡片frontend/src/components/SimpleProjectCard.tsx卡片内集成进度条、状态标签与开始/重试/查看/删除操作此外frontend/src/pages/SimpleProgressDemo.tsx 提供了一个可直接运行的演示页用模拟数据展示批量进度条与项目卡片组合效果ProjectCard.tsx、UnifiedStatusBar.tsx、HomePage.tsx等既有组件也已接入该 Store 读取进度。三、核心数据模型六阶段定义与权重系统的地基是 backend/services/simple_progress.py 顶部的阶段常量表。六个阶段按视频剪辑流水线的自然顺序排列权重合计正好100STAGES: List[Tuple[str, int]] [ (INGEST, 10), # 下载/就绪 (SUBTITLE, 15), # 字幕/对齐 (ANALYZE, 20), # 语义分析/大纲 (HIGHLIGHT, 25), # 片段定位/打分 (EXPORT, 20), # 导出/封装 (DONE, 10), # 校验/归档 ]源码在加载时将其拆分为两个查找结构供进度计算使用WEIGHTS {name: w for name, w in STAGES} # 阶段名 - 权重 ORDER [name for name, _ in STAGES] # 阶段执行顺序各阶段含义与对应流水线步骤见 backend/services/simple_pipeline_adapter.py阶段权重中文显示名源码STAGE_NAMES对应流水线步骤INGEST10素材准备素材目录创建、LLM 可用性预检SUBTITLE15字幕处理复用已有 SRT或 Whisper 本地自动生成字幕step1_outline大纲提取ANALYZE20内容分析step2_timeline时间线提取、step3_scoring内容评分HIGHLIGHT25片段定位step4_title标题生成、step5_clustering主题聚类EXPORT20视频导出step6_video视频切割封装DONE10处理完成数据同步、收尾归档阶段中文名映射定义在 backend/services/simple_progress.py 的STAGE_NAMES中前端 frontend/src/stores/useSimpleProgressStore.ts 也维护了一份等价的STAGE_DISPLAY_NAMES并为每个阶段配置了主题色STAGE_COLORSINGEST 蓝、SUBTITLE 绿、ANALYZE 橙、HIGHLIGHT 紫、EXPORT 粉、DONE 青供标签和进度条着色。四、进度计算原理compute_percent 详解进度计算是整个系统的数学核心实现在 backend/services/simple_progress.py 的compute_percent函数中def compute_percent(stage: str, subpercent: Optional[float] None) - int: # 累加之前阶段权重 done 0 for s in ORDER: if s stage: break done WEIGHTS[s] # 当前阶段 cur WEIGHTS.get(stage, 0) if subpercent is None: # 阶段切换时显示到当前阶段开始 return min(100, done cur) if stage DONE else min(99, done) else: # 带子进度按权重线性换算 subpercent max(0, min(100, subpercent)) return min(99, done int(cur * subpercent / 100))理解这段代码有三个关键点done是之前所有阶段权重之和遍历ORDER累加到达当前阶段之前的所有阶段权重。例如HIGHLIGHT之前的权重为 10 15 20 45。阶段切换无子进度时语义特殊普通阶段返回min(99, done)即只显示到当前阶段开始点只有DONE阶段返回 100表示整条流水线彻底完成。这是有意为之——避免某个阶段刚开始就显示满了。带子进度时按权重线性换算done int(cur * subpercent / 100)同时subpercent被 clamp 到 0–100结果上限min(99, ...)保证最终完成前不会出现 100%配合第 2 点只有DONE阶段能给出 100%。各阶段百分比速查表阶段权重切换阶段无子进度子进度 25%子进度 50%子进度 100%INGEST1002510SUBTITLE1510131725ANALYZE2025303545HIGHLIGHT2545515770EXPORT2070758090DONE10100929599这个映射关系在测试 backend/tests/test_cli.py 的test_progress_listener_receives_payload中被直接验证该测试断言监听器收到的 payload 中percent sp.compute_percent(ANALYZE, 50)即 35%将事件内容与计算函数绑定为同一事实来源。五、事件格式极简 JSON 负载每个阶段切换或阶段内子进度更新会生成一条统一结构的进度事件。文档给出的事件格式与源码emit_progress构造的 payload 完全一致{ project_id: 46ab50a6-...., stage: HIGHLIGHT, percent: 70, message: 已完成片段定位共 12 段候选, ts: 1640995200 }字段说明字段类型含义project_idstring项目唯一标识stagestring当前阶段名INGEST/SUBTITLE/ANALYZE/HIGHLIGHT/EXPORT/DONEpercentint0–100 的总进度百分比由compute_percent算出messagestring人类可读的进度描述如时间线提取完成、处理失败...tsintUnix 时间戳秒由time.time()生成得益于固定阶段设计整条流水线最多发送 6 次事件每个阶段 1 次DONE阶段可能附带失败消息消息量被压缩到极致。六、存储层Redis 与 SQLite 双实现 自动降级文档描述为Redis 存储但源码实现远比这更稳健backend/services/simple_progress.py 定义了存储抽象基类ProgressStoresave/get/delete/get_many并提供两个具体实现。RedisProgressStore服务端模式的首选存储使用 Redis Hash 保存快照key 为progress:project:{project_id}def save(self, project_id, stage, percent, message, ts): self.r.hset(fprogress:project:{project_id}, mapping{ stage: stage, percent: str(percent), message: message, ts: str(ts) }) # 同时向频道发布事件负载供订阅方如 CLI/MCP实时消费 payload {project_id: project_id, stage: stage, percent: percent, message: message, ts: ts} try: self.r.publish(fprogress:project:{project_id}, json.dumps(payload)) except Exception: passhgetall读取并还原为字典。Redis 连接地址默认取环境变量REDIS_URL缺省为redis://127.0.0.1:6379/0。SqliteProgressStore内置的兜底实现用单表progress_snapshotsproject_id主键、stage、percent、message、ts配合threading.Lock保证线程安全REPLACE INTO实现 upsert并提供基于IN (...)的批量读取get_many。存储选择与自动降级逻辑源码在模块加载时执行一次选择逻辑其优先级设计非常实用Desktop桌面模式强制 SQLite通过 backend/core/desktop_config.py 的is_desktop_mode()判定数据文件位于桌面数据目录下的progress.db。桌面端无需部署 Redis开箱即用Server 模式优先 Redis若redis库已安装且能ping通则使用RedisProgressStore任一环节失败自动降级 SQLite捕获异常后回退到 SQLite优先使用桌面数据目录否则落到项目根data/progress.db并记录 warning 日志。这意味着即使没有安装或启动 Redis整个系统依然可用只是快照持久化在 SQLite 中——这正是做笨做稳在存储层的体现。进度事件写入失败时emit_progress只会记录 error 日志而不会中断流水线执行。七、REST API 详解API 定义在 backend/api/v1/simple_progress.py路由前缀为/simple-progress共三个端点。1. 批量获取进度快照GET /api/v1/simple-progress/snapshot?project_idsproject-1project_idsproject-2project_ids为可重复的 Query 参数列表。内部调用get_multiple_progress_snapshots对不存在快照的项目直接跳过返回已有项目的快照数组[ {project_id: project-1, stage: HIGHLIGHT, percent: 70, message: 片段定位完成, ts: 1640995200}, {project_id: project-2, stage: INGEST, percent: 0, message: 等待开始, ts: 0} ]2. 单个项目进度GET /api/v1/simple-progress/snapshot/project-1注意此端点的容错设计若快照不存在不会返回 404而是返回一个默认状态stageINGEST、percent0、message等待开始、ts0前端拿到后即可平滑渲染等待开始的初始 UI无需额外判空分支。3. 获取阶段配置GET /api/v1/simple-progress/stages返回每个阶段的stage、weight、display_name中文名以及total_weight恒为 100。前端可据此动态渲染阶段步骤条或做权重可视化。八、后端集成emit_progress 与 SimplePipelineAdapter方式一在流水线中手动发送进度事件最轻量的接入方式是直接调用emit_progressfrom backend.services.simple_progress import emit_progress # 阶段切换 emit_progress(project_id, ANALYZE, 开始内容分析) # 带子进度percent 会按权重线性换算如 ANALYZE 50% 总进度 35% emit_progress(project_id, ANALYZE, 分析中(50%), subpercent50)emit_progress的完整调用链源码确认调用compute_percent得到总百分比组装 payload含tstime.time()通知所有进程内监听器add_progress_listener注册的回调CLI / MCP 场景用于实时打印写入进度存储Redis/SQLite打印结构化日志便于监控。方式二使用简化流水线适配器更推荐的方式是直接使用完整适配器让进度事件自动融入六步流水线from backend.services.simple_pipeline_adapter import create_simple_pipeline_adapter adapter create_simple_pipeline_adapter(project_id, task_id) result adapter.process_project_sync(video_path, srt_path)从 backend/services/simple_pipeline_adapter.py 的实现看process_project_sync内部按阶段推进并逐点上报上报点进度事件说明开头clear_progress(project_id)清理旧快照防止脏数据阶段 1emit_progress(..., INGEST, 素材准备完成)随后执行_preflight_llm()预检 LLM 可用性阶段 2emit_progress(..., SUBTITLE, ...)复用 SRT 或走_generate_subtitle_automaticallyWhisper 本地模型子进度 25%/40%再跑step1_outline完成后子进度 50%阶段 3emit_progress(..., ANALYZE, ...)跑step2_timeline子进度 50%、step3_scoring子进度 100%阶段 4emit_progress(..., HIGHLIGHT, ...)跑step4_title子进度 40%、step5_clustering子进度 100%阶段 5emit_progress(..., EXPORT, ...)跑step6_video切割完成后子进度 100%阶段 6emit_progress(..., DONE, 处理完成)随后执行DataSyncService.sync_project_from_filesystem回写数据库值得注意的失败处理细节适配器捕获PipelineFailure定义见 backend/pipeline/failures.py后会在失败发生的阶段发出带处理失败...前缀的事件并返回{status: failed, stage: ..., error: ...}结构普通异常则统一在DONE阶段上报失败消息。前端轮询到消息包含失败/错误关键字即可判定失败态。九、前端集成Zustand Store、进度条与项目卡片1. 进度状态管理useSimpleProgressStorefrontend/src/stores/useSimpleProgressStore.ts 用 Zustand 实现核心能力import { useSimpleProgressStore } from ../stores/useSimpleProgressStore const { startPolling, stopPolling, getProgress } useSimpleProgressStore() // 开始轮询建议显式传间隔见下文说明 startPolling([project-1, project-2], 2000) // 获取进度 const progress getProgress(project-1)Store 的轮询实现有几个亮点源码确认立即执行 定时器startPolling先立刻fetch一次/api/v1/simple-progress/snapshot?project_ids...再用setInterval周期性刷新首屏零等待终态自动停止当返回的快照全部处于终态stage DONE或消息含失败/错误时自动stopPolling避免无意义请求若返回空数组项目还在 pending则继续轮询等待条件轮询projectIds为空时直接跳过并告警重复调用会先停旧轮询再起新轮询本地缓存快照按project_id存进byId提供upsert、clearProgress、clearAllProgress、getAllProgress。同时导出阶段显示名、颜色与状态判断工具getStageDisplayName、getStageColor、isCompleted(stage)、isFailed(message)。文档与源码的一个差异提醒文档建议轮询间隔默认 2000msSimpleProgressBar组件的pollingInterval默认值确为 2000但 Store 层startPolling的函数签名默认值是 5000ms。因此显式传入间隔参数是最稳妥的用法。2. 进度条组件SimpleProgressBar / BatchProgressBarfrontend/src/components/SimpleProgressBar.tsx 提供单个项目进度条import { SimpleProgressBar } from ../components/SimpleProgressBar SimpleProgressBar projectIdproject-1 autoStart{true} pollingInterval{2000} showDetails{true} onProgressUpdate{(progress) console.log(progress)} /Props 说明Prop默认值作用projectId必填目标项目 IDautoStarttrue挂载后自动启动轮询卸载时自动停止pollingInterval2000轮询间隔毫秒showDetailstrue是否显示 message 详情与更新时间onProgressUpdate-进度更新回调父组件可据此驱动状态组件渲染逻辑源码确认无快照时显示等待开始处理...占位有快照时根据isFailed/isCompleted/percent将 antd Progress 的状态映射为exception/success/active/normal并用阶段色给标签、百分比、进度条统一着色同时展示阶段中文名与更新时间。同文件还导出了批量版本BatchProgressBar接收projectIds数组一次轮询多个项目子进度条共享同一轮询子组件autoStart{false}避免重复启动。3. 项目卡片组件SimpleProjectCardfrontend/src/components/SimpleProjectCard.tsx 把进度显示与项目操作整合在一张卡片里import { SimpleProjectCard } from ../components/SimpleProjectCard SimpleProjectCard project{project} onStartProcessing{handleStart} onViewDetails{handleView} onDelete{handleDelete} onRetry{handleRetry} /卡片行为源码确认当project.status processing时自动启动该项目的 2000ms 轮询并渲染SimpleProgressBar否则停止状态标签根据进度消息/阶段自动判定处理失败 / 处理完成 / 处理中 / 等待处理操作区按状态条件渲染开始处理pending/failed、重试失败态、查看详情、删除带确认弹窗四个按钮。进度到达DONE或失败时还会弹出message通知。4. 演示页frontend/src/pages/SimpleProgressDemo.tsx 内置了三个模拟项目demo-project-1/2/3可直观演示BatchProgressBarSimpleProjectCard的组合效果是理解整套前端接入方式的最佳入口。十、配置选项轮询间隔默认2000ms组件层/ 5000msStore 层默认参数建议范围1000–5000ms调整依据网络状况与并发项目数。局域网内可低至 1s公网弱网建议提高到 3–5s以降低无效请求。阶段权重总权重固定为 100权重应贴合各阶段实际耗时当前分配中HIGHLIGHT25最高因为标题生成 主题聚类涉及多轮 LLM 调用ANALYZE20次之若后续某阶段耗时可预期地变长例如引入更重的多模态分析直接调整STAGES中的权重即可计算逻辑无需改动。十一、故障处理Redis 连接失败存储初始化阶段失败会自动降级 SQLite见第六节并打印 warning 日志运行期写入异常时emit_progress捕获并记录 error 日志跳过本次进度保存但不中断流水线前端轮询到空数据时保持等待开始状态继续重试。网络中断前端fetch失败会在 catch 分支记录错误并继续下一轮轮询setInterval不受影响已获取的进度数据缓存在 ZustandbyId中网络恢复后自动用新快照覆盖后端流水线不受影响快照在存储层持续更新。阶段异常流水线内部错误由PipelineFailure携带stage字段定位失败阶段emit_progress发出带处理失败前缀的消息前端isFailed检测到失败关键字后进度条切换为exception状态卡片标签显示处理失败并提供重试按钮重试入口onRetry配合适配器开头的clear_progress可干净地重置进度重新执行。十二、性能优化文档列出的四项优化在实现中均有对应落地批量轮询GET /snapshot?project_idsaproject_idsb一次请求携带多个项目SQLite 端用IN (...)查询、Redis 端逐个hgetallBatchProgressBar正是以此驱动智能缓存Store 的byId避免重复渲染重复拉取相同项目的多个进度条共享同一份轮询数据条件轮询autoStart开关、SimpleProjectCard只在processing状态启动轮询、空项目列表直接跳过、终态自动停机——把无效请求降到最低自动清理适配器每次执行开头clear_progress清理旧快照避免脏数据与存储膨胀。十三、扩展性新增阶段在STAGES列表插入一项并调整其余权重WEIGHTS/ORDER自动重建API 的/stages与前端STAGE_DISPLAY_NAMES/STAGE_COLORS补上对应映射即可调整权重只改数字计算函数与存储层零改动自定义消息message字段完全开放适配器各上报点可自由携带业务上下文如共 12 段候选多环境支持存储选择已内建桌面模式 / 服务端模式两套策略REDIS_URL环境变量可指向不同环境的 RedisAUTOCLIP_LLM_CACHE_DIR等环境变量进一步支持离线回放场景。十四、监控与调试日志记录emit_progress每次发送输出进度事件已发送: {project_id} - {stage} ({percent}%) - {message}级别的 info 日志失败路径输出 error 日志状态检查任一时刻可通过GET /api/v1/simple-progress/snapshot/{project_id}实时查询某个项目的当前进度快照错误追踪快照保存/查询异常均带完整异常信息落日志适配器的失败返回结构含stage与error字段可直接对接前端失败态与错误上报进程内监听CLI / MCP 场景通过add_progress_listener(fn)注册回调即可实时打印进度见 backend/tests/test_cli.py 的test_progress_listener_receives_payload测试它同时验证了监听器收发与移除行为。十五、从旧复杂进度系统迁移指南若你的分支/部署仍在使用基于 WebSocket 订阅的旧进度系统可按文档与源码给出的路径迁移后端迁移将原有进度回调全部替换为emit_progress(project_id, stage, message, subpercent...)调用使用SimplePipelineAdaptercreate_simple_pipeline_adapter工厂替换旧适配器直接获得阶段化进度与失败上报移除复杂的 WebSocket 进度发布逻辑改由 HTTP 快照接口对外服务。前端迁移用useSimpleProgressStore替换旧状态管理轮询替代订阅用SimpleProgressBar/BatchProgressBar替换旧进度组件将 WebSocket 订阅代码替换为startPolling/stopPolling控制并接入getProgress读取快照。数据迁移清理旧的进度数据表/键让系统按当前模式初始化新的存储Server 模式 Redis、Desktop 模式 SQLite更新项目状态到阶段映射pending/processing/failed与六阶段快照的对应关系。十六、总结AutoClip 的简化进度系统用固定阶段 固定权重 HTTP 轮询替代了复杂订阅机制在可靠性、简单性、性能、扩展性与可调试性五个维度上都更契合视频剪辑流水线的实际需求✅可靠性基于 HTTP 轮询不依赖 WebSocket 常驻连接存储层 Redis 不可用时自动降级 SQLite进度事件失败不阻塞流水线✅简单性六个固定阶段、权重合计 100、最多 6 次事件计算函数单一且被测试锁定✅性能批量轮询一次取多项目、本地缓存、条件轮询与终态自动停机把请求量压到最低✅扩展性改STAGES即可增删阶段或调整权重前后端映射表一一对应✅调试性结构化日志、实时快照查询、进程内监听器与完整错误追踪线上排障成本极低。相比之前的复杂系统这套做笨做稳的方案在稳定维护与快速迭代之间取得了更好的平衡也验证了一个朴素的工程道理对于进度反馈这类对正确性要求高于实时性的信息简单可靠的轮询往往比复杂的实时推送更值得信赖。赞分享音视频AI 应用后端前端【免费下载链接】autoclipAutoClip : AI-powered video clipping and highlight generation · 一款智能高光提取与剪辑的二创工具项目地址https://gitcode.com/GitHub_Trending/autoc/autoclip点击查看免费下载相关推荐AutoClip 进度系统修复实战用固定阶段 HTTP 轮询替换复杂 WebSocket 进度体系AutoClip 进度系统修复实战用固定阶段 HTTP 轮询替换复杂 WebSocket 进度体系 本指南基于 AutoClip 仓库中的 docs/音视频AI 应用后端前端AutoClip简化进度系统揭秘固定阶段固定权重的做笨做稳设计哲学AutoClip简化进度系统揭秘固定阶段固定权重的做笨做稳设计哲学 AutoClip 是一款 AI 智能视频剪辑与高光提取二创工具它的「简化进度系统」只用音视频AI 应用后端前端AutoClip 增强进度系统Enhanced Progress System全指南架构、源码实现与前后端接入实战AutoClip 增强进度系统Enhanced Progress System全指南架构、源码实现与前后端接入实战 导读 AutoClip 是一款 AI音视频AI 应用后端前端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考