cat-shark
966f3e6b4b
把 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 个文档全部可达。
76 lines
4.7 KiB
Markdown
76 lines
4.7 KiB
Markdown
# 架构
|
||
|
||
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](./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 层、本地优先模型加载。
|
||
|
||
## 相关文档
|
||
|
||
- 节点输入输出协议、模型权重解析：[node-protocol.md](./node-protocol.md)
|
||
- 内置工作流与参数约定：[workflows.md](./workflows.md)
|
||
- 环境变量与启动：[configuration.md](./configuration.md)
|
||
- 批量处理、暂停/继续、孤儿清理：[operations.md](./operations.md)
|
||
- 设计决策与事故记录：[decisions.md](./decisions.md)
|