xin61
162 lines
8.2 KiB
Markdown
162 lines
8.2 KiB
Markdown
# EPUB 审校器长期维护手册
|
|
|
|
## 目标与边界
|
|
|
|
本工具服务于中日双语 EPUB 的网页审校：长篇连续阅读、逐段修改中文译文、标记翻译问题、导出反馈与修订 EPUB。翻译质量规则仍由项目根目录的 `AGENTS.md`、`rules/translation_rules.md`、当前系列的 `series-style.md` 与术语表共同约束。
|
|
|
|
审校器不负责整卷首译流程。用户在网页中留下的编辑、问题备注、长期规则建议，需要由 Codex 后续读取反馈文件后再沉淀到系列风格或候选术语中。网页术语表编辑是用户显式操作正式术语表的入口，保存时会直接写入配置路径指向的 JSON 文件。
|
|
|
|
## 数据模型与会话目录
|
|
|
|
`--review-root` 是唯一需要备份的运行数据目录。典型结构：
|
|
|
|
```text
|
|
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` 保存用户修改与标记，字段缺省时必须能回退到原始译文。
|
|
- `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 或导出文件。
|
|
|
|
## 目录与插图
|
|
|
|
结构接口 `/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`，也不要让目录被正文内容污染。
|
|
|
|
## 阅读与侧栏交互
|
|
|
|
验收口径：
|
|
|
|
- 初始进入审校时，左侧侧栏隐藏，正文占主要空间。
|
|
- 顶部“目录”只打开目录，“检索”只打开搜索/段落列表，不合并成一个常驻面板。
|
|
- 目录可展开/收起章节，插图作为所属章节的次级目录条目可点击阅读，文字 part 可点击定位。
|
|
- 点击目录章节、part 或插图条目后，侧栏不得自动收起；用户仍可点“隐藏”或按 `Escape` 关闭。
|
|
- 检索必须保留“当前范围 / 全书全局”切换；当前范围随当前章节或 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`；默认路径是项目根目录下当前 TRPG 系列的正式术语表。
|
|
- 术语表保存应保持 JSON 对象结构：key 为源语或匹配词，value 为译名，可继续使用 `#` 作为备注分隔。
|
|
- 重翻时必须实时读取术语表，按目标段落日文、HTML 与当前中文命中相关条目，不得只在提示词里泛泛要求“遵守术语表”。
|
|
- 未配置 Key 时，重翻接口应返回可读错误，不影响编辑保存。
|
|
- 重翻请求不得临时覆盖 `base_url` 或 `model` 后继续复用已保存密钥；要更换端点或模型必须先保存配置，避免把密钥发往未确认端点。
|
|
|
|
单段重翻流程：
|
|
|
|
1. 用户点击阅读段落，打开右侧面板。
|
|
2. 用户可填写额外重翻要求。
|
|
3. `/api/row/<row_id>/retranslate` 使用提示词、目标语句、当前中文、实时命中的术语表条目、同文件前后一段少量上下文、角色口吻提示生成候选。
|
|
4. 候选只显示在面板里，不自动覆盖。
|
|
5. 用户点击“应用重翻”后写入编辑框，再点击保存才进入审校记录。
|
|
6. 候选事件写入 jsonl，便于后续根据精修反馈优化提示词；当前版本不自动改写提示词。
|
|
|
|
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` 当前版本与版本说明
|
|
- 必要时同步 `MAINTENANCE.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` 不包含密钥字段
|
|
- `/api/glossary` 能读取术语表；新增、修改、删除条目后保存，再读取内容一致
|
|
- 重翻候选事件包含 `glossary_path` 与 `glossary_matches`
|
|
- `/api/reading-position` 能保存/读取位置；刷新或重启后回到上次阅读处
|