feat(editor): improve EPUB review workflow
This commit is contained in:
xin61
@@ -0,0 +1,140 @@
|
||||
# EPUB 审校器长期维护手册
|
||||
|
||||
## 目标与边界
|
||||
|
||||
本工具服务于中日双语 EPUB 的网页审校：长篇连续阅读、逐段修改中文译文、标记翻译问题、导出反馈与修订 EPUB。翻译质量规则仍由项目根目录的 `AGENTS.md`、`rules/translation_rules.md`、当前系列的 `series-style.md` 与术语表共同约束。
|
||||
|
||||
审校器不负责整卷首译流程，也不直接改正式术语表。用户在网页中留下的编辑、问题备注、长期规则建议，需要由 Codex 后续读取反馈文件后再沉淀到系列风格或候选术语中。
|
||||
|
||||
## 数据模型与会话目录
|
||||
|
||||
`--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` 保存用户修改与标记，字段缺省时必须能回退到原始译文。
|
||||
- `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`
|
||||
- part 标题默认使用 `part0000` 形式，真实标题可保留在 `source_title`
|
||||
- 插图通过 `/api/asset/<entry>` 读取，必须继续使用 `extracted_path()` 防止路径穿越
|
||||
|
||||
章节来源优先级：
|
||||
|
||||
1. EPUB 内部目录页的中文条目
|
||||
2. `nav.xhtml` / `toc.xhtml`
|
||||
3. 正文标题
|
||||
4. 文件名 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 时，重翻接口应返回可读错误，不影响编辑保存。
|
||||
|
||||
单段重翻流程：
|
||||
|
||||
1. 用户点击阅读段落，打开右侧面板。
|
||||
2. 用户可填写额外重翻要求。
|
||||
3. `/api/row/<row_id>/retranslate` 使用当前日文、当前中文、术语提示生成候选。
|
||||
4. 候选只显示在面板里，不自动覆盖。
|
||||
5. 用户点击“应用重翻”后写入编辑框，再点击保存才进入审校记录。
|
||||
|
||||
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 且浏览器可显示
|
||||
- 目录按钮、检索按钮、隐藏侧栏、点击段落打开右侧面板
|
||||
- 阅读段落下方没有编号和“快速编辑/快速标记”
|
||||
- 未配置 API Key 时重翻返回清晰错误
|
||||
- 配置保存后 `/api/gpt/config` 不包含密钥字段
|
||||
Reference in New Issue
Block a user