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

Data Flow

Cloud knowledge embedding

MakeLore 知识库 → Yuxi 已启用 embedding 目录与知识库/发布快照 → Yuxi 直连供应商 → Milvus 索引或查询。向量费用由平台承担，不进入 one-api/Works Square 模型目录、用户用量、词元点数或智能体金额预算。下述既有受管模型能力链不作为云知识库 embedding 入口；聊天及其他原有网关能力保持。访问资格和实际运行时限仍由云执行检查。

Managed model capability flow

one-api 官方接口/文档事实与实际 group 路由交集 -> Works 完整快照和业务授权 -> model-config v2 -> Main 安全 Provider metadata -> 产品 reasoningChoice/图片输入校验 -> 冻结父/子运行上下文 -> Pi 请求钩子清除 SDK 控制字段并写入原生字段。Renderer 消费相同能力投影，缺失事实不做名称推测；详情见官方能力决策。

Code image attachment projection

Main 在接收带图消息时立即将上传 attachment id 放入 optimistic user node；Pi 的实时事件与持久会话恢复都通过 production composition 的 projectImage 回调，将图片字节映射到同一附件存储。Renderer Snapshot/Patch 只携带附件引用，时间线按需读取二进制；重新打开会话后仍可展示图片。

附件存储按 MIME 与图片字节复用已写入文件，避免每次事件或历史 hydration 重写整张图片；既有随机 ID 附件继续可读。模型识图能力仍由官方能力投影决定，不能根据旧会话中助手自述“看不到图片”反向更改模型配置。源提交：03fc50f；生产 composition、真实 Pi 新建/恢复会话 HTTP 和 Electron 图片刷新测试提供验证。

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.
Code-owned official Plugin activation	System-included Data Service or Account Library entry for Game Resource / Project Scaffold	existing delivery/acquisition + project enablement + exact MakeLore resource package	Delivery/acquisition and project enablement remain separate. Once enabled, all three identities enter every parent Agent without assignment; child Agents remain empty. No device download, update, Beta, artifact signature, or device-uninstall action exists for these code-owned identities. Project Scaffold 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 code-owned official definition + project selection + applicable 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. Data Service、Game Resource 与 Project Scaffold 直接按项目启用状态取得资源；Agent assignment 只对采用该范围的其他 Plugin 保持权威。Disable、账号/项目切换、logout、Renderer crash、Main shutdown 或 worker generation 变化会使后续动作失效，但不改写持久化的未知 assignment；child worker 不接收 Plugin 投影。
Plugin workspace navigation	Project Configuration 插件 ResourceCard or compatibility URL	/project-config/plugins → Project Configuration remains mounted → same-page wide Plugin sheet → unified Plugin stores/Main routes	Code sidebar has no standalone Plugin entry. /plugins and old Plugin URLs only preserve query/filter intent while redirecting; embedding does not merge acquisition, install, project enablement, assignment, runtime authorization, or billing lifecycles.
Hosted Game Resource operation and delivery	Eligible parent makelore.game-resource generate call plus one explicit confirmation	frozen Plugin adapter → Main delivery coordinator → one GameResourceClient submission → internal status polling → all terminal downloads → assets/generated/game-resource/<executionId>/ in the frozen original project	Server policy owns pricing、payer、Admission 与 Provider receipt state；Main owns the durable local delivery receipt and filesystem. submission_unknown 不会作为新请求重放。重启或重试只恢复下载/保存，共享项目写租约仅在终态落盘期间持有；Agent 只收到一张进度/结果卡片，不暴露 status/save 工具，也不要求第二次确认。
桌面认证生命周期	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
Account Token Points V2	已登录账号菜单、窗口 focus 或重新可见	Renderer → Main /api/works/billing/points → Works Square /api/billing/points → safe balance projection	可管理会员的账号获得规范字符串点数与套餐/周期元数据；非管理者的精确字段全部置空，只投影 shared_available、共享/青少年类型和升级责任。旧 rolling-window usage API 与 stale event 不再参与。
Expiring reset-card wallet	已登录账号展开卡包或明确点击一张可用卡	Renderer → Main /api/works/billing/reset-cards[/{card_id}/redeem] → Works Square /api/billing/reset-cards[/{card_id}/redeem] → strict card projection	卡包延迟加载并显示运营赠卡的可用、已过期、已使用状态；Main 丢弃内部字段和未知错误文本，Renderer 对已到期或共享钱包禁用操作。只有服务端成功或幂等重放后才刷新卡包与 Token Point V2 余额；付费重置卡不经过此库存流。
用户模块入口策略	会话恢复 / 登录 / 刷新	Electron Main → Works /api/auth/me → 三布尔安全投影 → Renderer auth store → 卡片/路由/provider gate	缺失对象或字段默认 true；design 映射 painting；额外旧字段被忽略；终止性 401 清理 Main/Renderer 会话；全局 /settings 不受 Code gate
项目创建	新建项目对话框中的目录选择	Renderer 内部默认 interactive_ai_app → Host API → Main 生成 UUID 并原子初始化	普通用户不选择类型、模板或项目身份；只生成 .makelore/project.json 与 knowledge/，随后直接进入 /chat。既有 custom/历史类型和底层兼容入口仍保留
旧项目身份补齐	有效 .makelore/project.json 仅缺 projectId	Main serialized config read/repair → canonical UUID persisted once	并发读取共享同一次修复；原始 UUID、bind/independent-copy 控件不进入普通 UI。其他缺失或无效 metadata 仍是配置错误；initialized 不阻断有效项目
显式项目脚手架	用户在已获取且项目启用的 Project Scaffold Plugin 下明确要求初始化	Main-owned effective resolver 自动向该项目父 Agent 提供 Skill → Pi bash + 项目 write lease → MAKELORE_NODE_EXECUTABLE → bundled makelore-project-scaffold 脚本	不要求伙伴分配，也不是项目创建或聊天前置条件；child 仍为空。固定六文件目标；全量预检、不覆盖、受控失败只回滚本次路径；不安装依赖、不联网、不构建、不上传、不提审；下载 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
共享开发浏览器	用户面板打开或 parent Agent agent_browser open	当前项目身份 → Main-owned browser route/module → sandboxed WebContentsView + bounded CDP → 同一 Renderer 右侧 viewport/Console/Network	Agent 发起打开后先通知 Renderer 展示并最多等待 5 秒取得当前 generation 的可见 bounds；项目 id 仅允许具备 Renderer capability 的请求使用。非 Web、文件注入、跨目标及宿主级 CDP 被拒绝；诊断 owner 释放到零后停止采集。
客户端更新检查	设置页	Renderer update store → IPC → Main AppUpdater → 目标 feed	Main 记录并重抛原始错误；Renderer 只显示去重、脱敏的单条提示，稳定源缺包不伪装为最新版
Design Workspace load	Canvas 中央区与右侧 Works rail	Renderer Host API → Main-owned Works Square V2 adapter → current Workspace/Direction/Living Form projection	一个 Workspace 公开一个 current Direction 与 persistent Agent Session；右 rail 只选择/创建/删除 Workspace，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
Design activity and reply streaming	Direction Gateway journal	Main 固定活动阶段归一化 → Renderer operation-scoped activity；committed assistant delta → matching provisional assistant bubble → canonical Turn	design.assistant.progress 只显示在对应 optimistic user message 下方，不成为消息或右侧摘要；design.assistant.delta 只投影已提交回复。两者都按 Workspace、Direction、operation identity 和 replay cursor 收敛，均不改写 Specification
设计有限请求生命周期	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 reference alias editing	Active plan 的 final Prompt 与 binding-only reference row	@图片N token/add/replace/remove → typed field/collection operations → Current Specification revision	Prompt 决定图片如何参与生成；row 只管理稳定 reference/Asset identity。未绑定 alias 定点要求上传并阻止 Quote；删除时原子移除 binding 并重排后续 alias，既有 alias 不重复插入
Design Quote and confirmation	当前 exact Specification revision，或同一 accepted chat Run 中服务端识别出的显式完成意图	design.quote.request → immutable public Quote projection → design.generation.confirm with Quote ID	服务端可在同一 chat operation 下先发送 committed chat Direction projection，再发送 offered Quote projection；Store 依次收敛两者，Renderer 不发第二个 mutation。Renderer 只展示 output summary、warnings、expiry、Token Points；Provider Prompt/model/route/storage/internal billing 不下发或编辑，且只有用户显式确认 Quote ID 才授权创建 Task
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 URL	/image-prompts/*	App replace-redirect → /image-canvas	当前 Canvas 无“获取灵感”入口，App 不挂载或 lazy-load Museum 页面；保留的 Main API/auth/media 与 shared DTO 是 dormant 兼容/安全基础设施
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 Store/API 不参与当前 Renderer 导航或 Canvas 状态；保留代码不得被解释为可达产品流程。
• 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。
• Dormant Works Square Prompt Museum list/detail/media compatibility API；Main 继续持有 Bearer 与媒体校验，当前 App 没有可达 Renderer 消费者。
• 已实现的本机 Robot provisioning capability、固定 portal-open 与 hotspot scan/connect Host API。它们是本地 Main 操作，不读取 Works access token、不调用上游，也不接受任意 URL/SSID/BSSID/interface/profile。

Last Updated

2026-09-15