docs: 记录智能体头像主分支集成

.project-docs/20-architecture/data-flow.md

@@ -1,5 +1,11 @@
 # Data Flow
 
+## Personal cloud-agent avatars
+
+Renderer 选择头像 → Main 原生文件选择及 5 MB 校验 → 当前账号的 Yuxi Makelore 凭据 → 原生公开图片存储 → 返回持久化引用 `icon` 与独立展示地址 `icon_url`。上传只更新未保存预览；创建/保存才写入 Yuxi `Agent.icon`，省略字段保留旧值、显式 null 移除。取消或失败保留现有头像，账号切换丢弃迟到结果。
+
+个人列表和草稿读取当前头像；分享入口、接收列表与版本对比读取不可变发布快照。恢复版本将其头像复制到草稿；旧快照缺字段或图片加载失败使用默认图标。客户端不另建头像存储，移除引用不删除历史快照可能使用的图片。见[实现证据](../30-worklog/tasks/20261012-agent-avatars-840d7fd7.md)。
+
 ## Project conversations and distributed-agent consultation
 
 目录式创建 → Main 保存项目与 defaultAgentId → 项目直接列出会话 → 首次发送或显式新建创建 Conversation → 原 Pi 执行链。历史会话继续使用原 Agent 绑定；切换项目丢弃旧读取。