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

This commit is contained in:
2026-08-12 21:27:51 +08:00
parent 5b44864265
commit 6e822ccf7c
14 changed files with 156 additions and 36 deletions

View File

@@ -80,4 +80,4 @@ description: 当 NianCode 开发工程师角色为学习者软件项目设计数
## 交接
交接给市场运营时,提供真实功能事实和限制。准备提交审核时,提供构建/测试状态和实际运行的命令;正式安全打包与云端验收由 Makelore 完成
交接给市场运营时,提供真实功能事实和限制。准备提交审核时,提供构建/测试状态和实际运行的命令;正式提交由 Makelore Main 使用固定 npm 与项目 lockfile Vite 本地构建、预检同字节产物并上传双归档,平台独立校验并固化不可变 Release。客户端预检不是可信审核凭据

View File

@@ -52,7 +52,7 @@ NianCode 是面向 1016 岁学习者的教学工具。目标不只是把代
- 美术设计师:基于原型、可落地的视觉规则,而不是只有风格形容词。
- 开发工程师:改动文件、实现事实,以及尽可能提供测试/检查输出。
- 市场运营:宣传说法要绑定产品事实,缺证据的内容要标注。
- 发布准备:小游戏和小程序保留开发阶段真实 `npm run build`浏览器试玩、移动视口与已知限制证据用户只从项目配置点击一次“提交审核”。Makelore Main 会先用 Electron 内置 WebContents/CDP 检查当前已打开的本地 loopback preview桌面/移动、错误、白屏和外域,不调用 Playwright,预检本身也不在本地执行项目 Vite。这个检查只是可绕过的友好提示,不生成 receipt不证明项目或摘要与云端产物一致,也不模拟生产 opaque-origin。Main 随后安全打包;服务端受控构建、不可变 Release 安全校验和人工审核才是唯一不可绕过的发布门禁。若未来需要不可绕过 runtime gate必须使用绑定精确构建产物的可信 verifier。不得要求学习者准备 Docker、Compose、ZIP 或服务器登录信息。
- 发布准备小游戏和小程序保留开发阶段真实浏览器试玩、移动视口与已知限制证据用户只从项目配置点击一次“提交审核”。Makelore Main 使用安装包内固定 npm 和项目 `package-lock.json` 锁定的 Vite 构建安全快照,再以 Electron 内置 WebContents/CDP 对最终上传的同字节静态产物执行桌面/移动、错误、白屏和外域预检,不调用 Playwright。项目 Vite config/plugins 以桌面用户权限执行,因此只应提交用户信任的本地项目;它不是 sandbox。预检只是可绕过的友好提示,无可信 receipt也不模拟生产 opaque-origin。平台把 source、built 和 contract 当作不可信输入独立重算与校验,固化不可变 Release 后交由人工审核。不得要求学习者准备 Docker、Compose、ZIP 或服务器登录信息。
如果证据缺失,要在本角色负责的项目产物中明确记录缺口、影响和建议补充方式。

View File

@@ -6,12 +6,17 @@
## Task Completion Standard
- {condition that means a task is complete}
- 可发布小游戏/小程序的一键提交必须由 Electron Main 对安全源码快照执行固定 npm 11.6.2 的 `npm ci --ignore-scripts`,并调用项目 `package-lock.json` 锁定的 Vite 生成静态产物。
- Electron 双视口预检必须检查与最终 `built_archive` 相同的内存文件字节;预检失败不得上传,预检成功不得被表述为可信审核凭据。
- 上传协议必须同时携带源码归档、构建归档和严格版本化 artifact contract服务端独立重算摘要、校验合同并固化不可变 Release。
- Renderer 不得获得发布凭据、归档、临时目录、构建 origin 或任意本地路径;旧客户端和旧 sandbox/browser 任务必须提示升级后重新构建提交。
## Quality Checks
- {verification command, review expectation, or acceptance check}
- 发布安装包前运行 `pnpm verify:publish-runtime`,并对最终 Windows 产物运行 `pnpm verify:artifact:win`;固定 npm 闭包缺失或版本不符时 fail closed。
- 至少覆盖 release builder/静态产物服务/发布路由/Renderer 状态的聚焦测试、typecheck、scoped lint、Vite 构建和真实 Electron 双视口 production-seam E2E。
- 真实生产发布仍需成组验证服务端合同、不可变 Release、运营审核、CDN/App 播放;客户端本地验证不能替代该整链验收。
## Last Reviewed
{YYYY-MM-DD}
2026-08-12

View File

@@ -6,11 +6,11 @@
|---|---|---|---|
| 登录续期 | Renderer 活动信号 | Main Works Session | 连续 7 天未使用才清除会话 |
| 项目创建 | 新建项目对话框 | Host API → Main 项目初始化 | 创建时固定 `ProjectType`;小游戏/小程序原子生成受控模板,自定义只生成项目空间 |
| 一键提交 | `ProjectPublishAction` | Renderer capability → Host API → loopback preview preflight → Main packager → Works Square 版本上传 | 只对小游戏/小程序开放;本地预检只做 UX fail-fastMain 随后打包、自动版本、幂等重试和脱敏Renderer 轮询云构建 |
| 本地预览检查 | 当前项目内置浏览器 loopback URL | fresh Electron WebContents/CDP桌面、移动 | 检查错误、白屏和外域;不调用 Playwright/Vite,不产生 receipt/provenance不替代服务端门禁 |
| 一键提交 | `ProjectPublishAction` | Renderer capability → Host API → Main 本地 npm/Vite build → built snapshot preflight → source+built+contract 上传 | 只对小游戏/小程序开放Main 自动版本、幂等重试和脱敏Renderer 轮询服务端校验/固化状态 |
| 构建产物预检 | Main-owned built snapshot | 一次性 loopback origin → fresh Electron WebContents/CDP桌面、移动 | 检查错误、白屏和外域;不调用 Playwright检查与上传归档相同字节,但不产生可信 receipt |
| 提交绑定 | 云端成功上传响应 | Main → submission binding v2 | 只持久化成功的 app/version/review/hash落盘失败返回固定告警但不反转提交 |
| 运营发布 | Works Square 审核与交付 | 公共 `play_url` | 客户端只消费服务端发布结果;真实 Builder → OSS/CDN 生产链仍待整链验收 |
| 可信发布门禁 | 上传源码 | 服务端受控构建 → 包体/不可变 Release 校验 → 人工审核 | 唯一不可绕过权威;若未来增加 runtime 强门禁需可信 verifier 绑定精确构建产物 |
| 运营发布 | Works Square 审核与交付 | 公共 `play_url` | 客户端只消费服务端发布结果;真实合同校验 → OSS/CDN 生产链仍待整链验收 |
| 可信发布门禁 | source+built+artifact contract | 服务端逐字节重算/合同校验 → 不可变 Release 固化 → 人工审核 | 服务端不运行项目 Vite仍是不可绕过权威未来 runtime 强门禁需可信 verifier |
| 真机预览 | 项目空间 | Main → Owner preview / `play_url` | 核对 app、version、release 和同源 HTTPS`runtime_url` 仅一版本兼容回退 |
| 设计会话创建/切换 | AI 绘画页面或侧栏 | Renderer API → Main → Workspace Conversation API | 新会话属于现有 Workspace读取独立消息、Brief、Quote 和 `turnRevision` |
| 设计消息与确认 | 当前 Conversation | Main → 持久 Agent Gateway Session → Conversation 快照 | 请求和流式结果同时绑定 Workspace + Conversation |
@@ -18,10 +18,10 @@
## State Ownership
- Main 持有刷新凭据、发布 Token、临时 ZIP、幂等键和 submission binding v2Renderer 不持有归档路径或自动部署状态。
- Main 持有刷新凭据、发布 Token、固定 npm runtime、源码/构建归档、临时目录、幂等键和 submission binding v2Renderer 不持有归档路径、构建 origin 或自动部署状态。
- 项目内 `.niancode/project.json` 保存 `ProjectType`Main 在配置写入和目录复用时保持其不可变,并在打包时重新读取校验。
- Renderer 仅持有短效公开会话状态、提交展示状态和安全投影后的公共播放/短时预览 URL。
- 本地预检临时 WebContents/partition 只属于一次调用,不写 submission binding 或上传字段;其结果不具备 project/digest provenance,也不覆盖生产 opaque-origin。
- 本地构建临时目录、HTTP origin 和预检 WebContents/partition 只属于一次调用;预检读取与 `built_archive` 相同的内存字节,但结果不写为可信上传 receipt,也不覆盖生产 opaque-origin。
- 旧 schema v1 `submitted` 记录迁移并保留;旧 `armed``waiting_for_package``waiting_for_login``uploading``failed` 归一为 `legacy_retired`,不再启动 watcher 或上传任务。
- AI 绘画 Conversation 持有消息、Brief、Quote、`turnRevision` 和服务端 Session 绑定Workspace 持有 Conversation 列表、生成任务和资产。
- 本地开发适配器将旧单会话 schema v2 原子迁移为带默认 Conversation 的 schema v3打包应用不使用该本地适配器作为云端失败回退。

View File

@@ -7,7 +7,10 @@
| `src/components/works/ProjectPublishAction.tsx` | 可发布项目的一键提交、云构建轮询与用户可理解状态 | 只通过 Renderer API 提交非敏感元数据;绑定告警不终止轮询 |
| `src/lib/works-square.ts` | Renderer 侧 Works Square Host API 契约与安全错误映射 | 不接触 Token、ZIP、本地绝对路径或自动部署状态 |
| `electron/api/routes/works.ts` | Works Host API、Renderer capability 门禁、上游安全投影 | 发布凭据、打包、上传与本地绑定均在 Main 内完成 |
| `electron/agent-browser/module.ts` | 当前项目 loopback preview 的桌面/移动临时 WebContents/CDP 预检 | UX fail-fast不运行 Vite、不生成 receipt、不得升级为可信发布证明 |
| `electron/services/project-release-builder.ts` | Main-owned 安全快照、本地 npm/Vite 构建、source+built 双归档与 v1 contract | 固定 npm 11.6.2;项目 Vite 由 lockfile 决定Vite config/plugins 以桌面用户权限执行 |
| `electron/services/publish-runtime.ts` | 安装包内 npm 闭包定位与 Electron Node 执行 | 不回退全局 npm/PATH缺失或版本不符 fail closed |
| `electron/services/static-release-server.ts` | 用内存 built snapshot 建立一次性 loopback origin | 预检和最终上传归档必须来自相同文件字节;总是清理临时服务 |
| `electron/agent-browser/module.ts` | built artifact 的桌面/移动临时 WebContents/CDP 预检 | UX fail-fast不生成可信 receipt、不得升级为平台证明 |
| `electron/agent-browser/electron-adapter.ts` | Electron WebContents/CDP 设备指标、事件与临时 partition 适配 | probe 不挂载 UI并在结束后销毁视图、清理隔离存储 |
| `electron/services/project-packager.ts` | 受控项目扫描、静态 ZIP 生成和敏感/历史控制文件排除 | 只允许可发布 `ProjectType`,不提供 Compose 或手工 ZIP 路径 |
| `electron/services/works-submission-binding.ts` | submission binding v2 持久化与旧 schema 迁移 | 旧中间态终止为 `legacy_retired`;文件名暂作安装兼容 |
@@ -24,13 +27,14 @@
## Dependency Direction
- Renderer UI → Renderer API contract → Main Host routes → Main services → Works SquareRenderer 不反向读取 Main 凭据、文件系统或归档。
- Project configuration 决定产品分流Main packager 与服务端独立校验决定发布安全本地 `ProjectType` 不是授权结论。
- Local preview preflight 只依赖当前已运行的 loopback 页面并早于打包/网络请求;它不建立源码、摘要、构建产物之间的 provenance服务端仍是受控构建与 Release 安全权威。
- Project configuration 决定产品分流Main release builder 生成 source/built/contract服务端独立重算和校验决定发布安全本地 `ProjectType` 不是授权结论。
- Built artifact preflight 检查最终上传的同字节快照,但客户端可被绕过且不产生可信 receipt服务端仍是合同、摘要和不可变 Release 安全权威。
## Risky Or Sensitive Areas
- `electron/api/routes/works.ts` 同时承担发布 capability、上游安全投影和错误脱敏变更时必须验证未在拒绝前读取凭据或项目文件。
- `electron/agent-browser/module.ts` 的预检必须继续拒绝非 loopback/外域访问、隔离临时 partition 并清理所有 view/listener不能因本地通过而跳过服务端校验。生产 opaque-origin 行为不由该 loopback 检查覆盖
- `project-release-builder.ts` 执行受信本地项目的 Vite config/plugins拥有桌面用户权限必须保持路径、环境、时间、输出、进程树和临时目录限制不得包装为 sandbox
- `electron/agent-browser/module.ts` 的预检必须继续拒绝外域访问、隔离临时 partition 并清理所有 view/listener不能因本地通过而跳过服务端逐字节校验。生产 opaque-origin 行为不由该 loopback 检查覆盖。
- `works-cloud-deploy.json` 是兼容文件名;不得因名称重新引入自动部署协调语义。
- `runtime_url` 是一个客户端版本的迁移回退;删除前必须确认服务端和存量数据稳定提供 `play_url`
- 多 Conversation 事件处理必须区分对话快照与 Workspace 任务更新;不得用任务时间戳推进 Conversation 流水位,也不得让旧会话的迟到流覆盖当前会话。

View File

@@ -11,12 +11,12 @@ Makelore 是 Electron 桌面客户端。Renderer 负责项目操作与状态展
| Renderer | 项目配置、一键提交状态、真机二维码 | 不接触账号 Token、ZIP、幂等键或本地绝对路径 |
| Host API | 校验本地项目请求并投影安全响应 | 发布 mutation 还必须通过 Renderer capabilityHost token/base 不能单独触发发布 |
| Project Configuration & Template | 保存不可变 `ProjectType`,原子生成新项目骨架 | 小游戏/小程序生成受控 Vite 模板;自定义保持最小项目空间 |
| Project Packager | 确定性扫描、敏感文件排除与 ZIP 生成 | 限制文件数、包体和目录替换 |
| Project Release Builder | Main-owned 安全快照、本地 npm/Vite 构建、双归档与 artifact contract | 固定 npm 11.6.2Vite 由项目 lockfile 锁定;产物与预检使用同一内存字节 |
| Works Session | 七天真实活动滑动续期 | 刷新凭据由 Main 安全持有 |
| Submission Binding | 保存云端已接受的精确 app/version/review/hash 绑定 | schema v2 只记录成功提交;旧中间态迁移为 `legacy_retired`,不恢复后台任务 |
| Play URL Projection | 校验服务端公共播放地址 | 只接受同源 HTTPS 和精确 `/apps/{app_id}/`;优先 `play_url``runtime_url` 仅一版本回退 |
| Device Preview | 核对本地绑定、远端版本和 Release | 待审使用短时 Owner preview已发布使用安全投影后的 `play_url` |
| Local Preview Preflight | 在上传前复用当前项目 loopback preview 做桌面/移动 UX fail-fast | Main 使用 Electron WebContents/CDP不使用 Playwright、不执行 Vite、不生成可信证明 |
| Built Artifact Preflight | 在上传前对最终 built snapshot 做桌面/移动 UX fail-fast | Main 使用临时 loopback origin 与 Electron WebContents/CDP不使用 Playwright、不生成可信证明 |
| AI Design Workspace | 保存项目身份、Conversation 列表、生成任务和资产 | 任务和资产在切换 Conversation 后继续可见 |
| AI Design Conversation | 保存消息、Brief、Quote、`turnRevision` 与服务端 Agent Session 绑定 | 同一 Workspace 内互相隔离Session 由服务端持久化 |
| AI Design Event Routing | Main 云端适配器 → Host API/SSE → Renderer store | Conversation 更新按 Workspace + Conversation 路由;任务更新按 Workspace 归并 |
@@ -24,12 +24,13 @@ Makelore 是 Electron 桌面客户端。Renderer 负责项目操作与状态展
## Important Boundaries
- 发布只有现有项目配置底部的一个入口,不新增发布工作台、侧栏或资源卡。
- 创建者发布唯一调用链是 `ProjectPublishAction → publishWorksProjectSource → preflightCurrentProject → createStaticProjectPackage → 版本上传 → 状态轮询`;客户端不再提供 Compose runner、deploy-check、watcher/arm/upload 协调或手工 ZIP 上传入口。
- `preflightCurrentProject` 只检查当前项目已附着的受信 HTTP loopback preview。它用 fresh 非持久、未挂载的 Electron WebContents 和 CDP 检查桌面/移动视口、错误、白屏及外域访问,不安装/调用 Playwright不在本地执行项目 Vite/config/plugin。
- 客户端预检是可绕过的 UX fail-fast没有 receipt、project/digest provenance 或生产 opaque-origin parity不能证明随后上传源码或服务端构建产物安全。服务端受控构建、包体校验、不可变 Release 门禁及人工审核仍是唯一不可绕过权威;未来若要求 runtime 强门禁,需由可信 verifier 绑定精确构建产物
- 创建者发布唯一调用链是 `ProjectPublishAction → publishWorksProjectSource → Main-owned release build → preflightStaticArtifact → source+built+artifact_contract 上传 → 状态轮询`;客户端不再提供 Compose runner、deploy-check、watcher/arm/upload 协调或手工 ZIP 上传入口。
- release builder 对 Main-owned 安全快照运行安装包内固定 npm 11.6.2 的 `ci --ignore-scripts`,并显式调用项目 `package-lock.json` 锁定的 Vite。不得使用全局 PATH、预存 `node_modules` 或 Renderer 提供的路径/origin。项目 Vite config/plugins 以桌面用户权限执行,该边界不是 sandbox
- `preflightStaticArtifact` 以临时 HTTP loopback origin 提供最终 `built_archive` 的同一内存文件快照,并用 fresh 非持久、未挂载的 Electron WebContents/CDP 检查桌面/移动视口、错误、白屏及外域访问;不安装/调用 Playwright
- 客户端预检是可绕过的 UX fail-fast没有可信 receipt也不复刻生产 opaque-origin。服务端不执行项目 Vite而是独立重算和校验 source/built/contract 字节、固化不可变 Release人工审核仍不可绕过。未来若要求 runtime 强门禁,需由可信 verifier 绑定精确构建产物。
- `ProjectType` 由创建请求写入项目配置UI 与 Host API 不提供类型变更;缺少类型的旧配置归一为 `custom`
- 本地 `projectType` 只选择产品路径和内部构建 preset不是可信授权声明Main 仍需安全打包,服务端仍需独立校验清单和包体。
- 云端确认上传成功后,本机 submission binding 失败只能产生固定、无路径的 `binding_warning`不能把请求改判为失败Renderer 仍继续轮询云构建
- 云端确认上传成功后,本机 submission binding 失败只能产生固定、无路径的 `binding_warning`不能把请求改判为失败Renderer 仍继续轮询服务端校验与 Release 固化状态
- 公共播放投影只有在上游 `playable === true`、版本名非空且 URL 通过同源 HTTPS、无 userinfo/loopback、长度、精确路径和无 query/fragment 校验时才可播放;不可信数据 fail closed。
- Renderer 只能获得安全状态字段和可展示的播放/短时预览 URL不得持有发布凭据、归档路径或自动部署状态。
- 落盘文件名 `works-cloud-deploy.json` 仅为已安装客户端的数据兼容;领域模型和代码接口是 submission binding不表示仍存在 cloud deployment coordinator。
@@ -39,7 +40,7 @@ Makelore 是 Electron 桌面客户端。Renderer 负责项目操作与状态展
## Related Decisions
- 当前长期边界记录于 README、ADR-001、集成任务 `20260807-integrate-login-client-a4f8`、源任务 `20260810-static-release-only-a91c` 及本次 Integration Gate后续如改变唯一入口、凭据所有权、Conversation 状态归属或重新引入客户端部署协调器,应新增 ADR。
- 当前长期边界记录于 README、ADR-001、集成任务 `20260807-integrate-login-client-a4f8`、源任务 `20260810-static-release-only-a91c``20260812-client-built-release-makelore-7e5b` 及本次 Integration Gate后续如改变唯一入口、凭据所有权、构建执行边界、Conversation 状态归属或重新引入客户端部署协调器,应新增 ADR。
## Last Updated

View File

@@ -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` 锁定的 ViteVite 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-11AI 绘画支持在同一设计项目内创建和切换多条独立 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 安装并执行项目 ViteElectron 预检最终上传同字节产物,再上传 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

View File

@@ -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

View File

@@ -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.

View File

@@ -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 契约已经部署。

View File

@@ -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 以桌面用户权限执行,不是 sandboxRenderer 不获得路径、归档或 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、登录等待或自动上传提示用户从项目配置重新提交 |

View File

@@ -7,6 +7,7 @@ Use this index for searchable, traceable evidence records.
| 2026-08-11 | AI 设计多会话客户端集成 | 本地功能验证通过;仓库基线仍有既有失败 | `30-worklog/tasks/20260811-merge-all-code-a7c91e.md``4980894``03dae62` | 8 files / 116 focused tests、typecheck、changed-file ESLint、production build 与新增 Electron E2E 通过;生产 migration 0033/API 尚待验收,全量 lint/unit/E2E 的既有失败已单独记录 |
| 2026-08-10 | 客户端静态发布唯一链路 | 本地验证通过 | `30-worklog/tasks/20260810-static-release-only-a91c.md``4df0477``8dd99c1` | 227 项聚焦回归、typecheck、Vite/Electron build、实际 Electron E2E 与 13 files / 21 tests 收集通过;不等同于真实生产部署验收 |
| 2026-08-12 | Makelore 内置浏览器发布前预检 | 本地功能验证通过;不构成可信发布证明 | `30-worklog/tasks/20260812-client-browser-preflight-c8e2.md``926056a` | 121 项聚焦回归、typecheck、scoped lint、三端 build 与真实 Electron 双视口 E2E 通过loopback UX 预检无 receipt/provenance/opaque-origin parity服务端门禁仍需生产整链验收 |
| 2026-08-12 | Makelore Main-owned 本地静态 Release 构建 | 本地功能与 Windows 安装产物验证通过;安装器未发布 | `30-worklog/tasks/20260812-client-built-release-makelore-7e5b.md``5b44864` | 6 files / 129 focused tests、typecheck、scoped lint、Vite build、真实 Electron 双视口 E2E 与实际 npm/Vite smoke 通过;安装器 223,547,912 bytesSHA-256 `08A0BB7BC66EE4AD8B120E8955B149951CD86AF53CC966C7973AD4D77A5815C1`,内置 npm 11.6.2 已由 packaged verifier 验证,但未上传或发布 |
## When To Add Evidence

View File

@@ -4,7 +4,8 @@ Track future-facing memory: promised follow-ups, unfinished loops, timed checks,
| Date | Commitment | Trigger / Due | Owner | Status | Next Action |
|---|---|---|---|---|---|
| 2026-08-10 | 完成客户端提交到 App `play_url` 播放的真实生产整链验收 | 服务端 Builder、OSS immutable Release、CDN/Edge 与 App 消费链成组集成后 | 客户端/服务端集成 | Pending | 使用真实账号执行小游戏和小程序创建、客户端 loopback UX 预检、提交、服务端受控构建/不可变 Release 门禁、运营批准、CDN 发布、App 播放与监控核对;如需不可绕过 runtime gate另行设计可信 verifier |
| 2026-08-10 | 完成客户端提交到 App `play_url` 播放的真实生产整链验收 | source+built+contract 服务端协议、OSS immutable Release、CDN/Edge 与 App 消费链成组集成后 | 客户端/服务端集成 | Pending | 使用真实账号执行小游戏和小程序创建、客户端本地构建与同字节预检、双归档提交、服务端逐字节校验/不可变 Release 固化、运营批准、CDN 发布、App 播放与监控核对;如需不可绕过 runtime gate另行设计可信 verifier |
| 2026-08-12 | Windows 发布流水线保留固定 npm 运行时产物门禁 | 每次生成正式 Windows 安装器时 | 客户端发布 | Pending | 运行 `pnpm verify:publish-runtime``pnpm verify:artifact:win`;当前 223,547,912-byte / SHA-256 `08A0BB7BC66EE4AD8B120E8955B149951CD86AF53CC966C7973AD4D77A5815C1` 安装器仅为本地证据,尚未发布 |
| 2026-08-10 | 删除客户端 `runtime_url` 兼容回退 | 一个客户端兼容版本结束,且服务端与存量数据稳定提供 `play_url` | 客户端 | Pending | 删除类型字段、读取分支和对应回归测试 |
| 2026-08-11 | 部署并验收 AI 绘画多 Conversation 服务端契约 | 发布包含多会话客户端之前 | 客户端/服务端集成 | Pending | 确认迁移 `0033`、Conversation list/create/read/turn/confirm API、持久 Agent Session 与事件字段已上线 |

View File

@@ -9,7 +9,7 @@ This is the integrated registry of stale or conflicting canonical memory. Update
## Missing Context
- 尚未验证真实生产环境是否已部署 Builder → OSS immutable Release → CDN/Edge也未完成运营审核到 App `play_url` 播放的真实整链证据;客户端本地与模拟上游验证不能替代该结论。
- 尚未验证真实生产环境是否已部署 source+built+artifact contract 的逐字节校验 → OSS immutable Release → CDN/Edge也未完成运营审核到 App `play_url` 播放的真实整链证据;客户端本地与模拟上游验证不能替代该结论。
- 尚未验证生产 Works Square 已部署迁移 `0033`、多 Conversation API 与对应持久 Agent Session 契约;合并客户端代码不等同于具备生产发布条件。
## Feature Task Routing