# WayShot Studio（视频工作台）· 给 AI 助手的接入说明

> 网站：https://video.xiaomingai.net 。网页要登录；这份说明公开。你（AI 助手）要通过 MCP 工具来操作，不要去爬网页、也不要试着登录网页。

## 这是什么

WayShot Studio 做两件事：
- **视频创作（做同款）**：用户给一条爆款视频 + 自己拍的几段素材，AI 学会爆款的剪法、调色、质感、特效，用用户自己的画面出一条同款（不换脸、不生成画面）。也可以用模板库里别人做好的模板。
- **投放视频模板（录屏换图）**：把一条 App 录屏做成模板，把里面的照片、视频、文字换成别人的素材，批量出投放视频。

计算都在用户自己的 Mac 上（"本机助手"），AI 部分用用户本机登录的 Claude Code。

## 怎么接入（按顺序检查，做过的跳过）

1. **需要**：Apple 芯片的 Mac；装好并登录了 Claude Code；用户有这个网站的账号（没有就找管理员开）。
2. **看看是否已经接好**：运行 `claude mcp list`，里面有 `videoagent` 就已经接好了，直接跳到"怎么用"。
3. **没装本机助手**：在用户的终端运行
   `/bin/bash -c "$(curl -fsSL https://video.xiaomingai.net/helper/install.sh)"`
   约 3 分钟，最后会打开浏览器的授权页——**这一步必须用户本人点"授权"**（网页要先登录）。装好后助手常驻后台，并自动执行第 4 步。
4. **装了助手但 `videoagent` 不在列表里**：
   `claude mcp add --scope user videoagent -- ~/VideoAgentHelper/.venv/bin/python ~/VideoAgentHelper/agent_mcp.py`
5. 接好以后要**开一个新的 Claude Code 会话**，工具才会出现。工具连的是本机工作台 http://127.0.0.1:5199；助手没开时，工具会自动把它拉起来。

## 怎么用

**视频创作（常用）**
- 用户给了爆款和素材：`video_create_from_viral(viral_video=爆款路径, materials=[素材文件或文件夹], wait=900)`，约 6~10 分钟。
- 用现成模板：`video_list_templates` 挑一个 → `video_make_same(template=…, materials=[…], wait=300)`，约 1~2 分钟。
- 看结果：`video_status` 看状态和"缺什么素材"，`video_view` 看参考片和成片对比图。
- 不满意：`video_comment` 写在对应秒数（可以写好几条）→ `video_regenerate(wait=…)`。
- 满意：`video_download` 存到本地（默认"下载"文件夹）。
- 整理素材库：`materials_list` 看有什么 → `materials_view` 看缩略图 → `materials_organize` 建文件夹、归类（先跟用户说怎么分）。

做事原则：素材每段最多用一次，不够就出短一点，不硬凑；镜头好不好按参考片的风格判断（参考片本身糊、晃，就是它要的感觉）。路径都是用户这台 Mac 上的本地路径。

**投放视频模板**：`create_template` → `status(wait)` 等拆完 → `view` / `edit_segment` 检查 → `upload_materials` → `run(wait)` 出第一条 → 以后 `new_output` 批量出片。

## 全部工具

### 视频创作和素材库
- `video_list_templates`：视频创作：模板库（我的、团队的、所有人发布的爆款模板），拿 template id 做同款。fits 是这个模板适合的素材（时间、场景、氛围），按用户素材挑模板时看它
  参数：无
- `video_list_works`：视频创作：我的作品列表（状态、时长、待处理意见）
  参数：无
- `video_create_from_viral`：视频创作：给一条爆款视频（本地路径）+ 我拍的几段素材（文件或文件夹），直接出一条同款。AI 先拆爆款、照着做模板（顺手存成我的模板），再用素材出片，约 6~10 分钟。素材每段最多用一次，不够就出短一点，不硬凑。wait>0 等做完再返回
  参数：viral_video（必填），materials（必填），name，wait，open_browser
- `video_make_same`：视频创作·做同款：用模板库里的模板（template id）+ 我的素材（本地视频路径或文件夹；也可以给素材库 id）出一条，约 1~2 分钟。seconds 不填 = 推荐时长（按素材多少定，不硬凑）。wait>0 等做完再返回
  参数：template（必填），materials，material_ids，seconds，wait，open_browser
- `video_status`：视频创作：看一条作品现在怎么样（做好没、多长、缺什么素材、意见和 AI 的回复）。wait>0 时等它做完再返回
  参数：template（必填），work（必填），wait
- `video_view`：视频创作：看图——参考片和成片同一时刻的帧上下拼在一起。seconds 给几个秒数只看那几刻，不给就每个镜头一张
  参数：template（必填），work（必填），seconds
- `video_comment`：视频创作：在成片某一段写意见（哪里不对、想怎么改），可以写好几条，写完用 video_regenerate。模板是自己的，AI 可能直接改模板；别人的模板只改这一条
  参数：template（必填），work（必填），start_sec（必填），end_sec，text（必填）
- `video_regenerate`：视频创作：有待处理意见就按意见再生成，没有就按模板最新版重出。wait>0 等做完再返回
  参数：template（必填），work（必填），wait
- `video_download`：视频创作：把成片存到本地（默认存到「下载」文件夹）
  参数：template（必填），work（必填），save_to
- `video_publish`：视频创作：把我做的模板发布到发现页（先过机审），别人就能做同款
  参数：template（必填）
- `video_suggestions`：视频创作：我的模板收到的用户建议（别人做同款时提的、AI 判定是模板本身的问题，可能已经写好了新效果）
  参数：template（必填）
- `materials_list`：素材库：所有素材（id、名字、所在文件夹、视频还是照片、时长、尺寸；出过片的还有 looks_like：画面概况和 AI 选段时的描述）和文件夹列表。folder 给了只看这个文件夹（含子文件夹），"" 是未分类
  参数：folder
- `materials_view`：素材库：看素材的缩略图（一次最多 16 个 id），整理、挑素材前先看画面
  参数：ids（必填）
- `materials_organize`：素材库：整理。moves=[{ids:[素材id…], folder:"旅行/云南"}] 把素材移进文件夹（没有就自动建，"" = 未分类，最多 4 级）；create_folders 建空文件夹；rename_folders=[{from, to}] 改名。按时间（白天/黄昏/夜晚）、场景（室内/街景/风景…）、人物或事件分都行，和模板的"适合的素材"标签对得上最好用。整理前先和用户说一下打算怎么分
  参数：moves，create_folders，rename_folders
- `video_adopt`：视频创作：采纳一条用户建议，AI 把它融进模板（模板升版本）
  参数：template（必填），work（必填），comment（必填）

### 投放视频模板（录屏换图）
- `list_templates`：列出我能看到的录屏模板（个人空间 + 团队空间）
  参数：无
- `create_template`：用一条参考视频（本地路径）新建模板，自动开始 AI 拆解，并在浏览器里打开这个模板让人一起看
  参数：video_path（必填），name，open_browser
- `status`：看模板现在的状态：在哪一步、有哪些轴（before/after 分组）、拆出来的每一段、素材齐没齐、意见、成片，以及下一步该做什么。wait>0 时等它跑完（最多等这么多秒）再返回
  参数：id（必填），wait
- `view`：看图：what=segments 看拆解结果（每段一格，框出要换的照片）；what=result 看成片（原片和成片并排），可以用 from_sec/to_sec 只看一段、output 指定看哪条成片
  参数：id（必填），what，output，from_sec，to_sec，n
- `edit_segment`：改拆解的一段：action 换/不换，lane 改归到哪条轴（比如把认反的 before 改成 after2），start_sec/end_sec 调起止时间
  参数：id（必填），segment（必填），action，lane，start_sec，end_sec
- `upload_materials`：传这次真正要用的素材（本地照片/视频路径，也可以给文件夹）。不指定 lane 就自动分：before/after 按构图配对、分清原图和效果图；指定 lane 就只换那一条轴
  参数：id（必填），paths（必填），lane
- `swap_materials`：两条轴的素材对调（比如原图和效果图放反了：before2 和 after2 对调）
  参数：id（必填），lane_a（必填），lane_b（必填）
- `comment`：第②步 调整：在某一段写一条意见（哪里不对、想怎么改），写完用 run 让 AI 按意见改。范围用 start_frame/end_frame（帧号，含两头）或 start_sec/end_sec（秒）给，二选一
  参数：id（必填），start_frame，end_frame，start_sec，end_sec，text（必填）
- `run`：往下跑一步：拆解确认后 → 生成模板并用素材出片；有意见 → 按意见优化（成片跟着更新）；换了素材 → 按新素材重出。wait>0 时等跑完再返回
  参数：id（必填），wait
- `reanalyze`：拆解失败后重新拆解
  参数：id（必填）
- `new_output`：第④步：模板做好后，给另一批素材（另一个人的照片）再出一条成片，name 不填按时间起。批量：each_folder=true，paths 给好几个文件夹（每个文件夹是一个人的素材），每个文件夹出一条、名字=文件夹名
  参数：id（必填），paths（必填），name，each_folder
- `fill_output`：模板改结构加了照片位后，旧成片会缺新位置的素材（status 的 outputs 里标「缺 …」）：给它补一张 path 到 lane
  参数：id（必填），output（必填），lane（必填），path（必填）
- `rerender_output`：按模板最新版重出某一条成片（旧版的、补完素材的）
  参数：id（必填），output（必填）
- `download`：把成片存到本地（默认存到「下载」文件夹）。output 不填就是做模板时那条
  参数：id（必填），output，save_to
- `set_options`：第②步 调整里的选项：others 别人的照片（相册里其他人的）怎么处理：保持原样 / 隐私模糊；captions 压在照片上的字幕：自动避开脸 / 保持原位。status 里 options 是当前值
  参数：id（必填），others，captions
- `record`：看 AI 记录（页面「AI 记录」tab）：AI 对视频的理解和建议、工程师最近一次报告、版本历史、每一步用时和花费
  参数：id（必填）
- `open_in_browser`：在浏览器里打开模板页面，让人一起看（已经开着就不重复开）。一般不用调：操作模板时页面没开会自动打开
  参数：id

## 人在哪里看

工具会在用户的浏览器里打开对应页面，用户可以边看边改。页面地址：发现 http://127.0.0.1:5199/explore · 视频创作 /video · 投放视频模板 /ads · 我的 /me。