cat-shark/vrsub
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
把 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:
cat-shark
2026-09-13 15:40:31 +08:00
parent 669858c1d1
commit 966f3e6b4b
12 changed files with 1017 additions and 478 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+71 -19
View File
@@ -1,8 +1,10 @@
# VRSub
为视频生成 **VR 双眼字幕**的单体应用：API、调度器与全部节点在同一进程内运行，
单仓库、单环境、单命令启动。由原分布式 WOV 多仓库合并而来，详细约定见
[AGENTS.md](./AGENTS.md)。
单仓库、单环境、单命令启动。由原分布式 WOV 多仓库合并而来。
用户上传视频，选择工作流，即可得到中文 `.srt` 与 VR 双目 `.ass` 字幕；
也可以按文件夹批量处理整个媒体库，产物直接落在视频旁。
## 快速开始
@@ -11,35 +13,81 @@ uv sync
uv run uvicorn wov_app.main:app --reload
```
访问 `http://127.0.0.1:8000/` 上传视频，自动执行"提音 → 转写 → 翻译 → ASS"。
访问：
- 模型权重本地优先：把 whisper 模型放在 `model/faster-whisper-large-v3`
```
http://127.0.0.1:8000/ 应用中心（上传视频 → 字幕生成）
http://127.0.0.1:8000/tasks.html 任务管理
http://127.0.0.1:8000/batch.html 批量处理（按文件夹）
http://127.0.0.1:8000/admin.html 管理后台（工作流）
http://127.0.0.1:8000/workflow.html 工作流编排（DAG JSON）
http://127.0.0.1:8000/docs API 文档
```
- 模型权重本地优先：把 whisper 模型放在 `model/faster-whisper-large-v2`
（含 `model.bin`）即可完全离线运行。
- LLM 翻译默认使用 SiliconFlow（`Qwen/Qwen3.5-35B-A3B`），API Key 放在
gitignored 的 `.env`（`LLM_API_KEY=sk-...`），启动时自动加载；也可用
`LLM_API_BASE` / `LLM_MODEL` 环境变量覆盖。
- 默认模型切换为 `Qwen/Qwen3.5-35B-A3B`（2026-09）：对同片 2 小时日语 ASR 做
8 个模型全量对比，该模型质量与旧默认 `Qwen/Qwen3.6-35B-A3B` 持平，
速度 0.232 s/行（全评测最快），评测报告见
`data/experiments/translate_models/REPORT.md`。
- `subtitle-correction` 节点**不跟随**该默认值，有意保留
`Qwen/Qwen3.6-35B-A3B`：错听泛化实测新模型 0/4、旧模型 4/4。
- `llm-filter` 节点的 LLM 五类分类层**默认关闭**（`use_llm=0`）：
实测该层额外删除的 131 条中 56% 是真实对话，净收益为负；
现只跑确定性规则层，误删真对话从 73 条降为 0 条且无 LLM 调用。
- LLM 翻译默认使用 SiliconFlow，API Key 放在 gitignored 的 `.env`
（`LLM_API_KEY=sk-...`），启动时自动加载。
- 环境变量全表与依赖管理见 [docs/configuration.md](./docs/configuration.md)。
## 文档导航
| 文档 | 内容 |
| --- | --- |
| [docs/architecture.md](./docs/architecture.md) | 目录结构、核心机制（registry/scheduler/前端）、北极星不变式、单体化说明 |
| [docs/node-protocol.md](./docs/node-protocol.md) | 节点输入输出协议表、字幕样式统一、模型权重解析、长音频分块、VLM OCR 并发、暂停断点、前端框选 |
| [docs/workflows.md](./docs/workflows.md) | 内置工作流一览、`_note_` 参数标注约定、decode_full 与幻觉清洗、切换模型、产物命名 |
| [docs/configuration.md](./docs/configuration.md) | 环境变量全表、启动方式、Python/uv 管理 |
| [docs/operations.md](./docs/operations.md) | 孤儿数据清理、任务暂停/继续、进度日志、文件夹批量处理 |
| [docs/testing.md](./docs/testing.md) | 测试结构（按模块目录组织）、测试资产归属、真实模型集成测试 |
| [docs/decisions.md](./docs/decisions.md) | 设计决策与踩坑记录（模型选型、glm-ocr 循环、帧号排序等） |
| [docs/代码审查问题跟踪.md](./docs/代码审查问题跟踪.md) | 缺陷清单 R01–R08、修复记录与验收标准 |
| [docs/VR双目字幕景深与遮挡调查报告.md](./docs/VR双目字幕景深与遮挡调查报告.md) | VR 字幕景深/遮挡方案的调研全文 |
| [docs/调研-whisper漏句与decode_full验证.md](./docs/调研-whisper漏句与decode_full验证.md) | whisper 漏句与 decode_full 的实验记录 |
| [docs/adaptive_vad.md](./docs/adaptive_vad.md) | 每视频自适应 VAD 调参方案 |
| [docs/proper_nouns.md](./docs/proper_nouns.md) | 专有名词处理表 |
代理协作规则（TDD、提交许可、测试与注释规范、执行环境）见
[AGENTS.md](./AGENTS.md)，该文件只写规则、不含项目信息。
## 目录
| 路径 | 说明 |
| --- | --- |
| `src/wov_sdk/` | 协议数据模型（与分布式版兼容） |
| `src/wov_app/` | 应用层：API、注册表、调度器、数据库 |
| `nodes/` | 进程内节点实现（echo/ffmpeg/whisper/llm/ass） |
| `src/wov_app/` | 应用层：API、注册表、调度器、批量引擎、数据库 |
| `nodes/` | 进程内节点实现（echo/ffmpeg/whisper/llm/vlm/ass/ocr/filter） |
| `manifests/` | 节点清单 JSON |
| `workflows/` | 默认工作流定义 JSON（模型与链路均为数据） |
| `web/` | 静态前端 |
| `model/` | 本地模型权重（gitignored） |
| `data/` | SQLite 与存储（gitignored） |
| `tests/` | 测试（100% 行覆盖率） |
| `docs/` | 设计与运维文档 |
| `tests/` | 按模块组织的测试（见 [docs/testing.md](./docs/testing.md)） |
## 内置工作流
| ID | 名称 | 链路 |
| --- | --- | --- |
| `zh-direct` | 中文直出字幕 | 提音 → 中文转写 → ASS |
| `ocr-subtitle` | 字幕OCR提取 | 抽帧 → 逐帧 OCR → 汇总 SRT → LLM 过滤 |
| `learn-translate` | 学习资料转译+翻译字幕 | 提音 → 转写(decode_full) → LLM 翻译 → ASS |
链路细节与参数约定见 [docs/workflows.md](./docs/workflows.md)。
## 模型与实验结论摘要
- 默认 LLM 为 `Qwen/Qwen3.5-35B-A3B`（2026-09 切换）：对同片 2 小时日语 ASR 做
8 个模型全量对比，质量与旧默认 `Qwen/Qwen3.6-35B-A3B` 持平，速度 0.232 s/行
（全评测最快），评测报告见 `data/experiments/translate_models/REPORT.md`。
- `subtitle-correction` 节点**不跟随**该默认值，有意保留
`Qwen/Qwen3.6-35B-A3B`：错听泛化实测新模型 0/4、旧模型 4/4。
- 通用转写模型为 `faster-whisper-large-v2`（2026-09 由 large-v3 切换），
依据见 [docs/decisions.md](./docs/decisions.md#whisper-large-v2-vs-large-v3-切换)。
- `llm-filter` 节点的 LLM 五类分类层**默认关闭**（`use_llm=0`）：
实测该层额外删除的 131 条中 56% 是真实对话，净收益为负；
现只跑确定性规则层，误删真对话从 73 条降为 0 条且无 LLM 调用。
详细依据见 [docs/decisions.md](./docs/decisions.md#llm-filter-的-llm-分类层默认关闭)。
## 测试
@@ -47,8 +95,12 @@ uv run uvicorn wov_app.main:app --reload
uv run pytest
```
测试资产与集成测试说明见 [docs/testing.md](./docs/testing.md)，
测试规则（TDD、真实数据要求）见 [AGENTS.md](./AGENTS.md#测试规则)。
## 与分布式版的关系
- 协议数据模型、工作流 DAG 数据化、调度拓扑执行保持不变。
- 已移除：子进程节点、节点 HTTP 协议、节点注册/实例管理、TTL 回收。
- 未来回退分布式时，只需为 `registry.invoke` 重新加上进程边界。
- 详见 [docs/architecture.md](./docs/architecture.md#单体化说明)。