Files
makelore/.project-docs/30-worklog/tasks/20260812-client-browser-preflight-c8e2.md

6.8 KiB
Raw Blame History

Task: 将静态作品浏览器预检移入 Makelore

Identity

  • Task ID: 20260812-client-browser-preflight-c8e2
  • Mode: Feature
  • Branch: codex/20260812-client-browser-preflight-c8e2-browser-preflight
  • Worktree: D:\Datas\OthersProjects\makelore-browser-preflight-c8e2
  • Base commit: be9bc84474
  • Owner: codex
  • Status: Completed

Scope

  • 在唯一发布链路 ProjectPublishAction -> publishWorksProjectSource -> createStaticProjectPackage 上传前,检查当前项目已在内置浏览器运行的本地预览。
  • 复用 Main-owned AgentBrowserModule / ElectronAgentBrowserAdapter 和 Electron 自带 Chromium对同一受信回环 URL 执行桌面与移动视口预检。
  • 捕获主文档加载失败、页面异常、console/log error、失败资源、跨源请求/跳转和白屏;使用单一全局 deadline并总是销毁临时视图、清空临时 partition。
  • Renderer 仅接收固定错误码与中文操作提示,不接收本地路径、构建输出或浏览器事件细节。
  • 更新聚焦单元测试、Electron E2E、README 和本任务记录;不修改 canonical .project-docs

Intent And Constraints

  • 不新增 Playwright、Chromium 或其他浏览器下载依赖;不创建平行 BrowserWindow 能力。
  • 预检使用非持久临时 partition 和不挂载 UI 的 WebContentsView不污染用户浏览器标签、历史、cookie、localStorage 或登录态。
  • 不运行项目自定义脚本、不执行 Vite 配置、不在线安装依赖;没有受信本地预览时安全失败并提示先在内置浏览器打开预览。
  • 客户端预检仅改善提交前反馈,不写入上传字段、不构成信任声明;服务端继续独立构建、包体校验和发布门禁。
  • 仅在隔离 feature worktree 修改本任务拥有的客户端生产、测试、README 和任务记录文件。

Project Context Loaded

  • Task identity / ownership: 20260812-client-browser-preflight-c8e2, featurebranch/worktree/base 均与 task registry 一致。
  • Integrated snapshot: 发布唯一链路、Renderer/Main 安全边界和服务端独立验收已集成至 be9bc844
  • Relevant architecture: electron/agent-browser 已提供 sandboxed WebContentsView、CDP、权限拒绝与 partition 清理;electron/api/routes/works.ts 在 Main 内完成打包上传。
  • Peer overlap: 其他本地任务均在独立 worktree 且 ready_for_integration与本任务生产文件无并发写入重叠。
  • Planning Gate: Passed.

Plan

  1. 用失败测试固定内置浏览器临时 partition、双视口、错误捕获与 cleanup 契约。
  2. 增加基于当前项目 loopback URL 的临时双视口 probe并在上传前接入 Works 发布路由。
  3. 增加安全错误投影和 Renderer 文案,确认响应不暴露路径或底层日志。
  4. 更新 README执行 typecheck、聚焦单测、构建和 Electron E2E。
  5. 完成任务文档门禁并提交中文 feature commit。

Outcome

  • AgentBrowserModule 内新增 local_preview_preflight seam只接受当前项目已 attached 的显式端口 HTTP loopback URL不接受远程地址、HTTPS、userinfo、无端口或其他项目。
  • 每个桌面/移动视口创建一个 fresh 非持久 partition、未挂载的 sandboxed WebContentsView;先 prime about:blank,再用 CDP 设置设备指标并加载同一预览源。
  • 预检捕获主文档加载失败、renderer fault、Runtime exception/error Console、Log error、HTTP >=400、非预览源 HTTP(S) 请求、非取消资源失败、跨源顶层跳转和白屏/零尺寸画布;使用单一 30 秒 deadline。
  • cleanup 覆盖视图创建后的全部 setup/listener无论成功失败都移除监听、detach、destroy并以 1 秒上限 best-effort 清理临时 partition。用户持久浏览器 record/profile/历史/登录态不变。
  • Works 一键提交在安全打包和网络请求前调用预检;没有活动预览时返回固定 PREVIEW_REQUIRED。Renderer 只显示 allowlist 错误码和中文操作提示,不接收 URL、路径、事件或页面内容。
  • 未增加任何浏览器/Playwright 下载依赖,未执行项目构建或安装依赖,未生成或上传预检 receipt服务端继续独立构建和校验。
  • README 与提交状态文案已改为“本地预览检查 -> 上传 -> 云端受控构建与平台校验”。

Verification

  • pnpm exec vitest run tests/unit/agent-browser-electron-adapter.test.ts tests/unit/agent-browser-core.test.ts tests/unit/works-routes.test.ts tests/unit/works-project-publish.test.ts tests/unit/project-publish-action.test.tsx: 5 files / 121 tests passed。
  • pnpm run typecheck: passed。
  • scoped ESLint本任务全部 TS/TSX: passed。
  • pnpm run build:vite: Renderer、Electron Main、Preload 均构建成功;仅仓库既有 chunk/dynamic-import warning。
  • pnpm exec playwright test tests/e2e/local-preview-preflight.spec.ts --reporter=line: 1 passed真实 Electron 通过生产 AgentBrowserModule.preflightCurrentProject seam 完成桌面/移动双视口,证明临时 probe 的外域请求在发送前被拦截且 WebContents 数量恢复。
  • pnpm exec playwright test --list --reporter=line: E2E 收集成功(新增测试前为 14 files / 22 tests新增 spec 已单独运行)。
  • git diff --check: passed仅 Git LF/CRLF 工作区提示)。

Follow-ups

  • 集成后用真实项目运行本地预览,执行“预览 -> 提交 -> 云端 Builder -> 运营审核 -> App 播放”生产整链验收;客户端预检不替代该验收。
  • 当前预检验证的是用户当前已运行的本地预览 URL而非随后上传源码的确定性构建输出服务端独立重建是必要信任边界。

Promotion Candidates

  • Target: .project-docs/20-architecture/system-overview.mdmodule-map.mddata-flow.md.project-docs/40-domain/business-rules.md
    • Proposal: 一键提交前由 Main 复用当前项目内置浏览器的受信 loopback URL在 fresh 非持久、未挂载 Electron Chromium view 中执行本地预览 UX preflight没有活动预览时 fail closed。客户端不构建、不安装浏览器/依赖、不上传通过声明,服务端仍独立重建与校验。
    • Evidence: 121 项聚焦回归、typecheck、scoped lint、三端 Vite 构建和真实 Electron 生产 preflight seam E2E 通过。
    • Future impact: 后续不得把客户端预检改成桌面权限执行项目 Vite/config/plugin也不得重新把 Playwright/Chromium 下载装入 Builder若要验证上传源码对应输出应在服务端安全沙箱或建立新的受控构建契约。
    • Semantic conflicts: canonical 当前仍称“客户端提交 -> 云构建 -> 浏览器门禁”;需澄清客户端 local preview preflight 与服务端独立构建/平台校验的边界,并删除对服务端 Playwright smoke 的默认依赖描述。
    • Human confirmation required: 是;由 Integration Gate 统一提升。