# 任务：在这台电脑上安装并激活「广告视频复刻 MCP」

你在替一位**非技术的用户**做安装。请**一步一步来**：每步做完先验证再往下，
需要用户提供信息时**停下来问清楚**，其余全部由你自己完成 —— 不要让用户去敲命令、
不要让他手动找文件、不要让他复制机器码发来发去。

## 这套软件是什么

丢一条同行的爆款广告片进去 → 自动把片子**拆成结构** → 换成用户自己的品牌和台词重写脚本
→ **批量产出同款新片**。全程在这台电脑上跑，素材不出本机。

⚠️ **安装包不含任何素材**（数据目录是空的，这是有意为之）：用户装完是**一个干净的空工作台**，
素材要他**自己上传**。所以第 8 步会用他的一条素材跑通第一次。

> **不要把"库里没有素材"当故障** —— 空库是正常状态，不是装坏了。
> 安装包只有 ~0.4 MB，正是因为它不带素材；下载几乎瞬间完成。

## 交付标准（这 7 条全达成才算装完）

| # | 状态 | 怎么确认 |
|---|---|---|
| 1 | 程序就位、依赖装好 | `.venv\Scripts\python.exe --version` 有输出 |
| 2 | 两个模型 KEY 已填 | `.env` 里 `MINIMAX_API_KEY` / `ARK_API_KEY` 非空 |
| 3 | 离线自检全绿 | `offline_e2e` 无 FAIL |
| 4 | 工作台能打开、页面正常 | 浏览器里五个页签都点开过 |
| 5 | 已接入 WorkBuddy 并生效 | 能调出 `system_status` 工具 |
| 6 | **已激活授权** | 授权状态显示「授权·云端」，剩余天数 > 0 |
| 7 | 能真的出片 | 上传一条素材 → 跑一次混剪（¥0）→ **产物能播** |

## 步骤

### 第 0 步 · 先问清三件事（**不要跳过**）

在做任何下载之前，先问用户：

1. **装到哪个目录？** 建议 `D:\video-mcp`（要英文、无空格；别装到桌面或含中文的路径）。
2. **两个模型 KEY 有没有？** 这是用户**自己的账号**，必须他本人去申请（见下方链接）。
   - MiniMax（写脚本 / 生成视频）：<https://platform.minimaxi.com>
   - 火山方舟（拆解素材 / 生成定妆图）：<https://console.volcengine.com/ark/region:ark+cn-beijing/apikey>
   如果他还没有 → 把这两个链接给他，**等他办好再继续**；不要替他注册、不要用别处的 KEY。
3. **用户/公司叫什么**（第 7 步激活要用，写正式名称即可）。

> KEY 的费用由用户直接付给模型厂商，与我们无关。参考价：纯用库里已有片段拼片 **≈ 0 元**；
> AI 生成新镜头约 **0.5 元/秒**（20 秒片约 10 元）。建议先跑免费的混剪。

### 第 1 步 · 下载安装包

```powershell
$dst = "$env:USERPROFILE\Downloads\dvmcp.zip"
curl.exe -L --retry 3 -o $dst "https://aivideo.qiyuanagent.com/download/latest"
Get-Item $dst | Select-Object Length, FullName
```

- `/download/latest` **永远指向最新包**，不用关心包名。
- **包很小（约 0.4 MB）** —— 里面只有程序和文档，**不含素材**，所以是秒下。
  （素材由用户自己上传，见第 8 步。）
- 若下载失败：检查网络后重试一次；仍失败就把报错原文告诉用户。

### 第 2 步 · 解压

```powershell
$dir = "D:\video-mcp"          # ← 换成第 0 步用户选的目录
New-Item -ItemType Directory -Force -Path $dir | Out-Null
Expand-Archive -Path $dst -DestinationPath $dir -Force
Get-ChildItem $dir | Select-Object Name     # 应看到 install.ps1 / video_mcp / rules 等
```

### 第 3 步 · 跑安装脚本

```powershell
Set-Location $dir
powershell -ExecutionPolicy Bypass -File .\install.ps1
```

脚本会：建 `.venv` → 升级 pip → 装依赖（带三级镜像回退）→ 检查 ffmpeg → 生成 `.env` → 跑离线自检。

- **若提示缺 Python**：装 Python 3.10+（安装时**务必勾选 Add python.exe to PATH**），重跑本步。
- **若提示缺 ffmpeg**：`winget install Gyan.FFmpeg`，重跑本步。
- 首次约 3–10 分钟。

### 第 4 步 · 写入用户的两个 KEY（**用户提供**）

打开 `$dir\.env`，把第 0 步拿到的两个 KEY 填进去并保存：

```
MINIMAX_API_KEY=用户给你的 MiniMax 密钥
ARK_API_KEY=用户给你的火山方舟密钥
```

> 这两个 KEY **只写在本机 `.env`**，不上传任何服务器。填完不要贴到聊天里回显。

### 第 5 步 · 离线自检（不花钱、不联网，**必须全绿**）

```powershell
.venv\Scripts\python.exe -m video_mcp.tests.offline_e2e
```

它验证代码链路与依赖是否完整。**要求无 FAIL**；有 FAIL 先修再往下走
（把完整输出贴给用户，别含糊过去）。

### 第 6 步 · 接入 WorkBuddy（让 AI 能直接调工具）

在 `~/.workbuddy/mcp.json` 的 `mcpServers` 里增加（把路径换成实际安装目录）：

```json
"doubao-video": {
  "command": "D:\video-mcp\\.venv\\Scripts\\python.exe",
  "args": ["-m", "video_mcp.mcp_server"],
  "cwd": "D:\video-mcp"
}
```

然后**提醒用户去连接器页面点「信任」** —— 不点不会生效。之后重启对话或重连即可。

### 第 7 步 · 激活授权（**不用找服务商，自己就能拿到**）

授权接入后，直接调用工具：

```
system_activate(name="<第0步问到的公司/用户名称>", contact="<联系方式，可留空>")
```

它会把本机机器码发给我们的授权服务，**当场签发一份 7 天试用授权并自动装好**，
返回里会带上到期日。然后调 `system_machine_code()` 复核：应显示
`已注册=True`、`状态=授权·云端`、`剩余天数>0`。

| 返回/状态 | 含义与处置 |
|---|---|
| `ok=true`，`trial=true` | ✅ 试用已激活，全部功能可用（到期前会提示续费） |
| `ok=false, reason=unknown_key/suspended` | 账户异常 → **告诉用户联系服务商** |
| 连不上服务端（超时） | 检查网络后重试一次；仍失败 → 把报错原文告诉用户，**不要伪造成功** |

> 试用到期后功能会受限（**看素材库 / 预览 / 导出已有成片仍然可用**，只是不能出新片）。
> 续费、加台数、换机都由服务商在后台操作，用户无需重装。

### 第 8 步 · 用他的一条素材跑通第一次（**别只看代码，要真出片**）

**先问用户要一条素材视频** —— 最好是**一条同行的爆款广告片**（mp4，10–60 秒）；
没有的话，他自己拍的任何一条短视频也行。

1. 启动工作台：
   ```powershell
   .venv\Scripts\python.exe -m video_mcp.console.app
   ```
   浏览器打开 <http://127.0.0.1:8680>，确认五个页签都能打开、无报错：
   `项目` / `我的素材` / `AI 片段库` / `资料库` / `模型配置`；
2. 把那条素材**传进「我的素材」**，等它解析完（会自动拆句 + 分类；这一步用到语音识别，需联网）；
3. 跑一次**纯混剪**（不调用生成模型，**¥0**）—— 按这个顺序调工具：

   | 工具 | 作用 |
   |---|---|
   | `project_create(name="第一次混剪", mode="create", client="<客户 key>")` | 建项目，拿到 `project_id` |
   | `library_mix_plan(project_id=..., sources="user")` | 先看选片方案（选了哪几条、总时长、有没有告警） |
   | `media_mix_from_plan(project_id=..., sources="user")` | 出片（返回 `task_id`，**异步**） |
   | `task_status(task_id=...)` | 轮询到 `status=done`；成片路径在返回的 `task.artifacts` / `task.result` 里 |

4. **产物文件存在、能播放**才算过 —— 用 ffprobe 核一下时长，别只看接口返回值。

> 素材攒起来之后，随时可以跑 `素材库自检.py`，确认索引里的素材在这台机器上都找得到
> （换电脑 / 换目录后尤其要看）。

### 第 9 步 · 汇报

给用户一份简报，含**真实命令输出**（不要只说"已完成"）：

- 装在哪个目录、Python/ffmpeg 版本；
- 素材库自检结果的**实际数字**（坏链几条、健康度）；
- 两个 KEY 是否就位（**只说"已填写"，不要回显密钥内容**）；
- 授权状态（试用/剩余天数/到期日）；
- 混剪产物路径 + 时长；
- 有没有报错、还有什么没做。

## 硬性约束（务必遵守）

1. **只用项目自带的 Python**：`.venv\Scripts\python.exe`。
   用系统 Python 会导致**音频转写静默失败**（表现为"所有片段都没台词"），极难排查。
2. **不要删除任何文件**，也不要动 `clients\` / `libraries\` 里的数据。
   本环境对**批量删除**有安全守卫（一次 50 个文件会中断）；需要清理时用**移动到 `_trash`**，不要批量删。
3. 密钥只写进 `.env`；不要改 `.env.example`；**不要把密钥回显到聊天里**。
4. 工作台**只监听 127.0.0.1**，不要绑 `0.0.0.0`。
5. **不要为了"跑通"而伪造结果** —— 每步都要有真实输出作证据；做不到就明说"这步失败 + 原因"。
6. 被系统沙箱拦住网络/写文件时，**告诉用户点"允许"**，不要绕过。
7. 遇到包内文档（`交付说明.md` / `操作手册.md`）与本文冲突，**以本文为准**（本文是最新的）。

## 遇到问题时

- 卡在某一环 → 先读包内的 `交付说明.md`（系统逻辑）与 `操作手册.md`（命令与故障表）；
- 仍解决不了 → 把**完整报错原文**和已做步骤告诉用户，让他联系服务商，**不要自己乱改数据**。