75 lines
7.3 KiB
Markdown
75 lines
7.3 KiB
Markdown
# Task: 在 Makelore 构建并上传静态 Release
|
||
|
||
## Identity
|
||
|
||
- Task ID: 20260812-client-built-release-makelore-7e5b
|
||
- Mode: Feature
|
||
- Branch: codex/20260812-client-built-release-makelore-7e5b-client-built-release
|
||
- Worktree: D:\Datas\OthersProjects\makelore-client-built-release-7e5b
|
||
- Base commit: 3a80625fe2fb74ab4e0a883188a52eade8cd23b9
|
||
- Owner: codex
|
||
- Status: Completed
|
||
|
||
## Scope
|
||
|
||
- 在 Electron Main 内为可发布小游戏/小程序执行一次受控本地 Vite 构建，并把临时 `dist` 作为新版本协议的一部分上传。
|
||
- 让内置 Electron 浏览器预检绑定到本次 Main-owned 构建产物，而不是任意已打开的开发预览 URL。
|
||
- 保持 Renderer capability、凭据、临时路径、归档和上传都由 Main 持有；Renderer 只获得稳定状态和可操作提示。
|
||
- 更新发布状态轮询和旧服务端/旧客户端协议错误提示；不恢复 watcher、手工 ZIP、Compose 或云部署协调器。
|
||
- 不直接修改 canonical `.project-docs`；通过任务记录提出 Promotion Candidates。
|
||
|
||
## Intent And Constraints
|
||
|
||
- 用户明确要求本地构建以移除服务端 Docker 构建成本；浏览器能力复用 Electron 内置 Chromium，不新增 Playwright/Chromium 下载。
|
||
- 必须使用安装版可控、可验证的 Electron Node 与固定 npm 11.6.2；Vite 必须来自本次 `npm ci` 按项目 `package-lock.json` 安装的精确版本，不得依赖开发机全局 PATH 或预存 `node_modules`。协议 v1 不强制所有项目使用同一个 Vite 版本。
|
||
- 构建与临时 HTTP origin 均由 Main 创建和销毁，Renderer 不得提供任意本地路径、归档或预检 URL。
|
||
- 客户端构建/预检可被非官方客户端绕过，不上传可信 receipt；服务端仍将产物视为不可信字节并独立重算。
|
||
- 旧客户端缺新协议时由服务端明确拒绝；本客户端应把该错误映射为升级/重新提交，而不是云端沙箱故障。
|
||
|
||
## Project Context Loaded
|
||
|
||
- Task identity / ownership: branch、worktree、base 与 registry 匹配，Feature ownership 已建立。
|
||
- Integrated snapshot: 当前唯一发布链为 Main 打包源代码上传；`preflightCurrentProject` 只检查已附着 loopback 开发预览，不构建或证明上传产物。
|
||
- Relevant decisions: 当前客户端 canonical 明确禁止本地执行 Vite；本任务由用户确认后显式替换该边界，但仍不把客户端结果提升为安全信任结论。
|
||
- Peer overlap: browser preflight、static-release-only、cloud-build diagnosis 均已集成或为历史；Windows 打包任务只生成安装包，与本任务不共享生产代码写入。
|
||
- Planning Gate: Passed.
|
||
|
||
## Plan
|
||
|
||
1. 核对安装包中的 Node/npm/Vite 能力并定义 Main-owned client build 模块。
|
||
2. 让真实临时 `dist` 通过内置 Electron 双视口预检，确保 origin、网络和 cleanup fail closed。
|
||
3. 扩展 source package/upload 合同携带预构建产物与摘要，更新 Renderer 状态/错误投影。
|
||
4. 增加单元与真实 Electron E2E，验证无 Playwright、无任意路径/URL、无临时文件泄漏。
|
||
5. 完成任务记录、Promotion Candidates、文档门禁、独立终审和 feature commit。
|
||
|
||
## Outcome
|
||
|
||
- 新增 Main-owned release builder：对安全快照运行固定 npm 11.6.2 `ci --ignore-scripts` 和显式项目 Vite CLI，限制环境、时间、输出与进程树，并生成确定性 source/built ZIP 与严格 v1 contract。
|
||
- 内置 Electron 通过 Main-only `preflightStaticArtifact(...)` 验证与最终上传 ZIP 共用的内存文件快照；临时 loopback origin、非持久 partition、外域阻断和清理均由 Main 持有，不再要求用户预先打开开发预览。
|
||
- 发布请求改为上传 `archive`、`built_archive`、`artifact_contract`；Renderer 只传项目元数据且永不接触路径、归档、origin、Host token 或 Works 凭据。
|
||
- 发布 UI 已把旧 sandbox/browser 错误标为历史协议，提示升级客户端后重新构建提交；新本地构建、产物预检和服务端字节拒绝均使用固定中文操作提示。
|
||
- 新协议的 `BUILD_STALE`、归档存储和 ReleaseStore 瞬时失败不再伪装成旧任务；提示运营在“构建异常”中重新处理，旧 sandbox/browser 任务仍要求新版重提。
|
||
- electron-builder 从固定 npm 11.6.2 发布包自动生成有界且完整的运行时闭包；packaged verifier 会从真实 `resources/publish-runtime` 定位并用安装版 Electron Node 执行 `npm --version`。
|
||
|
||
## Verification
|
||
|
||
- 最终相关 Vitest：6 files / 129 passed。
|
||
- `pnpm typecheck`、scoped ESLint、`pnpm verify:publish-runtime`（npm 11.6.2）、`pnpm build:vite` 通过。
|
||
- 真实 Electron production seam E2E：1 passed，覆盖 Main-owned dist、双视口、外域请求发送前阻断和临时 WebContents 清理。
|
||
- 一次性真实构建 smoke（测试文件随后删除）：Electron 40 Node + 固定 npm 11.6.2 实际执行 `npm ci` 与项目 Vite 7.3.1，约 11.77 秒通过，并验证 dispose 后临时 dist 不可访问。
|
||
- 全量 Vitest：1532 passed / 3 failed；三项在未修改主分支可复现（缺失 `.opencode/agent` 测试目录、两个 OpenCode 并发/超时用例），不属于本次改动。
|
||
- `git diff --check` 通过。
|
||
- 最终工作树的 Windows 安装产物已实际重建并通过 `pnpm verify:artifact:win -- --allow-dirty`：packaged Electron 40.10.6 / Node 24.15.0 可执行固定 npm 11.6.2；安装器 223,547,912 bytes，SHA-256 `08A0BB7BC66EE4AD8B120E8955B149951CD86AF53CC966C7973AD4D77A5815C1`。
|
||
|
||
## Follow-ups
|
||
|
||
- 发布流水线必须继续对每个 Windows 安装产物运行 `pnpm verify:artifact:win`；本任务已验证当前本地构建产物，但没有上传或发布该安装器。
|
||
- 本地 npm/Vite 构建会以桌面用户权限执行项目 Vite config/plugins；这是用户项目代码受信任的客户端边界，不是 sandbox，也不能成为服务端授权或审核 receipt。
|
||
- Electron 预检是可绕过的 UX fail-fast，且不复刻生产 opaque-origin CSP；若需不可绕过 runtime 验收，应由未来独立可信 verifier 检查 immutable Release。
|
||
|
||
## Promotion Candidates
|
||
|
||
- Target: Makelore current-state/architecture/domain rules。Proposal: 发布链改为 Main-owned local npm/Vite build → exact dist Electron UX preflight → source+built+contract upload；删除“客户端不得执行 Vite”和“必须已有开发预览”的现行描述。Evidence: 124 focused tests、真实 Electron E2E、实际 npm/Vite smoke。Future impact: 安装包包含固定 npm，提交依赖锁文件与本地网络。Semantic conflict: 显式反转旧客户端边界；用户已确认，无需再次确认。
|
||
- Target: success criteria/API integration/skills。Proposal: 明确预检可绕过且无可信 receipt，服务端仍逐字节验证并要求人工审核；旧客户端必须升级重提。Evidence: route/API contract 与错误投影测试。Future impact: 后续客户端不得把 preflight 结果当平台证明。Semantic conflict: 无。
|
||
- Target: evidence/commitments。Proposal: 记录 packaged verifier 已证明安装产物中的固定 npm 11.6.2 完整闭包可由 Electron Node 执行，并保留客户端 Vite config 执行权限边界。Evidence: 安装器 SHA-256 与 `verify:artifact:win` 输出。Future impact: Windows 发布前保留硬门禁。Semantic conflict: 无，不宣称该本地产物已上传或发布。
|