Files

T

cat-shark 966f3e6b4b docs: AGENTS.md 只保留代理规则，项目信息迁入 README 与 docs/

把 AGENTS.md（545 行）中的项目知识按性质拆开，只留下对代理的要求：

- AGENTS.md（176 行）只写规则：读文档指引、提交许可、等待规则、TDD、
  测试规则（模块边界/三段结构/功能覆盖优先）、注释规范、目标运行环境、
  PowerShell 规则、文档维护规则；
- 项目信息新建 docs/ 专题：architecture、node-protocol、workflows、
  configuration、operations、testing、decisions；
- README 改为项目索引（定位、快速开始、文档导航、目录、工作流、结论摘要）；
- 修正旧文档错误：README 的"详细约定见 AGENTS.md"与"100% 行覆盖率"
  （pytest 已移除该门槛）；环境变量表补齐 WOV_AUTO_VAD 等 3 项。

新增 scripts/check_doc_links.py 校验相对链接与锚点，当前 14 个文档全部可达。

2026-09-13 15:40:31 +08:00

4.7 KiB

Raw Permalink Blame History

架构

VRSub 是"为视频生成 VR 双眼字幕"的单体应用（WOV AI Workflow Platform 的单机实现）：FastAPI 后端、工作流调度器与全部节点（提音 / 转写 / 翻译 / ASS）在同一个进程内运行，不再启动子进程、不再走节点 HTTP 协议。由原分布式多仓库（wov-api / wov-web / wov-sdk / wov-node-*）合并而来。

目录结构

vrsub/
├── src/wov_sdk/       # 协议数据模型（NodeManifest/InvokeRequest/InvokeResponse/
│                      #   WorkflowDefinition 等），与分布式版保持一致
├── src/wov_app/       # 应用层：main/config/db/registry/scheduler/batch/seed/routers
│   └── routers/       #   apps.py（用户端）、workflows.py（管理端）、batch.py（批量处理）
├── nodes/             # 进程内节点实现：echo/ffmpeg/whisper/llm/ass
├── manifests/         # 各节点清单 JSON（echo.json/ffmpeg.json/...）
├── workflows/         # 默认工作流定义 JSON（模型/链路均为数据，改模型不改代码）
├── web/               # 静态前端（index/tasks/admin/workflow + assets）
├── model/             # 本地 whisper 权重（gitignored）
├── data/              # SQLite + 上传/产物存储（gitignored）
├── docs/              # 设计与运维文档（本目录）
└── tests/             # 单元/API/冒烟测试（覆盖核心路径，不强制 100%）

核心机制

节点注册表（src/wov_app/registry.py）：启动时把 manifests/*.json 与 nodes/*.py 的 invoke 处理器静态注册到进程内字典，调度器按 node_type 直接调用。协议数据模型不变，为将来回退分布式保留兼容桥梁。
调度器（src/wov_app/scheduler.py）：后台线程轮询 SQLite 中的 QUEUED 任务，按工作流 DAG 拓扑顺序调用节点，产物按 data/storage/runs/<run_id>/steps/<node_id>/ 落盘并登记到 artifacts 表。
前端：由 FastAPI 静态挂载 web/，节点注册/实例管理页面已移除，仅保留应用中心、任务管理、批量处理、管理后台（工作流）与工作流编排。
工作流编排页（web/workflow.html）：支持新建工作流（空表单预填演示模板），从列表"编辑"加载任一工作流的最新定义（ID 锁定，保存即追加新版本）；"版本" 查看全部历史版本并可"加载到编辑器"（对比/回滚后另存新版本）；管理后台（admin.html）无编辑器，点"编辑"自动跳转 workflow.html?edit=<id> 加载。
批量引擎（src/wov_app/batch.py）：独立的单线程轮询线程处理 source=batch 的运行，与主调度器互不抢占；详见 operations.md。

关键设计约束（北极星不变式）

节点之间不直接调用，只通过产物 URI 交换数据；中间产物落在共享存储（data/storage），不放在节点模块内部。
工作流必须是数据文件或数据库记录（workflow_versions 表存 DAG JSON），不允许把步骤顺序写死在应用代码里。
节点注册表是节点调用的唯一入口；API 与调度器不绕过 registry 直接执行节点逻辑。
协议数据模型（wov_sdk）要长期稳定，宁可先少做功能，也不轻易改协议。
存储、队列、调度器都要通过抽象边界隔离，方便从单机实现替换为分布式实现。
用户端永远只看到"输入 -> 进度 -> 结果"，不暴露工作流细节。
单体对分布式版的三处降级：无子进程隔离、无空闲 TTL 回收（模型常驻，仅懒加载）、非 OCR 慢任务无法强制中断（由节点自身超时兜底；OCR 节点支持暂停信号逐帧中断）。

单体化说明

由原 7 个独立仓库合并：wov-api、wov-web、wov-sdk、wov-node-echo、 wov-node-ffmpeg、wov-node-whisper、wov-node-llm、wov-node-ass。
删除内容：NodeManager（子进程生命周期）、节点 HTTP 服务端（wov_sdk.server）、节点注册/实例管理 API 与页面、node_instances 表、各节点的 __main__ 进程入口。
保留内容：协议数据模型、工作流 DAG 数据化、调度拓扑执行、上传/进度/下载/ 重试 API、静态前端、SQLite Repository 层、本地优先模型加载。

4.7 KiB Raw Permalink Blame History Unescape Escape

架构

目录结构

核心机制

关键设计约束（北极星不变式）

单体化说明

相关文档

4.7 KiB

Raw Permalink Blame History