# 多媒体能力与 MCP 适配调整说明

## 背景

当前项目已经具备图片生成、视频生成、STT、TTS 等多媒体能力，并由 `tiangong-core` 通过 `tiangong-media` 统一调度。

在最近的问题排查中，暴露出一个关键缺陷：

- 图片生成结果在部分链路中被当成普通工具 `stdout` 文本处理。
- 前端展示依赖消息语义，而不是依赖工具日志。
- 一旦图片结果退化为工具文本，就容易出现：
  - 图片 Markdown 被截断
  - 前端只按纯文本显示
  - 无法区分“最终结果图片”和“中间过程图片”

同时，也提出了一个新的架构问题：

- 是否将图片/视频等多媒体能力统一迁移到 MCP 实现。

本说明用于明确后续架构调整方向，避免多媒体链路继续沿着“工具文本化”演化。

## 结论

后续多媒体能力采用以下原则：

1. 图片、视频、STT、TTS 等能力继续保留原生主链路。
2. MCP 不作为多媒体能力的唯一实现方式。
3. MCP 可以作为多媒体能力的一种后端适配来源。
4. 多媒体结果必须从工具文本中解耦，提升为明确的媒体结果语义。
5. 前端展示应基于媒体结果语义，而不是基于工具日志猜测内容类型。

## 为什么不统一改成 MCP

如果把图片、视频等多媒体能力全部降成 MCP tool，会带来几个明确问题：

- 返回值容易退化成普通文本，继续放大当前图片展示问题。
- 二进制结果、媒体 URL、缩略图、尺寸、格式、时长等元数据难以稳定表达。
- 进度、取消、重试、任务状态、审计和成本统计更难统一。
- 前端最终仍需要重新猜测“这个工具输出是不是图片/视频”，语义边界不稳定。

因此，MCP 更适合作为“后端适配器来源”，而不是“媒体能力主语义”。

## 调整目标

### 1. 保持媒体能力为一等公民

`tiangong-core` 中的媒体能力应继续作为独立能力存在，而不是普通工具文本输出的附属物。

这意味着：

- 图片/视频生成结果需要有独立结果模型
- 结果中要包含结构化媒体信息
- 会话层要能表达“这是媒体结果”而不是“这是一段工具输出”

### 2. 区分最终结果与中间过程

生成图片、视频这类能力有两种不同语义：

- 最终结果
  - 用户这一轮就是要图片或视频本身
  - 媒体应直接作为最终可展示结果进入会话
- 中间过程
  - 图片/视频只是后续分析、编辑、二次处理的输入
  - 此时媒体不应被误当成最终回复
  - 后续仍可能继续推理、继续调用工具、继续生成文本结论

因此后续实现必须支持“延迟决策”，而不能简单地把 `generate_image` 结果一律提升成 assistant 最终消息。

### 3. 建立统一媒体结果模型

后续应在核心层定义明确的媒体结果语义，例如：

- `MediaResult`
- `MediaAsset`
- `MediaKind`
- `MediaMessageContent`

建议至少覆盖：

- 图片 URL / 本地路径 / data URL
- 视频 URL / 本地路径
- 标题或说明文字
- 来源能力（image_generation / video_generation / tts / stt）
- 是否为最终展示结果
- 是否可继续作为后续工具输入

## 推荐架构

### 分层原则

后续多媒体架构保持三层：

1. `tiangong-core`
   - 负责媒体能力调度
   - 负责会话语义与最终展示语义
   - 负责区分最终结果与中间过程

2. `tiangong-media`
   - 负责统一媒体后端抽象
   - 定义图片/视频/STT/TTS 的原生接口
   - 返回结构化媒体结果

3. 后端实现层
   - 原生 provider 实现
   - MCP adapter 实现

### MCP 在后续架构中的位置

MCP 的正确位置应是：

- 作为 `tiangong-media` 的一种后端适配器
- 而不是直接替代媒体主链路

也就是说，后续如果要支持“通过 MCP 生成图片/视频”，应采用类似结构：

- `tiangong-media::image::ImageGenerator`
- `tiangong-media::video::VideoGenerator`
- `tiangong-media::mcp_image`
- `tiangong-media::mcp_video`

上层仍然只认统一媒体结果，不直接认 MCP tool 文本输出。

## 会话与渲染调整方向

### 当前问题

当前本地链路中，图片结果会在某些场景下进入：

- system 消息
- 工具执行日志
- 被裁剪的 `stdout`

这会导致：

- 图片 Markdown 被破坏
- 前端无法稳定渲染
- 无法区分媒体是否属于最终结果

### 调整方向

后续应改为：

1. 工具日志只保留摘要
   - 例如“已生成 1 张图片”
   - 不再承载完整图片展示内容

2. 媒体结果进入明确的会话消息语义
   - 最终结果时，进入 assistant 可展示消息
   - 中间结果时，进入结构化媒体记录或中间产物槽位

3. 前端按媒体语义渲染
   - 图片显示图片组件
   - 视频显示视频组件
   - STT/TTS 显示对应媒体交互组件

## 实施建议

后续建议按以下顺序推进：

### 第一阶段：结果语义解耦

- 从工具文本输出中分离图片/视频结果
- 建立结构化媒体结果模型
- 明确最终结果与中间过程的判定时机

### 第二阶段：会话消息模型扩展

- 会话层支持媒体消息内容
- 前端基于媒体消息内容渲染，而不是依赖 Markdown 猜测

### 第三阶段：MCP 媒体适配器

- 为 `tiangong-media` 增加 MCP adapter
- 让 MCP 成为媒体后端之一
- 不改变上层 `core` 和前端的媒体语义

## 当前约束

在完成结构化媒体结果模型之前，临时修复可以保留，但不能把它视为最终方案。

例如：

- 把生成图片结果暂时提升为 assistant Markdown 消息

这类做法可以缓解展示问题，但仍然无法完整区分：

- 最终结果图片
- 中间过程图片
- 后续需要继续加工的图片

因此它只能作为过渡修复，不能替代本说明里的正式调整方向。

## 后续开发准则

在多媒体相关开发中，后续必须遵守以下规则：

1. 不再把图片/视频最终展示内容仅作为工具日志保存。
2. 不再以 MCP tool 文本作为多媒体主结果语义。
3. 多媒体结果必须先转换成统一媒体结果模型，再进入会话层。
4. 前端展示应优先消费结构化媒体语义，而不是消费工具日志。
5. MCP 若参与多媒体实现，只能作为媒体后端适配器接入。
