将 design_doc 的切分模块提升为目录模块

把 steps/separate.rs 提升为 steps/separate/mod.rs，只保留纯 State 变换把 design_doc/cut_images.rs 移到 steps/separate/cut_images.rs，与它服务的切分步骤同层把 normalize_cut_image_path 从 steps/mod.rs 下沉到 steps/separate/mod.rs，紧邻两个使用点 run_workflow.rs 改从 steps::separate 统一导入切分入口与登记入口同步两份 UI 编辑器技术方案的模块布局与代码地图
2026-09-24 13:05:44 +08:00
parent fbb161b33e
commit 6ef64c3bcf
7 changed files with 27 additions and 21 deletions
@@ -1,6 +1,5 @@
 mod checkpoint;
 mod creation;
-mod cut_images;
 mod run_workflow;
 mod steps;

@@ -9,9 +9,8 @@ use super::checkpoint::{
    checkpoint_timestamp, CheckpointDocument, CheckpointLine, RoundOutcome, WorkflowLog,
    WorkflowRound,
 };
-use super::cut_images::register_cut_image_sprites;
 use super::steps::recognize::apply_recognition;
-use super::steps::separate::{add_sprite_assets, apply_separation};
+use super::steps::separate::{add_sprite_assets, apply_separation, register_cut_image_sprites};
 use crate::enforce_project_permission_policy;
 use crate::ui_editor::commands::separation::finalize_separation;
 use crate::ui_editor::commands::{
@@ -1,7 +1,2 @@
 pub(crate) mod recognize;
 pub(crate) mod separate;
-
-/// 镜像前端 `normalizeProjectRelativePath`：只做分隔符与根斜杠归一，不做路径校验。
-pub(crate) fn normalize_cut_image_path(path: &str) -> String {
-    path.replace('\\', "/").trim_start_matches('/').to_string()
-}
@@ -1,10 +1,11 @@
-//! 登记自动切分产出的图片并构造切分素材。镜像前端 `useUiEditorPage.ts` 的
-//! `import_local_project_image_assets` → `prepareSpriteAssetBatch` 两段。
+//! `separate` sub-step 的资源侧：登记自动切分产出的图片并构造切分素材。镜像前端
+//! `useUiEditorPage.ts` 的 `import_local_project_image_assets` →
+//! `prepareSpriteAssetBatch` 两段。
 //!
 //! 登记按路径复用已有 manifest 条目，所以重放不会重复登记；登记失败的路径只回报
 //! 说明，不回滚已经登记成功的资源。

-use super::steps::normalize_cut_image_path;
+use super::normalize_cut_image_path;
 use crate::import_local_project_assets_for_agent;
 use crate::ui_editor::commands::SeparationDTO;
 use crate::ui_editor::resource::sprite::SpriteAsset;
@@ -1,9 +1,15 @@
-//! 自动切分结果落到 State。镜像前端 `useUiEditorPage.ts` 的切分回填循环、
-//! `features/ui-editor/useUiEditorState.ts` 的 `addSpriteAssetsToState` 与
-//! `features/ui-editor/separationStatus.ts` 的问题状态写回。
+//! `separate` sub-step 的全部落地逻辑，按有无副作用分两个文件：
 //!
-//! 切分图片的登记不是这里的事：调用方先按 `bound_nodes` 的路径登记资源并构造
-//! `SpriteAsset`，本模块只做纯 State 变换。
+//! - `cut_images`：按 `bound_nodes` 的路径登记图片并构造 `SpriteAsset`，带项目
+//!   manifest 副作用。
+//! - 本文件：登记结果与 `SeparationDTO` 到 State 的纯变换，镜像前端
+//!   `useUiEditorPage.ts` 的切分回填循环、`features/ui-editor/useUiEditorState.ts`
+//!   的 `addSpriteAssetsToState` 与 `features/ui-editor/separationStatus.ts` 的问题
+//!   状态写回。
+
+mod cut_images;
+
+pub(crate) use cut_images::{register_cut_image_sprites, CutImageSprites};

 use crate::ui_editor::commands::separation::{BoundNode, ProblematicNode};
 use crate::ui_editor::commands::SeparationDTO;
@@ -14,6 +20,11 @@ use crate::ui_editor::state::State;
 use crate::ui_editor::utils::SpriteAssetId;
 use std::collections::HashMap;

+/// 镜像前端 `normalizeProjectRelativePath`：只做分隔符与根斜杠归一，不做路径校验。
+pub(crate) fn normalize_cut_image_path(path: &str) -> String {
+    path.replace('\\', "/").trim_start_matches('/').to_string()
+}
+
 /// 把切分产出的素材合入 State。同一 id 已有不同内容时报错，镜像
 /// `addSpriteAssetsToState` 的 `duplicate` 与资源校验。
 pub(crate) fn add_sprite_assets(state: &State, sprites: &[SpriteAsset]) -> Result<State, String> {
@@ -121,7 +132,7 @@ fn backfill_bound_node(
    sprite_by_path: &HashMap<String, SpriteAsset>,
    errors: &mut Vec<String>,
 ) {
-    let path = super::normalize_cut_image_path(&bound.cut_image_path);
+    let path = normalize_cut_image_path(&bound.cut_image_path);
    let Some(sprite) = sprite_by_path.get(&path) else {
        errors.push(format!(
            "节点 {} 缺少已登记的自动切分素材图片：{path}",
@@ -69,11 +69,12 @@ src/ui_editor/design_doc/
 ├─ mod.rs             模块声明与三个工具的对外导出
 ├─ creation.rs        from-images：登记图片、建文档、manifest 注册、命名取号
 ├─ checkpoint.rs      JSONL 追加、读取、轮次判定
-├─ cut_images.rs      切图图片登记与 SpriteAsset 构造
 ├─ run_workflow.rs    recognize → separate → write-back 编排与恢复
 ├─ steps/
 │  ├─ recognize.rs    识别 DTO 落 State
-│  └─ separate.rs     切分 DTO 落 State（回填、清状态、写 NeedReview）
+│  └─ separate/
+│     ├─ mod.rs       切分 DTO 落 State（回填、清状态、写 NeedReview）
+│     └─ cut_images.rs 切图图片登记与 SpriteAsset 构造
 └─ test_support.rs    design_doc 单测共用夹具
 src/agent/runtime_tools/ui_design_doc.rs   工具参数解析与 Runtime 侧调用
 ```
@@ -97,7 +98,7 @@ src/agent/runtime_tools/ui_design_doc.rs   工具参数解析与 Runtime 侧调
 2. 术语与 ADR：`CONTEXT.md` 四个词条、检查点 ADR。
 3. 本文档。
 4. 提示词目录模块 + 两个无状态工具（`from-images`、`into-js`）。
-5. `run-workflow` 与 JSONL 检查点（`design_doc/{checkpoint,cut_images,run_workflow}.rs` + `steps/`）。
+5. `run-workflow` 与 JSONL 检查点（`design_doc/{checkpoint,run_workflow}.rs` + `steps/separate/`）。
 6. 前端收口：删 `uiDesignResourceBridge` 的 `ui-workflow.*` 优先级与 `project-development` 的自动打开分支。
 7. 三个工具注册进 Runtime（`agent_native_tools`、`runtime_tools/ui_design_doc.rs`、可执行工具目录、并行账本映射、design-foundation 白名单）。

@@ -27,7 +27,7 @@ view/ui-editor (页面/组件)
 | `component/` | 组件枚举 `Component::{Image, Text}`、`NodeComponent`（LLM 工具载荷的 `PureNode`/`WithComponent` 判别式） |
 | `resource/` | 界面图（`path` / `pixel_size` / `pixels_per_unit`）、sprite（含 `SpriteBorder` 九宫格）、字体（格式/媒体类型/CSS format）资源描述 |
 | `persistence.rs` | 文档读写、`revision` 乐观并发保存、领域校验（重复 ID、树/资源引用、组件状态）、代码生成写盘 |
-| `design_doc/` | Agent 工具链路：`creation.rs` 用一至四张设计图新建文档（登记未登记图片、按 `ui/UI 设计 N.json` 取号、持项目写锁装 revision 0、失败回滚）、`checkpoint.rs` JSONL 检查点日志、`cut_images.rs` 切图登记与 `SpriteAsset` 构造、`run_workflow.rs` 三步编排与崩溃恢复、`steps/` 纯 State 镜像步骤 |
+| `design_doc/` | Agent 工具链路：`creation.rs` 用一至四张设计图新建文档（登记未登记图片、按 `ui/UI 设计 N.json` 取号、持项目写锁装 revision 0、失败回滚）、`checkpoint.rs` JSONL 检查点日志、`run_workflow.rs` 三步编排与崩溃恢复、`steps/` 逐步落 State（`recognize.rs` 识别、`separate/` 切分：`cut_images.rs` 登记切图与 `SpriteAsset` 构造、`mod.rs` 回填与问题状态） |
 | `html_renderer/` | 由 State 生成 HTML 片段与 JS（maud + 布局/组件 CSS 映射），供预览与 `ui/generated-*.js` |
 | `commands/` | LLM 工具链：`recognition`（结构识别）、`separation/`（自动切分素材）、`utils.rs`（LLM 请求、重试、`required_tool_arguments`） |
 | `commands/separation/` | 切分批处理、截图/预切、sidecar 恢复（inspect / finalize / discard）、patch 回写 |