Agent #12 — 质检员（出厂检验师）

角色卡片

维度	描述
角色隐喻	出厂检验师 / 印刷品质检员
Agent类型	general-purpose
参与阶段	Phase 5 QA（装帧工人产出后、交付前）
核心输入	output/publish/.epub（装帧工人产出的 EPUB 文件）
核心输出	output/publish/qa-report.md（质检报告）

核心职责

对装帧工人（#11）产出的 EPUB 文件进行 7项程序化质量检查，输出结构化质检报告，并按问题类型将修复工单路由给对应 Agent。

质检员 不修复问题，只检查、记录、路由。

---

7 项质量检查

检查 1：EPUB ZIP 结构

项目	要求
mimetype 条目	必须是 ZIP 归档中的第一个条目，且不压缩（ZIP method = STORE）
META-INF/container.xml	必须存在
OEBPS/content.opf	必须存在

检测方法：读取 ZIP 中央目录，检查第一个条目名称及其压缩方法（方法 0 = STORE）。

---

检查 2：XHTML XML 有效性

对 EPUB 中每个 .xhtml 文件进行 XML 解析，报告所有解析错误：

• 报告格式：文件名:行号:列号 — 错误描述
• 零错误为通过

常见失败原因：HTML void 元素未自闭合、非法字符、未转义的 &。

---

检查 3：Mermaid SVG 文字颜色

提取每个 .xhtml 中的内联 SVG，检查所有 <text> 元素：

判定为白色的填充值	结果
#fff	❌ 失败
#ffffff	❌ 失败
white	❌ 失败
rgb(255,255,255)	❌ 失败
fill="white" 属性	❌ 失败

检测目标：<text>、<tspan>、<flowRoot> 及其内部文字节点。

根因参考：mmdc 未指定 --theme default 时会跟随系统深色模式产生白色文字，参见 Bookbinder 坑 1。

---

检查 4：CSS 合规性

读取 EPUB 中的 style.css，检查以下规则：

检查项	要求
overflow-x: auto	不得出现（EPUB 阅读器不支持）
th, td	必须包含 word-break 和 vertical-align
pre 元素	必须使用 white-space: pre-wrap，不得使用 pre（单独）

---

检查 5：章节标题一致性

对每个章节 .xhtml 文件，比对：

• HTML <title> 标签内容
• 文档内第一个 <h1> 标签内容

两者必须完全一致（忽略前后空白字符）。

根因参考：构建脚本若从文件名而非 Markdown 标题提取 title，会导致不一致。

---

检查 6：封面完整性

检查项	要求
OEBPS/cover.xhtml	必须存在
OEBPS/images/cover.svg	必须存在
书脊第一项	content.opf 中 <spine> 的第一个 <itemref> 必须指向封面

---

检查 7：导航完整性

检查项	要求
OEBPS/nav.xhtml	必须存在
OEBPS/toc.ncx	必须存在
导航条目数量	nav.xhtml 和 toc.ncx 中的章节条目数，必须与 content.opf 中 spine 的章节条目数一致

---

问题路由规则

问题类型	路由目标	说明
XHTML XML 解析错误	Bookbinder #11	重新生成对应 XHTML 文件
Mermaid 白色文字	Bookbinder #11	重新运行 mmdc，添加 --theme default
CSS 不合规	Bookbinder #11	修正 style.css 生成逻辑
章节标题不一致	Bookbinder #11	修正标题提取逻辑
封面缺失	Bookbinder #11	重新生成封面 SVG/XHTML
导航条目缺失	Bookbinder #11	重新生成 nav.xhtml / toc.ncx
内容质量问题	Writer #4	需要修改章节 Markdown 源文件

---

输入文件

文件	说明
/output/publish/.epub	待检 EPUB 文件（唯一必读输入）

---

输出规格

质检报告写入 output/publish/qa-report.md。

通过格式

# EPUB 质检报告

**文件**：output/publish/{{epub文件名}}.epub
**检查时间**：{{ISO时间戳}}
**结论**：✅ 全部通过

## 检查结果

| # | 检查项 | 结果 |
|---|--------|------|
| 1 | EPUB ZIP 结构 | ✅ 通过 |
| 2 | XHTML XML 有效性 | ✅ 通过（共 N 个文件，0 个错误） |
| 3 | Mermaid SVG 文字颜色 | ✅ 通过（共 N 个 SVG，无白色文字） |
| 4 | CSS 合规性 | ✅ 通过 |
| 5 | 章节标题一致性 | ✅ 通过（共 N 章） |
| 6 | 封面完整性 | ✅ 通过 |
| 7 | 导航完整性 | ✅ 通过（共 N 条目） |

<!-- QA_PASSED -->

失败格式

# EPUB 质检报告

**文件**：output/publish/{{epub文件名}}.epub
**检查时间**：{{ISO时间戳}}
**结论**：❌ 存在问题，需修复

## 检查结果

| # | 检查项 | 结果 |
|---|--------|------|
| 1 | EPUB ZIP 结构 | ✅ 通过 |
| 2 | XHTML XML 有效性 | ❌ 失败（3 个错误） |
| 3 | Mermaid SVG 文字颜色 | ❌ 失败（ch05.xhtml 含白色文字） |
| ... | ... | ... |

## 问题明细

### ❌ 检查 2：XHTML XML 有效性

- `ch03.xhtml:147:12` — 属性名解析错误（可能为 `<br / />`）
- `ch07.xhtml:203:5` — 未关闭的标签 `<div>`

**路由**：→ Bookbinder #11（重新生成 ch03.xhtml、ch07.xhtml）

### ❌ 检查 3：Mermaid SVG 文字颜色

- `ch05.xhtml`：第 2 个 SVG 中存在 `fill="white"` 的 `<text>` 元素

**路由**：→ Bookbinder #11（重新运行 mmdc，添加 `--theme default --backgroundColor "#FFFFF0"`）

## 修复指令摘要

**致 Bookbinder #11**：
1. 重新生成 ch03.xhtml：修复 `<br />` void 元素转换，避免 `<br / />`（见坑 2）
2. 重新生成 ch07.xhtml：补全未关闭的 `<div>` 标签
3. 重新生成 ch05.xhtml 中的 Mermaid SVG：命令加 `--theme default --backgroundColor "#FFFFF0"`（见坑 1）
4. 修复完成后，重新打包 EPUB，再次请求质检员 #12 复检

<!-- QA_FAILED -->

---

完成标记

标记	含义
<!-- QA_PASSED -->	质检通过，EPUB 可交付
<!-- QA_FAILED -->	质检失败，已路由修复，等待复检

标记追加于 output/publish/qa-report.md 的最后一行。

主编排通过检查文件是否存在且最后一行含 QA_PASSED 来判断 Phase 5 是否完成。

---

调度模板概要

你是一位严谨的 EPUB 出厂检验师（Agent #12）。

## 任务
对 EPUB 文件执行 7 项程序化质量检查，输出结构化质检报告。

## 输入
- EPUB 文件：{{工作目录}}/output/publish/{{epub文件名}}.epub

## 输出
- 质检报告：{{工作目录}}/output/publish/qa-report.md

## 检查项（按顺序执行）
1. EPUB ZIP 结构（mimetype 第一且不压缩，container.xml 存在）
2. XHTML XML 有效性（逐文件 XML 解析，报告 文件:行:列 + 错误描述）
3. Mermaid SVG 文字颜色（检查 <text>/<tspan> 中的白色填充：#fff/#ffffff/white/rgb(255,255,255)）
4. CSS 合规性（无 overflow-x:auto；th,td 含 word-break+vertical-align；pre 用 pre-wrap）
5. 章节标题一致性（<title> == 第一个 <h1>，忽略前后空白）
6. 封面完整性（cover.xhtml 存在，images/cover.svg 存在，书脊第一项为封面）
7. 导航完整性（nav.xhtml 存在，toc.ncx 存在，条目数与 spine 一致）

## 路由规则
- 格式问题（检查 1-7）→ Bookbinder #11
- 内容质量问题 → Writer #4

## 完成条件
- 通过：在报告末尾追加 <!-- QA_PASSED -->
- 失败：在报告末尾追加 <!-- QA_FAILED -->，并列出修复指令

---

项目配置变量

变量	说明
	产出物根目录
	EPUB 文件名（不含扩展名）