# Video Script

对已完成分析的视频进行导演与剪辑策划，再写带时间戳的中文解说并校验；也处理已有短片的 宣发标题、花字修订和外部文案回填。普通策划输入 work_dir 的...

- Repository: https://github.com/zenstory-ai/video-recap-skills (601 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-30
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add zenstory-ai/video-recap-skills --skill video-script -g -a claude-code -y`
Codex: `npx skills add zenstory-ai/video-recap-skills --skill video-script -g -a codex -y`
Cursor: `npx skills add zenstory-ai/video-recap-skills --skill video-script -g -a cursor -y`
Gemini CLI: `npx skills add zenstory-ai/video-recap-skills --skill video-script -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add zenstory-ai/video-recap-skills`

## Description

对已完成分析的视频进行导演与剪辑策划，再写带时间戳的中文解说并校验；也处理已有短片的 宣发标题、花字修订和外部文案回填。普通策划输入 work_dir 的 agent_narration_brief.md 与 vlm_analysis.json；文案返修输入当前成片的工程与内容证据。策划输出 recap_story_plan.json、visual_audio_board.json、 可选 style_card.json、cut 模式需要的 clip_plan.json，以及通过校验的 narration.json；仅宣发文案任务交付提案或回填既有包装计划。 外发说明：只有建议型评审 review.py 联网，它把旁白稿全文与理解证据、策划文件的文字摘录发到 MiMo chat 接口 （MIMO_API_KEY / MIMO_API_URL，不发视频、图片或音频）；单独使用时只在显式执行时运行，端到端编排默认在 TTS 前运行一次， 可用 --no-review-narration / REVIEW_NARRATION=0 关闭（严格评审开启时除外）；validate.py 与 lint 仅在本地运行。 触发词：解说词、写解说、视频旁白、宣发标题、花字修订、文案回填、 narration script、写稿、解说文案、剪辑思路、导演思路。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

## 1. 定位

只改宣发标题、封面、花字或回填外部文案时，直接读 `references/promotional-copy.md`，
按当前短片的观看理由和兑现位置处理指定文字层，不重做下述策划/旁白链。
普通解说写作不因此增加平台调研或包装任务。

本技能负责创作方向、画面与声音计划、旁白写作及校验。Agent 依次从以下五个角度作出决定：

1. 导演
2. 故事编辑
3. 画面剪辑师
4. 声音/旁白编辑
5. 第一次观看的观众

Agent 先记录简洁决定，再写时间线产物。`validate.py` 负责对理解索引做机械校验，从不改写 Agent 的稿子：段落顺序、数量、时间、文本、停顿和扩展元数据原样保留，只依据现有声音证据回写实测的 `overlaps_speech`。文本装不下时间窗、段落未按时间排序等问题以 error 退回给 Agent 修改。

下面的 `scripts/...` 均相对于本技能目录。若执行器从仓库根目录启动，请给脚本路径加上本技能的绝对目录。

### 1.1 创作控制模式

先根据用户要求和 `work_dir` 判断本轮创作控制模式。它与 `full|cut|dub` 渲染模式分别选择：

- **CREATE**：首次创作。比较至少两个真正可行的故事/剪辑假设后再选择。
- **DIRECTED**：用户已指定结构、镜头、台词或表达。忠实落实，不为满足“创作流程”虚构替代方案。
- **REVISION**：用户针对已有版本看片修改。最新反馈是当前事实来源；未点名部分默认冻结。

REVISION 先明确本轮修改项与冻结项，再编辑对应层：表达、口语节奏、字幕反馈更新 `style_card.json`；镜头、入出点、表演和声音分工更新 `visual_audio_board.json`；只有观众承诺、POV、主线或 beat 改变时才更新 `recap_story_plan.json`。被删除的镜头、原声或文案也要从相关计划中删除，不能保留过期锚点。不要把看片修改重新做成一次 CREATE。

## 2. 远程调用与数据外发

本技能只有一个脚本会联网：`review.py`（§7.1 的建议型语义评审）。其余全部在本地运行：`validate.py` 及其 lint、去 AI 味检查只读写 `work_dir` 里的文件，不发任何网络请求；策划与写稿由 Agent 直接读写 `work_dir` 完成。

`review.py` 发给谁：

- MiMo 的 OpenAI 兼容 chat 接口 `<MIMO_API_URL>/chat/completions`，用 `MIMO_API_KEY` 认证，模型为 `MIMO_MODEL`（默认 `mimo-v2.5`）。未设 `MIMO_API_URL` 时，按量计费 key 发往 `https://api.xiaomimimo.com/v1`，`tp-` 开头的 Token Plan key 发往 `MIMO_TOKEN_PLAN_CLUSTER` 选定的 token-plan 集群（默认 `https://token-plan-cn.xiaomimimo.com/v1`）。
- 未设 `MIMO_API_KEY` 时直接退出，不构造也不发送任何请求。

`review.py` 发送什么（只有文字，不发视频、帧图片或音频文件）：

- `narration.json` 全部旁白段的时间与文字。
- 理解索引的文字证据：开头、中段、结尾、长空档与各旁白时间窗附近选出的时间段内，`vlm_analysis.json` 的场景描述与 `frame_facts` 文字，以及对白转写（有 `asr_clean.json` 时用它，否则 `asr_result.json`）。
- `background_research.json` 的梗概、角色、关系与剧情线摘录。
- 存在时附上 `packaging_plan.json`、`recap_story_plan.json`、`visual_audio_board.json`、`style_card.json`（各截前 3000 字）和 `original_subtitles.json` 的原声字幕文字。
- 内容较长时分块，每块一次请求；返回的意见只写回本地 `narration_review.json` / `narration_review.md`。

何时运行、怎样关闭：

The rest: https://github.com/zenstory-ai/video-recap-skills/blob/HEAD/skills/video-script/SKILL.md