giggle-official/ai-director

AI Director - AI短剧生成全流程

完整的AI短剧生成解决方案，从创意到成片，集成X2C平台账号管理和计费。

---

👥 多用户支持

本Skill支持多用户共享设备，每个用户拥有独立的X2C账号和配置。

用户凭证存储位置: credentials/{USER_ID}.json

调用脚本时需设置 USER_ID 或 TELEGRAM_USER_ID 环境变量：

USER_ID=5470522468 node scripts/ad-account-manager.js check-binding

OpenClaw从聊天调用时会自动传递用户ID。

---

🎯 模块概览

1. Ad Account Manager（账号管理）

• 功能: X2C平台账号绑定、验证
• 脚本: scripts/ad-account-manager.js
• 独立使用: ✅ 可以单独调用

2. Ad Writer（编剧）

• 功能: 从创意点子生成完整短剧脚本
• 类型: 提示词工程（Agent 读取指南后生成）
• 文档: references/AD-WRITER-GUIDE.md
• 依赖: ⚠️ 需要先绑定X2C账号

3. Ad Producer（视频生产）

• 功能: 从剧本生成完整视频
• 脚本: scripts/ad-producer.js
• 依赖: ⚠️ 需要先绑定X2C账号

---

🚀 快速开始

第一步：获取X2C API Key

用户必须自行完成以下步骤：

1. 打开 https://www.x2creel.ai 注册/登录账号
2. 进入个人中心 → API管理 → 创建/复制 API Key
3. 将 API Key 发送给我

示例对话：

用户：我想生成视频
助手：好的，需要先绑定X2C账号。请打开 https://www.x2creel.ai 登录，然后在个人中心获取API Key发给我。
用户：x2c_sk_xxx...
助手：验证通过！你的账号已绑定，现在可以开始生成视频了～

第二步：验证API Key（Agent自动执行）

Agent 收到 API Key 后，调用 ad-account-manager.js verify-key 验证有效性：

node scripts/ad-account-manager.js verify-key x2c_sk_xxx

验证成功后将 key 保存到 credentials/{USER_ID}.json

第三步：查看配置和定价

node scripts/ad-producer.js config

第四步：生成短剧

选项A - 仅编剧（Agent模式）： Agent 读取 references/AD-WRITER-GUIDE.md，根据用户创意生成剧本。

选项B - 全流程（剧本 + 视频）：

node scripts/ad-producer.js full-workflow "一个程序员穿越到古代当宰相" --duration 120 --wait

---

⚠️ 重要规则

在用户提供有效的 X2C API Key 之前，禁止执行任何视频生成或剧本生成操作！

如果用户要求生成视频但尚未绑定账号：

1. 引导用户访问 https://www.x2creel.ai
2. 告知获取API Key的步骤
3. 收到有效Key后才可进入制作流程

---

📦 Ad Account Manager（账号管理）

命令列表

# 发送验证码
node scripts/ad-account-manager.js send-code [email protected]

# 验证并获取 API Key
node scripts/ad-account-manager.js verify [email protected] 123456

# 检查绑定状态
node scripts/ad-account-manager.js check-binding

# 查看配置选项
node scripts/ad-account-manager.js config

# 解绑账号
node scripts/ad-account-manager.js unbind

# 帮助
node scripts/ad-account-manager.js help

直接绑定（如果已有 API Key）

node scripts/ad-account-manager.js bind --key "x2c_sk_<REDACTED>xxx"

---

🎭 Ad Character Manager（角色管理）

管理自定义角色，可在视频制作中用作主角。制作时系统会根据性别自动匹配角色与剧本中的人物。

注意： 每个用户最多 5 个角色。

命令列表

# 查询角色列表
node scripts/ad-character-manager.js list

# 创建角色
node scripts/ad-character-manager.js create <name> <gender> <image_url>

# 删除角色
node scripts/ad-character-manager.js delete <character_id>

# 帮助
node scripts/ad-character-manager.js help

参数说明

| 参数 | 说明 | 必填 | 选项 | |-----|------|:----:|------| | name | 角色显示名称 | ✅ | - | | gender | 性别 | ✅ | male, female, other | | image_url | 角色图片的公开 URL（最大 10MB） | ✅ | - |

使用示例

# 查看当前角色
node scripts/ad-character-manager.js list

# 创建女性角色
node scripts/ad-character-manager.js create Alice female https://example.com/alice.png

# 创建男性角色
node scripts/ad-character-manager.js create Bob male https://example.com/bob.png

# 删除角色
node scripts/ad-character-manager.js delete <uuid>

API 接口

| Action | 说明 | |--------|------| | character/list | 查询角色列表 | | character/create | 创建角色 | | character/delete | 删除角色 |

---

✍️ Ad Writer（编剧）

这是提示词工程模块，AI Agent 读取指南后自己生成剧本。

功能特性

• 斯皮尔伯格风格: 温情人性、视觉诗意、情感共鸣
• 三线并行: 当下故事线、前史线、反派/外因线
• 工业化流程: 严格遵循短剧市场物理生产限制
• 完整剧本结构: 剧名、梗概、人物小传、大纲、分集、正集

使用方式

Agent 工作流程：

1. 读取 references/AD-WRITER-GUIDE.md（完整编剧指南）
2. 根据用户创意，按指南生成剧本
3. 输出六部分完整剧本

用户指令示例：

帮我写一个短剧剧本：一个程序员意外拯救了CEO，却不知道对方的真实身份

输出内容

1. 剧名
2. 一句话梗概
3. 人物小传
4. 故事大纲
5. 分集概况（1-30集）
6. 剧本正集（完整台词和镜头描述）

---

🎬 Ad Producer（视频生产）

命令列表

# 查看配置和定价
node scripts/ad-producer.js config

# 生成剧本
node scripts/ad-producer.js generate-script "你的创意" --wait

# 查询剧本状态
node scripts/ad-producer.js script-status <project_id>

# 生产视频
node scripts/ad-producer.js produce-video <project_id> 1 --wait

# 查询视频进度
node scripts/ad-producer.js video-status <project_id> 1

# 全流程（推荐）
node scripts/ad-producer.js full-workflow "创意描述" --duration 120

生成选项

| 参数 | 说明 | 默认值 | |-----|------|-------| | --mode | short_video / short_drama | short_video | | --duration | 60 / 120 / 180 / 300 | 120 | | --ratio | 9:16 / 16:9 | 9:16 | | --style | 风格名称 | - | | --episodes | 集数（固定值，不可用户自定义） | short_video=1, short_drama=10 | | --language | zh / en | zh | | --character-ids | 角色UUID数组（逗号分隔），用作主角 | - | | --wait | 等待完成 | false |

成本

| 项目 | 积分 | 美元 | |-----|------|-----| | 剧本（short_video） | 10 | $0.1| | 剧本（short_drama） | 100 | $1 | | 视频 60s | 299 | $2.99 | | 视频 120s | 599 | $5.99 | | 视频 180s | 799 | $7.99 | | 视频 300s | 999 | $9.99 |

---

🔄 完整工作流程

方案A：分步执行

# 1. 绑定账号（首次使用）
node scripts/ad-account-manager.js send-code [email protected]
node scripts/ad-account-manager.js verify [email protected] 123456

# 2. 查看定价
node scripts/ad-producer.js config

# 3. 生成剧本
node scripts/ad-producer.js generate-script "一个程序员穿越古代" --wait
# → 获得 project_id

# 4. 生产视频
node scripts/ad-producer.js produce-video <project_id> 1 --wait

方案B：一键自动化

node scripts/ad-producer.js full-workflow "一个程序员穿越到古代当宰相" \
  --mode short_video \
  --duration 120 \
  --ratio 9:16

---

⚙️ 配置文件

config.json:

{
  "x2cApiKey": "x2c_sk_<REDACTED>your_api_key_here",
  "x2cEmail": "[email protected]",
  "x2cUserId": "user-uuid"
}

---

🛡️ 安全与隐私

• API keys 存储在本地 config.json
• 显示时自动脱敏
• 所有API调用使用 HTTPS

---

🔧 故障排查

账号未绑定

❌ X2C Account Not Bound

解决方案:

node scripts/ad-account-manager.js send-code [email protected]
node scripts/ad-account-manager.js verify [email protected] <code>

积分不足

❌ Error: Insufficient credits

解决方案: 访问 https://x2creel.ai 充值

API Key 无效

❌ Error: Invalid or missing API key

解决方案:

node scripts/ad-account-manager.js unbind
node scripts/ad-account-manager.js send-code [email protected]

---

📊 X2C Open API

Base URL: https://eumfmgwxwjyagsvqloac.supabase.co/functions/v1/open-api

接口列表

| Action | 说明 | |--------|------| | auth/send-code | 发送验证码 | | auth/verify | 验证获取 API Key | | config/get-options | 获取配置选项 | | character/list | 查询角色列表 | | character/create | 创建角色 | | character/delete | 删除角色 | | script/generate | 生成剧本 | | script/query | 查询剧本状态 | | video/produce | 生产视频 | | video/query | 查询视频进度 |

详细 API 文档见 references/X2C-OPEN-API.md

---

📚 文档参考

• 编剧指南: references/AD-WRITER-GUIDE.md
• 剧本示例: references/example.md
• X2C API: references/X2C-OPEN-API.md

---

🎓 最佳实践

成本优化

1. 先用 short_video 测试

   • 60s 视频成本低（299 积分）
   • 确认风格满意后再做长视频

2. 选择合适的时长

   • 60s: 简短宣传片
   • 120s: 标准短剧（推荐）
   • 180s-300s: 完整剧情

提高成功率

1. 创意要清晰具体

   • 明确主角、背景、冲突
   • 避免过于抽象的描述

2. 选择合适的风格

   • 用 config 命令查看可用风格
   • 3D古风、现代都市等

---

适用场景： 商业化部署、付费短剧生成服务、B端创作工具

---

🔍 Quality Evaluator（质量评估）

使用 Gemini 2.0 Flash 分析视频质量，按标准打分。

评估维度

维度一：单片段质量 (100分) | 指标 | 权重 | 说明 | |-----|------|-----| | 时空一致性 | 35% | 主体特征在镜头内保持稳定 | | 动态动力学 | 30% | 运动符合物理规律，无跳帧 | | 视觉纯净度 | 20% | 纹理清晰，无 AI 噪点 | | 光影交互 | 15% | 阴影随物体运动同步变化 |

维度二：合成视频质量 (100分) | 指标 | 权重 | 说明 | |-----|------|-----| | 视觉流一致性 | 30% | 镜头间色调匹配 | | 剪辑节奏感 | 25% | 转场自然，匹配 BGM | | 叙事匹配度 | 25% | 准确传达剧本剧情 | | 音画同步率 | 20% | 音效与视觉契合 |

使用方式

# 评估单个视频
node scripts/quality-evaluator.js <video_url> --prompt "原始提示词"

# JSON 输出
node scripts/quality-evaluator.js <video_url> --json

输出示例

{
  "total_score": 75,
  "pass": false,
  "issues": ["人物面部不一致", "光影不自然"],
  "suggestions": ["简化角色描述", "明确光源方向"],
  "prompt_improvements": "改进后的提示词..."
}

---

🔄 Auto-Iterate（自动迭代）

自动评估 + 改进提示词 + 重新生成，直到质量达标。

规则

• 及格线: 80 分
• 最大迭代: 5 次
• 每次迭代：生成 → 评估 → 如果不及格则改进提示词重试

使用方式

node scripts/auto-iterate.js "你的创意" \
  --duration 60 \
  --style "吉卜力" \
  --threshold 80 \
  --max-iterations 5

配置要求

config.json 需要包含：

{
  "x2cApiKey": "x2c_sk_<REDACTED>xxx",
  "geminiApiKey": "your_gemini_api_key"
}

---

适用场景： 商业化部署、付费短剧生成服务、B端创作工具

---

📋 用户参数确认格式（强制）

当用户要求创建视频时，必须用文字让用户直接回复选项来确认参数。必须等用户确认全部参数后才能开始生成：

📋 参数确认

请回复你的选择：

🎬 模式：短剧(10集) 或 短视频(1集)

⏱️ 时长/价格：60秒/299、120秒/599、180秒/799、300秒/999

📐 比例：竖屏(9:16) 或 横屏(16:9)

🎨 风格：3D古风 / 2D漫剧 / 吉卜力 / 皮克斯 / 写实 / 二次元 / 国风水墨

📂 分类：玄幻 / 悬疑 / 科幻 / 都市 / 热门 / 霸总 / 仙侠

例如：「短剧、180秒、竖屏、3D古风、仙侠」

**语言**: 中文 / English

## ⚡ 异步任务处理（重要！）

当用户要求生成视频时，必须使用**异步方式**，不要等待完成！

### 流程：

1. **启动任务，不等待**
```bash
# 启动视频生成，返回project_id
USER_ID=$USER_ID node scripts/ad-producer.js full-workflow "主题" --mode short_video --duration 60 --style "风格" --language zh

2. 添加任务到跟踪列表（必须！）

# 视频开始生成后，立即调用：
/opt/storyclaw/add-video-task.sh "$USER_ID" "$project_id" "$CHAT_ID"
# 参数: user_id, project_id, chat_id (Telegram用户ID)

3. 完成后自动通知

• cron job每2分钟检查一次 /tmp/active-video-tasks.json
• 完成后自动发送消息通知用户

关键点：

• 不要用 --wait 参数，会阻塞
• 启动任务后立即返回"正在生成，稍等"
• 必须调用 add-video-task.sh 添加任务到跟踪列表
• 创建cron job监控进度
• 完成后通过对应渠道通知用户

用户创建短剧时，以下5个参数只能从配置选项中选取，不允许自定义值：

1. 模式: short_video 或 short_drama
2. 时长: 60 / 120 / 180 / 300
3. 比例: 9:16 或 16:9
4. 风格: 3D古风 / 2D漫剧 / 吉卜力 / 皮克斯 / 写实风格 / 二次元 / 国风水墨
5. 分类:
   • 中文: 玄幻异能 / 悬疑惊悚 / 科幻末世 / 都市复仇 / 热门综合 / 霸总甜宠 / 仙侠古装
   • 英文: Werewolf & Shifter / Suspense & Horror / Power & Revenge / Sweet & CEO / Magic & Fantasy / AI Drama Lab

如果用户提供的任何一项不在配置列表中，必须提示用户从列表中重新选择，不得自行替换或忽略。

集数规则（强制）：

• short_video → 固定1集，不询问用户
• short_drama → 固定10集，不询问用户
• 不允许用户自定义集数，引导流程中不展示集数选项

🎬 视频生产流程（强制）

重要规则：同一集只能发起一次制作

每个episode只能提交一次 produce-video 命令！

• ✅ 可以多次查询 video-status
• ❌ 不能重复提交 produce-video

如果任务失败，等待第三方系统修复，不要重复提交。

short_video (1集)

1. 生成剧本
2. 视频生成 → 完成后通知用户

short_drama (10集) - 必须逐集生产

1. 生成剧本 (10集)
2. 等待剧本完成
3. EP1 视频生成 → 等待完成
4. EP2 视频生成 → 等待完成
5. EP3 视频生成 → 等待完成
...
10. EP10 视频生成 → 等待完成
11. 全部完成 → 通知用户

关键点：

• 必须等上一集完成后再开始下一集，不能并行
• 每集生成完成后记录状态
• 全部10集完成后统一通知用户

调用 config/get-options API可获取最新配置列表（风格和分类可能会更新）。

⚠️ Agent 输出规范

1. 链接必须完整输出，不得截断（视频 URL 带签名很长，但必须完整）
2. 使用代码块 ``` 包裹长链接，避免被聊天软件截断
3. 关键信息（Project ID、Video URL）必须清晰展示

📢 视频完成通知规则

短剧(10集)模式下，当前集完成后必须询问用户是否继续制作下一集！

当一集视频生成完成后：

1. 展示视频链接
2. 展示本集积分消耗
3. 询问用户是否继续制作下一集

示例回复：

🎉 视频生成完成！

📊 积分消耗：599积分

继续制作下一集吗？
- 是，继续EP3
- 暂时停止

注意：

• short_video (1集) 无需询问
• 短剧模式必须询问
• 用户选择"是"后，再发起下一集的制作

⚠️ 视频失败处理规则

视频生成失败后，禁止自动重试生成！

原因：每次生成都会扣除用户积分，自动重试会导致额外扣费。

处理流程：

1. 查询失败原因（通过 video-status 命令查看 status 和 progress）
2. 将失败原因告知用户
3. 等待用户指示是否重试或调整参数

示例回复：

❌ 视频生成失败
原因: 人物生成失败 (character step failed at 14%)
当前余额: 20,013 积分

请选择：
- 重试生成（将从余额中扣除相应积分）
- 更换风格/参数后重试
- 取消任务

🔄 多集短剧生产规则（short_drama）

视频必须逐集生产，不能同时启动多集。 流程：

1. 生成剧本时必须传 total_episodes 参数（如 "total_episodes": 10），否则只会生成1集
2. 调用 video/produce 启动第1集视频制作
3. 轮询第1集状态，等待完成
4. 第1集完成后，调用 video/produce 启动第2集
5. 重复直到所有集完成
6. 每集完成后通知用户进度（如 "EP3/10 完成"）
7. 全部完成后发送总积分报告

🎬 视频播放优化

CDN返回的视频URL末尾带有 &response-content-disposition=attachment，会导致浏览器强制下载而非播放。

规则：拿到视频URL后，必须去掉 &response-content-disposition=attachment 参数，然后可以直接在浏览器中播放，无需下载到本地。

流程：

1. 获取视频URL（从 video-status 命令）
2. 去掉 &response-content-disposition=attachment
3. 直接 browser navigate 到清理后的URL → 即可播放
4. 询问用户是否需要下载视频（默认不下载，只播放）
5. 如用户要下载/发送到Telegram：下载+压缩到16MB以下（480p, crf 32）再发送

---

📱 WebChat 消息推送

WebChat 是 StoryClaw 设备的网页聊天渠道，通过 webchat-stream-ws.sh 脚本推送消息。

脚本位置

/opt/storyclaw/webchat-stream-ws.sh

使用方法

# 发送新消息（INSERT 模式）
webchat-stream-ws.sh <user_id> --file <message_file> <agent_id>

# 更新现有消息（UPDATE 模式）
webchat-stream-ws.sh <user_id> --update <message_id> --file <message_file> <agent_id>

参数说明

| 参数 | 说明 | |------|------| | user_id | WebChat 用户 ID（32位hex） | | message_id | 已有消息的 ID，用于更新 | | message_file | 包含消息内容的文件路径（必须用 --file 传递，避免 $ 符号丢失） | | agent_id | 目标 agent ID（如 director） |

示例

# 1. 发送确认消息并获取 message_id
echo "正在生成视频..." > /tmp/msg.txt
MSG_ID=$(webchat-stream-ws.sh "180d08e23cdac976b4" --file /tmp/msg.txt "director")
echo "Message ID: $MSG_ID"

# 2. 任务完成后更新消息
echo "✅ 视频生成完成！" > /tmp/result.txt
webchat-stream-ws.sh "180d08e23cdac976b4" --update "$MSG_ID" --file /tmp/result.txt "director"

注意事项

1. 必须使用 --file 模式 — 直接传文本会导致 $ 符号丢失
2. message_id 用于原地更新 — 避免产生多条消息
3. 异步任务配合 — 视频生成等长时间任务，先发送"处理中"消息，任务完成后再 update

视频任务进度推送

使用 add-video-task.sh 添加任务时，chat_id 格式决定通知渠道：

# WebChat 推送（chat_id 格式：webchat:<user_id>:<agent_id>）
add-video-task.sh "180d08e23cdac976b4" "project-id" "webchat:180d08e23cdac976b4:director"

# Telegram 推送（chat_id 为纯数字）
add-video-task.sh "5470522468" "project-id" "5470522468"

check-video-tasks.sh 会每2分钟检查任务状态，根据 chat_id 格式自动选择推送渠道。

---

版本： 2.1.2 (X2C Open API + WebChat 推送支持)