Genarrative/docs/technical/PUZZLE_AGENT_ACTION_RESPONSE_SESSION_2026-04-25.md

拼图 Agent 操作回包收口说明

背景

拼图结果页在执行 select_puzzle_image 时，前端先调用 POST /api/runtime/puzzle/agent/sessions/:sessionId/actions，随后又调用 GET /api/runtime/puzzle/agent/sessions/:sessionId 拉取完整会话。完整会话包含消息、草稿与结果预览，体积明显大于一次选图操作本身，导致选择候选图时出现无意义流量与体感延迟。

落地规则

• actions 接口在服务端本来已经拿到变更后的 session，因此回包必须直接包含 operation + session。
• 前端收到 actions 回包后直接用 session 更新本地状态，不再为了同步选图、生成图片或编译草稿而补发完整会话 GET。
• publish_puzzle_work 发布后仍由服务端重新读取一次最新 session 并放入同一个 action response，前端只保留作品架与广场详情的必要刷新。
• 该改动只收敛 Rust api-server 与前端 contract，不引入 server-node 兼容逻辑。

验收口径

1. 选择拼图候选图只产生一次 POST /actions，不再紧跟完整 session GET。
2. 选图后结果页仍立即反映选中的正式图。
3. 发布后仍能跳转到已发布拼图详情。