抽取画布 Agent 公共执行框架
新增业务中立的 function-calling harness 与公共提示词协议 统一画布 Agent 工具路由约束和待确认控制语义 保留失败前输出并事务化收口 memory、deadline 与取消状态 迁移画布 Agent 和 API 编排并同步架构文档与项目记忆
This commit is contained in:
@@ -4250,8 +4250,8 @@
|
||||
|
||||
- 背景：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 的 `toolName` / `resourceId` / `objectKey` 等轻量元数据。用户用「这张」「刚才那个」「上一张」「把衣服换成……」等方式指代上一张图或继续编辑时，规划默认调用 `edit_image` 并引用该结果；不能因为本轮没有手动附件而退回 `generate_image`。
|
||||
- 决策补充：画布 Agent 侧边栏的“规范图 / 视觉规范图 / 风格规范图 / 素材规范展板”是 Agent 规划 prompt 和 function-calling 工具选择约束，不是侧边栏 UI 说明文案。此类请求默认走 `generate_image`，prompt 必须要求规范展板包含统一视角、线条粗细、色卡、材质、阴影、圆角、状态层级、尺寸标注等视觉规范元素；角色规范图若是规范展板也走 `generate_image`，只有实际角色立绘才走 `generate_character`，多个图标素材 / 图集才走 `generate_icon_spritesheet`。
|
||||
- 决策补充：画布 Agent 的 planning prompt 必须自动注入上一条已完成生成结果的 `latestGeneratedImage`，来源为上一轮 generation 的 `toolName` / `imageId` / `resourceId` / `objectKey` 等轻量元数据。用户用「这张」「刚才那个」「上一张」「把衣服换成……」等方式指代上一张图或继续编辑时，规划默认调用 `edit-image` 并把 `latestGeneratedImage.imageId` 传入 `edit-image.object_image_id`；不得生成工具 schema 中不存在的 `source_image_id`，也不能因为本轮没有手动附件而退回 `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`。
|
||||
|
||||
@@ -4510,3 +4510,11 @@
|
||||
- 对账边界：保留管理员显式手动对账。owner 始终可用；member 必须单独持有 `profile-wallet-consumption-reconcile` 独立操作权限，任意 Tab 都不隐式授予。`POST /admin/api/profile/users/reconcile-consumption` 经二次确认后调用 runtime service identity 受限 procedure，扫描该用户全部权威流水、比较并校准投影，记录管理员与对账时间。
|
||||
- 展示边界：现有共享“用户详情”弹窗的钱包区增加“历史花费”，前端只展示 BFF 顶层字段，不自行汇总账单；只有 BFF 返回 `canReconcileConsumption=true` 时展示手动对账按钮。
|
||||
- 验证方式：SpacetimeDB 钱包聚合测试、api-server / admin-web 定向测试、`npm run spacetime:generate`、`npm run check:spacetime-schema`、`npm run check:spacetime-runtime-access`、`npm run admin-web:typecheck`、`npm run check:encoding`、`git diff --check`。
|
||||
|
||||
## 2026-07-28 画布 Agent 的通用 function-calling harness 与画布 prompt 分层
|
||||
|
||||
- 背景：画布 Agent 的 JSON 输出协议、tool schema 注入、memory / hook、轮次保护和“全部工具待确认即结束回合”原先位于 `platform-editor-agent/src/framework`，与规范展板、已有图编辑路由、模型超时和画布工具混在同一 crate；八类工具还重复携带待确认控制话术。旧 `platform-agent` 已随 Creative Agent 退役，不能作为新公共层复活。
|
||||
- 决策：新增无旧玩法依赖的现役 `platform-agent-harness`，只承载业务中立的 function-calling 执行协议；`platform-editor-agent` 通过兼容 re-export 复用该 crate，并继续承载画布 LLM profile、角色 prompt、公共美术工具路由策略、图片上下文和工具实现。无工具场景同样注入 JSON 响应格式；prompt 不再宣称工具并发执行；request 级 system prompt 必须真实进入本轮请求。画布对话额外注入最近一条已完成图片的有界 `latestGeneratedImage` 元数据，后续编辑仍只用 SHA-256 `imageId` 选图。
|
||||
- 执行与失败决策：prompt 每轮通过 `AgentMemory::begin_staged` 使用与调用方 memory 行为等价、写入隔离的 `StagedAgentMemory` 事务；成功或已有工具活动时显式 `commit()`，直接 drop 表示回滚。无工具活动失败时回滚本轮 staged 增量，已发生工具活动后失败时提交已发生工具事实并追加 terminal error closure。外部 future drop / abort 若发生在工具完成后，提交工具结果与取消闭环；若发生在工具执行中，提交“已启动、结果未知”与取消闭环，后续先 reconcile，不能假装副作用未发生。harness 通过 `PromptRunError { error, partial_outputs }` 显式返回终态错误和失败前输出；结构化工具失败还必须向调用方保留 `ToolFailure.kind/retryable/fatal` 与原始 `output`，不在 harness 内压成单一字符串。api-server 的 18 分钟总 deadline 以 runtime future 下沉到 runner：completion 可被 deadline 终止，工具在开始前检查、开始后等待返回、返回后携带结果收口；禁止外层 timeout drop prompt 或中途取消 effectful tool 后伪造空 partial。
|
||||
- 保留边界：会话幂等、OSS 消息、120 秒前端软提示、20 分钟 transport、18 分钟 handler 总 deadline、1024 tokens、8 分钟 provider attempt、泥点计费、确认入队和 external job 懒回填均不进入公共 harness。SpacetimeDB schema、前端 wire DTO 和侧边栏 UI 不变。
|
||||
- 验证方式：`cargo test -p platform-agent-harness`、`cargo test -p platform-editor-agent`、`cargo test -p api-server editor_agent`、`cargo check -p api-server --locked`、DDD 边界检查、Rustfmt、编码检查和 `git diff --check`。
|
||||
|
||||
@@ -3272,8 +3272,17 @@
|
||||
- 现象：画布 Agent 已生成有效工具规划，却最终只保存 `ERROR max turns reached: 3`，助手文本和待确认工具卡都消失。
|
||||
- 原因：八类画布工具的 `call()` 只返回待用户确认的规划结果，但 function-calling runner 在成功工具后仍继续请求 LLM，只靠 prompt 要求模型不再重试；模型连续返回工具调用直到上限后，错误结果又丢弃此前累积的输出。
|
||||
- 处理：工具通过框架契约显式声明 `requires_user_confirmation`；当本批全部工具都成功且等待确认时，runner 在处理完整批次后立即返回已有助手文本和工具结果。未知工具、参数错误、hook skip、普通连续工具和不可解析响应仍继续受 `max_turns` 门禁保护。不要用单纯提高轮次上限掩盖终止条件缺失。
|
||||
- 验证：runner 回归测试必须同时覆盖“待确认工具只调用一次 LLM 并成功结束”和“普通连续工具仍会触发 max-turn 门禁”。
|
||||
- 关联：`server-rs/crates/platform-editor-agent/src/framework/run.rs`、`server-rs/crates/platform-editor-agent/src/framework/tool.rs`、`server-rs/crates/platform-editor-agent/src/agent/tools/`。
|
||||
- 验证：runner 回归测试必须同时覆盖“待确认工具只调用一次 LLM 并成功结束”“普通连续工具仍会触发 max-turn 门禁”“多工具按数组顺序执行”“request 级 system prompt 真实进入请求”；公共 prompt 在无工具时仍必须包含 runner 所需的 JSON 响应格式，且不得宣称并发执行。
|
||||
- 关联：`server-rs/crates/platform-agent-harness/src/run.rs`、`server-rs/crates/platform-agent-harness/src/tool.rs`、`server-rs/crates/platform-editor-agent/src/agent/tools/`。
|
||||
|
||||
## Agent 终态失败不能吞掉已发生的工具事实
|
||||
|
||||
- 现象：同一轮 prompt 中前面工具已经成功生成待确认结果，但后续工具、hook、completion 或 `max_turns` 失败后，API 只保存最后一条 `ERROR `，已执行工具和用户本轮语义从会话历史中消失。
|
||||
- 原因：runner 只返回单一 `PromptError`，或者直接向 committed memory 逐步写入，无法区分“尚未发生外部工具事实，整轮可回滚”与“已发生工具事实，只能提交并闭合错误”。工具失败若被压成字符串，调用方还会丢失 `kind`、`retryable`、`fatal` 和原始 `output`。
|
||||
- 处理：用 `PromptRunError { error, partial_outputs }` 保留失败前输出，并将本轮 memory 先写入 staged buffer。无工具活动失败时整体回滚 staged 增量；有成功或失败工具活动时提交已发生事实，并追加 terminal error closure。api-server 按 `partial_outputs` 顺序先持久化成功工具的 `not_completed` 待确认消息，再追加 `ERROR ` 终态消息；`ToolFailed` 保留给调用方做诊断和流程决策，不伪装成成功确认卡。
|
||||
- 取消边界：不能在 prompt future 内对 `agent.memory.take()` 后跨 await 持有，也不能用统一 `VecMemory` staging 绕过自定义 memory 的限长、摘要或脱敏规则。`AgentMemory::begin_staged` 必须产生行为等价、写入隔离的 `StagedAgentMemory`，成功或已有工具活动时显式 `commit()`，直接 drop 才表示回滚。外部 drop 若发生在工具完成后，guard 必须提交结果与取消闭环；若工具仍在执行，至少提交“已启动、结果未知”事实，供后续 reconcile。正式总 deadline 应作为 runner 内部 future 终止 completion；工具开始前检查 deadline，一旦开始则不能中途 drop，必须等待结果后再携带 partial outputs 收口。外层 timeout 只适合作为进程级最后保险，不能承担业务收口。
|
||||
- 验证：至少覆盖“无工具 completion 失败回滚 staged 用户消息”“非 fatal 工具失败对调用方暴露 `kind/retryable/fatal/output`”“成功工具后终态失败保留 partial tool output”“有工具活动时 committed memory 末尾存在 error closure”以及“API 增量中待确认工具位于 terminal `ERROR ` 之前”。上一张图继续编辑的 prompt 测试必须断言 `latestGeneratedImage.imageId -> edit-image.object_image_id`，且最终 prompt 不含 `source_image_id`。
|
||||
- 关联：`server-rs/crates/platform-agent-harness/src/run.rs`、`server-rs/crates/platform-agent-harness/src/tool.rs`、`server-rs/crates/platform-editor-agent/src/agent/prompt.rs`、`server-rs/crates/api-server/src/editor_agent/api.rs`。
|
||||
|
||||
## 画布 Agent 的规划请求不能关闭瞬时失败重试
|
||||
|
||||
@@ -3281,7 +3290,7 @@
|
||||
- 原因：规划请求虽然有 Agent 专用单次 timeout，但 `editor_agent_llm_client` 把 `max_retries` 硬编码为 0；VectorEngine `gpt-5.4-mini` 的偶发长尾、连接超时或可重试上游状态会在第一次失败后直接持久化成 system error。framework 的英文 `completion error` 前缀也被原样暴露给用户。
|
||||
- 处理：120 秒改为前端软提示阈值：POST 仍 pending 时显示不入库的“仍在处理中，请耐心等待”；provider 明确断开/失败才写正式错误。专用 provider 单 attempt 使用 8 分钟 hard timeout，请求发起阶段读取 `GENARRATIVE_LLM_MAX_RETRIES`，但画布 Agent 最多重试 1 次且重试退避最多 60 秒。不要只计算单次 complete 的最坏时间：runner 还可因非法 JSON/工具校验失败进入后续轮次，必须从 handler 入口开始计算 18 分钟总 deadline，进入 `agent.prompt(...)` 时扣除会话锁/上下文准备已用时间，为持久化和前端 20 分钟 timeout 留出余量。响应头后的体读取/解析错误按明确失败收口，必须使用真实 attempt 计数；规划、配置和定价错误对用户统一为中文，原始诊断只记后端日志。重试发生在任何生成工具执行前，不会重复提交生成任务或扣费，不要通过提高前端 timeout 或 runner `max_turns` 掩盖 provider 重试缺失。
|
||||
- 验证：`platform-editor-agent` 测试锁定 8 分钟 hard timeout 与中文错误；前端 fake timer 用例锁定 120 秒前只显示思考动画、到点后显示耐心等待、成功/失败后移除；`platform-llm` 回归用例锁定第二次 attempt 成功响应头后的 body timeout 仍报累计 2 次；`api-server` 测试锁定专用 client retry、18 分钟整体 deadline 与中文直达错误。运行态排障按同一 request id 对齐 `platform_llm` failure stage 与 `/messages` 总耗时，并确认仍 pending 的请求不再在 120 秒形成错误气泡。
|
||||
- 关联：`server-rs/crates/platform-editor-agent/src/agent/agent.rs`、`server-rs/crates/platform-editor-agent/src/framework/error.rs`、`server-rs/crates/api-server/src/state.rs`、`src/components/image-editor/EditorAgentConversation/useEditorAgentConversation.ts`、`src/components/image-editor/EditorAgentConversation/MessageBubble.tsx`、`src/services/image-editor/editorAgentClient.ts`。
|
||||
- 关联：`server-rs/crates/platform-editor-agent/src/agent/agent.rs`、`server-rs/crates/platform-agent-harness/src/error.rs`、`server-rs/crates/api-server/src/state.rs`、`src/components/image-editor/EditorAgentConversation/useEditorAgentConversation.ts`、`src/components/image-editor/EditorAgentConversation/MessageBubble.tsx`、`src/services/image-editor/editorAgentClient.ts`。
|
||||
|
||||
## 前端退役目录不能只靠扫描和 ignore 隔离
|
||||
|
||||
|
||||
@@ -59,7 +59,7 @@
|
||||
- SpacetimeDB schema guard 比较当前工作树与基线提交时，两侧都必须分别读取各自 `Cargo.toml` 的 `lib.path`，再沿 `mod` / `#[path]` 只扫描该快照 crate root 可达的 schema；不得递归扫描整个 `src/`，否则原位保留的旧源码会与现役历史数据壳产生假 accessor 重复。
|
||||
- `module-runtime` 仍是账号、钱包、公共设置、追踪和 feature gate 的现役领域 crate；其混合源码中的 `CreationEntry*`、旧公开作品、旧存档 / 浏览历史 / 游玩统计 DTO、command、mapper 和规则必须以编译条件退出，且不再依赖只为旧创作契约存在的 `shared-contracts`。历史 schema 只继续编译 `RuntimeBrowseHistoryThemeMode` 六个变体和完整保序的 `RuntimeProfileWalletLedgerSourceType` 等持久化 ABI，不保留围绕这些类型的旧业务实现。
|
||||
- 纯模板 crate 和专属运行态 crate 不属于 workspace members、default members 或任何在运 crate 的依赖图；源码目录保持原样。
|
||||
- `platform-agent` 及其专属 `langchainrust` 依赖同样退出 workspace 与 `api-server` 依赖图；现役编辑器 Agent 仅需的模型常量收口到 `platform-llm`，不再通过旧拼图 Phase 1 / Creative Agent 执行器 crate 复用。
|
||||
- `platform-agent` 及其专属 `langchainrust` 依赖同样退出 workspace 与 `api-server` 依赖图；现役编辑器 Agent 仅需的模型常量收口到 `platform-llm`，不再通过旧拼图 Phase 1 / Creative Agent 执行器 crate 复用。后续抽出的 `platform-agent-harness` 是无旧玩法依赖的通用 JSON function-calling 底座，不得依赖、复用或重新挂回本条退役 crate。
|
||||
- `platform-auth` 不再编译 runtime guest token；`platform-wechat` 不再编译旧生成结果订阅服务，只保留现役认证和支付协议。
|
||||
|
||||
## 验收
|
||||
|
||||
@@ -24,7 +24,7 @@ SpacetimeDB 版本口径：当前 Rust crate `spacetimedb`、`spacetimedb-sdk`
|
||||
|
||||
- HTTP 与运维入口：`api-server`、`pingora-gateway`、`server-manager-panel`。
|
||||
- 现役领域模块：`module-ai`、`module-assets`、`module-auth`、`module-editor-agent`、`module-runtime`。`module-runtime` 继续承载账号、钱包、公共设置、追踪、功能门禁等现役平台领域能力；该 crate 名称不代表旧玩法 runtime 路由仍在运行。
|
||||
- 平台副作用：`platform-agent`、`platform-auth`、`platform-audio`、`platform-hyper3d`、`platform-image`、`platform-llm`、`platform-matting`、`platform-oss`、`platform-speech`、`platform-wechat`。
|
||||
- 平台副作用：`platform-agent-harness`、`platform-editor-agent`、`platform-auth`、`platform-audio`、`platform-hyper3d`、`platform-image`、`platform-llm`、`platform-matting`、`platform-oss`、`platform-speech`、`platform-wechat`。已退役 Creative Agent 的旧 `platform-agent` 只保留历史源码，不属于现役 workspace 或依赖图。
|
||||
- 共享层：`shared-contracts`、`shared-kernel`、`shared-logging`。
|
||||
- SpacetimeDB：`spacetime-client`、`spacetime-module`。
|
||||
- 测试支撑：`tests-support`。
|
||||
@@ -76,11 +76,16 @@ npm run check:server-rs-ddd
|
||||
|
||||
- `/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。
|
||||
- `platform-agent-harness` 只承载与具体业务无关的 JSON function-calling 协议、工具 schema 注入、memory、hook、typed tool、轮次保护和待用户确认终止语义；`platform-editor-agent` 在其上叠加画布专属 LLM profile、system prompt、跨工具路由规则、图片上下文与八类生成工具。公共 harness 不依赖画布 DTO、计费、OSS、Axum 或 external job，也不得复用已退役的旧 `platform-agent`。harness 失败契约固定为 `PromptRunError { error, partial_outputs }`；`partial_outputs` 显式携带失败前已产生的助手文本、成功工具和结构化失败工具输出。`ToolFailure` 的 `kind`、`retryable`、`fatal` 及工具原始 `output` 必须对 harness 调用方可见，不得在公共层压成字符串或擅自丢弃。
|
||||
- prompt runner 对每个调用通过 `AgentMemory::begin_staged` 创建行为等价、写入隔离的 `StagedAgentMemory` 事务：限长、摘要、脱敏或持久化 memory 的 append 语义必须在本轮模型请求前生效，不得统一降级成 `VecMemory`。成功结束或已发生工具活动时必须显式调用 staged `commit()`，直接 drop 表示回滚。无工具活动的 completion、hook、解析或 `max_turns` 失败丢弃 staged transaction；已有成功或失败工具活动时在末尾追加 terminal error closure 后提交。外部 future drop / abort 若发生在工具完成后，必须提交工具结果与取消闭环；若工具仍在执行，则提交“已启动、结果未知”事实与取消闭环，供后续 reconcile，不能假装工具没有发生。
|
||||
- 画布 handler 的 18 分钟总 deadline 通过 runtime 提供的 deadline future 下沉到公共 runner：completion await 可被 deadline 终止；effectful tool 在开始前检查 deadline，开始后不被中途 drop，返回后再携带结果收口为 `PromptRunError`。禁止用外层 timeout 直接 drop 整个 prompt future 并伪造空 `partial_outputs`。
|
||||
- `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 上限、会话内串行锁、读改写、消息与工具结果持久化和 `touch` 元数据更新时间；该 JSON 不进入 `editor_canvas.layers_json`，也不作为画布布局真相。LLM 未配置、连接已经断开、请求明确失败、达到最终安全上限或规划不可解析时，必须写入 `role=system`、正文以 `ERROR ` 开头的消息，并通过 `deltaMessages` 返回，`errorMessage` 保持为空；前端隐藏前缀并显示红色错误气泡，面向用户的错误正文使用中文语义，不暴露 `completion error` 等 framework 内部前缀或原始配置/定价错误；原始诊断只写后端结构化日志。后端仍把该 system 消息注入后续 LLM memory，使 Agent 能读取失败上下文。普通 JSON POST 尚未结束不形成持久化消息；工具失败同样必须形成可回读记录，不能只返回瞬时错误。
|
||||
- 画布 Agent 的 `gpt-5.4-mini` Chat Completions 规划使用 1024 `max_tokens`。前端在 POST pending 120 秒后显示不入库的耐心等待提示；provider request future 明确返回 connect/timeout/HTTP/transport 错误时立即进入正式失败，尚未返回则继续等待。专用 provider 单 attempt hard timeout 为 8 分钟；请求发起阶段的 timeout、连接失败、`408`、`429` 与 `5xx` 读取 `GENARRATIVE_LLM_MAX_RETRIES`，但画布 Agent 最多重试 1 次，显式配置 0 仍可关闭，专用重试退避最多 60 秒。消息规划生命周期从 handler 入口开始计入 18 分钟总 deadline，进入 `agent.prompt(...)` 时只使用剩余预算；该 deadline 覆盖会话锁/上下文准备与最多 3 轮规划，并为错误持久化/HTTP 返回预留约 2 分钟，不允许多轮规划绕过前端 20 分钟 timeout。已收到成功响应头后的响应体读取或解析失败直接按明确失败收口，并使用该成功响应所属的真实 attempt 记录错误。重试只包围 LLM 规划请求并发生在任何待确认工具执行之前，因此不会重复提交生成任务或扣费。
|
||||
- 对话附件只允许引用当前工程 `editor_project_resource` 或当前账号 `editor_asset` 的图片；前端可提交展示用 `imageSrc` / `thumbnailSrc`，后端必须按 `resourceId` / `assetId` 重新归一、校验 owner / project 和 `objectKey`，再给 LLM 或生成工具使用。
|
||||
- planning prompt 注入的 `latestGeneratedImage.imageId` 只能映射到 `edit-image.object_image_id`；`source_image_id` 不是现役 `edit-image` schema 字段，prompt、tool args、确认执行和测试中都不得生成或兼容该字段。
|
||||
- 画布 Agent 工具复用既有编辑器图片生成 / 修改 / 图标 spritesheet BFF，并继续使用后端模型定价和 `execute_billable_asset_operation_with_cost`；前端不提交 `priceMudPoints`。
|
||||
- api-server 对 `PromptRunError` 的持久化顺序固定为：先按 `partial_outputs` 原顺序映射已成功工具，将其保存为 `status=not_completed` 且无 `externalJobId` 的待确认消息；再在同一会话增量末尾追加 `ERROR ` terminal system 消息并整体写入 OSS。后续规划失败不得吞掉失败前已执行的成功工具结果；结构化 `ToolFailed` 可用于调用方诊断与流程决策，但画布确认面不得把它伪装成成功待确认卡。
|
||||
- `/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`、结构化画布表或 `external_generation_job` 的业务真相。未激活结构化存储的 canvas 才继续以 `editor_canvas.layers_json` 作为 legacy 布局真相。
|
||||
|
||||
@@ -106,12 +106,16 @@
|
||||
|
||||
- 编排复用 `creative_agent_gpt5_client` 的 LLM 接入配置（同 provider/env，独立用途标识），画布 Agent 规划请求固定使用 VectorEngine `gpt-5.4-mini` Chat Completions；function-calling 注册八类工具。
|
||||
- 每个用户回合必须由 LLM 返回结构化计划；LLM 未配置、连接已经断开、请求明确失败、达到最终安全上限或返回格式不可解析时，后端写入正文为 `ERROR <错误内容>` 的 system 消息，不使用本地关键词或“收到：...”回显兜底。面向用户的规划错误使用中文语义，不暴露 `completion error` 等 framework 内部前缀或原始配置/定价诊断；原始错误只记录在后端日志。该错误消息与其它 system 消息一样进入后续 LLM memory，使 Agent 能看到上一轮失败上下文。普通 JSON POST 尚未结束只表示 provider request future 仍在等待，不能伪装成已持久化失败。
|
||||
- 规划 prompt 必须自动带入上一条已完成生成结果的 `latestGeneratedImage` 引用，内容只包含上一轮 generation 的 `toolName` / `resourceId` / `objectKey` / `assetObjectId` 等轻量元数据，不把私有签名 URL 或大图内容塞进 prompt。
|
||||
- 规划 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` 作为源图；除非用户明确要求全新生成，否则不能因为本轮没有重新上传附件而降级为 `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 覆盖非法 JSON/工具校验失败触发的后续规划轮，并为错误持久化和 HTTP 返回保留约 2 分钟，不再让前端 20 分钟 transport timeout 先触发。已收到成功响应头后的响应体读取或解析失败直接按明确失败收口，错误计数/日志使用该响应所属的真实 attempt。规划重试发生在任何生成工具执行之前，不会重复提交生成任务或扣费；生成图片/编辑图片仍走对应生成工具和模型计费。
|
||||
- 用户使用「这张」「刚才那个」「上一张」「把衣服换成……」等方式指代或编辑上一张结果图时，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。规划重试发生在任何生成工具执行之前，不会重复提交生成任务或扣费；生成图片/编辑图片仍走对应生成工具和模型计费。
|
||||
- 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 实际触发生成工具时按对应模型定价扣泥点。
|
||||
- 工具调用前后端校验泥点余额；不足时该次生成失败并在对话中以明确错误气泡告知，对话本身可继续。
|
||||
|
||||
@@ -152,7 +156,7 @@
|
||||
- `GET/POST /api/editor/projects/{projectId}/agent-conversations`（列表/新建）；
|
||||
- `GET/DELETE /api/editor/agent-conversations/{conversationId}`（详情/软删）；
|
||||
- `POST /api/editor/agent-conversations/{conversationId}/messages`（JSON）；
|
||||
- Agent 编排（function-calling 循环、工具内部调既有生成执行链路）放 api-server 编排层，独立文件，不复用 `creative_agent.rs` 内存会话。
|
||||
- 通用 function-calling harness 放 `platform-agent-harness`；画布 Agent profile 与工具放 `platform-editor-agent`；会话、计费、OSS 和工具内部生成执行链路由 api-server 编排层承接，不复用 `creative_agent.rs` 内存会话。
|
||||
- `shared-contracts` + `packages/shared`：`editorAgent` 会话、消息、工具确认展示与轻量媒体结果 DTO；消息响应返回 `conversation`、`deltaMessages` 和可选 `errorMessage`。
|
||||
|
||||
## 实施顺序
|
||||
|
||||
Reference in New Issue
Block a user