6.5 KiB
执行流程
所有命令在项目根目录运行。路径是示例，按源书调整；输出和工作目录应隔离不同模型／书籍测试。
Luna / agent 完整清单
这是本轮默认测试方式，无需外部 API。由用户指定的 Luna agent 翻译完整批次；未获委派授权时保持同一 agent 执行或说明所需模型不可用。
.venv/bin/python scripts/agent_book.py prepare input/book.epub --work .work/luna-book --model agent/luna
读取 .work/luna-book/agent-run.json 的 batch_files，不要遍历目录中旧批次。每个 batches/0000.json 包含 ID、原文、占位符、标题上下文和单元摘要。先审读全书各批次并冻结术语表；小书可直接生成如下手工表，较大书分批归并建议，记录歧义，不随每个正文批次改译名。
{"terms":[{"source":"Masayoshi Son","target":"孙正义","aliases":["Masa"],"notes":"Masa is his explicit nickname."}]}
译文结果只写 JSON 数组：
[{"entry_id":"从批次原样复制","source_sha256":"从批次原样复制","translated_text":"译文与占位符"}]
对完整批次逐个 apply，可只提交失败条目的重试；每次记录接受数，检查 manifest 中的 validation_errors。
.venv/bin/python scripts/agent_book.py apply input/book.epub --work .work/luna-book \
--result .work/luna-book/results-0000.json --glossary .work/luna-book/glossary.json
.venv/bin/python scripts/agent_book.py build input/book.epub --work .work/luna-book \
--model agent/luna --glossary .work/luna-book/glossary.json
build 要求所有条目通过独立格式与术语校验，并生成 translated_book.epub、bilingual_book.epub 和模型来源记录；不能用 build_sample.py 的部分模式冒充全书。apply 拒绝旧源摘要、未知 ID 和重复 ID；失败重试不会覆盖已有效译文，拒绝项写入 apply-report.json 并退出 1；不要把保留下来的旧译文当作新修复已经生效。不同模型使用独立工作目录。
API 完整翻译
.venv/bin/python main.py input/book.epub --complete-book --bilingual \
--config config/provider.yaml --output-dir output/provider
使用本地环境或 --env-file；不输出密钥。本轮默认使用用户指定的 Luna agent，不自动恢复旧 Sonnet 任务。后续显式指定其他模型时遵守新的选择。
无桌面 QA
基础检查仅用项目已有依赖：
.venv/bin/python scripts/headless_qa.py input/book.epub .work/luna-book/output/translated_book.epub \
--manifest .work/luna-book/manifest.json --out .work/luna-book/qa-chinese
视觉证据的可选依赖按 Playwright 官方浏览器文档 安装 headless shell：
.venv/bin/pip install -r requirements-qa.txt
# 可在项目内安装，以便隔离和复制 CI 配置：
export PLAYWRIGHT_BROWSERS_PATH="$PWD/.work/playwright"
.venv/bin/python -m playwright install chromium --only-shell
.venv/bin/python scripts/headless_qa.py input/book.epub .work/luna-book/output/translated_book.epub \
--manifest .work/luna-book/manifest.json --render --out .work/luna-book/qa-chinese
Linux 系统运行库仍可能需要官方 install --with-deps chromium --only-shell，按部署环境安装；中文渲染也需要书内或系统可用的 CJK 字体，不声称零系统依赖。
默认风险采样覆盖章／部、注号、图片和书后区域。--chapter 指定 ZIP 内完整 XHTML 路径，可重复；--pages 是连续浏览视口截图数，非阅读器页码。较大段落、远离页面开头的特殊内容可通过更多 --pages 或具体章节扩大抽样。
.venv/bin/python scripts/headless_qa.py input/book.epub .work/luna-book/output/bilingual_book.epub \
--manifest .work/luna-book/manifest.json --render --chapter Text/chapter1.xhtml \
--chapter Text/notes.xhtml --pages 3 --out .work/luna-book/qa-bilingual
退出 1 表示工程检查／完整度／注号点击失败；退出 2 表示所请求的渲染未成功，不以缺依赖降级成通过。report.json 保存源／输出 SHA、基线问题、覆盖范围、注释分类、布局提示和真实浏览器点击结果；review.html 和 PNG 是视觉证据。
查看截图后另写 review-record.json：已审文档／图片、发现项、修改与复验结果、语义抽查单元、剩余问题。原始自动报告的 visual／semantic 状态保持 pending，防止后续把机器生成证据误当人工验收。源码里不存在的网站尾注不在“完整源 EPUB 翻译”范围内；若用户要求纳入，单独获取、翻译并重建注号目标，不能猜注释内容。
版本封装：封面和 metadata
读取 README 的「中文封面与书库 metadata」步骤，使用 scripts/localize_edition.py prepare/apply。可在完整译本生成后单独封装，不重译正文。生图是 agent 的显式工具步骤，脚本只提取任务、验证已审图片、封装和审计；普通脚本不能假装拥有 Codex 的内置工具或私有 OAuth 生图权限。
先核实 title/author 的正式中文出版书目；保存网址、查询日期、版次关联和 ISBN（仅作为证据）。输入 title/author/identifier 不匹配时修订配置，不放宽匹配。保留繁体正式书名，用户需要简体时记录转换，不能默默改成另一书名。研究不到的条目写 title_status: project。
prepare 输出 cover-job.json 与参考封面。先查看参考图，用可用生图模型制作中文版和双语版，再查看输出图。review.json 记录实际 SHA、mode、title_zh、edition_revision、provider、model 和具体审查内容。模型 ID 不可见则为 null。错字、错误徽标、缺失修订号、裁切或缩略图不可读时迭代生图，不以 metadata 正确代替图片审校。不得借用另一部书的封面。
apply 仅用于相应完整译本；分别指定 mode／图片／review／输出，保留原译本。main.py 和 agent build 的可选 --edition-config 通过配置 covers 自动调用同一封装步骤。重新修订使用未封装的译本作为输入，更新修订号和图片审查记录。
运行原书到新版的 headless QA，并显式选择封面 XHTML（如 titlepage.xhtml）。查看全尺寸封面及书库缩略图，检查外置 SVG 或内嵌 SVG 是否拉伸。审计仍要求原图、字体、正文插图不变，并核验新的封面标识、摘要、实际 XHTML／SVG 引用、语言和作者。metadata 的已审书名不是全书语义验收。