makelore/.project-docs/20-architecture/system-overview.md

System Overview

Current Architecture

Makelore 是 Electron 桌面客户端。Renderer 负责项目操作与状态展示；Electron Main 持有认证、文件系统、安全打包、Works Square 网络访问和发布安全校验。

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 仅一版本回退
Built Artifact Preflight	在上传前对最终 built snapshot 做桌面/移动 UX fail-fast	Main 使用临时 loopback origin 与 Electron WebContents/CDP；不使用 Playwright、不生成可信证明
App Updater	Main 选择平台/架构 feed、驱动 electron-updater 并记录原始诊断	Renderer 只接收状态和脱敏后的单条用户提示；稳定源缺包保持错误
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 归并，避免切换会话时丢失任务或接收迟到消息。
• Updater feed 选择、原始错误日志、下载和安装生命周期只属于 Electron Main。Renderer 不得把缺失稳定 manifest 投影为“已是最新版”，也不得显示原始堆栈、URL、路径或错误码；并发检查共享同一错误事件时只发送一次错误状态，后续独立重试仍可重新报告。
• 图片与视频复用同一个单图来源选择器。图片 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