更新UI编辑器深模块架构文档

记录状态迁移、几何、不变量与操作生命周期 seam 同步结构化 LLM 适配器边界与验证结果
2026-09-18 10:24:03 +08:00
parent d986dbaeb0
commit 55a8513de4
2 changed files with 11 additions and 0 deletions
@@ -8769,3 +8769,10 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在

 - 决策：采用后台继续运行语义。Direct 回合由进程内项目身份锁持有，页面离开不取消；重进项目通过活动回合只读快照与 Thread Manager bootstrap/consume 恢复忙碌态和进度。左上角面板复用同一快照列出正在运行的 Direct 项目并支持进入。
 - 边界：快照不写项目文件、不进入公共 API、不跨应用重启恢复；读取失败保留上一份结果并单独提示，不改写成权限或审批失败。身份锁排他性、付费身份和项目写锁不变。
+
+## 2026-09-18 UI 编辑器深模块 seam 收敛
+
+- 决策：UI 编辑器的语义状态写入通过 React-free `stateTransition` seam；页面 hook 继续负责 React/history/lock adapter。保存前增加 `stateInvariants` projection，Rust 持久化规则仍是最终权威。
+- 决策：节点几何新增 State 级 `findStateNodePageContext`，页面选择、预览和状态迁移共享同一坐标递归入口；四类异步操作的 running/status 由 `operationLifecycle` adapter 承接。
+- 决策：结构化 LLM action 共用 `commands::utils::required_tool_arguments`，仅统一必需 tool-call 定位与有界 JSON 解析，不合并 prompt、schema 或 materializer。
+- 验证：AGC typecheck、UI State 定向 Vitest、编码检查、doc-index、diff 检查和 Tauri Rust fmt 通过；Tauri 全量 cargo check 仍受现有 platform-llm API 漂移错误阻断，与本次 UI editor 改动无关。
@@ -4,6 +4,8 @@

 `apps/ai-game-creator-shell` 的 UI 编辑器以 `useUiEditorSession` 作为视图与 adapter 的唯一协调边界。会话持有资源加载、revision、预览请求、选择、节点可见性、步骤 gate、异步操作和保存意图；`UiDesignStateStore` 与 Tauri 调用仍由该模块注入，不进入视图组件。

+实现层的深模块 seam 固定为：`features/ui-editor/stateTransition.ts`（React-free 语义 State transition）、`stateInvariants.ts`（保存前不变量 projection）、`nodeTransformGeometry.ts`（State 级节点几何）以及 `view/ui-editor/operationLifecycle.ts`（异步操作 adapter）。`useUiEditorState` 和 `useUiEditorSession` 只负责 React/history/lock 与平台 adapter 编排，不在视图中复制树遍历或几何反演。
+
 页面与子视图不得再传递完整 controller。它们按职责读取以下小 projection：

 - `input`：资源输入、节点树及调试操作。
@@ -19,6 +21,8 @@

 保存与代码生成共享同一份持久化 State/revision。会话层在保存或生成进行期间互斥拦截，且代码生成必须基于已加载的持久化 revision；视图层的保存按钮和“保存并返回”按钮同步遵守该互斥状态。

+Rust UI workflow 的结构化 LLM 动作共享 `commands::utils::required_tool_arguments` seam：它只负责必需 tool-call 定位与有界 JSON 解析；prompt、schema、领域校验和 materializer 继续留在 suggestion/recognition/binding/merge 各自 command。
+
 UI 编辑器的普通“保存”和“保存并生成代码”结果使用独立结果弹窗呈现，不在编辑器内容区追加状态条。普通保存成功仅提示保存成功；保存并生成成功展示生成器返回的项目相对路径（例如 `ui/generated-xxx.js`），复制按钮通过 Tauri clipboard manager 的 `writeText` 写入剪贴板。复制失败时保留可选中文本并提示手动复制；设置用户 fallback 后仍必须重新抛出原始错误，让 error report 链路收到未知 / 未处理的异常，不能把异常静默吞掉。此异常传播原则适用于所有 JS 边界，不限于生成路径或剪贴板。两类操作失败均在弹窗中展示；组合操作若保存成功但生成失败，明确提示项目已保存，重试动作仍复用原操作。保存并返回成功后直接返回，不打开结果弹窗；结果弹窗关闭后不保留路径状态。

 ## 2026-09-14 多树预览与树级偏移