# 短视频解析接口（MCP）

通过 MCP 服务 `myai-mcp-production`（正式环境）或 `myai-mcp-test`（测试环境）调用，实现"提交视频 → AI 解析 → 获取拆解与脚本"的流程。

> ⚠️ 原 Python 脚本 `Douyin_Video_Analysis_API.py` 已弃用，全部功能由 MCP 工具替代。

## 前置条件

- MCP 服务已配置并 Trust（详见 `MCP_工具调用规范.md` 3 自动检测与安装引导）
- 已完成飞书登录（登录检查机制见 `MCP_工具调用规范.md` 4 登录状态检查）

---

## 1) 三个 MCP 工具

| 工具 | 用途 | 必填参数 | 适用场景 |
|------|------|---------|---------|
| `upload_douyin_video` | 提交抖音链接做 AI 内容解析入库 | `share_text`（链接/分享文案） | 对标视频是抖音链接时 |
| `upload_other_video` | 上传本地视频文件做 AI 内容解析入库 | `title` + `file_path` | 对标视频是本地文件时 |
| `short_video_detail` | 查询解析结果（文案+拆解），判断是否完成 | `id`（详情ID） | 上传后轮询获取解析内容 |

---

## 2) 使用流程

### 场景一：抖音链接解析

```
步骤1：upload_douyin_video(share_text="https://v.douyin.com/xxxxx")
       → 返回 detailId（如 "1819"）

步骤2：等待 3-5 分钟（解析中，完成后飞书通知；最多等待 15 分钟）

步骤3：short_video_detail(id="1819")
       → content 和 analysis 均有内容 = 解析完成
       → 仍有空值 = 继续等待后重试（每轮间隔 1-2 分钟，超过 15 分钟判定超时）
```

**`share_text` 支持的格式：**
- 网页地址：`https://www.douyin.com/video/xxxxx`
- 分享短链：`https://v.douyin.com/xxxxx`
- APP 分享全文（自动从中识别链接）

### 场景二：本地视频文件解析

```
步骤1：upload_other_video(title="视频标题", file_path="C:/Videos/demo.mp4")
       → 返回 detailId

步骤2：等待 3-5 分钟（最多等待 15 分钟）

步骤3：short_video_detail(id="{detailId}")
       → 查询解析结果（每轮间隔 1-2 分钟，超过 15 分钟判定超时）
```

> 注意：`upload_other_video` 的 `file_path` 必须是本地视频文件的绝对路径，不要传抖音链接。

---

## 3) short_video_detail 返回说明

| 字段 | 说明 |
|------|------|
| `content` | **视频脚本**（解析完成后填充，可直接用于创作流程参考） |
| `analysis` | **视频拆解**（结构化分析：钩子/节奏/情绪/选题等） |
| `title` | 视频标题 |
| `track` | 赛道分类 |
| `authorName` | 作者名称 |
| `likeNum` | 点赞数 |
| `commentNum` | 评论数 |
| `shareNum` | 分享数 |
| `favoriteNum` | 收藏数 |
| `watchNum` | 播放量 |

**完成判断**：`content` 和 `analysis` 均有内容时视为解析完成；任一为空表示仍在解析中。

---

## 4) 与创作流程的集成

解析结果直接作为步骤3（对标视频拆解）的输入：

| 解析字段 | 对应创作流程用途 |
|---------|----------------|
| `content` | 对标视频脚本原文 |
| `analysis` | 视频结构化拆解（钩子/节奏/情绪等） |
| `track` | 赛道归类参考 |
| `watchNum` / `likeNum` | 爆款数据判定 |
| `authorName` | 对标账号信息 |
| `title` | 选题方向参考 |

---

## 5) 降级策略

降级触发条件与处理方式见 `MCP_工具调用规范.md` 5 降级策略。视频解析不可用时，步骤3改为用户手动提供视频信息或跳过，核心创作流程不受影响。