---
name: video-script-master
description: 视频剧本策略大师：通过4步工作流分析成功视频剧本并生成新的脚本和发布物料。支持完整流程分析、快速物料生成、批量处理等模式。专注于短视频内容创作，基于"好奇心缺口"理论生成高传播力的剧本和运营物料。
allowed-tools: [Read, Write, Edit, Bash, AskUserQuestion, Glob]
---

# 视频剧本策略大师 (Video Script Strategy Master)

## 概述

这是一个专业的短视频内容创作工具，通过逆向工程分析成功视频剧本，提取其结构模板，并基于该模板生成高质量、具有传播力的原创内容。

### 核心功能

1. **深度剧本分析**：多维度拆解视频剧本的结构、钩子机制、节奏感、语调和风格元素
2. **模板化提取**：将分析结果转化为标准化的4列CSV模板（模块、功能与目标、标准化手法、关键元素）
3. **智能选题构思**：基于模板联网搜索实时热点，生成3-4个真实、有深度的选题（附引用链接）
4. **全篇剧本生成**：使用 Thinking Mode 生成逻辑严密的纯口播剧本
5. **运营物料生成**：基于"好奇心缺口"理论生成4类发布物料（各3选1）
   - 视频发布文案（含话题标签）
   - 封面标题（数字悬念/冲突挑衅/剧情留白）
   - 置顶评论（≤20字 + 1个emoji）
   - 微信转发话术（肖东坡人设）

### 使用场景

- 单个视频创作（精细化分析和生成）
- 批量内容生产（规模化处理多个剧本）
- 竞品分析（提取爆款视频的成功模板）
- 快速物料生成（已有剧本，仅需运营物料）

---

## 先决条件

### Python 依赖安装

首次使用前需要安装 Python 依赖：

```bash
pip install google-generativeai
```

---

## 工作流程

### 启动时检查

每次启动时，我会执行以下检查：

#### 1. API Key 配置检查

检查 AI API Key 是否已配置（环境变量 `GEMINI_API_KEY` 或配置文件 `C:\Users\EDY\.video-script-master\config.json`）。

**如果未配置，启动交互式配置流程：**

##### 步骤1：选择 AI 服务供应商

使用 `AskUserQuestion` 询问：

```
问题："请选择您要使用的 AI 服务供应商"
header: "AI 服务配置"
options:
  - "Google Gemini（推荐）"
    description: "Google 官方 AI 模型，支持 Thinking Mode 和 Google Search 增强"
  - "OpenAI（即将支持）"
    description: "GPT-4 系列模型，强大的通用能力"
  - "Claude（即将支持）"
    description: "Anthropic Claude 系列，擅长长文本处理"
multiSelect: false
```

##### 步骤2：获取 API Key 指引

根据用户选择的供应商，提供对应的获取指引：

**Google Gemini**
```
📝 如何获取 Google Gemini API Key：

1. 访问：https://ai.google.dev/
2. 点击 "Get API Key" 按钮
3. 登录您的 Google 账号
4. 创建新的 API Key
5. 复制 API Key（格式如：AIza...）

💡 提示：
- 免费配额：每分钟 15 次请求
- 完整流程约需 5 次 API 调用
- 预计成本：$0.07/次（约 ¥0.5）
```

**OpenAI**（即将支持）
```
📝 如何获取 OpenAI API Key：

1. 访问：https://platform.openai.com/
2. 注册/登录账号
3. 进入 API Keys 页面
4. 创建新的 API Key
5. 复制 API Key（格式如：sk-...）
```

##### 步骤3：输入 API Key

使用 `AskUserQuestion` 收集 API Key：

```
问题："请输入您的 API Key"
header: "API Key 配置"
options:
  - "输入 API Key"
    description: "粘贴您从供应商处获取的 API Key"
  - "稍后配置"
    description: "我稍后再配置，先了解其他功能"
multiSelect: false
```

如果用户选择"输入 API Key"，再次使用 `AskUserQuestion` 收集：

```
问题："请粘贴您的 API Key"
header: "API Key"
（用户在文本框中输入）
```

##### 步骤4：保存配置

询问用户是否保存：

```
问题："是否将 API Key 保存到本地配置文件？"
header: "保存配置"
options:
  - "保存到配置文件（推荐）"
    description: "保存到 ~/.video-script-master/config.json，下次自动加载"
  - "仅本次使用"
    description: "仅在内存中保存，下次需要重新输入"
multiSelect: false
```

如果选择"保存到配置文件"，将 API Key 写入：
`C:\Users\EDY\.video-script-master\config.json`

格式：
```json
{
  "ai_provider": "google_gemini",
  "gemini_api_key": "AIza...",
  "created_at": "2026-01-29T17:30:00"
}
```

##### 步骤5：测试连接

保存后，测试 API 连接：

```bash
cd C:\Users\EDY\.config\claude\skills\video-script-master
python scripts\gemini_client.py
```

如果看到 `✅ Gemini Client 初始化成功`，说明配置成功。

如果失败，提示用户检查 API Key 是否正确，并询问是否重新配置。

#### 2. 未完成项目检查

检查是否有未完成的项目（从 `C:\Users\EDY\.video-script-master\projects\` 中查找 `metadata.json`）。

如果有未完成项目，询问是否继续或重新开始

### 模式选择

使用 `AskUserQuestion` 询问用户选择工作模式：

- **完整流程（4步分析）**：深度分析参考剧本，提取模板，生成新内容
- **快速生成物料**：基于现有剧本直接生成运营物料
- **批量处理**：批量分析或生成多个剧本

---

## 完整流程模式（推荐）

### 步骤1：摄取与深度分析

#### 1.1 收集参考剧本

使用 `AskUserQuestion` 收集参考剧本：

```
问题："请粘贴您想要分析的成功视频剧本"
header: "剧本输入"
options:
  - "粘贴剧本内容" (description: "输入完整的视频剧本文本")
```

#### 1.2 验证输入

检查剧本内容是否非空。如果为空，提示用户重新输入。

#### 1.3 创建项目目录

```bash
# 生成项目名称：{timestamp}_{topic_keyword}
# 示例：20260129_153045_科技产品评测

PROJECT_DIR="C:\Users\EDY\.video-script-master\projects\{project_name}"
mkdir -p "$PROJECT_DIR/inputs"
mkdir -p "$PROJECT_DIR/intermediate"
mkdir -p "$PROJECT_DIR/outputs"
```

#### 1.4 保存输入

将剧本保存到 `inputs\reference_script.txt`

#### 1.5 执行深度分析

```bash
cd C:\Users\EDY\.config\claude\skills\video-script-master
python scripts\analyze_script.py \
  --script "{用户输入的剧本}" \
  --output "{PROJECT_DIR}\intermediate\analysis.txt"
```

显示进度：
```
🔍 正在深度分析剧本...
├─ 使用模型：gemini-3-pro-preview
├─ 预计时间：30-60秒
└─ 分析维度：结构、钩子、节奏、语调、风格
```

#### 1.6 展示分析结果

读取 `intermediate\analysis.txt` 并展示前500字给用户预览。

#### 1.7 提取 CSV 模板

```bash
python scripts\extract_template.py \
  --analysis "{PROJECT_DIR}\intermediate\analysis.txt" \
  --output "{PROJECT_DIR}\intermediate\template.csv"
```

显示进度：
```
📋 正在提取CSV模板...
├─ 使用模型：gemini-3-flash-preview
└─ 预计时间：10-20秒
```

#### 1.8 更新元数据

创建/更新 `metadata.json`：
```json
{
  "project_name": "科技产品评测",
  "created_at": "2026-01-29T15:30:45",
  "updated_at": "2026-01-29T15:31:15",
  "status": "in_progress",
  "current_step": 2,
  "workflow_mode": "full",
  "parameters": {},
  "files": {
    "reference_script": "inputs\\reference_script.txt",
    "analysis": "intermediate\\analysis.txt",
    "template": "intermediate\\template.csv"
  }
}
```

---

### 步骤2：结构模板确认

#### 2.1 展示 CSV 模板

读取 `intermediate\template.csv` 并以表格形式展示。

示例格式：
```
【CSV 模板预览】

模块 | 功能与目标 | 标准化手法 | 关键元素
-----|-----------|-----------|----------
开场钩子 | 3秒内抓住注意力 | 反常识结论 + 具体数字 | "99%的人都不知道..."
核心内容 | 提供价值信息 | 递进式论证 | 数据支撑、案例
...
```

#### 2.2 询问是否编辑

使用 `AskUserQuestion`：

```
问题："CSV模板已生成，是否需要编辑？"
header: "模板确认"
options:
  - "直接使用（推荐）" (description: "使用AI生成的模板，无需修改")
  - "在编辑器中编辑" (description: "在记事本中打开CSV进行修改")
  - "粘贴修改后的内容" (description: "我已在其他地方编辑，直接粘贴")
multiSelect: false
```

#### 2.3 处理编辑选项

**选项A：直接使用**
- 将 `template.csv` 复制为 `confirmed_template.csv`

**选项B：在编辑器中编辑**
```bash
notepad "{PROJECT_DIR}\intermediate\template.csv"
```
等待用户编辑完成，询问："编辑完成了吗？"
然后将编辑后的文件复制为 `confirmed_template.csv`

**选项C：粘贴修改后的内容**
再次使用 `AskUserQuestion` 收集用户粘贴的CSV内容，保存为 `confirmed_template.csv`

#### 2.4 更新元数据

更新 `metadata.json` 的 `current_step` 为 3。

---

### 步骤3：选题构思

#### 3.1 收集参数

使用 `AskUserQuestion` 收集：

```
问题1："请设置目标字数"
header: "字数设置"
options:
  - "800字（推荐）"
  - "1000字"
  - "1200字"
  - "自定义字数"

问题2："是否有特定的选题方向？"
header: "选题方向"
options:
  - "无特定方向（AI自由构思）"
  - "输入选题方向"
```

如果用户选择"输入选题方向"，再次询问收集方向内容（如："科技数码"、"育儿心经"）。

#### 3.2 调用选题脚本

```bash
python scripts\ideate_topics.py \
  --template "{PROJECT_DIR}\intermediate\confirmed_template.csv" \
  --direction "{选题方向}" \
  --output "{PROJECT_DIR}\intermediate\topics.json"
```

显示进度：
```
💡 正在构思选题（联网搜索中）...
├─ 使用模型：gemini-3-pro-preview + Google Search
├─ 预计时间：60-90秒
└─ 提示：AI正在搜索实时热点和行业趋势
```

#### 3.3 读取并展示选题

读取 `topics.json`：
```json
[
  {
    "title": "5G时代的隐形杀手：你的手机正在吞噬你的睡眠质量",
    "explanation": "结合2025年最新研究，揭示5G手机辐射与睡眠质量的关系...",
    "citationLinks": [
      "https://example.com/research1",
      "https://example.com/research2"
    ]
  },
  ...
]
```

展示格式：
```
【AI 生成的选题】

选题1：5G时代的隐形杀手：你的手机正在吞噬你的睡眠质量
解析：结合2025年最新研究，揭示5G手机辐射与睡眠质量的关系...
参考来源：[Citation 1] [Citation 2]

选题2：...

选题3：...

【自定义选题区】
您也可以输入自己的选题标题。
```

#### 3.4 选择选题

使用 `AskUserQuestion`：

```
问题："请选择一个选题或输入自定义选题"
header: "选题选择"
options:
  - "{选题1标题}"
  - "{选题2标题}"
  - "{选题3标题}"
  - "输入自定义选题"
  - "重新生成选题（修改方向）"
multiSelect: false
```

**如果选择"输入自定义选题"**：
再次询问收集自定义选题内容。

**如果选择"重新生成选题"**：
询问新的选题方向，然后重新执行步骤 3.2-3.4。

#### 3.5 保存选定选题

将选定的选题保存到 `outputs\selected_topic.json`。

#### 3.6 更新元数据

更新 `metadata.json`：
- `current_step` = 4
- `parameters.target_word_count` = {目标字数}
- `parameters.topic_direction` = {选题方向}
- `user_selections.selected_topic_index` = {选择的索引}

---

### 步骤4：全篇生成

#### 4.1 生成剧本

```bash
python scripts\generate_script.py \
  --template "{PROJECT_DIR}\intermediate\confirmed_template.csv" \
  --topic "{选定的选题标题}" \
  --word-count {目标字数} \
  --output "{PROJECT_DIR}\outputs\final_script.txt"
```

显示进度：
```
✍️  正在生成全篇剧本...
├─ 使用模型：gemini-3-pro-preview (Thinking Mode)
├─ 预计时间：90-120秒
├─ 目标字数：800字
└─ 提示：AI正在深度思考（4000 tokens thinking budget）
```

#### 4.2 展示剧本

读取 `outputs\final_script.txt` 并展示给用户：

```
【生成的剧本】

{剧本内容}

---
字数统计：823字
```

#### 4.3 生成发布物料

```bash
python scripts\generate_assets.py \
  --script "{PROJECT_DIR}\outputs\final_script.txt" \
  --output "{PROJECT_DIR}\outputs\publication_assets.json"
```

显示进度：
```
📝 正在生成发布物料...
├─ 使用模型：gemini-3-flash-preview
└─ 预计时间：30-60秒
```

#### 4.4 展示物料

读取 `publication_assets.json` 并格式化展示：

```
【发布物料】

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📱 1. 发布文案 (3选1)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

选项1：
{文案1内容}
#话题1#话题2#话题3#话题4#话题5

选项2：
{文案2内容}
#话题1#话题2#话题3#话题4#话题5

选项3：
{文案3内容}
#话题1#话题2#话题3#话题4#话题5

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎯 2. 封面标题 (3选1)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

选项1（数字悬念型）：
{标题1}

选项2（冲突挑衅型）：
{标题2}

选项3（剧情留白型）：
{标题3}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
💬 3. 置顶评论 (3选1)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

选项1：
{评论1} 😊

选项2：
{评论2} 🔥

选项3：
{评论3} 💡

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📲 4. 微信转发话术
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

{微信话术内容}
```

#### 4.5 更新元数据

更新 `metadata.json`：
- `status` = "completed"
- `updated_at` = {当前时间}

#### 4.6 询问后续操作

使用 `AskUserQuestion`：

```
问题："项目已完成！接下来您想？"
header: "后续操作"
options:
  - "查看项目文件夹"
  - "开始新项目"
  - "退出"
multiSelect: false
```

---

## 快速物料生成模式

此模式适用于已有完整剧本，仅需生成运营物料的场景。

### 流程

#### 1. 收集现有剧本

使用 `AskUserQuestion` 收集剧本内容。

#### 2. 创建临时项目目录

```bash
PROJECT_DIR="C:\Users\EDY\.video-script-master\projects\quick_{timestamp}"
mkdir -p "$PROJECT_DIR/outputs"
```

#### 3. 直接生成物料

```bash
python scripts\generate_assets.py \
  --script "{临时保存的剧本文件}" \
  --output "{PROJECT_DIR}\outputs\publication_assets.json"
```

#### 4. 展示物料

按照"完整流程模式 - 步骤4.4"的格式展示物料。

---

## 批量处理模式

### 批量剧本分析

#### 1. 收集输入

询问用户：
- 选项A：提供包含多个剧本的目录路径
- 选项B：提供单个文件（每个剧本用分隔符 `---SEPARATOR---` 隔开）

#### 2. 批量执行

对每个剧本：
1. 创建独立项目目录
2. 执行步骤1-2（分析 + 提取CSV）
3. 保存结果

#### 3. 展示汇总

```
【批量分析完成】

成功：8个剧本
失败：2个剧本

详细结果：
✅ script_1 → C:\Users\EDY\.video-script-master\projects\batch_20260129_1\
✅ script_2 → C:\Users\EDY\.video-script-master\projects\batch_20260129_2\
...
❌ script_9 → 错误：API 配额超限
```

---

## 输出管理

### 项目目录结构

```
C:\Users\EDY\.video-script-master\projects\{project_name}\
├── metadata.json             # 项目元数据
├── inputs\
│   └── reference_script.txt  # 输入的参考剧本
├── intermediate\
│   ├── analysis.txt          # 分析结果
│   ├── template.csv          # 原始CSV模板
│   ├── confirmed_template.csv # 用户确认的CSV
│   └── topics.json           # 生成的选题列表
└── outputs\
    ├── selected_topic.json   # 选定的选题
    ├── final_script.txt      # 最终剧本
    └── publication_assets.json # 发布物料
```

### 文件命名规范

- 项目名称：`{YYYYMMDD_HHMMSS}_{topic_keyword}`
- 示例：`20260129_153045_科技产品评测`

---

## 错误处理

### API Key 未配置

**错误信息**：
```
❌ GEMINI_API_KEY not found.
```

**解决方案**：
1. 访问 https://ai.google.dev/ 获取 API Key
2. 设置环境变量或保存到配置文件
3. 重新运行

### 配额超限

**错误信息**：
```
⏸️  配额限制，等待 60 秒后重试...
```

**处理**：
- 自动重试（最多3次，指数退避）
- 如果持续失败，询问用户是否保存进度并稍后继续

### 网络错误

**错误信息**：
```
🔄 网络错误，重试 1/3...
```

**处理**：
- 自动重试3次
- 失败后提示用户检查网络连接

### JSON 解析失败（选题生成）

**处理**：
- 返回占位选题："生成失败，请重试"
- 提示用户重新生成选题

---

## 高级功能

### 模板库管理

保存常用的 CSV 模板到 `C:\Users\EDY\.video-script-master\templates\`，按类型分类（情感类、知识类、娱乐类等）。

### 选题历史去重

记录生成的所有选题到 `C:\Users\EDY\.video-script-master\topics_history.json`，在新生成时附加"避免与以下选题重复"。

---

## 使用提示

1. **首次使用**：建议选择"完整流程"模式，完整体验4步工作流
2. **CSV编辑**：如果AI生成的模板不够精细，可以手动调整
3. **选题方向**：越具体效果越好（如"2025年最新AI技术"比"科技"更精准）
4. **字数控制**：实际生成字数可能在目标±50字范围内
5. **物料使用**：每类物料提供3个选项，选择最符合平台风格的使用

---

## 成本估算

使用 Gemini API 的预估成本（完整流程）：

- 步骤1（分析）：~2500 tokens → $0.01
- 步骤2（提取）：~1200 tokens → $0.005
- 步骤3（选题）：~3000 tokens → $0.015
- 步骤4（剧本）：~5800 tokens → $0.029
- 步骤4（物料）：~2300 tokens → $0.012

**总计**：约 $0.07/次（约 ¥0.5）

---

## 技术栈

- **AI 模型**：Google Gemini (gemini-3-pro-preview / gemini-3-flash-preview)
- **特性**：Thinking Mode (4000 tokens), Google Search, JSON Schema
- **语言**：Python 3.8+
- **依赖**：google-generativeai

---

## 故障排查

**问题1：脚本找不到 gemini_client**
```bash
# 确保在正确目录执行
cd C:\Users\EDY\.config\claude\skills\video-script-master
```

**问题2：CSV格式错误**
- 检查是否包含表头
- 确保每行4列（用逗号分隔）
- 参考 `examples\example_csv_template.csv`

**问题3：生成内容不符合预期**
- 调整选题方向使其更具体
- 检查CSV模板质量
- 重新生成

---

## 版本信息

- **版本**：v1.0.0
- **更新日期**：2026-01-29
- **作者**：基于原项目 Video Script Reverse-Engineering Pro 改编

---

**祝您创作顺利！🎬**