From 9d1d5fda3d87b1dc55eed8b918fd9d039c44c8a0 Mon Sep 17 00:00:00 2001 From: Harvey Zhao Date: Thu, 10 Sep 2026 18:58:19 +0800 Subject: [PATCH] docs(refactor): [DOC-13] allow in-app browser fallback --- AGENTS.md | 3 +++ .../2026-09-10-DOC-13-browser-fallback.md | 8 +++++++ refactor/fixtures/README.md | 2 +- refactor/plan.md | 9 ++++---- refactor/progress.md | 4 ++++ refactor/release-reviews.md | 3 +++ refactor/tasks.json | 23 ++++++++++++++++--- 7 files changed, 44 insertions(+), 8 deletions(-) create mode 100644 refactor/changes/2026-09-10-DOC-13-browser-fallback.md diff --git a/AGENTS.md b/AGENTS.md index e3bd306d2..573105781 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,6 +25,9 @@ After implementation, follow [refactor/release-reviews.md](refactor/release-revi complete the three review rounds and close blocking findings before candidate publication. Connected Chrome interaction checks complement committed automated browser tests; neither connection availability nor mocks replace actual playback or required device evidence. +If Chrome is unavailable, use the Codex in-app browser for supported real-page tests. +The user explicitly authorizes this fallback; record the actual browser/version and limitations. +Do not block ordinary browser checks solely on the Chrome extension connection. Each review fix remains a separate task and commit. Revalidate changed candidate contents. The user explicitly includes GitHub CI/CD modernization in this refactor. Follow [refactor/github-ci-cd.md](refactor/github-ci-cd.md) for PR checks, regression matrices, diff --git a/refactor/changes/2026-09-10-DOC-13-browser-fallback.md b/refactor/changes/2026-09-10-DOC-13-browser-fallback.md new file mode 100644 index 000000000..8a3b0b366 --- /dev/null +++ b/refactor/changes/2026-09-10-DOC-13-browser-fallback.md @@ -0,0 +1,8 @@ +# DOC-13：Chrome 不可用时使用内置浏览器 + +- 用户明确授权 Chrome 不可用时使用 Codex 内置浏览器，无需再次等待或确认。 +- 根 AGENTS、发布复盘规范和夹具说明记录回退方式、环境证据及能力限制。 +- 实际打开 http://127.0.0.1:8083/fixtures/api.html，内置浏览器显示 PASS，9 项基础 API 检查通过，errors 为空。页面报告 UA 为 Windows / Chrome 152.0.0.0；这是内置浏览器的 UA，不是外部 Chrome 已恢复的证明。 +- BASE-02 从连接阻塞回到待办，持久快照和契约完整性由该任务验收；没有把本次页面检查标成播放或发布通过。 +- 验证：计划生成/依赖/本地链接与 Git 差异检查。无生产源码/依赖/分发变更。 +- 独立本地提交带 DOC-13；回退可撤销本次文档提交，不修改旧浏览器失败记录。 diff --git a/refactor/fixtures/README.md b/refactor/fixtures/README.md index 21db58977..c9dfb2ae3 100644 --- a/refactor/fixtures/README.md +++ b/refactor/fixtures/README.md @@ -9,6 +9,6 @@ 运行 `node --test refactor/scripts/browser-server.test.mjs` 验证真实 HTTP 服务返回原始 JS 字节、样本范围和路由隔离；`node --check refactor/fixtures/api.js` 只检查脚本语法。两者不能证明页面能在浏览器运行。 -2026-09-10：Chrome 连接服务连续失败，用户要求先继续其他任务；api.html 尚未实际执行，没有 API 快照或浏览器通过记录。BASE-02 保持 blocked；恢复连接后打开完整 URL，确认页面 PASS、没有错误，再核对报告和来源、生成持久基线。 +2026-09-10：Chrome 连接服务失败后，用户明确授权使用 Codex 内置浏览器。内置浏览器已打开 api.html，9 项基础 API 检查全部通过，页面 errors 为空，报告已保存至缓存。BASE-02 连接阻塞解除，接续核对报告和来源、生成持久基线；此时尚未完成整个 API 基线任务，也未验证真实播放。 夹具与报告路径由基线任务维护；ENG-05 可复用并扩充受控等待、媒体错误和正式自动化。api.js 依据已核对源码设计断言，真实发布行为如有不同应调查并记录，不能修改断言来盲目通过。 diff --git a/refactor/plan.md b/refactor/plan.md index 70c5533bd..babac5ee2 100644 --- a/refactor/plan.md +++ b/refactor/plan.md @@ -2,9 +2,9 @@ > 由 tasks.json 生成。请修改数据后运行 `node refactor/scripts/plan.mjs --write`，不要手改本表。 -基线：`40fcda6a37d0049d42e49c1e64e70d4fd9ba5f7f`。总任务 212 项，范围 22 个包及工作区/示例。 +基线：`40fcda6a37d0049d42e49c1e64e70d4fd9ba5f7f`。总任务 213 项，范围 22 个包及工作区/示例。 -状态：todo 196 / doing 0 / blocked 1 / done 15 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。 +状态：todo 197 / doing 0 / blocked 0 / done 16 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。 前置依赖是启动条件；验收是完成条件。任务可以继续拆分，但不能复用或悄悄删除旧 ID。 @@ -53,6 +53,7 @@ | DOC-10 | workspace
记录 GitHub CI/CD 增强范围与验收 | DOC-09 | CI/CD 规范、四项实施任务与发布依赖 | 现有 workflow 核对、计划检查通过并独立提交；不冒充远端执行完成 | L | done | | DOC-11 | workspace
记录全部包各自升级一个大版本 | DOC-10 | 22 包目标版本清单、决策和发布/CI/复盘规则同步 | 版本表与 manifest 对照、计划检查通过并独立提交；不修改旧 API 兼容要求 | L | done | | DOC-12 | workspace
复审开发启动、验收覆盖及发布依赖 | DOC-11 | 语义依赖修正、版本实施任务、基线/分发分类及契约映射要求、校验器保护 | 原范围状态保持，计划检查和故障负例通过，独立提交 DOC-12 | M | done | +| DOC-13 | workspace
记录并验证内置浏览器回退规则 | DOC-08 | 根指令、复盘和夹具文档中的浏览器回退及实际环境证据 | 内置浏览器打开真实页面，报告基础检查结果及未覆盖项；独立提交 | L | done | ## 1 基线 @@ -60,7 +61,7 @@ | --- | --- | --- | --- | --- | --- | --- | | BASE-01 | workspace
固定核心与试点的最小发布基线 | DOC-07 | 核心及 chapter 的 npm tarball/integrity、源码 SHA、已知支持窗口；其他包标待核对 | 核心/试点来源可重跑；不虚构全生态已验证，各包 01 步负责补齐自身历史发布基线 | H | done | | BASE-HARNESS-01 | workspace
建立最小发布包浏览器采集夹具与服务 | BASE-01 | 固定 tarball 静态服务、本地媒体 Range、公开 API 采集页面及受控报告路径 | HTTP 精确内容/范围和路由隔离测试、夹具语法通过；浏览器采集仍由 BASE-02 负责 | M | done | -| BASE-02 | workspace
捕获公共 API 和属性描述符 | BASE-01, BASE-HARNESS-01 | 核心与试点的构造/默认值/静态和实例 API 快照，其余包由 01/02 步补齐；登记契约/版本/固定测试 ID/命令/报告与负责任务 | 真实发布包反射与旧用户调用可重跑，未验证项明确 | H | blocked | +| BASE-02 | workspace
捕获公共 API 和属性描述符 | BASE-01, BASE-HARNESS-01 | 核心与试点的构造/默认值/静态和实例 API 快照，其余包由 01/02 步补齐；登记契约/版本/固定测试 ID/命令/报告与负责任务 | 真实发布包反射与旧用户调用可重跑，未验证项明确 | H | todo | | BASE-03 | workspace
捕获事件、异步和生命周期 | BASE-02 | ready/restart/destroy、Promise、切源/插件事件 trace；登记契约/版本/固定测试 ID/命令/报告与负责任务 | 成功、失败、重入和多实例有断言，历史缺陷有标记；使用已发布包和最小可重跑探针启动，不等待后续 ENG 服务 | H | todo | | BASE-04 | workspace
捕获 DOM、CSS 和官方 demo | BASE-02 | 核心模板/类名/变量、键盘/焦点/可访问名称基线及全 demo 路径映射；docs-browser-testing.md 中 HTML/编辑器的脚本来源与存储状态；登记契约/版本/固定测试 ID/命令/报告与负责任务 | 核心/试点用户样式和输入用法已记录，其他 demo 运行状态与未知项明确；使用已发布包和最小可重跑探针启动，不等待后续 ENG 服务 | M | todo | | BASE-05 | workspace
捕获包入口、资源和类型消费 | BASE-01 | 全包 manifest/资源路径清单；核心/试点的 UMD/AMD/ESM/CJS/legacy/i18n 和类型消费者基线；登记契约/版本/固定测试 ID/命令/报告与负责任务；区分库/npm 与站点实际分发类别，SSR import/模板/非浏览器构造错误分别捕获 | 核心/试点隔离消费可运行，其他包由各自契约任务验证，thumbnail tool 差异已登记 | H | todo | @@ -413,7 +414,7 @@ - DOC-10: [记录](changes/2026-09-10-DOC-10-github-ci-cd.md) - DOC-11: [记录](changes/2026-09-10-DOC-11-major-version-policy.md) - DOC-12: [记录](changes/2026-09-10-DOC-12-execution-readiness-review.md) +- DOC-13: [记录](changes/2026-09-10-DOC-13-browser-fallback.md) - BASE-01: [记录](changes/2026-09-10-BASE-01-published-baseline.md) [记录](baselines/releases.json) - BASE-HARNESS-01: [记录](changes/2026-09-10-BASE-HARNESS-01-browser-fixture.md) -- BASE-02: Chrome 工具连接连续失败，重置后仍不可用；用户要求先继续其他任务。恢复连接后执行 api.html 并核对报告，HTTP 服务通过不代表浏览器通过。 - ENG-01: [记录](changes/2026-09-10-ENG-01-reproducible-toolchain.md) [记录](baselines/toolchain-validation.json) diff --git a/refactor/progress.md b/refactor/progress.md index 0f12a8334..a49058b2e 100644 --- a/refactor/progress.md +++ b/refactor/progress.md @@ -1,5 +1,9 @@ # 进度与证据 +## 当前实施：Yarn 选择与浏览器回退 + +用户指定 packageManager 使用 Yarn，正在准备 ENG-PM-01 替换 ENG-01 的 npm 默认工具选择。ENG-02 暂回待办，待 Yarn 锁定验证后接续。用户同时授权 Chrome 不可用时使用内置浏览器；9 项发布包基础 API 检查已通过，BASE-02 连接阻塞解除，完整快照任务仍待完成。详见 [DOC-13](changes/2026-09-10-DOC-13-browser-fallback.md)。历史 npm 和 Chrome 失败记录保留为当时事实。 + ## 当前实施：ENG-01 工具链已验证 Node 24.21.0/npm 11.19.0、16 个直接工具和 npm lock 已固定；干净安装 1141 包、原 19 项测试、21 库包 63 产物与文档站构建全部通过，已有依赖解析版本没有升级。详见 [ENG-01 交付](changes/2026-09-10-ENG-01-reproducible-toolchain.md)。 diff --git a/refactor/release-reviews.md b/refactor/release-reviews.md index c8b30027c..5f3e849c7 100644 --- a/refactor/release-reviews.md +++ b/refactor/release-reviews.md @@ -10,11 +10,14 @@ | --- | --- | --- | | API/类型/产物自动测试 | 旧调用、返回值、事件语义、声明、入口及新旧核心/插件组合 | 对固定旧 tarball 和候选 tarball 使用相同用例；不以编译成功代替运行验证 | | 用户连接的 @Chrome | 本地 demo 的实际点击、拖动、键盘、播放、切源、字幕、控件、销毁重建及故障排查 | 记录 Chrome/系统版本、操作步骤、状态断言、错误和截图；一次交互验收不能代替持续回归 | +| Codex 内置浏览器 | Chrome 不可用时接续其支持的真实页面/API/媒体/交互验证 | 用户已明确授权自动回退；记录实际浏览器、版本、操作和限制，不将结果标成外部 Chrome 或真实设备通过 | | 仓库浏览器自动化 | 将稳定回归用例保存为测试，运行 Chromium/Firefox/WebKit 及所需正式 Chrome 组合 | 固定样本、环境和版本，CI 保存报告及失败证据；Playwright 的 WebKit 不等于真实 Safari | | 设备和外部资源 | iPhone/iPad Safari、Cast 接收端、相关 PiP/codec/SDK/广告/模型路径 | 按 BASE-08 的支持矩阵验证；模拟尺寸、mock 和其他浏览器的通过不能代替真机结论 | @Chrome 用于本地演示和候选产物验收，稳定场景同步沉淀为仓库测试。发布验收应加载与待发布内容一致的候选包；仅测试 docs/uncompiled 的源码开发构建不足以批准发布。 +2026-09-10 用户补充：Chrome 不可用时使用内置浏览器。无需等待扩展恢复即可继续它支持的验证；若特定能力不支持，再将该能力登记为未验证并继续其他任务。内置浏览器已实际打开固定发布包的 api.html，9 项基础 API 检查通过，页面 errors 为空；播放推进、切源、设备/SDK 及完整 API 基线仍分别验收。 + 播放验证至少检查媒体时间确实推进、暂停后停止、seek 到达预期位置、切源后旧异步结果不覆盖新状态、事件次数/顺序符合契约、插件 UI 与实际轨道一致、销毁后资源被回收。不能只凭页面加载、截图或播放按钮变化判断成功。事件比较允许有依据的浏览器差异，遵循 testing.md 的语义断言规范。 环境事实：2026-09-10 已通过浏览器工具清单确认 Chrome 扩展连接可用；当时未运行播放器用例、未确认 Chrome 版本，也未核实真机或接收设备可用性。此事实会过期，每次验收重新检查，不填写为测试通过。 diff --git a/refactor/tasks.json b/refactor/tasks.json index 6fc6f0621..9c952b674 100644 --- a/refactor/tasks.json +++ b/refactor/tasks.json @@ -219,6 +219,24 @@ "changes/2026-09-10-DOC-12-execution-readiness-review.md" ] }, + { + "id": "DOC-13", + "phase": "0 规划", + "title": "记录并验证内置浏览器回退规则", + "scope": [ + "workspace" + ], + "dependsOn": [ + "DOC-08" + ], + "status": "done", + "risk": "L", + "deliverable": "根指令、复盘和夹具文档中的浏览器回退及实际环境证据", + "acceptance": "内置浏览器打开真实页面，报告基础检查结果及未覆盖项；独立提交", + "evidence": [ + "changes/2026-09-10-DOC-13-browser-fallback.md" + ] + }, { "id": "BASE-01", "phase": "1 基线", @@ -267,12 +285,11 @@ "BASE-01", "BASE-HARNESS-01" ], - "status": "blocked", + "status": "todo", "risk": "H", "deliverable": "核心与试点的构造/默认值/静态和实例 API 快照，其余包由 01/02 步补齐；登记契约/版本/固定测试 ID/命令/报告与负责任务", "acceptance": "真实发布包反射与旧用户调用可重跑，未验证项明确", - "evidence": [], - "reason": "Chrome 工具连接连续失败，重置后仍不可用；用户要求先继续其他任务。恢复连接后执行 api.html 并核对报告，HTTP 服务通过不代表浏览器通过。" + "evidence": [] }, { "id": "BASE-03",