Editor agent refactored (#76)

重构了editor agent.
使得它能进行多轮工具调用， 把工具调用的结果嵌入到上下文里。
对于上下文的图片， 使用哈希后的id用来引用，不暴露细节信息to llm。
当前实现， 状态直接维护在json doc里， 需要对整个doc加锁，任务目前只能串行。
把SSE改成一个简单请求（ 因为生图工具耗时需要二次确认， 不需要再实时展示给用户进度）。
增加确认/取消生图操作。
把tool的参数和错误情况做了反馈。

TODO：  工具调用的规范/prompt还可以改进。

改用external job来做素材生成， 针对来自editor agent 的生成会把生成资产的引用加入到结果json里，
客户端轮询 external job 确定生成状态， 发现结束了或者失败了就 重新get 会话，后端重新提供会话的时候把 结果插入回会话历史里，用来让 ai 引用 以及显示

---------

Co-authored-by: 段舒康 <kdletters@qq.com>
Reviewed-on: https://git.genarrative.world/git/GenarrativeAI/Genarrative/pulls/76
Reviewed-by: 段舒康 <kdletters@qq.com>
Co-authored-by: 王德宇 <kvtodev@outlook.com>
Co-committed-by: 王德宇 <kvtodev@outlook.com>

docs/adr/【ADR】画布Agent会话消息存OSS-2026-07-03.md

@@ -4,7 +4,7 @@
 
 ## 背景
 
-画布Agent对话需要保存历史记录并支持新开会话。消息正文是流式追加、体量随对话增长的 JSON 数据；SpacetimeDB 是后端唯一结构化真相存储，但表行不适合承载不断增长的长文本；画布工程快照已有独立保存链路，且对话流式更新频率远高于布局保存。
+画布Agent对话需要保存历史记录并支持新开会话。消息正文会随对话和工具结果持续增长；SpacetimeDB 是后端唯一结构化真相存储，但表行不适合承载不断增长的长文本；画布工程快照已有独立保存链路，对话消息也不应与布局保存互相竞争。
 
 ## 决策
 
@@ -14,7 +14,7 @@
 - 浏览器禁止直接上传、覆盖或签名写入 `editor-agent/` 对象；前端只通过 `api-server` 的会话接口创建会话、发送消息、读取历史，OSS 读写由服务端完成。
 - 消息文档序列化后的读写上限为 2 MiB；超过上限时后端拒绝继续读写该会话消息文档，并返回 payload too large 语义错误。
 - 同一会话内的消息追加采用 `conversationId` 级串行锁，避免同一会话的“读-改-写”整对象过程互相覆盖。
-- Agent 工具调用失败时，仍保留 assistant 消息和 `failed` generation record，包括 tool call、模型、错误信息等排障字段；失败记录是会话历史的一部分，不因 SSE 已返回错误而丢弃。
+- Agent 规划失败使用 `role=system`、正文以 `ERROR ` 开头的消息持久化；首次响应和同 `clientMessageId` 重放都通过 `deltaMessages` 返回该消息，`errorMessage` 不重复携带。前端隐藏前缀并显示红色错误气泡，后端构建后续 LLM memory 时仍保留该消息，让 Agent 获取上一轮失败上下文。工具调用失败继续保留 `status=failed` 工具记录、模型和错误信息；失败记录都是会话历史的一部分。
 - 不把消息明细写入 SpacetimeDB 表，不把对话混入画布工程快照，不在 api-server 内存中保存会话真相。
 
 ## 备选方案与取舍
@@ -31,5 +31,5 @@
 - 会话表仍只保存元数据和 `messagesObjectKey`；API 可以在读取时把 OSS 消息文档拼装为会话详情返回，但完整消息正文的持久化真相仍是 OSS JSON 文档。
 - 消息文档最大 2 MiB；该限制用于阻止单个会话无限增长。后续如果需要更长历史，应引入归档、分页对象或摘要压缩，不应把正文回填进 SpacetimeDB 表。
 - 会话软删只打表标记，OSS 对象保留，便于恢复与审计。
-- 工具生成失败也会写入消息文档：assistant 消息可标记为失败 / 错误类型，`generations` 中保留 `failed` record、模型和错误信息，便于用户回看失败原因和后续排障。
+- 规划或工具生成失败也必须写入消息文档：规划失败保存 `ERROR ` system 消息，工具失败保存失败状态、模型和错误信息，便于用户回看失败原因和后续排障。
 - 若未来出现跨会话消息检索需求，需另建投影或索引，不回退为消息入表。

docs/project-memory/shared-memory/decision-log.md

@@ -15,6 +15,21 @@
 ```
 
 ---
+## 2026-07-17 画布 Agent 普通消息不提供客户端停止
+
+- 背景：普通消息进入 LLM 前，后端已经把用户消息写入 OSS；前端中断 fetch 只能停止本地等待，不能保证后端停止规划，且会保留无法与后端消息对齐的 optimistic message。
+- 决策：移除画布 Agent 普通消息的“停止”按钮和 `stopCurrentTurn`，发送期间保持按钮禁用并等待后端响应。待确认工具调用的“取消”仍保留，不受本决策影响。
+- 影响范围：画布 Agent 对话 hook、发送区交互、前端测试和专题文档。
+- 验证方式：运行画布 Agent hook / 面板定向测试、`npm run typecheck`、`npm run check:encoding` 和 `git diff --check`。
+- 关联文档：`docs/【编辑器】画布Agent对话面板-2026-07-03.md`。
+
+## 2026-07-10 画布 Agent 工具确认分离执行参数与展示投影
+
+- 背景：画布 Agent 已在实际生成前进入 `pending_confirmation`，但 `EditorAgentToolCall.args` 只保存工具私有 JSON，其中图片参数是保护真实 data key 的 SHA-256 opaque ID。前端直接解析 raw args 只能显示内部哈希或图片数量，无法向用户准确展示即将使用的目标图、参考图和完整参数；若直接把图片 URL 或对象塞回 raw args，又会破坏确认执行反序列化和 LLM 不可见真实 data key 的安全边界。
+- 决策：`EditorAgentToolCall.args` 继续作为确认执行唯一真相，不允许前端改写或回传替代参数；新增必填 `displayArgs` 只读展示投影，内含 `stringArgs`、`imageArgs` 和 `extras.priceMudPoints`。`stringArgs` 承载提示词与规格等用户可见字段，`imageArgs.refs` 承载 `imageId` 及后端解析出的 `objectKey`、`imageSrc`、可选缩略图、标签和尺寸；`extras.priceMudPoints` 由 api-server 在创建待确认消息时使用后端运行时模型定价快照计算，前端只显示“预计消耗 N泥点”，不自行计算或回传价格。api-server 必须按已注册 tool 白名单，从已校验 args 与 OSS 会话文档的附件 / 历史生成结果构建该投影；前端只渲染投影，以 `ResolvedAssetImage` 换签显示图片，不解析 tool 私有 schema、不展示 SHA-256 ID。展示价格不参与确认执行或实际扣费，确认后仍由既有生成 BFF 按后端运行时定价预扣费。删除只重复 `args` 且没有稳定语义的 `EditorAgentToolCall.summary`。模块尚未上线，不保留缺少 `displayArgs` 时读取 raw `args` 的旧消息降级路径。
+- 影响范围：`shared-contracts` / `packages/shared` 的 `editorAgent` DTO、`api-server/src/editor_agent/api.rs` 的待确认消息构建、画布 Agent 待确认卡、OSS 会话消息文档与相关测试。
+- 验证方式：`cargo test -p shared-contracts --manifest-path server-rs/Cargo.toml editor_agent`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_agent`、`npm run test -- src/components/image-editor/EditorAgentConversation/EditorAgentConversationPanelView.test.tsx src/components/image-editor/EditorAgentConversation/useEditorAgentConversation.test.tsx src/services/image-editor/editorAgentClient.test.ts`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
+- 关联文档：`docs/【编辑器】画布Agent对话面板-2026-07-03.md`、`docs/adr/【ADR】画布Agent会话消息存OSS-2026-07-03.md`。
 
 ## 2026-07-15 角色动作 BgFilter 请求超时按帧数扩展
 
@@ -275,10 +290,10 @@
 
 ## 2026-07-03 画布Agent会话元数据入 SpacetimeDB、消息正文存 OSS
 
-- 背景：图片画布工程需要对话式编辑历史，但消息正文随流式输出增长，不适合放入表行或画布布局快照；同时画布 Agent 只属于编辑器画布域，不能复用拼图 `creative-agent` 内存会话。
-- 决策：新增 `module-editor-agent` 承载纯领域规则，`editor_agent_conversation` 只保存会话元数据，完整消息以 `editor-agent/{conversationId}.json` 会话粒度存 OSS；`api-server` 负责编排 LLM、SSE、OSS 读写和既有生成工具调用。
+- 背景：图片画布工程需要对话式编辑历史，但消息正文随对话和工具结果增长，不适合放入表行或画布布局快照；同时画布 Agent 只属于编辑器画布域，不能复用拼图 `creative-agent` 内存会话。
+- 决策：`module-editor-agent` 只承载可供 SpacetimeDB WASM 使用的纯领域规则；Agent runner、工具实现和资产 DTO 迁入原生 `platform-editor-agent`，仅由 `api-server` 依赖。`editor_agent_conversation` 只保存会话元数据，完整消息以 `editor-agent/{conversationId}.json` 会话粒度存 OSS；`api-server` 负责编排 LLM、普通 JSON 消息、OSS 读写和既有生成工具调用。用户消息以独立 `clientMessageId` 在会话锁内幂等，数字 `message.id` 只作后端定位；旧 OSS 消息允许缺失幂等键，早期用户消息字符串 `id` 在读取时迁入 `clientMessageId`。画布 Agent 只与任务侧栏互斥，不与左侧素材 / 图层栏互斥。
 - 影响范围：图片画布右侧 Agent 面板、`shared-contracts` / `packages/shared` 的 `editorAgent` 契约、`spacetime-module` / `spacetime-client`、`platform-oss` 内部读签名边界、画布生成落板规则。
-- 验证方式：`npm run spacetime:generate`、`npm run check:spacetime-schema`、`cargo test -p module-editor-agent --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_agent`、前端 Agent 面板与 SSE client 定向测试、`npm run check:encoding`、`git diff --check`。
+- 验证方式：`npm run spacetime:generate`、`npm run check:spacetime-schema`、`cargo test -p module-editor-agent --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_agent`、前端 Agent 面板与 JSON client 定向测试、`npm run check:encoding`、`git diff --check`。
 - 关联文档：`docs/【编辑器】画布Agent对话面板-2026-07-03.md`、`docs/adr/【ADR】画布Agent会话消息存OSS-2026-07-03.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
 
 ## 2026-07-01 认证工作集只经 typed projection 同步正式表
@@ -3233,6 +3248,13 @@
 - 影响范围：`server-rs/crates/api-server/src/editor_generation_queue.rs`、`server-rs/crates/api-server/src/external_generation_worker.rs`、`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/api-server/src/character_animation_assets.rs`、`server-rs/crates/api-server/src/vector_engine_audio_generation/generation.rs`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`src/services/image-editor/editorProjectClient.ts`。
 - 验证方式：`cargo test -p api-server external_generation_worker --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server editor_canvas_generation --manifest-path server-rs/Cargo.toml`、`cargo test -p shared-contracts --manifest-path server-rs/Cargo.toml`、`npm run test -- src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx src/services/image-editor/editorProjectClient.test.ts`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
 
+## 2026-07-13 画布 Agent 工具执行状态复用外部生成任务
+
+- 决策：画布 Agent 的 OSS 工具消息使用 `status=not_completed|completed|failed|cancelled` 和可选 `externalJobId`；不使用 `cancelledAt`，不新增关联表。`external_generation_job` 是排队、执行、lease 与计费结算的唯一真相；OSS status 只表达该消息回填结果，不复制 queued / running。确认接口按 `conversationId + messageId + toolName` 稳定去重并复用既有编辑器 worker job kind。
+- 懒回填：`GET /conversation` 会在持有 conversation lock 后扫描 `status=not_completed` 且有 `externalJobId` 的工具消息，按 job id 定向读取主任务；完成时复用原工具 formatter 更新 system text、写入轻量媒体引用并标记 `completed`，任务本身失败时写入 `error` 并标记 `failed`。任务结果读取或 completed payload 解析 / formatter 首次失败后，在同一次 GET 内最多重试 3 次，每次等待 100ms 并重新读取主任务；读取失败或 completed 任务暂缺 `result_payload_json` 时，本次重试耗尽后保留 `not_completed + externalJobId` 供下次 GET 继续 reconcile，确定性的 payload 损坏、结构不兼容或 formatter 错误才在重试耗尽后写为 `failed`，避免致命错误永久循环。排队 / 执行保持 `not_completed`。worker 的 `result_payload_json` 只保留 formatter 与媒体引用所需的轻量生成回包，不向通用 summary 状态接口投影。
+- 影响范围：画布 Agent 共享契约、确认/取消接口、编辑器生成入队 helper、对话状态展示与恢复。
+- 验证方式：`cargo check -p api-server -p shared-contracts --manifest-path server-rs/Cargo.toml`、画布 Agent 定向前端测试、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
+
 ## 2026-06-18 原生壳 WebView 刷新能力只保留受控当前页刷新
 
 - 背景：Expo 移动壳和 Tauri 桌面壳都需要一个真实的宿主级刷新入口，供 H5 在检测到资源、登录态或运行态需要重新载入时请求宿主刷新当前容器；该能力不能演变成任意 URL 导航或原生 WebView ref 透传。
@@ -4055,7 +4077,7 @@
 
 - 背景：VectorEngine Apifox `api-349239079` 暴露 OpenAI-compatible `POST /v1/chat/completions`；创意 Agent 和通用 LLM 代理需要统一到 VectorEngine 文本服务，并将默认文本模型切换为 `gpt-5.4-mini`。
 - 决策：创意 Agent 的 `CREATIVE_AGENT_GPT5_MODEL` 固定为 `gpt-5.4-mini`，协议切到 Chat Completions，不再携带旧 APIMart `official_fallback` 字段；画布 Agent 侧边栏聊天规划请求也复用该模型和 Chat Completions 协议，不再显式使用 `gpt-4o` / Responses。通用 `/api/llm/chat/completions` 代理使用 `GENARRATIVE_LLM_PROVIDER=openai-compatible`、`GENARRATIVE_LLM_BASE_URL=https://api.vectorengine.cn/v1`、`GENARRATIVE_LLM_MODEL=gpt-5.4-mini`。未单独配置 `GENARRATIVE_LLM_API_KEY` 时，api-server 可复用 `VECTOR_ENGINE_API_KEY`；前端 LLM 客户端必须兼容 OpenAI `choices`、api-server raw `{content}` 和项目 envelope `{ok,data:{content}}` 三种非流式响应，以及 OpenAI SSE delta 和 api-server `event: delta` 两种流式响应。
-- 决策补充：画布 Agent 的 planning prompt 必须自动注入上一条已完成生成结果的 `latestGeneratedImage`，来源为上一轮 generation 的 `summary` / `toolName` / `resourceId` / `objectKey` 等轻量摘要。用户用「这张」「刚才那个」「上一张」「把衣服换成……」等方式指代上一张图或继续编辑时，规划默认调用 `edit_image` 并引用该结果；不能因为本轮没有手动附件而退回 `generate_image`。
+- 决策补充：画布 Agent 的 planning prompt 必须自动注入上一条已完成生成结果的 `latestGeneratedImage`，来源为上一轮 generation 的 `toolName` / `resourceId` / `objectKey` 等轻量元数据。用户用「这张」「刚才那个」「上一张」「把衣服换成……」等方式指代上一张图或继续编辑时，规划默认调用 `edit_image` 并引用该结果；不能因为本轮没有手动附件而退回 `generate_image`。
 - 决策补充：画布 Agent 侧边栏的“规范图 / 视觉规范图 / 风格规范图 / 素材规范展板”是 Agent 规划 prompt 和 function-calling 工具选择约束，不是侧边栏 UI 说明文案。此类请求默认走 `generate_image`，prompt 必须要求规范展板包含统一视角、线条粗细、色卡、材质、阴影、圆角、状态层级、尺寸标注等视觉规范元素；角色规范图若是规范展板也走 `generate_image`，只有实际角色立绘才走 `generate_character`，多个图标素材 / 图集才走 `generate_icon_spritesheet`。
 - 影响范围：`server-rs/crates/platform-agent`、`server-rs/crates/api-server/src/config.rs`、`src/services/llmClient.ts`、`.env.example`、`deploy/env/api-server.env.example`、`scripts/test-ve-llm.mjs`。
 - 验证方式：`npm run test -- src/services/llmClient.test.ts`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml from_env_reads_non_public_models_and_urls app_state_builds_creative_agent_gpt5_client_from_vector_engine_settings llm_chat_completions editor_agent_llm_request_uses_vector_engine_chat_model`、`cargo test -p platform-agent --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`、`git diff --check`。

docs/project-memory/shared-memory/document-map.md

@@ -1,6 +1,6 @@
 # 文档地图与阅读索引
 
-更新时间：`2026-07-03`
+更新时间：`2026-07-16`
 
 ## 当前文档入口
 
@@ -18,7 +18,7 @@
 | 微信小程序虚拟支付 | `docs/【技术方案】微信虚拟支付接入-2026-05-26.md` |
 | UI 像素资产与 9-slice 规范 | `UI_CODING_STANDARD.md` |
 | 图片画布生成面板与模型定价 | `docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`、`docs/【编辑器】模型定价配置管理方案-2026-06-22.md` |
-| 图片画布右侧 Agent 对话、会话消息 OSS 持久化、SSE 事件契约、与任务侧栏 / 左侧栏互斥规则 | `docs/【编辑器】画布Agent对话面板-2026-07-03.md`、`docs/adr/【ADR】画布Agent会话消息存OSS-2026-07-03.md` |
+| 图片画布右侧 Agent 对话、会话消息 OSS 持久化、普通 JSON 消息、工具任务懒回填及侧栏并存规则 | `docs/【编辑器】画布Agent对话面板-2026-07-03.md`、`docs/adr/【ADR】画布Agent会话消息存OSS-2026-07-03.md` |
 
 ## 阅读顺序
 

docs/technical/【前端架构】SSE客户端传输层收口约定-2026-06-03.md

@@ -1,6 +1,6 @@
 # SSE 客户端传输层收口约定
 
-更新时间：`2026-06-03`
+更新时间：`2026-07-16`
 
 ## 背景
 
@@ -13,7 +13,6 @@
 - `readSseStream` 负责读取 `Response.body`、识别 `\n\n` 与 `\r\n\r\n` 事件边界、合并多行 `data:`、flush `TextDecoder` 尾部缓冲，并支持事件处理函数返回 `false` 后取消 reader。
 - `readSseJsonStream` 只在传输事件基础上解析 JSON object，空 data 与异常 JSON 继续按旧口径静默跳过。
 - 各业务 client 只保留领域事件归一化、最终结果聚合和中文错误文案，不再重复实现 SSE 边界扫描、reader 循环或 UTF-8 flush。
-- `src/services/image-editor/editorAgentSse.ts` 消费画布 Agent 的 JSON SSE，只校验并归一 `stage`、`message_delta`、`tool_started`、`tool_completed`、`generation_result`、`error`、`done` 事件，不持有 reader 循环或事件边界解析。
 - OpenAI 兼容流、`[DONE]` 哨兵或其它非 JSON SSE 可直接使用 `readSseStream`；业务 JSON 事件优先使用 `readSseJsonStream`。
 
 ## 落地范围
@@ -26,27 +25,15 @@
 - `src/services/visual-novel-runtime/visualNovelRuntimeSse.ts`
 - `src/services/rpg-entry/rpgProfileClient.ts`
 - `src/services/llmClient.ts`
-- `src/services/image-editor/editorAgentSse.ts`
 
 后续新增 SSE client 时不得复制 `findSseEventBoundary`、`parseSseEventBlock` 或手写 reader 循环；若确实需要特殊 framing，应先扩展 `sseStream.ts` 的传输能力，再在业务 client 中处理领域语义。
 
-## 画布 Agent SSE client 口径
-
-`src/services/image-editor/editorAgentSse.ts` 是画布 Agent 的业务事件归一层，只允许做以下事情：
-
-- 调用 `readSseJsonStream(response, handler)` 读取 JSON SSE。
-- 白名单识别 `stage`、`message_delta`、`tool_started`、`tool_completed`、`generation_result`、`error`、`done`。
-- 支持两种兼容输入形态：优先使用 SSE `event:` 字段作为事件名；若 `data` 内含 `{ "event": "...", "data": {...} }`，则归一为同一 `EditorAgentSseEvent`。
-- 对未知事件名、缺失 `data` 或非对象 JSON 静默跳过，保持业务 client 的容错口径。
-
-`editorAgentSse.ts` 不得实现 `Response.body.getReader()`、`TextDecoder`、SSE 边界扫描、JSON 字符串拼接、fetch、鉴权、错误文案、会话状态聚合或画布聚焦逻辑；这些职责分别留在 `sseStream.ts`、`editorAgentClient.ts`、`useEditorAgentConversation.ts` 和画布视图层。
+画布 Agent 已改为 `POST /api/editor/agent-conversations/{conversationId}/messages` 普通 JSON 请求，不属于本 SSE 传输层的落地范围；其客户端只通过 `requestJson` 读取 `EditorAgentMessageResponse`，不得为了恢复旧文档口径重新增加私有 SSE parser。
 
 ## 验收
 
 - `src/services/sseStream.test.ts` 覆盖 CRLF / LF 边界、UTF-8 尾部 flush、异常 JSON 跳过和提前停止取消 reader。
 - `src/services/llmClient.test.ts` 覆盖 OpenAI 兼容文本流、异常 JSON 跳过和 `[DONE]` 后提前停止。
-- `src/services/image-editor/editorAgentSse.test.ts` 覆盖画布 Agent 的 `stage`、`generation_result`、`done` 事件解析，以及 `{ event, data }` fallback 形态归一。
-- `src/services/image-editor/editorAgentClient.test.ts` 覆盖会话 CRUD 路由和 `/messages/stream` 发起后能收到类型化 SSE 事件。
-- 后续修改 `editorAgentSse.ts` 时，若出现手写 reader、`TextDecoder`、SSE 边界扫描或 fetch 逻辑，应视为违反本收口约定。
+- `src/services/image-editor/editorAgentClient.test.ts` 覆盖会话 CRUD 和 `/messages` 普通 JSON 路由；画布 Agent 不纳入 SSE parser 验收。
 - 已有 OpenAI 兼容文本流、NPC 聊天流、创作 Agent、创意互动 Agent、视觉小说运行态和充值订单状态测试继续通过。
 - `npm run typecheck` 不产生新的类型错误。

docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md

@@ -28,7 +28,7 @@
 - 图片快速编辑面板只保留一个提示词输入框和模型选择，不展示额外参考图或比例 / 尺寸控件；原图 / 原素材作为 `/api/editor/images/edits` 的 `sourceImageSrc` 直接提交，不作为 `referenceImageSrcs`。完整图标图集 `icon-spritesheet` 支持快速编辑，拆分后的单个 `icon` 不提供该入口，前后端必须使用同一素材类型规则。打开快速编辑时画布必须自动平移缩放，让原素材完整落在可视区上半部分，底部面板固定出现在素材下方且不遮挡内容，竖屏 UI 素材也必须完整展示。快速编辑右侧显示矩形、椭圆、画笔框选工具，但进入时不默认启用；点击工具后显示选中态，再点同一工具取消启用。完成框选后，画布红色细框显示连续序号，提示词可按这些编号填写每个区域怎么改。点击 `修改` 后仍停留在当前快速编辑面板显示修改中，不创建独立 `Quick Edit Generator` 画布占位；生成成功后直接用结果覆盖原图图层，失败时保留当前面板并在错误红框中显示具体错误文案。
 - 底部生成类按钮每次点击都必须创建独立的画布生成对象；新建规范、角色形象或图标素材时，只切换当前编辑面板，不得销毁此前尚未生成或已生成后的其它生成对象状态。归档为非当前编辑对象的生成占位仍可拖动、删除和等待异步完成，完成 / 失败回写必须按生成对象 ID 读取最新占位状态，不能使用提交瞬间的旧快照。
 - 画布右上角提供自动隐藏任务侧栏。列表为空且侧栏关闭时只保留图标开关；生成或去背景任务进入时默认打开；用户可手动切换开关状态。进行中阶段只使用外部生成 BFF 返回的 `phaseDetail`：调用或等待图片 / 视频生成服务时显示“正在生成”，进入 BgFilter、逐帧抠图或手动去背景时显示“正在处理”；前端不得按耗时或任务类型猜测阶段。
-- 画布底部工具栏 / 面板 Dock 提供“画布 Agent”入口。点击后打开右侧独立 Agent 对话面板；桌面端为右侧窄面板，移动端占满可用宽度。该面板与素材侧栏、图层侧栏、右上角任务侧栏互斥，打开 Agent 时必须收起其它侧栏，打开其它侧栏或任务侧栏时也必须收起 Agent。Agent 面板不得在当前画布内容下方追加内联内容，也不默认展示大段功能说明文案。
+- 画布底部工具栏 / 面板 Dock 提供“画布 Agent”入口。点击后打开右侧独立 Agent 对话面板；桌面端为右侧窄面板，移动端占满可用宽度。该面板只与右上角任务侧栏互斥；素材 / 图层侧栏允许与 Agent 同时展开，切换左侧栏不得关闭 Agent。Agent 面板不得在当前画布内容下方追加内联内容，也不默认展示大段功能说明文案。
 - 所有会新建画布生成占位的入口必须先创建 draft，再统一经过 `ImageCanvasGenerationPlacementModel` 计算落点，禁止各入口自行使用当前视口中心裸坐标或原图右侧固定偏移。当前覆盖入口包括 `生成图片`、`生成规范`、`生成角色形象`、`生成图标素材`、`生成视频`、`生成UI设计图` 和 `生成角色动作`。placement 模型的避让对象为所有未隐藏画布图层，以及当前 active / inactive generation dialogs 中仍存在的 placeholder；每个避让矩形按 32px 画布世界坐标间距外扩。候选落点以当前视口世界中心为距离目标，优先选择离视口中心最近且不重叠的占位位置；若中心被占用，会按上下左右和环形候选继续寻找。打开生成面板时必须把避让后的 placeholder 写入 `openCanvasGenerationDialog(...)`，并立即调用 `centerViewportOnPlacement(...)` 居中到新占位中心，保持原 viewport scale 不变；图片快速编辑不属于新建占位入口，提交后覆盖源图。
 
 ## 交互规则
@@ -59,7 +59,7 @@
 - 资源表保存资源和素材级元数据；图层位置、层级、分组选中所需 ID 和 groupId 保存在 `editor_canvas` 的布局 JSON。布局 JSON 是混合数组：普通图层按 `layerId/resourceId` 保存，生成器占位和生成器对话框按 `itemType: "generation-dialog"` 保存，不新增单独表。普通图层的新保存不再把 `assetKind/generationInputs` 写入布局 JSON；刷新时优先从 `editor_project_resource` 恢复，旧布局中的同名字段只作为兼容兜底。生成器快照必须包含生成器 ID、模式、提示词、参数、参考图、状态、占位框位置和可选 `generatedLayerId`；角色、图标等纯色抠图生成器的前端用户路径不保存或恢复 `screenColor` / `segModel`，同源重绘也不再从 `generationInputs.fields` 恢复 `抠图背景色` 或 `抠图模型`；宣发素材生成器还必须保存并恢复 `publicationWorkflowId`、`publicationGameInfo` 和 `publicationReferences`，避免刷新后生成卡片字段或参考图丢失。生成器快照中的参考图同样只保存 `resourceId/sourceAssetId` 行引用和展示所需 label，不保存图片 Data URL、signed URL 或 `objectKey`；刷新时用 `editor_project_resource` / `editor_asset` 行恢复临时生成请求所需图片源。生成成功后仍保存该快照，只是渲染时由 `generatedLayerId` 锚定到成品图层而不重复显示灰色占位框。`generationInputs.references` 是用户可见输入快照中的行级索引，只允许保存 `{ title, label, refType, refId }`；生成接口只接收提交前临时状态解析出的 `objectKey` 或资源 ID；Data URL、Blob URL 和 signed URL 不进入请求体，不进入资源 / 素材元数据。图层展示尺寸不再作为独立 `Size` 真相保存，刷新与新建图层均按 `Resolution`（`originalWidth/originalHeight`）原分辨率显示。图层组第一版是画布内布局语义，不单独建表。
 - 图片类、生成视频和音频结果除作为 `editor_project_resource` 和画布图层保存外，还要写入账号级 `editor_asset` 素材库；该写入由生成 BFF 在请求携带 `assetFolderId` 时完成。角色、图标图集、UI 提取和角色动作等多产物任务把实际产生的 provider 原始输出及后处理结果分别入库：所有条目沿用 `character`、`icon-spritesheet`、`character-animation` 等真实类型，provider 原始输出承载任务模型成本，后处理派生产物阶段成本为 0。后台素材查询以最终产物为父行、每个中间产物为可展开的独立子行，分页只计算父任务；手动重拆图集保留独立 `taskId` 用于存储隔离和日志排障，通过私有 provenance 从服务端生成账号素材的 source resource、asset object 或 Object Key 取得可信来源任务，并把它写入 `groupTaskId`，不信任客户端可提交的 resource `taskId/assetKind`；跨项目复用后仍可通过稳定媒体引用找回来源。没有可信来源的新拆分显式归到自身任务，不走历史资源链回溯。每个手动切片同时写入 `groupTaskExpectedAssetCount`，全部切片落库后写独立 cohort 完成事实；后台 read model 只让同一根任务的一个已完成拆分批次并入原图集父项，用户后来删除单片不会让批次脱组，部分失败批次和后续重复拆分批次按各自真实任务分页，避免残缺批次抢占根任务、单组无限增长或素材丢失。历史行在项目资源仍存在时兼容回溯，删除项目资源前只固化直接受影响行的真实来源字段，有界展示 ID 不反写数据库。`GENARRATIVE_EXTERNAL_GENERATION_MODE=queue` 下，画布图片、改图、图标素材、UI 素材提取、角色动作、视频、音效和背景音乐生成都先返回 `queueState`，前端轮询 `/api/runtime/external-generation/jobs/{jobId}` 到完成后重新读取项目快照；`inline` 或无项目上下文时才使用响应中的 resource / asset 快照做本地落画布兜底，不再把同一生成结果二次调用素材创建接口。生成请求失败、inline 完成或 queue 任务终态完成 / 失败后，右上角泥点 chip 必须通过 `/profile/dashboard` 回读余额，不做本地乐观扣减。生成视频会单独抽取首帧封面写入 `thumbnailSrc`，素材栏和拖回画布时沿用该封面作为 poster。
 - 生成面板不展示资源名称输入，默认使用原有自动编号；提示词输入保持统一可见边框。内部命名契约仍使用可选 `assetLabel`，最大 80 字符并在提交时 trim；历史状态或内部调用携带非空名称时，同一个名称必须贯穿 `assetLabel`、`canvasCompletion.title`、项目资源、账号素材和本地兜底图层，刷新后不得退回模板名。图标图集与角色动作请求同样兼容该字段，中间原图使用主名称加固定后缀，拆分素材继续按素材描述命名。
-- 画布 Agent 会话按“SpacetimeDB 元数据 + OSS 消息正文”存储：`editor_agent_conversation` 只保存 `conversationId/projectId/ownerUserId/title/messagesObjectKey/deleted/createdAt/updatedAt` 等会话元数据；消息正文整体保存为私有 OSS JSON 文档 `editor-agent/{conversationId}.json`。消息文档单对象上限为 2 MiB，同一会话的消息追加和 SSE 最终写回由 api-server 按 `conversationId` 串行化，避免“读 OSS → 改消息 → 写 OSS”并发覆盖。前端只通过 api-server BFF 读取和发送会话，不直接读写 SpacetimeDB，也不直接读写 OSS。
+- 画布 Agent 会话按“SpacetimeDB 元数据 + OSS 消息正文”存储：`editor_agent_conversation` 只保存 `conversationId/projectId/ownerUserId/title/messagesObjectKey/deleted/createdAt/updatedAt` 等会话元数据；消息正文整体保存为私有 OSS JSON 文档 `editor-agent/{conversationId}.json`。消息文档单对象上限为 2 MiB，同一会话的消息追加和工具结果回填由 api-server 按 `conversationId` 串行化，避免“读 OSS → 改消息 → 写 OSS”并发覆盖。前端只通过 api-server BFF 读取和发送会话，不直接读写 SpacetimeDB，也不直接读写 OSS。
 - Agent 消息附件只允许引用当前工程画布资源或账号素材库图片，来源类型为 `canvas_resource` / `library_asset`，最多 9 张。附件请求可携带展示用 `imageSrc/thumbnailSrc/objectKey/width/height/label`，但持久化真相仍以后端校验后的 resource / asset 行和 OSS 对象为准；不得把 Data URL、signed URL 或 blob URL 当作会话长期事实。
 - 前端不直接订阅 SpacetimeDB，统一通过 api-server 的 `/api/editor/projects*` BFF 读写。
 - 工程刷新恢复可先应用 session 级轻量项目快照缓存，让画布和素材 chrome 尽快显示；缓存快照必须排除 `data:*` / `blob:` 内联媒体，且在后端项目快照返回前不得触发自动保存。后端快照回来后覆盖本地缓存显示并恢复正常保存队列。
@@ -79,7 +79,7 @@
 - `POST /api/editor/projects/{projectId}/agent-conversations`：在当前工程下创建画布 Agent 会话；可选传入标题，默认标题为“新对话”。
 - `GET /api/editor/agent-conversations/{conversationId}`：读取指定画布 Agent 会话详情，返回会话摘要和 OSS 消息正文中的消息列表。
 - `DELETE /api/editor/agent-conversations/{conversationId}`：软删除指定画布 Agent 会话，并返回删除后的会话摘要。
-- `POST /api/editor/agent-conversations/{conversationId}/messages/stream`：发送画布 Agent 消息并返回 JSON SSE。请求体包含 `clientMessageId`、`text` 和可选 `attachments`；文本与附件不可同时为空。SSE 事件名固定为 `stage`、`message_delta`、`tool_started`、`tool_completed`、`generation_result`、`error`、`done`。生成结果中的图片通过后端写入 project resource / 账号素材后返回轻量快照，前端只消费返回的资源引用并刷新 / 聚焦画布。工具失败时也必须保留失败 generation record，不得只返回一次性错误。
+- `POST /api/editor/agent-conversations/{conversationId}/messages`：发送画布 Agent 消息并返回普通 JSON `EditorAgentMessageResponse`。请求体包含 `clientMessageId`、`text` 和可选 `attachments`；文本与附件不可同时为空，同一会话重复 `clientMessageId` 必须幂等返回或拒绝重复追加。响应包含权威会话摘要、`deltaMessages` 和可选 `errorMessage`。LLM / 规划失败写入 `role=system`、正文以 `ERROR ` 开头的 OSS 消息并放入 `deltaMessages`，不再重复设置 `errorMessage`；前端隐藏前缀后显示红色错误气泡。工具失败继续保存工具状态和错误信息。
 - `GET /api/editor/assets/library`：读取当前账号的素材文件夹和素材。首次读取时自动创建“项目素材”默认文件夹。
 - `POST /api/editor/assets/folders`：新建素材文件夹。
 - `PATCH /api/editor/assets/folders/{folderId}`：重命名、折叠 / 展开素材文件夹。
@@ -103,8 +103,7 @@
 - 示例素材可继续复用 `public/creation-type-references/` 下的站内图片；用户上传和后续生成资源必须通过资源记录表达。
 - 不把 hover、dragging、临时吸附线、Space 临时抓手等瞬时 UI 状态写入后端。
 - 不在 UI 中加入大段功能说明，编辑器界面只展示必要的工具、素材和状态信息。
-- 画布 Agent 前端分层固定为：`editorAgentClient.ts` 负责 BFF 请求、鉴权错误和 stream 发起；`editorAgentSse.ts` 只负责 SSE JSON 事件归一；`useEditorAgentConversation.ts` 负责会话列表、当前会话、消息流、阶段和停止状态；`EditorAgentConversationPanelView.tsx` 只负责右侧面板展示与交互。
-- `editorAgentSse.ts` 必须复用 `src/services/sseStream.ts` 的 `readSseJsonStream`，不得复制 SSE reader、`TextDecoder`、事件边界扫描或 UTF-8 flush 逻辑；该文件不得承接 fetch、鉴权、会话聚合、画布聚焦或 UI 错误文案。
+- 画布 Agent 前端分层固定为：`editorAgentClient.ts` 负责普通 JSON BFF 请求、鉴权和错误映射；`useEditorAgentConversation.ts` 负责会话列表、当前会话、消息请求等待态、工具任务状态和客户端取消等待；`EditorAgentConversationPanelView.tsx` 只负责右侧面板展示与交互。画布 Agent 不新增私有 SSE parser。
 - 不复用或改写 `CreativeImageInputPanel` 的单图资产编辑语义；`/editor/canvas` 是独立图片画布工程的画布入口。
 
 ## 验收用例
@@ -124,11 +123,11 @@
 - 快速编辑面板底部只显示模型选择和 `修改` 按钮；打开时视口聚焦必须预留底部面板空间，面板位于素材下方，不得遮挡原素材，且素材在当前屏幕内完整可见。快速编辑请求只把原图或红框序号标注图作为 `sourceImageSrc` 直接提交，信息面板输入快照只展示用户填写的快速编辑提示词。
 - 点击生成、生成规范、生成角色形象或生成图标素材后创建的占位图可继续保留；点击画布空白区域让当前图片或占位图失焦时，关闭当前生成面板并移除图片选中样式，但不删除占位图本身。
 - 生成资源显示元数据按钮，元数据窗口展示来源、生成输入快照、model、task、Resolution 和 OSS 引用；生成输入快照只包含用户面板输入和参考图行引用，不包含后端拼接 Prompt，不再展示独立 Size 字段，也不渲染参考图 Data URL 缩略图。
-- 点击底部 Dock 的“画布 Agent”后，右侧独立 Agent 面板打开；素材 / 图层侧栏和任务侧栏被收起。再次点击或点击面板关闭按钮后收起 Agent。打开素材 / 图层侧栏或任务侧栏时，Agent 面板同步关闭。
+- 点击底部 Dock 的“画布 Agent”后，右侧独立 Agent 面板打开，任务侧栏被收起；素材 / 图层侧栏保持当前状态并可继续切换。再次点击或点击面板关闭按钮后收起 Agent；打开任务侧栏时 Agent 面板同步关闭。
 - Agent 面板能读取当前工程会话列表；无历史会话时发送第一条消息会先创建“新对话”。支持新建会话、切换会话和删除当前会话；删除必须通过独立确认弹窗完成，不能在面板下方追加确认内容。
 - Agent 输入支持文本消息、附件消息和纯附件消息；附件选择弹窗可在“画布 / 素材库”之间切换，只展示图片类资源，最多选择 9 张。
-- 发送消息后，面板展示用户消息、Agent 阶段状态和 SSE 增量回复；`stage/message_delta/tool_started/tool_completed/generation_result/error/done` 都能被正确渲染。流式响应中点击“停止”会中断当前请求，并把仍在 streaming / generating 的消息标记为停止态。
-- Agent 返回生成结果缩略图后，点击缩略图应优先聚焦当前画布中已有 `resourceId` 对应图层；如果当前内存布局尚未包含该资源，则重新读取工程快照，应用后再聚焦新图层。对话入口触发生成时不创建“即将生成”画布占位；生成中状态只显示在消息流，生成完成后通过后端 `canvasCompletion` 落新图层。工具失败时消息内必须保留失败 generation record 和错误气泡，不能只弹一次性 toast。
+- 发送消息后，面板先展示本地用户消息和请求等待态，再应用普通 JSON 响应中的 `deltaMessages`；客户端取消等待只终止本次 transport 等待，不把已经确认入队的外部生成任务改成停止态。
+- Agent 工具任务完成并懒回填后，消息内缩略图只作纯预览，不显示名称也不点击聚焦图层；前端同时重新读取工程快照和素材库。对话入口触发生成时不创建“即将生成”画布占位，生成完成后由后端 `canvasCompletion` 落新图层。规划或工具失败时消息内必须保留可回读的失败状态和错误气泡，不能只弹一次性 toast 或返回瞬时 `errorMessage`。
 - 画布 Agent 会话刷新后能从后端恢复会话标题、消息、附件和生成记录；前端不得根据本地临时状态伪造会话持久化结果。
 - 图片选中后的浮动工具栏按钮顺序固定为：快速编辑、分割线、裁扩按钮、去除背景按钮、UI设计图专属提取素材、角色图专属生成动画、分割线、重绘、下载按钮。裁扩通过画布边界拖拉完成，不再展示四边数值输入；默认自由比例，选择固定比例后拖拉边界保持对应比例，完成后在原素材旁边新增裁扩结果图层，扩展区域透明填充。去除背景调用同源 BFF `POST /api/editor/images/background-removals`，由 api-server 通过共享 BgFilter `background_mode=complex` 链路去背景并持久化结果；有项目上下文时先在画布创建关闭面板的去背景生成占位，完成后由后端通过 `canvasCompletion` 把新 project resource 写入该占位并返回快照，无占位上下文时才用新的 project resource 引用替换当前图层。画布任务侧栏按“排队/生成中”和“已完成”分页，生成中排在排队前，生成中耗时从任务开始时间戳实时计算，排队中不计时；进行中任务只显示阶段文本和已用时，不显示百分比；完成态生成任务副标题显示用户提示词并单行截断；点击任务只聚焦对应画布内容，不激活生成面板或改变任务顺序，聚焦时必须预留图片上方工具栏、底部工具栏和可见生成对话框空间。UI设计图的提取素材必须先进入红框素材框选状态，默认启用矩形框选，右侧框选工具与快速编辑统一且可再次点击取消启用态，当前启用工具按钮必须保持高亮。素材提取面板必须在素材下方，使用与生成新素材一致的面板宽度和底部模型 / 按钮样式，提示语显示 `使用框选工具框选你希望从画面中提取的素材`，并展示按原图坐标准确裁剪的框选区域截图预览、固定模型 `gpt-image-2`、左下角计划规格 `1:1·1K/2K` 和 `提取 · N泥点` 按钮，不显示额外取消按钮；点击素材和面板以外的画布区域即退出 UI 素材提取。至少框选一个区域后才可提交，前端把红色轮廓绘入原图后固定走 `gpt-image-2` 和自动决策纯色背景素材提取提示词。透明处理及拆分正常完成时，透明 spritesheet 和拆分素材都按后端快照保留为画布图层；透明处理失败时仅原图作为主结果，既不要求透明图也不要求切片；透明图成功但拆分失败时保留整张透明图并展示拆分告警。三种完成结果都以后端项目快照为准。
 - 重绘生成资源后，右侧出现新生成结果图层，并自动 fit 原图 + 新图，且重绘面板保持打开。

docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md

@@ -31,6 +31,7 @@
 - `acknowledge_external_generation_job_summaries_and_return`：按当前账号确认已终态任务的完成 / 失败提示，写入摘要投影的 `notification_acknowledged_at` 并追加审计事件。
 - `get_external_generation_queue_stats_and_return`：controller 读取队列积压、运行中任务和过期 lease 数量，用于计算 worker 目标实例数；该 procedure 只读 `external_generation_job`，不直接操作 systemd。
 - `get_external_generation_job_summary_and_return`：按 `job_id` 从轻量摘要投影读取单个任务状态，给 BFF 和生成页展示使用；必须只返回调用者有权读取的任务，不能暴露其它用户的 payload、错误详情或 worker 内部字段。
+- `get_external_generation_job_result_and_return`：仅供后端内部回填异步编辑器 Agent 工具调用；按 `job_id + owner_user_id` 返回 `status`、`last_error_message` 和已持久化的 `result_payload_json`，不返回请求 payload、lease 或其它 worker 字段。该 procedure 不替代摘要状态读取接口，也不经 BFF 暴露给前端。
 
 不带 `summary / summaries` 的旧 `get / list / acknowledge_external_generation_job*` procedure 只保留给受控内部兼容，不是 BFF 正式读取入口。
 

docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md

@@ -78,12 +78,15 @@ npm run check:server-rs-ddd
 
 ### 图片画布 Agent 对话
 
-- `/api/editor/projects/{projectId}/agent-conversations` 负责当前工程会话列表和新建；`/api/editor/agent-conversations/{conversationId}` 负责详情读取和软删；`/api/editor/agent-conversations/{conversationId}/messages/stream` 负责发送消息并返回 SSE。
+- `/api/editor/projects/{projectId}/agent-conversations` 负责当前工程会话列表和新建；`/api/editor/agent-conversations/{conversationId}` 负责详情读取、终态工具消息懒回填和软删；`POST /api/editor/agent-conversations/{conversationId}/messages` 负责发送消息并返回普通 JSON `EditorAgentMessageResponse`，画布 Agent 不提供 `/messages/stream` SSE 路由。消息请求必须携带最长 128 字符的 `clientMessageId`；前端对该 POST 显式启用 1 次瞬时 transport 重试，并复用同一个序列化 body、`clientMessageId` 和 `x-request-id`。同一会话在锁内按该键幂等，重复键同内容返回已有回合或从已保存用户消息继续，异内容返回 `409`。数字 `EditorAgentMessage.id` 仍只作为工具确认 / 取消的后端消息定位符，不能复用为客户端幂等键。
 - `module-editor-agent` 只承载纯领域校验：标题派生、附件上限、消息输入规则和会话软删访问规则；不直接依赖 Axum、SpacetimeDB、OSS、LLM 或 Tokio。
 - `spacetime-module` 的 `editor_agent_conversation` 只保存元数据；创建、列表、读取、更新时间和软删通过 `create_editor_agent_conversation_and_return`、`list_editor_agent_conversations_and_return`、`get_editor_agent_conversation_and_return`、`touch_editor_agent_conversation_and_return`、`delete_editor_agent_conversation_and_return` procedure 完成，`api-server` 只能经 `spacetime-client` facade 访问。
-- 完整消息文档存 OSS `editor-agent/{conversationId}.json`，由 `api-server` 负责 2 MiB 上限、会话内串行锁、读改写、SSE 事件持久化和 `touch` 元数据更新时间；该 JSON 不进入 `editor_canvas.layers_json`，也不作为画布布局真相。
+- 完整消息文档存 OSS `editor-agent/{conversationId}.json`，由 `api-server` 负责 2 MiB 上限、会话内串行锁、读改写、消息与工具结果持久化和 `touch` 元数据更新时间；该 JSON 不进入 `editor_canvas.layers_json`，也不作为画布布局真相。LLM / 规划失败必须写入 `role=system`、正文以 `ERROR ` 开头的消息，并通过 `deltaMessages` 返回，`errorMessage` 保持为空；前端隐藏前缀并显示红色错误气泡，后端仍把该 system 消息注入后续 LLM memory，使 Agent 能读取失败上下文。工具失败同样必须形成可回读记录，不能只返回瞬时错误。
 - 对话附件只允许引用当前工程 `editor_project_resource` 或当前账号 `editor_asset` 的图片；前端可提交展示用 `imageSrc` / `thumbnailSrc`，后端必须按 `resourceId` / `assetId` 重新归一、校验 owner / project 和 `objectKey`，再给 LLM 或生成工具使用。
 - 画布 Agent 工具复用既有编辑器图片生成 / 修改 / 图标 spritesheet BFF，并继续使用后端模型定价和 `execute_billable_asset_operation_with_cost`；前端不提交 `priceMudPoints`。
+- `/messages/{messageId}/confirm` 与 `/messages/{messageId}/cancel` 只返回成功确认；前端成功后立即重新读取整个会话，以会话详情中的权威消息状态和 `externalJobId` 驱动气泡展示与任务轮询。
+- 会话详情的终态懒回填必须在单次 GET 和同一 conversation lock 内完成有界重试：任务结果读取、completed payload 解析或工具 formatter 首次失败后最多重试 3 次，每次等待 100ms 并重新读取主任务。任务读取失败或 completed 任务暂缺 `result_payload_json` 时，本次重试耗尽后仍保留 OSS 工具消息的 `not_completed + externalJobId`，由下次会话读取继续 reconcile；JSON 损坏、结果结构不兼容或 formatter 失败等确定性致命错误在重试耗尽后原子写为 `failed`，保存“重试 3 次后仍失败”的最后错误，避免永久循环。
+- 画布 Agent 是“正式任务 payload 不进入通用用户 read model”规则的窄例外消费者：`GET /api/editor/agent-conversations/{conversationId}` 只按会话中已有的 `externalJobId` 定向读取主任务，完成后由对应工具 formatter 从 `result_payload_json` 提取并归一有界的图片 / 视频 / 音频引用，写入 OSS 工具消息后返回。前端仍不得通过通用任务列表 / 状态接口读取或解析 `request_payload_json` / `result_payload_json`；OSS 轻量媒体引用只是会话展示与后续 Agent 上下文，不替代 `editor_project_resource`、`editor_asset`、`editor_canvas.layers_json` 或 `external_generation_job` 的业务真相。
 
 ### 创作 / 游玩统一流程主干
 
@@ -282,8 +285,8 @@ npm run check:server-rs-ddd
 - Rust 结构体：`ExternalGenerationJob`
 - 源码：`server-rs/crates/spacetime-module/src/external_generation.rs`
 - 用途：外部生成 worker 的内部持久任务队列；`GENARRATIVE_EXTERNAL_GENERATION_MODE=queue` 时，`api-server` HTTP 角色只入队，`external-generation-worker` 角色通过 claim lease 领取、续租、执行，并用 `lease_token` 栅栏回写阶段、完成 / 失败。队列行继续保存 worker 执行、计费与滚动发布兼容所需字段，末尾可选 `phase` 只取 `generating / processing`；claim 写 `generating`，真实进入抠图处理时由受 `job_id + worker_id + lease_token` 保护的 procedure 写 `processing`。phase procedure 以结构化结果区分 `LeaseFencingRejected` 与 `OtherRejected`；`LeaseFencingRejected` 立即终止，`OtherRejected` 以及 SDK 的 `Procedure` / `Runtime` 错误不重试，只有 `Build` / `ConnectDropped` / `Timeout` 在同一个 job attempt 内重试一次。该重试只重新上报 phase，不把任务写回 `pending`，也不重新调用 provider；编辑器 job 入队固定 `max_attempts=1`，第二次传输失败后任务进入 `failed`，不会回到 `pending` 或从 provider 生成起点重跑。用户可见任务列表、价格、状态、阶段、未确认终态数量和通知确认时间的正式读取事实源已经迁到 `external_generation_job_summary`；BFF 不得再为列表 / 详情 / acknowledge 读取该大表。拼图 `compile_puzzle_draft` 的前置 `compile_puzzle_agent_draft`、`generate_puzzle_images` 与 `generate_puzzle_ui_background` 的业务写回也在对应 SpacetimeDB transaction 内校验 `job_id + worker_id + lease_token`、job kind、owner 和 source entity，避免过期 worker 写 session / work profile；图片画布编辑器的 `editor_image_generation`、`editor_image_edit`、`editor_background_removal`、`editor_icon_spritesheet_generation`、`editor_ui_design_asset_extraction`、`editor_character_animation_generation`、`editor_video_generation`、`editor_sound_effect_generation` 和 `editor_background_music_generation` 复用同一队列表，worker 成功后经 `api-server` facade 写入 `editor_project_resource` / `editor_asset` / `editor_canvas.layers_json`，前端只通过 BFF job 状态轮询和项目快照读取恢复完成态。`GENARRATIVE_EXTERNAL_GENERATION_MODE=inline` 时不创建该队列行，三个 external generation guard 字段必须同时为空才允许 api-server 受控同步写回，半空 guard 仍会拒绝。worker 成功写回业务事实后才能 complete job；业务失败态写回成功后才能 fail job，失败态未写回时保留租约等待后续重领。
-- 载荷约束：本次先对 `source_module = editor-canvas` 的 `request_payload_json` / `result_payload_json` 实施有限大小合法 JSON、任意层级禁止 `data:` / `blob:` 的双层门禁，只保存 worker 执行必需的普通参数和已登记媒体引用；其它玩法在完成各自参考图资源化之前不由本次门禁静默改变既有请求契约。该主表只供 worker claim / 执行和受控维护读取；正式用户任务列表、单任务状态、队列概览与 acknowledge 不得再返回或解析这两个 payload。
-- 非阻断告警：角色形象、图标图集和 UI 素材提取已保存 provider 原图、但透明背景处理最终失败时，以原图唯一主图完成任务；透明图和切片不写入画布。这个 source-only 降级只包住透明背景处理的最终失败，phase 上报、provider 原图持久化、透明处理图持久化或画布写回失败仍按任务错误传播。图标 / UI 透明图集成功但自动拆分降级时仍保留透明图集；通用 `warning` 与 `sliceWarning` 互斥。两类成功降级都以既有 `completed` 状态收口，不新增状态值：source-only 的 inline / external v1 响应使用结构化 `warning.code/reason`，仅拆分失败的 inline / external v1 响应继续使用既有 `sliceWarning.code/reason`，其 `reason` 保留原始诊断；queue worker 才把两者归一为有界的 `result_payload_json.warning`，且通用 `warning` 优先并原样保留完整 `reason`，只有 `sliceWarning.reason` 由 worker 添加“图集已生成，但自动拆分未完成：”前缀。队列结果不保存图片、切片列表或媒体 URL。
+- 载荷约束：本次先对 `source_module = editor-canvas` 的 `request_payload_json` / `result_payload_json` 实施有限大小合法 JSON、任意层级禁止 `data:` / `blob:` 的双层门禁，只保存 worker 执行必需的普通参数和已登记媒体引用。画布 Agent 来源的任务可在 `result_payload_json.editor-agent-tool-call-result` 中保存有界的轻量结果和已登记媒体引用，供后端按已有 `externalJobId + owner_user_id` 定向懒回填；其它编辑器任务保持元数据结果，并可保存有界的 `warning.code/reason`。其它玩法在完成各自参考图资源化之前不由本次门禁静默改变既有请求契约。该主表只供 worker claim / 执行、受控维护以及画布 Agent 的定向结果回填读取；正式用户任务列表、单任务状态、队列概览与 acknowledge 不得返回或解析这两个 payload。画布 Agent 懒回填必须经对应工具 formatter 归一为有界轻量媒体引用后写入 OSS 会话，不能把原始 payload 直接透传前端。
+- 非阻断告警：角色形象、图标图集和 UI 素材提取已保存 provider 原图、但透明背景处理最终失败时，以原图唯一主图完成任务；透明图和切片不写入画布。这个 source-only 降级只包住透明背景处理的最终失败，phase 上报、provider 原图持久化、透明处理图持久化或画布写回失败仍按任务错误传播。图标 / UI 透明图集成功但自动拆分降级时仍保留透明图集；通用 `warning` 与 `sliceWarning` 互斥。两类成功降级都以既有 `completed` 状态收口，不新增状态值：source-only 的 inline / external v1 响应使用结构化 `warning.code/reason`，仅拆分失败的 inline / external v1 响应继续使用既有 `sliceWarning.code/reason`，其 `reason` 保留原始诊断；queue worker 才把两者归一为有界的 `result_payload_json.warning`，且通用 `warning` 优先并原样保留完整 `reason`，只有 `sliceWarning.reason` 由 worker 添加“图集已生成，但自动拆分未完成：”前缀。除上述画布 Agent 定向回填的轻量结果外，队列结果不保存图片、切片列表或媒体 URL。
 
 ### `external_generation_job_summary`
 

docs/【编辑器】画布Agent对话面板-2026-07-03.md

@@ -1,6 +1,6 @@
 # 画布Agent对话面板
 
-日期：`2026-07-03`
+日期：`2026-07-16`
 
 ## 定位与边界
 
@@ -8,9 +8,9 @@
 - 它是画布域工具，**不承接玩法创作**、不产出玩法作品或模板，与 `CONTEXT.md` 中「表单/图片输入创作工作台」的 Avoid 边界不冲突。
 - 独立于拼图专用的 `/api/runtime/creative-agent/sessions`（该会话为 api-server 内存态、拼图领域专用，不复用）。
 
-## 能力范围（第一期）
+## 能力范围
 
-对话 Agent 可通过 function-calling 触发以下五类工具，全部复用既有计费收口接口：
+对话 Agent 可通过 function-calling 触发以下八类工具，全部复用既有计费收口接口：
 
 | 工具 | 后端接口 |
 | --- | --- |
@@ -19,19 +19,22 @@
 | 生成角色形象 | 既有角色形象生成入口对应接口 |
 | 生成图标素材 | `POST /api/editor/icon-spritesheets/generations` |
 | 生成 UI 设计图 | 既有 UI 设计图生成入口对应接口 |
+| 生成视频 | `POST /api/editor/videos/generations` |
+| 生成游戏音效 | `POST /api/editor/audios/sound-effects/generations` |
+| 生成背景音乐 | `POST /api/editor/audios/background-music/generations` |
 
 - 意图解析与工具编排在后端 api-server，前端只渲染状态，不承接业务规则。
 - 下面的工具选择口径属于 Agent 规划 prompt / function-calling 约束，不是侧边栏 UI 说明文案；侧边栏面板不展示这些规则解释。
 - 用户要求“规范图 / 视觉规范图 / 风格规范图 / 素材规范展板”时，规划默认选择 `generate_image`，并在 prompt 中明确要求生成规范展板，包含统一视角、线条粗细、色卡、材质、阴影、圆角、状态层级、尺寸标注等可落地的视觉规范元素。
 - 用户要求“角色规范图”且语义是角色的规范展板、风格展板或设定板时，仍走 `generate_image`，不要误分流到 `generate_character`；只有实际生成角色立绘、角色主形象或角色视觉资产时才走 `generate_character`。用户要求多个图标素材、图集或 spritesheet 时才走 `generate_icon_spritesheet`。
 - 所有生成必须走 `execute_billable_asset_operation_with_cost` 与模型定价配置，禁止绕过定价收口。
-- 视频 / 音频 / 图层操作等其余画板功能第一期不进入对话工具面，仍走现有面板。
+- 图层操作及其他未注册的画板功能第一期不进入对话工具面，仍走现有面板。
 
 ## 当前分支落地状态
 
-- 已落地：会话元数据、OSS 消息文档、会话 CRUD、SSE 消息流、后端 LLM 工具规划、右侧对话面板、会话历史、新建 / 软删会话、停止当前 SSE 回合、附件从画布资源 / 账号素材库选择，以及五类图片工具对既有生成入口的复用。
-- 已落地：`tool_started` / `tool_completed` 事件携带 `status`；工具失败时也会写入失败 generation record，并随后发送 `stage=failed` 与 `error`，前端应保留消息内失败条目。
-- 未落地：附件弹窗末尾上传格、跨刷新异步生成恢复、external generation task 轮询回填。未落地前，对话消息状态只表示本次 SSE 回合记录，不作为后台任务队列真相。
+- 已落地：会话元数据、OSS 消息文档、会话 CRUD、带 `clientMessageId` 幂等键的普通 JSON 消息请求、后端 LLM 工具规划、右侧对话面板、会话历史、新建 / 软删会话、附件从画布资源 / 账号素材库选择，以及八类图片 / 音视频工具对既有生成入口的复用。
+- 已落地：工具确认 / 取消、external generation task 轮询与会话懒回填。LLM 未配置、请求失败或规划结果解析失败时，后端把 `role=system`、正文以 `ERROR ` 开头的消息写入 OSS，并通过 `deltaMessages` 返回，`errorMessage` 保持为空；前端隐藏 wire 前缀并以红色错误气泡展示。工具执行失败继续保存 `status=failed`、模型和错误信息，不能只返回瞬时错误。
+- 未落地：附件弹窗末尾上传格。`external_generation_job` 继续作为后台任务队列真相，对话消息只保存确认、回填状态和轻量媒体结果引用。
 
 ## 会话与持久化
 
@@ -39,24 +42,27 @@
 - SpacetimeDB 新表 `editor_agent_conversation` 只存会话元数据：会话 ID、projectId、ownerUserId、标题、软删标记、聊天记录 OSS 对象引用、创建/更新时间。
 - 完整消息内容存 OSS：`editor-agent/{conversationId}.json`，**会话粒度整体读写**（追加消息=重写对象），不按消息拆对象。
 - 不把对话塞进画布工程快照 payload，不在 api-server 内存中保存会话真相。
-- 会话标题：新会话默认「新对话」，首条用户消息发出后自动截取前 N 字作为标题；第一期不做手动重命名。
+- 会话标题：新会话默认「新对话」，首条含文本的用户消息发出后自动截取前 N 字作为标题；列表摘要、详情和消息回包均携带同一必填标题，前端只展示该标题，不以会话 ID 或本地推导兜底。标题写入失败会使该消息请求失败，不能静默继续。
 - 会话删除：列表项 hover 出删除按钮 + 确认；软删（表打 deleted 标记，OSS 对象保留）。
+- 每次用户主动发送生成一个最长 128 字符的 `clientMessageId`；`editorAgentClient` 对网络错误和通用瞬时状态码显式启用 1 次 POST transport 重试，重试复用同一个已序列化 body、`clientMessageId` 和 `x-request-id`。该字段独立于数字 `message.id` 并随用户消息写入 OSS。旧消息缺失时按 `None` 兼容；早期 SSE 文档若把客户端键存成用户消息字符串 `id`，读取时将其迁入 `clientMessageId`，同时重建数字定位符。后端在会话锁内检查重复键：内容一致时返回已持久化的同一回合结果，尚无结果时复用原用户消息继续规划；文本或附件身份不同则返回 `409`，不得再次追加用户消息或调用 LLM。
 
 ## 生成结果落画板（对现有占位规则的例外）
 
-- 对话入口触发的生成**不创建"即将生成"画布占位**（区别于其余生成面板）；生成中状态由对话消息流承载。
-- 生成完成后：结果图按统一 placement 避让模型（视口中心就近、避开现有图层、32px 间距）落画板为新图层，同时登记到默认项目素材库，并在对话消息内显示纯缩略图；前端收到 `generation_result` 后立即刷新工程快照与素材库，缩略图本身不显示名称也不承担图层跳转。
+- 对话入口触发的生成**不创建"即将生成"画布占位**（区别于其余生成面板）；生成中状态由工具消息和外部任务状态承载。
+- 生成完成后：结果图按统一 placement 避让模型（视口中心就近、避开现有图层、32px 间距）落画板为新图层，同时登记到默认项目素材库；前端轮询到任务终态并重新读取会话后，以回填的轻量媒体引用显示纯缩略图并刷新工程快照与素材库，缩略图本身不显示名称也不承担图层跳转。
 - 消息内生成结果缩略图必须携带并优先使用 `objectKey` / `assetObjectId`，前端通过 `ResolvedAssetImage` / `/api/assets/read-url` 换签后渲染，不能把裸 `/generated-*` 私有路径直接交给 `<img>`。
-- 当前第一阶段通过既有编辑器生成 BFF 的 `canvasCompletion` 写回工程快照；刷新后异步任务恢复和轮询回填属于后续能力，不在本阶段声明为已完成。
+- 既有编辑器 worker 通过 `canvasCompletion` 写回工程快照；刷新后由 external generation task 状态和会话懒回填恢复结果。
 - 该例外已同步登记在《生成类面板Lovart统一改造方案-2026-06-17》「画布占位落点」节。
 
 ## 右侧布局
 
 - 对话框与既有任务侧栏（`ImageCanvasTaskSidebarView`）**互斥展开**：展开一个自动收起另一个；各自收起后保留入口按钮。
-- 对话框与左侧素材 / 图层侧栏也互斥：打开画布 Agent 时收起左侧栏；再次打开素材、图层或任务侧栏时收起 Agent 面板。
+- 对话框与左侧素材 / 图层侧栏**不互斥**，允许同时展开，便于在对话中选取和核对画布素材；左侧栏切换不改变 Agent 面板开关状态。
 - 桌面端对话框固定宽约 360–400px；移动端抽屉式全宽覆盖；收起态为胶囊/圆形入口按钮。
 - 会话管理入口在对话框头部：当前会话标题 + 历史会话下拉（按更新时间倒序）+ 新建对话按钮，全部包在对话框内。
-- 收起对话框只是隐藏面板，不卸载当前会话 hook；流式回复、`生成中` 阶段和停止按钮状态必须在收起 / 重新打开之间保持一致。
+- 快速切换会话或会话轮询刷新产生并发详情请求时，前端只允许最后发起的请求更新当前会话、消息、错误和加载态；旧响应不得覆盖用户最新选择。
+- 普通 JSON 消息请求的回包必须绑定发送时的会话：用户在等待期间切换到其他会话后，只更新原会话的列表摘要，不得把原会话的 `deltaMessages` 、错误或画布刷新副作用应用到当前面板。
+- 收起对话框只是隐藏面板，不卸载当前会话 hook；普通 JSON 消息请求的等待态和外部生成任务状态必须在收起 / 重新打开之间保持一致。
 
 ## 附件
 
@@ -68,11 +74,29 @@
 - 应用后附件以胶囊 chip 挂在输入框上方；发出的消息内附件渲染为纯文本胶囊 chip（名称 + 小图标），**默认无缩略图，鼠标悬浮才浮出缩略图预览**。
 - 附件领域形状：统一为画布资源 / 素材库对象引用（`resourceId` / `assetId` + 可选 `objectKey`），不存在只属于对话的第三种图；单条消息上限 9 张（前后端共同校验）。前端可携带展示用 `imageSrc` / `thumbnailSrc`，后端必须按当前工程和当前账号重新归一、校验归属与 `objectKey`。
 
+## 工具调用确认展示契约
+
+- Agent 规划出生成或编辑工具后，先把 `status=not_completed` 且没有 `externalJobId` 的工具消息持久化为待确认记录；确认卡必须在真正调用生成 provider 前展示本次提示词、规格参数、目标图和参考图缩略图，用户确认后才执行，取消后保留同一条 `status=cancelled` 记录。内部 system 文本和图片哈希 ID 不直接展示给用户。
+- 工具消息只保存 `status`（`not_completed` / `completed` / `failed` / `cancelled`）和可选 `externalJobId`。`external_generation_job` 仍是队列、执行、lease 与计费结算真相；OSS status 仅表示该条对话消息是否已经回填完成结果或失败，不复制 queued / running。
+- 确认接口必须先把工具参数转换为既有编辑器 worker payload，再使用 `editor-agent:{conversationId}:{messageId}:{toolName}` 稳定 dedupe key 入队；同一确认的请求重试只能得到同一个 external job。入队成功后把返回的 job id 写回同一条 OSS 工具消息，不新增 Agent 工具执行关联表。
+- 前端根据 `externalJobId` 查询通用 external-generation job 状态；worker 继续通过 `canvasCompletion` 把生成结果写回工程与素材库。浏览器断线、刷新或 api-server 重启不得导致确认接口重新扣费或重新提交 provider。
+- `GET /conversation` 会在同一个 conversation lock 内扫描 `status=not_completed` 且已有 `externalJobId` 的工具消息：只对这些消息按 job id 定向读取主任务；任务完成后复用对应工具的 `format_execute_message` 替换 system text、回填轻量图片 / 视频 / 音频引用并写为 `completed`，任务失败则回填 `error` 并写为 `failed`。任务结果读取或 completed payload 解析 / formatter 回填失败时，必须在同一次 GET 内完成首次尝试及最多 3 次重试，三次重试各间隔 100ms 并重新读取任务结果；仍失败才把该工具消息写为 `failed` 并保存最后错误。该重试不依赖前端再次刷新。排队和执行中都保持 `not_completed`，整轮扫描结果一次性写回 OSS。
+- `EditorAgentToolCall.args` 保留为工具返回的原始 JSON，是确认接口重新反序列化并执行工具的唯一参数真相。图片参数继续只保存由真实 data key 计算出的 opaque SHA-256 `imageId`；不得为了前端预览把 `args` 中的图片 ID 改写成 `objectKey`、URL 或展示对象，也不得由前端重组或回传一份新的执行参数。
+- `EditorAgentToolCall.displayArgs` 是必填、只读的用户确认展示投影，与 `args` 分离：
+  - `stringArgs` 保存提示词、比例、清晰度、模型、时长等可展示参数的稳定名称、用户可见标题和值；
+  - `imageArgs` 按“目标图片 / 参考图片”等参数分组，每个 `refs` 项包含与原始参数对应的 `imageId`，以及后端从已校验会话上下文解析出的 `objectKey`、`imageSrc`、可选 `thumbnailSrc` / `label` / `width` / `height`。
+  - `extras.priceMudPoints` 保存创建待确认消息时按后端运行时模型定价快照计算的预计泥点消耗；前端统一展示为“预计消耗 N泥点”，不自行计算价格。
+- `displayArgs` 只能由 api-server 按已注册 tool 白名单，基于已经通过 ToolArgs 校验的 `args` 和当前 OSS 会话文档中的附件 / 历史生成结果构建；不能信任 LLM 自报的展示地址、标题或素材元数据。展示投影不参与确认执行，确认接口仍只读取同一条持久化 tool call 的 `args`，避免“看到的素材”和“实际执行的素材”分叉。
+- `extras.priceMudPoints` 同样只属于展示投影，不作为扣费输入；确认后仍由既有生成 BFF 按后端运行时定价执行预扣费，因此该字段表达用户确认时看到的价格快照，而不是前端可提交或覆盖的计费真相。
+- `EditorAgentToolCall.summary` 只是 `args` 的重复字符串且没有稳定语义，当前契约删除该字段，不再作为展示或执行输入。
+- 前端待确认卡只消费必填 `displayArgs`，不解析各 tool 私有的 snake_case / camelCase schema，也不把 `sha256:*` ID 当标题或图片地址。图片统一通过 `ResolvedAssetImage` 使用 `objectKey` 换签后显示，签名 URL 不进入消息文档。模块尚未上线，不保留缺少 `displayArgs` 时读取 raw `args` 的旧消息降级路径。
+
 ## LLM 与计费
 
-- 编排复用 `creative_agent_gpt5_client` 的 LLM 接入配置（同 provider/env，独立用途标识），画布 Agent 规划请求固定使用 VectorEngine `gpt-5.4-mini` Chat Completions；function-calling 注册五类工具。
-- 每个用户回合必须由 LLM 返回结构化计划；LLM 未配置、请求失败或返回格式不可解析时，后端写入明确错误消息，不使用本地关键词或“收到：...”回显兜底。
-- 规划 prompt 必须自动带入上一条已完成生成结果的 `latestGeneratedImage` 引用，内容只包含上一轮 generation 的 `summary` / `toolName` / `resourceId` / `objectKey` / `assetObjectId` 等轻量元数据，不把私有签名 URL 或大图内容塞进 prompt。
+- 编排复用 `creative_agent_gpt5_client` 的 LLM 接入配置（同 provider/env，独立用途标识），画布 Agent 规划请求固定使用 VectorEngine `gpt-5.4-mini` Chat Completions；function-calling 注册八类工具。
+- 每个用户回合必须由 LLM 返回结构化计划；LLM 未配置、请求失败或返回格式不可解析时，后端写入正文为 `ERROR <错误内容>` 的 system 消息，不使用本地关键词或“收到：...”回显兜底。该错误消息与其它 system 消息一样进入后续 LLM memory，使 Agent 能看到上一轮失败上下文。
+- 规划 prompt 必须自动带入上一条已完成生成结果的 `latestGeneratedImage` 引用，内容只包含上一轮 generation 的 `toolName` / `resourceId` / `objectKey` / `assetObjectId` 等轻量元数据，不把私有签名 URL 或大图内容塞进 prompt。
+- 工具参数中的图片 ID 是由真实 object key 或图片地址计算的稳定 SHA-256 标识；真实 data key 仅存于 api-server 的工具上下文映射，所有图片工具在执行时查表恢复，不能把 object key 或图片地址作为 LLM 可见的工具 ID。
 - 用户使用「这张」「刚才那个」「上一张」「把衣服换成……」等方式指代或编辑上一张结果图时，LLM 默认选择 `edit_image` 并引用 `latestGeneratedImage` 作为源图；除非用户明确要求全新生成，否则不能因为本轮没有重新上传附件而降级为 `generate_image`。
 - 规划 prompt 必须显式区分“规范展板”和“实际素材产出”：规范图、视觉规范图、风格规范图、素材规范展板、角色规范图等规范展板请求走 `generate_image`，并补齐统一视角、线条粗细、色卡、材质、阴影、圆角、状态层级、尺寸标注等要求；实际角色立绘才走 `generate_character`，多个图标素材 / 图集才走 `generate_icon_spritesheet`。
 - 画布 Agent 规划请求使用 Chat Completions、1024 `max_tokens` 和 60 秒 Agent 专用请求超时；生成图片/编辑图片仍走对应生成工具和模型计费。
@@ -83,13 +107,13 @@
 
 做（第一期）：
 
-1. 助手文本 SSE 流式输出；
-2. 阶段提示行（思考中 → 思考完成 → 生成中 → 完成/失败）；
+1. 助手文本随普通 JSON 消息响应一次性返回；
+2. 消息请求等待态，以及工具任务的待确认、生成中、完成 / 失败状态；
 3. 工具/模型标注行（生成时显示模型名 + 图标）；
 4. 消息内生成结果缩略图（纯预览，不显示名称，不点击聚焦图层）；
 5. 生成中的进行中动画；
 6. 错误气泡（失败/余额不足，带原因）；
-7. 发送中断：进行中时发送按钮变「停止」，可中断当前回合（已提交的生成任务不追回，照常落画板）。
+7. 普通消息请求等待期间禁用发送按钮，不提供客户端停止操作；前端持续等待后端响应，避免后端已持久化消息但前端中断请求后产生会话状态错位。
 
 不做（明确排除，防止后人补齐）：
 
@@ -113,22 +137,22 @@
 - `api-server`：
   - `GET/POST /api/editor/projects/{projectId}/agent-conversations`（列表/新建）；
   - `GET/DELETE /api/editor/agent-conversations/{conversationId}`（详情/软删）；
-  - `POST /api/editor/agent-conversations/{conversationId}/messages/stream`（SSE）；
+  - `POST /api/editor/agent-conversations/{conversationId}/messages`（JSON）；
   - Agent 编排（function-calling 循环、工具内部调既有生成执行链路）放 api-server 编排层，独立文件，不复用 `creative_agent.rs` 内存会话。
-- `shared-contracts` + `packages/shared`：新 `editorAgent` DTO 与 SSE 事件契约（`stage`、`message_delta`、`tool_started`、`tool_completed`、`generation_result`、`error`、`done`）。
+- `shared-contracts` + `packages/shared`：`editorAgent` 会话、消息、工具确认展示与轻量媒体结果 DTO；消息响应返回 `conversation`、`deltaMessages` 和可选 `errorMessage`。
 
 ## 实施顺序
 
 1. 契约与领域规则（shared-contracts / packages/shared + module-editor-agent）；
 2. 存储层（spacetime-module 表 + procedure + migration + spacetime-client + schema check）；
-3. api-server 会话 CRUD + 消息 OSS 读写 + SSE 回显桩（不接 LLM，先保证会话链路端到端真实落库）；
+3. api-server 会话 CRUD + 消息 OSS 读写 + JSON 回显桩（不接 LLM，先保证会话链路端到端真实落库）；
 4. 前端最小纵切（对话框、会话管理、消息流、附件弹窗、侧边栏/小地图默认值）——可与 3 并行：3 只碰 `server-rs/`，4 只碰 `src/` 且先以契约 mock 客户端联调，汇合点在 4 末接真实 API；
-5. LLM 编排 + 五类工具接入 + 生成落画板 + 停止/错误态（替换回显桩这一个点）；
+5. LLM 编排 + 八类工具接入 + 生成落画板 + 请求等待 / 错误态（替换回显桩这一个点）；
 6. 验证与文档：定向测试、类型检查、`npm run check:encoding`、`git diff --check`、`npm run check:spacetime-schema`、api-server smoke `/healthz`；同步 `CONTEXT.md` 与相关文档。
 
 ## 第一阶段验收补充
 
-- 打开画布 Agent 后，任务侧栏和左侧素材 / 图层面板应关闭；再次打开任务侧栏或素材 / 图层面板时，Agent 面板应关闭。
-- 发送消息时先本地追加用户消息，再消费 SSE 增量；停止按钮只中断当前 SSE 回合，不追回已经提交的生成工具调用。
-- Agent 消息内生成结果缩略图只用于预览，不显示名称，也不点击跳转图层；收到 `generation_result` 时统一刷新工程快照和素材库。
+- 打开画布 Agent 后任务侧栏应关闭，再次打开任务侧栏时 Agent 面板应关闭；素材 / 图层面板与 Agent 可同时展开，互不改写开关状态。
+- 发送消息时先本地追加用户消息，再应用 JSON 响应中的 `deltaMessages`；请求等待期间发送按钮保持禁用，前端不主动中断当前回合。
+- Agent 消息内生成结果缩略图只用于预览，不显示名称，也不点击跳转图层；轮询到任务终态并完成会话懒回填后统一刷新工程快照和素材库。
 - 对话内容可被用户选中复制；用户从输入框或对话内容点击回画布图层 / 生成器时，焦点应回到画布对象，Backspace / Delete 等画布快捷键继续生效。

packages/shared/src/contracts/editorAgent.ts

@@ -1,38 +1,18 @@
 // 画布Agent对话契约：会话元数据存 SpacetimeDB，消息正文整体存 OSS（editor-agent/{conversationId}.json）。
 
 export const EDITOR_AGENT_MAX_ATTACHMENTS = 9;
-export const EDITOR_AGENT_TITLE_MAX_CHARS = 20;
-export const EDITOR_AGENT_DEFAULT_CONVERSATION_TITLE = '新对话';
-export const EDITOR_AGENT_MESSAGES_DOCUMENT_VERSION = 1;
+export const EDITOR_AGENT_ERROR_MESSAGE_PREFIX = 'ERROR ';
 
-export type EditorAgentStage =
-  | 'idle'
-  | 'thinking'
-  | 'responding'
-  | 'generating'
-  | 'completed'
-  | 'failed';
+export type EditorAgentMessageRole = 'user' | 'assistant' | 'system';
 
-export type EditorAgentMessageRole = 'user' | 'assistant';
-
-export type EditorAgentMessageKind = 'chat' | 'stage' | 'error';
-
-export type EditorAgentMessageStatus =
-  | 'streaming'
-  | 'generating'
+export type EditorAgentToolCallStatus =
+  | 'not_completed'
   | 'completed'
   | 'failed'
-  | 'stopped';
+  | 'cancelled';
 
 export type EditorAgentAttachmentSource = 'canvas_resource' | 'library_asset';
 
-export type EditorAgentToolName =
-  | 'generate_image'
-  | 'edit_image'
-  | 'generate_character'
-  | 'generate_icon_spritesheet'
-  | 'generate_ui_design';
-
 export interface EditorAgentAttachmentRef {
   source: EditorAgentAttachmentSource;
   referenceId: string;
@@ -45,36 +25,87 @@ export interface EditorAgentAttachmentRef {
 }
 
 export interface EditorAgentGeneratedImage {
-  resourceId: string | null;
+  resourceId?: string | null;
   objectKey?: string | null;
   assetObjectId?: string | null;
   imageSrc: string;
-  thumbnailSrc: string | null;
-  width: number | null;
-  height: number | null;
+  thumbnailSrc?: string | null;
+  width?: number | null;
+  height?: number | null;
 }
 
-export type EditorAgentGenerationStatus = 'generating' | 'completed' | 'failed';
+export interface EditorAgentGeneratedVideo {
+  resourceId?: string | null;
+  objectKey?: string | null;
+  assetObjectId?: string | null;
+  videoSrc: string;
+  thumbnailSrc?: string | null;
+  width?: number | null;
+  height?: number | null;
+}
 
-export interface EditorAgentGenerationRecord {
-  toolCallId: string;
-  toolName: EditorAgentToolName;
-  summary?: string | null;
-  taskId: string | null;
-  status: EditorAgentGenerationStatus;
-  model: string | null;
+export interface EditorAgentGeneratedAudio {
+  resourceId?: string | null;
+  objectKey?: string | null;
+  assetObjectId?: string | null;
+  audioSrc: string;
+}
+
+export interface EditorAgentToolCallStringArg {
+  name: string;
+  label: string;
+  value: string;
+}
+
+export interface EditorAgentToolCallImageRef {
+  imageId: string;
+  imageSrc: string;
+  objectKey?: string | null;
+  thumbnailSrc?: string | null;
+  label?: string | null;
+  width?: number | null;
+  height?: number | null;
+}
+
+export interface EditorAgentToolCallImageArg {
+  name: string;
+  label: string;
+  refs: EditorAgentToolCallImageRef[];
+}
+
+export interface EditorAgentToolCallDisplayExtras {
+  priceMudPoints: number;
+}
+
+export interface EditorAgentToolCallDisplayArgs {
+  stringArgs: EditorAgentToolCallStringArg[];
+  imageArgs: EditorAgentToolCallImageArg[];
+  extras: EditorAgentToolCallDisplayExtras;
+}
+
+export interface EditorAgentToolCall {
+  toolName: string;
+  status: EditorAgentToolCallStatus;
+  args: unknown;
+  displayArgs: EditorAgentToolCallDisplayArgs;
+  externalJobId?: string | null;
   images: EditorAgentGeneratedImage[];
+  // Older persisted conversation documents do not contain these media fields.
+  videos?: EditorAgentGeneratedVideo[];
+  audios?: EditorAgentGeneratedAudio[];
   error?: string | null;
 }
 
 export interface EditorAgentMessage {
-  id: string;
+  // Frontend must not use this to organize messages.
+  // It is an opaque backend locator for pending tool-call operations.
+  id: number;
+  // Present only on user messages created from a client send request.
+  clientMessageId?: string | null;
   role: EditorAgentMessageRole;
-  kind: EditorAgentMessageKind;
   text: string;
   attachments: EditorAgentAttachmentRef[];
-  generations: EditorAgentGenerationRecord[];
-  status: EditorAgentMessageStatus;
+  toolCall: EditorAgentToolCall | null;
   createdAt: string;
 }
 
@@ -82,12 +113,15 @@ export interface EditorAgentConversationSummary {
   conversationId: string;
   projectId: string;
   title: string;
-  createdAt: string;
   updatedAt: string;
 }
 
-export interface EditorAgentConversationDetail
-  extends EditorAgentConversationSummary {
+export interface EditorAgentConversationDetail {
+  conversationId: string;
+  projectId: string;
+  title: string;
+  createdAt: string;
+  updatedAt: string;
   messages: EditorAgentMessage[];
 }
 
@@ -109,63 +143,14 @@ export interface EditorAgentConversationResponse {
   conversation: EditorAgentConversationDetail;
 }
 
-export interface StreamEditorAgentMessageRequest {
+export interface EditorAgentMessageRequest {
   clientMessageId: string;
   text: string;
   attachments?: EditorAgentAttachmentRef[];
 }
 
-export interface EditorAgentStageEvent {
-  conversationId: string;
-  stage: EditorAgentStage;
+export interface EditorAgentMessageResponse {
+  conversation: EditorAgentConversationSummary;
+  deltaMessages: EditorAgentMessage[];
+  errorMessage: string | null;
 }
-
-export interface EditorAgentMessageDeltaEvent {
-  conversationId: string;
-  messageId: string;
-  role: EditorAgentMessageRole;
-  kind: EditorAgentMessageKind;
-  textDelta: string;
-}
-
-export interface EditorAgentToolEvent {
-  conversationId: string;
-  messageId: string;
-  toolCallId: string;
-  toolName: EditorAgentToolName;
-  summary?: string | null;
-  taskId?: string | null;
-  model?: string | null;
-  status?: EditorAgentGenerationStatus | null;
-  error?: string | null;
-}
-
-export interface EditorAgentGenerationResultEvent {
-  conversationId: string;
-  messageId: string;
-  toolCallId: string;
-  toolName: EditorAgentToolName;
-  model: string | null;
-  images: EditorAgentGeneratedImage[];
-}
-
-export interface EditorAgentErrorEvent {
-  conversationId: string | null;
-  code: string;
-  message: string;
-  recoverable: boolean;
-}
-
-export interface EditorAgentDoneEvent {
-  conversationId: string;
-  title: string | null;
-}
-
-export type EditorAgentSseEvent =
-  | { event: 'stage'; data: EditorAgentStageEvent }
-  | { event: 'message_delta'; data: EditorAgentMessageDeltaEvent }
-  | { event: 'tool_started'; data: EditorAgentToolEvent }
-  | { event: 'tool_completed'; data: EditorAgentToolEvent }
-  | { event: 'generation_result'; data: EditorAgentGenerationResultEvent }
-  | { event: 'error'; data: EditorAgentErrorEvent }
-  | { event: 'done'; data: EditorAgentDoneEvent };

scripts/dev.mjs

@@ -921,7 +921,8 @@ function readLinuxApiServerProcessSnapshot(pid) {
     if (
       error?.code === 'ENOENT' ||
       error?.code === 'EACCES' ||
-      error?.code === 'EPERM'
+      error?.code === 'EPERM'  ||
+      error?.code === 'ESRCH'
     ) {
       return null;
     }

server-rs/Cargo.lock

@@ -238,6 +238,7 @@ dependencies = [
  "platform-agent",
  "platform-audio",
  "platform-auth",
+ "platform-editor-agent",
  "platform-hyper3d",
  "platform-image",
  "platform-llm",
@@ -4441,6 +4442,19 @@ dependencies = [
  "urlencoding",
 ]
 
+[[package]]
+name = "platform-editor-agent"
+version = "0.1.0"
+dependencies = [
+ "hmac",
+ "platform-agent",
+ "platform-llm",
+ "serde",
+ "serde_json",
+ "sha2",
+ "shared-contracts",
+]
+
 [[package]]
 name = "platform-hyper3d"
 version = "0.1.0"

server-rs/Cargo.toml

@@ -42,6 +42,7 @@ members = [
     "crates/platform-wechat",
     "crates/platform-speech",
     "crates/platform-agent",
+    "crates/platform-editor-agent",
     "crates/pingora-gateway",
     "crates/server-manager-panel",
     "crates/shared-contracts",
@@ -84,6 +85,7 @@ module-square-hole = { path = "crates/module-square-hole", default-features = fa
 module-story = { path = "crates/module-story", default-features = false }
 module-visual-novel = { path = "crates/module-visual-novel", default-features = false }
 platform-agent = { path = "crates/platform-agent", default-features = false }
+platform-editor-agent = { path = "crates/platform-editor-agent", default-features = false }
 platform-auth = { path = "crates/platform-auth", default-features = false }
 platform-audio = { path = "crates/platform-audio", default-features = false }
 platform-hyper3d = { path = "crates/platform-hyper3d", default-features = false }

server-rs/crates/api-server/Cargo.toml

@@ -38,6 +38,7 @@ module-square-hole = { workspace = true }
 module-story = { workspace = true }
 module-visual-novel = { workspace = true }
 platform-agent = { workspace = true }
+platform-editor-agent = { workspace = true }
 platform-audio = { workspace = true }
 platform-auth = { workspace = true }
 platform-hyper3d = { workspace = true }

server-rs/crates/api-server/src/editor_agent/context.rs

@@ -0,0 +1,37 @@
+use platform_editor_agent::agent::tools::context::EditorToolContext;
+use crate::editor_agent::utils::IntoDataKey;
+use shared_contracts::editor_agent::EditorAgentConversationMessagesDocument;
+use std::collections::HashMap;
+use platform_editor_agent::agent::asset::{ImageId, ImageMetadata};
+
+pub fn build_tool_context(document: &EditorAgentConversationMessagesDocument) -> EditorToolContext {
+    let mut images: HashMap<ImageId, ImageMetadata> = HashMap::new();
+
+    for msg in document.messages.iter().rev() {
+        // tool gen
+        if let Some(tc) = &msg.tool_call {
+            for img in &tc.images {
+                let data_key = img.clone().into_data_key();
+                let image_id = ImageId::from_data_key(&data_key);
+                let metadata = ImageMetadata {
+                    tag: String::new(),
+                    data_key,
+                };
+                images.insert(image_id, metadata);
+            }
+        }
+
+        // user pointed
+        for a in &msg.attachments {
+            let data_key = a.clone().into_data_key();
+            let image_id = ImageId::from_data_key(&data_key);
+            let metadata = ImageMetadata {
+                tag: String::new(),
+                data_key,
+            };
+            images.insert(image_id, metadata);
+        }
+    }
+
+    EditorToolContext { images }
+}

server-rs/crates/api-server/src/editor_agent/display_args.rs

@@ -0,0 +1,315 @@
+use serde_json::Value;
+use platform_editor_agent::framework::error::PromptError;
+use platform_editor_agent::framework::tool::Tool;
+use shared_contracts::editor_agent::{EditorAgentConversationMessagesDocument, EditorAgentToolCallDisplayArgs, EditorAgentToolCallDisplayExtras, EditorAgentToolCallImageArg, EditorAgentToolCallImageRef, EditorAgentToolCallStringArg};
+use crate::editor_agent::pricing::EditorAgentPricedTool;
+use platform_editor_agent::agent::tools::context::EditorToolContext;
+use platform_editor_agent::agent::tools::edit_image::{EditImageTool, EditImageToolArgs};
+use platform_editor_agent::agent::tools::generate_background_music::{GenerateBackgroundMusicTool, GenerateBackgroundMusicToolArgs};
+use platform_editor_agent::agent::tools::generate_character::GenerateCharacterTool;
+use platform_editor_agent::agent::tools::generate_icon_spritesheet::{GenerateIconSpritesheetTool, GenerateIconSpritesheetToolArgs};
+use platform_editor_agent::agent::tools::generate_image::{GenerateImageTool, GenerateImageToolArgs};
+use platform_editor_agent::agent::tools::generate_sound_effect::{GenerateSoundEffectTool, GenerateSoundEffectToolArgs};
+use platform_editor_agent::agent::tools::generate_ui_design::GenerateUiDesignTool;
+use platform_editor_agent::agent::tools::generate_video::{GenerateVideoTool, GenerateVideoToolArgs};
+use platform_editor_agent::agent::asset::ImageId;
+use crate::editor_agent::utils::{IntoDataKey, IntoImageId};
+use crate::editor_generation_config::EditorGenerationPricingConfig;
+
+pub fn build_tool_call_display_args(
+    tool_name: &str,
+    args: &Value,
+    document: &EditorAgentConversationMessagesDocument,
+    tool_context: &EditorToolContext,
+    pricing: &EditorGenerationPricingConfig,
+) -> Result<EditorAgentToolCallDisplayArgs, PromptError> {
+    let mut display_args = EditorAgentToolCallDisplayArgs::default();
+
+    let price_mud_points = match tool_name {
+        EditImageTool::NAME => {
+            let args: EditImageToolArgs = parse_display_tool_args(tool_name, args)?;
+            let price_mud_points = EditImageTool {
+                context: tool_context.clone(),
+            }
+            .pricing(pricing, &args);
+            push_string_display_arg(&mut display_args, "prompt", "修改要求", args.prompt);
+            push_image_display_arg(
+                &mut display_args,
+                document,
+                "object_image_id",
+                "目标图片",
+                std::slice::from_ref(&args.object_image_id),
+            )?;
+            push_image_display_arg(
+                &mut display_args,
+                document,
+                "reference_image_ids",
+                "参考图片",
+                args.reference_image_ids.as_slice(),
+            )?;
+            price_mud_points
+        }
+        GenerateImageTool::NAME | GenerateCharacterTool::NAME | GenerateUiDesignTool::NAME => {
+            let args: GenerateImageToolArgs = parse_display_tool_args(tool_name, args)?;
+            let price_mud_points = match tool_name {
+                GenerateImageTool::NAME => GenerateImageTool {
+                    context: tool_context.clone(),
+                }
+                .pricing(pricing, &args),
+                GenerateCharacterTool::NAME => GenerateCharacterTool {
+                    context: tool_context.clone(),
+                }
+                .pricing(pricing, &args),
+                GenerateUiDesignTool::NAME => GenerateUiDesignTool {
+                    context: tool_context.clone(),
+                }
+                .pricing(pricing, &args),
+                _ => unreachable!("tool name was matched above"),
+            };
+            push_string_display_arg(&mut display_args, "prompt", "提示词", args.prompt);
+            push_optional_string_display_arg(
+                &mut display_args,
+                "aspect_ratio",
+                "画面比例",
+                args.aspect_ratio,
+            );
+            push_optional_string_display_arg(
+                &mut display_args,
+                "image_size",
+                "图片尺寸",
+                args.image_size,
+            );
+            push_image_display_arg(
+                &mut display_args,
+                document,
+                "reference_image_ids",
+                "参考图片",
+                args.reference_image_ids.as_slice(),
+            )?;
+            price_mud_points
+        }
+        GenerateIconSpritesheetTool::NAME => {
+            let args: GenerateIconSpritesheetToolArgs = parse_display_tool_args(tool_name, args)?;
+            let price_mud_points = GenerateIconSpritesheetTool {
+                context: tool_context.clone(),
+            }
+            .pricing(pricing, &args);
+            push_string_display_arg(
+                &mut display_args,
+                "icon_descriptions",
+                "图标描述",
+                args.icon_descriptions.join("\n"),
+            );
+            push_optional_string_display_arg(
+                &mut display_args,
+                "aspect_ratio",
+                "图集比例",
+                args.aspect_ratio,
+            );
+            push_optional_string_display_arg(
+                &mut display_args,
+                "image_size",
+                "图片尺寸",
+                args.image_size,
+            );
+            push_image_display_arg(
+                &mut display_args,
+                document,
+                "reference_image_id",
+                "规范参考图",
+                std::slice::from_ref(&args.reference_image_id),
+            )?;
+            push_image_display_arg(
+                &mut display_args,
+                document,
+                "reference_image_ids",
+                "额外参考图",
+                args.reference_image_ids.as_slice(),
+            )?;
+            price_mud_points
+        }
+        GenerateVideoTool::NAME => {
+            let args: GenerateVideoToolArgs = parse_display_tool_args(tool_name, args)?;
+            let price_mud_points = GenerateVideoTool {
+                context: tool_context.clone(),
+            }
+            .pricing(pricing, &args);
+            push_string_display_arg(&mut display_args, "prompt", "视频描述", args.prompt);
+            push_optional_string_display_arg(
+                &mut display_args,
+                "aspect_ratio",
+                "画面比例",
+                args.aspect_ratio,
+            );
+            if let Some(duration_seconds) = args.duration_seconds {
+                push_string_display_arg(
+                    &mut display_args,
+                    "duration_seconds",
+                    "时长（秒）",
+                    duration_seconds.to_string(),
+                );
+            }
+            push_optional_string_display_arg(&mut display_args, "model", "模型", args.model);
+            push_optional_string_display_arg(
+                &mut display_args,
+                "resolution",
+                "分辨率",
+                args.resolution,
+            );
+            push_optional_string_display_arg(&mut display_args, "sound", "声音", args.sound);
+            push_image_display_arg(
+                &mut display_args,
+                document,
+                "reference_image_ids",
+                "参考图片",
+                args.reference_image_ids.as_slice(),
+            )?;
+            price_mud_points
+        }
+        GenerateSoundEffectTool::NAME => {
+            let args: GenerateSoundEffectToolArgs = parse_display_tool_args(tool_name, args)?;
+            let price_mud_points = GenerateSoundEffectTool.pricing(pricing, &args);
+            push_string_display_arg(&mut display_args, "prompt", "音效描述", args.prompt);
+            if let Some(duration) = args.duration {
+                push_string_display_arg(
+                    &mut display_args,
+                    "duration",
+                    "时长（秒）",
+                    duration.to_string(),
+                );
+            }
+            price_mud_points
+        }
+        GenerateBackgroundMusicTool::NAME => {
+            let args: GenerateBackgroundMusicToolArgs = parse_display_tool_args(tool_name, args)?;
+            let price_mud_points = GenerateBackgroundMusicTool.pricing(pricing, &args);
+            push_string_display_arg(&mut display_args, "prompt", "音乐描述", args.prompt);
+            push_string_display_arg(
+                &mut display_args,
+                "make_instrumental",
+                "纯音乐",
+                if args.make_instrumental { "是" } else { "否" },
+            );
+            price_mud_points
+        }
+        _ => {
+            return Err(PromptError::InternalError(format!(
+                "missing display argument mapping for tool {tool_name}"
+            )));
+        }
+    };
+
+    display_args.extras = EditorAgentToolCallDisplayExtras { price_mud_points };
+
+    Ok(display_args)
+}
+
+fn parse_display_tool_args<T>(tool_name: &str, args: &Value) -> Result<T, PromptError>
+where
+    T: serde::de::DeserializeOwned,
+{
+    serde_json::from_value(args.clone()).map_err(|error| {
+        PromptError::InternalError(format!(
+            "failed to build display arguments for {tool_name}: {error}"
+        ))
+    })
+}
+
+fn push_string_display_arg(
+    display_args: &mut EditorAgentToolCallDisplayArgs,
+    name: &str,
+    label: &str,
+    value: impl Into<String>,
+) {
+    let value = value.into();
+    if value.trim().is_empty() {
+        return;
+    }
+    display_args.string_args.push(EditorAgentToolCallStringArg {
+        name: name.to_string(),
+        label: label.to_string(),
+        value,
+    });
+}
+
+fn push_optional_string_display_arg(
+    display_args: &mut EditorAgentToolCallDisplayArgs,
+    name: &str,
+    label: &str,
+    value: Option<String>,
+) {
+    if let Some(value) = value {
+        push_string_display_arg(display_args, name, label, value);
+    }
+}
+
+fn push_image_display_arg(
+    display_args: &mut EditorAgentToolCallDisplayArgs,
+    document: &EditorAgentConversationMessagesDocument,
+    name: &str,
+    label: &str,
+    image_ids: &[ImageId],
+) -> Result<(), PromptError> {
+    if image_ids.is_empty() {
+        return Ok(());
+    }
+
+    let refs = image_ids
+        .iter()
+        .map(|image_id| {
+            resolve_tool_call_image_ref(document, image_id).ok_or_else(|| {
+                PromptError::InternalError(format!(
+                    "display image reference {} is missing from conversation context",
+                    image_id.id
+                ))
+            })
+        })
+        .collect::<Result<Vec<_>, _>>()?;
+
+    display_args.image_args.push(EditorAgentToolCallImageArg {
+        name: name.to_string(),
+        label: label.to_string(),
+        refs,
+    });
+    Ok(())
+}
+
+pub fn resolve_tool_call_image_ref(
+    document: &EditorAgentConversationMessagesDocument,
+    image_id: &ImageId,
+) -> Option<EditorAgentToolCallImageRef> {
+    for message in document.messages.iter().rev() {
+        for attachment in message.attachments.iter().rev() {
+            if attachment.clone().into_image_id() == *image_id {
+                return Some(EditorAgentToolCallImageRef {
+                    image_id: image_id.id.clone(),
+                    image_src: attachment.image_src.clone(),
+                    object_key: attachment.object_key.clone(),
+                    thumbnail_src: attachment.thumbnail_src.clone(),
+                    label: attachment.label.clone(),
+                    width: attachment.width,
+                    height: attachment.height,
+                });
+            }
+        }
+
+        if let Some(tool_call) = &message.tool_call {
+            for image in tool_call.images.iter().rev() {
+                let data_key = image.clone().into_data_key();
+                if ImageId::from_data_key(data_key) == *image_id {
+                    return Some(EditorAgentToolCallImageRef {
+                        image_id: image_id.id.clone(),
+                        image_src: image.image_src.clone(),
+                        object_key: image.object_key.clone(),
+                        thumbnail_src: image.thumbnail_src.clone(),
+                        label: None,
+                        width: image.width,
+                        height: image.height,
+                    });
+                }
+            }
+        }
+    }
+
+    None
+}

server-rs/crates/api-server/src/editor_agent/mod.rs

@@ -0,0 +1,13 @@
+mod utils;
+pub mod api;
+mod display_args;
+mod context;
+mod resp_to_asset;
+mod reconcile;
+pub mod pricing;
+
+pub use api::{
+  cancel_editor_agent_tool_call, confirm_editor_agent_tool_call,
+  create_editor_agent_conversation, delete_editor_agent_conversation,
+  get_editor_agent_conversation, list_editor_agent_conversations,
+};

server-rs/crates/api-server/src/editor_agent/pricing.rs

@@ -0,0 +1,315 @@
+use crate::editor_generation_config::{
+    EditorGenerationPricingConfig,
+};
+#[cfg(test)]
+use crate::editor_generation_config::load_editor_generation_pricing_from_paths;
+#[cfg(test)]
+use platform_editor_agent::agent::asset::ImageId;
+#[cfg(test)]
+use platform_editor_agent::agent::tools::context::EditorToolContext;
+use platform_editor_agent::agent::tools::edit_image::{EditImageTool, EditImageToolArgs};
+use platform_editor_agent::agent::tools::generate_background_music::{
+    GenerateBackgroundMusicTool, GenerateBackgroundMusicToolArgs,
+};
+use platform_editor_agent::agent::tools::generate_character::GenerateCharacterTool;
+use platform_editor_agent::agent::tools::generate_icon_spritesheet::{
+    GenerateIconSpritesheetTool, GenerateIconSpritesheetToolArgs,
+};
+use platform_editor_agent::agent::tools::generate_image::{
+    GenerateImageTool, GenerateImageToolArgs,
+};
+use platform_editor_agent::agent::tools::generate_sound_effect::{
+    GenerateSoundEffectTool, GenerateSoundEffectToolArgs,
+};
+use platform_editor_agent::agent::tools::generate_ui_design::GenerateUiDesignTool;
+use platform_editor_agent::agent::tools::generate_video::{
+    GenerateVideoTool, GenerateVideoToolArgs,
+};
+use platform_editor_agent::framework::tool::Tool;
+use platform_image::GPT_IMAGE_2_MODEL;
+#[cfg(test)]
+use std::collections::HashMap;
+
+#[cfg(test)]
+fn context() -> EditorToolContext {
+    EditorToolContext {
+        images: HashMap::new(),
+    }
+}
+
+#[cfg(test)]
+fn image_args(image_size: Option<&str>) -> GenerateImageToolArgs {
+    GenerateImageToolArgs {
+        prompt: "生成图片".to_string(),
+        reference_image_ids: Vec::new(),
+        aspect_ratio: Some("1:1".to_string()),
+        image_size: image_size.map(ToOwned::to_owned),
+    }
+}
+
+#[test]
+fn every_editor_agent_tool_exposes_argument_based_pricing() {
+    let pricing = load_editor_generation_pricing_from_paths(None)
+        .expect("default editor pricing should load");
+    let context = context();
+
+    assert_eq!(
+        EditImageTool {
+            context: context.clone(),
+        }
+        .pricing(
+            &pricing,
+            &EditImageToolArgs {
+                object_image_id: ImageId {
+                    id: "image-1".to_string(),
+                },
+                reference_image_ids: Vec::new(),
+                prompt: "改成蓝色".to_string(),
+            },
+        ),
+        3
+    );
+    assert_eq!(
+        GenerateImageTool {
+            context: context.clone(),
+        }
+        .pricing(&pricing, &image_args(Some("2K"))),
+        5
+    );
+    assert_eq!(
+        GenerateCharacterTool {
+            context: context.clone(),
+        }
+        .pricing(&pricing, &image_args(None)),
+        3
+    );
+    assert_eq!(
+        GenerateUiDesignTool {
+            context: context.clone(),
+        }
+        .pricing(&pricing, &image_args(Some("2K"))),
+        5
+    );
+    assert_eq!(
+        GenerateIconSpritesheetTool {
+            context: context.clone(),
+        }
+        .pricing(
+            &pricing,
+            &GenerateIconSpritesheetToolArgs {
+                reference_image_id: ImageId {
+                    id: "image-1".to_string(),
+                },
+                reference_image_ids: Vec::new(),
+                icon_descriptions: vec!["背包".to_string(), "地图".to_string()],
+                aspect_ratio: Some("1:1".to_string()),
+                image_size: Some("2K".to_string()),
+            },
+        ),
+        5
+    );
+    assert_eq!(
+        GenerateVideoTool {
+            context: context.clone(),
+        }
+        .pricing(
+            &pricing,
+            &GenerateVideoToolArgs {
+                prompt: "镜头缓慢推进".to_string(),
+                reference_image_ids: Vec::new(),
+                aspect_ratio: None,
+                duration_seconds: Some(6),
+                model: Some("seedance2.0".to_string()),
+                resolution: Some("720p".to_string()),
+                sound: None,
+            },
+        ),
+        144
+    );
+    assert_eq!(
+        GenerateSoundEffectTool.pricing(
+            &pricing,
+            &GenerateSoundEffectToolArgs {
+                prompt: "按钮点击声".to_string(),
+                duration: None,
+            },
+        ),
+        5
+    );
+    assert_eq!(
+        GenerateBackgroundMusicTool.pricing(
+            &pricing,
+            &GenerateBackgroundMusicToolArgs {
+                prompt: "轻松背景音乐".to_string(),
+                make_instrumental: true,
+            },
+        ),
+        12
+    );
+}
+
+#[test]
+fn pricing_uses_the_supplied_runtime_snapshot() {
+    let mut pricing = load_editor_generation_pricing_from_paths(None)
+        .expect("default editor pricing should load");
+    pricing
+        .models
+        .get_mut("gpt-image-2")
+        .expect("gpt image pricing should exist")
+        .prices
+        .insert("2K".to_string(), 37);
+    pricing
+        .models
+        .get_mut("seedance2.0-fast")
+        .expect("video pricing should exist")
+        .prices
+        .insert("720p".to_string(), 7);
+    pricing
+        .models
+        .get_mut("audio1.0")
+        .expect("sound pricing should exist")
+        .price = Some(19);
+
+    assert_eq!(
+        GenerateImageTool { context: context() }.pricing(&pricing, &image_args(Some("2K"))),
+        37
+    );
+    assert_eq!(
+        GenerateVideoTool { context: context() }.pricing(
+            &pricing,
+            &GenerateVideoToolArgs {
+                prompt: "four seconds".to_string(),
+                reference_image_ids: Vec::new(),
+                aspect_ratio: None,
+                duration_seconds: None,
+                model: None,
+                resolution: None,
+                sound: None,
+            },
+        ),
+        28
+    );
+    assert_eq!(
+        GenerateSoundEffectTool.pricing(
+            &pricing,
+            &GenerateSoundEffectToolArgs {
+                prompt: "sound".to_string(),
+                duration: None,
+            },
+        ),
+        19
+    );
+}
+
+impl EditorAgentPricedTool for GenerateVideoTool {
+    fn pricing(
+        &self,
+        pricing: &EditorGenerationPricingConfig,
+        args: &GenerateVideoToolArgs,
+    ) -> u32 {
+        let model = args
+            .model
+            .as_deref()
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+            .unwrap_or(Self::DEFAULT_VIDEO_MODEL);
+        let resolution = args
+            .resolution
+            .as_deref()
+            .map(str::trim)
+            .filter(|value| !value.is_empty())
+            .unwrap_or(Self::DEFAULT_VIDEO_RESOLUTION);
+        let duration_seconds = args
+            .duration_seconds
+            .unwrap_or(Self::DEFAULT_VIDEO_DURATION_SECONDS);
+        pricing.video_model_mud_points(Some(model), resolution, duration_seconds)
+    }
+}
+
+impl EditorAgentPricedTool for GenerateUiDesignTool {
+    fn pricing(
+        &self,
+        pricing: &EditorGenerationPricingConfig,
+        args: &GenerateImageToolArgs,
+    ) -> u32 {
+        editor_agent_image_mud_points(pricing, Some("ui-design"), args.image_size.as_deref())
+    }
+}
+
+impl EditorAgentPricedTool for GenerateSoundEffectTool {
+    fn pricing(
+        &self,
+        pricing: &EditorGenerationPricingConfig,
+        _args: &GenerateSoundEffectToolArgs,
+    ) -> u32 {
+        pricing.sound_effect_model_mud_points(None)
+    }
+}
+
+impl EditorAgentPricedTool for GenerateImageTool {
+    fn pricing(
+        &self,
+        pricing: &EditorGenerationPricingConfig,
+        args: &GenerateImageToolArgs,
+    ) -> u32 {
+        editor_agent_image_mud_points(pricing, None, args.image_size.as_deref())
+    }
+}
+
+impl EditorAgentPricedTool for GenerateIconSpritesheetTool {
+    fn pricing(
+        &self,
+        pricing: &EditorGenerationPricingConfig,
+        args: &GenerateIconSpritesheetToolArgs,
+    ) -> u32 {
+        editor_agent_image_mud_points(pricing, Some("icon"), args.image_size.as_deref())
+    }
+}
+
+impl EditorAgentPricedTool for GenerateCharacterTool {
+    fn pricing(
+        &self,
+        pricing: &EditorGenerationPricingConfig,
+        args: &GenerateImageToolArgs,
+    ) -> u32 {
+        editor_agent_image_mud_points(pricing, Some("character"), args.image_size.as_deref())
+    }
+}
+
+/// api-server 侧的画布 Agent 工具计价扩展。
+///
+/// 通用 `Tool` 仍只负责参数校验；价格依赖 api-server 的运行时配置，不能下沉到
+/// `module-editor-agent`。实际执行和扣费仍由既有生成 BFF 负责。
+pub(crate) trait EditorAgentPricedTool: Tool {
+    fn pricing(&self, pricing: &EditorGenerationPricingConfig, args: &<Self as Tool>::Args) -> u32;
+}
+
+pub(crate) fn editor_agent_image_mud_points(
+    pricing: &EditorGenerationPricingConfig,
+    kind: Option<&str>,
+    image_size: Option<&str>,
+) -> u32 {
+    // 这些 Agent 工具当前向既有 BFF 传 model=None；BFF 会先归一为 gpt-image-2。
+    // 尺寸同样只把精确的 2K 识别为 2K，其余值回落到 1K。
+    let normalized_image_size = match image_size.map(str::trim) {
+        Some("2K") => "2K",
+        _ => "1K",
+    };
+    pricing.image_generation_mud_points(kind, Some(GPT_IMAGE_2_MODEL), Some(normalized_image_size))
+}
+
+impl EditorAgentPricedTool for GenerateBackgroundMusicTool {
+    fn pricing(
+        &self,
+        pricing: &EditorGenerationPricingConfig,
+        _args: &GenerateBackgroundMusicToolArgs,
+    ) -> u32 {
+        pricing.background_music_model_mud_points(None)
+    }
+}
+
+impl EditorAgentPricedTool for EditImageTool {
+    fn pricing(&self, pricing: &EditorGenerationPricingConfig, _args: &EditImageToolArgs) -> u32 {
+        editor_agent_image_mud_points(pricing, Some("quick-edit"), Some("1K"))
+    }
+}

server-rs/crates/api-server/src/editor_agent/reconcile.rs

@@ -0,0 +1,369 @@
+use crate::editor_agent::resp_to_asset;
+use crate::http_error::AppError;
+use crate::state::AppState;
+use platform_editor_agent::agent::tools::context::EditorToolContext;
+use platform_editor_agent::agent::tools::edit_image::{
+    EditImageTool, EditImageToolArgs, EditorImageEditResult,
+};
+use platform_editor_agent::agent::tools::generate_background_music::{
+    GenerateBackgroundMusicTool, GenerateBackgroundMusicToolArgs,
+};
+use platform_editor_agent::agent::tools::generate_character::GenerateCharacterTool;
+use platform_editor_agent::agent::tools::generate_icon_spritesheet::{
+    EditorIconSpritesheetResult, GenerateIconSpritesheetTool, GenerateIconSpritesheetToolArgs,
+};
+use platform_editor_agent::agent::tools::generate_image::{
+    EditorImageGenerationResult, GenerateImageTool, GenerateImageToolArgs,
+};
+use platform_editor_agent::agent::tools::generate_sound_effect::{
+    GenerateSoundEffectTool, GenerateSoundEffectToolArgs,
+};
+use platform_editor_agent::agent::tools::generate_ui_design::GenerateUiDesignTool;
+use platform_editor_agent::agent::tools::generate_video::{
+    GenerateVideoTool, GenerateVideoToolArgs,
+};
+use platform_editor_agent::framework::tool::Tool;
+use serde_json::Value;
+use shared_contracts::assets::{EditorAudioGenerateResponse, EditorVideoGenerateResponse};
+use shared_contracts::editor_agent::{
+    EditorAgentConversationMessagesDocument, EditorAgentMessage, EditorAgentToolCallStatus,
+};
+use spacetime_client::{EditorAgentConversationRecord, ExternalGenerationJobGetRecordInput};
+use tokio::time::{Duration, sleep};
+
+pub(crate) const EDITOR_AGENT_RESULT_RECONCILE_MAX_RETRIES: u8 = 3;
+const EDITOR_AGENT_RESULT_RECONCILE_RETRY_DELAY: Duration = Duration::from_millis(100);
+
+#[derive(Debug, PartialEq)]
+enum ResultReconcileFailure {
+    RetryLater(String),
+    Fatal(String),
+}
+
+impl From<String> for ResultReconcileFailure {
+    fn from(error: String) -> Self {
+        Self::Fatal(error)
+    }
+}
+
+pub async fn reconcile_editor_agent_tool_calls(
+    state: &AppState,
+    conversation: &EditorAgentConversationRecord,
+    document: &mut EditorAgentConversationMessagesDocument,
+) -> Result<Vec<EditorAgentMessage>, AppError> {
+    let candidates = document
+        .messages
+        .iter()
+        .enumerate()
+        .filter_map(|(message_index, message)| {
+            let tool_call = message.tool_call.as_ref()?;
+            if tool_call.status != EditorAgentToolCallStatus::NotCompleted {
+                return None;
+            }
+            Some((message_index, tool_call.external_job_id.clone()?))
+        })
+        .collect::<Vec<_>>();
+    let mut reconciled = Vec::new();
+
+    for (message_index, job_id) in candidates {
+        let mut last_reconcile_error = None;
+
+        for retry_count in 0..=EDITOR_AGENT_RESULT_RECONCILE_MAX_RETRIES {
+            let job = match state
+                .spacetime_client()
+                .get_external_generation_job_generated_artifacts(
+                    ExternalGenerationJobGetRecordInput {
+                        job_id: job_id.clone(),
+                        owner_user_id: conversation.owner_user_id.clone(),
+                    },
+                )
+                .await
+            {
+                Ok(job) => job,
+                Err(error) => {
+                    last_reconcile_error = Some(ResultReconcileFailure::RetryLater(format!(
+                        "读取生成任务结果失败：{error}"
+                    )));
+                    if should_retry_result_reconcile(retry_count) {
+                        sleep(EDITOR_AGENT_RESULT_RECONCILE_RETRY_DELAY).await;
+                    }
+                    continue;
+                }
+            };
+
+            match job.status.as_str() {
+                "completed" => {
+                    let original_message = document.messages[message_index].clone();
+                    match reconcile_completed_editor_agent_tool_call(
+                        &mut document.messages[message_index],
+                        job.result_payload_json.as_deref(),
+                    ) {
+                        Ok(()) => {
+                            last_reconcile_error = None;
+                            reconciled.push(document.messages[message_index].clone());
+                            break;
+                        }
+                        Err(error) => {
+                            document.messages[message_index] = original_message;
+                            last_reconcile_error = Some(error);
+                        }
+                    }
+                }
+                "failed" => {
+                    mark_job_failed(
+                        &mut document.messages[message_index],
+                        job.last_error_message
+                            .unwrap_or_else(|| "生成失败".to_string()),
+                    );
+                    last_reconcile_error = None;
+                    reconciled.push(document.messages[message_index].clone());
+                    break;
+                }
+                _ => {
+                    last_reconcile_error = None;
+                    break;
+                }
+            }
+
+            if should_retry_result_reconcile(retry_count) {
+                sleep(EDITOR_AGENT_RESULT_RECONCILE_RETRY_DELAY).await;
+            }
+        }
+
+        if let Some(error) = last_reconcile_error
+            && apply_exhausted_result_reconcile_failure(
+                &mut document.messages[message_index],
+                error,
+            )
+        {
+            reconciled.push(document.messages[message_index].clone());
+        }
+    }
+
+    Ok(reconciled)
+}
+
+fn should_retry_result_reconcile(retry_count: u8) -> bool {
+    retry_count < EDITOR_AGENT_RESULT_RECONCILE_MAX_RETRIES
+}
+
+fn mark_job_failed(message: &mut EditorAgentMessage, error: String) {
+    let tool_call = message
+        .tool_call
+        .as_mut()
+        .expect("reconcile candidate contains a tool call");
+    tool_call.error = Some(error.clone());
+    tool_call.status = EditorAgentToolCallStatus::Failed;
+    message.text = format!("[tool_call:{}] output: {error}", tool_call.tool_name);
+}
+
+fn mark_fatal_result_reconcile_failed(message: &mut EditorAgentMessage, error: String) {
+    mark_job_failed(
+        message,
+        format!(
+            "任务终态结果回填重试 {EDITOR_AGENT_RESULT_RECONCILE_MAX_RETRIES} 次后仍失败：{error}"
+        ),
+    );
+}
+
+fn apply_exhausted_result_reconcile_failure(
+    message: &mut EditorAgentMessage,
+    failure: ResultReconcileFailure,
+) -> bool {
+    match failure {
+        ResultReconcileFailure::RetryLater(_) => false,
+        ResultReconcileFailure::Fatal(error) => {
+            mark_fatal_result_reconcile_failed(message, error);
+            true
+        }
+    }
+}
+
+fn reconcile_completed_editor_agent_tool_call(
+    message: &mut EditorAgentMessage,
+    result_payload_json: Option<&str>,
+) -> Result<(), ResultReconcileFailure> {
+    let response = result_payload_json
+        .ok_or_else(|| ResultReconcileFailure::RetryLater("生成任务缺少结果数据".to_string()))
+        .and_then(|payload| {
+            serde_json::from_str::<Value>(payload)
+                .map_err(|error| ResultReconcileFailure::Fatal(error.to_string()))
+        })?
+        // TODO extract const
+        .get("editor-agent-tool-call-result")
+        .cloned()
+        .ok_or_else(|| {
+            ResultReconcileFailure::Fatal("生成任务缺少 Agent 工具调用结果".to_string())
+        })?;
+    let tool_call = message
+        .tool_call
+        .as_mut()
+        .ok_or_else(|| ResultReconcileFailure::Fatal("消息缺少工具调用".to_string()))?;
+    let tool_name = tool_call.tool_name.clone();
+
+    match tool_name.as_str() {
+        GenerateImageTool::NAME | GenerateCharacterTool::NAME | GenerateUiDesignTool::NAME => {
+            let args: GenerateImageToolArgs = parse_reconciled_value(&tool_call.args)?;
+            let result: EditorImageGenerationResult = parse_reconciled_value(&response)?;
+            message.text = match tool_name.as_str() {
+                GenerateCharacterTool::NAME => GenerateCharacterTool {
+                    context: EditorToolContext::default(),
+                }
+                .format_execute_message(&args, &result),
+                GenerateUiDesignTool::NAME => GenerateUiDesignTool {
+                    context: EditorToolContext::default(),
+                }
+                .format_execute_message(&args, &result),
+                _ => GenerateImageTool {
+                    context: EditorToolContext::default(),
+                }
+                .format_execute_message(&args, &result),
+            };
+            tool_call.images = vec![resp_to_asset::editor_agent_generated_image(&result)];
+        }
+        EditImageTool::NAME => {
+            let args: EditImageToolArgs = parse_reconciled_value(&tool_call.args)?;
+            let result: EditorImageEditResult = parse_reconciled_value(&response)?;
+            tool_call.images = vec![resp_to_asset::editor_agent_generated_edited_image(&result)];
+            message.text = EditImageTool {
+                context: EditorToolContext::default(),
+            }
+            .format_execute_message(args, result);
+        }
+        GenerateIconSpritesheetTool::NAME => {
+            let args: GenerateIconSpritesheetToolArgs = parse_reconciled_value(&tool_call.args)?;
+            let result: EditorIconSpritesheetResult = parse_reconciled_value(&response)?;
+            message.text = GenerateIconSpritesheetTool {
+                context: EditorToolContext::default(),
+            }
+            .format_execute_message(&args, &result);
+            tool_call.images = resp_to_asset::editor_agent_generated_spritesheet_images(&result);
+        }
+        GenerateVideoTool::NAME => {
+            let args: GenerateVideoToolArgs = parse_reconciled_value(&tool_call.args)?;
+            let result: EditorVideoGenerateResponse = parse_reconciled_value(&response)?;
+            message.text = GenerateVideoTool {
+                context: EditorToolContext::default(),
+            }
+            .format_execute_message(&args, &result);
+            tool_call.videos = vec![resp_to_asset::editor_agent_generated_video(&result)];
+        }
+        GenerateSoundEffectTool::NAME | GenerateBackgroundMusicTool::NAME => {
+            let result: EditorAudioGenerateResponse = parse_reconciled_value(&response)?;
+            message.text = if tool_name == GenerateSoundEffectTool::NAME {
+                let args: GenerateSoundEffectToolArgs = parse_reconciled_value(&tool_call.args)?;
+                GenerateSoundEffectTool.format_execute_message(&args, &result)
+            } else {
+                let args: GenerateBackgroundMusicToolArgs =
+                    parse_reconciled_value(&tool_call.args)?;
+                GenerateBackgroundMusicTool.format_execute_message(&args, &result)
+            };
+            tool_call.audios = vec![resp_to_asset::editor_agent_generated_audio(&result)];
+        }
+        _ => {
+            return Err(ResultReconcileFailure::Fatal(format!(
+                "不支持回填工具 {tool_name}"
+            )));
+        }
+    }
+    tool_call.error = None;
+    tool_call.status = EditorAgentToolCallStatus::Completed;
+    Ok(())
+}
+
+fn parse_reconciled_value<T: serde::de::DeserializeOwned>(value: &Value) -> Result<T, String> {
+    serde_json::from_value(value.clone()).map_err(|error| error.to_string())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    fn pending_tool_message() -> EditorAgentMessage {
+        serde_json::from_value(json!({
+            "id": 1,
+            "role": "system",
+            "text": "waiting",
+            "attachments": [],
+            "toolCall": {
+                "toolName": "generate_image",
+                "status": "not_completed",
+                "args": {},
+                "displayArgs": {
+                    "stringArgs": [],
+                    "imageArgs": [],
+                    "extras": { "priceMudPoints": 0 }
+                },
+                "externalJobId": "job-1",
+                "images": []
+            },
+            "createdAt": "2026-07-16T00:00:00Z"
+        }))
+        .expect("pending tool message should deserialize")
+    }
+
+    #[test]
+    fn terminal_result_reconcile_retries_three_times_after_the_initial_attempt() {
+        assert!(should_retry_result_reconcile(0));
+        assert!(should_retry_result_reconcile(1));
+        assert!(should_retry_result_reconcile(2));
+        assert!(!should_retry_result_reconcile(3));
+    }
+
+    #[test]
+    fn exhausted_fatal_result_reconcile_marks_the_tool_call_failed() {
+        let mut message = pending_tool_message();
+
+        let changed = apply_exhausted_result_reconcile_failure(
+            &mut message,
+            ResultReconcileFailure::Fatal("invalid result payload".to_string()),
+        );
+
+        assert!(changed);
+        let tool_call = message.tool_call.expect("tool call should remain present");
+        assert_eq!(tool_call.status, EditorAgentToolCallStatus::Failed);
+        assert_eq!(
+            tool_call.error.as_deref(),
+            Some("任务终态结果回填重试 3 次后仍失败：invalid result payload")
+        );
+        assert!(message.text.contains("重试 3 次后仍失败"));
+    }
+
+    #[test]
+    fn missing_result_payload_is_retryable_and_preserves_pending_job_reference() {
+        let mut message = pending_tool_message();
+
+        let error = reconcile_completed_editor_agent_tool_call(&mut message, None)
+            .expect_err("missing result payload should be retried later");
+
+        assert_eq!(
+            error,
+            ResultReconcileFailure::RetryLater("生成任务缺少结果数据".to_string())
+        );
+        assert!(!apply_exhausted_result_reconcile_failure(
+            &mut message,
+            error,
+        ));
+        let tool_call = message.tool_call.expect("tool call should remain present");
+        assert_eq!(tool_call.status, EditorAgentToolCallStatus::NotCompleted);
+        assert_eq!(tool_call.external_job_id.as_deref(), Some("job-1"));
+        assert_eq!(tool_call.error, None);
+    }
+
+    #[test]
+    fn read_failure_is_retryable_without_terminal_message_mutation() {
+        let mut message = pending_tool_message();
+        let error = ResultReconcileFailure::RetryLater(
+            "读取生成任务结果失败：temporarily unavailable".to_string(),
+        );
+
+        assert!(!apply_exhausted_result_reconcile_failure(
+            &mut message,
+            error,
+        ));
+        let tool_call = message.tool_call.expect("tool call should remain present");
+        assert_eq!(tool_call.status, EditorAgentToolCallStatus::NotCompleted);
+        assert_eq!(tool_call.external_job_id.as_deref(), Some("job-1"));
+    }
+}

server-rs/crates/api-server/src/editor_agent/resp_to_asset.rs

@@ -0,0 +1,105 @@
+use platform_editor_agent::agent::tools::edit_image::EditorImageEditResult;
+use platform_editor_agent::agent::tools::generate_icon_spritesheet::EditorIconSpritesheetResult;
+use platform_editor_agent::agent::tools::generate_image::EditorImageGenerationResult;
+use serde_json::Value;
+use shared_contracts::assets::{EditorAudioGenerateResponse, EditorVideoGenerateResponse};
+use shared_contracts::editor_agent::{
+    EditorAgentGeneratedAudio, EditorAgentGeneratedImage, EditorAgentGeneratedVideo,
+};
+
+fn value_string(value: Option<&Value>, field: &str) -> Option<String> {
+    value
+        .and_then(|resource| resource.get(field))
+        .and_then(Value::as_str)
+        .map(ToOwned::to_owned)
+}
+
+pub fn editor_agent_generated_image(
+    result: &EditorImageGenerationResult,
+) -> EditorAgentGeneratedImage {
+    EditorAgentGeneratedImage {
+        resource_id: value_string(result.resource.as_ref(), "resourceId"),
+        object_key: result.object_key.clone(),
+        asset_object_id: result.asset_object_id.clone(),
+        image_src: result.image_src.clone(),
+        thumbnail_src: None,
+        width: Some(result.width),
+        height: Some(result.height),
+    }
+}
+
+pub fn editor_agent_generated_edited_image(
+    result: &EditorImageEditResult,
+) -> EditorAgentGeneratedImage {
+    EditorAgentGeneratedImage {
+        resource_id: value_string(result.resource.as_ref(), "resourceId"),
+        object_key: result.object_key.clone(),
+        asset_object_id: result.asset_object_id.clone(),
+        image_src: result.image_src.clone(),
+        thumbnail_src: None,
+        width: Some(result.width),
+        height: Some(result.height),
+    }
+}
+
+pub fn editor_agent_generated_spritesheet(
+    result: &EditorIconSpritesheetResult,
+) -> EditorAgentGeneratedImage {
+    EditorAgentGeneratedImage {
+        resource_id: value_string(result.spritesheet_resource.as_ref(), "resourceId"),
+        object_key: value_string(result.spritesheet_resource.as_ref(), "objectKey"),
+        asset_object_id: value_string(result.spritesheet_resource.as_ref(), "assetObjectId"),
+        image_src: result.spritesheet_image_src.clone(),
+        thumbnail_src: None,
+        width: Some(result.spritesheet_width),
+        height: Some(result.spritesheet_height),
+    }
+}
+
+pub fn editor_agent_generated_spritesheet_images(
+    result: &EditorIconSpritesheetResult,
+) -> Vec<EditorAgentGeneratedImage> {
+    let images = result
+        .icon_image_srcs
+        .iter()
+        .map(|image| EditorAgentGeneratedImage {
+            resource_id: value_string(image.resource.as_ref(), "resourceId"),
+            object_key: value_string(image.resource.as_ref(), "objectKey"),
+            asset_object_id: value_string(image.resource.as_ref(), "assetObjectId"),
+            image_src: image.image_src.clone(),
+            thumbnail_src: None,
+            width: Some(image.width),
+            height: Some(image.height),
+        })
+        .collect::<Vec<_>>();
+    if images.is_empty() {
+        vec![editor_agent_generated_spritesheet(result)]
+    } else {
+        images
+    }
+}
+
+pub fn editor_agent_generated_video(
+    result: &EditorVideoGenerateResponse,
+) -> EditorAgentGeneratedVideo {
+    EditorAgentGeneratedVideo {
+        resource_id: value_string(result.resource.as_ref(), "resourceId"),
+        object_key: result.object_key.clone(),
+        asset_object_id: result.asset_object_id.clone(),
+        video_src: result.video_src.clone(),
+        thumbnail_src: result.thumbnail_src.clone(),
+        width: Some(result.width),
+        height: Some(result.height),
+    }
+}
+
+pub fn editor_agent_generated_audio(
+    result: &EditorAudioGenerateResponse,
+) -> EditorAgentGeneratedAudio {
+    EditorAgentGeneratedAudio {
+        resource_id: value_string(result.resource.as_ref(), "resourceId"),
+        object_key: result.object_key.clone(),
+        asset_object_id: result.asset_object_id.clone(),
+        audio_src: result.audio_src.clone(),
+    }
+}

server-rs/crates/api-server/src/editor_generation_queue.rs

@@ -47,12 +47,41 @@ where
     T: Serialize,
 {
     let job_id = build_prefixed_uuid_id("task-");
+    enqueue_editor_generation_job_with_identity(
+        state,
+        owner_user_id,
+        job_kind,
+        source_entity_id,
+        request_label,
+        price_mud_points,
+        payload,
+        job_id.clone(),
+        format!("editor-canvas:{job_kind}:{job_id}"),
+    )
+    .await
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(crate) async fn enqueue_editor_generation_job_with_identity<T>(
+    state: &AppState,
+    owner_user_id: &str,
+    job_kind: &str,
+    source_entity_id: impl Into<String>,
+    request_label: impl Into<String>,
+    price_mud_points: u64,
+    payload: &T,
+    job_id: String,
+    dedupe_key: String,
+) -> Result<ExternalGenerationJobRecord, AppError>
+where
+    T: Serialize,
+{
     let request_payload_json = serialize_editor_generation_job_payload(payload)?;
     let now_micros = current_utc_micros();
     state
         .spacetime_client()
         .enqueue_external_generation_job(ExternalGenerationJobEnqueueRecordInput {
-            dedupe_key: format!("editor-canvas:{job_kind}:{job_id}"),
+            dedupe_key,
             job_id,
             job_kind: job_kind.to_string(),
             owner_user_id: owner_user_id.to_string(),

server-rs/crates/api-server/src/external_generation_worker.rs

@@ -829,7 +829,9 @@ async fn process_external_generation_job_once(
             )
             .await
             {
-                Ok(_) => complete_editor_generation_job(&state, &worker_id, &job).await,
+                Ok(result) => {
+                    complete_editor_generation_job(&state, &worker_id, &job, result.0).await
+                }
                 Err(error) => {
                     let message = error.body_text();
                     fail_job(&state, &worker_id, &job, message.clone()).await?;
@@ -858,7 +860,9 @@ async fn process_external_generation_job_once(
             )
             .await
             {
-                Ok(_) => complete_editor_generation_job(&state, &worker_id, &job).await,
+                Ok(result) => {
+                    complete_editor_generation_job(&state, &worker_id, &job, result.0).await
+                }
                 Err(error) => {
                     let message = error.body_text();
                     fail_job(&state, &worker_id, &job, message.clone()).await?;
@@ -960,7 +964,9 @@ async fn process_external_generation_job_once(
             )
             .await
             {
-                Ok(_) => complete_editor_generation_job(&state, &worker_id, &job).await,
+                Ok(result) => {
+                    complete_editor_generation_job(&state, &worker_id, &job, result.0).await
+                }
                 Err(response) => {
                     let message = response_error_message(response).await;
                     fail_job(&state, &worker_id, &job, message.clone()).await?;
@@ -989,7 +995,9 @@ async fn process_external_generation_job_once(
             )
             .await
             {
-                Ok(_) => complete_editor_generation_job(&state, &worker_id, &job).await,
+                Ok(result) => {
+                    complete_editor_generation_job(&state, &worker_id, &job, result.0).await
+                }
                 Err(response) => {
                     let message = response_error_message(response).await;
                     fail_job(&state, &worker_id, &job, message.clone()).await?;
@@ -1018,7 +1026,9 @@ async fn process_external_generation_job_once(
             )
             .await
             {
-                Ok(_) => complete_editor_generation_job(&state, &worker_id, &job).await,
+                Ok(result) => {
+                    complete_editor_generation_job(&state, &worker_id, &job, result.0).await
+                }
                 Err(response) => {
                     let message = response_error_message(response).await;
                     fail_job(&state, &worker_id, &job, message.clone()).await?;
@@ -1047,7 +1057,9 @@ async fn process_external_generation_job_once(
             )
             .await
             {
-                Ok(_) => complete_editor_generation_job(&state, &worker_id, &job).await,
+                Ok(result) => {
+                    complete_editor_generation_job(&state, &worker_id, &job, result.0).await
+                }
                 Err(response) => {
                     let message = response_error_message(response).await;
                     fail_job(&state, &worker_id, &job, message.clone()).await?;
@@ -1167,18 +1179,13 @@ async fn complete_editor_generation_job(
     state: &AppState,
     worker_id: &str,
     job: &ExternalGenerationJobRecord,
+    response: Value,
 ) -> Result<(), String> {
     complete_job(
         state,
         worker_id,
         job,
-        Some(
-            json!({
-                "sourceModule": job.source_module.clone(),
-                "sourceEntityId": job.source_entity_id.clone(),
-            })
-            .to_string(),
-        ),
+        Some(editor_generation_result_payload_json(job, &response)),
     )
     .await
 }
@@ -1206,6 +1213,17 @@ fn editor_generation_result_payload_json(
         "sourceModule": job.source_module.clone(),
         "sourceEntityId": job.source_entity_id.clone(),
     });
+    if is_editor_agent_generation_job(job)
+        && let Some(object) = payload.as_object_mut()
+    {
+        // The Agent needs this compact result to restore its tool-call card. Other jobs keep
+        // master's metadata-only completion payload to avoid turning the queue into an asset API.
+        object.insert(
+          // TODO extract const
+            "editor-agent-tool-call-result".to_string(),
+            compact_editor_generation_result(response.clone()),
+        );
+    }
     if let Some(warning) = extract_editor_generation_warning(response)
         && let Some(object) = payload.as_object_mut()
     {
@@ -1214,6 +1232,56 @@ fn editor_generation_result_payload_json(
     payload.to_string()
 }
 
+fn is_editor_agent_generation_job(job: &ExternalGenerationJobRecord) -> bool {
+    serde_json::from_str::<Value>(job.request_payload_json.as_str())
+        .ok()
+        .is_some_and(|payload| {
+            payload
+                .pointer("/generationInputs/source")
+                .and_then(Value::as_str)
+              // TODO extract const
+                .is_some_and(|source| source.trim() == "editor-agent")
+        })
+}
+
+fn compact_editor_generation_result(mut result: Value) -> Value {
+    let Some(object) = result.as_object_mut() else {
+        return result;
+    };
+    object.remove("project");
+    object.remove("asset");
+    object.remove("spritesheetAsset");
+    for field in ["resource", "spritesheetResource"] {
+        let Some(resource) = object.get_mut(field).and_then(Value::as_object_mut) else {
+            continue;
+        };
+        resource
+            .retain(|key, _| matches!(key.as_str(), "resourceId" | "objectKey" | "assetObjectId"));
+    }
+    if let Some(icon_image_srcs) = object
+        .get_mut("iconImageSrcs")
+        .and_then(Value::as_array_mut)
+    {
+        for icon in icon_image_srcs {
+            let Some(icon) = icon.as_object_mut() else {
+                continue;
+            };
+            if let Some(resource) = icon.get_mut("resource").and_then(Value::as_object_mut) {
+                resource.retain(|key, _| {
+                    matches!(key.as_str(), "resourceId" | "objectKey" | "assetObjectId")
+                });
+            }
+            icon.retain(|key, _| {
+                matches!(
+                    key.as_str(),
+                    "name" | "imageSrc" | "width" | "height" | "resource"
+                )
+            });
+        }
+    }
+    result
+}
+
 fn extract_editor_generation_warning(response: &Value) -> Option<Value> {
     let data = response.get("data").unwrap_or(response);
     let (warning, is_slice_warning) = match data.get("warning") {
@@ -1629,6 +1697,128 @@ mod tests {
         );
         assert!(payload.get("spritesheetImageSrc").is_none());
         assert!(payload.get("iconImageSrcs").is_none());
+        assert!(payload.get("editor-agent-tool-call-result").is_none());
+    }
+
+    #[test]
+    fn editor_agent_result_payload_keeps_compact_response() {
+        let mut job = external_generation_job_record_fixture(Some("lease-1"));
+        job.request_payload_json = json!({
+            "generationInputs": { "source": "editor-agent" },
+        })
+        .to_string();
+        let response = json!({
+            "imageSrc": "/api/assets/object/generated.png",
+            "objectKey": "users/user-1/generated.png",
+            "assetObjectId": "asset-object-1",
+            "width": 1024,
+            "height": 1024,
+            "sourceType": "generated",
+            "prompt": "castle",
+            "actualPrompt": null,
+            "model": "gpt-image-2",
+            "provider": "VectorEngine",
+            "taskId": "provider-task-1",
+            "resource": {
+                "resourceId": "resource-1",
+                "objectKey": "users/user-1/generated.png",
+                "assetObjectId": "asset-object-1",
+                "imageSrc": "data:image/png;base64,SHOULD_NOT_PERSIST",
+            },
+            "asset": { "assetId": "asset-1" },
+            "project": { "projectId": "project-1" },
+        });
+
+        let payload: Value =
+            serde_json::from_str(&editor_generation_result_payload_json(&job, &response))
+                .expect("worker result should be valid JSON");
+
+        assert_eq!(
+            payload["editor-agent-tool-call-result"]["imageSrc"],
+            json!("/api/assets/object/generated.png")
+        );
+        assert_eq!(
+            payload["editor-agent-tool-call-result"]["resource"],
+            json!({
+                "resourceId": "resource-1",
+                "objectKey": "users/user-1/generated.png",
+                "assetObjectId": "asset-object-1",
+            })
+        );
+        assert!(payload["editor-agent-tool-call-result"].get("asset").is_none());
+        assert!(payload["editor-agent-tool-call-result"].get("project").is_none());
+        assert!(!payload.to_string().contains("data:image"));
+    }
+
+    #[test]
+    fn editor_agent_spritesheet_result_keeps_all_persisted_slices() {
+        let mut job = external_generation_job_record_fixture(Some("lease-1"));
+        job.request_payload_json = json!({
+            "generationInputs": { "source": "editor-agent" },
+        })
+        .to_string();
+        let response = json!({
+            "spritesheetImageSrc": "/api/assets/object/sheet.png",
+            "spritesheetWidth": 512,
+            "spritesheetHeight": 512,
+            "taskId": "provider-task-1",
+            "spritesheetResource": {
+                "resourceId": "sheet-resource",
+                "objectKey": "users/user-1/sheet.png",
+                "assetObjectId": "sheet-object",
+            },
+            "iconImageSrcs": [
+                {
+                    "name": "backpack",
+                    "imageSrc": "/api/assets/object/backpack.png",
+                    "width": 64,
+                    "height": 64,
+                    "resource": {
+                        "resourceId": "icon-resource-1",
+                        "objectKey": "users/user-1/backpack.png",
+                        "assetObjectId": "icon-object-1",
+                        "imageSrc": "data:image/png;base64,SHOULD_NOT_PERSIST",
+                    },
+                    "asset": { "assetId": "icon-asset-1" },
+                },
+                {
+                    "name": "map",
+                    "imageSrc": "/api/assets/object/map.png",
+                    "width": 64,
+                    "height": 64,
+                    "resource": {
+                        "resourceId": "icon-resource-2",
+                        "objectKey": "users/user-1/map.png",
+                        "assetObjectId": "icon-object-2",
+                    },
+                },
+            ],
+        });
+
+        let payload: Value =
+            serde_json::from_str(&editor_generation_result_payload_json(&job, &response))
+                .expect("worker result should be valid JSON");
+
+        assert_eq!(
+            payload["editor-agent-tool-call-result"]["iconImageSrcs"]
+                .as_array()
+                .map(Vec::len),
+            Some(2)
+        );
+        assert_eq!(
+            payload["editor-agent-tool-call-result"]["iconImageSrcs"][0]["resource"],
+            json!({
+                "resourceId": "icon-resource-1",
+                "objectKey": "users/user-1/backpack.png",
+                "assetObjectId": "icon-object-1",
+            })
+        );
+        assert!(
+            payload["editor-agent-tool-call-result"]["iconImageSrcs"][0]
+                .get("asset")
+                .is_none()
+        );
+        assert!(!payload.to_string().contains("data:image"));
     }
 
     #[test]

server-rs/crates/api-server/src/main.rs

@@ -39,7 +39,6 @@ mod custom_world_asset_prompts;
 mod custom_world_foundation_draft;
 mod custom_world_result_prompts;
 mod custom_world_rpg_draft_prompts;
-mod editor_agent;
 mod editor_generation_config;
 mod editor_generation_queue;
 mod editor_green_screen;
@@ -115,6 +114,7 @@ mod wechat;
 mod wooden_fish;
 mod work_author;
 mod work_play_tracking;
+mod editor_agent;
 
 use shared_logging::{OtelConfig, init_tracing};
 use socket2::{Domain, Protocol, Socket, Type};