fix(editor): prevent duplicate AI translation layers

.gitignore

@@ -1,8 +1,21 @@
-# This repository is scoped to the bilingual EPUB review editor.
+# This repository is scoped to the bilingual EPUB review editor and shared workflow docs.
 # Keep translation corpora, EPUBs, review sessions, and generated outputs out of Git.
 *
 
 !.gitignore
+!AGENTS.md
+!README.md
+!打开EPUB审校器.cmd
+!rules/
+!rules/**
+!templates/
+!templates/**
+!epub_delivery/
+!epub_delivery/**
+
+epub_delivery/**/__pycache__/
+epub_delivery/**/*.py[cod]
+
 !tools/
 tools/*
 !tools/epub_review_editor/

AGENTS.md

@@ -0,0 +1,141 @@
+# 轻小说翻译长期项目工作流
+
+本项目用于持续推进日语轻小说的简中翻译、复审、润色与 EPUB 交付。开始任何任务前，先阅读本文件，再读取 `rules/translation_rules.md`、当前系列的 `series-style.md` 和正式术语表。
+
+## 必读顺序
+
+1. `rules/translation_rules.md`
+2. 当前系列目录下的 `series-style.md`
+3. 当前系列目录下的 `mingcibiao.json`
+4. 当前卷目录下与任务阶段相关的文件
+
+如果任务是新卷启动，继续读取 `templates/new_volume_start_template.md`。如果任务是封装交付，继续读取 `epub_delivery/epub_delivery_recipe.md`。
+
+## 项目结构
+
+标准结构如下：
+
+```text
+<project-root>
+  <series-folder>\
+    mingcibiao.json
+    mingcibiao.ai.json
+    mingcibiao.candidates.json
+    series-style.md
+    <novel-folder>\
+      text\
+      preprocess_text\
+      trans_text\
+      final_text\
+      deliverables\
+```
+
+## 长期工作流
+
+1. 导入源文件，保留段落编号、div 结构、ruby 信息和必要标签。
+2. 扫描正文与 ruby，整理候选词到 `mingcibiao.candidates.json`。
+3. 等用户确认后，将候选词合并进 `mingcibiao.json`。
+4. 锁词后进行正文首译，首译写入 `trans_text/chunks`。
+5. 逐段复审，复审写入 `trans_text/reviewed_chunks`。
+6. 复审完成后恢复 HTML，写入 `final_text`。
+7. 交付前检查术语、残留日文、ruby、段落覆盖率和 HTML 结构。
+8. 需要 EPUB 时，使用 `epub_delivery/build_epub_variants.py` 生成纯译版和/或中日双语版。
+
+## 默认多 Agent 协作分工
+
+除非用户明确指定单线程处理，长卷、跨文件、翻译复审或 EPUB 交付任务默认按多 Agent 流水线协作：
+
+- 统筹 Agent：读取本文件、`translation_rules.md`、`series-style.md`、`mingcibiao.json`，确认当前阶段、输入文件、输出目录、风险点与暂停条件。
+- 术语 Agent：扫描原文、ruby、标题、技能名、人名地名与高频特殊表达，输出候选术语；只提出候选，不擅自写入正式 `mingcibiao.json`。
+- 首译 Agent：只处理明确分配的 chunk 范围，严格使用已锁定术语、系列风格和段落编号。
+- 复审 Agent：逐段对照源文、首译、术语表和风格文件，修正误译、漏译、日式语序、角色口吻漂移。
+- 格式恢复 Agent：恢复 HTML，保留 div、ruby、段落编号、必要标签和图片引用。
+- QA Agent：执行术语命中、残留日文、ruby、段落覆盖率、HTML 结构、空段落和交付文件检查；只读审查时只给报告，不改文件。
+- 交付 Agent：仅在 QA 通过或用户确认风险后，生成纯译版和/或中日双语版。
+
+并行 Agent 必须写入各自负责的目录或报告，不跨范围修改。发现正式术语、结构、交付形式或规则冲突时，暂停并交给统筹 Agent 汇总后请用户确认。
+
+审校器功能开发或维护任务应先读取 `tools/epub_review_editor/MAINTENANCE.md`，按工程维护、回归测试和版本规则处理，并默认采用“后端/API、前端交互、文档/工作流、QA 验收”的多 Agent 协作，不套用正文翻译流水线。
+
+## 翻译与润色原则
+
+- 输出必须是自然、流畅的简体中文轻小说文风。
+- 以意义优先，再调整成中文语序，不要贴着日语句序硬译。
+- 对话要符合角色性格，不要把所有角色写成同一种口吻。
+- 术语、人名、地名、组织名优先服从 `mingcibiao.json`。
+- 如果发现会影响一致性的新术语，先记录为候选词，不要擅自发明多个译名。
+- 保留 `[Pxxxx]`、`<lk>...</lk>`、必要的 ruby 和 HTML 标签。
+- 不合并、不拆分原有段落，除非用户明确要求重排结构。
+- 复审必须逐段覆盖，不可以只抽查。
+
+## 提示词第一性原理
+
+- 输入必须完整但克制：源文、必要上下文、命中术语、系列风格和输出格式要求同时给出；单段重翻不塞整本术语表。
+- 约束必须显式：不要只写“遵守术语表”，必须把本段实际命中的术语列入提示词；未命中的术语不得进入提示。
+- 输出必须可验收：要求保持段落数量、段落编号、HTML/ruby/标签结构，不输出解释、分析或额外段落。
+- 意义优先于字面：先理解语义、人物关系、语气和叙述功能，再改写成自然简中轻小说文风。
+- 复审不同于重译：复审优先保留首译中正确内容，只修误译、漏译、术语、语序、口吻和格式问题。
+- 不让模型自行定规则：遇到术语冲突、角色称谓冲突、ruby 含义不明、结构缺损时，输出问题或候选，不自行发明长期规则。
+
+## Ruby 与格式
+
+- 纯读音、无额外信息的 ruby，通常直接译成普通中文。
+- 隐含义、别名、外语读音、技能名、称号、世界观术语，应按需要保留为真实 ruby。
+- 不要把有意义的 ruby 改成括号。
+- 不要删除 `<rt>` 后再用猜测补回。
+- 双语版中，日文保留为灰色，中文译文紧随其后。
+
+## 常用用户指令
+
+- `新卷启动`：按 `templates/new_volume_start_template.md` 检查目录、风格文件和术语表。
+- `开始翻译`：进入正文翻译流程。
+- `继续`：按当前阶段自动推进下一步；没有风险点时不要重复解释整套流程。
+- `生成双语版`：生成中日双语 EPUB。
+- `生成翻译版`：生成纯译文 EPUB。
+- `终交付封装` 或 `合并为epub交付给我`：默认生成纯译版和中日双语版。
+
+## 交付脚本
+
+通用封装脚本位于 `epub_delivery/build_epub_variants.py`。常用命令：
+
+```powershell
+$env:PYTHONIOENCODING='utf-8'
+$env:SOURCE_EPUB='<源EPUB完整路径>'
+$env:NOVEL_ROOT='<小说工程根目录完整路径>'
+python '<project-root>\epub_delivery\build_epub_variants.py' --mode both
+```
+
+可选模式：
+
+```powershell
+python '<project-root>\epub_delivery\build_epub_variants.py' --mode translated
+python '<project-root>\epub_delivery\build_epub_variants.py' --mode bilingual
+```
+
+## 双语 EPUB 网页审校
+
+中日双语 EPUB 生成后，如用户需要网页审校、实时修改译文或标记翻译问题，使用 `tools/epub_review_editor/server.py`：
+
+```powershell
+$env:PYTHONIOENCODING='utf-8'
+python '<project-root>\tools\epub_review_editor\server.py' '<中日双语版.epub>' --daemon
+```
+
+审校器会生成独立 session，默认写入 `epub_review_sessions\`。重点读取：
+
+- `feedback/translation_feedback.jsonl`：结构化逐条反馈记录
+- `feedback/feedback_for_codex.md`：适合直接纳入后续翻译优化的摘要
+- `exports/*_网页审校版_*.epub`：用户导出的修订版 EPUB
+
+当用户说“读取我的审校反馈”“根据网页标记优化翻译”或类似指令时，优先读取上述反馈文件，将其中的具体修改、问题类型和长期规则沉淀到当前系列的复审口径、候选术语或风格文件中。正式术语表仍需用户确认后再改。
+
+## 决策规则
+
+- 如果 `series-style.md` 不存在，先用 `templates/series_style_template.md` 创建，再暂停等待用户填写。
+- 如果 `series-style.md` 为空或明显未完成，先提示用户确认是否继续。
+- 如果用户确认继续，只按已填写部分限定风格，空白部分视为未指定。
+- 名词表、规则冲突、交付形式等会影响全卷一致性的事项，先暂停让用户确认。
+- 用户只说“继续”时，按当前上下文进入下一步，不重新解释流程。
+- 每次完成代码、文档或工作流更新后，先完成必要检查，再将当前仓库同步到 `https://git.diaomin.asia/` 对应远端；如果缺少远端地址、凭据或登录授权，先询问用户，不要静默跳过。
+- 涉及通用工作流、目录结构、术语表格式、验收标准或默认协作方式的变更，必须同步 `rules/translation_rules.md` 与 `README.md`。
+- 涉及网页审校器行为、API、配置、前端交互或 GPT 重翻的变更，必须同步 `tools/epub_review_editor/MAINTENANCE.md` 并按其版本规则发版。

README.md

@@ -0,0 +1,64 @@
+# 最小发布包
+
+这是用于对外共享的轻小说翻译工作流最小包。
+
+## 包含内容
+
+- `AGENTS.md`：完整长期项目工作流，包括默认多 Agent 分工、决策规则与交付入口
+- `rules/translation_rules.md`：通用翻译规则，适用于所有线程和卷
+- `templates/new_volume_start_template.md`：新卷启动检查模板
+- `templates/series_style_template.md`：系列风格模板
+- `templates/startup_message_template.md`：启动消息模板
+- `templates/continue_message_template.md`：继续推进模板
+- `templates/delivery_message_template.md`：双语版与终交付模板
+- `epub_delivery/epub_delivery_recipe.md`：通用 EPUB 交付说明模板
+- `epub_delivery/build_epub_variants.py`：通用双语封装脚本
+- `tools/epub_review_editor/`：可独立部署的 EPUB 网页审校器，支持阅读审校、书架、AI 翻译 EPUB、GPT 重翻、术语表编辑、反馈与导出
+- `tools/epub_review_editor/MAINTENANCE.md`：网页审校器维护、验收、GPT 重翻、术语命中与版本规则
+- `tools/epub_review_editor/LONG_TERM_MEMORY.md`：审校器长期维护记忆，继续历史任务或上下文压缩后优先读取
+- `打开EPUB审校器.cmd`：Windows 一键启动入口，会自动准备本地 Python 环境并打开网页工具
+
+## 使用建议
+
+1. 先读 `AGENTS.md`，再读 `rules/translation_rules.md`
+2. 按需要选择 `templates/` 下的对应模板
+3. 若是新系列，先使用 `templates/series_style_template.md`
+4. 如果要进行 EPUB 交付，使用 `epub_delivery/` 里的说明和脚本
+5. 复制整个文件夹即可在其他机器上复用
+
+## 固定工作流入口
+
+复用本包时，默认工作流为：
+
+1. 先读 `AGENTS.md`，确认当前任务属于新卷启动、首译、复审、恢复、QA、审校器反馈处理或 EPUB 交付。
+2. 再读 `rules/translation_rules.md`，作为所有 Agent 的硬性规则。
+3. 当前系列必须提供 `series-style.md` 与 `mingcibiao.json`。
+4. 长卷任务默认使用多 Agent 分工：统筹、术语、首译、复审、格式恢复、QA、交付。
+5. 正式术语表由用户确认后更新；候选词表不得直接当正式词表使用。
+6. 交付前必须通过术语、残留日文、ruby、段落覆盖率和 HTML 结构检查。
+
+## 版本规则
+
+本包文档和脚本建议使用语义化版本：
+
+- PATCH：错字、说明修正、兼容性小修、脚本 bugfix。
+- MINOR：新增向后兼容模板、检查项、可选流程或审校器能力。
+- MAJOR：改变目录结构、正式工作流阶段、术语表格式、交付脚本参数或默认产物行为。
+
+发版时至少检查：
+
+- `AGENTS.md`
+- `rules/translation_rules.md`
+- `README.md`
+- `epub_delivery/epub_delivery_recipe.md`
+- `tools/epub_review_editor/MAINTENANCE.md`，如本次包含审校器变化
+
+## 仓库同步
+
+每次完成代码、文档或工作流更新后，先完成必要检查，再将仓库同步到 `https://git.diaomin.asia/` 对应远端。若当前仓库没有配置完整远端地址，或推送时需要登录、令牌、凭据授权，应先询问用户。
+
+## 说明
+
+- 这个包刻意不包含原文、词表、chunk 文件和已生成的 EPUB 成品。
+- 文档里的路径均为占位写法，复制到任意位置后都可以按相同结构使用。
+- 它用于复用工作流，不是完整的翻译工程目录。

epub_delivery/build_epub_variants.py

@@ -0,0 +1,380 @@
+from __future__ import annotations
+
+import argparse
+import html
+import json
+import os
+import re
+import zipfile
+from pathlib import Path
+
+
+P_RE = re.compile(r"<p\b([^>]*)>(.*?)</p>", re.S | re.I)
+H_RE = re.compile(r"<h([1-6])\b([^>]*)>(.*?)</h\1>", re.S | re.I)
+RUBY_RE = re.compile(r"<ruby\b[^>]*>.*?</ruby>", re.S | re.I)
+RB_RE = re.compile(r"<rb\b[^>]*>(.*?)</rb>", re.S | re.I)
+RT_RE = re.compile(r"<rt\b[^>]*>(.*?)</rt>", re.S | re.I)
+TAG_RE = re.compile(r"<[^>]+>")
+NAV_LABEL_TRANSLATIONS = {
+    "\u76ee\u6b21": "\u76ee\u5f55",
+    "\u5c11\u5e74\u671f\u3000\u5341\u4e8c\u6b73\u306e\u521d\u590f": "\u5c11\u5e74\u671f \u5341\u4e8c\u5c81\u521d\u590f",
+    "\u5c11\u5e74\u671f\u3000\u5341\u4e8c\u6b73\u306e\u76db\u590f": "\u5c11\u5e74\u671f \u5341\u4e8c\u5c81\u76db\u590f",
+    "\u5c11\u5e74\u671f\u3000\u5341\u4e09\u6b73\u306e\u79cb": "\u5c11\u5e74\u671f \u5341\u4e09\u5c81\u4e4b\u79cb",
+    "\u7d42\u7ae0": "\u7ec8\u7ae0",
+    "\u30d8\u30f3\u30c0\u30fc\u30bd\u30f3\u30b9\u30b1\u30fc\u30eb1.0\u3000Ver0.3": "\u4ea8\u5fb7\u68ee\u91cf\u88681.0 Ver0.3",
+    "\u5965\u4ed8": "\u7248\u6743\u9875",
+    "\u3042\u3068\u304c\u304d": "\u540e\u8bb0",
+}
+
+
+def extract_paragraphs(html: str) -> list[str]:
+    return [m.group(2) for m in P_RE.finditer(html)]
+
+
+def extract_headings(text: str) -> list[str]:
+    return [m.group(3) for m in H_RE.finditer(text)]
+
+
+def strip_tags(fragment: str) -> str:
+    return html.unescape(TAG_RE.sub("", fragment)).strip()
+
+
+def translate_known_labels(text: str) -> str:
+    result = text
+    for jp, cn in NAV_LABEL_TRANSLATIONS.items():
+        result = result.replace(jp, cn)
+    return result
+
+
+def clean_term_value(value: str) -> str:
+    return str(value).split("#", 1)[0].strip()
+
+
+def load_terms(novel_root: Path) -> dict[str, str]:
+    candidates = [novel_root / "mingcibiao.json", novel_root.parent / "mingcibiao.json"]
+    term_path = next((path for path in candidates if path.exists()), None)
+    if term_path is None:
+        return {}
+    raw = term_path.read_text(encoding="utf-8-sig")
+    raw = re.sub(r",\s*([}\]])", r"\1", raw)
+    return {str(key): clean_term_value(value) for key, value in json.loads(raw).items()}
+
+
+def split_ruby_term(value: str) -> tuple[str, str] | None:
+    match = re.fullmatch(r"(.+?)\(([^()<>]+)\)", clean_term_value(value))
+    if not match:
+        return None
+    rb, rt = match.group(1).strip(), match.group(2).strip()
+    if not rb or not rt:
+        return None
+    return rb, rt
+
+
+def source_ruby_items(fragment: str) -> list[tuple[str, str]]:
+    items = []
+    for ruby in RUBY_RE.findall(fragment):
+        rb_parts = [strip_tags(part) for part in RB_RE.findall(ruby)]
+        rt_parts = [strip_tags(part) for part in RT_RE.findall(ruby)]
+        rb = "".join(rb_parts) or strip_tags(re.sub(r"<rt\b[^>]*>.*?</rt>", "", ruby, flags=re.S | re.I))
+        rt = "/".join(part for part in rt_parts if part)
+        if rb and rt:
+            items.append((rb, rt))
+    return items
+
+
+def translated_ruby_for(rb: str, rt: str, terms: dict[str, str]) -> tuple[str, str] | None:
+    for key in (f"{rb}({rt})", rb, rt):
+        value = terms.get(key)
+        if not value:
+            continue
+        parsed = split_ruby_term(value)
+        if parsed:
+            return parsed
+    return None
+
+
+def restore_translated_ruby(source_inner: str, translated_inner: str, terms: dict[str, str]) -> str:
+    if not terms:
+        return translated_inner
+    restored = translated_inner
+    for rb, rt in source_ruby_items(source_inner):
+        parsed = translated_ruby_for(rb, rt, terms)
+        if not parsed:
+            continue
+        cn_rb, cn_rt = parsed
+        literal = f"{cn_rb}({cn_rt})"
+        if literal not in restored:
+            continue
+        ruby_html = f"<ruby><rb>{html.escape(cn_rb)}</rb><rt>{html.escape(cn_rt)}</rt></ruby>"
+        restored = restored.replace(literal, ruby_html, 1)
+    return restored
+
+
+def set_doc_lang_and_title(text: str, title: str, lang: str = "zh-CN") -> str:
+    text = re.sub(r"<title>.*?</title>", f"<title>{title}</title>", text, count=1, flags=re.S)
+    text = re.sub(r'xml:lang="[^"]+"', f'xml:lang="{lang}"', text, count=1)
+    if 'lang="' in text:
+        text = re.sub(r'lang="[^"]+"', f'lang="{lang}"', text, count=1)
+    else:
+        text = text.replace('<html ', f'<html lang="{lang}" ', 1)
+    text = re.sub(r'class="([^"]*)\bvrtl\b([^"]*)"', lambda m: f'class="{(m.group(1) + " hltr " + m.group(2)).strip()}"', text, count=1)
+    return text
+
+
+def add_gray_style(attrs: str) -> str:
+    if re.search(r"\bstyle\s*=", attrs, re.I):
+        if re.search(r'style="[^"]*"', attrs, re.I):
+            def repl(m: re.Match[str]) -> str:
+                body = m.group(1)
+                body = re.sub(r"\bcolor\s*:\s*[^;]+;?", "", body, flags=re.I).strip()
+                if body and not body.endswith(";"):
+                    body += ";"
+                body = (body + " color:#808080;").strip()
+                return f'style="{body}"'
+
+            return re.sub(r'style="([^"]*)"', repl, attrs, count=1, flags=re.I)
+        if re.search(r"style='[^']*'", attrs, re.I):
+            def repl2(m: re.Match[str]) -> str:
+                body = m.group(1)
+                body = re.sub(r"\bcolor\s*:\s*[^;]+;?", "", body, flags=re.I).strip()
+                if body and not body.endswith(";"):
+                    body += ";"
+                body = (body + " color:#808080;").strip()
+                return f"style='{body}'"
+
+            return re.sub(r"style='([^']*)'", repl2, attrs, count=1, flags=re.I)
+    return attrs + ' style="color:#808080;"'
+
+
+def transform_xhtml(
+    source_text: str,
+    translated_text: str | None,
+    bilingual: bool,
+    title: str,
+    terms: dict[str, str],
+) -> str:
+    source_text = set_doc_lang_and_title(source_text, title)
+    translated_headings = extract_headings(translated_text or "")
+    if translated_headings:
+        heading_iter = iter(translated_headings)
+
+        def replace_heading(match: re.Match[str]) -> str:
+            try:
+                inner = next(heading_iter)
+            except StopIteration:
+                inner = translate_known_labels(match.group(3))
+            return f"<h{match.group(1)}{match.group(2)}>{inner}</h{match.group(1)}>"
+
+        source_text = H_RE.sub(replace_heading, source_text)
+    else:
+        source_text = translate_known_labels(source_text)
+    translated_paragraphs = extract_paragraphs(translated_text or "")
+    matches = list(P_RE.finditer(source_text))
+
+    pieces: list[str] = []
+    last = 0
+    for index, match in enumerate(matches):
+        pieces.append(source_text[last:match.start()])
+        attrs = match.group(1)
+        source_inner = match.group(2)
+        translated_inner = translated_paragraphs[index] if index < len(translated_paragraphs) else source_inner
+        translated_inner = restore_translated_ruby(source_inner, translated_inner, terms)
+
+        if bilingual:
+            gray_attrs = add_gray_style(attrs)
+            pieces.append(f"<p{gray_attrs}>{source_inner}</p>")
+            if strip_tags(translated_inner):
+                pieces.append(f"<p{attrs}>{translated_inner}</p>")
+        else:
+            inner = translated_inner if translated_inner.strip() else source_inner
+            pieces.append(f"<p{attrs}>{inner}</p>")
+
+        last = match.end()
+
+    pieces.append(source_text[last:])
+    return "".join(pieces)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Build translated and bilingual EPUB variants for any novel volume.")
+    parser.add_argument(
+        "--mode",
+        choices=("translated", "bilingual", "both"),
+        default="both",
+        help="Which deliverable(s) to build.",
+    )
+    parser.add_argument(
+        "--source-epub",
+        default=os.environ.get("SOURCE_EPUB"),
+        help="Path to the source EPUB.",
+    )
+    parser.add_argument(
+        "--novel-root",
+        default=os.environ.get("NOVEL_ROOT"),
+        help="Path to the novel project root.",
+    )
+    parser.add_argument(
+        "--out-dir",
+        default=os.environ.get("OUT_DIR"),
+        help="Directory where deliverables are written.",
+    )
+    parser.add_argument(
+        "--title",
+        default=os.environ.get("EPUB_TITLE"),
+        help="Optional display title. If omitted, the source EPUB title is used.",
+    )
+    return parser.parse_args()
+
+
+def load_manifest(novel_root: Path) -> dict:
+    manifest_path = novel_root / "text" / "_epub_import_manifest.json"
+    if manifest_path.exists():
+        return json.loads(manifest_path.read_text(encoding="utf-8"))
+    final_dir = novel_root / "final_text"
+    files = [
+        {
+            "source_epub_path": f"text/{path.name}",
+            "output": path.name,
+        }
+        for path in sorted(final_dir.glob("part*.html"))
+    ]
+    return {
+        "metadata": {"title": novel_root.name},
+        "files": files,
+    }
+
+
+def output_title(manifest: dict, override: str | None) -> str:
+    return override or manifest["metadata"]["title"]
+
+
+def output_filename(title: str, suffix: str) -> str:
+    safe_title = re.sub(r'[\\/:*?"<>|]+', "_", title).strip()
+    return f"{safe_title}_{suffix}.epub"
+
+
+def main() -> int:
+    args = parse_args()
+    if not args.source_epub or not args.novel_root:
+        raise SystemExit("SOURCE_EPUB and NOVEL_ROOT must be provided via args or environment.")
+
+    source_epub = Path(args.source_epub)
+    novel_root = Path(args.novel_root)
+    output_dir = Path(args.out_dir) if args.out_dir else novel_root / "deliverables"
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    manifest = load_manifest(novel_root)
+    terms = load_terms(novel_root)
+    book_title = output_title(manifest, args.title)
+    source_to_output = {item["source_epub_path"]: item["output"] for item in manifest["files"]}
+    source_output_to_xhtml = {item["output"]: item["source_epub_path"] for item in manifest["files"]}
+
+    final_dir = novel_root / "final_text"
+    translated_by_output = {p.name: p for p in final_dir.glob("part*.html")}
+
+    variants = [
+        {
+            "name": output_filename(book_title, "简中译本"),
+            "title": f"{book_title}（简中译本）",
+            "bilingual": False,
+            "mode": "translated",
+        },
+        {
+            "name": output_filename(book_title, "中日双语版"),
+            "title": f"{book_title}（中日双语版）",
+            "bilingual": True,
+            "mode": "bilingual",
+        },
+    ]
+    if args.mode != "both":
+        variants = [item for item in variants if item["mode"] == args.mode]
+
+    with zipfile.ZipFile(source_epub, "r") as src_zip:
+        entries = src_zip.infolist()
+        source_bytes = {entry.filename: src_zip.read(entry.filename) for entry in entries}
+
+    for variant in variants:
+        out_path = output_dir / variant["name"]
+        if out_path.exists():
+            out_path.unlink()
+
+        with zipfile.ZipFile(out_path, "w") as out_zip:
+            out_zip.writestr("mimetype", b"application/epub+zip", compress_type=zipfile.ZIP_STORED)
+            for entry in entries:
+                name = entry.filename
+                if name == "mimetype":
+                    continue
+
+                data = source_bytes[name]
+                if name.lower().endswith(".opf"):
+                    text = data.decode("utf-8")
+                    text = re.sub(
+                        r"<dc:title>.*?</dc:title>",
+                        f"<dc:title>{variant['title']}</dc:title>",
+                        text,
+                        count=1,
+                        flags=re.S,
+                    )
+                    text = re.sub(
+                        r"<dc:language>.*?</dc:language>",
+                        "<dc:language>zh-CN</dc:language>",
+                        text,
+                        count=1,
+                        flags=re.S,
+                    )
+                    text = re.sub(
+                        r'<meta\s+content="vertical-rl"\s+name="primary-writing-mode"\s*/>',
+                        '<meta content="horizontal-lr" name="primary-writing-mode"/>',
+                        text,
+                        count=1,
+                    )
+                    text = re.sub(
+                        r'page-progression-direction="rtl"',
+                        'page-progression-direction="ltr"',
+                        text,
+                        count=1,
+                    )
+                    data = text.encode("utf-8")
+                elif name.lower().endswith(".ncx"):
+                    text = data.decode("utf-8")
+                    text = re.sub(r'xml:lang="[^"]+"', 'xml:lang="zh-CN"', text, count=1)
+                    text = re.sub(
+                        r"<docTitle>\s*<text>.*?</text>\s*</docTitle>",
+                        f"<docTitle><text>{variant['title']}</text></docTitle>",
+                        text,
+                        count=1,
+                        flags=re.S,
+                    )
+                    text = translate_known_labels(text)
+                    data = text.encode("utf-8")
+                elif (
+                    (name.startswith("item/xhtml/") and name.endswith(".xhtml"))
+                    or name in source_to_output
+                ):
+                    manifest_source = source_output_to_xhtml.get("part" + name[len("item/xhtml/p-") : -len(".xhtml")] + ".html")
+                    output_name = source_to_output.get(name) if name in source_to_output else None
+                    if output_name is None and manifest_source is not None:
+                        output_name = source_to_output.get(manifest_source)
+                    if output_name:
+                        translated_file = translated_by_output.get(output_name)
+                        if translated_file and translated_file.exists():
+                            source_text = data.decode("utf-8")
+                            translated_text = translated_file.read_text(encoding="utf-8")
+                            data = transform_xhtml(
+                                source_text,
+                                translated_text,
+                                variant["bilingual"],
+                                variant["title"],
+                                terms,
+                            ).encode("utf-8")
+
+                compress_type = zipfile.ZIP_STORED if name == "mimetype" else zipfile.ZIP_DEFLATED
+                out_zip.writestr(name, data, compress_type=compress_type)
+
+        print(f"Wrote {out_path}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

epub_delivery/epub_delivery_recipe.md

@@ -0,0 +1,68 @@
+# EPUB 交付说明模板
+
+这是每一本新开卷都可以复用的交付说明模板。使用时只需要替换其中的源 EPUB 路径、小说根目录，必要时再覆盖显示标题即可。
+
+## 适用范围
+
+- 适用于单卷 EPUB 的终交付封装
+- 适用于纯译版和中日双语版两种输出
+- 适用于当前卷和未来新卷
+
+## 前置条件
+
+1. 该卷的正文翻译已经完成。
+2. `final_text/` 中已经存在修复后的最终 HTML。
+3. 源 EPUB 文件可用。
+4. 小说工程根目录可用。
+5. 如果希望输出文件名使用自定义卷名，可以额外传入 `--title`。
+
+## 通用命令
+
+### 同时生成纯译版和双语版
+
+```powershell
+$env:PYTHONIOENCODING='utf-8'
+$env:SOURCE_EPUB='<源EPUB完整路径>'
+$env:NOVEL_ROOT='<小说工程根目录完整路径>'
+python '<封装脚本完整路径>' --mode both
+```
+
+### 仅生成纯译版
+
+```powershell
+$env:PYTHONIOENCODING='utf-8'
+$env:SOURCE_EPUB='<源EPUB完整路径>'
+$env:NOVEL_ROOT='<小说工程根目录完整路径>'
+python '<封装脚本完整路径>' --mode translated
+```
+
+### 仅生成双语版
+
+```powershell
+$env:PYTHONIOENCODING='utf-8'
+$env:SOURCE_EPUB='<源EPUB完整路径>'
+$env:NOVEL_ROOT='<小说工程根目录完整路径>'
+python '<封装脚本完整路径>' --mode bilingual
+```
+
+### 指定显示标题
+
+```powershell
+$env:PYTHONIOENCODING='utf-8'
+$env:SOURCE_EPUB='<源EPUB完整路径>'
+$env:NOVEL_ROOT='<小说工程根目录完整路径>'
+python '<封装脚本完整路径>' --title '<显示标题>' --mode both
+```
+
+## 输出约定
+
+- 纯译版 EPUB：仅保留中文译文
+- 双语版 EPUB：原文显示为灰色，译文显示为正常颜色
+- 输出目录默认写入 `NOVEL_ROOT\deliverables`
+- 如果传入 `--title`，输出文件名和书内标题都会使用该标题
+
+## 生成规则
+
+- `生成双语版`：执行双语版输出
+- `生成翻译版`：执行纯译版输出
+- `终交付封装` 或 `合并为epub交付给我`：执行两种输出

rules/translation_rules.md

@@ -0,0 +1,199 @@
+# 通用翻译规则
+
+这是一份给多线程轻小说翻译任务共用的规则文件。所有线程在开始工作前，都应先读取本文件，再读取当前系列的风格文件与术语表。
+
+## 适用范围
+
+- 适用于本工作流根目录下的所有系列与卷。
+- 适用于单线程翻译，也适用于拆分成多个线程的并行翻译、复审、封装任务。
+- 若某个系列有自己的 `series-style.md`，则以该系列风格文件为准，但不得覆盖本文件的硬性规则。
+
+## 标准目录
+
+```text
+<project-root>
+  <series-folder>\
+    mingcibiao.json
+    mingcibiao.ai.json
+    mingcibiao.candidates.json
+    series-style.md
+    <novel-folder>\
+      text\
+      preprocess_text\
+      trans_text\
+      final_text\
+      deliverables\
+```
+
+## 多 Agent 协作规则
+
+- 默认按“统筹、术语、首译、复审、格式恢复、QA、交付”分工；小任务可由一个 Agent 连续承担多个角色，但仍必须按阶段产出。
+- 每个 Agent 开工前必须确认当前系列、当前卷、输入路径、输出路径、chunk 范围和所读规则文件。
+- 每个线程只处理明确分配的卷、文件或 chunk 范围，不要跨卷混写。
+- 线程之间共享同一套系列术语表和系列风格文件。
+- 多线程任务中，所有线程都必须遵守相同的译名、标点、ruby、标签和交付规则。
+- 首译 Agent 不修改正式术语表；复审 Agent 不直接改源文；QA Agent 默认只报告，除非用户要求修复。
+- 并行 chunk 必须以段落编号作为边界，不得合并、拆分或重排段落。
+- 任何影响全卷一致性的判断，只能进入候选词、风格建议或 QA 报告，不能在单个 chunk 内私自固定。
+- 如果用户要求“继续”，且当前任务没有需要确认的风险点，可以直接接着做下一步。
+- 如果用户要求“自动输入继续”，则在任务完成并等待后续指令时，默认继续推进下一步，直到遇到必须确认的分歧或风险。
+
+## 术语规则
+
+- `mingcibiao.json` 是正式术语表，优先级最高。
+- `mingcibiao.candidates.json` 只放候选词，不直接当正式词表使用。
+- 用户确认后，先合并候选词，再进入锁词、翻译、复审流程。
+- 术语一旦锁定，所有线程都必须一致使用。
+- 若发现新术语且会影响一致性，先记录为候选词，不要在线程里擅自发明多个译名。
+
+### 术语命中规则
+
+术语命中必须以当前任务范围实时计算，不能把完整术语表塞进提示词。单段重翻只使用目标段落源文、ruby 与少量上下文中实际命中的术语；复审可额外参考当前译文中的旧译名或疑似不一致译名进行纠偏。
+
+命中优先级：
+
+1. `mingcibiao.json` 的精确源语 key 命中。
+2. 原文 ruby 中的 rb/rt 命中，尤其是技能名、称号、别名、外语读音和世界观术语。
+3. 正文中片假名、专名、组织名、地名、人名、带特殊标记的称谓命中。
+4. 当前译文中已出现的旧译名或疑似不一致译名，仅用于复审纠偏，不用于单段重翻扩展术语。
+5. `mingcibiao.candidates.json` 只作为候选参考，不能覆盖正式术语。
+
+这里的“命中”指目标文本与正式术语表 key、别名或 ruby 信息匹配。原文中出现但尚未进入正式术语表的片假名、专名或称谓，只能作为候选术语发现，不得作为固定译名硬约束写入 prompt。当前译文中的旧译名只用于发现不一致或疑似误译，不得反向触发源文未命中的术语提示。
+
+术语应用规则：
+
+- 正式术语表命中后，译文必须使用指定译名；除非上下文证明不是同一概念，才可标记为冲突并暂停确认。
+- value 中如含 `#` 备注，`#` 前作为译名，`#` 后作为说明，不得把说明直接写入正文。
+- 如果术语表写作 `中文(外语/读音)`，且原文对应有意义 ruby，最终 HTML 应恢复为真实 ruby，不保留括号形式。
+- 同一源语在同卷中不得出现多个译名；发现历史不一致时，复审阶段统一并记录。
+- 新术语只进入候选词表，候选项至少包含：源语、建议译名、出现位置、上下文、理由、是否含 ruby。
+
+## 系列风格规则
+
+- 每个系列都应拥有自己的 `series-style.md`。
+- 在开始首译之前确认 `series-style.md` 已存在且已填写完毕。
+- 如果当前系列没有 `series-style.md`，先在系列根目录生成一个，再要求填写该系列的风格内容后继续后续步骤。
+- 如果 `series-style.md` 为空、只有部分内容，或明显未完成，先提示用户确认是否继续。
+- 如果用户确认继续，则只以已填写的部分作为当前系列的风格约束；空白部分视为未指定，不要自行补写成固定规则。
+- 如果用户不确认继续，先补全系列风格，再进入候选词表或首译。
+- 系列风格文件应记录该系列的语气、叙述习惯、对话风格、术语偏好、标点偏好、双语版处理偏好和禁止事项。
+
+## 翻译流程
+
+### 1. 导入与预处理
+
+- 源文件若为 EPUB，先导入到对应系列与卷目录。
+- 预处理时保留段落编号、div 结构、ruby 信息和必要的标签。
+- 只对正文文本做翻译，不要破坏 HTML 结构。
+
+### 2. 候选词表
+
+- 先整理候选词表。
+- 用户确认后再合并成正式术语表。
+- 术语表更新后，再进行锁词。
+
+### 3. 首译
+
+- 首译前确认 `series-style.md` 已填写并与当前系列一致。
+- 如果不存在，先创建 `series-style.md`，写入系列风格模板，再暂停等待用户填写并确认。
+- 如果 `series-style.md` 为空或只有部分内容，先提示用户确认。
+- 用户确认继续后，只按已填写部分限定首译风格；空白项不额外施加约束。
+- 如果用户不确认继续，先补齐系列风格，再开始首译。
+- 只翻译锁词后的 chunk，不要回头直接改源 HTML。
+- 每个段落都要按中文自然语序重写，不要机械贴着日语句序。
+- 保留 `[Pxxxx]`、`<lk>...</lk>`、必要的 ruby 和 div 标记。
+
+### 4. 复审
+
+- 复审必须逐段检查，不可以只抽查。
+- 复审时以“源文 + 首译 + 中文自然度”三者一起判断。
+- 复审记录要完整覆盖全部段落。
+
+### 5. 恢复与校验
+
+- 复审完成后再恢复 HTML。
+- 最后必须做术语、残留日文、ruby、覆盖率检查。
+- 若有可修复的警报，优先修复后再交付。
+
+## 验收标准
+
+首译验收：
+
+- chunk 范围内所有 `[Pxxxx]` 均有对应译文。
+- 段落数量、顺序、编号不变。
+- 正式术语命中项全部使用统一译名。
+- 无明显漏译、整句日文残留、机器直译式语序。
+- 必要 HTML、ruby、`<lk>` 标签未被破坏。
+
+复审验收：
+
+- 逐段覆盖，不以抽查代替复审。
+- 每段同时检查源文、首译、术语和中文自然度。
+- 修正误译、漏译、术语不一致、角色口吻漂移、标点不统一、ruby 处理错误。
+- reviewed_chunks 可直接进入 HTML 恢复，不遗留“待确认”正文占位。
+
+交付验收：
+
+- final_text 段落覆盖率为 100%。
+- 残留日文只允许出现在双语日文层、必要 ruby rt 或用户确认保留的位置。
+- HTML 可解析，章节顺序、标题、图片、注释、ruby 和空段落正常。
+- 纯译版与中日双语版按用户要求生成，文件名、版本和输出目录清晰。
+- 如存在未修复风险，必须在交付说明中列出。
+
+## 中文风格
+
+- 输出必须是自然、流畅的简体中文轻小说文风。
+- 以意义优先，再调整成中文语序。
+- 不要保留日语式前置修饰和拖长句。
+- 不要把“看得懂”的汉字词直接照搬成中文。
+- 对话要符合角色性格，不要统一成同一种口吻。
+
+## Ruby 规则
+
+- 只在有意义时保留 `<ruby><rt>`。
+- 纯读音、无额外信息的 ruby，通常直接译成普通中文。
+- 隐含义、别名、外语读音、技能名、称号、世界观术语，应按需要保留为真实 ruby。
+- 不要把有意义的 ruby 改成括号。
+- 不要删除 `<rt>` 后再用猜测补回。
+- 如果术语表写作 `中文(外语/读音)`，且原文对应位置是有意义 ruby，最终 HTML 必须恢复为 `<ruby><rb>中文</rb><rt>外语/读音</rt></ruby>`，不要在正文中保留 `中文(外语/读音)` 括号形式。
+
+## 标签与格式
+
+- 保留 `[Pxxxx]` 段落编号。
+- 保留 `<lk>...</lk>` 块的内容一致性。
+- 保留必要的 HTML 结构，不要把标签当成普通文本改写。
+- 交付前检查段落、标题、ruby、空段落和灰字双语格式是否正确。
+
+## 双语交付
+
+- 用户说“生成双语版”时，默认执行双语封装。
+- 双语版规则：
+  - 日文保留在上或前一层。
+  - 日文用灰色字体显示。
+  - 中文译文紧随其后。
+  - 原始 HTML 结构尽量保持。
+- 用户说“生成翻译版”时，生成纯译文 EPUB。
+- 用户说“终交付封装”或“合并为epub交付给我”时，默认生成两份：
+  - 纯译文版
+  - 中日双语版
+
+## 推荐命令模板
+
+```powershell
+$env:PYTHONIOENCODING='utf-8'
+$env:SOURCE_EPUB='<source epub path>'
+$env:NOVEL_ROOT='<novel root path>'
+python '<project-root>\epub_delivery\build_epub_variants.py' --mode both
+```
+
+```powershell
+python '<project-root>\epub_delivery\build_epub_variants.py' --mode translated
+python '<project-root>\epub_delivery\build_epub_variants.py' --mode bilingual
+```
+
+## 默认响应
+
+- 当任务完成并等待下一步时，如果用户已经要求自动续跑，则继续下一步。
+- 如果需要用户确认，先暂停并说明原因。
+- 如果用户只说“继续”，则按当前上下文中的下一步执行，不重新解释整套流程。
+- 每次完成代码、文档或工作流更新后，先完成必要检查，再将当前仓库同步到 `https://git.diaomin.asia/` 对应远端；如果缺少远端地址、凭据或登录授权，先询问用户，不要静默跳过。

templates/continue_message_template.md

@@ -0,0 +1,28 @@
+# 继续推进模板
+
+把下面这段直接发给我，就可以继续当前卷的工作。
+
+```text
+继续
+
+请按当前阶段自动推进下一步。
+若当前步骤已完成且没有风险点，请直接进入下一步。
+若需要我确认名词表、规则冲突或交付形式，请先暂停说明。
+```
+
+## 常用补充
+
+```text
+继续执行
+继续翻译
+继续审核
+继续封装
+```
+
+## 推荐简版
+
+```text
+继续
+请自动推进到下一步。
+```
+

templates/delivery_message_template.md

@@ -0,0 +1,37 @@
+# 双语版与终交付模板
+
+把下面这段直接发给我，就可以进入封装交付。
+
+```text
+终交付封装
+
+请按当前卷的封装规则执行：
+1. 生成纯译版 EPUB
+2. 生成中日双语版 EPUB
+3. 如有需要，先修复影响封装的警报
+
+双语版要求：
+- 日文保留
+- 日文用灰色字体
+- 中文译文紧随其后
+
+如果当前卷已经有固定的封装脚本，请直接复用。
+如果需要重新生成，请先确认输出目录无误。
+```
+
+## 常用触发词
+
+```text
+生成双语版
+生成翻译版
+终交付封装
+合并为epub交付给我
+```
+
+## 推荐简版
+
+```text
+终交付封装
+请生成纯译版和中日双语版 EPUB。
+```
+

templates/new_volume_start_template.md

@@ -0,0 +1,96 @@
+# 新卷启动模板
+
+把这份文件当作新卷开工清单。新卷开始前，先确认本卷信息，再按下面的默认流程推进。
+
+## 你需要先给出的信息
+
+- 书名或 EPUB 文件名
+- 对应系列名
+- 卷名
+- 目标目录
+- 是否先做候选词表
+- 是否要中途停下来让我确认名词表
+- 是否需要双语版、纯译版，或两者都要
+
+## 开工前顺序
+
+1. 读取通用规则：[translation_rules.md](./translation_rules.md)
+2. 读取当前系列的 `series-style.md`
+3. 如果 `series-style.md` 不存在，先用 [series_style_template.md](./series_style_template.md) 生成一个，再要求填写
+4. 如果 `series-style.md` 为空、只有部分内容，或明显未完成，先提示确认是否继续
+5. 如果你确认继续，则只按已填写部分限定系列风格；空白部分视为未指定
+6. 确认当前系列目录和卷目录
+7. 确认术语表文件：
+   - `mingcibiao.json`
+   - `mingcibiao.ai.json`
+   - `mingcibiao.candidates.json`
+8. 确认本卷目录结构：
+   - `text`
+   - `preprocess_text`
+   - `trans_text`
+   - `final_text`
+   - `deliverables`
+
+## 默认工作流
+
+### 1. 仅做词表时
+
+- 扫描正文与 ruby。
+- 先整理 `mingcibiao.candidates.json`。
+- 不进入正文翻译。
+
+### 2. 用户确认后
+
+- 合并候选词。
+- 锁词。
+- 再开始翻译正文 chunk。
+
+### 3. 首译与复审
+
+- 首译只写 `trans_text/chunks`。
+- 首译前再次确认系列风格是否完整；如果只有部分内容，按已填写部分执行。
+- 复审写 `trans_text/reviewed_chunks`。
+- 复审必须逐段覆盖全部段落。
+
+### 4. 恢复与校验
+
+- 复审完成后再恢复 HTML。
+- 最后检查 ruby、术语残留、覆盖率、HTML 结构。
+
+### 5. 封装交付
+
+- 生成纯译版时，使用 `--mode translated`。
+- 生成双语版时，使用 `--mode bilingual`。
+- 两份都要时，使用 `--mode both`。
+
+## 你的常用触发词
+
+- `开始翻译`：开始正文翻译流程
+- `继续`：继续当前阶段的下一步
+- `生成双语版`：只生成中日双语 EPUB
+- `生成翻译版`：只生成纯译版 EPUB
+- `终交付封装`：生成两份 EPUB
+- `合并为epub交付给我`：生成两份 EPUB
+
+## 默认约定
+
+- 如果我已经完成当前步骤并在等待下一步，而你没有特别叫停，我会按上下文继续推进。
+- 如果涉及名词表或会影响全卷一致性的决策，我会先停下来让你确认。
+- 如果你没有特别说明，我默认：
+  - 先做候选词表，再翻译正文
+  - 最后交付纯译版和双语版
+
+## 推荐复制模板
+
+你每开一卷时，可以直接发：
+
+```text
+新卷：
+书名：
+系列：
+卷名：
+目录：
+是否先做候选词表：是 / 否
+是否中途确认名词表：是 / 否
+交付方式：纯译版 / 双语版 / 两者都要
+```

templates/series_style_template.md

@@ -0,0 +1,75 @@
+# 系列风格模板
+
+把这份文件复制为当前系列根目录下的 `series-style.md`，并按系列实际情况填写。
+
+## 基本信息
+
+- 系列名：
+- 系列简称：
+- 适用卷范围：
+- 风格负责人：
+- 最近更新时间：
+
+## 叙述风格
+
+- 整体语气：
+- 叙述节奏：
+- 句子长短偏好：
+- 常用视角：
+- 叙事温度：
+
+## 对话风格
+
+- 角色口吻差异：
+- 礼貌与粗口尺度：
+- 幽默、吐槽、卖萌、傲娇等表达偏好：
+- 对话标点偏好：
+
+## 术语与译名
+
+- 固定术语偏好：
+- 人名、地名、组织名的译法：
+- 技能名、称号、武器名的译法：
+- 日文保留、音译、意译的优先级：
+
+## 标点与格式
+
+- 句末标点偏好：
+- 省略号、破折号、感叹号、问号偏好：
+- 书名号、引号、括号使用习惯：
+- 双语版灰字处理偏好：
+
+## Ruby 处理偏好
+
+- 何种 ruby 应保留：
+- 何种 ruby 可直接转成普通中文：
+- 外语读音或隐藏含义的处理方式：
+
+## 禁止事项
+
+- 不希望出现的翻译腔：
+- 不希望出现的固定误译：
+- 本系列禁止照搬的表达：
+
+## 参考片段
+
+### 原文片段 1
+
+-
+
+### 推荐译法 1
+
+-
+
+### 原文片段 2
+
+-
+
+### 推荐译法 2
+
+-
+
+## 备注
+
+- 如果后续又确认了新的固定译法，请及时补充到这里。
+- 本文件是系列级别的风格依据，不要与其他系列混用。

templates/startup_message_template.md

@@ -0,0 +1,48 @@
+# 启动消息模板
+
+把下面这段直接发给我，就可以作为新卷开工消息。
+
+```text
+新卷启动
+书名：
+系列：
+卷名：
+源文件：
+工作目录：
+
+先做候选词表：是 / 否
+名词表确认后再开始正文：是 / 否
+是否允许我说“继续”后自动推进：是 / 否
+交付方式：纯译版 / 双语版 / 两者都要
+
+若有专用规则文件，请先读取：
+1. 通用规则：<project-root>/translation_rules.md
+2. 新卷模板：<project-root>/new_volume_start_template.md
+
+请先检查目录与术语表，再按当前阶段执行。
+```
+
+## 常用追加指令
+
+```text
+开始翻译
+继续
+生成双语版
+生成翻译版
+终交付封装
+合并为epub交付给我
+```
+
+## 推荐简版
+
+```text
+新卷启动：
+书名：<填写>
+系列：<填写>
+卷名：<填写>
+源文件：<填写>
+工作目录：<填写>
+先做候选词表：是
+名词表确认后再开始正文：是
+交付方式：两者都要
+```

tools/epub_review_editor/LONG_TERM_MEMORY.md

@@ -0,0 +1,33 @@
+# EPUB 审校器长期维护记忆
+
+## 稳定规则
+
+- 继续审校器开发、跨线程接力或上下文压缩后恢复任务时，先读 `AGENTS.md`、`rules/translation_rules.md`、`tools/epub_review_editor/MAINTENANCE.md` 和本文件。
+- 每次完成代码、文档或工作流更新后，按维护手册运行相关检查，提交并推送到 `https://git.diaomin.asia/akai/-----.git`；需要登录或凭据时先问用户。
+- 审校器版本遵守语义化：PATCH 修 bug，MINOR 新增向后兼容能力，MAJOR 才做破坏性行为变更。
+- 用户明确要求长期多 Agent 协作；审校器开发默认按后端/API、前端交互、文档/工作流、QA 验收拆分。
+
+## 用户偏好
+
+- UI 要遵循第一性原理：减少无意义入口，统计口径必须清楚，翻译相关设置应围绕“源文、命中术语、少量上下文、角色口吻、输出格式”组织。
+- 术语不可全局硬塞进 prompt；例如 Falchion/ファルシオン 只有命中时才提示，译名使用“大砍刀”，不要译成“偃月刀”。
+- 长篇 EPUB 优先阅读友好、章节可导航、编辑反馈能沉淀到后续翻译优化。
+
+## 当前架构状态
+
+- `0.13.1` 当前版本建立在元数据书架上：`/api/sessions` 与 `/api/library` 生成 `library.json`，书籍会带 `metadata`、`series_id`、`cover_url` 等字段；书架删除是软删除，只隐藏 session，不删除原始 EPUB。
+- 同系列配置存放在 `epub_review_sessions/series_configs/<series-id>.json`，只保存术语表路径和三段提示词，不保存 API Key。
+- 整书翻译源抽取不使用双语审校的 `rows.json`；`rows.json` 是审校行数，日语 EPUB 的可翻译数量看 `/api/session/<id>/translation-source`，UI 文案应称为“正文块”以避免和双语审校“段”混淆。
+- 翻译源统计应区分可翻译正文块、HTML 文件、正文段、标题、图片、目录和空白块；默认试译只翻译前 20 段/块，不代表源书被删。
+- 翻译页默认应保持克制，只显示源书名和可翻译正文块数量；冗余段落预览、诊断 note 和大批统计 chip 不应默认出现在 UI。
+
+## 已知排查结论
+
+- `TRPGプレイヤーが異世界で最強ビルドを目指す 3` 日版 EPUB 解包内容未被删除。此前用户看到数量偏少，原因是 UI 混用了双语审校 `row_count` 与日语源书 `source_count`，且试译 job 的 `total=25` 只是范围限制。
+- 当前修复后，该 session 的可翻译源正文块为 `2949`，统计包含 `3084` 个候选块、`3083` 个 `<p>`、`1` 个标题、`27` 个图片块、`7` 个目录块和 `129` 个空白块。
+- 2026-07-08 修复整书翻译重复层：如果输入已经是中日双语 EPUB，翻译源抽取只把显式灰色/source 源段作为 item，并记录下一段中文 pair；双语输出替换旧中文层，纯中文输出移除对应日文层。`build_rows()` 也收敛为只接受显式灰色/source 标记，不再因含假名就把普通段落当源文。
+
+## 下次优先检查
+
+- 若用户继续优化书架视觉，优先检查真实浏览器中的封面网格、悬停遮罩、移动端按钮可见性和长书名溢出。
+- 若用户继续优化翻译流程，优先检查同系列配置是否正确覆盖翻译页和后台 job，且不会把系列 prompt 保存进全局 `gpt_config.json`。

tools/epub_review_editor/MAINTENANCE.md

@@ -0,0 +1,280 @@
+# EPUB 审校器长期维护手册
+
+## 目标与边界
+
+本工具服务于中日双语 EPUB 的网页审校：长篇连续阅读、逐段修改中文译文、标记翻译问题、导出反馈与修订 EPUB。它也提供可选的书架入口 AI 翻译模块，用于对已入书架的日语 EPUB 发起 API 辅助首译，并生成中日双语或纯中文 EPUB。翻译质量规则仍由项目根目录的 `AGENTS.md`、`rules/translation_rules.md`、当前系列的 `series-style.md` 与术语表共同约束。
+
+AI 翻译模块是可选辅助首译入口，不替代长期项目里的候选词确认、复审、QA 与正式交付流程。用户在网页中留下的编辑、问题备注、长期规则建议，需要由 Codex 后续读取反馈文件后再沉淀到系列风格或候选术语中。网页术语表编辑是用户显式操作正式术语表的入口，保存时会直接写入配置路径指向的 JSON 文件。
+
+## 数据模型与会话目录
+
+`--review-root` 是唯一需要备份的运行数据目录。典型结构：
+
+```text
+epub_review_sessions/
+  app_state.json
+  gpt_config.json
+  library.json
+  series_configs/
+    <series-id>.json
+  translation_jobs/
+    <job-id>/
+      job.json
+      translations.json
+  translated_outputs/
+    *_AI翻译_*.epub
+  <session-id>/
+    source.epub
+    extracted/
+    review_state/
+      epub_entries.json
+      rows.json
+      session.json
+      state.json
+    feedback/
+      translation_feedback.jsonl
+      feedback_for_codex.md
+    exports/
+```
+
+兼容要求：
+
+- `rows.json` 是初始解析结果，不应因用户编辑而重写。
+- `state.json.edits` 保存用户修改与标记，字段缺省时必须能回退到原始译文。
+- `state.json.reading_position` 保存当前阅读位置，字段包括 `mode`、`scope`、`chapter_id`、`part_id`、`image_item_id`、`row_id`、`scroll_top`、`offset`、`updated_at`；缺省时必须回退到首页/首章。
+- `session.json` 与 `app_state.json` 只保存会话定位信息。
+- `gpt_config.json` 只属于本地运行环境，不写入 EPUB、不写入导出文件、不通过 API 回传密钥。
+- `gpt_config.json` 可保存本地提示词设置与术语表路径，但仍不得写入 EPUB 或导出文件。
+- `library.json` 是由 EPUB 元数据和会话状态生成的书架索引，可重建；字段包括书籍、系列、作者、出版社、语言、封面和更新时间。
+- `series_configs/<series-id>.json` 保存同系列共享的 `glossary_path`、`translation_prompt`、`format_prompt`、`character_prompt`，不得保存 API Key、Base URL 或模型密钥。
+- `translation_jobs/<job-id>/job.json` 保存整书 AI 翻译任务状态、进度、输出路径和日志；不得保存 API Key。
+- `translated_outputs/` 保存 AI 翻译生成的 EPUB；生成后应创建独立 session，使 `/api/sessions` 和书架自然可见。
+- 项目根目录的 `打开EPUB审校器.cmd` 是用户一键入口，委托 `tools/epub_review_editor/open_editor.ps1` 创建 `.venv`、安静检测 Flask 依赖、缺失时自动安装依赖、复用同版本已运行服务或启动 `server.py --daemon` 并打开浏览器；该入口不得硬编码用户私有路径。
+
+## 目录与插图
+
+结构接口 `/api/structure` 应保持向后兼容：
+
+- text chapter: `kind: "text"`、`parts`、`row_count`、`touched_count`、`marked_count`
+- image item: 优先作为 text chapter 的 `items` 子项返回，字段为 `kind: "image"`、`images`、`parts: []`、`row_count: 0`；没有所属文字章时才保留顶层 image chapter
+- 统计字段同时保留总数和细分：`chapter_count`、`text_chapter_count`、`image_chapter_count`、`top_level_image_chapter_count`、`image_count`、`asset_count`。其中 `image_chapter_count` 表示目录里的图片条目数，不一定是顶层章节数
+- part 标题默认使用 `part0000` 形式，真实标题可保留在 `source_title`
+- 插图通过 `/api/asset/<entry>` 读取，必须继续使用 `extracted_path()` 防止路径穿越；只把 raster 图片纳入 `/api/structure` 与 `/api/asset` 白名单，不能任意读取解包目录文件
+
+章节来源优先级：
+
+1. EPUB 内部目录页的中文条目
+2. `nav.xhtml` / `toc.xhtml`
+3. 正文 `<h1-6>` 标题
+4. 文件名 fallback
+
+不要把正文首段或第一句对白作为章节标题 fallback。宁可显示 `part0000`，也不要让目录被正文内容污染。
+
+## 阅读与侧栏交互
+
+验收口径：
+
+- 顶栏左上角必须保留“书架”入口；书架是独立页面，列出 `--review-root` 下历史打开过的审校书籍/会话。
+- 点击书架条目必须通过会话打开流程进入对应审校页面，并恢复该书上次阅读位置；从审校页进入书架或切换书籍前必须保存当前阅读位置并沿用未保存编辑保护。
+- 没有历史书籍时，书架显示空状态并提供“打开新的 EPUB”入口；开始页/书架页顶栏保持正常显示，不套用审校页沉浸隐藏。
+- 书架应按 EPUB 元数据建立分类：全部书籍、同系列、作者、出版社、语言；同系列分类使用稳定 `series_id`，显示书籍数量。
+- 书架主区域以封面网格为主，不用横向信息卡替代封面；无封面时使用稳定 fallback，不出现破图或布局跳动。
+- 鼠标悬停或键盘 focus 到封面时，封面变暗并显示书名、系列/作者/卷数、审校段数、最近更新时间，以及“校对”“翻译”“删除”按钮；点击“翻译”或“删除”不得触发“校对”。
+- 书架删除默认是软删除：只在 session manifest/state 中写入 `hidden` / `deleted_at`，从 `/api/sessions` 与 `/api/library` 隐藏，不删除原始 EPUB、导出 EPUB 或反馈文件；删除 active session 时必须清空 `active_session_id`。
+- 选中同系列分类后，必须能打开“系列设置”，设置该系列共享的术语表路径、翻译内容提示词、格式提示词和角色口吻提示词。
+- 初始进入审校时，左侧侧栏隐藏，正文占主要空间。
+- 顶部“目录”只打开目录，“检索”只打开搜索/段落列表，不合并成一个常驻面板。
+- 目录可展开/收起章节，插图作为所属章节的次级目录条目可点击阅读，文字 part 可点击定位。
+- 点击目录章节、part 或插图条目后，侧栏不得自动收起；用户仍可点“隐藏”或按 `Escape` 关闭。
+- 检索必须保留“当前范围 / 全书全局”切换；当前范围随当前章节或 part 更新，全局检索可跨章节返回并跳转。
+- 阅读模式不显示每段编号、快速编辑、快速标记按钮。
+- 阅读区提供默认、护眼、夜间背景切换，并允许调整字号与行距；设置可保存在浏览器本地，不要求写入 EPUB 或 session。
+- 审校页顶部标题栏与阅读标题栏默认收起，鼠标移到页面上方或键盘焦点进入标题栏时再显示；开始页保持正常显示；展开后不得遮住侧栏“隐藏”或审校工具“关闭”等面板操作。
+- 鼠标停留在顶栏或阅读标题栏时，沉浸顶栏不得因自动计时过早收起；前端脚本和样式发布时应带版本参数或等效缓存失效机制，避免浏览器继续执行旧入口代码。
+- 阅读区“上一节 / 下一节”必须按 spine/目录内的小章节顺序移动，覆盖文字 part 与插图条目，不得只跳顶层大章节。
+- 点击正文段落打开右侧精修与重翻面板。
+- 右侧面板打开或关闭导致正文宽度变化时，应恢复用户原来正在看的段落位置。
+- 刷新页面、重启服务或从已有会话重新打开 EPUB 时，应恢复到上次阅读的章节/part/插图、段落和滚动位置。
+- 移动窄屏下，侧栏和右侧面板应以抽屉/底部面板方式显示，不遮死主要操作。
+
+## 编辑、反馈与导出
+
+保存本段时必须：
+
+- sanitize 中文 HTML，但允许 `ruby/rb/rt/rp/mark/span` 等必要内联标签。
+- 记录 `before_cn_html`、`after_cn_html`、问题类型、严重程度、标签、备注、长期规则建议。
+- 更新 `feedback/translation_feedback.jsonl`。
+
+生成反馈时必须：
+
+- 写入 `feedback_for_codex.md`。
+- 只汇总已编辑、已标记或有备注的段落。
+- 保留日文原文、修改前、修改后，便于后续翻译规则复盘。
+
+导出 EPUB 前必须先写回已保存的译文修改，插图文件保持原样。
+
+## GPT 重翻
+
+GPT 能力是可选增强，不应影响离线审校。
+
+安全与配置：
+
+- 支持 OpenAI 兼容的 `base_url`、`model`、`api_key`。
+- 支持单独设置 `translation_prompt`、`format_prompt`、`character_prompt`；缺省时必须回退到内置预设。
+- API Key 优先读取 `gpt_config.json`，也支持环境变量 `OPENAI_API_KEY`。
+- `/api/gpt/config` 不得返回 API Key。
+- `/api/gpt/config` 可以返回提示词与预设，但不得返回密钥。
+- `/api/glossary` 读取和保存配置路径指向的 `mingcibiao.json`；默认路径应由当前打开 EPUB 对应的系列目录或用户保存的配置决定，不应在通用维护口径中硬编码某个具体系列。
+- 未保存配置时，可在项目根目录下唯一的一级系列目录 `mingcibiao.json` 中自动推断默认术语表；若无法唯一推断，则回退到项目根目录 `mingcibiao.json` 并允许用户在网页中显式设置。
+- 术语表保存应保持 JSON 对象结构：key 为源语或匹配词，value 为译名，可继续使用 `#` 作为备注分隔。
+- 重翻时必须实时读取术语表，按目标段落日文纯文本、日文 HTML 与 ruby/rt 命中相关条目，不得只在提示词里泛泛要求“遵守术语表”。
+- 未配置 Key 时，重翻接口应返回可读错误，不影响编辑保存。
+- 重翻请求不得临时覆盖 `base_url` 或 `model` 后继续复用已保存密钥；要更换端点或模型必须先保存配置，避免把密钥发往未确认端点。
+
+单段重翻流程：
+
+1. 用户点击阅读段落，打开右侧面板。
+2. 用户可填写额外重翻要求。
+3. `/api/row/<row_id>/retranslate` 使用提示词、目标语句、实时命中的术语表条目、同文件前后一段少量上下文、角色口吻提示生成候选。
+4. 候选只显示在面板里，不自动覆盖。
+5. 用户点击“应用重翻”后写入编辑框，再点击保存才进入审校记录。
+6. 候选事件写入 jsonl，便于后续根据精修反馈优化提示词；当前版本不自动改写提示词。
+
+术语实时命中实现口径：
+
+- 每次 `/api/row/<row_id>/retranslate` 请求都必须读取当前配置的 glossary 文件，不使用服务启动时的缓存作为唯一来源。
+- 单段重翻的术语命中范围只包括目标段落日文纯文本和日文 HTML 中的可见文本/ruby/rb/rt 信息；当前中文译文不能反向触发新术语，避免把旧误译或幻觉带入 prompt。
+- 传给 GPT 的目标日文 HTML 只保留必要内联标签和 ruby 结构，不携带 class/style/data-* 等属性，避免属性值污染术语命中或 prompt。
+- 前后一段上下文只用于语气、指代和连贯性参考，不参与单段重翻的术语命中；单段重翻的 `glossary_matches` 只由目标段落自身触发。
+- 正式术语表 value 如包含 `#`，`#` 前是指定译名，`#` 后只是备注，不写入正文。
+- 未命中术语时，重翻 prompt 不得塞入无关术语兜底规则；例如只有原文出现 `ファルシオン` 或 `Falchion` 时，才可命中“大砍刀”。
+- 读取旧版保存提示词时，若只剩“优先服从给定名词表”这类泛泛规则，应回退到当前内置预设，避免用户继续沿用已淘汰的全局术语设计。
+- 任何术语特例都不得写入全局 prompt。Falchion / ファルシオン / 大砍刀 只能由 `glossary_matches` 动态生成；未命中时，重翻 messages 中不得出现这些字符串。
+- 命中结果必须随候选事件写入 jsonl，字段至少包含 `glossary_path` 与 `glossary_matches`；未命中时记录空数组，便于排查 prompt。
+
+Prompt 第一性原理：
+
+- prompt 必须只携带目标段落、少量上下文、命中术语、系列风格摘要和输出格式；单段重翻不携带完整术语表。
+- prompt 不得只泛泛要求遵守术语表，必须列出本段命中的具体术语；未命中的术语不得进入提示。
+- prompt 必须要求只输出修订后的中文 HTML，不输出说明。
+- prompt 必须要求不合并、不拆分段落，不删除段落编号或必要标签。
+- prompt 必须要求保留有意义 ruby 为真实 `<ruby><rb>...</rb><rt>...</rt></ruby>`。
+
+Prompt 硬规则：
+
+- 输出简体中文轻小说文风。
+- 意义优先，不贴日语语序硬译。
+- 不合并、不拆分段落。
+- 有意义 ruby 必须保留为真实 `<ruby><rb>...</rb><rt>...</rt></ruby>`，不要改成括号。
+- 标点统一为简中出版格式：对话引号用「」，省略号用……，破折号用——，问号用？，感叹号用！，问叹连用用？！/！？。
+
+## 整书 AI 翻译
+
+整书 AI 翻译从书架页进入，只处理已经上传或打开过、因此已有 session 的 EPUB。它必须作为后台任务运行，前端只负责创建任务、轮询进度、展示日志和打开输出 session。
+
+后端接口口径：
+
+- `GET /api/translation/defaults` 返回当前公开 GPT 配置、默认提示词、默认术语表路径、默认范围和输出模式，不返回 API Key。
+- `GET /api/session/<session_id>/translation-source` 只读取指定 session，统计可翻译日文正文块和样例，不切换 active session；必须同时返回诊断统计，说明审校行数、可翻译正文块、图片、目录、空白块不是同一口径。
+- `GET /api/library` 与 `GET /api/sessions` 返回按 EPUB 元数据生成的书架索引、系列列表和封面 URL。
+- `GET/POST /api/series/<series_id>/config` 读写同系列翻译配置；空字段表示未设置，不能自动写入全局默认 prompt。
+- `POST /api/translation/start` 创建后台任务并快速返回 `job_id`；请求不得临时覆盖 `base_url` 或 `model` 后复用已保存密钥，要更换端点或模型必须先保存配置。
+- `GET /api/translation/jobs/<job_id>` 返回任务状态、进度、日志、输出 EPUB 和输出 session id，不返回 API Key。
+
+翻译输入与提示词：
+
+- 日语源 EPUB 需要新的源段落抽取器，不复用只识别双语灰字的 `build_rows()`。
+- 翻译源抽取器至少覆盖 `<p>` 与正文 `<h1-h6>`；日文上下文中的纯汉字/标点短句应进入翻译队列，纯图片、空白和目录页不进入。
+- 默认范围必须是前 N 段试译，当前默认 20 段；全书翻译必须由用户显式选择。
+- 每段请求只携带目标段落日文 HTML、前后一段少量上下文、该段实时命中的术语、翻译提示词、格式提示词与角色口吻提示词。
+- 不得把完整术语表塞进 prompt；未命中的术语不得进入 prompt。
+- 若同系列配置存在，整书翻译优先使用同系列的术语表路径和提示词；API Key、Base URL、模型仍使用全局 API 配置。
+- 输出只接受当前段中文 HTML 片段，随后进行中文标点规整、HTML sanitize 与术语 ruby 括号形式修复。
+
+输出与书架：
+
+- `bilingual` 模式在原日文 `<p>` 后插入中文 `<p>`，并把原日文段落标为灰色且标记为 source，方便进入现有双语审校器逐段审校。
+- 如果输入已经是中日双语 EPUB，翻译源抽取必须识别显式灰色/source 源段与下一段中文译文的 pair；`bilingual` 模式应替换已有中文层，不得追加第二个中文层；`translated` 模式应输出新的中文层并移除对应日文源层。
+- 如果历史 session 已经出现“日文源层 + 中文层 + 旧中文灰色源层 + 新中文层”的四层坏结构，进入翻译源统计、整书翻译或 rows 重建前应自动清理为“日文源层 + 第一个中文层”，避免旧中文继续被当作日文源文。
+- `translated` 模式用中文替换原日文段落；该输出会加入书架，但由于没有日中成对段落，可能没有逐段双语审校行。
+- 图片、样式、OPF、spine 和非正文文件应原样保留。
+- 翻译失败的单段必须写入可见占位和任务日志，不能让整本输出静默缺段。
+- 输出 EPUB 创建 session 时不应自动切换用户当前 active session；只有用户点击“打开输出审校”才切换。
+
+任务安全与恢复：
+
+- 后台 job 不能在网络调用期间持有全局锁；只在写状态文件时短暂加锁或原子写入。
+- `job.json` 和中间 `translations.json` 必须原子写入，避免前端轮询读到半截 JSON。
+- 日志、状态、EPUB 元数据和反馈文件不得包含 API Key。
+- 任务失败时应将状态置为 `failed` 并写清楚错误，不能让前端永久停在 running。
+- 后续如加入暂停/取消/恢复，必须保持现有 `job.json` 字段向后兼容。
+
+## 版本规则
+
+版本号使用 `version = "0.1.0"` 格式：
+
+| 层级 | 触发条件 |
+| --- | --- |
+| PATCH | 修复 bug 或兼容性小修 |
+| MINOR | 新增向后兼容能力、API 字段或可选配置 |
+| MAJOR | 破坏兼容的 API、配置或行为变更 |
+
+发版时必须同步：
+
+- `version.py`
+- `static/index.html` 顶部版本徽标 fallback
+- `README.md` 当前版本与版本说明
+- 必要时同步 `MAINTENANCE.md` 中的维护口径
+
+版本文档同步边界：
+
+- 审校器自身行为、API、配置、前端交互变化，同步本文件。
+- 会影响整个翻译项目的规则变化，同步项目根目录 `AGENTS.md` 与 `rules/translation_rules.md`，不要只写在审校器维护手册中。
+- 对外最小包内容、启动方式或发布说明变化，同步 README。
+
+## 回归清单
+
+每轮改动至少检查：
+
+- `python -m py_compile tools/epub_review_editor/server.py tools/epub_review_editor/version.py`
+- `node --check tools/epub_review_editor/static/app.js`
+- `powershell -NoProfile -ExecutionPolicy Bypass -File tools/epub_review_editor/open_editor.ps1` 能启动服务并打印 URL
+- 从项目根目录执行 `打开EPUB审校器.cmd` 能启动服务；失败时窗口停留并显示错误；成功时浏览器打开书架/上传页
+- 重复执行一键入口时优先复用同版本已运行服务；如需新起服务，端口探测不得允许多个服务同时监听同一端口
+- `git diff --check`
+- `/api/version`
+- `/api/session`
+- `/api/structure`
+- `/api/gpt/config`
+- 首个插图 `/api/asset/...` 返回 200 且浏览器可显示
+- 非白名单或非 raster asset 不能被 `/api/asset/...` 读取
+- 目录按钮、检索按钮、隐藏侧栏、点击段落打开右侧面板
+- 阅读段落下方没有编号和“快速编辑/快速标记”
+- 未配置 API Key 时重翻返回清晰错误
+- 配置保存后 `/api/gpt/config` 不包含密钥字段
+- `/api/glossary` 能读取术语表；新增、修改、删除条目后保存，再读取内容一致
+- 重翻候选事件包含 `glossary_path` 与 `glossary_matches`
+- 无关段落的重翻 messages 不得包含 `大砍刀`、`Falchion` 或 `ファルシオン`；含 `ファルシオン` 或 ruby `Falchion` 的段落必须命中“大砍刀”
+- 顶栏复杂操作收敛在“审校工具”入口；未选择段落时仍可配置 AI、术语表并执行反馈与交付，段落编辑/重翻按钮禁用
+- `/api/reading-position` 能保存/读取位置；刷新或重启后回到上次阅读处
+- 阅读外观默认/护眼/夜间、字号、行距切换即时生效，刷新后仍保留；夜间模式下正文、原文、按钮和侧栏文本可读
+- 审校页顶部栏和阅读标题栏默认不遮挡正文，鼠标移到页面上方后可操作；开始页顶栏不隐藏；目录侧栏和审校工具打开时，其顶部按钮仍可直接点击
+- 鼠标停留在顶栏按钮区域时，书架/打开 EPUB/审校工具按钮能连续点击，不会在点击前自动收起；浏览器重新加载后应使用当前版本 app.js/style.css
+- “上一节 / 下一节”在相邻 part 和章节内插图之间移动，不再按顶层大章节跳转
+- 顶栏左上角“书架”能打开独立书架页；书架列出历史会话，空状态可进入上传页，点击书籍可进入对应审校页并恢复阅读位置
+- 书架左侧分类可按全部书籍、同系列、作者、出版社、语言筛选；右侧封面网格在桌面端悬停变暗显示信息和“校对/翻译”，移动端不依赖 hover 才能操作
+- `GET /api/sessions` 和 `GET /api/library` 返回 `library`、`series`、书籍元数据、`series_id`、`cover_url`，并写入可重建的 `library.json`
+- `GET/POST /api/series/<series_id>/config` 能读写同系列术语表和提示词；保存后同系列其他书进入翻译页会自动套用
+- 书架卡片“翻译”按钮能进入独立翻译页，且不会触发卡片的“进入审校”
+- `/api/translation/defaults` 不返回 API Key，提示词和术语表路径可读取
+- `/api/session/<session_id>/translation-source` 能统计日语 EPUB 可翻译正文块和诊断字段；非日语或无正文时返回清晰空状态；审校行数、源正文块数、试译 limit 不得在 UI 上混为一个“段落数”
+- 翻译页默认只显示源书名和“可翻译正文块 N 个”，不保留冗余段落预览、诊断 note 或大批统计 chip 的可见入口；诊断字段可保留在 API 中供排查
+- 未配置 API Key 时，`/api/translation/start` 返回清晰错误，不影响阅读、编辑、导出和单段重翻
+- 启动整书翻译任务后，`/api/translation/jobs/<job_id>` 可看到 pending/running/completed/failed、总段数、已完成数、当前文件和日志
+- 默认翻译范围是前 20 段试译；全书翻译必须由用户显式切换并确认
+- 整书翻译每段只注入该段源文/ruby 命中的术语，不注入无关术语或全表
+- 整书翻译完成后，输出 EPUB 写入 `translated_outputs/` 并自动出现在书架；中日双语输出打开后 `row_count > 0`
+- 已双语 EPUB 再次执行整书翻译时，输出不得出现“旧中文译文 + 新中文译文”重复层；审校行 `jp_text` 不得变成中文旧译文
+- 纯中文输出可以加入书架，且文档说明其不适合逐段双语审校
+- 离开翻译页、返回书架或打开输出审校时，前端进度轮询会停止
+- 书架卡片“删除”按钮能软删除会话、刷新书架、清空 active session（如删除当前书），且不会删除原始 EPUB 文件

tools/epub_review_editor/README.md

@@ -1,9 +1,90 @@
 # 双语 EPUB 审校编辑器
 
+当前版本：`0.13.1`
+
 这个工具用于把生成后的中日双语 EPUB 打开成浏览器审校界面。用户可以直接修改中文译文，也可以标记“哪里翻得不好”，并把所有记录沉淀为可交给 Codex 的反馈文件。
 
+## 版本规则
+
+维护版本号使用 `version = "0.1.0"` 这种语义化格式：
+
+| 层级 | 触发条件 |
+| --- | --- |
+| PATCH | 修复 bug 或兼容性小修 |
+| MINOR | 新增向后兼容能力、API 字段或可选配置 |
+| MAJOR | 破坏兼容的 API、配置或行为变更 |
+
+本次从 `0.1.0` 升到 `0.2.0`，因为新增了独立上传、会话管理、下载接口与可选 `--host` 配置，且保持原命令行 EPUB 路径用法兼容。
+
+`0.2.1` 修复目录章节识别：优先读取 EPUB 内部目录页的中文标题，并把目录锚点之间的多个正文 part 合并为同一章；左侧目录增加章节展开/收起按钮。
+
+`0.3.0` 新增插图阅读能力：目录中会把 EPUB spine 里的插图页作为独立章节显示，阅读模式可直接查看图片；正文子章节标题统一使用 `part0000` 这类规整编号，方便长篇审校快速定位。
+
+`0.4.0` 新增阅读型交互与 GPT 重翻：左侧目录/检索改为按需打开的独立侧栏；阅读模式去掉每段下方操作按钮，点击段落直接打开右侧精修与重翻面板，并在面板挤开正文后恢复原阅读位置；本地可配置 OpenAI 兼容 GPT API，对单段生成重翻候选，确认后再应用到编辑框。
+
+`0.4.1` 修复后端/API 安全与结构细节：章节内插图与文字按 spine 顺序 flush，结构统计补充 text/image 细分字段；内部目录识别增加目录页/链接密度判定；结构和 `/api/asset` 仅允许已识别的 raster 图片并加 `nosniff`；重翻接口不再允许单次请求临时覆盖 Base URL 或模型后复用已保存密钥。
+
+`0.5.0` 改进长篇目录与检索：目录章节标题不再用正文首段猜测，章节内插图作为次级条目挂在所属章节下，阅读时可按原 spine 顺序穿插显示；点击目录不会自动收起侧栏，桌面端正文会为常驻侧栏让位；检索新增“当前范围 / 全书全局”切换。
+
+`0.6.0` 新增 GPT 提示词设置：可在网页中单独配置“翻译内容提示词”“格式与标点提示词”“角色状态与口吻提示词”，并提供默认预设；单段重翻只携带目标语句、相关名词表、少量前后文和角色口吻提示，候选输出会进行中文标点规整与术语 ruby 括号形式修正。
+
+`0.7.0` 新增实时术语表能力：GPT 重翻会从配置的 `mingcibiao.json` 实时读取命中术语并写入提示词；网页中可查看当前术语表路径、搜索术语，新增、修改、删除条目并保存，保存后的术语会立即用于下一次重翻。
+
+`0.8.0` 新增阅读位置恢复：阅读器会自动记录当前章节/part/插图、当前可见段落和滚动位置；重新打开服务、刷新页面或切回已有会话时，会回到上次阅读的位置。
+
+`0.9.0` 收敛重翻与审校工具入口：顶栏复杂操作统一到“审校工具”；单段重翻只携带目标段落真实命中的术语，移除无关段落里的 Falchion/大砍刀全局注入，并按第一性原理精简 prompt。
+
+`0.10.0` 新增阅读外观与沉浸阅读：阅读区可切换默认、护眼、夜间背景，并保存字号与行距；审校页顶部栏和阅读标题栏默认收起，鼠标移到页面上方时再显示；阅读区上一节/下一节按 part 或插图小章节移动。
+
+`0.11.0` 新增书架页面：顶栏左上角提供“书架”入口，集中列出历史打开过的审校书籍；点击书籍可直接进入对应审校页面，并继续沿用该书的上次阅读位置。
+
+`0.11.1` 修复沉浸顶栏在鼠标停留时过早收起的问题，并给前端静态资源加入版本参数，避免浏览器缓存旧脚本导致新入口不可用。
+
+`0.12.0` 新增书架入口的 AI 翻译模块：可从书架选择日语 EPUB，设置 OpenAI 兼容 API、提示词、术语表、翻译范围与输出模式，后台显示翻译进度；完成后生成的中日双语或纯中文 EPUB 会自动加入书架。
+
+`0.12.1` 新增一键启动入口：项目根目录提供 `打开EPUB审校器.cmd`，会自动准备本地 Python 环境、安装依赖并以前台浏览器打开书架/上传页。
+
+`0.12.2` 修复一键启动入口首次运行时依赖检测会被 Flask 缺失的 traceback 中断的问题；现在会先安静检测依赖，缺失时自动安装，再启动网页工具。重复打开入口时会优先复用同版本已运行服务，并修正端口探测，避免多个服务同时监听同一端口。
+
+`0.13.0` 新增元数据书架与同系列配置：书架按 EPUB 元数据建立 `library.json`，左侧提供系列、作者、出版社、语言分类，封面悬停显示书籍信息以及“校对/翻译”入口；同系列可共享术语表路径、翻译内容提示词、格式提示词和角色口吻提示词。AI 翻译源统计改为正文块诊断，区分审校行数、可翻译日文正文块、图片、目录和空白块，并补翻日文标题与日语上下文里的短句，避免把默认试译范围误认为正文被删。
+
+`0.13.1` 修复整书 AI 翻译重复正文块：已是中日双语的 EPUB 再翻译时会识别旧的日文源文/中文译文 pair，并替换中文层，不再把旧译文当成源文追加新译文；审校行识别也收敛为只接受显式灰色/source 标记。翻译页删除冗余段落预览和诊断提示，统一使用“正文块”口径，书架封面悬停菜单新增“删除”，可从书架软删除会话且不删除原始 EPUB。
+
+## 独立安装
+
+这个审校器现在可以脱离 Codex 使用，只需要 Python 和浏览器。把 `tools/epub_review_editor` 目录复制到其他电脑或服务器后，在该目录里安装依赖：
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\python -m pip install -r requirements.txt
+```
+
+Linux/macOS：
+
+```bash
+python3 -m venv .venv
+./.venv/bin/python -m pip install -r requirements.txt
+```
+
 ## 启动
 
+最方便的方式是在项目根目录双击：
+
+```text
+打开EPUB审校器.cmd
+```
+
+第一次运行会在 `tools/epub_review_editor/.venv` 创建本地 Python 环境并安装依赖；之后会直接启动服务并打开浏览器。
+
+不预先指定 EPUB，直接打开上传界面：
+
+```powershell
+$env:PYTHONIOENCODING='utf-8'
+python 'C:\Users\xin61\Documents\轻小说翻译持续改进\tools\epub_review_editor\server.py'
+```
+
+也可以像原来一样直接打开某个 EPUB：
+
 ```powershell
 $env:PYTHONIOENCODING='utf-8'
 python 'C:\Users\xin61\Documents\轻小说翻译持续改进\tools\epub_review_editor\server.py' '<中日双语版.epub>' --daemon
@@ -15,12 +96,40 @@ python 'C:\Users\xin61\Documents\轻小说翻译持续改进\tools\epub_review_e
 http://localhost:5177
 ```
 
+局域网或服务器部署时，把监听地址改为 `0.0.0.0`，并把审校数据目录固定到一个你会备份的位置：
+
+```powershell
+python .\server.py --host 0.0.0.0 --port 5177 --review-root .\epub_review_sessions
+```
+
+当前版本没有登录鉴权，不要直接暴露到公网。需要远程使用时，优先放在可信局域网、VPN、反向代理鉴权或 SSH 隧道后面。
+
+## 浏览器上传 EPUB
+
+- 启动时不带 EPUB 路径，会进入开始页。
+- 点击“选择 EPUB 文件”，上传中日双语 EPUB 后会自动创建审校会话。
+- 开始页会列出已有会话，换电脑或重启服务后可以继续打开之前的审校记录。
+- 顶栏左上角“书架”会列出历史打开过的书籍，并按 EPUB 元数据生成分类；点击封面或“校对”会进入对应审校页面。
+- 书架中每本书封面悬停会变暗并显示书籍信息、“校对”“翻译”和“删除”按钮；“翻译”可对日语 EPUB 发起 AI 翻译任务，输出 EPUB 会自动加入书架；“删除”只会从书架隐藏审校会话，不删除原始 EPUB。
+- 上传的 EPUB、解包副本、反馈与导出文件都会保存在 `--review-root` 指定目录下。
+
 ## 能做什么
 
 - 阅读模式下按章节连续阅读日文原文与中文译文，不需要逐句点击。
-- 左侧目录按 EPUB nav/toc 或 spine 文件顺序组织章节；章节下显示内部 part，点击 part 后只看该 part，点击章节则看整章连续正文。
-- 在阅读模式中点击段落即可打开快速审校面板，直接编辑中文译文或标记问题。
+- 顶栏左上角可进入“书架”，集中查看历史打开过的书籍、审校进度和最近阅读记录；书架左侧可按全部书籍、同系列、作者、出版社和语言分类，右侧以封面网格显示书籍。
+- 阅读区可切换默认、护眼、夜间背景，并调整字号与行距；设置会保存在当前浏览器中，下次打开继续沿用。
+- 审校页顶部标题栏与阅读标题栏默认隐藏，鼠标移到页面上方时显示，减少长文阅读时的遮挡。
+- 阅读区“上一节 / 下一节”按 part 或插图小章节移动，不再只跳顶层大章节。
+- 每个审校会话会自动保存上次阅读位置，下次打开会回到上次所在章节、part、插图或段落附近。
+- 左侧目录和检索默认隐藏，通过顶部“目录”“检索”两个按钮分别打开，不会把两种入口混在同一个常驻侧栏里。
+- 目录优先按 EPUB 内部目录页或 nav/toc 组织章节；章节下显示内部 `part0000` 形式的 part 与次级插图条目，可展开/收起，点击 part 后只看该 part，点击章节则按原 spine 顺序连续阅读正文和插图。
+- 插图页会作为所属章节的次级条目出现在目录里，点击后可在阅读模式中直接查看原 EPUB 图片；点击目录项不会自动隐藏左侧侧栏。
+- 检索支持“当前范围”和“全书全局”两种范围，适合在单章精查和整本书排查术语时切换。
+- 在阅读模式中点击段落即可打开右侧精修与重翻面板，直接编辑中文译文、标记问题或调用 GPT 重翻；打开/关闭面板时会尽量保持原来的阅读位置。
 - 精修模式保留原有逐段编辑界面，用于较细的逐段复审。
+- 可从“审校工具”统一配置 OpenAI 兼容的 `base_url`、`model`、API Key、重翻提示词与术语表，并对当前段落生成重翻候选；候选不会自动覆盖正文，需要点击“应用重翻”并保存。
+- 可在“审校工具”的“AI 设置与术语表”里配置并读取正式术语表，实时搜索、增删改术语并保存；单段重翻会按当前段落命中术语表条目，而不是只在提示词里泛泛要求遵守术语。
+- 可从书架进入“AI 翻译 EPUB”页面，对日语 EPUB 设置翻译内容提示词、格式与标点提示词、角色口吻提示词、术语表路径、翻译范围、输出为中日双语或纯中文 EPUB；同系列书籍会优先套用系列提示词和术语表配置，任务在后台运行，页面实时显示进度与日志。
 - 直接编辑中文译文。
 - 标记问题段落或选中文本。
 - 记录问题类型、严重程度、标签、备注和可沉淀的长期规则。
@@ -30,7 +139,13 @@ http://localhost:5177
 
 ## 重要输出
 
-每个 EPUB 会建立独立审校 session，默认位于：
+每个 EPUB 会建立独立审校 session。通过浏览器上传时，默认位于：
+
+```text
+epub_review_sessions\<timestamp>_<epub-name>_<hash>\
+```
+
+通过命令行直接指定 EPUB 时，仍沿用固定路径：
 
 ```text
 epub_review_sessions\<epub-name>_<hash>\
@@ -43,18 +158,31 @@ epub_review_sessions\<epub-name>_<hash>\
 - `exports/*_网页审校版_*.epub`：导出的修订版 EPUB。
 - `review_state/state.json`：网页编辑器当前状态。
 - `extracted/`：EPUB 解包后的工作副本。
+- `translation_jobs/<job-id>/job.json`：AI 翻译任务状态、进度和日志。
+- `translated_outputs/*_AI翻译_*.epub`：AI 翻译模块生成并自动加入书架的 EPUB。
+- `library.json`：按 EPUB 元数据生成的书架索引，包含书籍、系列和封面信息。
+- `series_configs/*.json`：同系列共享的提示词与术语表路径配置，不包含 API Key。
+
+在服务器上使用时，“生成反馈”和“导出审校 EPUB”会返回浏览器可访问的下载地址，不需要登录服务器找文件。
 
 ## 使用建议
 
 - 正式长篇 EPUB 优先使用“阅读模式”：先在左侧点章节/part 连续读，看到问题再点段落快速编辑或标记。
+- 同时审校多本书时，优先从顶栏左上角进入“书架”，再选择目标书籍；从书架进入会恢复该书上次阅读位置。
 - 需要集中逐段复审时切到“精修模式”，左侧段落列表会跟随当前章节筛选。
 - 只想记录问题时：勾选“标记为翻译问题”，写备注，保存本段。
 - 想直接修正译文时：编辑中文译文后保存本段。
-- 想让 Codex 学习你的偏好时：把“可沉淀为长期规则”写具体，例如“Falchion 固定译为大砍刀，不要译成偃月刀”。
+- 想让 Codex 学习你的偏好时：把“可沉淀为长期规则”写具体，例如“某个术语只在原文实际出现时才进入重翻提示”。
+- 想单段重翻时：点击段落打开“审校工具”，先在“AI 设置与术语表”中保存 GPT 配置；提示词分为翻译内容、格式标点、角色口吻三块，可恢复预设。术语表路径会从当前项目中可唯一识别的系列 `mingcibiao.json` 推断，也可以改成其他 `mingcibiao.json`。再点“重翻本段”；满意后点“应用重翻”，最后保存本段记录。
+- 想整书 AI 翻译时：先上传或打开日语 EPUB，让它出现在书架里；在书架封面悬停后点击“翻译”，保存 API 设置，并在系列设置里保存该系列术语表和提示词。默认先做前 20 段试译，确认效果后再把范围切换为全书。中日双语输出可直接进入审校；纯中文输出会入书架，但没有逐段双语审校行。
+- 术语表路径默认会从当前项目中可唯一识别的系列 `mingcibiao.json` 推断；如果无法唯一推断，请在页面里填写目标术语表路径。
+- 想调整术语时：打开“审校工具”的“AI 设置与术语表”，在术语表区域搜索、修改或新增条目，点击“保存术语表”；下一次重翻会重新读取已保存的最新术语。
 - 审校结束后点击“生成反馈”，再在聊天里告诉 Codex 读取 `feedback_for_codex.md` 和 `translation_feedback.jsonl`。
 
 ## 当前限制
 
 - 当前解析规则针对本项目的“日文灰字 + 中文紧随其后”的双语 EPUB。
-- 目录用于审校导航，不负责可视化修改 EPUB 的图片、目录和 OPF 元数据。
+- AI 翻译模块是可选辅助首译入口，不替代正式长卷的候选词确认、复审和 QA；默认试译前 20 段，避免误触发全书 API 成本。
+- 目录用于审校导航；插图可以阅读和跳转，但当前版本不提供图片内容编辑。
+- GPT API Key、提示词与术语表路径仅保存在 `--review-root` 下的本地 `gpt_config.json`，接口不会回传密钥；重翻时只能使用已保存的 Base URL 和模型，避免把密钥发往未确认端点。术语表编辑会直接写入配置路径指向的 JSON 文件，服务器部署时请保护好审校目录和术语表，不要把没有鉴权的服务暴露到公网。
 - 浏览器内保存的是审校工作副本；要生成 EPUB 文件，需要点击“导出审校 EPUB”。

tools/epub_review_editor/open_editor.ps1

@@ -0,0 +1,134 @@
+$ErrorActionPreference = "Stop"
+
+$toolRoot = Split-Path -Parent $PSCommandPath
+$projectRoot = (Resolve-Path (Join-Path $toolRoot "..\..")).Path
+$serverPath = Join-Path $toolRoot "server.py"
+$reviewRoot = Join-Path $projectRoot "epub_review_sessions"
+$venvRoot = Join-Path $toolRoot ".venv"
+$venvPython = Join-Path $venvRoot "Scripts\python.exe"
+$requirements = Join-Path $toolRoot "requirements.txt"
+$versionFile = Join-Path $toolRoot "version.py"
+$defaultPort = 5177
+
+$env:PYTHONIOENCODING = "utf-8"
+
+function Get-PythonCommand {
+  $pyLauncher = Get-Command py -ErrorAction SilentlyContinue
+  if ($pyLauncher) {
+    return [pscustomobject]@{ Exe = $pyLauncher.Source; Args = @("-3") }
+  }
+
+  $python = Get-Command python -ErrorAction SilentlyContinue
+  if ($python) {
+    return [pscustomobject]@{ Exe = $python.Source; Args = @() }
+  }
+
+  throw "Python was not found. Install Python 3, then run this launcher again."
+}
+
+function Invoke-PythonCommand {
+  param(
+    [Parameter(Mandatory = $true)]
+    [string]$Exe,
+    [string[]]$Args = @()
+  )
+
+  & $Exe @Args
+  return $LASTEXITCODE
+}
+
+function Test-FlaskInstalled {
+  & $venvPython -c "import importlib.util, sys; sys.exit(0 if importlib.util.find_spec('flask') else 1)" 2>$null
+  return ($LASTEXITCODE -eq 0)
+}
+
+function Get-ExpectedVersion {
+  if (!(Test-Path $versionFile)) {
+    return ""
+  }
+  $content = Get-Content -Raw -Encoding UTF8 $versionFile
+  $match = [regex]::Match($content, 'version\s*=\s*"([^"]+)"')
+  if ($match.Success) {
+    return $match.Groups[1].Value
+  }
+  return ""
+}
+
+function Test-LocalPortOpen {
+  param(
+    [Parameter(Mandatory = $true)]
+    [int]$Port
+  )
+
+  $client = New-Object System.Net.Sockets.TcpClient
+  try {
+    $async = $client.BeginConnect("127.0.0.1", $Port, $null, $null)
+    if (!$async.AsyncWaitHandle.WaitOne(100, $false)) {
+      return $false
+    }
+    $client.EndConnect($async)
+    return $true
+  } catch {
+    return $false
+  } finally {
+    $client.Close()
+  }
+}
+
+function Get-RunningEditorUrl {
+  $expectedVersion = Get-ExpectedVersion
+  for ($port = $defaultPort; $port -lt ($defaultPort + 100); $port++) {
+    if (!(Test-LocalPortOpen -Port $port)) {
+      continue
+    }
+    $url = "http://127.0.0.1:$port"
+    try {
+      $versionPayload = Invoke-RestMethod -Uri "$url/api/version" -TimeoutSec 1 -ErrorAction Stop
+      if (!$expectedVersion -or $versionPayload.version -eq $expectedVersion) {
+        return "http://localhost:$port"
+      }
+    } catch {
+      continue
+    }
+  }
+  return ""
+}
+
+$runningUrl = Get-RunningEditorUrl
+if ($runningUrl) {
+  Write-Host "EPUB review editor is already running."
+  Start-Process $runningUrl
+  Write-Host $runningUrl
+  Write-Host "review root: $reviewRoot"
+  exit 0
+}
+
+if (!(Test-Path $venvPython)) {
+  Write-Host "Creating local Python environment..."
+  $python = Get-PythonCommand
+  $venvArgs = @()
+  if ($python.Args) {
+    $venvArgs += $python.Args
+  }
+  $venvArgs += @("-m", "venv", $venvRoot)
+  if ((Invoke-PythonCommand -Exe $python.Exe -Args $venvArgs) -ne 0) {
+    throw "Failed to create local Python environment."
+  }
+}
+
+if (!(Test-FlaskInstalled)) {
+  Write-Host "Installing review editor dependencies..."
+  & $venvPython -m pip install -r $requirements
+  if ($LASTEXITCODE -ne 0) {
+    throw "Failed to install dependencies from requirements.txt."
+  }
+  if (!(Test-FlaskInstalled)) {
+    throw "Dependencies were installed, but Flask is still unavailable in the local Python environment."
+  }
+}
+
+Write-Host "Starting EPUB review editor..."
+& $venvPython $serverPath --review-root $reviewRoot --daemon
+if ($LASTEXITCODE -ne 0) {
+  throw "Failed to start EPUB review editor."
+}

tools/epub_review_editor/requirements.txt

@@ -0,0 +1 @@
+Flask>=3.0,<4.0

tools/epub_review_editor/static/index.html

@@ -4,12 +4,13 @@
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>双语 EPUB 审校编辑器</title>
-  <link rel="stylesheet" href="/static/style.css">
+  <link rel="stylesheet" href="/static/style.css?v=0.13.1">
 </head>
 <body>
   <header class="topbar">
+    <button id="bookshelfBtn" class="bookshelfNavButton" type="button">书架</button>
     <div class="brandBlock">
-      <h1>双语 EPUB 审校编辑器</h1>
+      <h1>双语 EPUB 审校编辑器 <span id="appVersion" class="versionBadge">v0.13.1</span></h1>
       <p id="sessionMeta">正在载入……</p>
     </div>
     <div class="modeTabs" role="tablist" aria-label="审校模式">
@@ -17,21 +18,245 @@
       <button id="polishModeBtn" class="modeButton" type="button">精修模式</button>
     </div>
     <div class="toolbar">
-      <button id="showTouchedBtn" type="button">仅看已记录</button>
-      <button id="feedbackBtn" type="button">生成反馈</button>
-      <button id="applyBtn" type="button">写回 EPUB 内容</button>
-      <button id="exportBtn" type="button">导出审校 EPUB</button>
+      <button id="tocPanelBtn" type="button">目录</button>
+      <button id="searchPanelBtn" type="button">检索</button>
+      <button id="openLibraryBtn" type="button">打开 EPUB</button>
+      <button id="reviewToolsBtn" type="button">审校工具</button>
     </div>
   </header>
 
-  <main class="layout">
-    <aside class="sidebar">
-      <div class="searchbox">
-        <input id="searchInput" type="search" placeholder="搜索原文、译文、备注">
+  <main class="bookshelfScreen" id="bookshelfScreen" hidden>
+    <div class="libraryShell">
+      <aside class="librarySidebar" aria-label="书架分类">
+        <div class="libraryBrandRow">
+          <button id="libraryMenuBtn" class="iconTextButton" type="button">☰</button>
+          <strong>Starrea</strong>
+        </div>
+        <label class="librarySearchLabel">
+          <span>搜索</span>
+          <input id="bookshelfSearchInput" type="search" placeholder="搜索书名、作者、系列">
+        </label>
+        <nav class="libraryFacetList" id="bookshelfFacetList"></nav>
+        <div class="librarySidebarFooter">
+          <button id="bookshelfRefreshBtn" type="button">刷新</button>
+          <button id="bookshelfOpenUploadBtn" class="primary" type="button">导入 EPUB</button>
+        </div>
+      </aside>
+      <section class="bookshelfPanel">
+        <div class="bookshelfHeader">
+          <div>
+            <h2 id="bookshelfTitle">全部书籍</h2>
+            <p id="bookshelfDescription">按 EPUB 元数据建立书架，封面悬停可直接进入审校或翻译。</p>
+          </div>
+          <div class="bookshelfActions">
+            <button id="seriesConfigBtn" type="button" disabled>系列设置</button>
+            <button id="bookshelfOpenUploadBtnInline" class="primary" type="button">打开新的 EPUB</button>
+          </div>
+        </div>
+        <div class="bookshelfMeta" id="bookshelfMeta">正在读取书架……</div>
+        <div class="bookshelfGrid" id="bookshelfList"></div>
+      </section>
+    </div>
+  </main>
+
+  <aside class="seriesConfigDrawer" id="seriesConfigDrawer" hidden>
+    <div class="seriesConfigHeader">
+      <div>
+        <h2 id="seriesConfigTitle">系列设置</h2>
+        <p id="seriesConfigMeta">同系列书籍会优先共用这里的提示词和术语表。</p>
       </div>
-      <div class="stats" id="stats"></div>
-      <nav class="toc" id="toc" aria-label="章节目录"></nav>
-      <div class="rowList" id="rowList"></div>
+      <button id="closeSeriesConfigBtn" type="button">关闭</button>
+    </div>
+    <label>
+      术语表路径
+      <input id="seriesGlossaryPathInput" type="text" placeholder="mingcibiao.json 的完整路径或项目内相对路径">
+    </label>
+    <label>
+      翻译内容提示词
+      <textarea id="seriesTranslationPromptInput" rows="5"></textarea>
+    </label>
+    <label>
+      格式与标点提示词
+      <textarea id="seriesFormatPromptInput" rows="5"></textarea>
+    </label>
+    <label>
+      角色状态与口吻提示词
+      <textarea id="seriesCharacterPromptInput" rows="4"></textarea>
+    </label>
+    <div class="seriesConfigActions">
+      <button id="saveSeriesConfigBtn" class="primary" type="button">保存系列设置</button>
+    </div>
+  </aside>
+
+  <main class="translationScreen" id="translationScreen" hidden>
+    <section class="translationPanel">
+      <div class="translationHeader">
+        <div>
+          <h2>AI 翻译 EPUB</h2>
+          <p id="translationBookMeta">选择书架中的 EPUB 后设置范围、输出格式和必要提示词。</p>
+        </div>
+        <div class="translationHeaderActions">
+          <button id="translationBackBookshelfBtn" type="button">返回书架</button>
+          <button id="translationOpenReviewBtn" class="primary" type="button" disabled>打开输出审校</button>
+        </div>
+      </div>
+
+      <section class="translationGrid">
+        <form class="translationSettings" id="translationForm">
+          <section class="translationCard">
+            <div class="sectionTitle compactTitle">
+              <h2>输出与范围</h2>
+              <span id="translationSourceMeta">未读取源书信息</span>
+            </div>
+            <div class="translationOptions">
+              <label>
+                输出格式
+                <select id="translationOutputModeInput">
+                  <option value="bilingual">中日双语 EPUB</option>
+                  <option value="translated">纯中文 EPUB</option>
+                </select>
+              </label>
+              <label>
+                翻译范围
+                <select id="translationRangeModeInput">
+                  <option value="limit">前 N 个正文块试译</option>
+                  <option value="all">全书</option>
+                </select>
+              </label>
+              <label>
+                正文块数
+                <input id="translationLimitInput" type="number" min="1" max="5000" value="20">
+              </label>
+              <label>
+                Temperature
+                <input id="translationTemperatureInput" type="number" min="0" max="1" step="0.1" value="0.2">
+              </label>
+            </div>
+          </section>
+
+          <section class="translationCard">
+            <div class="sectionTitle compactTitle">
+              <h2>API 与术语表</h2>
+              <span id="translationGptStatus">未读取配置</span>
+            </div>
+            <div class="translationOptions apiOptions">
+              <label>
+                Base URL
+                <input id="translationBaseUrlInput" type="url" placeholder="https://api.openai.com/v1">
+              </label>
+              <label>
+                Model
+                <input id="translationModelInput" type="text" placeholder="gpt-4o-mini">
+              </label>
+              <label>
+                API Key
+                <input id="translationApiKeyInput" type="password" placeholder="留空则保留已有密钥">
+              </label>
+              <label>
+                术语表路径
+                <input id="translationGlossaryPathInput" type="text" placeholder="mingcibiao.json 的完整路径或项目内相对路径">
+              </label>
+            </div>
+            <div class="translationActions">
+              <button id="translationSaveConfigBtn" type="button">保存 API 设置</button>
+            </div>
+          </section>
+
+          <section class="translationCard">
+            <div class="sectionTitle compactTitle">
+              <h2>提示词</h2>
+              <button id="translationResetPromptsBtn" type="button">恢复预设</button>
+            </div>
+            <label>
+              翻译内容提示词
+              <textarea id="translationPromptInput" rows="5"></textarea>
+            </label>
+            <label>
+              格式与标点提示词
+              <textarea id="translationFormatPromptInput" rows="5"></textarea>
+            </label>
+            <label>
+              角色状态与口吻提示词
+              <textarea id="translationCharacterPromptInput" rows="4"></textarea>
+            </label>
+            <div class="translationActions">
+              <button id="translationStartBtn" class="primary" type="submit">开始翻译</button>
+            </div>
+          </section>
+        </form>
+
+        <aside class="translationProgressCard">
+          <div class="sectionTitle compactTitle">
+            <h2>翻译进度</h2>
+            <span id="translationJobMeta">尚未开始</span>
+          </div>
+          <div class="translationProgress">
+            <div class="translationProgressBar" id="translationProgressBar"></div>
+          </div>
+          <div class="translationProgressText" id="translationProgressText">等待开始翻译。</div>
+          <div class="translationOutput" id="translationOutput" hidden></div>
+          <div class="translationLogs" id="translationLogs"></div>
+        </aside>
+      </section>
+    </section>
+  </main>
+
+  <main class="startScreen" id="startScreen" hidden>
+    <section class="startPanel">
+      <div class="startHeader">
+        <div>
+          <h2>打开中日双语 EPUB</h2>
+          <p>上传一个“日文灰字 + 中文译文紧随其后”的双语 EPUB，审校记录会保存在本机或服务器的审校目录中。</p>
+        </div>
+        <button id="refreshSessionsBtn" type="button">刷新会话</button>
+      </div>
+
+      <form class="uploadBox" id="uploadForm">
+        <label class="fileDrop" for="epubFileInput">
+          <span class="fileDropTitle">选择 EPUB 文件</span>
+          <span class="fileDropName" id="selectedFileName">尚未选择文件</span>
+          <input id="epubFileInput" type="file" accept=".epub,application/epub+zip">
+        </label>
+        <button id="uploadBtn" class="primary" type="submit">上传并开始审校</button>
+      </form>
+
+      <section class="sessionBrowser">
+        <div class="sectionTitle compactTitle">
+          <h2>已有审校会话</h2>
+          <span id="sessionListMeta"></span>
+        </div>
+        <div class="sessionList" id="sessionList"></div>
+      </section>
+    </section>
+  </main>
+
+  <main class="layout" id="reviewLayout" hidden>
+    <aside class="sidebar" id="sidebar" hidden>
+      <div class="sideHeader">
+        <strong id="sideTitle">目录</strong>
+        <button id="closeSidebarBtn" type="button" aria-label="隐藏侧栏">隐藏</button>
+      </div>
+      <section class="tocPanel" id="tocPanel">
+        <div class="tocToolbar" aria-label="目录操作">
+          <strong>章节目录</strong>
+          <div>
+            <button id="expandTocBtn" type="button">展开全部</button>
+            <button id="collapseTocBtn" type="button">收起</button>
+          </div>
+        </div>
+        <nav class="toc" id="toc" aria-label="章节目录"></nav>
+      </section>
+      <section class="searchPanel" id="searchPanel" hidden>
+        <div class="searchbox">
+          <input id="searchInput" type="search" placeholder="搜索原文、译文、备注">
+          <div class="searchScope" role="group" aria-label="检索范围">
+            <button id="searchScopeCurrentBtn" type="button" class="active">当前范围</button>
+            <button id="searchScopeBookBtn" type="button">全书全局</button>
+          </div>
+        </div>
+        <div class="stats" id="stats"></div>
+        <div class="rowList" id="rowList"></div>
+      </section>
     </aside>
 
     <section class="readerPane" id="readerPane">
@@ -41,8 +266,25 @@
           <h2 id="readerTitle">选择章节开始阅读</h2>
         </div>
         <div class="readerTools">
-          <button id="prevPartBtn" type="button">上一章</button>
-          <button id="nextPartBtn" type="button">下一章</button>
+          <div class="appearanceControls" aria-label="阅读外观">
+            <div class="themeSwitch" role="group" aria-label="背景模式">
+              <button id="themeDefaultBtn" type="button" data-reader-theme="default">默认</button>
+              <button id="themeEyeBtn" type="button" data-reader-theme="eye">护眼</button>
+              <button id="themeNightBtn" type="button" data-reader-theme="night">夜间</button>
+            </div>
+            <label class="readerSlider">
+              <span>字号</span>
+              <input id="readerFontSizeInput" type="range" min="15" max="24" step="1" value="17">
+              <output id="readerFontSizeValue">17</output>
+            </label>
+            <label class="readerSlider">
+              <span>行距</span>
+              <input id="readerLineHeightInput" type="range" min="1.6" max="2.4" step="0.05" value="1.95">
+              <output id="readerLineHeightValue">1.95</output>
+            </label>
+          </div>
+          <button id="prevPartBtn" type="button">上一节</button>
+          <button id="nextPartBtn" type="button">下一节</button>
         </div>
       </div>
       <article class="readingFlow" id="readingFlow"></article>
@@ -117,7 +359,7 @@
           </label>
           <label>
             可沉淀为长期规则
-            <textarea id="learnNoteInput" rows="3" placeholder="例：Falchion 固定译为大砍刀，不要译成偃月刀。"></textarea>
+            <textarea id="learnNoteInput" rows="3" placeholder="例：某个术语只在原文实际出现时才进入重翻提示。"></textarea>
           </label>
         </section>
 
@@ -130,66 +372,143 @@
     </section>
   </main>
 
-  <aside class="quickEditor" id="quickEditor" hidden aria-label="快速审校面板">
+  <aside class="quickEditor" id="quickEditor" hidden aria-label="审校工具面板">
     <div class="quickHeader">
       <div>
         <div class="rowId" id="quickRowId"></div>
         <div class="rowPath" id="quickRowPath"></div>
       </div>
-      <button id="closeQuickEditorBtn" type="button" aria-label="关闭快速审校">关闭</button>
+      <button id="closeQuickEditorBtn" type="button" aria-label="关闭审校工具">关闭</button>
     </div>
-    <details class="quickSourceWrap" open>
+    <details class="toolSection quickSourceWrap" open>
       <summary>日文原文</summary>
       <section class="quickSource" id="quickJpText"></section>
     </details>
-    <label class="quickField">
-      中文译文
-      <div id="quickCnEditor" class="cnEditor quickCnEditor" contenteditable="true" spellcheck="false"></div>
-    </label>
-    <div class="quickControls">
-      <label class="markToggle">
-        <input id="quickMarkedInput" type="checkbox">
-        标记问题
+    <details class="toolSection" open>
+      <summary>当前段</summary>
+      <label class="quickField">
+        中文译文
+        <div id="quickCnEditor" class="cnEditor quickCnEditor" contenteditable="true" spellcheck="false"></div>
       </label>
-      <select id="quickIssueTypeInput">
-        <option value="">问题类型</option>
-        <option value="误译">误译</option>
-        <option value="漏译">漏译</option>
-        <option value="术语不一致">术语不一致</option>
-        <option value="人名/地名问题">人名/地名问题</option>
-        <option value="翻译腔">翻译腔</option>
-        <option value="角色口吻不对">角色口吻不对</option>
-        <option value="语序不顺">语序不顺</option>
-        <option value="标点/格式">标点/格式</option>
-        <option value="其他">其他</option>
-      </select>
-      <select id="quickSeverityInput">
-        <option value="">严重程度</option>
-        <option value="轻微">轻微</option>
-        <option value="中等">中等</option>
-        <option value="严重">严重</option>
-      </select>
-    </div>
-    <label class="quickField">
-      标签
-      <input id="quickTagsInput" type="text" placeholder="例：术语, 对话">
-    </label>
-    <label class="quickField">
-      问题备注
-      <textarea id="quickCommentInput" rows="3" placeholder="哪里翻得不好，或应该如何改。"></textarea>
-    </label>
-    <label class="quickField">
-      可沉淀为长期规则
-      <textarea id="quickLearnNoteInput" rows="2" placeholder="可复用的翻译偏好或禁忌。"></textarea>
-    </label>
-    <div class="quickActions">
-      <button id="quickMarkSelectionBtn" type="button">标记选中文本</button>
-      <button id="quickSaveBtn" type="button">保存</button>
-      <button id="quickOpenFullBtn" type="button">进入精修</button>
-    </div>
+      <div class="quickControls">
+        <label class="markToggle">
+          <input id="quickMarkedInput" type="checkbox">
+          标记问题
+        </label>
+        <select id="quickIssueTypeInput">
+          <option value="">问题类型</option>
+          <option value="误译">误译</option>
+          <option value="漏译">漏译</option>
+          <option value="术语不一致">术语不一致</option>
+          <option value="人名/地名问题">人名/地名问题</option>
+          <option value="翻译腔">翻译腔</option>
+          <option value="角色口吻不对">角色口吻不对</option>
+          <option value="语序不顺">语序不顺</option>
+          <option value="标点/格式">标点/格式</option>
+          <option value="其他">其他</option>
+        </select>
+        <select id="quickSeverityInput">
+          <option value="">严重程度</option>
+          <option value="轻微">轻微</option>
+          <option value="中等">中等</option>
+          <option value="严重">严重</option>
+        </select>
+      </div>
+      <label class="quickField">
+        标签
+        <input id="quickTagsInput" type="text" placeholder="例：术语, 对话">
+      </label>
+      <label class="quickField">
+        问题备注
+        <textarea id="quickCommentInput" rows="3" placeholder="哪里翻得不好，或应该如何改。"></textarea>
+      </label>
+      <label class="quickField">
+        可沉淀为长期规则
+        <textarea id="quickLearnNoteInput" rows="2" placeholder="可复用的翻译偏好或禁忌。"></textarea>
+      </label>
+      <div class="quickActions">
+        <button id="quickMarkSelectionBtn" type="button">标记选中文本</button>
+        <button id="quickSaveBtn" type="button">保存当前段</button>
+        <button id="quickOpenFullBtn" type="button">打开完整精修</button>
+      </div>
+    </details>
+    <section class="gptBox toolSection" id="gptBox">
+      <div class="gptConfigTitle">AI 重翻</div>
+      <div class="gptStatus" id="gptStatus">未读取配置</div>
+      <label class="quickField">
+        重翻要求
+        <textarea id="gptInstructionInput" rows="2" placeholder="可选：这次希望更口语、更忠实，或特别注意某个术语。"></textarea>
+      </label>
+      <div class="gptActions">
+        <button id="retranslateBtn" type="button">重翻本段</button>
+        <button id="applyRetranslationBtn" type="button" disabled>应用重翻</button>
+      </div>
+      <div class="gptCandidate" id="gptCandidate" hidden></div>
+    </section>
+    <details class="toolSection gptConfig" id="gptConfig" open>
+      <summary>AI 设置与术语表</summary>
+        <div class="gptConfigGroup">
+          <div class="gptConfigTitle">API</div>
+          <label>
+            Base URL
+            <input id="gptBaseUrlInput" type="url" placeholder="https://api.openai.com/v1">
+          </label>
+          <label>
+            Model
+            <input id="gptModelInput" type="text" placeholder="gpt-4o-mini">
+          </label>
+          <label>
+            API Key
+            <input id="gptApiKeyInput" type="password" placeholder="留空则保留已有密钥">
+          </label>
+          <label>
+            术语表路径
+            <input id="glossaryPathInput" type="text" placeholder="mingcibiao.json 的完整路径或项目内相对路径">
+          </label>
+        </div>
+        <div class="gptConfigGroup">
+          <div class="gptConfigTitle">提示词</div>
+          <label>
+            翻译内容提示词
+            <textarea id="gptTranslationPromptInput" rows="5" placeholder="设置忠实度、文风、术语优先级等内容要求。"></textarea>
+          </label>
+          <label>
+            格式与标点提示词
+            <textarea id="gptFormatPromptInput" rows="5" placeholder="设置 HTML、ruby、标点替换与输出格式规则。"></textarea>
+          </label>
+          <label>
+            角色状态与口吻提示词
+            <textarea id="gptCharacterPromptInput" rows="4" placeholder="设置角色状态、性格口吻、对话风格判断规则。"></textarea>
+          </label>
+        </div>
+        <div class="gptConfigGroup glossaryGroup">
+          <div class="gptConfigTitle">术语表</div>
+          <div class="glossaryMeta" id="glossaryMeta">未读取术语表</div>
+          <div class="glossaryTools">
+            <input id="glossarySearchInput" type="search" placeholder="搜索原文、译名或备注">
+            <button id="reloadGlossaryBtn" type="button">重新读取</button>
+            <button id="addGlossaryEntryBtn" type="button">新增术语</button>
+            <button id="saveGlossaryBtn" type="button" disabled>保存术语表</button>
+          </div>
+          <div class="glossaryList" id="glossaryList"></div>
+        </div>
+        <div class="gptConfigActions">
+          <button id="resetGptPromptsBtn" type="button">恢复预设提示词</button>
+          <button id="saveGptConfigBtn" type="button">保存 AI 设置</button>
+        </div>
+    </details>
+    <details class="toolSection" open>
+      <summary>反馈与交付</summary>
+      <div class="deliveryActions">
+        <button id="showTouchedBtn" type="button">仅看已记录</button>
+        <button id="feedbackBtn" type="button">生成反馈文件</button>
+        <button id="applyBtn" type="button">写回 EPUB 内容</button>
+        <button id="exportBtn" type="button">导出审校 EPUB</button>
+      </div>
+    </details>
   </aside>
 
   <div class="toast" id="toast" hidden></div>
-  <script src="/static/app.js"></script>
+  <script src="/static/app.js?v=0.13.1"></script>
 </body>
 </html>

tools/epub_review_editor/version.py

@@ -0,0 +1,7 @@
+version = "0.13.1"
+
+VERSION_RULES = {
+    "PATCH": "修复 bug 或兼容性小修",
+    "MINOR": "新增向后兼容能力、API 字段或可选配置",
+    "MAJOR": "破坏兼容的 API、配置或行为变更",
+}

打开EPUB审校器.cmd

@@ -0,0 +1,11 @@
+@echo off
+setlocal
+
+"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -ExecutionPolicy Bypass -File "%~dp0tools\epub_review_editor\open_editor.ps1"
+set "exit_code=%ERRORLEVEL%"
+if not "%exit_code%"=="0" (
+  echo.
+  echo Startup failed. See the message above.
+  pause
+)
+exit /b %exit_code%