SKILL介绍

.codex/skills/web-video-presentation/
├── SKILL.md                    # Skill 主协议：工作流、checkpoint、自检和开发约束
├── README.md / README.zh-CN.md # 英文 / 中文说明文档
├── references/                 # 分阶段参考规范，按需阅读
│   ├── CHAPTER-CRAFT.md        # 单章开发指引：视频感、动效、代码红线和自检
│   ├── OUTLINE-FORMAT.md       # outline.md 的章节、step、信息池格式
│   ├── SCRIPT-STYLE.md         # 文章改写成口播稿的风格规则
│   ├── THEMES.md               # 主题 token 契约、内置主题和自定义主题流程
│   ├── AUDIO.md                # 口播音频抽取、合成和故障排查
│   ├── RECORDING.md            # 浏览器录屏、自动播放和后期建议
│   └── EXAMPLES/               # 示例以“章节结构 anchor / 题材 case”的形式存在
│       ├── README.md           # 示例目录说明：什么时候看、怎么借鉴
│       ├── hook-chapter/       # 完整章节代码 anchor：钩子型开场的节奏和实现形态
│       ├── list-reveal/        # 完整章节代码 anchor：列举型逐 step 揭示的实现形态
│       └── case-tech-review/   # 题材 outline case：科技测评类章节规划示例
├── scripts/                    # Skill 自身的辅助脚本
│   └── scaffold.sh             # 一键生成 Vite + React + TypeScript 演示项目
├── templates/                  # scaffold.sh 复制到新项目里的运行时模板
│   ├── index.html              # Vite 入口 HTML
│   ├── vite.config.ts          # Vite 配置
│   └── src/                    # React 舞台、stepper、组件、示例章节和样式
└── themes/                     # 内置视觉主题，每套包含 theme.json + tokens.css
    ├── paper-press/            # 亮色印刷 / 杂志质感
    ├── warm-keynote/           # 暖色 keynote / 产品演示气质
    ├── midnight-press/         # 暗色印刷 / 电影感开发者审美
    ├── blueprint/              # 技术蓝图 / 系统架构拆解
    └── ...

整体流程

在3个「停留点」中可以让AI反复调整文件，例如脚本/大纲、画面/动画等等，直到满意后再进行下一步

Phase 1   内容编写
   1.1  识别用户输入
   1.2  一次产出 script.md + outline.md
        （口播稿 + 开发计划）
   ▼
[Checkpoint Plan]      ← 必须停。一次对齐 5 件事：
                         稿子 / outline / 主题 / 素材 / 开发模式
   ▼
Phase 2   网页开发
   2.1  脚手架（按选定主题）
   2.2  第 1 章 = 主线程 + 完整版本（强制 anchor）
        ▼
        [硬节点] 用户验收第 1 章 ← 不可跳过
        ▼
   2.3  第 2~N 章（按选定模式：A 逐章 / B 顺序 / C 并行）
   ▼
[Checkpoint Audio]     ← 必须停。是否合成音频
   ▼
Phase 3   音频合成（可选）
   ▼
Phase 4   录屏 + 后期

工作目录

my-video/
├── article.md          # 用户给原文时必有 —— 不删！开发阶段画面信息源
├── script.md           # 必有：B 站风格口播稿（决定节拍）
├── outline.md          # 必有：开发计划（章节切分 + 每步内容 + 信息池）
└── presentation/       # 脚手架产出的 Vite + React + TS 项目
    ├── src/chapters/<NN>-<id>/
    │   ├── <Chapter>.tsx     # 视觉实现
    │   ├── <Chapter>.css
    │   └── narrations.ts     # ★ step 数 + 口播文本的唯一真相源
    ├── scripts/
    │   ├── extract-narrations.ts   # 扫所有 narrations.ts → audio-segments.json
    │   └── synthesize-audio.sh     # 调 mmx 合成 mp3
    ├── audio-segments.json         # extract 产出（合成前 review）
    └── public/audio/<id>/<N>.mp3   # 可选：合成的音频

`script.md`和`outline.md`

第一步就是根据用户提供的文章生成口播稿script.md，references/SCRIPT-STYLE.md中对口播稿的形式/风格/结构做了大量约束，包括：

信息保留度大于60%
文字的形式和风骨
落盘时以---分割每个完整想法，作为后续的画面推进step
生成口播稿script.md后会直接生成大纲outline.md，references/OUTLINE-FORMAT.md中对大纲的格式和内容也有大量约束，包括：
只规划节奏+内容+信息密度，并不规划画面的视觉设计
约束整体结构：罗列章节，每章节都要有信息池+开发计划+口播节选，最后要有素材清
1. 信息池：一些专业术语名词/短语，以及在article.md中的来源行号
2. 开发计划：章节的每个画面的具体内容，按照step划分
3. 口播节选（可选）：节选口播稿的一句话，猜测是用于后续构建时的“对应”和“验证”
强调step的作用，口播稿中---分割的就是step，相应的就是一页画面，最后这些稿子和分块方式会整合到前端项目的narrations.ts中
需要参考references/CHAPTER-CRAFT.md来规范每个章节的大纲内容，相当于一个视觉设计和大纲的中间沟通桥梁

三次「停留点」

生成完script.md和outline.md需要让用户确认，并且选择前端的风格
撰写完毕第1章的内容，用户确认画面风格+信息密度+动画效果等内容是否满足要求，并决定接下来的开发计划，包括：
1. 串行开发，每章节完成后用户进行验收或者全部完成后再验收
2. 并行开发，每个subagent负责1个章节，反馈修改可以统一让主agent进行
所有章节都开发完毕后，询问是否合成音频。用户可以手动切换画面并录制播报，也可以用AI语音自动生成视频

自动播报和录制

核心参考文件：references/AUDIO.md和references/RECORDING.md

音频生成

会为每个画面（即每个step）生成一份单独的音频放在前端项目/public/audio下面，按照章节/画面的层级分目录存放。音频生成的来源文件是每个章节的narrations.ts文件，会将该文件转化为audio-segments.json文件，让用户审核后进行录制。默认使用MiniMax的CLI工具mmx生成，播报语音的质量还有待提升，可以考虑用商汤的senseaudio试试。

[
  {
    "chapter": "trace-scope",
    "step": 1,
    "text": "LazyLLM Tracing 解决的不是“多打日志”。它把一次真实请求变成 Trace 树：入口是 root span，Retriever、LLM、Tool 都挂成子节点，最后由 exporter 写到 Langfuse 或本地后端。",
    "audio": "trace-scope/1.mp3"
  },
  {
    "chapter": "trace-scope",
    "step": 2,
    "text": "这棵树先绑定请求上下文。`trace_id` 串起整条链，`session_id`、`user_id` 和 `request_tags` 用来聚合和筛选。这些字段会沿着组件调用传播，所以跨组件行为不会散成几段孤立日志。",
    "audio": "trace-scope/2.mp3"
  },
  {
    "chapter": "trace-scope",
    "step": 3,
    "text": "Trace 必须留下拓扑。每个节点有自己的 `span_id`，父节点写在 `parent_span_id`。Pipeline 可以 fan-out 到 retriever、formatter、llm，retriever 内部还能再嵌 TxtReader。",
    "audio": "trace-scope/3.mp3"
  },
  ...
]

视频生成

SKILL设计的是“可见浏览器窗口 + 系统录屏”的流程：

打开网页：http://localhost:5173/?auto=1 ，显示Press SPACE to start遮罩
用“QuickTime / OBS / 系统录屏”开始录制；按一次Space，遮罩消失，前端会开始播放音频
每段音频结束后自动推进下一页，最后手动停录，再裁掉头尾

案例运行

资料准备

新建一个仓库，把SKILL.md所在文件夹放到.codex/skills中或.claude/skills中，并且在仓库中至少放一份技术文档，可补充额外上下文供AI读取。此处示例使用vscode中的codex插件。

元数据审查

查看script.md和outline.md文件进行审查，如果需要调整直接让AI修改。

生成和审查章节一

SKILL强制生成章节一后让用户进行审查，可以调整前端界面或者口播内容

调整前端界面

调整前后对比：

调整播报内容

每个页面的停留时长取决于口播时长，播报内容会复制到前端项目的narrations.ts文件中，让AI一并调整即可。

串行/并行生成

本质上没有区别，生成“画面”后仍需要人工的调整，时间瓶颈并不在生成的速度上，而是在人工的调整和优化上。

并行生成所有章节后，可以一次性反馈多个问题进行调整，效率可能更高些。

音频生成和视频录制

风格主题切换

在SKILL目录中提供多个主题风格，只需替换掉前端的一个.css文件即可

使用体验

缺点

口播风格难以适配
口播稿的风格被references/SCRIPT-STYLE.md框得比较死，如果想要偏个人风格的口播稿需要多次调整/亲手撰写
画面需要多次调整
想仅凭outline.md和script.md两份文档，推测出即将AI生成的前端动画效果，比较困难；因此往往需要先生成画面，然后多次调整内容
流程固定
每个“页面”的流程是固定的：1. 进入某个step页面后，语音和动画同时自动开启；2. 动画快速结束后，静止停留在该页面，等待口播音频结束；3. 推进下一step页面；
这就导致如果每个页面只会播放一次动画，如果页面元素比较多，观众难以将页面内容和口播内容对应上

优点

上下文/记忆管理
1. SKILL采用渐进式披露，将整个流程设置为不同阶段，每个阶段指定好读取固定的.md文件，并列明每个.md文件的概述和作用
2. 将过程性资料(例如outline.md/script.md/article.md等等)持久化到本地，并在SKILL.md中列明工作目录，即使多次对话来反复修改口播稿/大纲/章节页面，压缩上下文后AI仍能比较出色地完成任务
3. 第1章验收后再进行并行开发，使得subagent有参考地生成页面，前后主题风格统一
用户切入点设置合理
1. 提供3个「停留点」让用户进行验收和修改，从而确保AI生成的内容符合用户的预期
2. 提供人工录制和自动录制两种生成视频的方式
个性化丰富
提供多种主题可供选择，前端构建完毕后仍可以通过替换.css来切换不同风格的主题；同时也可以构建新的风格/主题