文档：集成本地构建发布契约

2026-08-12 21:27:51 +08:00
parent 5b44864265
commit 6e822ccf7c
14 changed files with 156 additions and 36 deletions
--- a/.project-docs/30-worklog/current-state.md
+++ b/.project-docs/30-worklog/current-state.md
@@ -11,10 +11,11 @@ This file is the integrated default-branch snapshot. Feature tasks record progre
 - `4df0477` / `8dd99c1`：客户端静态发布唯一链路、旧 Compose 协调链退役及安全边界补强。
 - `4980894` / `03dae62`：AI 绘画 Enter 发送及同一 Workspace 下的多 Conversation 客户端模型。
 - `926056a`：Makelore 内置 Electron WebContents/CDP 发布前本地预览检查。
+- `5b44864`：Main-owned 本地 npm/Vite 构建、同字节 Electron 双视口预检、source+built 双归档与 artifact contract 上传。

 ## Current Focus

-客户端面向非专业用户提供“创建小游戏或小程序 → 在内置浏览器打开本地预览 → 项目配置中一键提交 → Main 安全打包上传 → 轮询云端构建 → 运营审核”的唯一创建者链路。提交前由 Main 复用当前项目受信 loopback preview，并以 Electron 自带 Chromium WebContents/CDP 检查桌面/移动视口、运行错误、白屏和外域访问；不使用 Playwright，也不在该检查中执行项目 Vite。该检查是可由客户端调用路径绕过的 UX fail-fast，不产生 receipt 或 project/digest provenance，也不模拟生产 opaque-origin，因此不属于可信发布门禁。自定义和缺少类型字段的旧项目不提供该入口。已发布作品优先使用安全投影后的 `play_url`，`runtime_url` 仅保留一个客户端版本的兼容回退。
+客户端面向非专业用户提供“创建小游戏或小程序 → 项目配置中一键提交 → Main 本地 npm/Vite 构建 → Electron 双视口预检最终产物 → 上传 source+built 双归档与 contract → 运营审核”的唯一创建者链路。Main 对安全源码快照运行安装包内固定 npm 11.6.2 的 `npm ci --ignore-scripts`，再显式调用项目 `package-lock.json` 锁定的 Vite；Vite config/plugins 以当前桌面用户权限执行，因此只适用于用户信任的本地项目，不是 sandbox。预检由 Main 以临时 loopback origin 和 Electron WebContents/CDP 检查与最终 `built_archive` 相同的内存文件字节，覆盖桌面/移动视口、运行错误、白屏和外域访问；不使用 Playwright。该检查仍可由非官方客户端绕过，不产生可信 receipt，也不复刻生产 opaque-origin。服务端不再替客户端运行项目 Vite，而是把源码、构建归档和 contract 视为不可信输入，逐字节重算与校验并固化不可变 Release；人工审核仍不可绕过。自定义和缺少类型字段的旧项目不提供该入口。已发布作品优先使用安全投影后的 `play_url`，`runtime_url` 仅保留一个客户端版本的兼容回退。

 AI 绘画的一个 Workspace 可包含多条 Conversation。消息、Brief、Quote 和 `turnRevision` 随 Conversation 隔离；生成任务和资产保持 Workspace 级共享。每条 Conversation 使用服务端持久 Agent Gateway Session，切换会话只重连对应事件流。

@@ -26,21 +27,22 @@ AI 绘画的一个 Workspace 可包含多条 Conversation。消息、Brief、Quo
 - 2026-08-10：删除客户端旧 Compose deploy-check、watcher/arm/upload 协调和手工 ZIP 路由；submission binding v2 保留旧 `submitted` 绑定并把旧中间态归一为 `legacy_retired`，同时补齐 Renderer capability、`play_url` 安全投影和本机绑定失败告警。
 - 2026-08-11：AI 绘画支持在同一设计项目内创建和切换多条独立 Conversation；保留项目级任务/资产，并使用 Workspace + Conversation 身份保护异步与流式更新。退出时关闭本地流并清除本地 Session-id 缓存，不删除服务端持久 Conversation Session。
 - 2026-08-12：一键提交前复用当前项目的内置浏览器 loopback preview，以 fresh 临时 Electron WebContents/CDP 执行桌面/移动 UX 预检；服务端仍执行唯一受控构建、不可变 Release 安全门禁和人工审核。
+- 2026-08-12：发布架构反转为 Main-owned 本地构建；固定 npm 11.6.2 按项目 lockfile 安装并执行项目 Vite，Electron 预检最终上传同字节产物，再上传 source+built 双归档和严格 contract。服务端仅校验并固化不可信字节，不再承担项目 Vite 构建。

 ## In Progress

- 成组集成服务端 Builder、OSS immutable Release、CDN/Edge 与 App 消费链后，使用真实账号和生产配置执行客户端提交到作品播放的整链验收。
+- 成组集成服务端 source+built+contract 校验、OSS immutable Release、CDN/Edge 与 App 消费链后，使用真实账号和生产配置执行客户端提交到作品播放的整链验收。

 ## Next Recommended Steps

-1. 成组核对服务端 Builder → OSS immutable Release → CDN/Edge 的发布契约与客户端 `play_url` 消费契约。
-2. 配置真实生产环境，分别执行“小游戏/小程序创建 → 客户端本地预览检查 → 提交 → 服务端受控构建与安全门禁 → 运营批准 → App 播放”。
+1. 成组核对客户端 source+built+contract 上传 → 服务端逐字节校验 → OSS immutable Release → CDN/Edge 的发布契约与客户端 `play_url` 消费契约。
+2. 配置真实生产环境，分别执行“小游戏/小程序创建 → 客户端本地构建与同字节预检 → 提交 → 服务端合同/摘要校验与不可变 Release 固化 → 运营批准 → App 播放”。
 3. 核对待审 Owner preview 到期刷新、CDN 发布/撤回、生产监控和告警证据。
 4. 在一个客户端兼容版本且服务端与存量数据稳定提供 `play_url` 后，删除 `runtime_url` 回退。

 ## Open Questions / Blockers

- 客户端与模拟上游回归已完成；真实 Builder、OSS/CDN、运营审核、App 播放、生产账号和环境变量仍待部署环境确认，不能据此宣称生产发布链已经验收。
+- 客户端与模拟上游回归已完成；真实服务端新协议、OSS/CDN、运营审核、App 播放、生产账号和环境变量仍待部署环境确认，不能据此宣称生产发布链已经验收。当前已验证的 Windows 安装器未上传或发布。

 ## Risky Areas

@@ -50,9 +52,11 @@ AI 绘画的一个 Workspace 可包含多条 Conversation。消息、Brief、Quo
 - `works-cloud-deploy.json` 仅是已安装数据的兼容文件名，不代表客户端仍拥有自动部署协调器；旧中间态不得恢复为后台任务。
 - 刷新凭据、发布 Token、ZIP、幂等键和重试只能由 Electron Main 持有。
 - 本地 `projectType` 只决定产品分流和模板选择，不得作为授权依据或替代 Main/服务端的包体校验。
+- 本地构建必须使用安装版 Electron Node、固定 npm 11.6.2 和项目 `package-lock.json` 锁定的 Vite，不得回退到全局 PATH、已有 `node_modules` 或未验证的 npm 闭包；依赖安装需要网络。
+- 项目 Vite config/plugins 以桌面用户权限执行，不能称为 sandbox；此风险边界必须在发布说明中保留。
 - AI 绘画消息、Brief、Quote 和 `turnRevision` 必须按 Workspace + Conversation 隔离；任务事件仍按 Workspace 归并，迟到的异步结果不得污染已切换的会话。
 - 服务端持久 Conversation Session 不由客户端在注销或退出时删除；Main 只关闭本地流、清除本机缓存并撤销本地凭据。
- 客户端 loopback preview 检查没有 receipt、project/digest provenance 或生产 opaque-origin parity；只有服务端受控构建、不可变 Release 校验和人工审核构成不可绕过的发布门禁。如未来需要不可绕过的 runtime gate，必须引入可信 verifier 并绑定精确构建产物。
+- 客户端对最终构建字节的 loopback 检查没有可信 receipt，且不复刻生产 opaque-origin；服务端必须独立重算 source/built/contract、校验不可变 Release，人工审核仍不可绕过。如未来需要不可绕过的 runtime gate，必须引入可信 verifier 并绑定精确构建产物。

 ## Last Updated

--- a/.project-docs/30-worklog/task-history.md
+++ b/.project-docs/30-worklog/task-history.md
@@ -10,6 +10,7 @@
 | 2026-08-09 | 客户端项目类型 | 创建时固定小游戏/小程序/自定义类型；前两类生成受控发布模板 | current-state、architecture、domain |
 | 2026-08-10 | 客户端静态发布链路收敛 | 唯一一键静态提交、旧 Compose 协调链退役、submission binding v2 与 `play_url` 安全边界 | current-state、architecture、domain、evidence、commitments |
 | 2026-08-12 | Makelore 内置浏览器发布前预检 | Electron WebContents/CDP loopback UX fail-fast；服务端受控构建与审核仍为唯一可信门禁 | current-state、architecture、domain、evidence、commitments |
+| 2026-08-12 | Makelore 本地构建静态 Release | 固定 npm + 项目 lockfile Vite、本地同字节双视口预检、source+built+contract 双归档协议 | current-state、architecture、domain、evidence、commitments、skills |

 ## Notes

--- a/.project-docs/30-worklog/tasks/20260812-integrate-client-built-release-makelore-72ce.md
+++ b/.project-docs/30-worklog/tasks/20260812-integrate-client-built-release-makelore-72ce.md
@@ -0,0 +1,98 @@
+# Task: 集成 Makelore 本地构建发布事实
+
+## Identity
+
+- Task ID: 20260812-integrate-client-built-release-makelore-72ce
+- Mode: Integration
+- Branch: codex/20260812-integrate-client-built-release-makelore-72ce-integrate-client-built-release
+- Worktree: D:\Datas\OthersProjects\makelore-integrate-client-built-release-72ce
+- Base commit: 5b44864265eb8a85484e38e49f5e177d108328a3
+- Owner: codex
+- Status: Completed
+
+## Scope
+
+- 从源任务 `20260812-client-built-release-makelore-7e5b` 晋升 Main-owned 本地 npm/Vite 构建、同字节 Electron 双视口预检、双归档上传和服务端固化边界。
+- 更新 canonical current state、architecture、domain、evidence、commitments、history、success criteria，以及仍在使用的 `.opencode` 发布课程说明。
+- 只修改 canonical 文档、现行发布 skill 和本 integration task record；不修改生产代码、source task 或其他历史 task record。
+
+## Intent And Constraints
+
+- 用户已明确批准架构反转：客户端用安装版 Electron Node、固定 npm 11.6.2 和项目 lockfile Vite 本地构建；服务端不再运行项目 Vite，只校验并固化不可信字节。
+- Vite config/plugins 以桌面用户权限执行，不是 sandbox；仅适用于用户信任的本地项目，依赖安装需要网络。
+- Electron 预检检查与最终 `built_archive` 相同的内存字节，但无可信 receipt、不复刻生产 opaque-origin，不得替代服务端摘要/合同/不可变 Release 校验或人工审核。
+- 旧客户端与旧 sandbox/browser 任务提示升级后重新构建提交；新版 `BUILD_STALE`、归档存储和 ReleaseStore 瞬时失败由运营在“构建异常”中重试。
+- 当前 Windows 安装器证据固定为 223,547,912 bytes、SHA-256 `08A0BB7BC66EE4AD8B120E8955B149951CD86AF53CC966C7973AD4D77A5815C1`；仅记录为已验证但未上传、未发布。
+
+## Project Context Loaded
+
+Task context:
+- Task ID: `20260812-integrate-client-built-release-makelore-72ce`
+- Mode: Integration
+- Branch: `codex/20260812-integrate-client-built-release-makelore-72ce-integrate-client-built-release`
+- Worktree: `D:\Datas\OthersProjects\makelore-integrate-client-built-release-72ce`
+- Base commit: `5b44864265eb8a85484e38e49f5e177d108328a3`
+- Other active local tasks: release-client、login-sliding、browser-preflight、static-release-only、cloud-build diagnosis、source client-built-release、design multisession、design enter-send、Windows package。
+- Overlap or semantic-conflict assessment: browser-preflight canonical 曾明确禁止客户端执行 Vite，与本任务相反；用户已明确批准架构反转，因此冲突已获人类决策。其余 peers 不改变本次计划；Windows package 只提供旧安装产物背景，不覆盖本次最终产物证据。
+
+Read:
+- `.project-docs/05-agent-entry/read-before-planning.md`
+- `.project-docs/05-agent-entry/memory-index.md`
+- `.project-docs/30-worklog/current-state.md`
+- `.project-docs/00-brief/project-positioning.md`
+- `.project-docs/00-brief/success-criteria.md`
+- `.project-docs/10-decisions/decision-index.md`
+- `.project-docs/20-architecture/system-overview.md`
+- `.project-docs/20-architecture/module-map.md`
+- `.project-docs/20-architecture/data-flow.md`
+- `.project-docs/40-domain/business-rules.md`
+- `.project-docs/40-domain/glossary.md`
+- `.project-docs/50-evidence/evidence-index.md`
+- `.project-docs/60-reflection/reflection-index.md`
+- `.project-docs/80-commitments/commitments.md`
+- `.project-docs/90-maintenance/stale-items.md`
+- source task record and every active peer task record through its registry-owned worktree
+
+Relevant understanding:
+- Project goal: 为非专业用户提供一个 Main-owned、安全投影且无需 Docker/ZIP/服务器操作的一键静态发布链。
+- Current integrated focus: 旧 snapshot 仍以开发 loopback preview + 服务端构建为主，本任务明确替换该边界。
+- Active task scope: 只晋升源提交 `5b44864` 已验证的长期事实，不改生产代码。
+- Active constraints: Renderer 不得持有凭据、路径、归档或 origin；客户端结果不成为服务端信任声明。
+- Decisions affecting this task: 用户已确认本地构建架构反转；ADR-001 与发布链无冲突。
+- Evidence, reflections, or commitments affecting this task: source task 129 focused tests、真实 Electron E2E、npm/Vite smoke、packaged verifier；生产整链仍未验收。
+- Files or modules likely involved: canonical `.project-docs`、`.opencode/skills/youth-ai-product-course/SKILL.md`、`.opencode/skills/dev-build-test/SKILL.md`。
+- Unknowns, stale docs, or conflicts: 服务端新协议、OSS/CDN、运营/App 生产整链未验证；项目 positioning 仍是旧模板占位，但不影响本次局部晋升。
+
+Gate result:
+- Passed.
+
+## Plan
+
+1. 以源 task outcome/promotion candidates 和 `5b44864` 生产差异为证据，替换旧本地预检/云端构建 canonical 描述。
+2. 同步发布运行时、双归档合同、错误重试、安装器证据和生产整链 commitment。
+3. 运行 project-docs、drift、diff 和聚焦语义扫描，提交中文 integration commit，完成 task context；保留 worktree ownership。
+
+## Outcome
+
+- 已将发布 canonical 链路更新为 Main-owned local npm/Vite build → final built snapshot Electron 双视口预检 → source+built+artifact contract 上传 → 服务端逐字节校验与不可变 Release 固化。
+- 已明确固定 npm 11.6.2、项目 lockfile Vite、桌面权限执行 config/plugins（非 sandbox）、无全局 PATH/既有 `node_modules` 回退和依赖网络要求。
+- 已保留客户端预检可绕过、无可信 receipt、不复刻 opaque-origin，以及 Renderer 不接触路径/归档/origin/凭据的安全边界。
+- 已固化旧客户端/旧 sandbox-browser 任务重提、新版瞬时固化失败由运营重试，并登记最终 Windows 安装器大小/SHA 和“未上传、未发布”事实。
+- 已同步两份仍在使用的 `.opencode` 发布课程 skill；未修改生产代码、source task 或任何 peer/historical task record。
+
+## Verification
+
+- `check_project_docs.py`: PASS。
+- `check_doc_drift.py --task-id 20260812-integrate-client-built-release-makelore-72ce`: PASS，写入边界仅包含 canonical project docs 与本 integration task record。
+- `git diff --check`: PASS（仅 Git LF/CRLF 工作区提示）。
+- 聚焦语义扫描核对固定 npm、Vite、双归档、`preflightStaticArtifact`、`BUILD_STALE` 和旧 sandbox/browser 协议表述；canonical 现行描述已与 `5b44864` 源实现/任务证据一致。
+- source tip `5b44864265eb8a85484e38e49f5e177d108328a3` 已存在且正是 integration base；`Integrated Through` 已登记 `5b44864`。
+
+## Follow-ups
+
+- 服务端新协议、不可变 Release、运营审核、CDN/App 播放仍需真实生产整链验收。
+- 每次正式 Windows 安装器发布前继续运行 publish runtime 与 artifact verifier。
+
+## Promotion Candidates
+
+- None. Accepted source facts are being promoted by this Integration Gate.