akai-tools/-----

Fork 0

Files

T

xin61 0ccd14cf67 feat(editor): restore reading position

2026-07-07 18:13:08 +08:00

8.2 KiB

Raw Blame History

EPUB 审校器长期维护手册

目标与边界

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

审校器不负责整卷首译流程。用户在网页中留下的编辑、问题备注、长期规则建议，需要由 Codex 后续读取反馈文件后再沉淀到系列风格或候选术语中。网页术语表编辑是用户显式操作正式术语表的入口，保存时会直接写入配置路径指向的 JSON 文件。

数据模型与会话目录

--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 保存用户修改与标记，字段缺省时必须能回退到原始译文。
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 白名单，不能任意读取解包目录文件

章节来源优先级：

EPUB 内部目录页的中文条目
nav.xhtml / toc.xhtml
正文 <h1-6> 标题
文件名 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 后继续复用已保存密钥；要更换端点或模型必须先保存配置，避免把密钥发往未确认端点。

单段重翻流程：

用户点击阅读段落，打开右侧面板。
用户可填写额外重翻要求。
/api/row/<row_id>/retranslate 使用提示词、目标语句、当前中文、实时命中的术语表条目、同文件前后一段少量上下文、角色口吻提示生成候选。
候选只显示在面板里，不自动覆盖。
用户点击“应用重翻”后写入编辑框，再点击保存才进入审校记录。
候选事件写入 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 能保存/读取位置；刷新或重启后回到上次阅读处

8.2 KiB Raw Blame History