MagicCut

基于 Claude Code Skills 的视频素材自动化流水线。输入一段脚本文案，自动完成：

脚本拆分镜 → 关键词优化 → 素材搜索 → AI 评分筛选 → 下载 → 去字幕 → 镜头切分 → 片段匹配

全程在 Claude Code 终端中运行，通过 HTML 预览页可视化审查结果。支持通过 cc-connect 在 IM 平台（飞书/微信/Telegram）远程操作。

界面预览

流水线在 3 个人工确认点生成交互式审核页面，所有修改自动回流到流水线状态：

Step 1 · 分镜审核

AI 将脚本拆解为分镜场景（画面描述 / 旁白 / 情绪 / 时长 / 搜索关键词），支持编辑、拖拽排序、合并、关键词增删：

Step 4 · 素材评分筛选

AI 视觉模型对候选素材逐条评分并给出理由，支持封面预览、按评分/场景筛选、点击选择：

Step 8 · 片段匹配确认

切分后的片段自动绑定到最佳场景，逐条预览匹配理由与置信度，人工确认后进入成片环节：

1. 环境准备

系统要求

Claude Code CLI
Python 3.8+
FFmpeg（镜头切分需要）
Node.js 18+（仅 cc-connect 需要）

安装依赖

git clone https://github.com/agentone666-ship-it/MagicCut.git
cd MagicCut
pip install -r requirements.txt

配置 API Key

通过环境变量设置：

export TIKHUB_API_KEY="你的 TikHub API Key"        # 必需：素材搜索+下载
export GHOSTCUT_APP_KEY="你的 GhostCut App Key"     # 可选：去字幕
export GHOSTCUT_APP_SECRET="你的 GhostCut Secret"   # 可选：去字幕

2. 快速开始

一句话跑完整流程

在 Claude Code 终端中：

/pipeline-run "在美丽的海边，阳光洒在金色的沙滩上..." --project sunset

系统会自动执行 8 步流程，在 3 个确认点暂停等你审核。

只跑部分步骤

# 只搜素材
/pipeline-run --project sunset --skills "material-search" --inputs '{"keywords":["海边日落"]}'

# 搜完下载再去字幕
/pipeline-run --project sunset --skills "material-search,download-videos,remove-subtitle"

3. 完整流程详解

[1] 脚本拆分镜     ──确认──→  用户审核场景划分
[2] 关键词优化     ──自动──→  自动执行
[3] 素材搜索       ──自动──→  自动执行（调 TikHub）
[4] 素材评分筛选   ──确认──→  用户选择要下载的素材
[5] 下载视频    ┐
[6] 去字幕      ├─ 自动批量   自动执行
[7] 镜头切分    ┘
[8] 片段匹配       ──确认──→  用户确认绑定关系

Step 1：脚本拆分镜

AI 将脚本文案拆解为分镜场景列表，包含画面描述、旁白、情绪、时长、搜索关键词。

系统：已拆解为 8 个场景，总时长 42s
     👉 查看详情：http://localhost:8899/step-01-review.html
     请确认场景划分，或告诉我修改意见

用户打开 HTML 预览页审核，可以：

编辑画面描述、旁白、时长
拖拽调整场景顺序
合并/删除场景
增删搜索关键词

确认后回复 "continue"。

Step 2-3：关键词优化 + 素材搜索

自动执行，不暂停。优化搜索关键词后调用 TikHub API 搜索素材。

⏳ 正在优化搜索关键词...
✅ 关键词优化完成，15 个中文词 + 10 个英文词
⏳ 正在搜索素材（小红书 + TikTok）...
✅ 搜索完成，45 条候选素材

Step 4：素材评分筛选

AI（Mimo-V2-Omni）对候选素材评分，暂停等用户选择。

系统：45 条素材已评分，20 条超过 60 分
     👉 查看详情：http://localhost:8899/step-04-review.html
     在页面上点击选择要下载的素材，选好后回复"continue"

用户在 HTML 页面上：

查看封面 + 播放预览
按评分/点赞排序
点击卡片选择素材
筛选最低评分

Step 5-7：下载 + 去字幕 + 镜头切分

自动批量执行，不暂停。

⏳ 正在下载 5 个视频...
✅ 下载完成（5/5）
⏳ 正在去字幕...
✅ 去字幕完成（4 成功，1 跳过）
⏳ 正在切分镜头...
✅ 切分完成，共 23 个片段

Step 8：片段匹配

AI 将切分后的片段匹配到最佳场景，暂停等用户确认。

系统：23 个片段已匹配到 8 个场景
     👉 查看详情：http://localhost:8899/step-08-review.html
     确认绑定关系，或调整后回复"continue"

4. 自定义编排

不局限于固定 8 步，可以任意组合 skill：

# 只搜索不下载
/pipeline-run --project test --skills "material-search" --inputs '{"keywords":["工厂生产线"]}'

# 已有视频，只需要去字幕+切分
/pipeline-run --project test --skills "remove-subtitle,shot-segmentation"

# 完整流程但跳过去字幕
/pipeline-run --project test --skills "script-to-scenes,scenes-to-keywords,material-search,material-filter,download-videos,shot-segmentation,segment-match"

操作命令

/pipeline-run "脚本文本" --project <name>               # 新建项目，跑完整流程
/pipeline-run --project <name> --continue                # 继续执行（确认后）
/pipeline-run --project <name> --rerun-step 4            # 重跑第 4 步
/pipeline-run --project <name> --rollback-to 1           # 回退到第 1 步
/pipeline-run --project <name> --skills "a,b,c"          # 自定义 skill 列表
/pipeline-run --project <name> --skills "a" --inputs '{}'  # 带初始输入

5. IM 远程操作（cc-connect）

通过 cc-connect 在飞书/微信/Telegram 中操作 MagicCut：

安装 cc-connect

npm install -g cc-connect

使用

在 IM 中自然语言对话：

你：帮我搜海边日落的素材

MagicCut：✅ 素材搜索完成，45 条候选素材
         👉 查看结果：http://localhost:8899/step-03-review.html

你：选好了，下载前5个然后去字幕

MagicCut：⏳ 正在下载...
         ✅ 下载完成（5/5）
         ⏳ 正在去字幕...
         ✅ 去字幕完成
         👉 查看结果：http://localhost:8899/step-06-review.html

你：优化 skill

MagicCut：分析你的操作记录...
         问题：你跳过了评分低于 70 的素材，是因为画面质量还是内容不匹配？

6. HTML 预览页

每个确认门控生成交互式 HTML 预览页，通过本地 HTTP 服务访问。

页面	路径	功能
分镜审核	`step-01-review.html`	编辑场景、拖拽排序、合并、改关键词
素材选择	`step-04-review.html`	封面预览、视频播放、点击选择、评分筛选
片段匹配	`step-08-review.html`	预览片段、确认绑定、调整匹配

预览页在确认门控暂停时自动启动本地服务（默认 http://localhost:8899）。

7. 三层反馈

在 HTML 预览页中操作时，系统自动收集反馈信号：

第一层：动作反馈（自动）

用户编辑时自动记录结构化 diff：

{
  "actions": [
    {"type": "merge", "target": "scenes", "detail": {"merged": [3,4], "into": 3}},
    {"type": "edit", "target": "scenes[2].visual_description", "before": "...", "after": "..."}
  ]
}

第二层：意图批注（可选）

每个改动旁有 💬 按钮，点击写原因：

{
  "annotations": [
    {"action_index": 0, "text": "同一地点的连续镜头不应该拆开"}
  ]
}

第三层：龙虾追问（主动触发）

回到 CLI 说 "优化 skill"，龙虾分析 diff + 批注后追问：

龙虾：你把场景 3 和 4 合并了，批注说"同一地点不拆开"。
     问题：同一地点怎么定义？室内不同房间算同一地点吗？

你：同一个大空间算同一地点，不同房间算不同地点。

龙虾：明白。已提取规则："同一室内大空间的连续镜头合并为一个场景，不同房间视为不同场景。"

反馈数据保存在 project-{name}/step-{N}-feedback.json。

8. Skill 说明

Skill	类型	推荐模型	说明
`script-to-scenes`	LLM	Claude Opus 4.6	脚本拆解为分镜场景
`scenes-to-keywords`	LLM	Claude Opus 4.6	场景生成搜索关键词（中英文）
`material-search`	工具	—	调用 TikHub API 搜索素材
`material-filter`	LLM+Vision	Mimo-V2-Omni	素材评分筛选
`download-videos`	工具	—	下载无水印视频
`remove-subtitle`	工具	—	调用 GhostCut 去字幕
`shot-segmentation`	工具	—	FFmpeg 场景检测 + 切分
`segment-match`	LLM+Vision	Mimo-V2-Omni	片段匹配到场景

独立运行 Skill

每个工具类 skill 可脱离 pipeline 独立运行：

# 素材搜索
python3 .claude/skills/material-search/search.py \
  --keywords '["海边日落","sunset beach"]' \
  --platform xiaohongshu \
  --max-results 10

# 下载视频
python3 .claude/skills/download-videos/download.py \
  --videos '[{"id":"note_xxx","platform":"xiaohongshu"}]' \
  --output-dir ./downloads

# 去字幕
python3 .claude/skills/remove-subtitle/remove_subtitle.py \
  --urls '["https://xxx.mp4"]'

# 镜头切分
python3 .claude/skills/shot-segmentation/segment.py \
  --videos '["./video.mp4"]' \
  --threshold 0.5

9. 项目结构

MagicCut/
├── .claude/
│   ├── CLAUDE.md                          # 项目规范
│   └── skills/
│       ├── pipeline-run/                  # 编排器
│       │   ├── SKILL.md                   # 编排逻辑（状态管理+确认门控）
│       │   └── templates/                 # HTML 预览页模板
│       │       ├── step-01-review.html    # 分镜审核（可编辑）
│       │       ├── step-04-review.html    # 素材选择（可点选）
│       │       └── step-08-review.html    # 片段匹配（可调整）
│       ├── script-to-scenes/SKILL.md      # LLM: 脚本 → 分镜
│       ├── scenes-to-keywords/SKILL.md    # LLM: 场景 → 关键词
│       ├── material-search/               # 工具: 素材搜索
│       │   ├── SKILL.md
│       │   └── search.py
│       ├── material-filter/SKILL.md       # LLM+Vision: 评分筛选
│       ├── download-videos/               # 工具: 下载
│       │   ├── SKILL.md
│       │   └── download.py
│       ├── remove-subtitle/               # 工具: 去字幕
│       │   ├── SKILL.md
│       │   └── remove_subtitle.py
│       ├── shot-segmentation/             # 工具: 镜头切分
│       │   ├── SKILL.md
│       │   └── segment.py
│       ├── segment-match/SKILL.md         # LLM+Vision: 片段匹配
│       └── ffmpeg-video-editor/SKILL.md   # 参考: FFmpeg 命令
├── project-{name}/                        # 项目数据目录
│   ├── pipeline-state.json                # 流水线状态
│   ├── step-01-scenes.json                # 分镜结果
│   ├── step-01-review.html                # 分镜预览页
│   ├── step-01-feedback.json              # 反馈数据
│   ├── step-02-keywords.json              # 关键词
│   ├── step-03-candidates.json            # 搜索候选
│   ├── step-04-scored.json                # 评分结果
│   ├── step-05-downloaded.json            # 下载清单
│   ├── step-06-cleaned.json               # 去字幕结果
│   ├── step-07-segments.json              # 切分结果
│   ├── step-08-bindings.json              # 绑定关系
│   ├── downloads/                         # 原始视频
│   ├── cleaned/                           # 去字幕视频
│   ├── segments/                          # 切分片段
│   └── history/                           # 回退历史
└── requirements.txt

10. 常见问题

Q: 搜不到素材？

检查 TIKHUB_API_KEY 环境变量
关键词太泛会搜到不相关的，太窄搜不到。AI 会自动优化关键词（Step 2）

Q: 去字幕失败？

检查 GHOSTCUT_APP_KEY 和 GHOSTCUT_APP_SECRET
本地文件需要先上传到公开 URL，目前 --paths 模式需要配置 PDS

Q: HTML 预览页打不开？

确认本地 HTTP 服务已启动（pipeline-run 在确认门控时自动启动）
默认端口 8899，冲突时自动 +1
直接打开 HTML 文件会因为 fetch 跨域失败，必须通过 HTTP 服务

Q: 怎么回退？

/pipeline-run --project sunset --rollback-to 1

会把 step-1 之后的所有文件归档到 history/，从头重跑。

Q: 怎么只重跑某一步？

/pipeline-run --project sunset --rerun-step 4

只重跑 Step 4（素材评分），不影响其他步骤。

Q: 怎么在飞书里用？

安装 cc-connect，配置好后在飞书直接对话即可。

License

MIT

Name		Name	Last commit message	Last commit date
.claude		.claude
data		data
docs/screenshots		docs/screenshots
.gitattributes		.gitattributes
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
dashboard.html		dashboard.html
feedback-components.js		feedback-components.js
plan.md		plan.md
range_server.py		range_server.py
requirements.txt		requirements.txt
workflow-rules.md		workflow-rules.md

Latest commit

History

Folders and files

Repository files navigation