# 图片发送时解析计划

## Current Design

- 上传接口 `POST /api/workspace/{workspace_id}/image-attachments` 保存原图、创建 `workspace_image_attachments` 记录，并立即启动后台解析。
- 前端把 `uploaded` / `processing` 都视为不可发送状态，轮询到 `ready` 后才允许用户发送。
- `GET /api/chat/stream` 只接受已经 `ready` 的 attachment，并把 `summary_for_agent.txt` 拼进发给 agent 的消息。

## Risks

- 用户粘贴或上传图片后，send 前的编辑、删除、取消都已经触发了模型解析，成本和时延不受用户最终发送动作控制。
- 解析结果可能对应用户最终不会发送的图片，attachment 的生命周期边界不清晰。
- 前端必须等待解析完成才能继续写消息，交互上像“上传即提交”。

## Target Contract

- 上传接口只做文件存储和 DB 记录创建，canonical 状态为 `uploaded`。
- 图片原始 bytes 不进入主 agent context。
- 只有用户点击 send 且消息引用 `attachment_ids` 时，后端才解析这些图片。
- send 链路解析成功后写入 `analysis.json` / `summary_for_agent.txt`，更新状态为 `ready`，再把 summary 注入 agent prompt。
- 解析失败时该轮 send 返回错误，attachment 状态为 `failed`，前端要求用户移除失败图片后重试。

## Implementation Steps

- 删除上传接口的后台解析调度。
- 将 `build_image_summary_prompt_block()` 改为按需解析 `uploaded` attachment。
- 前端 composer 允许 `uploaded` 图片直接发送，只阻止 `failed` 图片。
- 取消 uploaded 状态的轮询，避免上传后长期轮询。

## Verification Checklist

- 上传接口契约测试：上传后状态为 `uploaded`，不生成 analysis/summary 文件。
- send 前置解析契约测试：`build_image_summary_prompt_block()` 收到 `uploaded` 图片时触发解析，并产出 prompt summary。
- 前端类型检查通过。
- 后端图片 attachment 测试通过。