摘要：让 Agent "看见"图片视频、把剪贴板里的多媒体粘进输入框——听起来是两个小功能，实际是三类上限、一把剪贴板类型、一次"技能影响了消息流"的概念混乱。这篇讲 MEDIA 与 PASTE 两大设计，以及"消息流即真相源"这个统一答案。
先讲一个 10 月 19 日的概念事故，它是这篇的题眼。用户在测试多媒体功能时问了一个问题：
MEDIA 的架构设计听起来是对的，但最终用技能实验出来，它怎么能影响到信息流里边消息里面已经读取的东西呢？
讨论绕了很久（"你用图示给我讲""这整个是怎么协作的？总管把图发给执行 Agent，执行 Agent 去读，怎么又看图是总管的了？"），最后用户自己一句话理清了：
哦，等于说都是执行 Agent 处理读取，只不过他们这几个 Agent 共用这个消息信息流引擎是吧？引擎会默认处理这个东西。
对。消息流是所有 Agent 共享的真相源：用户发的图、执行 Agent 读的文件、总管看的汇报，都挂在消息流上，谁需要谁取用。理解了这一点，MEDIA 和 PASTE 的设计就顺理成章了。
一、MEDIA：三种上限分开治
让 Agent"看见"图片/视频/音频，第一反应是把图塞进上下文。docs/MEDIA.md 开头就拆穿了这个直觉——三种"上限"要分开治：
- 会话上限：图片内联进上下文，几张图就把 token 吃光；
- 传输上限：大文件直接传，请求体爆炸；
- 理解上限：就算传进去，模型一次能"看清"的视觉信息也有限。
定案是引用式 + 请求期物化 + 视觉焦点窗口：
- 媒体进媒体库（内容寻址目录，去重），消息里挂引用而不是数据本体；
- 请求期物化：真正要模型看的时候才按需转成它能吃的形态；
- 视觉焦点窗口：一次只让模型"注视"有限的视觉内容，超预算走降级阶梯（按序退让：缩图→抽帧→转文字描述→只读元数据），每一级都保理解质量。
接入形态是 skill + CLI（flyagent-media，与 agent-browser 同构）：Agent 按 skill 的规矩用 CLI 读媒体。落地上演了一出"任务实测连挂排查"（bced6f8 fix(media): flyagent-media 修复（任务实测连挂排查）+ 测试记录与文档）——测试记录 docs/test-log-2026-10-20.md 完整留档了连挂的原因链。实测翻车不可怕，翻车不留档才可怕。
二、PASTE：剪贴板不是"一个东西"，是一把类型
⌘V 粘贴多媒体的需求听起来一句话："粘贴截图和文件进输入框。"实现前的分析（docs/PASTE.md）先把剪贴板拆开：
剪贴板不是「一个东西」，是一把类型。
纯文本、富文本、文件引用、图片位图、截图临时文件……⌘V 进来的可能是其中任意一种甚至多种。两个关键决策：
决策一：识别放后台。 前台 web 剪贴板 API 能力残缺（读不到文件路径），后台 NSPasteboard 全能。定案：后台分类识别，前端只触发——paste.rs（1200 行）按"先到先得、命中即停"的优先级分类。
决策二：插纯路径。 文件/图片落盘到工作区专属目录后，输入框里插纯路径文本，不搞"引用 + 路径"的花哨格式——Agent 本来就认路径，多一层格式多一层翻译。
01876b1 feat(paste): Composer ⌘V 粘贴多媒体——剪贴板识别，文件粘路径、截图落工作区
三、边界：别让特例污染通用路径
上线第二天发现两个边界病，都是同一类错误——特例逻辑溢出到通用路径：
我发现个问题：新增的粘贴图片和粘贴文件那块业务逻辑，现在影响整个粘贴的所有东西。它不应该影响所有粘贴的行为，它把自己的 block 里面内容加上就行了。
03487a4 fix(paste): 粘贴行格式化只管文件/图片块——文本原样插、尾部不补换行
修法就是把格式化逻辑的作用域收窄到自己的 block：文本原样插入，尾部不加换行，文件/图片块才走格式化。和第九篇"插件同级可插拔"是同一个哲学：加法的边界要收在加的地方。
PASTE 文档里还有两块值得抄的工程货：边界情况矩阵（每种剪贴板类型 × 每种输入场景）和降级阶梯（每级都不丢数据）——识别失败也绝不吞内容，宁可插原文。
四、小结
MEDIA + PASTE 合起来回答了一个问题：Agent 的多模态输入，数据放哪？ 答案统一：
- 消息流即真相源——媒体挂引用进消息流，谁用谁取；
- 物化在请求期——上下文里只放当下要看的；
- 识别在后台，契约最简——纯路径，不做格式发明；
- 特例不污染通用——加法的边界收在加的地方；
- 降级不丢数据——每一级退让都保理解、保内容。
下一篇回到"分身"的脑子：什么时候该自己拍板？
本系列基于 34 天真实开发记录（107 次提交、12 份设计文档、全程与 AI 结对）整理。
本文由 AI图鉴自动抓取并翻译，版权归原作者所有；如需查看原文请点下方链接。