@kernel-sig/console 0.1.0

package/scripts/e2e-verify.py

@@ -0,0 +1,773 @@
+#!/usr/bin/env python3
+"""浏览器端端到端验证。
+
+断言的是**页面上实际渲染出的内容**，而非接口返回值 ——
+接口正确但前端渲染错误、或路由时序有误的情况，只有浏览器测试能发现。
+（本项目的"登录后被弹回登录页"与"刷新后会话丢失"两个缺陷正是这样发现的。）
+
+用法：
+    KSC_E2E_PASSWORD=<实例口令> python3 scripts/e2e-verify.py
+    KSC_BASE_URL=http://host:port KSC_E2E_PASSWORD=xxx python3 scripts/e2e-verify.py
+
+依赖：pip install playwright && playwright install chromium
+"""
+
+import os
+import re
+import sys
+
+from playwright.sync_api import Page, sync_playwright
+
+BASE = os.environ.get("KSC_BASE_URL", "http://localhost:18080")
+USERNAME = os.environ.get("KSC_E2E_USERNAME", "admin")
+
+# 口令只从环境变量取，不给默认值。这个脚本登的是**你自己的实例**，
+# 在源码里写死任何一个口令，都等于随代码一起公开它。
+PASSWORD = os.environ.get("KSC_E2E_PASSWORD")
+if not PASSWORD:
+    sys.exit("请用 KSC_E2E_PASSWORD 环境变量提供实例口令")
+
+# 表格的数据行。
+#
+# AntD 的 Table 会在 tbody 的第一个位置插一个 aria-hidden 的度量行，用来
+# 量出各列的宽度；它没有内容、也不是一条数据。自建的表格没有这一行。
+# 这个选择器对两种实现都成立 —— 迁移过程中两种表格并存，断言不必跟着改。
+DATA_ROWS = "tbody tr:not(.ant-table-measure-row)"
+
+results: list[tuple[str, bool, str]] = []
+
+# 只跑指定段落，逗号分隔的**标题子串**，例如：
+#   KSC_E2E_SECTIONS=pulls,issues python3 scripts/e2e-verify.py
+# 全量约三分钟。改一处界面就要等三分钟的话，人很快就会不再跑它 ——
+# 而这份脚本是前端唯一的一层网（前端没有单元测试）。
+ONLY = [part.strip() for part in os.environ.get("KSC_E2E_SECTIONS", "").split(",") if part.strip()]
+
+_skipping = False
+
+
+def check(name: str, ok: bool, detail: str = "") -> None:
+    if _skipping:
+        return
+    results.append((name, ok, detail))
+    print(f"[{'PASS' if ok else 'FAIL'}] {name}" + (f" — {detail}" if detail else ""))
+
+
+def section(title: str) -> None:
+    global _skipping
+    _skipping = bool(ONLY) and not any(part in title for part in ONLY)
+    if _skipping:
+        print(f"\n─── {title} ───（跳过）")
+        return
+    print(f"\n─── {title} ───")
+
+
+def login(page: Page) -> None:
+    page.goto(f"{BASE}/login", wait_until="networkidle")
+    page.get_by_label("用户名").fill(USERNAME)
+    page.get_by_label("密码").fill(PASSWORD)
+    page.get_by_role("button", name="登录").click()
+    page.wait_for_url("**/dashboard", timeout=15000)
+    page.wait_for_load_state("networkidle")
+
+
+def verify_auth(page: Page) -> None:
+    """认证与路由守卫。"""
+    section("认证与路由守卫")
+
+    page.goto(BASE, wait_until="networkidle")
+    check("未登录访问 / 被路由守卫拦截", page.url.endswith("/login"), page.url)
+
+    check("登录页标题渲染", page.get_by_role("heading", name="登录").is_visible())
+
+    bg = page.evaluate("getComputedStyle(document.body).backgroundColor")
+    check("主题令牌生效（非默认白底）", bg != "rgb(255, 255, 255)", bg)
+
+    # 错误凭据应给出后端返回的提示，且不泄露账号是否存在
+    page.get_by_label("用户名").fill(USERNAME)
+    page.get_by_label("密码").fill("definitely-wrong-password")
+    page.get_by_role("button", name="登录").click()
+    alert = page.get_by_role("alert")
+    alert.wait_for(state="visible", timeout=8000)
+    check("错误凭据显示提示", "用户名或密码错误" in alert.inner_text())
+    check("错误后停留在登录页", page.url.endswith("/login"))
+
+    login(page)
+    check("登录后跳转到仪表盘", page.url.endswith("/dashboard"), page.url)
+
+    page.reload(wait_until="networkidle")
+    page.wait_for_timeout(1200)
+    check("刷新后会话保持", page.url.endswith("/dashboard"), page.url)
+
+    cookies = page.context.cookies()
+    access = next((c for c in cookies if c["name"] == "ksc_access"), None)
+    check("访问令牌 Cookie 为 HttpOnly", bool(access and access.get("httpOnly")))
+
+    page.goto(f"{BASE}/setup", wait_until="networkidle")
+    page.wait_for_timeout(1000)
+    check("已初始化后 /setup 被拒", not page.url.endswith("/setup"), page.url)
+
+
+def verify_pulls(page: Page) -> None:
+    """PR 列表与详情。"""
+    section("PR 列表与详情")
+
+    page.goto(f"{BASE}/pulls", wait_until="networkidle")
+    page.wait_for_timeout(2500)
+    body = page.inner_text("body")
+    check("PR 列表渲染", "Pull Request" in body)
+
+    rows = page.locator(DATA_ROWS)
+    count = rows.count()
+    check("列表有数据行", count > 0, f"{count} 行")
+
+    # 门禁筛选：这是列表页的核心交互。
+    # 分面栏的每个取值现在是 AntD 的 Checkbox（原来是自绘方块加
+    # `<button aria-pressed>`），所以按 role 定位而不是按 button。
+    # 可访问名含计数，例如「可合入 196」，按子串匹配即可。
+    ready = page.get_by_role("checkbox", name="可合入").first
+    if ready.count() > 0:
+        ready.click()
+        page.wait_for_timeout(1800)
+        after = page.locator(DATA_ROWS).count()
+        all_ready = after > 0 and all(
+            "可合入" in rows.nth(i).inner_text() for i in range(min(after, 5))
+        )
+        check("门禁筛选「可合入」结果正确", all_ready, f"{after} 行")
+        # 勾选后地址栏应带上该筛选 —— 这是"筛选可分享"的前提
+        check("筛选写入地址栏", "stage=ready_to_merge" in page.url, page.url)
+
+        # 用一次干净的导航重置，而不是点"清除"再点一次。
+        # 分面栏每一维都有自己的"清除"，`has_text="清除"` 会命中第一个维度，
+        # 于是门禁筛选残留下来，把后面几步一起带偏 —— 而失败信息还指向别处。
+        page.goto(f"{BASE}/pulls", wait_until="networkidle")
+        page.wait_for_timeout(1500)
+        check("重置后筛选已清空", "stage=" not in page.url, page.url)
+    else:
+        check("存在门禁筛选条", False)
+
+    # 搜索
+    search = page.get_by_placeholder("按标题或 PR 编号搜索，回车确认")
+    search.fill("KVM")
+    search.press("Enter")
+    page.wait_for_timeout(1800)
+    check("搜索有结果", page.locator(DATA_ROWS).count() > 0)
+    check("搜索写入地址栏", "q=KVM" in page.url, page.url)
+
+    # 详情。挑一个带标签的 PR：标签面板在没有标签时不渲染，
+    # 用列表第一条会把"这条 PR 恰好没有标签"误报成界面缺陷。
+    labelled = _pull_with_labels(page)
+    if labelled:
+        page.goto(f"{BASE}/pulls/{labelled}", wait_until="networkidle")
+    else:
+        page.goto(f"{BASE}/pulls", wait_until="networkidle")
+        page.wait_for_timeout(1500)
+        page.locator(DATA_ROWS).first.locator("a").first.click()
+        page.wait_for_url("**/pulls/**", timeout=15000)
+    page.wait_for_timeout(2500)
+    detail = page.inner_text("body")
+    check("进入 PR 详情", "/pulls/" in page.url)
+    check("详情含合并门禁面板", "合并门禁" in detail)
+    check("详情含元信息面板", "元信息" in detail)
+    check("详情含标签面板", "标签" in detail, "取自确实带标签的 PR")
+    check("详情含分类面板", "分类" in detail)
+    # 逐个断言存在并点击。原先是 `if count() > 0` 才点，
+    # 标签改名后会静默通过 —— 那种断言等于没写。
+    #
+    # AntD 的 Tabs 渲染成 role=tab 而不是 button（自绘的那版是 button），
+    # 且可访问名含条数角标，例如「提交 27」，所以按子串匹配。
+    for tab in ["概览", "提交", "文件变更", "讨论", "AI 分析"]:
+        el = page.get_by_role("tab", name=tab)
+        check(f"详情页含「{tab}」标签", el.count() > 0)
+        if el.count() > 0:
+            el.click()
+            page.wait_for_timeout(900)
+    check("详情页标签可切换", True)
+
+    # 切回讨论页签，确认内容确实换了（点击生效不等于面板渲染了）
+    page.get_by_role("tab", name="讨论").click()
+    page.wait_for_timeout(1200)
+    check(
+        "切到讨论页签后面板已渲染",
+        page.locator("details").count() > 0 or "评审" in page.inner_text("body"),
+    )
+
+
+def verify_issues(page: Page) -> None:
+    section("Issue 列表")
+
+    page.goto(f"{BASE}/issues", wait_until="networkidle")
+    page.wait_for_timeout(2500)
+    check("Issue 列表渲染", "Issue" in page.inner_text("body"))
+    check("列表有数据行", page.locator(DATA_ROWS).count() > 0)
+
+    # 类型筛选使用 AtomGit 原生 issue_type
+    for label in ["内核缺陷", "内核需求", "任务"]:
+        button = page.locator("button", has_text=label).first
+        if button.count() > 0:
+            button.click()
+            page.wait_for_timeout(1800)
+            rows = page.locator(DATA_ROWS)
+            ok = rows.count() > 0 and label in rows.first.inner_text()
+            check(f"按类型「{label}」筛选结果正确", ok)
+            button.click()
+            page.wait_for_timeout(1000)
+            break
+
+
+def verify_dashboard(page: Page) -> None:
+    section("总览仪表盘")
+
+    page.goto(f"{BASE}/dashboard", wait_until="networkidle")
+    page.wait_for_timeout(2500)
+    body = page.inner_text("body")
+    for label in ["可合入", "阻塞中", "待评审", "超 30 天未评审"]:
+        check(f"指标卡「{label}」", label in body)
+    for block in ["门禁阶段分布", "流转效率", "仓库概况", "评审人工作量"]:
+        check(f"区块「{block}」", block in body)
+
+    # 指标卡与门禁阶段都要能点进去：看到"CI 失败 83"却点不进去，
+    # 就得自己去列表页把筛选重选一遍 —— 那正是这个平台要消掉的一步。
+    targets = page.locator("a[href*='/pulls?']")
+    check("指标卡/阶段行可点进筛选后的列表", targets.count() >= 4, f"{targets.count()} 处")
+    stage_rows = page.locator("a[title^='查看处于']")
+    check("门禁阶段整行是链接", stage_rows.count() > 0, f"{stage_rows.count()} 行")
+    if stage_rows.count() > 0:
+        href = stage_rows.first.get_attribute("href")
+        check("阶段链接带上该阶段筛选", bool(href) and "stage=" in href, href)
+
+    # 首页的关注数字与队列页同源：分别统计的话，关掉一条规则后
+    # 两个页面会显示两个不同的组数，而且从界面上看不出谁对。
+    dashboard_groups = re.search(r"收敛为 (\d+) 组", body)
+    check("首页给出收敛后的组数", dashboard_groups is not None)
+    if dashboard_groups:
+        page.goto(f"{BASE}/attention", wait_until="networkidle")
+        page.wait_for_timeout(3000)
+        queue_groups = re.search(r"收敛为 (\d+) 组", page.inner_text("body"))
+        check(
+            "首页与队列页组数一致",
+            queue_groups is not None and queue_groups.group(1) == dashboard_groups.group(1),
+            f"首页 {dashboard_groups.group(1)} / 队列 {queue_groups and queue_groups.group(1)}",
+        )
+        page.goto(f"{BASE}/dashboard", wait_until="networkidle")
+        page.wait_for_timeout(2000)
+
+
+def verify_attention(page: Page) -> None:
+    """关注队列。设计目标是**收敛**：一条规则一行，而不是每个命中对象一行。
+
+    断言因此落在"分组是否给出了判断依据与出路"上，而不是逐条列表能否筛选 ——
+    逐条列表已经被收敛掉了，那是这份页面存在的前提。
+    """
+    section("关注队列")
+
+    page.goto(f"{BASE}/attention", wait_until="networkidle")
+    page.wait_for_timeout(3000)
+    body = page.inner_text("body")
+
+    check("队列页渲染", "关注队列" in body)
+
+    # 每组一个「逐条处理」链接，用它数分组
+    group_count = page.locator("a", has_text="逐条处理").count()
+    check("收敛为分组视图", group_count > 0, f"{group_count} 组")
+    if group_count == 0:
+        # 也可能是规则被全部关掉 —— 那样页面必须说明原因，而不是留白
+        check("队列为空时说明原因", "关注队列为空" in body)
+        return
+
+    check("写明收敛前后条数", "收敛为" in body)
+
+    # 判定依据与处置建议：只列问题不给出路，队列就只是噪音来源
+    check("说明这条规则在提醒什么", "建议：" in body)
+    check("分组带严重程度", page.locator("span", has_text=re.compile(r"^(阻塞|严重|警告|提示)$")).count() > 0)
+    check("给出最久等待天数", "最久已等" in body)
+    check("规则名可读", any(name in body for name in ("评审超期", "CVE 未推进", "Issue 未指派", "长期无活动")))
+
+    href = page.locator("a", has_text="逐条处理").first.get_attribute("href")
+    check("逐条处理指向可筛选的列表", bool(href) and ("/pulls" in href or "/issues" in href), href)
+
+    # 样例展开后才有逐条的动作 —— 收敛视图默认不铺开，这是有意的
+    sample_btn = page.locator("button", has_text="样例").first
+    check("提供样例展开入口", sample_btn.count() > 0)
+    if sample_btn.count() > 0:
+        sample_btn.click()
+        page.wait_for_timeout(1200)
+        claim = page.locator("button", has_text="认领")
+        check("样例行提供认领入口", claim.count() > 0)
+        if claim.count() > 0:
+            claim.first.click()
+            try:
+                page.locator("button", has_text="交还").first.wait_for(
+                    state="visible", timeout=10000
+                )
+                check("认领后该行变为交还", True)
+            except Exception:
+                check("认领后该行变为交还", False, page.inner_text("body")[-200:])
+
+            check("组头统计已认领条数", "已认领" in page.inner_text("body"))
+
+            release = page.locator("button", has_text="交还").first
+            if release.count() > 0:
+                release.click()
+                page.wait_for_timeout(2000)
+                check("交还后恢复为认领", page.locator("button", has_text="认领").count() > 0)
+
+    # 订阅设置：规则可关、阈值可调、范围可限定
+    page.get_by_role("button", name="关注设置").click()
+    page.wait_for_timeout(1500)
+    settings = page.inner_text("body")
+    check("关注设置可展开", "阈值" in settings)
+    # 阈值是 AntD 的 InputNumber：它的内层 input 是 type="text" 配
+    # role="spinbutton"，不再有 type=number
+    thresholds = page.get_by_role("spinbutton")
+    check("阈值可调", "天" in settings and thresholds.count() > 0, f"{thresholds.count()} 个")
+    # 范围选项要**点开浮层**才存在：AntD 的选项按需渲染，不像原生 select
+    # 那样把全部 option 一直放在 DOM 里。查页面文本永远查不到。
+    # 用属性后缀定位而不是写死某条规则的名字 —— 规则名会改，后缀不会。
+    scope = page.locator('[aria-label$="适用范围"]').first
+    check("适用范围可限定", scope.count() > 0)
+    if scope.count() > 0:
+        scope.click()
+        page.wait_for_timeout(800)
+        choices = page.locator(".ant-select-item-option:visible").all_inner_texts()
+        check(
+            "范围可选全部/仅 PR/仅 Issue",
+            {"全部", "仅 PR", "仅 Issue"} <= set(choices),
+            str(choices),
+        )
+        page.keyboard.press("Escape")
+        page.wait_for_timeout(500)
+    check("写明改动生效时机", "重算" in settings)
+
+    first = page.locator("input[type=checkbox]").first
+    check("关注设置列出规则开关", first.count() > 0)
+    if first.count() > 0:
+        was_checked = first.is_checked()
+        first.click()
+        page.wait_for_timeout(1500)
+        check("规则开关可切换", page.locator("input[type=checkbox]").first.is_checked() != was_checked)
+        # 复原：这套设置是全局的，验证不能把环境留在改动后的状态
+        page.locator("input[type=checkbox]").first.click()
+        page.wait_for_timeout(1500)
+        check("规则开关可还原", page.locator("input[type=checkbox]").first.is_checked() == was_checked)
+
+
+def _pull_with_classification(page: Page) -> str | None:
+    """挑一个已有分类结果、且不是人工指定的 PR。
+
+    不能用列表第一行：列表按"最近更新"排序，而分类任务每 10 分钟才跑一轮，
+    刚同步进来的 PR 会排在最前且尚无分类 —— 那时分类面板显示"尚未分类"，
+    根本没有"修改"入口。取第一行测的是"这十分钟里没有新 PR 进来"。
+
+    也不能挑人工指定的：那种条目的入口文案是「撤销人工指定」。
+    """
+    repos = page.request.get(f"{BASE}/api/v1/repositories")
+    if repos.status != 200 or not repos.json():
+        return None
+    repo_id = repos.json()[0]["id"]
+    resp = page.request.get(
+        f"{BASE}/api/v1/repositories/{repo_id}/classifications",
+        params={"per_page": 50},
+    )
+    if resp.status != 200:
+        return None
+    for item in resp.json()["items"]:
+        if item.get("subject_type") == "pull_request" and item.get("source") != "manual":
+            return item["subject_id"]
+    return None
+
+
+def verify_classification(page: Page) -> None:
+    """PR 详情页的分类面板与人工覆盖。"""
+    section("分类与人工覆盖")
+
+    classified = _pull_with_classification(page)
+    if classified:
+        page.goto(f"{BASE}/pulls/{classified}", wait_until="networkidle")
+    else:
+        page.goto(f"{BASE}/pulls", wait_until="networkidle")
+        page.wait_for_timeout(2500)
+        page.locator(DATA_ROWS).first.locator("a").first.click()
+        page.wait_for_url("**/pulls/**", timeout=15000)
+    page.wait_for_timeout(2500)
+
+    body = page.inner_text("body")
+    check("详情页含分类面板", "分类" in body)
+    # AI 分析标签必须存在，否则整套 AI 对接在界面上不可达
+    check("详情页含 AI 分析标签", "AI 分析" in body)
+
+    # 点开修改，指定一个类型并保存，随后应标记为人工指定
+    edit = page.locator("button", has_text="修改").first
+    if edit.count() == 0:
+        check("分类面板提供修改入口", False)
+        return
+
+    edit.click()
+    page.wait_for_timeout(800)
+
+    # AntD 的 Select 不是原生 <select>，没有 select_option()：点开浮层，
+    # 输入类别名过滤，再点命中的选项。
+    #
+    # 两点注意，都是 AntD 这个组件的信息架构决定的：
+    # 一是浮层里的列表是虚拟滚动的，只渲染可视窗口内的几项，所以要先过滤
+    #   （该 Select 开了 showSearch 且按 label 过滤）；
+    # 二是浮层里同时存在两套结构 —— 一套给读屏器的隐藏 listbox（role=option
+    #   在它们身上，但尺寸为零、点不到），一套可见列表（只带类名，没有 role）。
+    #   所以按 role 定位一定超时，只能按可见性加类名。
+    page.get_by_label("类型").click()
+    page.wait_for_timeout(500)
+    page.get_by_label("类型").fill("新功能")
+    page.wait_for_timeout(600)
+    page.locator(".ant-select-item-option:visible", has_text="新功能").first.click()
+    page.wait_for_timeout(500)
+    page.get_by_label("子系统").fill("mm")
+    page.locator("button", has_text="保存").first.click()
+    page.wait_for_timeout(2500)
+
+    after = page.inner_text("body")
+    check("人工指定后显示「人工」标记", "人工" in after)
+    check("人工指定后类型生效", "新功能" in after)
+    check("人工指定后出现撤销入口", "撤销人工指定" in after)
+
+    # 撤销后交还给自动分类。「交还」必须立刻生效，而不是等下一轮定时重算 ——
+    # 点了按钮类型却没变，使用者只会以为按钮坏了。
+    undo = page.locator("button", has_text="撤销人工指定").first
+    if undo.count() > 0:
+        undo.click()
+        page.wait_for_timeout(3000)
+        restored = page.inner_text("body")
+        check("撤销后不再显示人工标记", "人工" not in restored.split("分类")[-1][:400])
+        check("撤销后类型已由规则重算", "新功能" not in restored.split("分类")[-1][:400])
+
+
+def verify_ai(page: Page) -> None:
+    """AI 对接的设置页与分析面板。"""
+    section("AI 对接")
+
+    page.goto(f"{BASE}/settings/ai", wait_until="networkidle")
+    page.wait_for_timeout(2500)
+    body = page.inner_text("body")
+
+    check("AI 设置页渲染", "AI 对接" in body)
+    check("含模型端点区块", "模型端点" in body)
+    check("含任务路由区块", "任务路由" in body)
+    # 按任务配模型是成本控制的核心，四项任务都应列出
+    for task in ["类型判定", "变更摘要", "风险审查", "Backport 核对"]:
+        check(f"任务路由含「{task}」", task in body)
+    check("提示按次计费", "按次计费" in body or "计费" in body)
+
+    # 补判按钮的可用性必须与"是否配了端点"一致。
+    # 原先直接断言"禁用"，隐含假设环境里没配端点 —— 配过之后就永远失败，
+    # 而失败原因是环境而不是代码。这里改为由接口读实际状态再比对。
+    classify_button = page.locator("button", has_text="立即补判").first
+    if classify_button.count() > 0:
+        providers = page.request.get(f"{BASE}/api/v1/ai/providers")
+        configured = False
+        if providers.ok:
+            payload = providers.json()
+            rows = payload if isinstance(payload, list) else payload.get("items", [])
+            configured = any(row.get("is_enabled", True) for row in rows)
+        check(
+            "补判按钮可用性与端点配置一致",
+            classify_button.is_disabled() is not configured,
+            f"已配置端点={configured} 按钮禁用={classify_button.is_disabled()}",
+        )
+
+    # PR 详情页的 AI 分析面板
+    page.goto(f"{BASE}/pulls", wait_until="networkidle")
+    page.wait_for_timeout(2500)
+    page.locator(DATA_ROWS).first.locator("a").first.click()
+    page.wait_for_url("**/pulls/**", timeout=15000)
+    page.wait_for_timeout(2000)
+    # AntD 的页签是 role=tab，不是 button（自绘的那版是 button）
+    page.get_by_role("tab", name="AI 分析").click()
+    page.wait_for_timeout(1500)
+
+    ai_body = page.inner_text("body")
+    check("AI 面板渲染", "分析" in ai_body)
+    check("AI 面板说明不自动调用", "不自动执行" in ai_body or "按次计费" in ai_body)
+
+
+def verify_settings(page: Page, token: str | None) -> None:
+    section("仓库与凭据设置")
+
+    page.goto(f"{BASE}/settings/general", wait_until="networkidle")
+    page.wait_for_timeout(2000)
+    body = page.inner_text("body")
+    check("凭据区块渲染", "访问凭据" in body)
+    check("仓库区块渲染", "纳管仓库" in body)
+    check("显示凭据指纹而非明文", "指纹" in body)
+    check("显示 webhook 地址", "webhook" in body.lower())
+    # 计数来自接口，不硬编码具体数值，避免数据变化后误报
+    check("显示 PR 与 Issue 计数", "PR" in body and "Issue" in body)
+
+    if token:
+        leaked = token in page.content()
+        check("页面无凭据明文泄漏", not leaked)
+
+
+def _pull_with_labels(page: Page) -> str | None:
+    """挑一个确实带标签的 PR。
+
+    取列表第一条会随同步进来的新 PR 而变，而没有标签的 PR 本就不渲染
+    标签面板 —— 那样断言的是"当前排第一的 PR 有没有标签"，与代码无关。
+    """
+    repos = page.request.get(f"{BASE}/api/v1/repositories")
+    if repos.status != 200 or not repos.json():
+        return None
+    repo_id = repos.json()[0]["id"]
+    pulls = page.request.get(
+        f"{BASE}/api/v1/repositories/{repo_id}/pulls",
+        params={"state": "all", "per_page": 50},
+    )
+    if pulls.status != 200:
+        return None
+    for item in pulls.json()["items"]:
+        if item.get("label_names"):
+            return item["id"]
+    return None
+
+
+def verify_versions(page: Page) -> None:
+    """版本与分支页。维护者来这里问的是"这个版本现在什么状态、谁负责"。"""
+    section("版本与分支")
+
+    page.goto(f"{BASE}/branches", wait_until="networkidle")
+    page.wait_for_timeout(3000)
+    body = page.inner_text("body")
+    check("版本列表渲染", "版本与分支" in body)
+    check("列出负责人", "@" in body, "负责人来自 sig-info.yaml")
+
+    # 待处理数是判断"该不该现在动手"的依据，必须能点进那批 PR
+    pending = page.locator("a[href*='branch=']").first
+    check("待处理可点进该分支的 PR", pending.count() > 0)
+
+    page.locator(f"{DATA_ROWS} a").first.click()
+    page.wait_for_url("**/branches/**", timeout=15000)
+    page.wait_for_timeout(3000)
+    detail = page.inner_text("body")
+
+    check("详情页给出负责人", "负责人" in detail)
+    check("给出上游基线", "上游基线" in detail or "基础版本" in detail)
+    check("给出当前 tag", "当前 tag" in detail)
+    check("给出合入趋势", "合入趋势" in detail)
+
+    # 分期总结：用户要的是"每个版本的双周/月度合入总结"，不是只有上一期。
+    # 期次行仍是原生 <li><button>，但标记从 aria-pressed 换成了 aria-current：
+    # 一行是一期、带合入数与贡献者，语义是"当前查看的是这条"，
+    # 不是"这个开关被按下了"。
+    check("给出分期合入总结", "分期合入总结" in detail)
+    period_rows = page.locator("li button[aria-current]")
+    check("分期总结列出多期", period_rows.count() >= 2, f"{period_rows.count()} 期")
+    check("选中的那期被标出", period_rows.count() > 0 and period_rows.first.get_attribute("aria-current") == "true")
+
+    check("分期带 CVE 数", "CVE" in detail)
+    check("含发版说明", "发版说明" in detail)
+
+    # 粒度切换现在是 AntD 的 Segmented。它的可点击元素是 label，
+    # 里面那个 input[type=radio] 是给读屏器与键盘用的、视觉上不可见 ——
+    # 按 role 定位会拿到那个 input，直接点它点不动。
+    # 页面上有两个切换（合入趋势与分期总结各一个），取第一个。
+    monthly = page.locator("label.ant-segmented-item", has_text="按月").first
+    check("可切换月/双周", monthly.count() > 0)
+    if monthly.count() > 0:
+        monthly.click()
+        page.wait_for_timeout(2500)
+        check("切到按月后仍渲染", "分期合入总结" in page.inner_text("body"))
+
+
+def verify_meetings(page: Page) -> None:
+    """SIG 例会页。"""
+    section("SIG 例会")
+
+    page.goto(f"{BASE}/meetings", wait_until="networkidle")
+    page.wait_for_timeout(3000)
+    body = page.inner_text("body")
+    check("例会列表渲染", "SIG 例会" in body)
+    check("给出统计口径", "已开例会" in body and "累计议题" in body)
+    check("给出主持轮值", "主持轮值" in body)
+    check("列出会议日期", re.search(r"\d{4}-\d{2}-\d{2}", body) is not None)
+
+    links = page.locator("a[href*='/meetings/']")
+    check("会议可点进详情", links.count() > 0, f"{links.count()} 场")
+    if links.count() == 0:
+        return
+
+    links.first.click()
+    page.wait_for_url("**/meetings/**", timeout=15000)
+    page.wait_for_timeout(2500)
+    detail = page.inner_text("body")
+
+    check("详情页给出议题", "议题" in detail)
+    check("详情页给出统计", "涉及 PR" in detail)
+    check("详情页可回列表", "返回例会" in detail)
+    check("详情页可翻上一场", "上一场" in detail or "下一场" in detail)
+
+
+def verify_no_leak(page: Page, token: str | None) -> None:
+    """用真实 token 值比对，而非检查头部名称字符串。"""
+    if not token:
+        return
+    section("凭据泄漏检查")
+    for path in ["/pulls", "/issues", "/settings/general", "/dashboard"]:
+        page.goto(f"{BASE}{path}", wait_until="networkidle")
+        page.wait_for_timeout(1000)
+        check(f"{path} 无 token 明文", token not in page.content())
+
+
+def verify_dom_contract(page: Page) -> None:
+    """迁移期间不许偷偷弄丢的东西。
+
+    全站 5700 行未迁移代码依赖 Tailwind 的 preflight：box-sizing 归一、
+    元素 margin 归零、列表不画圆点、裸 button 不带 UA 底色。AntD 会注入
+    自己的全局样式，这些一旦被顶掉，界面上只会"看着有点怪"，
+    没有任何断言会报错 —— 所以在这里钉成计算值。
+    """
+    section("DOM 契约")
+
+    # 把色值统一归一化后再比较：一边是 oklch 令牌，一边是浏览器算出的 rgb，
+    # 不归一化就没法比。做法与 antd-theme.ts 的 resolveToken 一致 ——
+    # 画一个像素再读回，这是唯一能把 oklch 变成 sRGB 的可靠读法。
+    resolve_js = """
+    (value) => {
+      const c = document.createElement('canvas');
+      c.width = 1; c.height = 1;
+      const ctx = c.getContext('2d');
+      ctx.clearRect(0, 0, 1, 1);
+      ctx.fillStyle = 'transparent';
+      ctx.fillStyle = value;
+      ctx.fillRect(0, 0, 1, 1);
+      const [r, g, b, a] = ctx.getImageData(0, 0, 1, 1).data;
+      return a === 255 ? `rgb(${r}, ${g}, ${b})` : `无法解析(${value})`;
+    }
+    """
+
+    page.goto(f"{BASE}/pulls", wait_until="networkidle")
+    page.wait_for_timeout(2500)
+
+    body_bg = page.evaluate(f"({resolve_js})(getComputedStyle(document.body).backgroundColor)")
+    surface0 = page.evaluate(
+        f"({resolve_js})(getComputedStyle(document.documentElement)"
+        f".getPropertyValue('--color-surface-0'))"
+    )
+    check("body 背景仍是页面底色令牌", body_bg == surface0, f"{body_bg} vs {surface0}")
+
+    rows = page.locator("table > tbody > tr")
+    check("列表页仍是语义表格", rows.count() > 0, f"{rows.count()} 行")
+
+    # preflight 的几条效果，用**临时插入的探针元素**来测，而不是去页面上
+    # 找恰好符合条件的那一个。原先这里拿分页的"上一页"按钮当裸 button 探针，
+    # 分页换成 AntD 组件后它就不存在了 —— 断言随之报错，而 preflight
+    # 其实好端端的。测的是 CSS 规则，就该直接测规则。
+    probes = page.evaluate(
+        """
+        () => {
+          const host = document.createElement('div');
+          host.style.cssText = 'position:absolute;left:-9999px;top:0';
+          host.innerHTML =
+            '<button>x</button><ul><li>x</li></ul><pre>x</pre><span></span>';
+          document.body.appendChild(host);
+          const read = (sel, prop) => {
+            const el = host.querySelector(sel);
+            return el ? getComputedStyle(el)[prop] : 'NO_ELEMENT';
+          };
+          const out = {
+            buttonBg: read('button', 'backgroundColor'),
+            listStyle: read('ul', 'listStyleType'),
+            preMarginTop: read('pre', 'marginTop'),
+            // box-sizing 是 preflight 里最要命的一条：丢了它，
+            // 全站 w-full + px-* 的盒子都会溢出
+            boxSizing: read('span', 'boxSizing'),
+          };
+          host.remove();
+          return out;
+        }
+        """
+    )
+    check("裸 button 背景透明（preflight）", probes["buttonBg"] == "rgba(0, 0, 0, 0)", probes["buttonBg"])
+    check("列表不画圆点（preflight）", probes["listStyle"] == "none", probes["listStyle"])
+    check("pre 无 UA 边距（preflight）", probes["preMarginTop"] == "0px", probes["preMarginTop"])
+    check("box-sizing 归一（preflight）", probes["boxSizing"] == "border-box", probes["boxSizing"])
+
+    # 讨论区 <details>/<ol> 的结构不在这里查：只有存在机器人评论的 PR 才会
+    # 渲染它们，而"哪个 PR 有"随同步变化 —— 那样的断言测的是数据。
+    # 该结构由 scripts/e2e-pr-detail.py 覆盖，它用显式传入的 KSC_PULL_ID 跑。
+
+
+def load_token() -> str | None:
+    env = os.environ.get("ATOMGIT_TOKEN")
+    if env:
+        return env
+    from urllib.parse import urlparse
+
+    path = os.path.expanduser("~/.git-credentials")
+    if not os.path.exists(path):
+        return None
+    with open(path, encoding="utf-8") as fh:
+        for line in fh:
+            parsed = urlparse(line.strip())
+            if parsed.hostname == "atomgit.com" and parsed.password:
+                return parsed.password
+    return None
+
+
+def main() -> int:
+    token = load_token()
+    with sync_playwright() as p:
+        browser = p.chromium.launch(headless=True)
+        context = browser.new_context(viewport={"width": 1500, "height": 1000})
+        page = context.new_page()
+
+        console_errors: list[str] = []
+        page.on(
+            "console",
+            lambda m: console_errors.append(m.text) if m.type == "error" else None,
+        )
+
+        # (段落标题, 执行体)。标题与各 verify_* 里 section() 的调用一致，
+        # 单段运行时据此跳过整段 —— 只让 check() 静默没用，
+        # 浏览器仍会把每个页面走一遍，省不下时间。
+        steps: list[tuple[str, object]] = [
+            ("认证与路由守卫", lambda: verify_auth(page)),
+            ("PR 列表与详情", lambda: verify_pulls(page)),
+            ("Issue 列表", lambda: verify_issues(page)),
+            ("关注队列", lambda: verify_attention(page)),
+            ("分类与人工覆盖", lambda: verify_classification(page)),
+            ("AI 对接", lambda: verify_ai(page)),
+            ("总览仪表盘", lambda: verify_dashboard(page)),
+            ("版本与分支", lambda: verify_versions(page)),
+            ("SIG 例会", lambda: verify_meetings(page)),
+            ("仓库与凭据设置", lambda: verify_settings(page, token)),
+            ("凭据泄漏检查", lambda: verify_no_leak(page, token)),
+            ("DOM 契约", lambda: verify_dom_contract(page)),
+        ]
+        try:
+            # 登录动作住在 verify_auth 里。只跑后段时必须先补一次登录，
+            # 否则每个页面都会被路由守卫弹回登录页，报出一堆假失败 ——
+            # 那比不跑更糟，会让人去查根本不存在的界面问题。
+            if ONLY and not any(part in "认证与路由守卫" for part in ONLY):
+                login(page)
+
+            for title, run in steps:
+                if ONLY and not any(part in title for part in ONLY):
+                    continue
+                run()
+        except Exception as exc:
+            check("脚本执行完成", False, f"{type(exc).__name__}: {exc}")
+        finally:
+            browser.close()
+
+    failed = [r for r in results if not r[1]]
+    print("\n" + "=" * 60)
+    print(f"通过 {len(results) - len(failed)} / {len(results)}")
+
+    # 未登录时对 /auth/me 的探测会返回 401，属预期行为，不计为错误
+    real_errors = [e for e in console_errors if "401" not in e]
+    if real_errors:
+        print("\n浏览器控制台错误（已排除会话探测的 401）:")
+        for error in real_errors[:10]:
+            print("  -", error[:200])
+    return 1 if failed or real_errors else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())