Video Script

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkDeclared3 observations
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

它把旁白稿全文与理解证据、策划文件的文字摘录发到 MiMo chat 接口 (MIMO_API_KEY / MIMO_API_URL,不发视频、图片或音频)

Audit 0.4.1 · source sha 4bf6ff660438 · 22 Oct 2026Report an issue or request a re-scan

• Publisherworldwonderer GitHub organizationOwner of the repository this skill is read from
• Source folderworldwonderer/video-recap-skills/skills/video-scriptThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict4bf6ff660438A new audit runs when the source changes
• Repository statusNot archivedLast push 1 day ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: 对已完成分析的视频进行导演与剪辑策划,再写带时间戳的中文解说并校验;也处理已有短片的 宣发标题、花字修订和外部文案回填。普通策划输入 work_dir 的 agent_narration_brief.md 与 vlm_analysis.json;文案返修输入当前成片的工程与内容证据。策划输出 recap_story_plan.json、visual_audio_board.json、 可选 style_card.json、cut…

---
name: video-script
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、写稿、解说文案、剪辑思路、导演思路。
---

## 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`。

何时运行、怎样关闭:

- 单独使用本技能时,`review.py` 只在用户或 Agent 显式执行它时运行;不执行它就没有任何外发。用户不希望稿件离开本机时,不要运行它,改为人工复核后直接跑 `validate.py`。
- 端到端编排默认在 TTS 前自动调用一次这项评审,失败不阻断;关闭方式是编排入口的 `--no-review-narration` 或环境变量 `REVIEW_NARRATION=0`。若同时开启了严格评审(`--require-narration-review` 或 `REQUIRE_NARRATION_REVIEW=1`),评审必须运行,关闭开关不生效。
- 评审是建议型的:只写报告,从不改写 `narration.json`;是否修改由 Agent 或用户决定。

## 3. 读取素材并确认状态

首先阅读:

- `work_dir/agent_narration_brief.md`:场景、时长、安静窗口与字数预算。
- `asr_writing_chunks.json`:长对白的写作分块。
- `timeline_fusion.json`:判断某段是否有对白或静音槽。
- `vlm_analysis.json` / `asr_result.json`:核对具体画面与原声证据;有 `asr_clean.json` 时以它的文本为准(lint、评审、剪辑和合成都读它)。
- brief 顶部列出的 contact sheet:不要只依赖场景摘要;反应、走位、静止和台词前后的具体时刻常常更重要。
- `production_reference.json`(仅当 `work_dir` 里有):另一部成片拆出的可迁移方法与节奏数值,用法见 §4。

full 模式使用原片时间。cut 模式第一阶段只写 `clip_plan.json`;`edited_source.mp4` 产生后,第二阶段才按输出时间写 `narration.json`。

写任何创作产物前,直接读取 `work_dir` 判断当前阶段:

- `recap_run_manifest.json`:确认 `edit_mode`、源视频和本轮设置。
- full 模式:没有 `narration.json` 时进入写稿;存在时先复核再校验。
- cut 第一阶段:尚无 `clip_plan_validated.json` / `edited_source.mp4`,只写 `clip_plan.json`。
- cut 第二阶段:两者都存在,按 `clip_plan_validated.json.clips[]` 中的 `source_start/end` 与 `output_start/end` 核对映射,再写输出时间的旁白。

必须确认旁白没有跨越错误剪辑边界,也没有落进已删除区间。整个判断只依赖 `work_dir` 产物。

## 4. 制定创作方案

先阅读 `references/creative-editing-playbook.md`,再按创作控制模式写或更新工作产物:

1. **`recap_story_plan.json`**:导演意图、CREATE 中至少两个剪辑假设、选定的 POV / 主线,以及由“变化”定义的 beats。DIRECTED / REVISION 不强行新增假设。
2. **`visual_audio_board.json`**:每拍的画面任务、具体表演/反应、入点/出点、`audio_owner`、原声锚点与 `narration_job`。
3. **`style_card.json`(适用时)**:用户当前认可的声音、口语节奏、字幕阅读姿态和明确禁忌。收到表达或字幕反馈后更新原文件,而不是只改最终文案。

只记录决定、证据锚点、被放弃的备选方案和简短理由,不写冗长思维过程。

若 `work_dir` 有 `production_reference.json`,制定方案前先读它。它来自另一部成片,只含可迁移的方法和测得的节奏,不含本片事实,不能作为本片画面、剧情或台词的证据。优先级:用户指令 > 本片证据 > 参考。CREATE 可把它的 `structure` 当作一个候选假设,与素材自生的假设比较;DIRECTED / REVISION 默认不套用。`targets` 是参考值,不是配额:与本片的 `audio_owner`、完整台词或表演冲突时以素材为准。可在 `recap_story_plan.json` 写可选字段 `reference_methods: [{"id": "m1", "decision": "adopt|adapt|skip", "note": "..."}]`。没有这个文件就跳过本段。

### 4.1 导演判断

锁定:

- 观众承诺
- POV
- 戏剧问题
- 起始与结束情绪
- 隐瞒与揭示
- 结尾余味

### 4.2 故事编辑

CREATE 比较两个真正可行的结构后选择一个;DIRECTED / REVISION 沿用用户指定或已确认的结构,除非最新反馈明确改变故事方向。每个 beat 至少改变一项:知识、权力、目标、关系、情绪或风险。若删除后因果、人物和情绪都没有损失,该 beat 通常不应保留。

### 4.3 画面剪辑

选择具体时刻,而不是只选择事件。比较:

- 说话者与倾听者
- 动作与反应
- 早进与晚进
- 早出与多停半秒

在不破坏理解的前提下晚进早出,同时保留不可替代的表演、停顿、失误、动作声和完整台词。

### 4.4 声音与旁白分工

先指定 `audio_owner`,再写字。旁白只允许承担以下 `narration_job`:

- `context`
- `causal_link`
- `foreshadow`
- `interpretation`
- `transition`
- `none`

画面、原声或沉默已经足够时使用 `none`,不要默认铺旁白。

### 4.5 cut 模式第一阶段

cut 模式先根据 `recap_story_plan.json` 与 `visual_audio_board.json` 写原片时间的 `clip_plan.json`,此时不要写 `narration.json`:

```json
{
  "target_duration": "10m",
  "clips": [
    {
      "start": 12.0,
      "end": 38.0,
      "reason": "b01 | hook | knowledge: unknown→threat | POV=主角 | 保留倾听反应 | 入点=问题已问出 | 出点=沉默落地"
    }
  ]
}
```

`reason` 统一使用:

```text
beat_id | function | change | POV | preferred moment | 入点 | 出点
```

片段顺序必须构成一条完整故事线,而不是无序高光。可使用 0–1 个 cold open,随后回到因果清楚的 setup → turn → escalation → payoff。片段长度服从具体时刻,不使用统一秒数模板;片尾必须保留完整台词或动作。密集 scene-change 候选的来源判断与处理规则由剪辑阶段定义,写计划时遵循同一规则,不制造人工闪切。

## 5. 撰写旁白

full 模式直接按原片时间写;cut 第二阶段先查看 `edited_source.mp4` 与剪后故事板,补充 `visual_audio_board.json` 的输出时间并重新确认 `audio_owner` / `narration_job`,再按输出时间写:

```json
[
  {
    "start": 5.0,
    "end": 12.0,
    "narration": "解说文本。",
    "pause_after_ms": 250,
    "overlaps_speech": true,
    "emotion": "紧张"
  }
]
```

字段说明:

| 字段 | 含义 |
|------|------|
| `s

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

1. 2026-10-22
   !CAUTION B 89 / 100

   first audit · source 4bf6ff660438

Questions about Video Script

• github.com/worldwonderer/video-recap-skills/tree/main/skills/vid — the audited source at commit 4bf6ff660438 and every finding aboveObserved · 22 Oct 2026

Spotted something wrong? Report a correction · Methodology