文档：集成本地构建发布契约
This commit is contained in:
@@ -6,14 +6,17 @@
|
||||
- 新建小游戏和小程序会生成平台固定版本的受控 Vite 发布模板，并可使用项目配置中的单一“提交审核”入口；`custom` 和缺少类型字段的旧项目不提供一键发布。
|
||||
- `ProjectType` 不等于 `BuildPreset`：第一期两个可发布产品类型都映射到内部受控 Vite preset；本地 `projectType` 不是授权边界，Main-owned 安全打包、Host API 和服务端包体校验仍必须执行。
|
||||
- 非专业用户只执行一次“提交审核”；构建通过后由运营审核，审核通过即直接发布。
|
||||
- 创建者发布唯一链路是项目配置“一键提交审核” → 当前 loopback preview 的客户端 UX 预检 → Main 安全打包 → 服务端版本上传 → 客户端轮询云构建；不恢复独立发布上传页、云部署工作台、Compose/deploy-check、自动 watcher/arm/upload 或手工 ZIP 入口。
|
||||
- 提交前预检必须复用 Makelore 当前项目内置浏览器的受信 HTTP loopback preview，以 fresh 非持久 Electron WebContents/CDP 检查桌面/移动视口、运行错误、白屏与外域访问；不得为此调用 Playwright、执行项目 Vite/config/plugin、安装依赖或污染用户浏览器状态。
|
||||
- 客户端预检是可绕过的 UX fail-fast，不写上传字段，不产生 receipt、project/digest provenance，也不声称具备生产 opaque-origin parity。服务端受控构建、包体与不可变 Release 校验、人工审核仍是唯一不可绕过发布门禁；未来若要求 runtime 强门禁，必须由可信 verifier 绑定精确构建产物。
|
||||
- 创建者发布唯一链路是项目配置“一键提交审核” → Main 本地 npm/Vite 构建 → 最终 built snapshot 的客户端 UX 预检 → source+built+artifact contract 上传 → 服务端校验/固化 → 运营审核；不恢复独立发布上传页、云部署工作台、Compose/deploy-check、自动 watcher/arm/upload 或手工 ZIP 入口。
|
||||
- 本地构建必须由 Main 对安全源码快照使用安装版 Electron Node 和固定 npm 11.6.2 执行 `npm ci --ignore-scripts`，再显式调用项目 `package-lock.json` 安装的 Vite；不得依赖全局 PATH、既有 `node_modules` 或 Renderer 提供的任意路径/origin。
|
||||
- 项目 Vite config/plugins 以桌面用户权限执行，因此发布链只适用于用户信任的本地项目；它不是 sandbox。安装依赖需要网络，运行时闭包缺失或版本不符必须 fail closed。
|
||||
- 提交前预检必须由 Main 以一次性 loopback origin 提供最终上传 `built_archive` 的同一内存文件快照，以 fresh 非持久 Electron WebContents/CDP 检查桌面/移动视口、运行错误、白屏与外域访问；不得调用 Playwright 或污染用户浏览器状态。
|
||||
- 客户端预检是可绕过的 UX fail-fast，不上传可信 receipt，也不声称具备生产 opaque-origin parity。服务端把源码、构建归档和 contract 当作不可信字节，独立重算、校验并固化不可变 Release；人工审核仍是不可绕过发布门禁。未来若要求 runtime 强门禁，必须由可信 verifier 绑定精确构建产物。
|
||||
- 待审版本只能通过绑定精确 Release 的短时 Owner preview 验收；旧版本、构建中或失败状态不能生成可扫码假象。
|
||||
- 发布和预览安全边界由 Electron Main 持有，Renderer 不接触账号 Token、ZIP、幂等键和本地绝对路径。
|
||||
- 发布 Host API 必须在读取凭据、查询项目和打包前校验 Renderer capability；仅持有 Host token/base 的非 UI 调用方不得发起发布。
|
||||
- 客户端只持久化服务端已接受的 submission binding v2。旧 `submitted` 绑定必须保留；旧 `armed`、`waiting_for_package`、`waiting_for_login`、`uploading`、`failed` 必须迁移为可理解的 `legacy_retired`，不得恢复后台任务。
|
||||
- 云端上传成功但本机 submission binding 保存失败时，提交仍视为成功；客户端显示固定、无本地路径的告警并继续轮询云构建，避免诱导重复提交。
|
||||
- 云端上传成功但本机 submission binding 保存失败时，提交仍视为成功；客户端显示固定、无本地路径的告警并继续轮询服务端校验与 Release 固化状态，避免诱导重复提交。
|
||||
- 旧客户端缺少 source+built+contract 新协议，或服务端仍存在旧 sandbox/browser 任务时，必须提示升级客户端并重新构建提交；不得把它们伪装为新版瞬时故障。新版合同校验后的 `BUILD_STALE`、归档存储或 ReleaseStore 瞬时失败由运营在“构建异常”中重试。
|
||||
- 已发布作品优先读取 `play_url`，只有字段缺失时才使用一个客户端版本的 `runtime_url` 回退。公共播放 URL 必须是 Works Square 同源 HTTPS、无 userinfo/loopback、精确 `/apps/{encodeURIComponent(app_id)}/`、无 query/fragment，且上游明确 `playable === true` 并提供非空版本名；否则按不可播放处理。
|
||||
- `works-cloud-deploy.json` 仅是已安装客户端的数据兼容文件名，不表示客户端仍提供 cloud deployment coordinator。
|
||||
- Works Square 会话按真实键盘、鼠标或触摸活动滑动续期，连续 7 天未使用才要求重新授权。
|
||||
@@ -24,7 +27,7 @@
|
||||
|
||||
## Open Questions
|
||||
|
||||
- 生产整链需要真实账号、Builder、OSS immutable Release、CDN/Edge、运营审核、App 播放与监控环境完成最终验收；当前客户端验证不能替代该验收。
|
||||
- 生产整链需要真实账号、新上传/校验合同、OSS immutable Release、CDN/Edge、运营审核、App 播放与监控环境完成最终验收；当前客户端验证不能替代该验收。
|
||||
- 是否需要在生产发布链引入绑定精确 Release/digest 的可信 runtime verifier；当前客户端 loopback preflight 不能承担该职责。
|
||||
- 在一个客户端兼容版本且服务端与存量数据稳定提供 `play_url` 后，移除 `runtime_url` 回退。
|
||||
- 多 Conversation 客户端发布前需确认服务端迁移 `0033`、Conversation API 与持久 Session 契约已经部署。
|
||||
|
||||
@@ -5,7 +5,9 @@
|
||||
| `ProjectType` | 创建项目时选择且之后不可变的产品类型 | 当前值为 `mini_game`、`mini_program`、`custom`；缺少字段的旧配置按 `custom` 处理 |
|
||||
| `BuildPreset` | 平台内部用于构建和验收项目包的受控实现 | 不等于 `ProjectType`；第一期小游戏和小程序都使用 Vite preset |
|
||||
| 受控发布模板 | Main 在新建可发布项目时生成的固定依赖、锁文件和可运行示例 | 保障一键提交的结构基线，但本地模板和 `projectType` 本身都不是授权边界 |
|
||||
| Local Preview Preflight | 上传前对当前项目受信 loopback preview 执行的桌面/移动 Electron WebContents/CDP 检查 | 可绕过 UX fail-fast；没有 receipt、project/digest provenance 或生产 opaque-origin parity |
|
||||
| Main-owned Release Build | Electron Main 对安全源码快照执行固定 npm 与项目 lockfile Vite 的本地构建 | Vite config/plugins 以桌面用户权限执行，不是 sandbox；Renderer 不获得路径、归档或 origin |
|
||||
| Artifact Contract | 与 source/built 双归档一并上传的严格版本化清单 | 服务端把三者视为不可信输入并独立逐字节重算、校验 |
|
||||
| Built Artifact Preflight | 上传前对最终 built snapshot 的同一内存字节执行桌面/移动 Electron WebContents/CDP 检查 | 可绕过 UX fail-fast；无可信 receipt，不复刻生产 opaque-origin |
|
||||
| Trusted Runtime Verifier | 未来可将 runtime 检查绑定到精确构建产物/摘要的可信执行方 | 当前未实现；不可用客户端本地预检冒充 |
|
||||
| Submission Binding | 客户端在云端接受上传后保存的精确 app/version/review/hash 绑定 | schema v2 只记录成功提交；落盘文件名暂保留 `works-cloud-deploy.json` 以兼容已安装数据 |
|
||||
| `legacy_retired` | 旧自动部署中间态迁移后的终止状态 | 不恢复 watcher、登录等待或自动上传；提示用户从项目配置重新提交 |
|
||||
|
||||
Reference in New Issue
Block a user