# 执行流程

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

## Luna / agent 完整清单

这是本轮默认测试方式，无需外部 API。由用户指定的 Luna agent 翻译完整批次；未获委派授权时保持同一 agent 执行或说明所需模型不可用。

```bash
.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、原文、占位符、标题上下文和单元摘要。先审读全书各批次并冻结术语表；小书可直接生成如下手工表，较大书分批归并建议，记录歧义，不随每个正文批次改译名。

```json
{"terms":[{"source":"Masayoshi Son","target":"孙正义","aliases":["Masa"],"notes":"Masa is his explicit nickname."}]}
```

译文结果只写 JSON 数组：

```json
[{"entry_id":"从批次原样复制","source_sha256":"从批次原样复制","translated_text":"译文与占位符"}]
```

对完整批次逐个 apply，可只提交失败条目的重试；每次记录接受数，检查 manifest 中的 `validation_errors`。

```bash
.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 完整翻译

```bash
.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

基础检查仅用项目已有依赖：

```bash
.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 官方浏览器文档](https://playwright.dev/python/docs/browsers) 安装 headless shell：

```bash
.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` 或具体章节扩大抽样。

```bash
.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

完整译本生成后，按 [中文版本整理](cover-metadata.md) 核对权威书名、生成并审查两版封面、更新书库 metadata 和复验封面。已有完整译本可以直接从该流程开始，不重译正文。封面／metadata 的检查和全书语义审查分别记录。