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 个文档全部可达。
This commit is contained in:
2026-09-13 15:40:31 +08:00
parent 669858c1d1
commit 966f3e6b4b
12 changed files with 1017 additions and 478 deletions
+75
View File
@@ -0,0 +1,75 @@
# 架构
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/ # 各节点清单 JSONecho.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)