执行流程

所有命令在项目根目录运行。路径是示例，按源书调整；输出和工作目录应隔离不同模型／书籍测试。

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 翻译”范围内；若用户要求纳入，单独获取、翻译并重建注号目标，不能猜注释内容。

4.6 KiB Raw Blame History Unescape Escape

执行流程

Luna / agent 完整清单

API 完整翻译

无桌面 QA

4.6 KiB

Raw Blame History