# 图片上传与独立解析实现计划

## Current Design

- 当前 chat 入口是 `GET /api/chat/stream`，主 agent 只接收纯文本 prompt。
- workspace 文件预览已支持图片，但 chat message 没有通用 attachment 契约。
- evidence/postpass 已采用 backend-owned job 的模式，适合复用到图片解析：大 payload 留文件，主 agent 只读 compact summary。

## Target Contract

- 原图只进入 workspace 文件和 attachment 索引，不进入 `messages_v2.content`、`parts` 或 ACP prompt。
- 图片解析由 backend-owned image parser job 完成，不由主 agent spawn subagent。
- 主 agent 只通过 `attachment_ids -> summary_for_agent.txt -> compact prompt block` 感知图片。
- 只有 status 为 `ready` 的 attachment 才能进入 chat；`processing/failed` 不做隐式 fallback。

## Implementation Steps

- 增加 `workspace_image_attachments` 表和 `messages_v2.attachments` 列。
- 增加上传/查询 API：保存原图、写 DB、调度解析、返回状态。
- 增加 image parser core：默认调用 dev 环境同一套 Bedrock Claude Sonnet profile，输出 `analysis.json` 和 `summary_for_agent.txt`；无模型配置时标记失败。
- 修改 chat stream：接收 `attachment_ids`，校验 ready，拼接 compact image summary 到 effective prompt，并把 attachment metadata 写入 user message。
- 修改前端 ChatPanel：支持选择图片、等待解析完成、展示附件缩略图，发送时传 attachment ids。

## Verification Checklist

- 合法图片上传后文件落盘，DB 状态可从 `uploaded/processing` 到 `ready/failed`。
- failed/pending 图片不能随 chat 发送。
- ready 图片发送后，主 prompt 只包含 summary，不包含 base64 或原图 bytes。
- message history 可序列化/反序列化 attachments。
- 本地 pytest 覆盖 DB helper、解析 fallback、prompt assembly、API mock。