EPUB 审校器长期维护手册

目标与边界

本工具服务于中日双语 EPUB 的网页审校：长篇连续阅读、逐段修改中文译文、标记翻译问题、导出反馈与修订 EPUB。翻译质量规则仍由项目根目录的 AGENTS.md、rules/translation_rules.md、当前系列的 series-style.md 与术语表共同约束。

审校器不负责整卷首译流程，也不直接改正式术语表。用户在网页中留下的编辑、问题备注、长期规则建议，需要由 Codex 后续读取反馈文件后再沉淀到系列风格或候选术语中。

数据模型与会话目录

--review-root 是唯一需要备份的运行数据目录。典型结构：

epub_review_sessions/
  app_state.json
  gpt_config.json
  <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 保存用户修改与标记，字段缺省时必须能回退到原始译文。
session.json 与 app_state.json 只保存会话定位信息。
gpt_config.json 只属于本地运行环境，不写入 EPUB、不写入导出文件、不通过 API 回传密钥。

目录与插图

结构接口 /api/structure 应保持向后兼容：

text chapter: kind: "text"、parts、row_count、touched_count、marked_count
image chapter: kind: "image"、images、parts: []、row_count: 0
统计字段同时保留总数和细分：chapter_count、text_chapter_count、image_chapter_count、image_count、asset_count
part 标题默认使用 part0000 形式，真实标题可保留在 source_title
插图通过 /api/asset/<entry> 读取，必须继续使用 extracted_path() 防止路径穿越；只把 raster 图片纳入 /api/structure 与 /api/asset 白名单，不能任意读取解包目录文件

章节来源优先级：

EPUB 内部目录页的中文条目
nav.xhtml / toc.xhtml
正文标题
文件名 fallback

阅读与侧栏交互

验收口径：

初始进入审校时，左侧侧栏隐藏，正文占主要空间。
顶部“目录”只打开目录，“检索”只打开搜索/段落列表，不合并成一个常驻面板。
目录可展开/收起章节，插图章节可点击阅读，文字 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。
API Key 优先读取 gpt_config.json，也支持环境变量 OPENAI_API_KEY。
/api/gpt/config 不得返回 API Key。
未配置 Key 时，重翻接口应返回可读错误，不影响编辑保存。
重翻请求不得临时覆盖 base_url 或 model 后继续复用已保存密钥；要更换端点或模型必须先保存配置，避免把密钥发往未确认端点。

单段重翻流程：

用户点击阅读段落，打开右侧面板。
用户可填写额外重翻要求。
/api/row/<row_id>/retranslate 使用当前日文、当前中文、术语提示生成候选。
候选只显示在面板里，不自动覆盖。
用户点击“应用重翻”后写入编辑框，再点击保存才进入审校记录。

Prompt 硬规则：

输出简体中文轻小说文风。
意义优先，不贴日语语序硬译。
不合并、不拆分段落。
有意义 ruby 必须保留为真实 <ruby><rb>...</rb><rt>...</rt></ruby>，不要改成括号。
Falchion / ファルシオン固定译为“大砍刀”，不要译成“偃月刀”。

版本规则

版本号使用 version = "0.1.0" 格式：

层级	触发条件
PATCH	修复 bug 或兼容性小修
MINOR	新增向后兼容能力、API 字段或可选配置
MAJOR	破坏兼容的 API、配置或行为变更

发版时必须同步：

version.py
static/index.html 顶部版本徽标 fallback
README.md 当前版本与版本说明

回归清单

每轮改动至少检查：

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
git diff --check
/api/version
/api/session
/api/structure
/api/gpt/config
首个插图 /api/asset/... 返回 200 且浏览器可显示
非白名单或非 raster asset 不能被 /api/asset/... 读取
目录按钮、检索按钮、隐藏侧栏、点击段落打开右侧面板
阅读段落下方没有编号和“快速编辑/快速标记”
未配置 API Key 时重翻返回清晰错误
配置保存后 /api/gpt/config 不包含密钥字段

5.6 KiB Raw Blame History