life-echo/docs/plans/2026-03-10-memoir-image-generation-design.md

# 回忆录自动图片生成与插入设计

日期：2026-03-10  
范围：`api` + `app-android` + PDF 导出链路  
状态：已完成设计评审（分节确认通过）

## 1. 背景与问题

当前回忆录生成链路已经具备三个前置条件：

- LLM 会在章节正文中插入 `{{{{IMAGE:描述}}}}` 占位符
- `Chapter.images` 与 `Book.cover_image_url` 已在数据库模型中预留
- Android 端已具备“无图片则移除占位符”的兜底逻辑

但系统仍缺少完整的图片生产与消费闭环：

- 没有占位符解析与结构化存储
- 没有图片生成 provider 封装
- 没有对象存储持久化
- Android 无法按占位符位置渲染图片
- PDF 导出会原样输出图片占位符
- `memory_agent.py` 中的 `image_suggestions` 未进入正式链路

这导致当前提示词虽然已经产出图片意图，但业务上仍然只能展示纯文本章节。

## 2. 目标与非目标

### 2.1 目标

- 在章节叙事生成后自动提取图片占位符
- 通过图片生成 provider 生成配图，并持久化到腾讯云 COS
- 将图片结果写回 `Chapter.images`
- Android 按正文中的占位符位置渲染图片、加载态与失败态
- PDF 导出时嵌入图片或清理占位符
- 图片生成支持开关、上限、风格、尺寸等配置
- 图片生成失败不影响章节文本生成与展示

### 2.2 非目标

- 本期不做 iOS 适配
- 本期不引入多 provider UI 配置
- 本期不新增独立图片任务表
- 本期不依赖 provider 临时 URL 作为最终展示地址

## 3. 方案决策

### 3.1 已确认的关键决策

- `Chapter.images` 直接升级为对象数组，不保留 `List<String>` 旧契约
- 图片生成采用异步补图模式，不阻塞章节文本返回
- 图片最终持久化到腾讯云 COS
- 当前 provider 定为 Liblib，但其调用细节暂未确认，后端通过 adapter 抽象同步/异步差异

### 3.2 方案对比

- 方案 A：将图片生成并上传全部并入 `process_memoir_segments`
  - 优点：代码集中
  - 缺点：章节任务变长，失败面扩大，不符合“先出文本、后补图”
- 方案 B：章节生成任务 + 章节补图子任务
  - 优点：职责清晰，失败隔离好，最贴合当前需求
  - 结论：采用
- 方案 C：新增图片任务表与完整流水线
  - 优点：长期最规范
  - 缺点：超出本期范围，改动过重

## 4. 总体架构

```mermaid
flowchart TD
  segment["Segment transcripts"] --> memoirTask["process_memoir_segments"]
  memoirTask --> narrative["Generate chapter narrative with IMAGE placeholders"]
  narrative --> initImages["Initialize Chapter.images from placeholders"]
  initImages --> persistChapter["Save chapter text + pending image items"]
  persistChapter --> returnText["Chapter text available to client"]
  persistChapter --> imageTask["generate_chapter_images(chapter_id)"]
  imageTask --> promptOpt["Prompt optimization with LLM"]
  promptOpt --> provider["ImageGenerationProvider"]
  provider --> download["Download generated image bytes"]
  download --> cos["Tencent COS upload"]
  cos --> updateChapter["Update Chapter.images item status/url"]
  updateChapter --> android["Android chapter rendering"]
  updateChapter --> pdf["PDF export rendering"]
```

设计原则：

- 章节文本与图片生成解耦
- `Chapter.images` 作为图片状态与渲染的唯一事实来源
- 图片子任务按 item 状态幂等执行
- provider 与存储能力通过 service abstraction 隔离

## 5. 数据模型设计

`Chapter.images` 升级为对象数组，建议最小结构如下：

```json
[
  {
    "index": 0,
    "placeholder": "{{{{IMAGE:南方小镇的青石板路}}}}",
    "description": "南方小镇的青石板路",
    "prompt": "A serene old town in southern China, bluestone path, white walls, black tiles...",
    "url": "https://cdn.example.com/memoirs/chapters/xxx.png",
    "status": "pending",
    "provider": "liblib",
    "style": "watercolor",
    "size": "1024x1024",
    "error": null,
    "created_at": "2026-03-10T10:00:00Z",
    "updated_at": "2026-03-10T10:00:00Z"
  }
]
```

字段说明：

- `index`：该图片在章节中的顺序索引
- `placeholder`：原始占位符文本，用于正文位置匹配
- `description`：从占位符中解析出的原始描述
- `prompt`：优化后的生成 prompt，便于审计与排障
- `url`：腾讯云 COS 上的持久化访问地址
- `status`：`pending | processing | completed | failed`
- `provider`：当前为 `liblib`
- `style` / `size`：便于后续风格和尺寸策略落地
- `error`：失败时的摘要信息
- `created_at` / `updated_at`：状态追踪

`Book.cover_image_url` 保留现有结构，作为 P3 交付项。

## 6. 后端处理流程

### 6.1 章节任务

`process_memoir_segments` 保持现有文本生成职责，在章节内容落库前后增加两步：

1. 生成叙事正文，正文中保留 `{{{{IMAGE:...}}}}`
2. 从正文中提取图片占位符
3. 按配置进行去重、排序、截断
4. 初始化 `Chapter.images` 为 `pending` item 列表
5. 保存章节文本和图片元数据
6. 派发 `generate_chapter_images.delay(chapter.id)`

这样章节文本可先返回，不被图片生成阻塞。

### 6.2 图片子任务

新增 `generate_chapter_images(chapter_id: str)`：

1. 读取最新章节数据
2. 仅选择 `pending` 或允许重试的 `failed` item
3. 逐项将状态更新为 `processing`
4. 生成 prompt
5. 提交 provider 任务并等待结果
6. 下载图片字节
7. 上传 COS
8. 回写 `url`、`prompt`、`status=completed`
9. 失败则回写 `status=failed` 与 `error`

单张图片失败不影响同章节其他图片。

### 6.3 幂等性

- 已有 `completed` 且存在 `url` 的 item 不重复生成
- 重跑章节时按 `placeholder` 去重
- COS key 使用 `chapter_id + index + prompt_hash` 生成
- 子任务每次读取数据库最新状态，避免并发覆盖旧值

## 7. 占位符解析与 Prompt 优化

### 7.1 占位符解析

新增 `parse_image_placeholders(content: str)`，输出：

```json
[
  {
    "index": 0,
    "description": "南方小镇的青石板路",
    "placeholder": "{{{{IMAGE:南方小镇的青石板路}}}}",
    "start_offset": 128
  }
]
```

规则：

- 只匹配 `{{{{IMAGE:...}}}}` 主格式
- 保留原始顺序
- 去掉空描述
- 可按描述文本去重
- 配置图片上限，默认每章最多 2 至 3 张

`start_offset` 仅服务端内部使用，不暴露给客户端。

### 7.2 Prompt 优化

新增 image prompt optimizer：

- 输入：占位符描述、章节标题、章节分类、前后文摘要
- 输出：英文图片生成 prompt、风格、尺寸

优先按章节分类映射默认风格：

- `childhood` / `family`：温暖插画或水彩
- `career_*`：偏写实
- `beliefs` / `summary`：更克制、书籍插画感

如果 LLM 优化失败，则退回“原始中文描述 + 章节上下文”的降级 prompt，不阻塞图片生成。

## 8. Provider 与腾讯云 COS 设计

### 8.1 Provider 抽象

新增接口：

```python
class ImageGenerationProvider:
    def submit_generation(self, prompt: str, size: str, style: str) -> dict: ...
    def poll_generation(self, job: dict) -> dict: ...
    def download_image(self, result: dict) -> bytes: ...
```

当前实现 `LiblibImageProvider`，内部可适配两类 provider 行为：

- 同步返回图片结果
- 异步返回任务 ID 后轮询结果

这样即使 Liblib 最终 API 细节变化，任务编排层仍保持稳定。

### 8.2 COS 存储

新增 `TencentCosStorageService`：

- 输入：图片字节、key、content type
- 输出：可持久访问的 URL

推荐 key 结构：

- `memoirs/{user_id}/{chapter_id}/{index}-{prompt_hash}.png`

存储要求：

- 只保存 COS URL 到数据库
- 不依赖第三方临时 URL
- 上传后可选做图片格式标准化与压缩

## 9. Android 渲染方案

Android 不再只把正文当作一整块 Markdown 字符串处理，而是新增“正文块解析层”：

- `TextBlock`
- `ImageBlock`

流程：

1. 根据正文中的 `placeholder` 将内容拆分为顺序块
2. 用 `placeholder` 匹配 `Chapter.images`
3. 按图片状态渲染对应 UI

渲染规则：

- `completed`：显示图片
- `pending` / `processing`：显示固定比例占位骨架
- `failed`：隐藏图片并保持正文连续

推荐使用自定义 Compose 组件渲染图片，不使用 Markdown 内联图片，原因是：

- 更易处理加载态和失败态
- 更易支持点击放大查看
- 更便于后续统一样式和缓存控制

`TextUtils.removeImagePlaceholders()` 调整为兜底工具，仅在“无可用图片渲染链路”场景下移除占位符。

## 10. PDF 导出方案

`pdf_service.py` 需要从“纯文本分段输出”升级为“文本块 + 图片块”输出：

1. 解析章节内容中的占位符
2. 匹配 `Chapter.images`
3. 对 `completed` 图片下载并嵌入 PDF
4. 对 `pending` / `failed` / 丢失图片移除占位符

约束：

- PDF 中绝不能原样输出 `{{{{IMAGE:...}}}}`
- 图片下载失败时回退为纯文本段落
- 图片尺寸需要统一，避免破坏版式

## 11. 配置与开关

建议新增环境变量：

- `MEMOIR_IMAGE_ENABLED`
- `MEMOIR_IMAGE_MAX_PER_CHAPTER`
- `MEMOIR_IMAGE_PROVIDER`
- `MEMOIR_IMAGE_STYLE_DEFAULT`
- `MEMOIR_IMAGE_SIZE_DEFAULT`
- `LIBLIB_API_KEY`
- `LIBLIB_BASE_URL`
- `TENCENT_COS_SECRET_ID`
- `TENCENT_COS_SECRET_KEY`
- `TENCENT_COS_REGION`
- `TENCENT_COS_BUCKET`
- `TENCENT_COS_BASE_URL`

默认策略：

- 功能默认关闭
- 每章图片默认上限 2
- provider 默认 `liblib`
- 图片生成失败不影响章节成功状态

## 12. 错误处理与重试

重试分层：

- 章节任务：保持现有重试策略
- 图片子任务：单张图片最多重试 2 至 3 次
- COS 上传失败：可在单图级别重试

错误原则：

- 单图失败不阻塞同章节其他图片
- 保留 `error` 字段用于排障
- provider 或 LLM 异常时只影响对应图片项

状态流转：

```text
pending -> processing -> completed
pending -> processing -> failed
failed -> processing -> completed
```

## 13. 测试与验收

### 13.1 后端测试

- 占位符解析单元测试
- 章节初始化图片列表测试
- 图片子任务幂等测试
- provider adapter mock 测试
- COS 上传 service 测试
- PDF 导出占位符清理与图片嵌入测试

### 13.2 Android 测试

- 内容块解析测试
- 图片状态渲染测试
- 图片点击放大交互测试
- 无图片 / 失败图片 / 部分成功图片混合场景测试

### 13.3 验收标准

- 章节生成后自动初始化图片任务
- 生成成功图片的 URL 正确写入 `Chapter.images`
- Android 正确按正文位置展示图片
- 图片失败时正文正常显示，用户不看到原始占位符
- PDF 成功嵌入图片或清理占位符
- 功能可通过配置开关关闭

## 14. 分期落地

### P0

- 占位符解析
- `Chapter.images` 对象数组升级
- 图片 provider adapter
- Prompt 优化
- 腾讯云 COS 上传
- Celery 图片子任务

### P1

- Android 图片渲染与点击放大
- 加载态 / 失败态展示

### P2

- PDF 图片嵌入与占位符清理

### P3

- 基于整本回忆录摘要生成 `Book.cover_image_url`

### P4

- 多 provider 支持
- 风格自定义
- iOS 适配

## 15. 风险与缓解

### 15.1 风险

- `Chapter.images` API 契约升级会影响 Android 反序列化
- Liblib API 细节未最终确认
- 图片生成成本可能随章节数增长
- PDF 图片下载可能导致导出变慢

### 15.2 缓解

- 服务端与 Android 同步升级，空数组兼容历史数据
- 使用 provider adapter 隔离 Liblib 具体协议
- 配置每章图片上限，默认关闭功能
- PDF 对失败图片只做清理，不阻塞导出

## 16. 实施建议

推荐按以下顺序实现：

1. 后端数据契约与占位符解析
2. 图片子任务与 COS 上传
3. Android 内容块渲染
4. PDF 导出改造
5. 封面图生成

本设计已确认，可进入实现计划阶段。