e2e-diagnostician

name

e2e-diagnostician

description

Diagnose a Baoyu Translate e2e-runner artifact set and act as the gate that decides whether downstream quality + reporter agents run. Reads tests/e2e-out/<ts-sha>/ runner products (captured.md / status.md / console.jsonl / failure.md?), produces a diagnosis.md, and — when the gate fails — additionally writes an e2e-report.md in acceptance form so the upstream caller can stop the pipeline. Use when the user asks to "diagnose e2e", "run e2e gate", "为什么 e2e 没过", or after a /e2e-runner run is complete.

e2e-diagnostician

Slice 6 of PRD #26. 读 e2e-runner 的全部产物,跑诊断判定清单,产出 diagnosis.md(永远写),并在 gate 不通过时额外写 e2e-report.md (验收形态,含问题清单 + 影响点 + 修复建议)——让上游调用方知道后续 e2e-quality / e2e-reporter 不执行。

不复现用户路径(那是 runner 的工作),不评翻译质量(那是 quality 的工作),不写最终 e2e-report.md 的成功版(reporter 的工作)。

输入契约

tests/e2e-out/<iso8601-timestamp>_<git-sha>/
├── article-zh-CN-quick/
│   ├── captured.md                          # 注入译文集合
│   ├── status.md                            # url/mode/status/段落数/批次/duration
│   ├── console.jsonl                        # 过滤 [baoyu] 后的全量日志
│   └── failure.md?                          # 失败时存在
├── article-zh-CN-normal/    (同上)
├── article-zh-CN-refined/   (同上)
└── e2e-report.md                            # runner 写的跑通/跑挂概览占位

• 必出三模式子目录 + 每模式至少 captured.md/status.md/console.jsonl。
• 缺失任意必出文件 → 整体判未通过,归类为"Incomplete runner artifacts" (前置条件失败,不属于判定清单 C1-C4 任一项)。
• failure.md / e2e-report.md 条件性出现。
• Reference 段落数固定从 tests/reference/article-zh-CN-<mode>/translation.md 读 —— runner 不复制 reference,不重新计数。

判定清单与 runner 产物 schema 的详细定义见 .claude/skills/e2e-runner/SKILL.md。 修改产物 schema 需同步两处(本 skill 读取端 + runner 写入端)。

输出契约

tests/e2e-out/<ts-sha>/
├── diagnosis.md                             # 永远写:全量判定证据 + 修复建议
└── e2e-report.md                            # 仅未通过时写:验收形态,问题清单 + 影响点

• diagnosis.md 永远写。包含:per-criterion pass/fail + 证据、 per-mode 状态表、最终 verdict(PASS / FAIL)、fix 建议。
• e2e-report.md 仅 gate 未通过时写。与 diagnosis.md 内容相同 但 framing 改成"验收形态":第一段直接说"未通过 + 简述根因", 把 issue list 提到头部便于人扫读;不复述判定证据(那部分只在 diagnosis.md)。成功时不写,留给 e2e-reporter 在 e2e-quality 之后 落最终版。

Gate 行为

Gate 是布尔决策,粒度 = 一次 e2e(三个模式聚合):

决策	写 diagnosis.md	写 e2e-report.md	后续 quality / reporter
PASS (无 C1-C4 触发)	✓	✗	调用方决定是否继续
FAIL (任一 C1-C4 触发)	✓	✓	不执行(被 gate 截断)

PRD #26 明确:"诊断未通过 → 后续 quality + reporter 不执行"。 e2e-diagnostician 不调用 quality/reporter,只写产物;上游 orchestrator 根据 diagnosis.md 顶端 verdict 决定是否继续调用它们。

verdict 行固定写 <ts-sha> verdict: <PASS|FAIL>(整行可 grep 判定结果)。

诊断判定清单

按以下顺序检查,任一未通过 → 整体 FAIL,记录对应 finding 到 diagnosis.md issue list(每条 finding 含:问题、影响点、修复建议)。

C0 — 前置:runner 产物完整性

• 期望:三模式子目录均存在,每模式至少 captured.md/status.md/console.jsonl 三个文件(非空)。
• 失败 → 标 Incomplete runner artifacts,提示重跑 e2e-runner。不算 判定 C1-C4 失败,直接判 FAIL。

C1 — 无 failure.md

• 期望:三模式子目录下均无 failure.md。
• 失败 → 该模式判 fail,整体 FAIL。Finding 含 failure.md 里的 error/stack/last_log_* 字段。

C2 — 单批 duration 异常

• 读 status.md 的 duration_ms / batch_count:
  • batch_count == 0 或 duration_ms 缺失 → 跳过本判定(归 C0 或 C1)。
  • 计算 avg_batch_ms = duration_ms / batch_count。
• 阈值:单批平均耗时 > 60s(issue #32 example;status.md 只暴露 duration_ms / batch_count,无 per-batch 计时,所以公式取平均 avg_batch_ms = duration_ms / batch_count,超 60000 即视为异常, 记 finding "Single batch duration > 60s")。
• 影响:单批 60s 意味着要么 API 慢、要么该批段落超长、要么协议层卡住。 修复建议:看 console.jsonl 找 phase:'translate', event:'batch' 的 data.batchStartTs 间隔;若 API 慢则检查 ai-provider-test.txt 与 chrome.storage.local 端 baseURL;若超长则看 data.batchSize。
• 注:此处阈值与 .claude/skills/baoyu-translate/.../refined-workflow.md 无关,是 e2e 流水线级的硬性 SLA,锁在诊断里便于回归。

C3 — console error 事件

• 读 console.jsonl,逐行 JSON.parse,找:
  • phase == 'task' && event == 'error'
  • phase == 'ai' && event == 'error'
• 期望:三模式 console.jsonl 中均无以上事件。
• 失败 → 该 finding 列出命中行(ts + data 摘要,不含 apiKey —— 已被 shared/logging.ts::redactPayload 替换为 [REDACTED])。
• 注:phase == 'task' && event == 'cancel' 不算 error( 对应用户点取消的合法路径)。

C4 — captured.md 段落数 ±30%

• 读 captured.md 的 paragraph_count: 行(或对文件数空行 split 计数 —— runner 已写好 paragraph_count: 行,直接读)。
• 读 tests/reference/article-zh-CN-<mode>/translation.md 的段落数 (空行 split,与 captured.md 计数方式一致)。
• 阈值:captured / reference ∈ [0.7, 1.3]。超出 → 标 "Paragraph count drift ±30%"。
• 边界:若 reference = 0(e.g. reference 文件被误删),跳过本判定并标 "Reference missing" finding,不算 FAIL(这是 C0-C4 唯一不阻断 PASS 的情形),但要写进 diagnosis.md 便于维护者补 reference。
• 影响:段落数偏离意味着 extractor 漏抽或合并段落、injector 重复注入。 修复建议:用 tests/e2e-out/<ts-sha>/<mode>/captured.md 的人工 grep 对照 tests/reference/article-zh-CN-<mode>/translation.md 找差异模式; 视情况回溯 src/content/extractor.ts(见 ADR-0001)。

diagnosis.md shape

# e2e diagnosis — <ts-sha>

verdict: <PASS|FAIL>                            # 调用方 grep 这一行决定后续
generated_at: <ISO timestamp>

## Per-mode summary

| mode        | status    | paragraphs (captured / reference) | duration_ms | batches | failure.md | console.error |
|-------------|-----------|-----------------------------------|-------------|---------|------------|---------------|
| quick       | complete  | 73 / 75 (97%)                     | 4200        | 1       | absent     | 0             |
| normal      | complete  | 78 / 75 (104%)                    | 12300       | 2       | absent     | 0             |
| refined     | FAILED    | 12 / 84 (14%)                     | 6200        | 1       | present    | 1             |

## Criteria results

- [x] C0 runner artifacts complete                 — 3 modes, all files present
- [x] C1 no failure.md                             — 3 modes, none present
- [x] C2 single batch ≤ 60s                        — quick avg=4200ms OK; normal avg=6150ms OK; refined avg=6200ms OK
- [ ] C3 no console error events                   — refined: 1 hit, see findings
- [ ] C4 paragraph count within ±30%               — refined captured=12 ref=84 → 14% drift → FAIL

## Findings (FAIL only; ordered by impact)

### F1 — refined mode failure.md present (C1)
- **problem**: `tests/e2e-out/<ts-sha>/article-zh-CN-refined/failure.md` exists.
  - error: "Translation cancelled by user via popup"  ← 由 failure.md 读出
  - last_log_phase: "translate"
  - last_log_event: "cancel"
- **impact**: refined 模式未产出完整译文 → quality / reporter 缺一条输入;
  反映到端到端是用户能复现的"点 refined 翻译后没反应"。
- **fix suggestion**:
  1. 看 console.jsonl 找 `phase:'translate', event:'cancel'` 的 ts 与
     `data.reason`;若 `reason == 'user'`,此为用户行为,非缺陷,改
     e2e-runner 跑挂模拟。
  2. 若非用户取消,grep 全部 pipeline phase(`extract`/`analyze`/
     `translate`/`review`/`polish`/`inject`)的 `event:'error'`
     找根因(看 SW 端 `src/background/ai-adapter.ts` / `pipeline.ts`
     的对应阶段)。

### F2 — console error event in refined (C3)
- **problem**: `tests/e2e-out/<ts-sha>/article-zh-CN-refined/console.jsonl`
  含一条 `phase:'task', event:'error'`:
  `{"phase":"task","event":"error","ts":1717329014900,"data":{"message":"translate batch failed"}}`。
  - `apiKey` 字段不在该 payload(已脱敏)。
- **impact**: translate 阶段在 refined 跑批时失败一次,和 F1 的 cancel 事件
  时间相邻(`task.error` ts=1717329014900 vs `task.cancel` ts=1717329015000),
  极可能是 F1 的直接上游;用户表现为"点 refined 后译文没出来"。
- **fix suggestion**: 先解决 F1 的 cancel 根因(F1 fix-suggestion #2)后,
  该 task.error 通常会一并消失;若仍在,grep 同 console.jsonl 里
  `phase:'ai', event:'error'` / `phase:'ai', event:'retry'` 看 provider 端。

### F3 — paragraph count drift (C4)
- **problem**: refined 模式 captured 段落数 = 12,reference = 84,比值 14%
  (阈值 70%–130%)。
- **impact**: extractor 漏抽 86% 段落,或 injector 只注入了首批。极可能
  伴随 `failure.md` (本例就是)。
- **fix suggestion**: 先解决 F1 后重跑;若 F1 解决后 F3 仍在,看
  `console.jsonl` 里 `phase:'extract', event:'done'` 的
  `data.paragraphCount` —— 若该值 = 12,问题在 extractor;若 = 84,问题在
  injector / 状态恢复。

## Next step

- If verdict = PASS: caller decides to invoke /e2e-quality → /e2e-reporter.
- If verdict = FAIL: STOP. Forward `e2e-report.md` to maintainer.

diagnosis.md 的 issue list (Findings) 只在 FAIL 时写;PASS 时 只写 verdict + per-criteria + per-mode summary + "Next step: invoke e2e-quality"。

e2e-report.md shape (FAIL only)

# e2e report — <ts-sha>

verdict: <PASS|FAIL>                            # = diagnosis.md 同 verdict
status: FAILED                                  # 显式一行,人扫读
generated_at: <ISO timestamp>

## TL;DR

<一段话概括:哪几个模式挂了、第一条 finding 是什么、影响是什么>

## Issue list (acceptance form)

| # | mode | criterion | problem | impact |
|---|------|-----------|---------|--------|
| 1 | refined | C1 | failure.md present | 用户能复现的"refined 翻译无反应" |
| 2 | refined | C3 | console task.error (1 hit) | translate 批次失败一次,直接上游是 F1 |
| 3 | refined | C4 | 12/84 段落 (14%) | 86% 段落未注入 |
| ... |

## Per-mode snapshot

<一行/mode,同 diagnosis.md 的 per-mode summary 表>

## Refer to diagnosis.md for full evidence

判定证据(per-criteria pass/fail + 修复建议)完整版在同目录
`diagnosis.md`;本文件是验收形态,只挑结论。

## Next step

**STOP.** 不调用 /e2e-quality / /e2e-reporter。
Maintainer: 修完代码后重跑 `/e2e-runner` + `/e2e-diagnostician`。

e2e-report.md 是给"人"看的(cat / PR 评论 / CI artifact 摘要), diagnosis.md 是给"调用方 + 修复者"看的(grep verdict 决策 + 看 finding 排查)。两者 verdict 必须一致;两份都写同样的 <ts-sha> verdict: ... 行。

跨契约

ADR 契约(修改需同步两处):

• [baoyu] 前缀由 ADR-0002 写入端定义,本 skill 读取端通过 console.jsonl 间接消费(runner 已过滤)。修改前缀需同步 ADR-0002。
• gate 行为由 ADR-0003 §Consequences 锁定。修改 gate 阈值或决策 需同步 ADR-0003。

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

• LogPhase / LogEvent 枚举复用 src/shared/logging.ts(C3 判定 phase == 'task' 与 phase == 'ai' 来自该处)。
• TranslationMode 枚举复用 src/shared/types.ts,与 runner 共享 三模式子目录命名。
• reference 路径固定 tests/reference/article-zh-CN-<mode>/translation.md, 与 ADR-0003 §4.2 锁定。

产物契约(与 runner 严格同步):

• tests/e2e-out/<ts-sha>/<mode>/{captured.md,status.md,console.jsonl,failure.md?} 的 schema 与字段名(paragraph_count/duration_ms/batch_count/ status/final_a11y_text/error/stack/last_log_phase 等)由 .claude/skills/e2e-runner/SKILL.md 锁定;本 skill 读取端按该 schema 解析,任一字段缺失回退到 C0 失败(不强行猜)。

手工验证范式

PR / 调试时可手工跑(无需真实 e2e-runner),构造 runner 产物最小集:

TS_SHA="2026-06-02T10-30-00_abcdef1"
RUN="tests/e2e-out/${TS_SHA}"
mkdir -p "$RUN/article-zh-CN-quick" "$RUN/article-zh-CN-normal" "$RUN/article-zh-CN-refined"

场景 A:全 success,期望 PASS

for mode in quick normal refined; do
  cat > "$RUN/article-zh-CN-$mode/captured.md" <<EOF
# article-zh-CN-$mode
paragraph_count: 75
captured_at: 2026-06-02T10:30:42Z

<译文段落 1>

<译文段落 2>
EOF
  cat > "$RUN/article-zh-CN-$mode/status.md" <<EOF
# article-zh-CN-$mode
url: https://takes.jamesomalley.co.uk/p/this-might-be-oversharing
mode: $mode
status: complete
paragraph_count: 75
batch_count: 1
duration_ms: 4200
final_a11y_text: complete
EOF
  echo '{"phase":"task","event":"complete","ts":1717329030000,"data":{"durationMs":4200,"paragraphCount":75}}' \
    > "$RUN/article-zh-CN-$mode/console.jsonl"
done

期望:触发本 skill,diagnosis.md 写 + verdict=PASS,e2e-report.md 不写。 调用方可继续 /e2e-quality → /e2e-reporter。

场景 B:某模式 failure.md 存在 + 段落漂移,期望 FAIL

# quick + normal 复用场景 A
for mode in quick normal; do cp -r "$RUN/article-zh-CN-quick" "$RUN/article-zh-CN-$mode"; done

# refined 改成失败
cat > "$RUN/article-zh-CN-refined/failure.md" <<'EOF'
# article-zh-CN-refined — FAILED
error: Translation cancelled by user via popup
stack: 
final_a11y_text: cancelled
console_jsonl_lines: 8
last_log_phase: translate
last_log_event: cancel
last_log_ts: 1717329015000
EOF
cat > "$RUN/article-zh-CN-refined/status.md" <<EOF
# article-zh-CN-refined
url: https://takes.jamesomalley.co.uk/p/this-might-be-oversharing
mode: refined
status: cancelled
paragraph_count: 12
batch_count: 1
duration_ms: 6200
final_a11y_text: cancelled
EOF
# 调低 captured 段落数,触发 C4
sed -i 's/paragraph_count: 75/paragraph_count: 12/' "$RUN/article-zh-CN-refined/captured.md"
# console.jsonl 加一条 task.error 事件,触发 C3
echo '{"phase":"task","event":"error","ts":1717329014900,"data":{"message":"translate batch failed"}}' \
  >> "$RUN/article-zh-CN-refined/console.jsonl"

期望:触发本 skill,diagnosis.md 写 + verdict=FAIL,e2e-report.md 也写。 Issue list 含 F1 (failure.md / C1) + F2 (console task.error / C3) + F3 (段落漂移 / C4)。 不调用 /e2e-quality / /e2e-reporter。

不在本 skill 范围

• 跑 runner:/e2e-runner 的工作。本 skill 假定产物已存在。
• 质量对比:captured.md vs reference 的 jaccard / 2-gram / Claude judge 评分由 /e2e-quality 负责。本 skill 只看结构层信号 (段落数 / 失败标志 / error 事件 / 耗时),不评译文本身。
• 成功 case 的最终 e2e-report.md:本 skill 不写;成功时留给 /e2e-reporter 在 /e2e-quality 之后覆盖。
• CI artifact retention:与 runner 一致,本地产物由 .gitignore 屏蔽(Slice 5 落地),CI retention 由 CI 系统决定。
• threshold 调优:C2/C4 阈值由 issue #32 / ADR-0003 锁定,本 skill 不暴露配置项;调整需改 ADR 并开新 issue。

用法

触发本 skill 后:

1. 定位 run 目录:
   • 若用户给了 <ts-sha>,用 tests/e2e-out/<ts-sha>/。
   • 若没给,ls -1 tests/e2e-out/ | tail -1 取最新一个时间戳目录。
2. C0 完整性检查:三模式子目录 + 必出文件。失败直接判 FAIL 写产物。
3. C1-C4 逐条判定:每条收集证据(failure.md 内容 / status.md 数值 / console.jsonl 命中行 / captured.md 段落数)。
4. 写 diagnosis.md:per-mode 表 + criteria 结果 + findings (FAIL 时)
   • next step。
5. 若 FAIL,写 e2e-report.md:TL;DR + issue list 表 + next step "STOP"。
6. 回报用户:
   • PASS:"Diagnosis PASS for <ts-sha>. diagnosis.md 写了;e2e-report.md 未写(留给 e2e-reporter)。下一步:调 /e2e-quality。"
   • FAIL:"Diagnosis FAIL for <ts-sha>. diagnosis.md + e2e-report.md 都写了 — 验收形态在 e2e-report.md。后续 quality / reporter 不执行, 修代码后重跑 runner + diagnostician。"

故障排查

现象	根因	修复
verdict=PASS 但 runner 明显挂了	C1-C4 漏判;检查 console.jsonl 是不是没被过滤 [baoyu]	看 raw console 是否含 phase:'task', event:'error' 但 console.jsonl 缺它 → runner 没过滤干净
C4 reference 段落数算错	reference 文件被手工改过,或读取方式不一致	awk 'NF>0' tests/reference/article-zh-CN-quick/translation.md | wc -l 对照 captured.md 的 paragraph_count:
verdict=FAIL 但实际三个模式都过	C0 误判(产物缺文件)或 C1 误判(failure.md 不该有)	看 diagnosis.md 的 criteria 段,看是哪一条先红
e2e-report.md 在 PASS 时被生成	漏检 verdict 后再写 e2e-report.md 的逻辑	写产物前 if-分支:verdict == FAIL 才写
console.jsonl 是 null / 不可 parse	runner 写盘时没序列化第二参数	重跑 runner;该 bug 不在本 skill 修

参考

• PRD #26:父 PRD(Slice 6 / 第 6 片)。
• ADR-0002:日志 schema + [baoyu] 前缀契约(C3 判定用到 phase 枚举)。
• ADR-0003:e2e 流水线 + gate 行为 + 产物契约。
• .claude/skills/e2e-runner/SKILL.md:输入端产物 schema 来源(Slice 5)。
• src/shared/logging.ts:LogPhase / LogEvent / LogPayload 定义。
• src/shared/types.ts:TranslationMode 枚举。
• tests/reference/article-zh-CN-<mode>/translation.md:C4 ground truth。