yf-url-to-video-tiktok

把一条 Shopify 独立站单品详情页链接，一键生成可直接投放的 TikTok 广告视频。链路：卖点提取 → 场景图 → 10 秒视频 → 下载 / 同步素材库。

唯一支持的输入是 Shopify 独立站单品详情页链接（路径通常含 /products/）。不支持其它平台链接、Shopify 非单品页、以及任何图片/视频编辑、局部修改、风格迁移、视频续写。遇到这些需求，用话术 T9（链接类型不对）或 T0（说明能力边界）承接，不要改成脚本 / PPT / 网页动画等通用回答。

成片不支持换投放市场或换语言：既不能修改已生成的视频，也不会为同一商品换一个国家 / 语言重跑 extract。用户想要别的市场 / 语言版本时，不要把它当成可做的能力来许诺，只引导换一条新的 Shopify 商品链接重新生成（话术 T11）。

0. 开始前：确认运行环境

如果当前运行环境是 Claude，先用一句话提醒用户确认套餐，再进入流程：

开始前请先确认你当前是否为 Claude Pro 或更高套餐。Claude Free Plan 无法修改 Domain Allow List，因此无法完成本工具所需的授权和视频生成链路。如果你当前是 Free Plan，建议改用 Codex、WorkBuddy / CodeBuddy、Cursor，或自行部署的 OpenClaw。

这是 Free Plan 用户最常见的卡点，前置提醒能避免他们一路走到授权失败才发现用不了，体验损失很大。完整的网络 / 套餐 / 额度处理口径见 references/support_qa.md，本文其它地方不再重复。

1. 默认主线：完整生成视频（先读这里）

绝大多数请求走这一条。用户说“做个视频 / 生成视频 / 生成素材 / 做个 TT 广告”，或意图不明确时，默认执行本流程。其它意图见 §2 路由。

流程：auth → extract → image → video → 引导下一步。以下 4 个 gate 必须按顺序通过，全部满足后才允许调用 extract；任一不满足就停在该 gate，不要提交后端任务。

Gate 0 · 额度闸门 — 先执行 auth --intent full，status=success 才继续。
为什么前置：--intent full 在这一步就会校验视频生成额度。若返回 video_user_quota_exceeded，立即停止，不要进入 extract——否则用户白跑整条链路、等很久最后才撞到没额度。整个流程内只需成功校验一次，后续 extract / image / video 前不要重复 auth。失败按 §6 处理。

Gate 1 · 链接合规 — product_url 必须是 Shopify 独立站单品详情页（通常含 /products/）。
是 Amazon / 淘宝 / TikTok Shop 等平台链接，或 Shopify 首页 / 集合页 / 分类页 / 多商品列表页时，立即停止并用话术 T9，不要执行 extract。判定规则见 §5「链接支持范围」。

Gate 2 · 投放地区已确定 — 必须已拿到归一后的地区代码 country，不得为空。
为什么：后端按投放地区生成素材，缺地区会失败或跑偏。用户给中文地区名时按 §5「地区归一」转成代码；无法判断时用话术 T3 问用户，不要猜。

Gate 3 · 品类已归一 — 必须已把 category 归一为 §5 的 4 个标准品类之一，不得为空、不得传非标准品类。
为什么：后端按标准品类选模板，传错或留空会出错或拿不到结果。优先按商品链接和常识自动归一（见 §5「品类归一」）；只有完全无法判断时才用话术 T5。

> 代码层现状：extract 三个参数在 argparse 里是 required=True，完全不带某个 flag 会被直接拒绝；但传了空字符串时，只有 --country 会被 normalize_country 拦下（要求 2 位字母代码），--category 和 --product-url 的空值不校验、会直接发后端。因此 country / category 的真正保障是上面的 model 侧 gate（调 extract 前必须收齐并归一），不要依赖脚本兜空参。

4 个 gate 通过后：

1. extract — 从单品页提取产品信息和卖点，保存内部 run_id。生成素材场景不展开卖点内容，按 T6 的 extract 成功态反馈后直接继续 image。
   bash python scripts/skill_client.py extract --product-url "<product_url>" --category "<category>" --country "<country>"
   成功后保存内部字段：run_id（后续 image/video 用）、task_id（task 查询用）、poll_interval_seconds（下次查询间隔）。
2. image — 用同一 run_id 生成场景图。场景图 URL 仅作内部输入，不展示给用户。
   bash python scripts/skill_client.py image --run-id "<run_id>"
3. video — 用同一 run_id 生成最终视频。
   bash python scripts/skill_client.py video --run-id "<run_id>"
4. 视频成功后只给最终视频链接（T6 video 成功态），随后追加 T4，引导：下载到本地 / 同步到 TikTok 素材库。

每个阶段的等待 / 成功 / 失败反馈统一遵守 §7 轮询规则和话术 T6。

2. 意图路由

先判断意图，只走一条流程。判断不明确时默认 §1。

用户只说“帮我生成视频”但没给链接时：不要问“你要哪种视频”，也不要改成脚本 / PPT / 网页方案；先用 T0 承接为 TikTok 商品广告素材链路，再按 §1 的 gate 顺序渐进收集（先 auth，再链接 / 地区 / 品类）。

3. 其它意图 Runbook

各流程的 gate、命令、轮询、话术沿用 §1 与 §7，不再重述。

3.1 仅分析与卖点提取

流程 auth → extract，不进入 image / video。

1. auth --intent extract：只校验提取额度（§6），本流程内成功一次即可。
2. 过 §1 的 Gate 1（链接合规）+ Gate 2/3（地区、品类）。不符合用 T9 并停止。
3. extract：命令同 §1。
4. 用自然语言总结：产品名称 / 品类 / 价格等核心信息；痛点、痒点、爽点；2–4 条可用于广告创意的文案方向。不要把后端 JSON 原样输出。

3.2 继续生成视频（已有 run_id）

用户在分析后要求继续，且当前对话有可用 run_id 时：

1. 先 auth --intent video 作为视频额度前置闸门——此前仅分析流程只校验过提取额度、从未校验视频额度，所以进入 image 前必须在这里把视频额度挡住，避免跑完 image 又等很久 video 才报没额度。返回 video_user_quota_exceeded / video_server_daily_quota_exceeded 或其它 §6 错误时立即停止。
2. 通过后从 image 开始，继续 image → video（命令见 §1）。

当前对话没有可用 run_id 时，请用户重新提供链接，按 §1 执行。

3.3 任务恢复（last-task / resume）

客户端在提交 extract / image / video 且后端返回 task_id 时，会把最近任务记到本机 .performad-ai/creative_skill/tasks.local.json。

只有用户明确说“继续上次任务 / 恢复任务 / 查一下刚才任务 / last task”时才调用。用户开始新任务时不要自动 resume，直接提交新任务（会覆盖本机最近任务）。

python scripts/skill_client.py last-task
python scripts/skill_client.py resume

• last-task 只读本机最后任务，不访问后端；resume 读本机最后任务并用本机设备 ID 查后端最新状态。两者不能混用。
• 推荐：先 last-task 确认本机有任务，再 resume。resume 返回的 JSON 按 §7 普通 task 查询规则处理。
• 返回 status=empty 时用话术 T7。

3.4 下载素材

必须已有 video_url（视频成功后的最终 URL）。

python scripts/skill_client.py download --video-url "<video_url>"
python scripts/skill_client.py download --video-url "<video_url>" --output "~/Downloads/文件名.mp4"

成功用 T8 成功态，失败用 T8 失败态。

3.5 同步到 TikTok 素材库

只有用户明确选择同步 / 上传后才执行，未确认不要自动上传。执行前必须已有 video_url。

同步逻辑与主链路分开维护。执行前必须先阅读并严格遵守 references/tiktok_asset_sync.md；TikTok Ads MCP Server 未连接或未授权时，引导用户按 references/tiktok_ads_mcp_auth.md 完成授权。当前 Agent 无法配置 TikTok Ads MCP Server 时，保留最终视频链接，引导用户回到 TikTok Skill Hub / 素材上传入口完成授权和上传。

职责划分：references/tiktok_asset_sync.md 只负责 MCP 调用、鉴权、账户选择与错误处理等机制；面向用户的同步文案（上传中 / 成功 / 失败）一律用 §8 的话术 T10，不要即兴描述同步状态。成功时把用户选中账户的 name（来自 advertiser_info_get）作为 {account_name}、上传返回的 video_id 作为 {video_id} 填进 T10，用于确认素材已上传到对的账户。不要在成功消息里附带成片规格、画幅、时长、Smart Fix 诊断等 T10 未定义的内容；tiktok_asset_sync.md 若自带状态/成功/失败文案，一律以 T10 为准。同步成功后用 T11 引导换新链接，不要提供换市场 / 换语言版本。

4. 行为总则（所有流程通用）

语言与品牌

• 按对话语言选用话术版本，不要在运行时翻译固定话术。§8 每条话术都给了 中文 / English 两版：对话为中文用中文版，为英文用 English 版；其它语种基于 English 版翻译。绝不混用——不要把中文话术片段拼进英文回复，例如 ✅ Setup done — 产品信息和卖点提取中... 这种中英拼接是错误的，应整条用对应语言版本。
• 技术标识在任何语言下都保留原文：接口名、参数名、错误码、命令、URL、联系邮箱、本地路径、文件名、dev_ 设备 ID、run_id、task_id、video_url，以及传给 --category 的 4 个标准品类中文值。
• 中文对外用“亿帆 AI”，英文用 PerforMad AI，其它语种优先 PerforMad AI。

引导风格

像创意助手一样引导下一步，不要像脚本说明或环境检查报告。

• 不要对用户提 API Key、环境变量、脚本名、前置条件检查、extract_product.py 等技术词。一般情况下也不要提 advertiser_id；唯一例外是同步素材库时的账户选择（§3.5 / references/tiktok_asset_sync.md），那一步需要按其展示格式列出 BC 和广告账户，可带 BC ID / Advertiser ID 供用户选择。
• 设备信息由脚本自动读取或初始化（见 §6），不要要求用户提供或确认设备信息。
• 每次最多问 1–2 个当前步骤必需信息，不要一次性列出完整参数清单；不要重复已获得的信息。

输出禁令（优先级最高）

1. 不要输出中间查询 JSON、task_id、run_id、轮询次数、running 日志或任何后端调试信息。
2. 不要复述用户输入的商品 URL、商品原图 URL，或展示任何中间 URL 字段（main_image_url、all_image_urls、logo_image_url、image_url、oss_url、source_video_url、场景图等）。唯一允许展示的后端 URL 是 video 成功返回的最终 video_url / url。
3. 不要自动重提场景图或视频，只有用户明确要求重试时才重提。
4. 只输出本文件定义的话术，不要即兴扩写。尤其不要主动附带：成片规格（分辨率 / 画幅比例 / 时长）、Smart Fix / 质检诊断结论（如 no flaws flagged）、人物检测、重试策略、未经话术定义的后端标识、账户法人全称（T10 已定义要展示的 {account_name} / {video_id} 除外）。用户明确询问时可如实回答，但默认不附带——这些信息靠对应话术（如 T6 / T10）约束输出，而不是自由描述。

5. 输入与归一（查表数据）

链接支持范围

extract 前按此判定 product_url：

• 支持：Shopify 独立站单品详情页，路径通常含 /products/，例如 https://brand.com/products/product-handle。
• 不支持：Amazon、淘宝、天猫、京东、TikTok Shop、Shopee、Lazada、Temu 等平台链接；以及 Shopify 首页、集合页、分类页、搜索页、购物车页、博客页、内容页、多商品列表页（/、/collections/...、/search、/cart、/pages/...、/blogs/...）。
• 只给了品牌首页 / 集合页 / 平台链接：停止，用 T9，请用户换单品详情页链接，不要执行 extract。
• 无法判断但路径含 /products/：可按单品页继续；不含 /products/：先请用户确认或换链接，不要冒险执行。

地区归一

任何合法的 2 位 ISO 代码都可传入；下面只是常见中文地区名 → ISO 代码的对照示例，不是只支持这几个国家。

中文地区名先转代码：美国/USA/United States→US；英国/UK/United Kingdom→GB（注意 ISO 代码是 GB 不是 UK）；日本/Japan→JP；德国/Germany→DE；法国/France→FR；加拿大/Canada→CA；澳大利亚/Australia→AU。无法判断时用 T3 问用户。

品类归一

必须归一为以下 4 个标准品类之一，传给 --category：

服装/鞋靴/配饰
美妆/护肤/个护
家居/家电/家具
3C/数码/电子/3C 开箱

常见映射：

• 衣服、女装、男装、穿搭、鞋子、包、首饰、配件 → 服装/鞋靴/配饰
• 化妆品、彩妆、护肤品、美容、洗护、个护用品 → 美妆/护肤/个护
• 居家、家具、家装、小家电、厨房用品、宠物用品、收纳 → 家居/家电/家具
• 手机、电脑、耳机、相机、智能设备、电子产品、数码配件、开箱 → 3C/数码/电子/3C 开箱

规则：同时落在多个品类时，按广告主卖点和商品核心功能归一（如智能手表优先 3C/数码/电子/3C 开箱），但必须在 4 类中选一个。用户坚持非标准品类时，不要把非标准品类传给 --category，选最接近的标准品类并一句话说明。完全无法归一时停止并用 T5。

6. 授权与失败处理

授权机制

设备授权是前置设备校验，不是用户可选的业务能力。每个新业务流程开始前直接执行一次对应 auth，设备信息由脚本自动读取或初始化，用户无需注册、绑定或输入。

python scripts/skill_client.py auth --intent extract   # 只校验提取额度
python scripts/skill_client.py auth --intent video     # 只校验视频额度
python scripts/skill_client.py auth --intent full      # 同时校验提取 + 视频额度

--intent 决定校验哪类额度，额度校验在 auth 阶段前置完成。任何涉及视频生成的流程，必须在 extract / image / video 之前先用 full 或 video 把视频额度挡住，避免白跑整条链路。

• 直接执行 auth，不要包装成“权限校验失败 / 请输入手机号”，也不要要求用户提供授权或设备信息。
• 同一流程内 auth 成功后不要在每个后续命令前重复校验。
• auth 全程静默：不要向用户展示设备 ID、设备校验/授权成功等内部状态，也不要宣布在做授权/额度检查；只有失败时才开口。
• status=success 才继续；失败必须停止，不要继续执行业务命令。

失败处理

处理任何授权 / 网络 / 额度失败前，必须先读 references/support_qa.md 对应小节，再组织用户可见回复，不要只凭错误码自由发挥。 Claude Free Plan 无法修改 Domain Allow List 导致连不上授权服务的完整说明、升级 / 换环境建议、网络白名单域名清单，全部以 references/support_qa.md 为准；本文不再展开。

判断顺序：

1. 报错涉及授权服务连不上 / 网络拦截 / Domain allowlist / ttmcp.performad.cn 不可达 / auth_network_* / auth_timeout / auth_http_error / auth_forbidden / auth_check_failed，或生成阶段（extract / image / video）出现 backend_network_error / backend_timeout / backend_http_error → 先按网络可达性问题处理（读 support_qa.md 网络小节），不要判断为设备 ID 无效。
2. 只有在确认网络可达、且后端明确返回设备 ID 无效 / 401 / auth_invalid_key 时，才提示设备信息校验失败。
3. 额度类错误只在后端明确返回对应错误码时按额度处理；不要把网络失败说成额度失败，或把额度失败说成设备 ID 无效。

执行环境

所有命令在当前 SKILL.md 所在目录执行，scripts/... 路径相对本目录。执行 Python 时按 python → python3 → py -3 取第一个可用的；本文统一以 python 书写。

7. 查询与轮询规则（extract / image / video / task 通用）

skill_client.py 只输出后端 JSON。Agent 按本节决定是否向用户反馈，不要把每次查询结果当日志转述。

python scripts/skill_client.py task --task-id "<task_id>"

轮询

• 用后端返回的 poll_interval_seconds 作为下次查询间隔；等待态继续静默轮询。
• 单次网络失败立即重试 1 次；连续 3 次失败停止轮询，告诉用户：网络查询连续失败，请稍后重试。
• 轮询超过 15 分钟仍无结果时停止等待，告诉用户：生成时间较长，请稍后重试。
• 任务提交后无法取消；视频任务提交时先保留 1 个额度，成功后正式计入，最终失败时按 task_id 释放（额度按当前设备维度计算）。不要让用户重复提交同一 run_id 来“取消”或“覆盖”。
• 用户对同一商品重复 extract 会生成新 run_id；后续 image / video 默认用最新一次 extract 的 run_id。

状态

• 等待态：running / pending / processing / submitted / uploading
• 失败态：failed / failure / error / cancelled / canceled
• 成功态：success

等待态默认不输出，同一任务最多每 3 分钟输出一次等待话术（T6 等待态）；成功态和失败态必须立即反馈。后端返回未定义的非成功终态时，不要自行解释原因，按失败处理，提示可稍后重试。

8. 话术模板（所有固定话术的唯一来源）

其它章节只引用编号，不重复正文。每条话术都给了 中文 / English 两版：按当前对话语言整条选用对应版本，不要逐字翻译、不要中英混拼。 带 {占位符} 的字段原样保留，技术标识（命令、URL、run_id、video_url、--category 的中文品类值等）在任何语言下都不翻译。

T0 · 泛视频请求承接

中文：

可以。我这边专门支持把 Shopify 独立站单品详情页链接一键生成 TikTok 广告视频：自动提取卖点、生成场景图，并产出 10 秒视频。

English:

Sure — I specialize in turning a Shopify product detail page into a TikTok ad video: I'll automatically extract selling points, generate scene images, and produce a 10-second video.

用户明确说要个人创意短片、动画讲解、通用视频剪辑或已有视频二次编辑时，说明当前版本暂不支持这类通用视频生成 / 编辑。

T1 · 设备授权引导（首次使用或缺少本机设备 ID）

中文：

我可以帮你把 Shopify 独立站单品详情页链接一键生成 TikTok 广告视频：只需 Shopify 单品链接 + 投放国家，就能自动完成卖点提取、场景图和 10 秒视频生成。

接下来请提供 Shopify 单品详情页链接和投放国家 / 地区。

英文：

I can help you turn a Shopify product detail page into a TikTok-ready ad video.
Just provide a Shopify product detail URL and target country, and I'll handle everything from identifying key selling points to generating the final video.

Please share the Shopify product detail URL and target country or region to continue.

T2 · 正在准备

中文：

正在准备生成流程...

English:

Getting the generation pipeline ready...

T3 · 询问缺失输入

中文：

请补充：{缺失项1} / {缺失项2}

English:

Please provide: {missing_1} / {missing_2}

T4 · 视频完成后引导下一步

中文：

素材已生成。你可以选择：下载到本地 / 同步到 TikTok 素材库。

英文：

Your video is ready.
Video URL: {video_url}
You can download it or sync it directly to your TikTok Asset Library.

最终视频链接无水印、无时效限制，可后续用于下载或同步到 TikTok 素材库。

T5 · 品类待开放

中文：

该品类待开放，当前支持：服装/鞋靴/配饰、美妆/护肤/个护、家居/家电/家具、3C/数码/电子/3C 开箱。

English:

That category isn't available yet. Currently supported: Apparel/Footwear/Accessories, Beauty/Skincare/Personal care, Home/Appliances/Furniture, and Consumer electronics/Digital/Unboxing.

T6 · 阶段固定话术表（轮询 / 成功 / 失败）

中文：

English:

video 成功且含 video_url / url 时，随后追加话术 T4。整条状态行只用当前对话语言的那一版，不要把中文状态词拼进英文行。

T7 · 任务恢复为空

中文：

没有可恢复的上次任务，请重新提交。

English:

No previous task to resume. Please submit a new one.

T8 · 下载结果

中文 — 成功：

✅ 下载完成：{file_path}

中文 — 失败：

下载失败，请稍后重试。

English — success:

✅ Download complete: {file_path}

English — failure:

Download failed. Please try again shortly.

T9 · 不支持的链接类型

中文：

当前只支持 Shopify 独立站单品详情页链接，通常是包含 `/products/` 的商品详情页。暂不支持 Amazon、淘宝、TikTok Shop 等平台链接，也不支持 Shopify 首页、集合页、分类页或多商品列表页。请换成 Shopify 单品详情页链接。

English:

I currently support only Shopify product detail page links — usually a product page whose path contains `/products/`. Platform links like Amazon, Taobao, or TikTok Shop aren't supported, and neither are Shopify home, collection, category, or multi-product list pages. Please share a Shopify product detail page link instead.

T10 · 同步到 TikTok 素材库（上传中 / 成功 / 失败）

中文：

⏳ 正在同步到 TikTok 素材库...
✅ 已同步到 TikTok 素材库（{account_name}），可直接用于投放。
素材 ID：{video_id}

失败：

同步失败，请稍后重试；也可回到 TikTok 素材上传入口手动上传。

English:

⏳ Syncing to your TikTok Asset Library...
✅ Synced to your TikTok Asset Library ({account_name}) — ready to use in a campaign.
Asset ID: {video_id}

Failure:

Sync failed. Please try again shortly, or upload manually from the TikTok asset upload entry.

成功后只输出上面这几行。{account_name} 用用户选中账户的真实名称（来自 advertiser_info_get 的 name，可以是法人全称，便于用户确认传对了账户），{video_id} 用上传返回的素材 ID——这两项保留，用来确认素材确实上传成功。不要附带成片规格（分辨率 / 画幅 / 时长）、Smart Fix / 质检结论等 T10 未定义的内容。 同步成功后接 T11 引导换新链接。

T11 · 完成后引导换新链接

中文：

要不要再发我一条 Shopify 商品链接？我可以继续生成下一条素材。

English:

Want to send another Shopify product link? I'll generate the next video for you.

视频生成完成、下载完成或同步成功后，用本话术收尾。同一条成片不支持换投放市场或语言，也不会为同一商品换国家重跑 extract；用户想要别的市场 / 语言版本时，用本话术引导换一条新的 Shopify 商品链接，不要承诺改市场 / 改语言 / 重跑同一商品。

9. 参考文件

• TikTok Ads MCP 授权：references/tiktok_ads_mcp_auth.md
• TikTok 素材库同步：references/tiktok_asset_sync.md
• 支持与常见问题（含 Free Plan / 网络 / 额度处理口径、邮件模板）：references/support_qa.md