feat(subtitles): 补字幕第 1 步——上传字幕 / zip,识别语言与季集,配对写入视频同目录,历史与撤销

Co-Authored-By: Claude Opus 5.5 <[email protected]>

docs/plan/README.md

@@ -29,6 +29,10 @@
 - `BrowserService`（`apps/server/src/modules/browser/service.ts`，约 2300 行）仍是单个类。纯函数已移到 `session-view.ts`；Cloudflare 挑战流程（`beginChallenge`～`fetchSiteHtml`，约 400 行）要拆成独立协作对象，需要先把它用到的私有方法改成公开接口，下次改挑战流程时做。
 - 超长函数：`planImport`（`organize-plan.ts`，约 830 行）、`finalizeRecord`（`organize-finalize.ts`，约 460 行）、`OrganizeWizard` 组件（约 800 行）。文件已按阶段拆开，函数内部等改到相关逻辑时再拆，不单独重构。
 
+### 进行中
+
+- 补字幕：[subtitles.md](subtitles.md)，第 1 步（手动上传）已完成，下一步字幕站（SubHD、字幕库）在线搜索。
+
 ### 业务（需要真实环境或决定）
 
 - R06 通用 HTTP 失败转浏览器：要先定"哪些失败转浏览器、每站每小时上限、失败后怎么提示"，再实现；真实 Cloudflare 挑战需要一个会触发挑战的站点账号验收。

docs/plan/subtitles.md

@@ -0,0 +1,36 @@
+# 补字幕（2026-10-03 定）
+
+参考 MoviePilot 插件「海拉鲁字幕大师」（ifsherlock/MoviePilot-Plugins `plugins.v3/subtitlemanualupload` 1.2.6）。本项目只取**手动上传**和**在线搜索**；调轴、AI 翻译联动、入库后自动补字幕不做。自动补字幕以后接进我们自己的工作流（整理完成、订阅缺字幕、智能体调用），复用本模块的能力，不照插件的事件队列做。
+
+## 拆分
+
+| 层面 | 放在哪 |
+| --- | --- |
+| 字幕站的登记、代理、限流、健康、浏览器会话 | 复用站点体系：新站点类型「字幕站」（`site.kind = subtitle`），站点页单列一组，添加站点时选「字幕站」 |
+| 解析、配对、写入、历史、在线搜索与下载 | 新模块 `subtitles`（server）+ `packages/domain/src/subtitles`（纯函数）+ `packages/adapters/src/subtitles`（SubHD / 字幕库） |
+| 入口 | 作品页「补字幕」：上传 / 在线搜索 → 预览配对 → 写入；同页看历史、撤销 |
+
+## 写入规则（用户确认）
+
+- 写在视频同目录，`视频主干名 + 语言后缀 + 扩展名`；语言后缀沿用整理规则 `sidecarLanguageSuffix`（`.chi.zh-cn` / `.zh-tw` / `.eng` / `.ja` / `.ko`）。
+- 同名字幕已存在：先备份到数据目录（不在媒体库里留 `.bak`），再临时文件 + 改名原子写入。
+- 写入后登记为字幕资产（`media_asset.kind = subtitle`，位置 `sidecar_of_location_id` 指向视频），记一条历史；撤销 = 删掉写入的文件，有备份就还原。
+- 只写进作品在媒体库里的视频所在目录（媒体库根目录已启用）；字幕和压缩包内容走 JSON（base64），服务端不留临时文件。
+
+## 解析与配对（对照插件 `matching/subtitle_language.py`、`upload/upload_session.py`）
+
+- 支持 `.srt .ass .ssa .vtt .sub .sbv` 和 `.zip`（rar / 7z 先不做，插件也要依赖容器里的 unar）。
+- 语言：先看文件名标签（chs / cht / 简体 / 繁體 / eng / 双语 …），再看内容（CJK、假名、谚文、繁体常用字比例）；中英双语按简中处理（与整理规则一致）。
+- 季集：用文件名解析（复用资源名解析器）；电影只有一个目标。对不上的留空让人选；同一集多个字幕按语言区分，同语言重复的提示。
+
+## 在线（SubHD、字幕库）
+
+- 搜索词：作品中文名、原名、年份，剧集带季号；结果按标题与季集匹配度排序，对不上的不列。
+- 验证码三层兜底：① 代码识别（SubHD SVG 路径长度表、字幕库 BMP 采样模板，插件里各 80 行左右）；② 浏览器服务打开页面（与 PT 站过人机验证同一流程，可人工接管）；③ 智能体视觉处理页面挑战。
+- 下载结果走与上传相同的解析 → 预览 → 写入。
+
+## 分步
+
+1. 手动上传：解析、配对预览、写入、历史与撤销、作品页入口。（v0.3.22 完成）
+2. 字幕站类型 + SubHD / 字幕库搜索下载（第 ① 层验证码），站点页与添加站点。
+3. 验证码第 ② ③ 层兜底（浏览器、智能体）。