恢复工作流时只读快照，不再重放已完成步骤的改动

- 检查点每步除记录结果外，再落一份「该步应用完之后」的状态快照，切分那步另带回填出错说明，旧日志无快照仍可解析 - 主流程只应用本次新完成那一步的改动，已完成步骤整步跳过，不再重复登记切图或重复累加回填说明 - 崩溃恢复改为只读检查点里的状态快照并逐级取回，删掉按记录结果重算目标状态的旧实现 - 只有结果、没有状态快照的旧检查点行按未完成处理，由主流程重跑该步 - 漂移与写回幂等判据改为对照快照：状态既不是本轮起点、也不是切分后那份才算漂移；文档已等于切分后快照即视为写回完成 - 同步 ADR、技术方案、代码地图与共享记忆里的检查点口径
2026-09-24 18:16:34 +08:00
parent 62b0f103de
commit 565c2277d5
9 changed files with 352 additions and 95 deletions
@@ -1,17 +1,18 @@
 # UI 工作流检查点用追加式 JSONL 日志

-UI 设计文档的工作流由 Agent 工具驱动、跨多次外部调用，崩溃后需要能续跑。检查点定为**文档旁一条按行追加的 JSONL 日志**：每完成一个步骤追加一行——原始 State 快照、识别 DTO、切分 DTO、回写标记——"某步是否完成"只看日志里有没有对应的行，没有就是没完成，恢复时从第一个缺失的行对应的步骤继续。
+UI 设计文档的工作流由 Agent 工具驱动、跨多次外部调用，崩溃后需要能续跑。检查点定为**文档旁一条按行追加的 JSONL 日志**：每一步做完就追加一行——起始一轮记原始 State 快照，识别与切分各记自己的 DTO **以及该步应用完之后的那份 State 快照**，最后一行是回写标记——"某步是否完成"只看日志里有没有对应的行，没有就是没完成。恢复只做两件事：读回已完成步骤留下的 State 快照，然后从第一个没有快照的步骤继续。

 ## 考虑过的方案

 - 每步一个 sidecar 状态机（步骤状态 + sealedAtRevision + evidence 清单）：要额外维护状态迁移、封条判据和证据校验，等于给每一步发明一套小协议。
 - 把切分专用的 `SeparationState` 泛化成通用检查点：切分需要"每个批次、每个节点"的细粒度恢复语义，其它步骤不需要，泛化会把这份复杂度摊给所有步骤。

-追加式日志只需要"存在即完成"这一条判据，新增步骤类型等于新增一种行，天然可扩展。
+追加式日志只需要"存在即完成"这一条判据，新增步骤类型等于新增一种行，天然可扩展。每步应用完的 State 快照随该步行一同落下，恢复就只是"读回最新快照"，不必再维护一份"照 DTO 重算一遍"的镜像逻辑。

 ## 后果

 - 日志是恢复用的派生信息，不是项目内容：不登记为 manifest 资产，不推进项目 revision。
 - 每行必须一次性原子追加；崩溃时可能留下写了一半的最后一行，未形成完整行的步骤一律视为未完成。
 - 同一份文档可以被多次运行，日志必须能区分轮次：每一轮以一行原始 State 快照开头，该轮的第一行回写标记即为这一轮结束；恢复只针对最后一个没有回写标记的轮次。
+- 恢复只看快照、不重放步骤：已完成步骤在日志里带着"那一步应用完"的 State，恢复直接采纳并整步跳过。若照 DTO 再跑一遍，会重复登记切图、把同一条回填出错原因重复累加。只有带 State 快照的行才算已完成，旧格式（只有 DTO）按未完成重跑。
 - 切分 op 内部的细粒度恢复仍由 `SeparationState` 承担，日志只记录工作流层面的步骤完成，不顺带复制它的进度。
@@ -9279,7 +9279,7 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在

 - 背景：UI 编辑器的 Agent 链路原本只有一个 `ui.workflow.run`，把发现页面、桥接设计图、结构识别、多树合并、组件绑定、finalize 全塞进一个工具，工具参数本身就是工作流状态；识别与切分的产物由前端 `useUiEditorPage.ts` 落 State 再保存，Agent 侧没有任何恢复点，任一步失败只能整轮重来。
 - 决策：拆成三个各自只做一件事的工具——`ui-design-doc.from-images`（一至四张设计图新建并登记文档，返回 `assetId` 与 `relativePath`）、`ui-design-doc.run-workflow`（`recognize → separate → write-back`）、`ui-design-doc.into-js`（渲染 `ui/generated-<stem>-<digest>.js`，不推进 revision）。只有 `run-workflow` 带崩溃恢复，粒度到子步骤。
- 决策（检查点）：恢复判据只有「这一步有没有对应的检查点行」。检查点是文档旁追加式 JSONL `ui/.<文档名>-workflow.jsonl`（不进 manifest、不推进 revision），行类型 `run` / `recognize` / `separate` / `write-back` / `outdated`；一轮以 `run` 开头、以首个 `write-back` 或 `outdated` 结束，只有最后一轮没有结束行时才恢复。追加前截断崩溃留下的半行；文档中途漂移（当前 State 与 `run` 行快照不一致）时追加 `outdated` 并返回错误，由下一次调用显式开新一轮，不在同一次调用里自动重启；写回按「目标 State 与文档当前 State 相等」判幂等并补 `write-back` 行。
+- 决策（检查点）：恢复判据只有「这一步有没有对应、且带着 State 快照的检查点行」。检查点是文档旁追加式 JSONL `ui/.<文档名>-workflow.jsonl`（不进 manifest、不推进 revision），行类型 `run` / `recognize` / `separate` / `write-back` / `outdated`；`run` 行带这一轮开始时的 State 快照，`recognize` / `separate` 行带该步应用完之后的 State 快照。恢复只读快照：逐级取回已完成步骤留下的 State，只把新完成那一步的改动应用到文档，已完成步骤整步跳过、绝不照 DTO 重跑（重跑会重复登记切图、把同一条回填出错原因重复报一遍）。只有 DTO、没有 State 快照的旧行按未完成处理，由主流程重跑该步。一轮以 `run` 开头、以首个 `write-back` 或 `outdated` 结束，只有最后一轮没有结束行时才恢复。追加前截断崩溃留下的半行；文档中途漂移（当前 State 既不是 `run` 行快照、也不是切分后那份快照）时追加 `outdated` 并返回错误，由下一次调用显式开新一轮，不在同一次调用里自动重启；写回按「切分后那份 State 快照与文档当前 State 相等」判幂等并补 `write-back` 行。
 - 决策（边界）：文档内设计图身份直接采用该图在 manifest 里的 `assetId`，输入给相对路径时先登记再用它的 `assetId`；每次调用都新建文档，不做「原型 → 已存在文档」的幂等查找。切图资源失败不回滚，重放靠 by-path 复用接上；切分 op 内部更细粒度的恢复仍由 `SeparationState` sidecar 承担，日志不复制它的进度。前端 `useUiEditorPage.ts` 的人工链路保留同语义，Rust 只是第二份实现，不把编排搬进 Rust。
 - 退役：`ui.workflow.run`、`ui_editor/commands/{merge.rs,binding.rs}`、`ui_editor/workflow.rs`、`ensure_ui_design_resource_for_prototype`、`ui/ui-workflow-<sha256前24>.json` 命名与 `ui-workflow.*` manifest 阶段全部删除，不保留迁移、兼容与 fallback。
 - 代价与取舍：不接受跨语言 fixture 比对（四个 seam 都是简单变换，靠同语义实现与各自单测覆盖）；`run-workflow` 每次调用都推进一轮，调用方重复调用会重新识别而不是被幂等短路（除「保存成功但缺 `write-back` 行」这一种重放）。工具名 `ui-design-doc.*` 含连字符，Function Calling 的函数名归一同时处理 `.` 与 `-`。
@@ -1758,5 +1758,5 @@ Direct 回合的所有权属于进程内项目身份锁，不属于当前页面

 - `ui.workflow.run` 单工具（`discover → prepare → recognize → merge → binding → status → finalize`）整体退役：它的参数就是工作流状态，任一步失败只能整轮重来，步骤产物又由前端会话落盘，Agent 侧没有任何恢复点。同时退役 `merge.rs`、`binding.rs`、`workflow.rs`、`ensure_ui_design_resource_for_prototype`（原型 → 文档的幂等查找）、`ui/ui-workflow-<sha256前24>.json` 命名与 `ui-workflow.*` manifest 阶段，均不保留兼容、迁移或 fallback。
 - 当前只保留三个工具：`ui-design-doc.from-images`（一至四张设计图 → 新建并登记文档，返回 `assetId` 与 `relativePath`，无状态）、`ui-design-doc.run-workflow`（`recognize → separate → write-back`，唯一带崩溃恢复的工具）、`ui-design-doc.into-js`（渲染 `ui/generated-<stem>-<digest>.js`，无状态、不推进 revision）。项目根目录、项目 ID 与 provider 身份由 Runtime 注入，模型只给设计图引用或文档 `assetId`。
- `run-workflow` 的恢复判据只有一条：这一步有没有对应的检查点行。检查点是文档旁追加式 JSONL（`ui/.<文档名>-workflow.jsonl`），行类型为 `run` / `recognize` / `separate` / `write-back` / `outdated`，一轮以 `run` 开头、以首个 `write-back` 或 `outdated` 结束；只有最后一轮没有结束行时才恢复。追加前先截断崩溃留下的半行，文档中途漂移时追加 `outdated` 并返回错误，由下一次调用显式开新一轮，不在同一次调用里自动重启。切图资源失败不回滚，靠 manifest 的 by-path 复用接上；切分 op 内部更细粒度的恢复仍由 `SeparationState` sidecar 承担，检查点日志不复制它的进度。
+- `run-workflow` 的恢复判据只有一条：这一步有没有对应、且带着 State 快照的检查点行。检查点是文档旁追加式 JSONL（`ui/.<文档名>-workflow.jsonl`），行类型为 `run` / `recognize` / `separate` / `write-back` / `outdated`，`run` 行带本轮起始 State，`recognize` / `separate` 行带该步应用完之后的 State。恢复只读快照、整步跳过已完成步骤，只把新完成那一步的改动应用到文档，绝不照 DTO 重放（重放会重复登记切图、重复累加回填出错说明）；只有 DTO 的旧行按未完成重跑。一轮以 `run` 开头、以首个 `write-back` 或 `outdated` 结束；只有最后一轮没有结束行时才恢复。追加前先截断崩溃留下的半行，文档中途漂移（当前 State 既不是 `run` 行快照、也不是切分后那份快照）时追加 `outdated` 并返回错误，由下一次调用显式开新一轮，不在同一次调用里自动重启。切图资源失败不回滚，靠 manifest 的 by-path 复用接上；切分 op 内部更细粒度的恢复仍由 `SeparationState` sidecar 承担，检查点日志不复制它的进度。
 - 三个工具的描述与参数文案都在 `prompts/runtime/texts/ui-design-doc.json`（目录 ID `uiDesignDoc`），Rust 侧不得硬编码面向模型的长文案。策划 `design-foundation` 的自主构建白名单同步登记这三个工具，命令映射复用 `asset.register` / `file.write`。
@@ -48,12 +48,13 @@
 检查点是文档旁一条追加式 JSONL 日志，方案与被否方案见 [ADR：UI 工作流检查点用追加式 JSONL 日志](../adr/【ADR】UI工作流检查点用追加式JSONL日志-2026-09-23.md)。

 - 位置：`ui/.<文档文件名去扩展名>-workflow.jsonl`，与文档同级，不进 manifest、不推进项目 revision。
- 行格式：`run`（原始 State 快照 + 起始 revision）、`recognize`（DTO）、`separate`（DTO）、`write-back`（新 revision）、`outdated`（本轮作废原因）；行内另带 `at` 时间戳。
+- 行格式：`run`（原始 State 快照 + 起始 revision）、`recognize`（DTO + 该步应用完的 State 快照）、`separate`（DTO + 该步应用完的 State 快照 + 回填说明）、`write-back`（新 revision）、`outdated`（本轮作废原因）；行内另带 `at` 时间戳。
 - 判据只有一条：「本步有没有对应的行」。每行必须一次性原子追加，崩溃留下的半行一律视为该步未完成。
+- 恢复只看快照、不重放步骤：已完成的步骤在检查点里带着那一步应用完之后的 State 快照，恢复时直接读回这份 State 并整步跳过，不按记录下来的 DTO 重放该步 delta——重放会重复登记切图、重复累加回填说明，把同一份错误报两遍。只有带状态快照的行才算已完成，旧格式（只有 DTO）的行按未完成重跑。
 - 轮次：一轮以 `run` 行开头，以该轮第一行 `write-back` 或 `outdated` 结束；只有最后一轮没有结束行时才需要恢复。`outdated` 只作废未完成的那一轮，不删除既有行。
 - 半行：追加前先把日志截断到最后一个换行，丢掉崩溃留下的半行，避免它夹在日志中间。
- 漂移：文档在轮次中途被改动（当前 State 与 `run` 行快照不一致）时，追加一行 `outdated` 并**返回错误**，不在同一次调用里自动重开新一轮；下一次调用看到 `outdated` 才从头开新一轮，且以当前文档为基准。
- 写回幂等：`save` 成功但 `write-back` 行没追加时，重放会重建出同一份目标 State，此时按「目标 State 与文档当前 State 相等」判定为已写完，直接补 `write-back` 行并返回成功。这条判据成立的前提是工作流这条路不产生随机身份：识别树的根节点 id 来自 DTO，切图资源 id 走 manifest 的 by-path 复用。
+- 漂移：文档在轮次中途被改动（当前 State 既不是 `run` 行快照、也不是切分后那份快照）时，追加一行 `outdated` 并**返回错误**，不在同一次调用里自动重开新一轮；下一次调用看到 `outdated` 才从头开新一轮，且以当前文档为基准。
+- 写回幂等：`save` 成功但 `write-back` 行没追加时，恢复读回的切分后 State 与文档当前 State 相等，即判为已写完，直接补 `write-back` 行并返回成功。这条判据成立的前提是工作流这条路不产生随机身份：识别树的根节点 id 来自 DTO，切图资源 id 走 manifest 的 by-path 复用。
 - 切图资源不回滚：切分产出的图片与已登记资源在失败后保留，重放靠 by-path 复用接上，不做回滚清理。
 - 写回成功后才清理 sidecar：与前端切分链路一致，`backfill_errors` 为空且 `problematic_nodes` 为空时调用
  `finalize_separation`；有回填问题或问题节点时保留 sidecar，交给编辑器显示恢复入口。
@@ -71,7 +72,7 @@ src/ui_editor/agent_tools/
 ├─ checkpoint.rs      JSONL 追加、读取、轮次判定
 ├─ run_workflow.rs    recognize → separate → write-back 编排与恢复
 ├─ steps/
-│  ├─ mod.rs          用已记录 DTO 重放目标 State
+│  ├─ mod.rs          步骤子模块声明
 │  ├─ recognize.rs    识别 DTO 落 State
 │  ├─ separate/
 │  │  ├─ mod.rs       切分 DTO 落 State（回填、清状态、写 NeedReview）
@@ -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、树/资源引用、组件状态）、代码生成写盘 |
-| `agent_tools/` | Agent 工具链路：`creation.rs` 用一至四张设计图新建文档（登记未登记图片、按 `ui/UI 设计 N.json` 取号、持项目写锁装 revision 0、失败回滚）、`checkpoint.rs` JSONL 检查点日志、`run_workflow.rs` 三步编排与崩溃恢复、`steps/` 逐步落 State（`mod.rs` 用已记录 DTO 重放目标 State、`recognize.rs` 识别、`separate/` 切分：`cut_images.rs` 登记切图与 `SpriteAsset` 构造、`mod.rs` 回填与问题状态、`write_back.rs` 保存与漂移文案） |
+| `agent_tools/` | Agent 工具链路：`creation.rs` 用一至四张设计图新建文档（登记未登记图片、按 `ui/UI 设计 N.json` 取号、持项目写锁装 revision 0、失败回滚）、`checkpoint.rs` JSONL 检查点日志、`run_workflow.rs` 三步编排与崩溃恢复（恢复只读检查点里的 State 快照、整步跳过已完成步骤，不按 DTO 重放）、`steps/` 逐步落 State（`mod.rs` 步骤子模块声明、`recognize.rs` 识别、`separate/` 切分：`cut_images.rs` 登记切图与 `SpriteAsset` 构造、`mod.rs` 回填与问题状态、`write_back.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 回写 |