脚本整理skill

Agent 适配

• 这是通用 SKILL.md 版本，任何支持本地 skill 的 agent 都应从本文件读取规则。
• 所有脚本路径都以本 skill 仓库根目录为基准；不要依赖某台机器上的绝对路径。
• agents/openai.yaml 只是 OpenAI/Codex 的界面元数据，不影响其他 agent 读取 SKILL.md。
• 使用 scripts/minimax_tts.py 前，先确认当前工作目录或传入路径能访问待配音文本与输出目录。
• 团队使用时不要把真实 MiniMax API Key 写进 SKILL.md、脚本或 GitHub 仓库；把 key 放在使用者本机的环境变量或 .env 中。

核心原则

只做“整改”，不做“改写”：

• 保留原文的口播文案、参考链接、产品名、数字、英文、语气和顺序。
• 不润色原始口播，不替换词语，不把原文改成更顺的表达。
• 可以补齐结构性字段，例如目标人群、核心卖点、视频封面文案、分镜脚本表，但必须基于原文信息推导。
• 分镜表里的“对应文案”必须使用原文句子或原文连续片段；不要改写成新句子。
• 原文缺少视频画面、音频、互动数据、截图时，不要伪造；用可执行的画面设计建议补齐分镜。
• 配音生成只使用整理后的原文口播，不为了配音顺口而改写文案；如需停顿，只能插入 MiniMax 支持的停顿标记。
• 视频封面文案可以基于脚本和产品卖点提炼，不要求逐字来自原文；但不得新增原文和卖点中没有的产品能力、数据或承诺。

标准输出结构

按参考文档格式输出，每条脚本使用以下顺序：

# 脚本一：标题（产品/主题）

**目标人群**：...

**核心卖点**：...

视频封面文案：

主标题：产品/品牌名或产品核心主题
副标题：一句话价值主张

| 段落 | 时间 | 段落功能 | 画面类型 | 画面设计 | 对应文案 |
|---|---|---|---|---|---|
| 1 | 0-5s | 开头钩子 |  |  | 原文句子 |

优化后的文案：

原文口播，按段落整理，不改字词。

参考视频：

原文链接

配音文件：

生成后的音频链接或本地文件路径

如果参考文档使用“优化的方案”等近似标题，可统一整改为“优化后的文案”，除非用户要求保留参考文档原字段名。

工作流程

1. 读取源文档内容。

   • 飞书链接优先用 lark-cli wiki +node-get 解析节点，再用 lark-cli docs +fetch --api-version v2 读取正文。
   • 如果用户提供参考格式文档，也读取参考文档，优先模仿它的字段顺序、标题层级和表格列名。

2. 识别每条脚本边界。

   • 优先按原文已有的“脚本一/脚本二”、空行分组、参考视频链接、产品主题切分。
   • 不要为了显得整齐而打乱原文脚本顺序。

3. 补齐结构性字段。

   • 脚本标题：从原文主题、产品名、开头钩子中提炼。
   • 目标人群：根据原文明确指向的用户补齐，例如制造业老板、工程师、方案商、质检主管。
   • 核心卖点：浓缩原文中已经出现的价值点，不新增未出现的事实或承诺。
   • 视频封面文案：只整理视频画面上方的封面标题区，不包含画面下方口播字幕、字幕条、进度条附近文字。
   • 默认写成两行：主标题 + 副标题。
     1. 主标题：产品/品牌名或产品核心主题，例如 西门子Xcelerator、埃数AI视觉检测、设序闪设2D。
     2. 副标题：一句话价值主张，例如 一站式智能企业增长引擎、AI视觉检测一体化交付方案。
   • 封面文案要像短视频上方封面字卡，短、直给、便于上屏；可以基于脚本和卖点提炼表达，但所有产品能力、数据和强承诺必须能从脚本或产品卖点中找到依据。
   • 如果脚本和卖点没有明确产品名，主标题用主题名；如果没有明确数据，不要硬写百分比或“第一/唯一/行业首创”等强承诺。

4. 生成分镜脚本表。

   • 固定列名：段落 / 时间 / 段落功能 / 画面类型 / 画面设计 / 对应文案。
   • 按叙事功能切分，优先 4-8 秒一段；每条脚本通常 6-8 段。
   • 段落功能 用短标签，例如开头钩子、传统痛点、方案引入、核心能力展示、利益点释放、留资 CTA。
   • 画面类型 写素材类别，例如传统工厂制造素材、西门子产品界面、开源素材、平台页面、产品演示素材。
   • 画面设计 写剪辑与字幕建议，例如文字强调效果、关键词红色强调、分屏对比、动效展示、底部 CTA。
   • 对应文案 必须逐句取自原文。可合并相邻原句，但不要改字。

5. 整理“优化后的文案”。

   • 使用原文完整口播。
   • 只允许调整换行、段落顺序对齐原文、清除明显抓取噪声。
   • 不要把文案写得更营销化；用户要的是格式整改，不是文案改写。

6. 按需生成配音。

   • 用户要求“配音”“语音合成”“生成音频”“用 MiniMax/Minimax API”时，使用 scripts/minimax_tts.py。
   • 配音文本取每条脚本的“优化后的文案”或用户指定文案；不要把分镜表字段、标题、目标人群、核心卖点混进口播。
   • 默认模型：speech-2.8-hd；默认音色：Arrogant_Miss（嚣张小姐，中文普通话）；默认参数：speed=1、pitch=0、vol=1、language_boost=Chinese、format=mp3。
   • MiniMax T2A 同步接口：POST https://api.minimaxi.com/v1/t2a_v2，备用地址：https://api-bj.minimaxi.com/v1/t2a_v2；鉴权使用 Authorization: Bearer <API_KEY>。
   • 文本小于 10000 字符；超过 3000 字符优先考虑流式或分段生成。短视频脚本通常用非流式即可。
   • 可以在原文句子之间加入 <#0.3#> 这类停顿标记；不要连续插入多个停顿标记，不要插到不能发音的空文本之间。
   • 输出音频默认保存到当前工作目录或用户指定目录，文件名带脚本序号或主题，避免覆盖已有音频。
   • 生成后的配音文件或音频链接必须放在该条脚本的“参考视频/参考链接”正下方，字段名用“配音文件：”或“配音链接：”。

7. 写入或更新文档。

   • 默认创建新文档；只有用户明确要求覆盖或继续更新某个文档时才覆盖。
   • 写入飞书时优先用 lark-cli docs +create 或 lark-cli docs +update --mode overwrite。
   • 保留本地 Markdown 备份，便于再次修改。

MiniMax 配音工具

先设置 API Key，三种方式任选一种：

$env:MINIMAX_API_KEY="你的_API_Key"

或在当前工作目录/本 skill 根目录创建 .env：

MINIMAX_API_KEY=你的_API_Key

仓库提供 .env.example 作为模板；复制为 .env 后填入公司内部提供的 MiniMax Key。真实 .env 不要提交到 GitHub。

常用命令：

python scripts/minimax_tts.py --input ./script.txt --output ./voice.mp3

可选参数：

• --voice-id：默认 Arrogant_Miss，也可替换为系统音色或复刻音色 ID。
• --speed：语速，范围 [0.5,2]，默认 1。
• --pitch：语调，范围 [-12,12]，默认 0。
• --vol：音量，范围 (0,10]，默认 1。
• --emotion：可选 happy/sad/angry/fearful/disgusted/surprised/calm/fluent/whisper，一般不手动指定。
• --env-file：指定一个包含 MINIMAX_API_KEY=... 的 .env 文件；不指定时自动读取当前工作目录和本 skill 根目录的 .env。
• --dry-run：只打印请求体，不调用接口；用于检查文本和参数。

缺失内容处理

• 没有分镜表：按原文补分镜表。
• 没有目标人群/核心卖点：根据原文补齐。
• 没有封面文案：根据脚本和产品卖点补成“主标题 + 副标题”两行封面文案；不要把画面下方字幕当成封面文案。
• 没有参考视频：留空或写“未提供”，不要搜索替代链接。
• 生成了配音：把音频文件路径、飞书附件链接或可访问音频链接放在“参考视频/参考链接”下面。
• 没有视频画面：画面设计写建议，不声称已经看到画面。
• 有音频/图片/表格附件：能保留就保留；不能迁移时在最终说明里告知。

质量检查

完成前逐项检查：

• 是否包含每条脚本的分镜表。
• 分镜表列名是否是 段落 / 时间 / 段落功能 / 画面类型 / 画面设计 / 对应文案。
• “对应文案”和“优化后的文案”是否保留原文，没有润色改写。
• 补充字段是否都能从原文找到依据。
• 视频封面文案是否只有主标题和副标题两行，是否排除了画面下方字幕，且没有编造卖点。
• 是否没有伪造视频画面、互动数据、截图或音频。
• 如生成配音，配音文件/链接是否紧跟在参考视频/参考链接下面。