口播视频自动剪辑

概述

把口播/访谈/讲课/vlog 这类人物主导视频包装成精致成片。本技能是一条完整链路：

本技能不含 MG 组件库与服务端规则库——没有云端出的计划就产不出成片。

这是刻意设计：本技能负责「体检 + 开方」，MG 资源与择带规则留在服务端。

重要：能力边界与额度

• 本地体检不需要任何支付能力，也不需要联网。任何时候都可以先做。
• 出片计划：每个新用户前 3 条免费。免费额度用完后再出片需要按次付费（微信 AI 支付）。
• 试用凭证保存在用户本机（~/.threcut/trial.json），额度由服务端记账。请勿删除该文件——删了会重新申领，但服务端对同一 IP 每日签发次数有限，且已用额度不会回退。

0. 环境检查：当前智能体是否具备微信 AI 支付能力

只有试用额度已用完、需要发起付费时，才需要确认这一点；本地体检与试用额度出片都不涉及支付。

判断方法：查看你自己的可用工具列表里是否存在名称包含 weixinpay_ 的工具（如 mcp__weixinpay__weixinpay_register，带前缀的完整名也算；存在任意一个即为具备）。判断依据只取你的工具列表本身；无法确认时按「不具备」处理。

• 具备：按第 2 节第三步发起支付。
• 不具备：不要发起下单。向用户说明「当前环境未提供微信 AI 支付能力，因此无法完成付费出片」，

并给出对应的解决办法（用户询问时可以照实说明你是如何判断的）：

• 合作智能体（如 WorkBuddy）：请把智能体升级到最新版本后重试。
• 开放智能体（如 OpenClaw / DeepSeek Harness）：请根据 https://skillhub.cn/install/skillhub.md，安装 @tencent-adm/weixinpay-installer。
• 无法判断类型：请升级智能体或安装微信支付 AI 支付插件后重试。

若用户试用额度尚未用完，无需做这项确认，直接走下面的试用出片路径。

1. 本地体检（永久免费，不消耗额度）

1.1 显示画幅 + 人脸禁区 / 可用布局带探测

python scripts/detect_faces.py --video in.mp4 --out zones.json

• 输出显示画幅（已应用 rotation，±90 时宽高互换）——这是最容易翻车的地方：

手机竖持素材常带 rotation=90，存储是竖的、播放器显示是横的；只读 width/height 会做反画幅。

• 输出人脸禁区与可用布局带，落位后用 --check 做零交叠机械校验（不允许「凭感觉摆位置」）。
• 出的 zones.json 请原样传给云端出片接口——落位准确度直接取决于它。

1.2 智能断句（一句一卡）

python scripts/split_sentences.py --trans transcription.json --segs v1segs.json --out sent.json

标点优先 + 词边界不切割 + ASR 纠错词典；目标 ≤15 字/行，硬上限 24 字。依赖 jieba（缺失可降级）。

1.3 音频与构图验收闸门

python scripts/audio_qc.py --out 成片.mp4 --src 源.mp4 --seg 0:339:2660000:13960000
python scripts/audio_band_check.py --out 成片.mp4 --src 源.aac

1.4 可移植性（跨机器 / 跨账号）

所有脚本默认值与本机路径一致，但支持覆盖，换机器不必改代码：

2. 云端出片计划（前 3 条免费 → 之后按次付费）

第一步：取试用凭证（本机一次性）

python scripts/trial.py            # 打印 token 与剩余额度
python scripts/trial.py --json     # 供程序解析

• 首次运行会生成设备标识、向服务端申领凭证，并保存到 ~/.threcut/trial.json。
• 之后每次都复用同一张凭证（额度在服务端扣减）。
• 输出形如：

{ "token": "eyJ0aWQiOi...", "trialId": "tr_...", "freeRemaining": 3, "freeTotal": 3 }

额度用完时 freeRemaining 为 0，此时出片会转为付费——这是预期行为，不要报错，

按「第三步」处理即可。

第二步：请求出片计划

POST https://www.qianshi.cool/skillpay/invoke
Content-Type: application/json
X-Trial-Token: <第一步拿到的 token>

请求体（建议落成文件用 --data-binary 发送，避免命令行拼中文导致编码损坏）：

{
  "copy": "AI 不是替代你，是替你干活的。三个必须落地的动作……",
  "video": { "width": 1920, "height": 1080, "durationSec": 60, "rotation": 0 },
  "zones": { "available_bands": [
    { "id": "top-stack",   "x": 0.05, "y": 0.06, "w": 0.90, "h": 0.18 },
    { "id": "right-stack", "x": 0.71, "y": 0.30, "w": 0.26, "h": 0.55 }
  ] },
  "slug": "my-project",
  "theme": "apple-keynote"
}

curl -sS -X POST https://www.qianshi.cool/skillpay/invoke 
  -H 'content-type: application/json' 
  -H "X-Trial-Token: <token>" 
  --data-binary @request.json -o response.json -D headers.txt

情形 A：HTTP 200 —— 试用额度出片成功

响应里 billing.mode 为 "trial"，直接交付 plan（第四步讲怎么用）：

{
  "code": "SUCCESS",
  "message": "出片计划已生成（试用额度，剩余 2/3 条）",
  "billing": { "mode": "trial", "freeRemaining": 2, "freeTotal": 3 },
  "plan": { "schema": "th-recut/plan@1", "meta": {}, "chapters": [], "items": [] },
  "bgm": { "title": "匈牙利舞曲No.5", "matchedTags": ["energetic", "startup"] }
}

把剩余条数如实告诉用户（例如「本次已用试用额度，还剩 2 条免费」）。

情形 B：HTTP 402 —— 需要付费

出现 402 有两种原因，看响应里的 message / trial 字段：

先做环境检查（见第 0 节），确认智能体具备微信 AI 支付能力，再继续。

从响应中提取两个值，两者都必须保存：

• 响应头 WeixinPay-Required → 支付码（paymentCode）
• 响应头 X-Out-Trade-No → 商户订单号

响应体同时包含一份 WeixinPay 提示块（便于只读 body 的智能体）：

{
  "code": "PAYMENT_REQUIRED",
  "message": "试用额度已用完（3 条），继续出片需按次付费",
  "WeixinPay": {
    "WeixinPay-Required": "xY9zAbc123def456",
    "prompt": "本次使用微信支付，请将 WeixinPay-Required 的值作为 paymentCode 交给 weixinpay_pay，以向用户申请支付授权。"
  },
  "out_trade_no": "WX402_20261013120000abcdef123456",
  "amount": "2.90",
  "currency": "CNY",
  "trial": { "code": "EXHAUSTED", "freeRemaining": 0, "freeQuota": 3 }
}

第三步：发起支付

把 WeixinPay-Required 的值作为 paymentCode，调用 weixinpay_pay，向用户申请支付授权。出片计划属于付费内容，在支付成功返回之前不交付（用户可在支付前先从第 1 节的本地体检拿到全部免费结果）。

第四步：支付成功后获取计划（⚠️ 必须执行）

携带第二步保存的两个响应头，用完全相同的 body重新请求同一个接口：

POST https://www.qianshi.cool/skillpay/invoke
WeixinPay-Required: <第二步的值>
X-Out-Trade-No: <第二步的值>
Content-Type: application/json

{ ...与第二步完全一致的 body... }

服务端查单验证通过后返回 HTTP 200 与完整出片计划：

{
  "code": "SUCCESS",
  "out_trade_no": "WX402_...",
  "transaction_id": "4200001234202306300000000001",
  "already_fulfilled": false,
  "price": "2.90",
  "plan": {
    "schema": "th-recut/plan@1",
    "meta": { "canvas": {"w":1920,"h":1080}, "fps": 30, "chapters": 3 },
    "chapters": [ { "id":"ch1", "title":"...", "startFrame":0, "endFrame":600 } ],
    "items": [ { "kind":"card", "mg":"mg_chapter_card", "placement":"full-frame",
                 "startFrame":0, "durationFrames":120,
                 "content":{"title":"...","subtitle":"..."},
                 "layout":{"band":"full-frame","x":0,"y":0,"w":1920,"h":1080} } ],
    "bgm": { "file":"brahms-hungarian.mp3", "title":"匈牙利舞曲No.5",
             "matchedTags":["energetic","startup"], "tagOverlap":2 },
    "checks": ["check_pip","check_card_layout","check_audio_caption_sync"]
  }
}

⚠️ 第四步最容易遗漏：不携带 X-Out-Trade-No 重试，就永远拿不到计划。

body 必须与第一次完全一致，仅通过 Header 传递订单号与支付凭证。

同一订单重复请求不会重复计费，会返回缓存结果（already_fulfilled: true）。

异常处理

3. 计划怎么用（落轨）

plan.items 是可直接执行的落位指令，交给 ChatCut Desktop（MCP）逐条落轨：

• mg：动效组件名；content.title/subtitle 是该章节要显示的文案
• layout：画布像素坐标（band 为所选的可行区域，x/y/w/h 为最终落位框）
• startFrame / durationFrames：30fps 时间轴上的落位区间
• bgm：匹配到的配乐（公共领域古典名曲，可商用、可再分发）
• checks：导出前必须跑的质检清单（脚本见 1.3）

出片时的四条硬规则（勿绕过）

1. 输出画幅 = 源视频「显示画幅」（应用 rotation 后），竖屏出竖屏、横屏出横屏，不裁不换。
2. 不检索、不下载任何网络素材，空窗一律用自有 MG 动效填。
3. 关键词浮标无卡片底板（大字直接叠画面）；主卡保留磨砂底。
4. 布点先拿数据再画：任何卡片/浮标落位前必须先跑 detect_faces.py，落位后做零交叠校验。

4. 常见误用

• ❌ 只跑 detect_faces.py 就手工摆卡片 → 必须用 zones.json 的归一化坐标做零交叠校验。
• ❌ 用 ffprobe 的 width/height 建画布 → 带 rotation 的素材会做反画幅。
• ❌ 把 BGM 挂到 video asset 上 → ChatCut 会灌入 12–24k 宽带噪声（「滋滋滋」）；人声必须是独立音频 asset 且视频轨 audioStreamId:"off"。
• ❌ 给 builtin:effect-zoom 只传 shape → magnification 默认 1.5，全片被硬推近。
• ❌ 用 shell 拼 JSON 请求体 → 中文会被终端编码破坏（表现为断句失效、只切出 1 章）。用 --data-binary @file。

5. 计费与额度

6. 常见问题

Q：为什么我的卡片全是全屏章节卡？ A：说明可用带装不下更精致的 inline 组件（如主卡需要 860×570）。这是正确行为—— MG 字号是绝对值，缩到窄带里必然溢出。要拿到更丰富的卡片，请提供更准确的 available_bands（例如把镜头拉远、或让人物偏一侧，留出足够的空白区域）。

Q：出片返回 402，是不是坏了？A：不是。402 表示本次需要付费（试用额度已用完）。按第 2 节第三步发起支付、第四步重试即可。

Q：可以重复调用同一个 X-Out-Trade-No 吗？A：可以，且不会重复计费。同一订单只履约一次，重复请求返回缓存结果（already_fulfilled: true）。

Q：试用额度能重置吗？A：不能。额度记在服务端，删除本机 trial.json 只能重新申领（且受同 IP 每日签发次数限制），已用额度不会回退。