@@ -1,6 +1,6 @@
# 画布Agent对话面板
日期：`2026-07-23 `
日期：`2026-07-29 `
## 定位与边界
@@ -10,15 +10,17 @@
## 能力范围
对话 Agent 可通过 function-calling 触发以下八 类工具，全部 复用既有计费收口接口 ：
对话 Agent 可通过 function-calling 触发以下十 类工具；生成类工具 复用既有计费收口，确定性拆图即时执行且不计费 ：
| 工具 | 后端接口 |
| --- | --- |
| 生成图片 | `POST /api/editor/images/generations` |
| 修改图片（基于附件/画布素材） | `POST /api/editor/images/edits` |
| 生成角色形象 | 既有角色形象生成入口对应接口 |
| 基于角色图片生成角色动作 | `POST /api/editor/character-animations/generations` |
| 生成图标素材 | `POST /api/editor/icon-spritesheets/generations` |
| 生成 UI 设计图 | 既有 UI 设计图生成入口对应接口 |
| 拆分已有 UI / 图集元素 | 复用 `POST /api/editor/icon-spritesheets/slices` 的确定性连通域拆分逻辑 |
| 生成视频 | `POST /api/editor/videos/generations` |
| 生成游戏音效 | `POST /api/editor/audios/sound-effects/generations` |
| 生成背景音乐 | `POST /api/editor/audios/background-music/generations` |
@@ -28,14 +30,15 @@
- 用户要求“规范图 / 视觉规范图 / 风格规范图 / 素材规范展板”时，规划默认选择 `generate_image` ，并在 prompt 中明确要求生成规范展板，包含统一视角、线条粗细、色卡、材质、阴影、圆角、状态层级、尺寸标注等可落地的视觉规范元素。
- 用户要求“角色规范图”且语义是角色的规范展板、风格展板或设定板时，仍走 `generate_image` ，不要误分流到 `generate_character` ；只有实际生成角色立绘、角色主形象或角色视觉资产时才走 `generate_character` 。用户要求多个图标素材、图集或 spritesheet 时才走 `generate_icon_spritesheet` 。
- 所有生成必须走 `execute_billable_asset_operation_with_cost` 与模型定价配置，禁止绕过定价收口。
- `split-elements` 只接受当前画布项目中的 `ui-design` 或 `icon-spritesheet` 资源，直接执行既有确定性切片、项目资源 / 素材库持久化和画布回填；不调用生成模型、不进入定价、不展示确认卡，也不创建 `external_generation_job` 。
- function-calling 的 JSON Schema 必须与参数默认值和运行时校验保持一致，不能只在 description 中提示会被运行时拒绝的组合。`generate-ui-design` 固定 `gpt-image-2` ，因此 `image_size` 只暴露 `1K / 2K` ；其它可切换图片模型的工具通过共享条件 schema 在显式选择 `gpt-image-2` 时同样把 `image_size` 限制为 `1K / 2K` ，省略模型时仍按默认 nanobanana2 允许 `0.5K` 。`generate-video` 省略 `model` 时按默认 `seedance2.0-fast` 约束 `resolution` 为 `480p / 720p` ，显式选择其它模型时仍使用其现有分辨率范围。运行时强类型校验继续作为最终防线。
- 图层操作及其他未注册的画板功能第一期不进入对话工具面，仍走现有面板。
## 当前分支落地状态
- 已落地：会话元数据、OSS 消息文档、会话 CRUD、带 `clientMessageId` 幂等键的普通 JSON 消息请求、后端 LLM 工具规划、右侧对话面板、会话历史、新建 / 软删会话、附件从画布资源 / 账号素材库选择，以及八类 图片 / 音视频工具对既有生成入口的复用 。
- 已落地：会话元数据、OSS 消息文档、会话 CRUD、带 `clientMessageId` 幂等键的普通 JSON 消息请求、后端 LLM 工具规划、右侧对话面板、会话历史、新建 / 软删会话、附件从画布资源 / 账号素材库选择，以及九类收费 图片 / 音视频工具和一类免费即时拆图工具 。
- 已落地：工具确认 / 取消、external generation task 轮询与会话懒回填。LLM 未配置、请求失败或规划结果解析失败时，后端把 `role=system` 、正文以 `ERROR ` 开头的消息写入 OSS，并通过 `deltaMessages` 返回，`errorMessage` 保持为空；前端隐藏 wire 前缀并以红色错误气泡展示。工具执行失败继续保存 `status=failed` 、模型和错误信息，不能只返回瞬时错误。
- 未落地：附件弹窗末尾上传格。`external_generation_job` 继续 作为后台任务队列真相，对话消息只保存确认、回填状态和轻量媒体结果引用 。
- 未落地：附件弹窗末尾上传格。收费生成继续以 `external_generation_job` 作为后台任务队列真相；即时拆图在当前消息请求内完成并把 `status=completed` 与轻量图片引用直接写入 OSS 对话消息 。
## 会话与持久化
@@ -86,13 +89,14 @@
## 工具调用确认展示契约
- api-server 的 `EditorAgentToolExecutionMode` 明确区分 `ConfirmedExternalJob` 与 `Immediate` ：前者才允许读取定价、构建确认展示和 worker payload；后者由 function-calling runner 当场执行，成功消息直接持久化为 `completed` ，不得经过确认接口或伪造零价外部任务。
- 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**，不是 LLM 返回的原始 JSON。api-server 收到工具调用后，必须先按已注册的 ToolArgs 反序列化、补齐字段默认值、删除未进入 ToolArgs 的未知 / 退役字段、执行工具参数校验，再重新序列化并写入 `args` ；校验失败的调用不得持久化为待确认消息。所有有明确默认值的工具标量参数在强类型 ToolArgs 中必须使用非 `Option` 字段：调用方省略字段或把顶层字段显式传为 `null` 时，统一在 ToolArgs 反序列化前视为未提供，由 Serde 补齐默认值，并把具体默认值写入规范 `args` ；没有默认值的必填字段显式传为 `null` 时同样按缺失处理.(for compatibility) 后续计价、确认展示和 job payload 不得再次使用 `unwrap_or` 补同一默认值。LLM 原始参数只作为本次规范化的瞬时输入，不作为执行或审计真相；确认、取消、任务回填与后续上下文统一读取同一条消息中的规范 `args` 。图片参数继续只保存由真实 data key 计算出的 opaque SHA-256 `imageId` ；不得为了前端预览把 `args` 中的图片 ID 改写成 `objectKey` 、URL 或展示对象，也不得由前端重组或回传一份新的执行参数。
- api-server 内画布 Agent 工具统一实现 object-safe `EditorAgentTool: ToolDyn` 。`validate_args` 、计价、确认展示、worker job 构建、 `format_execute_message` 和结果媒体投影都 使用统一 JSON 边界；每个具体工具实现 负责把 JSON 反序列化为自己的强类型 Args / 结果，并把校验与完成消息格式化转发到 `platform-editor-agent` 中既有的 typed `validate_args` / `format_execute_message` ，不得在调用方复制工具规则。`editor_agent_tool(toolName, context)` 是唯一按工具名分派的位置，规划、确认和任务回填只调用返回的 dyn tool；新增工具必须补齐同一个 trait 实现和该工厂分支。LLM builder 的 `.tool(...)` 注册列表仍是独立显式清单，不属于本次动态分派 。framework runner 必须在 `ToolCallOutput` 中保留工具返回的结构化 output； `format_tool_call_message` ，不得丢弃 `TOOL_CALL_PENDING_MESSAGE` 后自行拼另一套“等待确认”输出。
- api-server 内画布 Agent 工具统一实现 object-safe `EditorAgentTool: ToolDyn` 。`validate_args` 、`format_execute_message` 和结果媒体投影使用统一 JSON 边界；只有 `ConfirmedExternalJob` 工具实现计价、确认展示和 worker job 构建， `Immediate` 工具不得被这些方法调用。 每个具体工具负责把 JSON 反序列化为自己的强类型 Args / 结果，并把校验与完成消息格式化转发到 `platform-editor-agent` 中既有的 typed `validate_args` / `format_execute_message` ，不得在调用方复制工具规则。`editor_agent_tool(toolName, context)` 是唯一按工具名分派的位置，规划、确认和任务回填只调用返回的 dyn tool；新增工具必须补齐同一个 trait 实现和该工厂分支。LLM builder 的 `.tool(...)` 注册列表仍是独立显式清单。framework runner 必须在 `ToolCallOutput` 中保留工具返回的结构化 output； `format_tool_call_message` ，不得丢弃 `TOOL_CALL_PENDING_MESSAGE` 后自行拼另一套“等待确认”输出。
- `EditorAgentToolCall.displayArgs` 是必填、只读的用户确认展示投影，与 `args` 分离：
- `stringArgs` 保存提示词、比例、清晰度、模型、时长等可展示参数的稳定名称、用户可见标题和值；前端渲染模型字段时复用图片编辑器公共展示名映射，`gemini-3.1-flash-image-preview` 显示为 `nanobanana2` 、`audio1.0` 显示为 `Vidu` 、`chirp-v5` 显示为 `Suno` ，视频模型显示现有产品标签，不得改写后端参数真相；
- `imageArgs` 按“目标图片 / 参考图片”等参数分组，每个 `refs` 项包含与规范参数对应的 `imageId` ，以及后端从已校验会话上下文解析出的 `objectKey` 、`imageSrc` 、可选 `thumbnailSrc` / `label` / `width` / `height` 。
@@ -104,19 +108,19 @@
## LLM 与计费
- 编排复用 `creative_agent_gpt5_client` 的 LLM 接入配置（同 provider/env，独立用途标识），画布 Agent 规划请求固定使用 VectorEngine `gpt-5.4-mini` Chat Completions； 八 类工具。
- 编排复用 `creative_agent_gpt5_client` 的 LLM 接入配置（同 provider/env，独立用途标识），画布 Agent 规划请求固定使用 VectorEngine `gpt-5.4-mini` Chat Completions； 显式 注册十 类工具。
- 每个用户回合必须由 LLM 返回结构化计划；LLM 未配置、连接已经断开、请求明确失败、达到最终安全上限或返回格式不可解析时，后端写入正文为 `ERROR <错误内容>` 的 system 消息，不使用本地关键词或“收到：...”回显兜底。面向用户的规划错误使用中文语义，不暴露 `completion error` 等 framework 内部前缀或原始配置/定价诊断；原始错误只记录在后端日志。该错误消息与其它 system 消息一样进入后续 LLM memory，使 Agent 能看到上一轮失败上下文。普通 JSON POST 尚未结束只表示 provider request future 仍在等待，不能伪装成已持久化失败。
- 规划 prompt 必须自动带入上一条已完成生成结果的 `latestGeneratedImage` 引用，内容只包含上一轮 generation 的 `toolName` / `imageId` / `resourceId` / `objectKey` / `assetObjectId` 等轻量元数据，不把私有签名 URL 或大图内容塞进 prompt。
- 工具参数中的图片 ID 是由真实 object key 或图片地址计算的稳定 SHA-256 标识；真实 data key 仅存于 api-server 的工具上下文映射，所有图片工具在执行时查表恢复，不能把 object key 或图片地址作为 LLM 可见的工具 ID。
- 用户使用「这张」「刚才那个」「上一张」「把衣服换成……」等方式指代或编辑上一张结果图时，LLM 默认选择 `edit-image` ，并把 `latestGeneratedImage.imageId` 传入 `edit-image.object_image_id` ；不得构造工具 schema 中不存在的 `source_image_id` 。除非用户明确要求全新生成，否则不能因为本轮没有重新上传附件而降级为 `generate-image` 。
- 规划 prompt 必须显式区分“规范展板”和“实际素材产出”：规范图、视觉规范图、风格规范图、素材规范展板、角色规范图等规范展板请求走 `generate-image` ，并补齐统一视角、线条粗细、色卡、材质、阴影、圆角、状态层级、尺寸标注等要求；实际角色立绘才走 `generate-character` ，多个图标素材 / 图集才走 `generate-icon-spritesheet` 。
- 画布 Agent 规划请求使用 Chat Completions 和 1024 `max_tokens` 。发送后 120 秒是前端软提示阈值，不是 provider 失败 deadline：若普通 JSON POST 仍 pending，消息流临时显示“仍在处理中，请耐心等待”并继续等待，提示不写入 OSS 消息历史；连接或请求明确失败则立即按正式错误收口。provider 单 attempt 保留 8 分钟 hard timeout；请求发起阶段的 timeout、连接失败、`408` 、`429` 与 `5xx` 读取 `GENARRATIVE_LLM_MAX_RETRIES` ，但画布 Agent 最多重试 1 次，专用重试退避最多 60 秒。消息规划生命周期从 handler 入口开始计入 18 分钟总 deadline，进入 `agent.prompt(...)` 时使用扣除会话锁和上下文准备后的剩余预算；该 deadline 必须作为 runner 内部 deadline future 参与 completion await，并在每个 tool 开始前、返回后检查，不能用外层 `tokio::timeout` 丢弃整个 prompt future，也不能中途 drop 已开始的工具。工具一旦开始就等待其返回，再按 deadline 携带结果收口；当前八类画布 工具只做同步参数校验并返回待确认，因此不会延长正式生成链 。deadline 命中时仍按 `PromptRunError` 返回已经完成的工具结果、提交对应 staged memory 并追加终态错误。该 deadline 覆盖非法 JSON/工具校验失败触发的后续规划轮，并为错误持久化和 HTTP 返回保留约 2 分钟，不再让前端 20 分钟 transport timeout 先触发。已收到成功响应头后的响应体读取或解析失败直接按明确失败收口，错误计数/日志使用该响应所属的真实 attempt。规划重试发生在任何生成工具执行之前，不会重复提交生成任务或扣费；生成图片/编辑图片仍走对应生成工具和模型计费。
- 画布 Agent 规划请求使用 Chat Completions 和 1024 `max_tokens` 。发送后 120 秒是前端软提示阈值，不是 provider 失败 deadline：若普通 JSON POST 仍 pending，消息流临时显示“仍在处理中，请耐心等待”并继续等待，提示不写入 OSS 消息历史；连接或请求明确失败则立即按正式错误收口。provider 单 attempt 保留 8 分钟 hard timeout；请求发起阶段的 timeout、连接失败、`408` 、`429` 与 `5xx` 读取 `GENARRATIVE_LLM_MAX_RETRIES` ，但画布 Agent 最多重试 1 次，专用重试退避最多 60 秒。消息规划生命周期从 handler 入口开始计入 18 分钟总 deadline，进入 `agent.prompt(...)` 时使用扣除会话锁和上下文准备后的剩余预算；该 deadline 必须作为 runner 内部 deadline future 参与 completion await，并在每个 tool 开始前、返回后检查，不能用外层 `tokio::timeout` 丢弃整个 prompt future，也不能中途 drop 已开始的工具。工具一旦开始就等待其返回，再按 deadline 携带结果收口；九类收费生成 工具只做同步参数校验并返回待确认，`split-elements` 则在该 deadline 内完成确定性拆图 。deadline 命中时仍按 `PromptRunError` 返回已经完成的工具结果、提交对应 staged memory 并追加终态错误。该 deadline 覆盖非法 JSON/工具校验失败触发的后续规划轮，并为错误持久化和 HTTP 返回保留约 2 分钟，不再让前端 20 分钟 transport timeout 先触发。已收到成功响应头后的响应体读取或解析失败直接按明确失败收口，错误计数/日志使用该响应所属的真实 attempt。规划重试发生在任何生成工具执行之前，不会重复提交生成任务或扣费；生成图片/编辑图片仍走对应生成工具和模型计费。
- function-calling runner 必须把“等待用户确认”作为显式工具语义：当本批所有工具都校验成功并进入待确认状态时，立即以成功结果结束当前规划回合并持久化助手文本与待确认卡，不得继续依赖 LLM 自行停止；未知工具、参数错误、普通连续工具和不可解析响应仍受 `max_turns` 保护。
- runner 失败必须返回显式的 `PromptRunError { error, partial_outputs }` ，不得只返回终态错误而丢弃本轮已产生的文本或工具事实。prompt 执行使用 `AgentMemory::begin_staged` 创建行为等价且写入隔离的 `StagedAgentMemory` 事务，限长、摘要、脱敏等 append 规则必须在本轮 completion 前生效；成功或已发生工具活动时必须显式调用 `commit()` ，直接 drop staged transaction 表示回滚，不得统一复制成 `VecMemory` 或仅替换 box 冒充持久化提交。本轮无工具活动失败时回滚 staged 用户消息、助手文本和不可解析响应；已有工具活动时在末尾追加 terminal error closure 后提交。外部 drop / abort 若尚无工具活动则回滚并保持原 committed memory；若工具已完成则提交结果与取消闭环，若工具仍在执行则提交“已启动、结果未知”事实与取消闭环，后续必须先 reconcile 再决定是否重试。
- `ToolFailure` 必须以结构化工具失败输出暴露给 harness 调用方：调用方能读取 `kind` 、`retryable` 、`fatal` 和工具返回的原始 `output` ；不得把它们压成单一错误字符串。这些字段只提供流程决策与诊断事实，是否重试、如何展示或持久化仍由业务调用方决定。
- api-server 收到带 `partial_outputs` 的终态失败时，必须先按原顺序把其中已成功工具转成 `status=not_completed` 待确认消息并写入同一会话增量，再追加 `ERROR <错误内容>` 终态 system 消息；不得因后续轮次、其它工具或 `max_turns` 失败而吞掉已经执行并返回的工具结果。
- 通用 JSON function-calling 协议、工具 schema 注入、memory / hook、`max_turns` 和“全部工具待确认即结束回合”统一由现役 `platform-agent-harness` 承载；无工具时也必须输出同一 JSON 响应格式。画布角色 prompt、规范展板 / 已有图路由、模型与超时 profile、八类工具、计费、OSS 会话和 external job 编排继续留在 `platform-editor-agent` / `api-server` ，不得回流已退役的旧 `platform-agent` 。
- **对话回合免费**（聊天、分析回复不扣泥点），仅 Agent 实际触发生成工具时按对应模型定价扣泥点。
- **对话回合免费**（聊天、分析回复不扣泥点），仅 Agent 实际触发生成工具时按对应模型定价扣泥点；确定性 `split-elements` 免费 。
- 工具调用前后端校验泥点余额；不足时该次生成失败并在对话中以明确错误气泡告知，对话本身可继续。
## Lovart 参照做/不做清单（验收标准）
@@ -165,7 +169,7 @@
2. 存储层（spacetime-module 表 + procedure + migration + spacetime-client + schema check）；
3. api-server 会话 CRUD + 消息 OSS 读写 + JSON 回显桩（不接 LLM，先保证会话链路端到端真实落库）；
4. 前端最小纵切（对话框、会话管理、消息流、附件弹窗、侧边栏/小地图默认值）——可与 3 并行：3 只碰 `server-rs/` ， `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` 与相关文档。
## 第一阶段验收补充
