makelore/.project-docs/20-architecture/data-flow.md

Data Flow

Primary Flows

Flow	Source	Destination	Notes
Marketplace catalog and Account Library	Signed-in Renderer intent	bounded Host API → Main Marketplace client/cache → Works Square catalog, Library, resolve, Admission, and download APIs	Main binds requests to the current Account and response generation. Free acquisition changes only Account Library; it does not install, enable a project, assign an Agent Skill, or authorize runtime execution.
Marketplace device installation	Account Library entry and explicit channel	Main resolve/Admission/download → descriptor/signature/archive/client compatibility verification → immutable Package Store index switch	Stable and explicit Beta remain distinct even when they resolve to the same immutable Release. Failed install/update retains the previous current release; explicit uninstall waits only for protecting worker/account references and completes after the final worker exits.
Official bundled Plugin acquisition	Account Library entry for Game Resource or Project Scaffold	server stable bundled Release/Admission + exact MakeLore resource package	Free acquisition changes Library only; project enablement and Agent assignment remain separate. No device download, update, Beta, artifact signature, or device-uninstall action exists for either code-owned identity. Game Resource is hosted; Project Scaffold is skill_only and may execute only its bundled .mjs. Historical Hosted Web Search entries are ignored.
Selected-model Web Search	Parent Pi turn with an explicitly supported selected model	makelore_web_search core tool → frozen model/provider/credential request with provider-native forced search → ordinary model response/usage	No Marketplace Release, Account Library, Admission, Hosted Web Search client, Plugin Charge, or agent_browser fallback participates. Unsupported selected models expose no tool; child workers receive none.
Conversation-driven Device Package install	Agent tool inspects npm/Git/absolute local Plugin/loose Skill source	Main preview → distinct later user confirmation → immutable device-package generation → new/idle parent worker resources	Renderer has no install picker. Lifecycle scripts never run. Pi extensions and non-empty Skill scripts/ are disclosed as desktop-user executable code before confirmation. Active workers retain their frozen generation until the turn settles; child workers remain empty.
Effective Plugin worker snapshot	Installed trusted package or acquired official bundled definition + project selection + Agent assignments + current server policy	effective resolver → Registry/resource loader/Extension Host/tool catalog → parent Pi worker	One frozen snapshot supplies Skills, tools, package roots, and runtime authorization. Disable, account/project switch, logout, Renderer crash, Main shutdown, or worker generation change invalidates future actions without mutating persisted unknown assignments; child workers receive no Plugin projection.
Hosted Game Resource operation	Eligible parent makelore.game-resource tool call plus explicit confirmation	frozen Plugin adapter → capability Registry → Main GameResourceClient → fixed Works Square game-resource route → provider-neutral receipt/result	Server policy owns pricing, payer, Admission and receipt state. Stable logical operation identity survives response loss/Main restart; submission_unknown is not replayed as a fresh request. Result saving uses a bounded project-relative path and the existing project write lease.
桌面认证生命周期	Renderer 登录、刷新与注销请求	Host API → Main Works Session → Works Square /api/auth/{login,mobile-login,refresh,logout} → one-feel auth	Main 加密持有并先持久化轮换 token；客户端不携带 OAuth client secret；连续 7 天未使用才清除会话，终止性 400/401 fail closed
用户模块入口策略	会话恢复 / 登录 / 刷新	Electron Main → Works /api/auth/me → 三布尔安全投影 → Renderer auth store → 卡片/路由/provider gate	缺失对象或字段默认 true；design 映射 painting；额外旧字段被忽略；终止性 401 清理 Main/Renderer 会话；全局 /settings 不受 Code gate
项目创建	新建项目对话框	Host API → Main 项目初始化	固定 interactive_ai_app 或 custom，只生成 .makelore/project.json 与 knowledge/；历史双类型在读取边界归一，不因读取改写
显式项目脚手架	用户为已获取、项目启用并分配给 Agent 的 Project Scaffold Plugin 明确要求初始化	Pi bash + 项目 write lease → MAKELORE_NODE_EXECUTABLE → bundled makelore-project-scaffold 脚本	固定六文件目标；全量预检、不覆盖、受控失败只回滚本次路径；不安装依赖、不联网、不构建、不上传、不提审；下载 artifact 不参与
一键提交	ProjectPublishAction	Renderer capability → Host API → Main 本地 npm/Vite build → built snapshot preflight → source+built+contract 上传	只对规范交互式 AI 应用（含读取时归一的历史别名）开放；首次 create 通过单一 multipart 合同原子提交文字资料与必选 PNG/JPEG/WebP 封面，创建失败或冲突不上传版本；已有 draft/published 只提交版本并沿用云端资料/封面，不做无条件 metadata PATCH
构建产物预检	Main-owned built snapshot	一次性 loopback origin → fresh Electron WebContents/CDP（桌面、移动）	检查错误、白屏和外域；不调用 Playwright，检查与上传归档相同字节，但不产生可信 receipt
提交绑定	云端成功上传响应	Main → submission binding v2	只持久化成功的 app/version/review/hash；落盘失败返回固定告警但不反转提交
运营发布	Works Square 审核与交付	公共 play_url	客户端只消费服务端发布结果；真实合同校验 → OSS/CDN 生产链仍待整链验收
可信发布门禁	source+built+artifact contract	服务端逐字节重算/合同校验 → 不可变 Release 固化 → 人工审核	服务端不运行项目 Vite；仍是不可绕过权威，未来 runtime 强门禁需可信 verifier
AI 编程 Conversation 创建与准备	当前 project / Agent / 本地 Conversation	Renderer 本地创建 → /api/coding/* → Main .makelore schema-v2 store → shared Agent Server 内 target logical Runtime/Session lazy prepare	Composer 与逻辑线程准备解耦；首次 Conversation 可立即编辑。未解析模型必须先验证并持久化，再打开首个逻辑线程；.niancode / .opencode 项目元数据不读取、不迁移
AI 编程 prompt 与流式投影	当前 Conversation draft / attachment refs	Renderer mutation → Host 202 acceptance/dedupe → Main target Agent Server channel → Pi events → Snapshot + patch-batch SSE → Renderer reducer	每个 Conversation 独立 Runtime/Session/credential/extension context/generation/seq；gap 只恢复目标 Conversation。accepted/uncertain mutation 不自动重放，权威 Snapshot 到达前保留相同 optimistic node identity
AI 编程前台状态收敛	Main lifecycle:sleep、编程视图挂载/项目上下文变化、页面重新可见或窗口 focus	Renderer 关闭旧 SSE → 静默读取当前选中 Conversation 的 Main-owned Snapshot → target-only reducer	已选 Conversation 即使身份未变也会与后台 terminal 状态收敛；selection key 防止选择渲染自身造成重复 hydration。该流程只读 Snapshot，绝不重放 accepted/uncertain mutation
AI 编程模型与思考强度切换	当前 Conversation	Renderer → /api/coding/conversations/{id} → Main validate/persist → target logical Runtime	同账号已解析模型复用 set_model；跨账号模型等 active run settled 后只重建目标逻辑线程，旧凭据不会进入新 generation；切换失败不销毁可继续使用的旧线程
AI 编程上下文压缩	Renderer compact action / Pi compaction events	correlated compact RPC → target projector → Snapshot/Patch timeline	Pi 0.84.2 的手动 compact 不发 agent_settled；RPC success 或权威 compaction failure 终结 compact 并 exactly-once 释放对应 ownership，不提前结算普通 prompt
AI 编程 Provider 错误	Pi logical-thread Provider 请求	selected thread-local credential store → Main AI proxy → Works 模型上游 → projector safe error	确定性的 Works user-context 缺失使缓存 gateway credential 过期、返回非重试认证失败且不重放请求；Renderer 只看到固定 Provider-auth 提示，不能把它解释为 Pi 崩溃
AI 编程子 Agent	parent logical thread subagent.v1 tool call	explicit extension → authenticated Main bridge → scheduler → independent ephemeral Pi child process	child 并发最多 4、单次最多 8、禁止递归；child 使用 FIFO 进程预算 8，shared parent 逻辑线程不各占一个 process lease；coding child 与 parent 共用项目 write lease，父 abort/crash/generation 失效必须清理 child 与 permit
客户端更新检查	设置页	Renderer update store → IPC → Main AppUpdater → 目标 feed	Main 记录并重抛原始错误；Renderer 只显示去重、脱敏的单条提示，稳定源缺包不伪装为最新版
Design Workspace load	Canvas/Sidebar	Renderer Host API → Main-owned Works Square V2 adapter → current Workspace/Direction/Living Form projection	一个 Workspace 公开一个 current Direction 与 persistent Agent Session；conversation timeline 是交互历史，不是独立 authority object
Design input and reconciliation	Chat/direct edit/decision/proposal/lock/Asset binding/restore	Renderer draft → Main → design.input.apply → canonical Direction projection	全部进入同一 reducer；accepted 前 draft 保持本地，revision conflict 刷新权威投影，unknown result 复用原 command/operation identity
设计有限请求生命周期	Renderer Workspace JSON 调用 / shared Works token refresh	Main deadline → Electron transport → safe-read-only Node fallback → Host API timeout envelope	包括取凭据、请求头和响应 body 的完整生命周期最多 30 秒；超时 abort transport 并稳定返回 504 DESIGN_WORKSPACE_REQUEST_TIMEOUT；透明 fallback 只允许 GET/HEAD/OPTIONS，mutation 不隐式重放
Design Asset binding	当前 Workspace 已完成图片 / 本地上传	canonical Asset → typed asset_binding input → Current Specification revision	图片/视频用途由 Specification medium 和 binding role 决定；只提交真实 Workspace Asset identity，不使用本地路径或自然语言占位
Design Quote and confirmation	当前 exact Specification revision	design.quote.request → immutable public Quote projection → design.generation.confirm with Quote ID	Renderer 只展示 output summary、warnings、expiry、Token Points；Provider Prompt/model/route/storage/internal billing 不下发或编辑
Design Task and Asset sync	Direction event stream / Workspace resource events / explicit refresh	Renderer Task/Asset projections	Task/Asset events独立于 Living Form；transport order 和 progress 不改写 Specification，也不授权新生成操作
设计项目删除	Canvas 侧栏精确项目名确认	Renderer → Main Host API → Works Square Workspace DELETE	删除成功后清理当前 Workspace/Direction/resources 并选择最近更新的剩余项目；结算与软删除语义由服务端负责
Prompt Museum 浏览与使用	Canvas 侧栏“获取灵感”	Renderer → Main Host API → Works Square list/detail；选中 Prompt → 进程内 pending state → 当前 Canvas 输入框	只发送白名单筛选/游标；Works Token 留在 Main，Prompt 不自动发送，Museum 不包含客户端静态数据集
Robot 引导式热点配网 V1（已实现、默认开启）	Robot Binding 页面	用户选择引导配网 → 进入固件配网模式 → Renderer 经 Host API 请求 Main 扫描 → 用户选择短效候选 → Windows/macOS Adapter 连接并核验当前 SSID → Main 打开固定 Portal → 用户在 Portal 配置 Wi-Fi → 电脑恢复互联网 → 现有六位 Binding	精确环境值 0 或 capability 读取失败回退直接六位码；系统 Wi-Fi 保留兜底，Makelore 不收集 Wi-Fi 密码、不修改固件，热点发现/bound 都不等于可信身份或 online/ready

State Ownership

• Main 持有刷新凭据、发布 Token、固定 npm runtime、源码/构建归档、临时目录、幂等键和 submission binding v2；Renderer 不持有归档路径、构建 origin 或自动部署状态。
• 项目内 .makelore/project.json 是 ProjectType、Agent 与 Coding 项目配置的唯一权威；Main 在配置写入和目录复用时保持 ProjectType 不可变，并在打包时重新读取校验。历史 mini_game / mini_program 只在内存中归一为 interactive_ai_app，读取和脚手架运行不改写原文件。
• Renderer 仅持有短效公开会话状态和提交展示状态。
• Renderer 可持久化当前账号的三布尔模块入口策略，但不持有原始 Works profile 或 Token。新账号不继承上一账号缓存；网络/暂时上游失败可保留同会话已知策略，终止性 401 不得回退到默认开启。
• 本地构建临时目录、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 Design Current Specification 与 current Direction 是语义权威；conversation timeline 只保存交互历史，immutable Quote 绑定精确 Specification revision，Task/Asset 属于 Workspace resource projection。
• AI 绘画 Main 持有 Workspace 请求 deadline、底层 transport fallback 和共享 Works token refresh flight。共同等待者必须在同一有限期限内 settle，refresh flight 结束后必须释放，后续刷新可重新发起；底层 mutation transport failure 不得自动产生第二次上游请求。
• Prompt Museum pending Prompt 是 Renderer 进程内一次性导航状态；Canvas 消费后立即清除，不进入 Workspace/Specification，直到用户主动提交 Design input。
• Retired Learning data is outside the active client state model. Historical downloaded course data is not read, migrated, or automatically deleted.
• 图生图参考图与视频首帧都先归一为当前 Workspace Asset，再通过 typed binding 写入 Specification；本地路径不会进入 canonical contract。
• Development 与 packaged Canvas 都使用 Main-owned Works Square V2 adapter。V1 DTO/local semantic adapter 与 local/cloud mode switches 已删除，不存在失败回退。
• 注销和退出关闭本地 event stream、清除 drafts/pending state 和凭据；服务端 current Direction Session 与 semantic history 保持持久化。
• project、Agent、Conversation schema v2 与每条 Conversation 的 opaque Pi session binding 由 Main 在 .makelore/project.json 和 .makelore/conversations.json 原子持久化。当前客户端不读取、迁移或删除 .niancode / .opencode 项目元数据。
• Renderer Store 只拥有产品中立 Snapshot、Patch、optimistic request 与 project-scoped metadata。每条 Conversation 的 generation/seq 独立；stale generation 丢弃，gap/reconnect/foreground reconciliation 只为目标 Conversation 取 Snapshot 并应用严格连续的缓冲 tail，不重放 mutation。隐藏 Conversation 的红点只表示新出现的 pending interaction，或当前 run 新进入 completed/failed/aborted terminal；流式助手文字、thinking、工具过程和单个工具失败本身不触发红点。
• Main 以一个长驻 Agent Server 承载每条 active/warm Conversation 的隔离 Pi Runtime/Session/channel、Provider/resource revision 和 thread-local credential store。运行中 stale revision 保留本 run snapshot，settled 后只重建目标逻辑线程；整个 Server 退出则使所有旧 channel 失效，下次恢复只启动一个新 Server。
• top-level 逻辑 turn 并发上限 4、warm idle logical-thread LRU 上限 8、child 并发上限 4，child 使用 FIFO process budget 8；shared parent 线程不各占一个 process lease。同项目 coding mutation 共用 write lease；read-only child 可旁路写锁。
• prompt/compact 的 RPC confirmation timeout 只进入 uncertain，不能释放 run permit、process ownership 或 Main background lease。迟到 success/failure/exit/abort 必须单调且 exactly-once 收敛；隐藏页面超过 grace 也不得停止 active/uncertain run。
• AI 编程压缩状态属于目标 Conversation Snapshot。Pi 0.84.2 手动 compact 的 correlated RPC success 可代替缺失的 agent_settled 终结 compact；普通 prompt 仍只由权威 terminal/settled 结束。
• Main Host AI proxy 持有凭据刷新和错误分类。确定性 Works user-context 缺失必须失效缓存 credential 并 fail fast；真实认证、endpoint/proxy/rate-limit、Provider variation、真实并发与共享 Agent Server 内的跨线程凭据隔离仍是用户明确接受但未验证的风险。
• Main AppUpdater 持有 feed、原始异常、下载和安装状态；设置页只消费状态投影。一次 electron-updater error 事件覆盖的并发检查不会在 Renderer 重复发错，但独立的后续检查仍有自己的报告生命周期。
• Robot V1 引导状态只在 Renderer 当前进程内保存，不持久化 Wi-Fi 凭据、activation code 或 Binding operation ID。相同进程内的模糊 Binding 重试复用 operation ID；无效码或重启后必须取得新码并使用新 operation ID。
• Robot Hotspot Module 只在 Main 内保存最近一次扫描的短效、不透明候选快照。新的扫描、clear、60 秒过期或进程重启使旧 candidate ID 失效；Renderer 关闭/重开向导以 generation 防止旧扫描/连接结果回写。

External Interfaces

• Works Square 项目创建、版本上传、构建状态与 Release 状态 API。
• Works Square /api/auth/me 模块权限 API；Electron Main 持有 Bearer 并只向 Renderer 投影 programming/design/robot 对应的三个布尔值，额外旧字段被忽略。
• 本机 Host API 的发布路由；发布路由要求 Renderer capability。
• 本机 /api/coding/* project/Agent/Conversation、Snapshot/patch-batch SSE、prompt/compact/fork/recover、attachment/file/interaction/diagnostics 路由，以及 Main-owned AI 模型代理。
• Main-owned electron-updater IPC 与 Works Square 平台/架构稳定 feed；正式安装产物发布不由 Renderer 控制。
• 服务端安全投影后的公共 play_url；只接受同源 HTTPS、精确 App 路径和可信版本状态。
• Works Square Design V2 Workspace/Direction/Living Form API、持久 Agent Gateway Session、Direction event stream，以及 design.input.apply、design.quote.request、design.generation.confirm stable-operation contract。
• Works Square Prompt Museum list/detail API；Main 添加当前账号 Bearer Token，Renderer 只使用 Host API 投影。
• 已实现的本机 Robot provisioning capability、固定 portal-open 与 hotspot scan/connect Host API。它们是本地 Main 操作，不读取 Works access token、不调用上游，也不接受任意 URL/SSID/BSSID/interface/profile。

Last Updated

2026-09-04