wangxuming/makelore
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
bc25f4d29ec0877198d6ef53b2bc1c13792c3dba
makelore/.project-docs/20-architecture/system-overview.md

29 KiB
Raw Blame History

System Overview

Current Architecture

知识文档上传、附件导入与替换后由客户端自动衔接既有解析索引接口，Main 保留处理 Task、可用性与替换关系。Renderer 每 5 秒串行刷新已加载页面，以服务端持久 Task 与实际分块显示阶段、失败原因及可用于回答的文档；请求未确认时保留同一操作意图，观察到新 Task 后才解除本地不确定状态。替换失败及清理重试保留旧可用内容，零分块不显示可用。见知识处理交互规则。

知识库 embedding 独立于原有 one-api 模型网关：Yuxi 拥有目录、供应商地址/密钥与实际维度并直连供应商，平台承担费用，不计算用户用量、词元点数或智能体金额预算。访问资格与运行时限保留，聊天计费不变；见已接受向量规则。

微信账号生命周期独立于智能体：MakeLore“渠道 > 微信”展示用户的 Core ChannelAccount 清单，通过 Yuxi 用户级账号 API 连接及选择可选目标；多个账号可指向同一已发布智能体，路由切换保留登录。Core 持有路由与不可变回执，Yuxi 本地 binding 只索引当前关联并保留历史 caller/session，Main 持有请求恢复与凭据。发布页只显示关联摘要与入口；详见用户级账号决策。

微信渠道只供扫码绑定的账号使用：Adapter 从持久登录状态匹配发送者，Core 校验绑定、代次、Worker 和会话后提供可信 is_self，Yuxi 据此建立账号隔离的 caller/session。其他微信需要各自扫码创建连接；不再提供使用范围、邀请或单个调用者授权管理。历史受邀记录不能进入新请求、恢复或投递，也不转为扫码账号内容。历史空身份连接需要重新扫码。

个人微信云智能体已按 已接受渠道决策 集成：AgentBus 拥有共享身份下的 Worker/ChannelAccount 路由及交付，Yuxi 拥有独立账号会话和原生执行，Works Square 拥有创建者词元点数，MakeLore Main 拥有桌面授权与恢复。沿用标准 Worker；付款不授予其他账号或历史受邀会话的内容权限。上线验收与本地代码集成分开记录。

个人云智能体职责见 已接受决策：Yuxi 拥有云执行，WS 拥有账号和词元点数，MakeLore Main 提供 Host API；Code/Pi、Canvas、Robot 保持既有体系。

Agents 的 Renderer 使用账号级桌面工作区：DraftEditor 分别持有编辑内容和已保存草稿，CloudChat 固定当前试用修订与请求身份，DesktopSplit 负责分栏和窗口适配。编辑器以“我的要求”与“高级设置”两个 Tab 控制同一持久挂载的表单，基础要求默认展示，高级分类单独记忆；切换回到内容顶部并保留局部表单及试用输入。草稿保存不重建试用组件，页内隐藏会话保留运行状态但不写已读/最近位置；新试用由用户明确选择。费用上限经既有 Host API 独立保存，布局偏好仅保存尺寸，不充当离线内容存储。

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 目录选择式创建、Agent/Skill/知识与项目资源配置 新建流程不暴露类型、模板或身份选择：Renderer 写入内部默认 interactive_ai_app，Main 生成 UUID，并只创建 .makelore/project.json 与 knowledge/；既有 custom 与历史类型继续兼容
Project Scaffold Skill 显式生成固定版本的交互式 AI 应用起步文件，并提供发布准备度指导 官方 makelore.project-scaffold bundled Marketplace Plugin；账号已获取且项目启用后自动提供给每个父 Agent，不需要伙伴分配，child 为空；它不是创建或聊天前置条件。完整预检、不覆盖、受控回滚，不安装依赖、不联网、不构建、不上传、不提审。
Project Release Builder Main-owned 安全快照、本地 npm/Vite 构建、双归档与 artifact contract 固定 npm 11.6.2；Vite 由项目 lockfile 锁定；产物与预检使用同一内存字节
Works Session & Remembered Password Main-owned 登录、刷新、注销、七天真实活动滑动续期与可选密码回填 登录、刷新、注销统一经过 Works Square；轮换凭据由 Main 安全持有和持久化。记住密码使用独立的 packaged-only OS 加密记录，不进入 Renderer 持久状态或 Works Square；客户端不携带 OAuth client secret
Token Points V2 Main-owned /api/works/billing/points 安全投影 → Renderer 账号菜单 会员管理者可查看套餐、本周与总余额及刷新时间；非管理者只获得 shared_available 粗粒度状态，套餐、周期和精确点数统一投影为 null
Reset Card Wallet Main-owned /api/works/billing/reset-cards list/redeem 安全投影 → Renderer 账号菜单卡包 仅展示 Works Square 的 owner-scoped 运营赠卡，客户端派生已到期状态但不计算重置额度、不乐观成功；服务端确认后同步刷新卡包与 Token Point V2 余额。付费重置卡仍由支付成功立即履约，不进入卡包。
Module Access Policy Main-owned /api/auth/me projection → Renderer auth state → module chooser/router Renderer 接收 Code/Canvas/Robot/Agents 四个布尔权限；服务端 design 映射客户端 painting，云模块两端均为 cloud_agents；缺失对象/字段默认开启，额外字段被忽略
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 只接收状态和脱敏后的单条用户提示；稳定源缺包保持错误
Makelore Code Workspace project/Agent/Conversation schema v2、产品中立 Snapshot/Patch、Composer 与时间线 Conversation 本地创建且不等待 worker；sleep 关闭旧 SSE，视图挂载、项目切换、visibility/focus 会静默刷新已选 Snapshot；旧 OpenCode 会话备份后不再继续，Renderer 不导入 Pi RPC/event 类型
Coding Host API & Composition 唯一 /api/coding/* composition、202 acceptance/dedupe、SSE、附件/文件/交互/诊断 Electron Main 拥有 project/Conversation 服务、选中目标、认证和错误脱敏；SSE 公开面只有 Snapshot 与 patch-batch
Pi Conversation Runtime 一个长驻 Pi 0.84.2 Agent Server 承载每条 active/warm Conversation 的隔离逻辑 Runtime/Session/JSONL channel 严格 LF JSONL RPC、generation recovery、Snapshot hydration；正式包从 staged pi-runtime manifest/root 定位并校验 Pi 包入口；top-level 逻辑 turn 并发 4、warm idle LRU 8；Server 退出统一使旧 channel 失效并按需单实例重启
Pi Provider & Managed Resources Provider catalog、thread-local secret projection、model/resource revision、Prompt/Skill/extension materialization、selected-model tools Works model_capabilities_v2 由 Main 归一化并持久化，作为受管模型图片/思考能力唯一依据；未知不回退本地 profile。Main 保存原生 reasoningChoice 并冻结供应商字段，经 Pi 请求钩子发送。父/子凭据仍限于目标执行上下文；Web Search 保持独立适配器、所选模型及普通模型计费，不回退 agent_browser；secret 不进入 argv、catalog 或 Renderer
Pi Extension, Subagents & Lifecycle 必需的生成式 Makelore extension、Main 显式选定的已安装 extensions、UI interaction、ephemeral child、write lease 与 background run lease Makelore bridge 固定为首个 extension，其余选定 extension 全部经 Pi 的 explicit additional paths 加载且 ambient discovery 关闭；child 并发 4、单次最多 8、禁止递归；active/uncertain run 不因页面隐藏或 confirmation timeout 被停止，replacement/stop 必须可解释并清理所有 ownership
Shared Agent Browser Project-scoped sandboxed WebContentsView、Renderer 右侧面板与 Main-owned CDP bridge 用户和 Agent 操作同一页面；Renderer 必须先提供可见 bounds，Agent open 最多等待 5 秒取得可见 viewport。Console/Network 诊断按 owner 引用计数；关闭面板、切换项目/模块、隐藏窗口或后台休眠会清理 view、debugger 与轮询。
Code-owned Official Project Plugins Existing Account acquisition or system-included delivery → project enablement → effective parent snapshot Data Service、Game Resource 与 Project Scaffold 都不要求 Agent assignment，项目启用后自动进入每个父 Agent；child 不继承 Plugin。三者不经过设备下载、更新、Beta 或 artifact 签名；Game Resource 的一次确认由 Main 提交一次、内部轮询并把全部终态输出自动写入冻结的原项目，恢复本地交付不得重新生成或计费；Project Scaffold 的 .mjs 仍只来自签名客户端固定资源。需要分配的 Marketplace 下载包保持原规则。
Device Packages Conversation install tools → Main-owned inspect/preview/confirm/commit → immutable local generation → parent Skill/Pi-extension resources 支持 npm、Git、绝对本地 Plugin 目录与 loose SKILL.md；没有可见安装入口、Account Library、Release、Admission 或 Marketplace Package Store。可执行 extension 与非空 Skill scripts/ 拥有桌面用户权限，必须披露并独立确认；生命周期脚本禁用。每个 generation 包含所有显式安装且当前启用的 Skill/extension；新/idle parent 自动刷新，active parent 在 turn settled 后刷新，child 始终为空。
Unified Plugin Workspace Project Configuration 的 插件 ResourceCard → /project-config/plugins same-page wide sheet 复用统一 Plugin controller 与生命周期；Project Configuration 保持挂载，Code 侧栏不再提供独立入口；/plugins 和旧 Plugin URL 仅做保留查询条件的兼容重定向
AI Design Workspace & Living Form 一个 Workspace 的当前 Direction、Current Specification、持久 Agent Session、conversation timeline、Tasks 与 Assets 中央区域承载对话和唯一 active 制作方案，320–340 px 右侧 Works rail 承载 Workspace 导航；紧凑布局使用同一右侧 Sheet。Renderer 只持有草稿和已接受投影
AI Design Input & Reconciliation Chat、字段/集合编辑、decision、proposal、lock、Asset binding 与 restore 全部进入同一 design.input.apply reducer；稳定 command/operation ID 支持 unknown-result 重放，revision conflict 刷新权威状态；待提交 chat 从同一 pending operation 临时投影，固定 public activity 附着于该用户消息，assistant delta 只进入匹配 operation 的一个未完成助手气泡；两者都不生成独立语义权威或全局整理栏
AI Design Gateway Routing Main-owned Works Square V2 adapter 与 Direction event stream Main 持有 Works Token、stream ticket、WebSocket、重试分类和错误脱敏；Main 将闭集 design.assistant.progress 阶段归一为固定中文，不透传模型推理或任意服务端文案；事件顺序、activity 与 Task progress 都不构成 Specification 真值
AI Design Quote & Task Controls 精确 Specification revision 编译出的不可变 Quote 与 Workspace Tasks 客户端只展示 public output summary、warnings、expiry 与 Token Points，并以 Quote ID 确认；Provider Prompt/model/route/storage/billing atoms 不下发
AI Design Assets Workspace 已完成作品或本地上传的真实 Asset Asset 通过 typed binding 写入 Specification；生成结果经 Main-owned asset download 保存
Dormant Prompt Museum compatibility Retained Main Host API/auth/media validation/shared DTO → Works Square 当前 App 不挂载或打包 Museum 页面，Canvas 无“获取灵感”入口，历史 /image-prompts 重定向到 /image-canvas；保留代码不是可见产品模块
Robot Workspace Account-scoped agent configuration, device activation/binding, assignment, and credential-recovery UI Renderer receives only safe Works Square projections. Configuration choices come from the USER-scoped safe catalog; unavailable current values remain editable without exposing provider credentials or configuration internals.
AI Hardware Main Route Fixed /api/works/ai-hardware Host API to Works Square proxy Main owns Bearer auth, stable operation IDs, bounded retry, ETag/If-Match, request/response limits, error redaction, and the fixed no-store configuration-catalog proxy. Versioned responses accept only canonical strong or weak numeric ETags that equal the DTO revision; mutations always emit strong If-Match. It never forwards Renderer authorization headers.
Robot Hotspot Module Main-owned bounded scan/connect/verify interface with Windows WLAN and macOS CoreWLAN/CoreLocation adapters Accepts only short-lived opaque candidates from the latest scan, exposes no BSSID/interface/profile/native diagnostic, and retains the system-Wi-Fi fallback.
Guided Hotspot Binding V1 Implemented, default-on Renderer journey over in-page hotspot selection, the current firmware Portal, and six-digit Binding Exact environment value 0 disables the journey. Hotspot discovery is unauthenticated convenience; Portal credential entry remains firmware-owned, and no BLE, automatic claim, or firmware change is part of V1.

Important Boundaries

  • Renderer 只能通过 Main Host API 发起认证操作。Electron Main 是 access/refresh token 的唯一客户端所有者；登录、刷新、注销统一经过 Works Square 固定路由，客户端不得直连 one-feel/custom 身份服务，也不得保存 confidential OAuth client secret。

  • 可选的记住密码记录属于 Electron Main 的独立本机边界，只能在正式安装包且 OS 凭据加密可用时落盘；Renderer 不得持久化账号密码，Works Square 不得接收记住标志或新增密码持久化。

  • Code、Canvas 与 Robot 是三个已启用顶层产品模块；Robot 仍是唯一硬件产品模块，不存在单独 Hardware 卡片。

  • 每个登录用户可由 Works module_access 关闭任意顶层模块入口。Main 只投影三个布尔值；被关闭卡片置灰不可点，根/深层/别名路由在 MainLayout 和模块初始化前拦截。Code provider 必须等待 auth policy hydration，而全局 /settings 不属于 Code policy guard。

  • 模块入口策略是用户交互与客户端初始化边界，不是服务端 API 授权。终止性 /api/auth/me 401 必须清理 Main 和 Renderer 会话；各模块 API 仍须独立强制认证与授权。

  • Product UI language is Chinese-only. Unsupported system or persisted language values normalize to zh; removed locale files are not runtime fallbacks.

  • Canvas is cloud-only in development and packaged builds. The removed local Workspace adapter and V1 DTOs are not fallback paths.

  • Prompt Museum 不属于当前可见产品面。不得恢复“获取灵感”入口或挂载 Museum Renderer 页面；历史 /image-prompts 只重定向到 Canvas。保留的 Main-owned 认证、媒体校验、固定 API 与共享 DTO 是 dormant 兼容/安全基础设施。

  • Learning is retired. No Learning route, Renderer surface, Main Host API, download service, shared DTO, packaging asset, or fallback remains. Historical downloaded course data is not read, migrated, or automatically deleted.

  • AI hardware network access is Main-owned. Renderer cannot hold Works Square or Xiaozhi credentials and cannot select arbitrary upstream paths or headers.

  • Robot model, language, and voice choices are dynamically projected from the Xiaozhi USER catalog through Works Square and Electron Main; the catalog is bounded, account-scoped, and private, no-store at each public hop.

  • One local account maps to one server-side Xiaozhi account binding. Agents and devices are resources beneath that account binding, not separate Xiaozhi users.

  • Robot/Canvas/module-selection routes must not initialize AI Programming projects or providers.

  • Makelore Code 的唯一 production runtime 是精确 pin 的 Pi 0.84.2；不得恢复 OpenCode fallback、双 runtime、兼容执行路径或 Renderer 直连本地 runtime。上游 @earendil-works/pi-ai 内名称含 opencode 的静态 Provider adapter 不属于产品旧 runtime。

  • Renderer 只消费共享的产品中立 project/Conversation/Snapshot/Patch DTO，并经 src/lib/host-api.ts 或 src/lib/api-client.ts 访问 Main。Pi RPC、event、Provider credential 和本地 runtime 路径保持 Main-private。

  • accepted/uncertain Coding mutation 不得自动重放；RPC confirmation timeout 后仍保留 target run permit、process ownership 和 background lease，直到迟到 success/failure/exit/abort 权威收敛。其他 Conversation 必须继续可用。

  • Main 发出 lifecycle:sleep 时 Coding 页面必须关闭旧事件流；编程视图挂载、项目上下文变化、页面重新可见或窗口 focus 时必须从 Main 静默刷新已选 Conversation 的权威 Snapshot。该只读收敛不得转化为 prompt/interaction 的自动重放。隐藏 Conversation 红点只代表新的 pending interaction 或新的 completed/failed/aborted terminal transition。

  • 正式包中的 Agent Server 必须以显式 staged pi-runtime 的 manifest/root 解析 Pi 依赖，校验导入入口未逃逸对应包目录；不得依赖脚本相邻目录、应用 node_modules 或系统包解析作为 fallback。

  • 父 Pi worker 与 Agent Server 必须获得应用选择且不可被 worker overlay 覆盖的 MAKELORE_NODE_EXECUTABLE。包含脚本的 Device Package Skill 只能显式使用该 Node 路径，不得依赖系统 PATH。

  • selected Provider credential 只投影到目标父逻辑线程的内存 credential store 或目标 child 进程；跨账号模型变化必须重建目标逻辑线程。确定性 Works user-context 缺失是 Provider-auth failure：失效缓存 credential、fail fast、固定脱敏提示，不得归类为 Pi crash。

  • one-api 获取官方能力事实，Works 应用业务权限后下发 v2，Main 负责归一化、 持久化与运行前校验。受管模型缺失能力保持未知，不使用模型名推测。 reasoningChoice 保存 default/disabled/enabled 与可选原生 effort，独立于 Pi 枚举；Main 冻结每次运行的供应商字段，Pi 钩子在请求时应用。default 不发送 控制字段；关闭及启用遵循实际 control_format。BYOK 和 Web Search 保持独立。

  • Guided Hotspot Binding is implemented behind a Main-owned capability that is true by default; exact NIANCODE_AI_HARDWARE_GUIDED_HOTSPOT_BINDING=0 disables it, while capability-read failure falls back to direct six-digit Binding. The guided state is process-local, opener failures expose only the same fixed address for manual copy, and Binding conflicts refresh the safe account overview.

  • Robot hotspot scanning and connection are local Main operations that return before Works credentials/upstream access. Renderer may submit only an opaque candidate ID from the latest bounded scan; Main alone filters open printable Xiaozhi-* SSIDs, performs platform association, and verifies the exact current SSID.

  • Hotspot discovery and connection do not authenticate a Robot. BSSID, interface/profile details, native diagnostics, location data, and Wi-Fi credentials never cross the Main boundary; permission or platform failure keeps the system-settings/manual path available.

  • The fixed portal action may open only http://192.168.4.1/ in the system browser and must not acquire cloud credentials or call Works Square. Renderer never supplies a portal URL and never handles Wi-Fi credentials.

  • A successful Binding means account ownership was established; it is not evidence that the Robot is currently online or protocol-ready.

  • 发布只有现有项目配置底部的一个入口，不新增发布工作台、侧栏或资源卡。

  • 创建者发布唯一调用链是 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 不提供类型变更。普通新建流程只要求目录并写入内部默认 interactive_ai_app；不向用户暴露类型、模板或项目 ID 选择。既有 custom 项目继续打开，历史 mini_game / mini_program 在读取边界归一为 interactive_ai_app 且不因读取被改写，缺少类型的旧配置归一为 custom。

  • Main 为新项目自动生成 UUID，并为仅缺 projectId 的有效旧配置串行补齐；原始 ID、绑定/独立副本选择和 initialized gate 不属于普通界面。缺失或无效的其他 metadata 仍进入 Project Configuration。

  • 项目创建只拥有 .makelore/project.json 和 knowledge/。交互式 AI 应用起步树由用户可选地明确调用 Scaffold Skill 生成；Skill 不是创建或进入聊天的前置条件，其发布准备度结论不执行也不替代 Main build/preflight/package/upload 或 Works Square 校验与审核。

  • makelore.data-service、makelore.game-resource 与 makelore.project-scaffold 共用代码所有的项目级激活谓词；满足既有交付/获取条件并由项目启用后，其完整资源进入每个 parent Agent，不读取伙伴分配。Project Scaffold 是 bundled skill_only Marketplace Plugin，其官方 .mjs 只从固定客户端资源根加载；下载 artifact 的扩展名/资产校验没有放宽，仍拒绝 .mjs。

  • 本地 projectType 只选择显式脚手架和内部构建路径，不是可信授权声明；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 Design 的一个 Workspace 公开一个当前 Direction、一个持久 Agent Session 和一个 Current Specification；conversation timeline 是交互历史，不是独立创建或选择的语义权威。

  • Living Form 与 chat、direct edit、decision、proposal、lock、Asset binding、restore 共用同一服务端 reducer。Renderer 草稿在 accepted 前不进入 canonical state。

  • AI Design Renderer 必须把自由描述与 Agent 的自然追问放在主交互面。Specification 投影只复述当前理解并提供默认收起的细节和可选手动调整；普通 Decision Prompt 不得自动渲染成要求青少年逐项完成的表单。

  • Main 通过 design.input.apply、design.quote.request 和 design.generation.confirm 访问 V2。unknown transport result 必须复用原 command/operation identity；结构化业务错误不得重放，未知上游文本不得穿透安全投影。

  • Main-owned Canvas Workspace JSON 请求和 shared Works token refresh 的完整生命周期最多 30 秒，超时 abort transport 并以固定 504 DESIGN_WORKSPACE_REQUEST_TIMEOUT 结束 Renderer 等待。Electron net.fetch 失败后的 Node fetch 透明回退只允许 GET、HEAD、OPTIONS；PATCH/POST 等 mutation 只允许由持有显式幂等身份的上层协议决定重试，不能由底层 transport 隐式重放。该边界不改变上面的 WebSocket→REST 幂等 fallback。

  • Renderer 的异步与流式结果必须核对 Workspace、Direction、revision 和 operation identity；Direction snapshot 是 Specification 真值，Task/Asset 事件只更新 Workspace resource projection。

  • 待提交 chat 可以从现有 pending operation 立即投影为明确标注“发送中/正在确认”的用户气泡，但只有服务端 canonical turn 能进入对话历史；确定失败必须恢复原草稿，不能另建一套消息状态或新业务意图。

  • design.assistant.delta 是未完成的传输状态，不是 canonical assistant turn。Renderer 只能把它临时绘制为与同一 pending chat identity 绑定的单个未完成助手气泡，并在该 operation 确定收敛后由 canonical turn 替换；不得持久化为第二条消息、伪装为已完成回复或创建独立整理进度栏。unknown outcome 保留原 identity 与已有片段，其他 operation 的更新不得全局清除它；中央 active 制作方案继续呈现 Current Specification 的公共投影。重叠连接与重放 chunk 必须按连接 generation 和 chunkIndex 收敛。

  • design.assistant.progress 是与同一 pending chat identity 绑定的瞬时活动投影，可在 optimistic user bubble 下更新和折叠。它只能使用 Main 归一化的固定阶段，不得成为 conversation Turn、中央 active 制作方案中 Current Specification 的副本、通用全局整理栏或 model chain-of-thought；终态事件按原 operation identity 收敛它。

  • 确认生成只提交不可变 Quote ID。Task 事务已提交但事件迟到时可刷新 Workspace projection；Task progress 不得改写 Living Form 或授权新的生成操作。

  • Updater feed 选择、原始错误日志、下载和安装生命周期只属于 Electron Main。Renderer 不得把缺失稳定 manifest 投影为“已是最新版”，也不得显示原始堆栈、URL、路径或错误码；并发检查共享同一错误事件时只发送一次错误状态，后续独立重试仍可重新报告。

  • 图片与视频复用同一个单图来源选择器。图片 Brief 可从当前 Workspace 的已完成作品或本地上传中选择一张参考图继续生成；视频 Brief 使用同一入口绑定首帧。两条路径都必须通过现有 Workspace Asset 上传/选择契约提交一个真实 attachmentAssetIds，不得用本地路径或自然语言描述代替资产身份。

  • Canvas generation confirmation must use the immutable server Quote for the exact current Specification revision. The client confirms only the Quote identity and never edits or derives provider Prompt, model, dimensions, supplier pricing, or Token Point cost.

  • Canvas project deletion is an explicit destructive Workspace mutation guarded by exact project-name confirmation. Renderer clears the deleted Workspace's local state and selects the most recently updated remaining Workspace; upstream hiding, cancellation, reservation release, and settlement remain service-owned behavior.

  • 图片/视频输入以 typed Asset binding 和 Current Specification medium 决定用途，不再从本地化 quick-reply 文案或 V1 Brief 推断行为。

Related Decisions

  • 当前长期边界记录于 README、ADR-002 至 ADR-008（ADR-001 已由 ADR-007 supersede，ADR-005 已由 2026-09-04 Learning 移除决定 supersede）及各 Integration Gate；后续如改变唯一入口、项目创建/Scaffold Skill/发布权威、凭据所有权、构建执行边界、Living Form/Specification 状态归属、Pi 单 runtime/worker/lease 边界、Marketplace/Web Search 分发边界、Robot 配网边界、重新引入 Learning 或重新引入客户端部署协调器，应新增 ADR。

Last Updated

2026-09-15