e2e-quality

name

e2e-quality

description

Compare e2e captured translations against the baoyu-translate skill ground truth (tests/reference/article-zh-CN-<mode>/translation.md) for all three translation modes, computing both cheap metrics (character jaccard, Chinese 2-gram overlap, paragraph drift) and Claude judge scores across 5 dimensions (accuracy, terminology consistency, cultural annotation, fluency, faithfulness). Writes tests/e2e-out/<ts-sha>/quality.md. Use only after /e2e-diagnostician returns verdict=PASS — when the gate fails, this skill must not run. Triggers on /e2e-quality, "run quality", "compare translations", "judge e2e quality", or after a successful /e2e-diagnostician run.

e2e-quality

Slice 7 of PRD #26 (Part A). 仅在 e2e-diagnostician verdict=PASS 后被调用 —— gate 失败时本 skill 不执行(由上游 orchestrator 把控)。

读三模式 captured.md vs tests/reference/article-zh-CN-<mode>/translation.md, 跑两类指标:

• cheap 指标:脚本可生成,不调 LLM —— 字符级 jaccard、中文 2-gram 重合度、 段落数偏差。给定量参考。
• judge 指标:Claude 在本 session 内以独立 vendor 身份(避免与翻译 model 自身认同)对 3 模式 × 2 输入(captured + reference)做 5 维评分 —— 准确性 / 术语一致 / 文化注释 / 通顺 / 忠实。给定性结论。

输出 tests/e2e-out/<ts-sha>/quality.md,供 e2e-reporter 汇总。

调用前提

1. tests/e2e-out/<ts-sha>/diagnosis.md 存在。
2. diagnosis.md 顶端 verdict: PASS 行被 grep 到。
3. 三模式子目录下 captured.md / status.md / console.jsonl 存在 (与 e2e-diagnostician C0 共享前提;若此处发现缺失,说明 runner / diagnostician 产物异常,应 STOP 并提示重跑,而非强行猜 reference)。

任一前提不满足 → 立即停止,不要试图补跑或自行生成产物。 报 "Quality precondition failed: ",由用户决定是否回退到 runner / diagnostician。

输入契约

tests/e2e-out/<ts-sha>/
├── article-zh-CN-quick/
│   └── captured.md                    # runner 写入的注入译文集合
├── article-zh-CN-normal/
│   └── captured.md
├── article-zh-CN-refined/
│   └── captured.md
├── diagnosis.md                       # verdict: PASS 行必须存在
└── (e2e-report.md?                    # 来自 runner 的占位,本 skill 不读)

tests/reference/article-zh-CN-<mode>/translation.md —— ground truth, 与 tests/reference/article.md (原文)配套。

段落计数方式

captured.md 在 paragraph_count: 行明确给出;translation.md 用 awk 'NF>0' <file> | wc -l 算非空行(忽略标题行 # article-zh-CN-...、 captured_at: 等元数据行)。与 e2e-diagnostician C4 计数方式一致 (避免两个 agent 报不同数)。

输出契约

tests/e2e-out/<ts-sha>/
├── diagnosis.md
├── quality.md                         # 本 skill 写
└── e2e-report.md                      # 由 e2e-reporter 写

quality.md 不覆盖诊断报告,只补翻译质量层评估;最终汇总留给 e2e-reporter。

Cheap 指标(脚本可生成)

每一模式各算 3 个数值,合入 quality.md 的表格。所有计算用 GNU coreutils

• Python(标准库,无第三方依赖)即可完成。

1. 字符级 Jaccard

captured 与 reference 的中文字符集合的交集 / 并集。过滤掉 ASCII (数字、英文、标点)避免链接 / 路径污染:

import re
def zh_chars(text: str) -> set[str]:
    return set(re.findall(r'[一-鿿]', text))
captured = zh_chars(open('captured.md').read())
reference = zh_chars(open('reference/translation.md').read())
jaccard = len(captured & reference) / len(captured | reference)

报告 0.0–1.0,保留 3 位小数。不设硬阈值 —— 翻译改写是 LLM 的本职, 字符完全相等反而意味着直译;e2e-reporter 据此定性。

2. 中文 2-gram 重合度

captured 与 reference 的中文 2-gram (连续 2 字) 集合的 Jaccard:

def zh_2grams(text: str) -> set[str]:
    chars = re.findall(r'[一-鿿]', text)
    return {''.join(pair) for pair in zip(chars, chars[1:])}
captured = zh_2grams(open('captured.md').read())
reference = zh_2grams(open('reference/translation.md').read())
overlap = len(captured & reference) / len(captured | reference)

报告 0.0–1.0,保留 3 位小数。比 1-gram 更能反映"用词风格是否对齐"。

3. 段落数偏差

captured_count = captured.md 头 paragraph_count: 行的整数; reference_count = translation.md 非空行数;drift_pct = (captured / reference) × 100,保留 1 位小数。

drift_pct 应在 70–130%(与 e2e-diagnostician C4 阈值一致)。 注:cheap 指标在这里重复 C4 检出的偏差 —— 目的不同:

• C4 是 gate 判定(e2e-diagnostician 用以决定 PASS/FAIL)。
• 这里把同一数值摆进质量报告,供 e2e-reporter 报告里"段落数 vs reference 接近度"一栏引用。

Judge 指标(Claude 5 维评分)

cheap 指标只能反映"表面相似"。翻译改写/术语选择/通顺度需要 LLM 判定。 PRD #26 §4.2 锁定:由 Claude 在本 session 内以独立 vendor 身份跑,5 维评分。

为什么是 Claude 而非翻译 model 自身

避免 self-affinity bias —— 让翻译 model 评自己的译文会系统性偏松。 ADR-0003 §4.2 明确:不新加 API key,直接用 Claude Code session 内的 推理能力(无需 fetch / 无需 token)。

评分维度

维度	含义	1 分代表	5 分代表
准确性 (accuracy)	事实/数据/逻辑与原文是否一致	多处事实错	全部一致
术语一致 (terminology)	关键术语全文是否统一翻译	同一术语多次翻法不一	全文统一,首现标注原文
文化注释 (cultural-notes)	对中文读者陌生的概念是否加注	完全无注释	注释到位且简练
通顺 (fluency)	是否像母语者写的中文	翻译腔重,逐句直译	自然流畅,无翻译腔
忠实 (faithfulness)	是否贴近原文风格 / 修辞 / 语气	大幅改写脱离原文	保留原文幽默/自嘲/口语化

每维度 1–5 整数分。5 维总分 = 25 满分,每模式分别打。

执行范式

每次评分 = 1 个模式:把 captured.md 与 translation.md 一起作为输入, judge 给 captured 打 5 维分(reference 作为对照基准,自身不独立打分)。 3 模式各打 1 次,共 3 次评分调用。每次评分 prompt 包含:

1. 原文片段:tests/reference/article.md 完整内容(可截取关键段)。
2. 待评译文:captured.md 或 translation.md 完整内容。
3. 评分维度说明:上表 + 1/5 分锚点 + 0.5 步长(允许 4.5 这种)。
4. 格式契约:返回 JSON {"accuracy": 4.5, "terminology": 5, "culturalNotes": 4, "fluency": 5, "faithfulness": 4, "rationale": "..."} 便于解析。rationale 1-2 句点出关键观察。

Claude 作为 judge 的内部 prompt 模板见本文末尾 §Judge prompt template (避免在 SKILL.md 内嵌过长 prompt)。

Judge 输入边界

• 不做端到端重译对照(那是评审,本 skill 是评分)。
• 不做长篇 critique(每维 1-2 句 rationale,详细诊断留给 e2e-diagnostician 的 finding 机制)。
• 不调翻译 model 自身作 judge(避免 self-affinity)。

quality.md shape

# e2e quality — <ts-sha>

generated_at: <ISO timestamp>
source_article: tests/reference/article.md
ground_truth_dir: tests/reference/article-zh-CN-{quick,normal,refined}

verdict: <PASS|REVIEW>                     # PASS = 3 模式总分均 >= 18/25;REVIEW = 至少 1 模式 < 18 或任一维度 <= 2
                                              # 不阻断 e2e,只作 e2e-reporter 摘要

## Cheap metrics

| mode    | jaccard (char) | 2-gram overlap | paragraph drift (captured / reference) |
|---------|----------------|----------------|----------------------------------------|
| quick   | 0.342          | 0.187          | 75 / 75 (100.0%)                       |
| normal  | 0.401          | 0.234          | 78 / 75 (104.0%)                       |
| refined | 0.456          | 0.298          | 84 / 84 (100.0%)                       |

## Judge scores (5-dim, 1-5 each, total / 25)

| mode    | accuracy | terminology | cultural-notes | fluency | faithfulness | total |
|---------|----------|-------------|----------------|---------|--------------|-------|
| quick   | 4.0      | 4.5         | 3.0            | 4.5     | 4.0          | 20.0  |
| normal  | 4.5      | 5.0         | 4.0            | 4.5     | 4.5          | 22.5  |
| refined | 5.0      | 5.0         | 5.0            | 5.0     | 5.0          | 25.0  |

## Per-mode rationale (摘录自 judge)

### quick
- accuracy 4.0: 数据点 "2,000 calories a day" 漏掉单位
- terminology 4.5: "Deliveroo" 首次出现加注"（英国外卖平台）",后续保持;但 "Ocado" 首次未加注
- cultural-notes 3.0: 多处英国本土品牌/概念未加注
- fluency 4.5: 整体自然,偶有长句可断
- faithfulness 4.0: "I didn't have any reason to ever leave the house" 略直译,口吻可更口语

### normal
...

### refined
...

## Recommendations (供 e2e-reporter 摘要用)

- quick 模式:术语注释覆盖度需改进(建议 EXTEND.md 加 audience=general 时
  必加注释规则)
- normal 模式:整体可发布,小修即可
- refined 模式:对得上 baoyu-translate skill 标准译文质量

## Next step

调用 `/e2e-reporter` 汇总 `diagnosis.md` + `quality.md` → 最终 `e2e-report.md`。

verdict 行 REVIEW 表示"cheap 指标 + judge 评分至少 1 模式有显著不足 (总分 < 18 / 25 或任一维度 <= 2)",不阻断 e2e,只让 e2e-reporter 在 e2e-report.md 突出"质量待优化建议"。PASS 三模式均 ≥ 18 且无低分维度。

Judge prompt template

You are an independent translation quality judge. You are NOT the model that
produced the translation under review. Score on 5 dimensions, each 1-5
integer or half-integer (e.g. 3.5, 4.5), with a 1-2 sentence rationale per
dimension.

# Source article (English)
{article.md 完整内容}

# Reference translation (baoyu-translate skill output, ground truth)
{tests/reference/article-zh-CN-<mode>/translation.md 完整内容}

# Captured translation (e2e output under review)
{tests/e2e-out/<ts-sha>/article-zh-CN-<mode>/captured.md 完整内容}

# Scoring dimensions
- accuracy: 事实/数据/逻辑与原文是否一致 (1=多处错, 5=全部一致)
- terminology: 关键术语全文是否统一翻译 (1=多次翻法不一, 5=全文统一+首现标注)
- cultural-notes: 对中文读者陌生的概念是否加注 (1=完全无, 5=注释到位简练)
- fluency: 是否像母语者写的中文 (1=翻译腔重, 5=自然流畅)
- faithfulness: 是否贴近原文风格/修辞/语气 (1=大幅改写, 5=保留原文风格)

# Output format (strict)
Return ONLY a JSON object (no prose before/after):
{
  "accuracy": <1-5>,
  "terminology": <1-5>,
  "culturalNotes": <1-5>,
  "fluency": <1-5>,
  "faithfulness": <1-5>,
  "total": <sum>,
  "rationale": "<1-2 句总评,关键观察>"
}

跨契约

ADR 契约(修改需同步):

• [baoyu] 前缀虽不直接出现在本 skill 输入(消费的是 captured.md 而 非 console.jsonl),但间接:本 skill 假设 runner 已按 [baoyu] 过滤 console.jsonl,diagnostician 借此判定 console error。修改前缀需同步 ADR-0002 + runner + diagnostician + 本 skill 文档。
• Gate 行为由 ADR-0003 §Consequences 锁定:diagnostician FAIL → quality 不被调用。本 skill 自身不检 verdict(由上游 orchestrator 把控),但 在 SKILL.md 内显式写"调用前提"以便调用方有据可查。

代码库契约(复用既有实现,不重新声明):

• 三模式枚举 quick / normal / refined 复用 shared/types.ts::TranslationMode。
• captured.md schema(段落数 / 元数据格式)由 e2e-runner/SKILL.md 锁 定;本 skill 读取端按该 schema 解析,字段缺失回退到 "Quality precondition failed" STOP(不强行猜)。
• translation.md 段落计数与 e2e-diagnostician C4 共享 awk 'NF>0' | wc -l 算法(避免两个 agent 报不同数)。

手工验证范式

TS_SHA="2026-06-02T10-30-00_abcdef1"
RUN="tests/e2e-out/${TS_SHA}"

# 假设 runner + diagnostician 已跑过,verdict=PASS,质量有差异
# 准备一份 captured.md 与 reference 略有差异的 quick 模式
cat > "$RUN/article-zh-CN-quick/captured.md" <<'EOF'
# article-zh-CN-quick
paragraph_count: 75
captured_at: 2026-06-02T10:30:42Z

<译文略,与 reference 字面 ~30% 重合>
EOF

# 触发本 skill,期望 quality.md 生成,jaccard/2-gram 数值合理(0.2-0.4),
# judge 评分在 18-22/25 范围。verdict 行 `verdict: PASS` 或 `REVIEW`。

不在本 skill 范围

• Gate 判定:由 e2e-diagnostician 负责;本 skill 不判 PASS/FAIL, 只在 quality.md 里给"质量层 verdict"(PASS / REVIEW,不阻断)。
• 最终 e2e-report.md:由 e2e-reporter 写,本 skill 不写。
• 重跑翻译:若 quality 不满意,需回 e2e-runner(改 prompt / provider / 模型)重出 captured,本 skill 只评不改。
• 阈值调优:cheap 指标判定"是否够对齐"留给 e2e-reporter 的人审; judge verdict 阈值(总分 ≥ 18 / 25)按 issue #33 / 经验性,不在本 skill 锁死;若后续调优需开新 issue。

用法

触发本 skill 后:

1. 确认 verdict=PASS:grep '^verdict: PASS' "$RUN/diagnosis.md",失败 立即报"Diagnostician gate not PASS — quality not invoked"。
2. 三模式 captured.md 存在 + paragraph_count: 行可解析。
3. 算 cheap 指标:Python 标准库脚本,1-2 秒出结果。
4. 调 Claude judge:3 次评分调用(quick / normal / refined),每次按模板 prompt 给出 5 维评分 + rationale。
5. 写 quality.md:表格 + rationale 摘录 + recommendations + verdict。
6. 回报用户:"Quality done for <ts-sha>. cheap 指标 + Claude 5 维评分见 quality.md。verdict=<PASS|REVIEW>。下一步:调 /e2e-reporter 汇总 diagnosis.md + quality.md → 最终 e2e-report.md。"

故障排查

现象	根因	修复
"Diagnostician gate not PASS"	上游没跑或跑挂	先跑 /e2e-diagnostician,verdict=PASS 后再调本 skill
paragraph_count: 行解析失败	runner 写盘格式变更	看 e2e-runner/SKILL.md 的 captured.md shape,改本 skill 解析端
judge 返回 prose 而非 JSON	Claude 没遵守 format 约束	重新 prompt 加 Return ONLY a JSON object, no prose;若仍失败,记到 quality.md 的 judge_errors 段
cheap 指标全 0	captured.md 误读到 translation.md	校对路径,本 skill 读 <ts-sha>/article-zh-CN-<mode>/captured.md 而非 reference
1 模式 judge 总分 < 12	翻译严重偏离	不阻断,verdict: REVIEW + 在 recommendations 突出提示

参考

• PRD #26:父 PRD(Slice 7 / Part A:quality)。
• ADR-0002:日志 schema + [baoyu] 前缀契约(本 skill 间接消费)。
• ADR-0003:e2e 流水线 + gate 行为 + 产物契约。
• .claude/skills/e2e-runner/SKILL.md:captured.md schema 来源(Slice 5)。
• .claude/skills/e2e-diagnostician/SKILL.md:C4 段落数 ±30% 阈值与本 skill paragraph drift 共享。
• .claude/skills/e2e-reporter/SKILL.md:本 skill 的下游(汇总到 e2e-report.md)。
• src/shared/types.ts::TranslationMode:三模式枚举。
• tests/reference/article.md + tests/reference/article-zh-CN-<mode>/: ground truth。