6.6 KiB
6.6 KiB
System Overview
Current Architecture
Makelore 是 Electron 桌面客户端。Renderer 负责项目操作与状态展示；Electron Main 持有认证、文件系统、安全打包、Works Square 网络访问和预览 URL 校验。
Main Components
| Component | Responsibility | Notes |
|---|---|---|
| Renderer | 项目配置、一键提交状态、真机二维码 | 不接触账号 Token、ZIP、幂等键或本地绝对路径 |
| Host API | 校验本地项目请求并投影安全响应 | 发布 mutation 还必须通过 Renderer capability；Host token/base 不能单独触发发布 |
| Project Configuration & Template | 保存不可变 ProjectType，原子生成新项目骨架 |
小游戏/小程序生成受控 Vite 模板；自定义保持最小项目空间 |
| Project Release Builder | Main-owned 安全快照、本地 npm/Vite 构建、双归档与 artifact contract | 固定 npm 11.6.2；Vite 由项目 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 |
| 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 Image Source Picker | 当前 Workspace 已完成图片或本地上传 | 图片 Brief 绑定图生图参考图；视频 Brief 绑定首帧；提交一个真实 Asset ID |
| AI Design Event Routing | Main 云端适配器 → Host API/SSE → Renderer store | Conversation 更新按 Workspace + Conversation 路由；任务更新按 Workspace 归并 |
Important Boundaries
- 发布只有现有项目配置底部的一个入口，不新增发布工作台、侧栏或资源卡。
- 创建者发布唯一调用链是
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 仍继续轮询服务端校验与 Release 固化状态。 - 公共播放投影只有在上游
playable === true、版本名非空且 URL 通过同源 HTTPS、无 userinfo/loopback、长度、精确路径和无 query/fragment 校验时才可播放；不可信数据 fail closed。 - Renderer 只能获得安全状态字段和可展示的播放/短时预览 URL，不得持有发布凭据、归档路径或自动部署状态。
- 落盘文件名
works-cloud-deploy.json仅为已安装客户端的数据兼容；领域模型和代码接口是 submission binding，不表示仍存在 cloud deployment coordinator。 - AI 绘画中，一个 Workspace 可包含多条 Conversation；消息、Brief、Quote 和
turnRevision属于 Conversation，生成任务和资产属于 Workspace。新建 Conversation 不得隐式创建新 Workspace。 - 每条 Conversation 复用服务端持久 Agent Gateway Session。客户端不得在注销或退出时 DELETE 该 Session；只关闭本地事件流并清除本机 Session-id 缓存，重新访问时从 Conversation API 刷新。
- Renderer 的异步与流式状态必须同时校验 Workspace + Conversation 身份；项目任务事件只按 Workspace 归并，避免切换会话时丢失任务或接收迟到消息。
- 图片与视频复用同一个单图来源选择器。图片 Brief 可从当前 Workspace 的已完成作品或本地上传中选择一张参考图继续生成；视频 Brief 使用同一入口绑定首帧。两条路径都必须通过现有 Workspace Asset 上传/选择契约提交一个真实
attachmentAssetIds，不得用本地路径或自然语言描述代替资产身份。 - 当前兼容协议仍通过精确 quick reply
从作品列表选择图片打开选择器，并由当前 Brief medium 区分用途；仅medium === image使用图生图语义，video、null 或缺失 medium 保持视频首帧语义。该展示文案耦合不得扩散到更多用途，后续应升级为结构化 action/purpose。
Related Decisions
- 当前长期边界记录于 README、ADR-001、集成任务
20260807-integrate-login-client-a4f8、源任务20260810-static-release-only-a91c、20260812-client-built-release-makelore-7e5b、20260812-design-image-to-image-client-c91e及本次 Integration Gate；后续如改变唯一入口、凭据所有权、构建执行边界、Conversation 状态归属或重新引入客户端部署协调器，应新增 ADR。
Last Updated
2026-08-13