diff --git a/docs/README.md b/docs/README.md index 4ecca9b6f..292145459 100644 --- a/docs/README.md +++ b/docs/README.md @@ -62,7 +62,6 @@ - [AGC 资源派生与非破坏性编辑合同](./technical/【技术方案】AGC资源派生与非破坏性编辑合同-2026-09-09.md)：AGC 全类型现有资源非破坏性编辑的权威合同，约束资源派生、替换与写回边界。 - [AGC 聊天素材引用](./【功能说明】AGC聊天素材引用-2026-09-08.md)：聊天输入框 @ 引用项目素材的入口、引用模型与「当前版本素材」口径。 - [AGC 聊天 AI 润色与发送前提醒](./【功能说明】AGC聊天AI润色与发送前提醒-2026-09-10.md)：提示词润色与发送前提醒的交互、失败与取消口径。 -- [UI 工作流资源桥接与 Runtime 执行](./【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md) - [UI 编辑器代码地图与模块职责](./technical/【技术方案】UI编辑器代码地图与模块职责-2026-09-23.md)：Rust `ui_editor` 模块、`features/ui-editor` 语义层与 `view/ui-editor` 视图层的职责划分与扩展指引。 - [UI 编辑器 Agent 工具化重写](./technical/【技术方案】UI编辑器Agent工具化重写-2026-09-23.md)：三个工具（建文档 / 跑工作流 / 出 JS）的契约、两步工作流、JSONL 检查点与模块布局。 - [UI 编辑器 Godot 容器布局](./technical/【技术方案】UI编辑器Godot容器布局模型-2026-08-18.md) diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index 291db67d1..373fb830d 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -9337,3 +9337,13 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在 - 代价与取舍：删掉 `name` / `description` 后界面图在 UI 上只能用文件名标识；合并冲突的代表节点选择不再有“优先级”依据；`role` / `slave_to` 曾承担的“主页面 + 子界面”语义彻底消失。旧 `ui_design.json` 里的 `metadata` 由 serde 默认忽略、下次保存后自然消失（`State` / `UIDesignImage` 都没有 `deny_unknown_fields`），已生成的 `ui_trees` 不受影响。 - 影响面：`apps/ai-game-creator-shell/src-tauri/src/{main.rs,ui_editor/**}`、`src/features/ui-editor/**`、`src/view/ui-editor/**`、`src/view/project-development/index.tsx`、`tests/{uiEditorPage,uiEditorState,previewWorkspaceZoom}.test.*`、`docs/technical/【技术方案】UI编辑器代码地图与模块职责-2026-09-23.md`、`docs/【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md`、`docs/technical/【设计】UI编辑器工作流完成通知弹窗-2026-09-04.md`、`docs/technical/【前端架构】UI编辑会话模块边界-2026-08-19.md`。 - 验证：`cargo check` 与 `cargo test --bin genarrative-ai-game-creator-shell ui_editor`（160 passed）通过，ts-rs 重新导出 `types/UIDesignImage.ts` 并删除三个已退役类型；`npx vitest run` 定向 `uiEditorPage` / `uiEditorState` / `uiDesignStateStore` / `previewWorkspaceZoom` / `appSurface` 全绿；AGC `tsc --noEmit`、改动文件 eslint、`cargo fmt --check`、`check:encoding`、`git diff --check` 通过。整套 Rust 测试在本容器仍有 60 条环境性失败（`/sbin -> usr/bin` 让 `command.exec` 沙箱 merged-usr 预检失败），与本次改动无关。 + +## 2026-09-23 UI 编辑器 Agent 工具化重写 + +- 背景：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--.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` 行。 +- 决策（边界）：文档内设计图身份直接采用该图在 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-.json` 命名与 `ui-workflow.*` manifest 阶段全部删除，不保留迁移、兼容与 fallback。 +- 代价与取舍：不接受跨语言 fixture 比对（四个 seam 都是简单变换，靠同语义实现与各自单测覆盖）；`run-workflow` 每次调用都推进一轮，调用方重复调用会重新识别而不是被幂等短路（除「保存成功但缺 `write-back` 行」这一种重放）。工具名 `ui-design-doc.*` 含连字符，Function Calling 的函数名归一同时处理 `.` 与 `-`。 +- 验证方式：`cargo test --bin genarrative-ai-game-creator-shell design_doc` 覆盖检查点、识别/切分镜像与切图登记；`ui_design_doc` 与 `native_ui_design_doc_tools` 用例覆盖工具入参和函数名；`npm run check:encoding`、`npm run check:doc-index`、`git diff --check` 通过。整套 Rust 用例在本容器仍有 9 条既有环境性失败（本地 HTTP 资源编辑器与 LLM 超时，改动前同样失败）。 diff --git a/docs/project-memory/shared-memory/project-overview.md b/docs/project-memory/shared-memory/project-overview.md index 2729c69de..54f3fbaba 100644 --- a/docs/project-memory/shared-memory/project-overview.md +++ b/docs/project-memory/shared-memory/project-overview.md @@ -67,7 +67,7 @@ SpacetimeDB crate、SDK、CLI / standalone 与生成 bindings 按 `2.8.3` 对齐 - 2026-09-09 起，AGC 已新增遵循 OpenAI Agent Plugins 组合模型的通用 Plugin Host/SDK：Plugin、Skill 和 MCP 进入统一扩展 catalog；插件生命周期、行分隔 JSON-RPC、UI 面板、Capability Registry、权限和审计由 `plugin_host` 统一承接，Skill/MCP 仍分别交给各自现有 loader/transport；目标编辑器只通过通用 `EditorAdapter` 扩展点接入。详见 `docs/technical/【技术方案】AGC通用插件宿主与编辑器适配-2026-09-09.md`。 - Unity 编辑器能力以 `plugins/agc-unity-editor` 内置插件提供，固定复用 Apache-2.0 的 DotCraft Attach 核心；Windows x64 / Unity Mono 接入不安装项目包。GUI、Runtime 与 DirectProject 通过现有 Runner 统一执行归属，跨进程回执与持久不确定阻断统一处理。首次打开 Unity 工程只初始化 AGC `.agent` 元数据，保留原引擎工程；详见 `docs/technical/【技术方案】AGC Unity编辑器插件接入-2026-09-18.md`。 - DirectProject 的 Codex 原生文件、搜索、命令、图片查看和 Skill 仅在用户项目 cwd 与 `workspaceWrite(writableRoots=[project])` 内可用；原生命令允许联网以支持 npm 安装，npm 缓存位于项目内 `.npm-cache/`。多 Agent、Apps、插件、hooks、图片生成、Goals、Workspace Dependencies、Tool Suggestion 和原生浏览器/电脑控制保持关闭。app-server 使用隔离 `CODEX_HOME`，provider 凭据只由 AGC 客户端代理持有，不能进入模型上下文或 shell 环境。 -- `ui-prototype`（设计图片）与 UI 编辑器 `UI` JSON 是不同资源。白名单 `ui.workflow.run` 按页面执行 `prepare → recognize → status → finalize`，由 provider-backed 识别、合并和组件绑定持久化 State/revision，并把 `reference-ready → structure-ready → merge-ready → binding-ready → application-ready → completed` 投影到 manifest。Provider 缺失、请求失败、工具缺失、结果不匹配或仍有待审节点时保留真实阶段并返回 blocker，不得用 deterministic seed 伪造完成。 +- `ui-prototype`（设计图片）与 UI 编辑器 `ui-design-doc` JSON 是不同资源。Agent 只通过三个工具驱动：`ui-design-doc.from-images` 由一至四张已登记设计图新建并登记文档（文档内设计图身份即图片 assetId），`ui-design-doc.run-workflow` 在 Rust 内跑 `recognize → separate → write-back` 并写回 State/revision，`ui-design-doc.into-js` 产出 `ui/generated-*.js`（不推进 revision）；工具名与入参文案在 `prompts/runtime/texts/ui-design-doc.json`。Provider 缺失、请求失败、工具缺失或结果不匹配时保留真实 State 并返回错误，不得用 deterministic seed 伪造完成；旧 `ui.workflow.run`、多树合并、组件绑定与原型幂等桥接已退役，不保留兼容入口。 - UI workflow 的资源桥接与 Runtime 边界以 `docs/【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md` 和 AGC 实施计划的 2026-08-24 覆盖段为准；只生成图片、登记空 JSON 或进入普通图片画布都不构成 workflow 完成。 ## 退役边界 diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md index a77227485..f2d860ef1 100644 --- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md +++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md @@ -1859,3 +1859,10 @@ Direct 回合的所有权属于进程内项目身份锁，不属于当前页面 `AgentRuntimeErrorEvent` 把失败投影到用户消息、运行面板和项目内 `.agent/runtime/errors/.json` 时，同一份已脱敏诊断还要投影成 AppData `diagnostics/application.log` 的两行：`agent.runtime.error`（身份行：`eventId / source / stage / code / retryable / clientTurnId / elapsedMs / detailRef`）与 `agent.runtime.error.detail`（详情行：`hint / summary / detail / metadata`）。原因是项目内 sidecar 只在项目目录可见，而“报告问题”只上传应用级日志：没有这两行时，用户提交的失败消息里只剩一个 `详情：.agent/runtime/errors/...json` 路径，团队拿不到诊断正文。 口径：两行都由 `agent/runtime_error.rs` 从同一份 diagnosis 生成，字段不退化成第二份来源；`summary` 按 320 字符、`detail` 与 `metadata` 按（1200 / 200 字符）预算先脱敏再截断，落盘前还会被 `sanitize_diagnostic_message` 二次脱敏并按行截断，因此自由文本字段在行内先压平换行。拆两行是因为整行一旦出现凭据标记会被整体替换成脱敏占位：所以**自由文本（summary / hint / detail）只放详情行**，身份行只留程序生成与调用方常量字段，详情行被整体脱敏时事件仍能按 eventId / detailRef 定位。写日志先于写 sidecar：sidecar 失败不能连日志一起丢。 + +## 2026-09-23 AGC UI 设计文档 Agent 工具化重写 + +- `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-.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--.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 承担，检查点日志不复制它的进度。 +- 三个工具的描述与参数文案都在 `prompts/runtime/texts/ui-design-doc.json`（目录 ID `uiDesignDoc`），Rust 侧不得硬编码面向模型的长文案。策划 `design-foundation` 的自主构建白名单同步登记这三个工具，命令映射复用 `asset.register` / `file.write`。 diff --git a/docs/technical/【技术方案】UI编辑器代码地图与模块职责-2026-09-23.md b/docs/technical/【技术方案】UI编辑器代码地图与模块职责-2026-09-23.md index eae334588..8373cd104 100644 --- a/docs/technical/【技术方案】UI编辑器代码地图与模块职责-2026-09-23.md +++ b/docs/technical/【技术方案】UI编辑器代码地图与模块职责-2026-09-23.md @@ -27,11 +27,13 @@ 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/` | UI 设计文档入口：`creation.rs` 用一至四张设计图新建文档（登记未登记图片、按 `ui/UI 设计 N.json` 取号、持项目写锁装 revision 0、失败回滚） | +| `design_doc/` | Agent 工具链路：`creation.rs` 用一至四张设计图新建文档（登记未登记图片、按 `ui/UI 设计 N.json` 取号、持项目写锁装 revision 0、失败回滚）、`checkpoint.rs` JSONL 检查点日志、`cut_images.rs` 切图登记与 `SpriteAsset` 构造、`run_workflow.rs` 三步编排与崩溃恢复、`steps/` 纯 State 镜像步骤 | | `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 回写 | +Agent 工具（`agent_native_tools.rs` + `agent/runtime_tools/ui_design_doc.rs`）：`ui-design-doc.from-images` 新建文档并登记；`ui-design-doc.run-workflow` 在 Rust 内跑 `recognize → separate → write-back`，按文档旁 JSONL 检查点恢复；`ui-design-doc.into-js` 复用 `generate_ui_design_code_at` 产出 `ui/generated-*.js`，不推进 revision。旧 `ui.workflow.run` 与 `ensure_ui_design_resource_for_prototype` 已退役。 + 关键命令（`main.rs` 注册）：`load_ui_design_state`、`save_ui_design_state`、`generate_ui_design_code`、`create_ui_design_doc_from_images`、`recognize_ui`、`separate_ui`、`inspect_separation_recovery`、`finalize_separation`、`discard_separation_recovery`。 保存语义（`save_ui_design_state_at`）：`Saved` / `Unchanged` / `Conflict`（返回当前快照）三态；先 `validate_state` 再持锁重读比对 `expected_revision`，成功后推进项目 revision。代码生成只接受已保存的 revision，产物路径为 `ui/generated--.js`。 diff --git a/docs/【协作规范】文档生命周期与现状索引-2026-09-12.md b/docs/【协作规范】文档生命周期与现状索引-2026-09-12.md index ec52ae65f..6dab86572 100644 --- a/docs/【协作规范】文档生命周期与现状索引-2026-09-12.md +++ b/docs/【协作规范】文档生命周期与现状索引-2026-09-12.md @@ -62,6 +62,7 @@ - `docs/technical/【技术方案】AI游戏创作Agent Runtime V1.1-2026-07-12.md` - `docs/technical/【技术说明】AGC接第三方Provider的兼容性缺陷-2026-08-19.md` - `docs/technical/【测试用例】AIWeb工程静态预览MVP验收清单-2026-06-13.md` +- `docs/【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md` 这些文件保留用于追溯；若其中仍有有效结论，应先融合到当前专题，再删除重复表述。 diff --git a/docs/【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md b/docs/【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md index 3719b6ec0..1aa5fcaaf 100644 --- a/docs/【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md +++ b/docs/【技术方案】UI工作流资源桥接与Runtime执行-2026-08-24.md @@ -1,4 +1,9 @@ # UI 工作流资源桥接与 Runtime 执行 +> 文档状态：`historical` +本方案描述的 `ui.workflow.run` 单工具、`discover → prepare → recognize → merge → binding → status → finalize` 阶段、 +`ensure_ui_design_resource_for_prototype` 幂等桥接与 `.agent/ui-workflows/.json` 回执均已退役， +仅用于追溯。当前 Agent 链路见 [`【技术方案】UI编辑器Agent工具化重写-2026-09-23.md`](./technical/【技术方案】UI编辑器Agent工具化重写-2026-09-23.md)： +三个工具分别为 `ui-design-doc.from-images`、`ui-design-doc.run-workflow`、`ui-design-doc.into-js`。 ## 目标