78 lines
6.8 KiB
Markdown
78 lines
6.8 KiB
Markdown
# 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: be9bc84474cd23aa3861c0cb059082785e72abf2
|
||
- 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`, feature，branch/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.md`、`module-map.md`、`data-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 统一提升。
|