log and doc

2026-07-14 10:51:21 +08:00
parent d0451f8226
commit 21c39ee8db
2 changed files with 5 additions and 3 deletions
@@ -3138,7 +3138,8 @@

 ## 2026-07-13 画布 Agent 工具执行状态复用外部生成任务

- 决策：画布 Agent 的 OSS 工具消息删除独立 `status`，只保存可选 `externalJobId`、确认前取消事实 `cancelledAt` 和消息展示结果；`external_generation_job` 是排队、执行、完成、失败、lease 与计费结算的唯一真相。确认接口按 `conversationId + messageId + toolName` 稳定去重并复用既有编辑器 worker job kind，不新增 `editor_agent_tool_execution` 或其它关联表。
+- 决策：画布 Agent 的 OSS 工具消息使用 `status=not_completed|completed|failed|cancelled` 和可选 `externalJobId`；不使用 `cancelledAt`，不新增关联表。`external_generation_job` 是排队、执行、lease 与计费结算的唯一真相；OSS status 只表达该消息回填结果，不复制 queued / running。确认接口按 `conversationId + messageId + toolName` 稳定去重并复用既有编辑器 worker job kind。
+- 懒回填：只有下一次消息请求会在持有 conversation lock 后扫描 `status=not_completed` 且有 `externalJobId` 的工具消息，按 job id 定向读取主任务；完成时复用原工具 formatter 更新 system text、写入轻量媒体引用并标记 `completed`，失败时写入 `error` 并标记 `failed`。排队 / 执行保持 `not_completed`。前端轮询只读取 job，不刷新会话、不触发后端持久化。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`。