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

Data Flow

Permanent wallet and recharge

账号菜单 / PointWallet → src/lib/works-billing.ts → Main 固定 /api/works/billing/* 路由 → Works Square 账务 API。Main 持有认证与账号绑定，通过 shared/works-billing.ts 的公开 DTO 投影余额、产品、订单及流水；充值沿用 Renderer capability，Renderer 不传付款人、价格、Token 或任意上游地址。账号切换后 Main 与账号绑定的 UI 丢弃迟到结果，打开菜单和窗口 focus 刷新当前账号。

本人点数与 AI 编程已选付款来源分开呈现。shared_available 为布尔值时只向 Renderer 提供另一付款方的可用性，精确余额置空；为 null 时保留本人规范字符串余额，即使 family_shared=true 且来源为 self / shared_group。充值资格来自服务端，不能用旧会员管理权限或共享标记推算。云智能体创建者付款与 Plugin 个人付款不受 AI 编程来源选择改变。

明确充值 → 稳定 request identity 创建订单 → 冻结订单金额/点数与支付信息 → GET 恢复/查询原订单 → 服务端确认入账 → 刷新本人余额与流水。请求结果不明时保留原 identity，不自动重放 POST；已有待支付/人工核对订单先恢复，不能另建替代订单。商品改价不改变旧订单，支付二维码或用户声称支付不构成到账证据。网页续付和付款来源管理只打开固定账号页。

规则与证据见永久点数规则及集成记录。

Game Audio generation and local delivery

Project-enabled optional bundled Game Audio → frozen eligible parent tool → one explicit generation confirmation → Main durable pre-submit receipt → fixed Works Square hosted API. Main queries the original execution internally, then saves every output beneath assets/generated/game-audio/<executionId>/ in the frozen original project. A lost POST response uses operation lookup; restart, account reconnect and download retry never submit another generation. The shared project write lease covers materialization/tracker only, not network waiting. Provider/billing status and local delivery status remain separate.

The conversation card displays saved relative paths. An explicit preview click uses the receipt/account-owned Main route and existing bounded local media reader, then native audio controls with no autoplay. No Provider credential, URL, job ID or audio payload is sent to the model. Server migration 0093 and enabled authoritative prices are deployment prerequisites; synthetic media tests are not real Meowa acceptance.

Code conversation metadata

Main 的 .makelore/conversations.json schema v2 是 Conversation 标题和归档状态的唯一权威。新建自动命名会话由 Main 生命周期订阅从首条真实、完整用户消息提取标题；未命名会话的历史 hydration 可补齐同一次命名。串行存储重查 titleMode / autoTitleSet，手动命名和已删除记录不会被后续事件覆盖。内部命名字段不进入公共 DTO，也不向 Pi session title 双写。

重命名、归档和恢复经现有 Host API 修改元数据；conversation.metadata-changed 在现有 SSE 上只传项目和会话身份，不伪造运行时 generation/seq。Renderer 合并列表刷新、在重连时重新读取列表，并拒绝跨项目或早于本地变更的旧结果。归档不 dispose runtime、不移动 JSONL；Main 阻止归档会话的新 prompt/steer/follow-up 与 fork，保留已接受请求、现有任务、审批与中止能力。

Code model replacement

用户在现有 Conversation 中明确选择模型后，Main 先校验新选择。若目标尚无 worker，则先持久化新模型并清除失败准备留下的注册缓存，再沿原 session binding 准备 Pi；旧模型已下架不能成为更换模型的前置条件。已崩溃 worker 即使同账号也用新模型重建目标线程，恢复原历史；已有 worker 保留原来的 mutation/uncertainty 门禁。

Provider catalog 的模型不可用错误投影为 CODING_MODEL_UNAVAILABLE，界面提示重新选择，不再误报通用运行时不可用。更换模型不会自动选择替代项、重发消息或为修复选择而强制停止运行任务。

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
Permanent Token Point Wallet	已登录账号菜单、窗口 focus、明确充值或恢复订单	Renderer → Main /api/works/billing/* → Works Square 固定账务 API → safe wallet/order projection	本人精确余额与另一付款方可用性分开；稳定充值身份、冻结订单、原单恢复与服务端确认入账遵循上方数据流。会员、周额度与重置卡流程已移除。
用户模块入口策略	会话恢复 / 登录 / 刷新	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-22