video-script

name	video-script
description	为短视频/口播生成或优化脚本。适用于 AI 技术科普、Agent/Skill/RAG 等技术概念讲解、工具实测、热点拆解类短视频。支持两种模式：给定主题从零产出口播稿、对已有口播稿进行优化。触发关键词包括：口播、口播稿、视频脚本、短视频文案、录视频、拍视频、video script。

短视频口播稿生成工作流

定位

面向王二讲Agent的短视频号，主打 3 分钟 AI 技术硬核拆解和知识科普。观众画像：对 AI 感兴趣的开发者和技术爱好者，刷短视频学知识点。

口播稿结构模板（3 分钟 ≈ 800 字）

五段式结构，每一段都有明确的功能定位：

段落	功能	字数参考
钩子 + 信任建立	场景引入（"你是不是每天都在用 X？"）+ 建立"我凭什么讲这个"的信任感 + 用 3 个问题预告全文结构	150-180 字
开场白 + 出发	"哈喽大家好，我是二哥呀" + 点明时长和主题 + "系好安全带"过渡	40-50 字
逐层讲解	按钩子预告的 3 个层次逐层递进，用"那聪明的你肯定想到了"串联各层	450-500 字
总结 + 建议	"最后简单总结下" + 简洁回顾 + 一条可操作的实用建议	80-100 字
收尾	引导关注	30-40 字

钩子 + 信任建立 写法

钩子不靠"紧张感"和"错误答案"，靠的是真实场景 + 好奇心 + 信任感。模式：

1. 场景引入：从观众日常切入（"你是不是每天都在用 Claude Code？"）
2. 好奇心：抛出一个他们用但没想过的问题（"那你知不知道，它的短期记忆是怎么实现的？"）
3. 信任建立：用事实说明"我有资格讲这个"（翻了源码、做了实验、自己实现了一个）。可以用幽默递进增加人味，如"可以自信地、大方地、光明磊落地帮你搞清楚"
4. 三层提问：用 3 个问题预告全文结构，让观众知道接下来会讲什么

注意：

• 钩子只抛问题，不提前剧透答案细节。比如"压缩结果是加密的"这种具体结论留到正文讲。同理，第一层提到某个概念时，只用中性描述（如"压缩状态"），把冲击力强的定性词（如"加密"）留给后面的层次作为揭晓
• 如果有系列前作（如上期讲了 Claude Code），引入时要展开观众的具体猜测（"也是把聊天记录存在一个数组里，快满了就压缩成一份摘要？"），而不只是一句"是不是也一样"

逐层讲解 写法

每层之间用"那聪明的你肯定想到了""那聪明的你肯定又要问了"串联。这种写法的好处：

• 把观众当聪明人，有尊重感
• 自然引出下一个问题，不需要生硬过渡
• 形成"提问→回答→新提问"的递进节奏

每层讲完一个知识点就往下走，不复述、不总结。

不要用"我们待会儿再说它"这类预告式过渡。3 分钟口播太短，观众直接跟着你往下走，不需要路标。

写作原则

小白友好（最高优先级）

口播稿的观众不是同事，是刷短视频学知识的人。所有技术表达必须过"小白能不能一遍听懂"这道关。

术语白话化：技术术语第一时间翻译成人话，不要让观众去理解专业词

• "Messages 数组" → "把聊天记录存在一个数组里"
• "异构项目列表" → "混合列表"
• "无状态" → "没有记忆……每次调用都是一张白纸"
• "assistant 消息" → "模型回复"
• "20K token" → "两万个 token"
• rg、sed → "重新搜索、重新读取"
• 英文类型名连发要翻译：message、reasoning、function_call → 普通消息、推理过程、工具调用

删掉观众不需要知道的细节：

• API 字段名（instructions、tools、input）→ 说清楚干嘛的就行（"系统指令和工具定义单独传给模型"）
• API 路径（/responses/compact）→ "提交给服务端"
• 竞品内部机制对比（"Claude Code 固定恢复最近 5 个文件"）→ 小白不关心竞品怎么实现的，只需要知道"文件内容压缩后可能没了"
• "什么叫异构？"这种自问自答也可以删——用破折号直接解释比设问更流畅

术语归类：多个并列术语要归成 2-3 个白话类别。如"权限、沙箱、AGENTS.md、工具定义、Skill 上下文"→"项目配置、系统指令和工具定义"

因果链必须完整：小白最怕的是"为什么？"没解释清楚。如果两个概念之间有因果关系，中间不能断。反例："旧 prompt 是新 prompt 前缀，能命中 Prompt Caching"→ 断了，小白不知道为什么前缀=缓存。正例："每次新请求的开头都和上一次完全一样→服务端认出来'这一段我算过了'→跳过→不重复计费→这就是 Prompt Caching"

对比铺垫：两个东西要对比时，前面那个就要为后面埋线。如"你能看懂的文字摘要"→后面才能接"模型能看懂，但你看不懂"；"结构很简单"→后面才能接混合列表的复杂

拟人化增加共情：把技术行为说成人的行为，观众秒懂

• "Codex 有个小心机"
• "服务端认出来'这一段我算过了'"
• "不是它傻，是它确实忘了"

节奏感

短视频的核心是节奏。长短句交替，每 30 秒左右埋一个钩子防止观众划走。

• 短句制造冲击："其实没有。""不，Claude Code 没那么蠢。"
• 长句承载信息：技术讲解用完整句子，不废话，无歧义，表达准确，一句话不超过 40 个字
• 关键结论前停顿：用独立的、短的段落断开，给观众反应时间。如"Codex 不是。"单独成段
• 密集技术段落要拆段：一段话讲了多个技术点时，拆成多个短段落，每个点独立停顿，利于口播换气和观众消化
• 幽默短评调节节奏：连续技术讲解之间插一句轻松点评（"我只能说，用心了，OpenAI"），防止观众疲劳

口语化但表达严谨

口播稿必须顺口。但技术描述要准确，不能牺牲严谨。

• 用"怎么办？""靠的是什么？"这类问句推进节奏
• 技术术语保留英文原文（Function Calling、JSON Schema、tool_calls、Embedding、Top-K）
• 连接词用口语化的（"好，接下来""告诉他——"），不用（"此外""与此同时""综上所述"）
• "换句话说"全篇最多 1 次，且必须是真正换了角度的解释，不是原话重复
• 多补语气词让句子像说话（"都是""会""的""了""要"）。如"单独传给了模型"比"单独传给模型"更自然；"Codex 要自己维护"比"Codex 只能自己维护"更中性（"只能"带无奈感，陈述事实用"要"）
• 技术归因要准确：比如"没有记忆"是大模型本身的特性（"不管是 Fable 5 还是 GPT-5.6"），不是某个工具的设计选择

信息密度

3 分钟只有 800 字左右的容量，每句话都必须有信息增量。

• 不说废话、不重复、不铺垫。画面感补充如果和前一句同义就删掉——"一串加密数据"已经够了，不需要再补一句"你打开一看，全是乱码"
• 一个知识点讲清楚就往下走，不用"换句话说""也就是说"复述
• 例子要具体到能在脑子里产生画面（尽量结合当前时间的热点话题）
• 源码/文档引用要翻译成观众能直接做的事："应保持线程短小、目标集中"→"能开新线程就开新线程，别在一个线程里一直发送新的提示词"
• 总结不要重复正文已经讲过的点。如果第三层已经讲了"压缩会丢信息"，总结不必再说"压缩次数越多，忘得越多"
• 总结中技术回顾和实用建议是两类信息，用"另外"隔开，不要一句话塞完

案例写法

案例是口播稿的灵魂，质量决定观众会不会跟着继续观看下去。

• 生活化、搞笑、夸张优先：用"母猪会上树"而不是"读过 config.yaml"，用"不影响你的帅气或美貌"而不是干巴巴地说"这不是 bug"
• 类比式案例（推荐，用于概念辨析）：用日常生活场景映射技术概念。如 what-is-react 用"闭卷考试 vs 开卷考试"说清楚 CoT 和 ReAct 的区别
• 完整故事：从头到尾，每个知识点在故事中自然出现

画面感

观众在"看"视频，所以脚本要帮观众在脑子里绘制画面。

• 用具体场景代替抽象描述
• 步骤讲解可操作
• 拟人化技术概念（"Claude Code 没那么蠢""数组会一直变大变大变大"）
• 用当前具体模型名增加画面感："不管是 Fable 5 还是 GPT-5.6"比"不管用什么模型"更有画面

去 AI 味

禁止出现：

• 总结性套话："值得注意的是""需要指出的是""综上所述"
• 学术腔："本质上来说""从技术角度分析""我们可以发现"
• 互联网黑话："赋能""闭环""抓手""链路"
• AI 三段式：每个要点都走"概念→解释→例子"的固定模板
• 过渡废话："接下来让我们看看""话不多说""下面我来介绍一下"

鼓励使用：

• 幽默反转："不是？不，你必须是。""不，Claude Code 没那么蠢。"
• 夸张比喻："压缩后摘要里只留下了一句'母猪会上树'"
• 观众代入："那聪明的你肯定想到了""那聪明的你肯定又要问了"
• 生活化收束："就像下雨时你打了伞，但身上可能还是会淋几滴雨"

固定元素

以下元素在每期口播稿中保持一致：

• 架构图占位符：在钩子 + 信任建立之后、开场白之前，插入一张架构图占位符，用一张图把本期核心知识点的结构展示出来。格式：

【截图：<名称>；风格：<风格>；截图目标：<展示什么>；关键词：<关键词1>、<关键词2>、<关键词3>】

风格参考 ai-article Skill 的 6 种（whiteboard、skill-card、data-board、three-layer、swimlane、checklist-card），口播稿最常用 whiteboard（架构/流程）和 three-layer（层级关系）。每期只需 1 张。

• 开场白："哈喽大家好，我是二哥呀。今天用 3 分钟，给你讲清楚 XXX。"（在钩子和信任建立之后，不是最开头）
• 出发过渡："系好安全带，我们粗粗粗出发了～"（开场白之后，正式讲解之前）
• 层间过渡："那聪明的你肯定想到了""那聪明的你肯定又要问了"（串联各层之间）
• 总结引入："最后简单总结下。"（可微调为"最后总结一下"）
• 收尾："这个知识点你学废了吗？想解锁更多 AI 硬核知识，点赞关注，我是二哥，咱们下期见！"

工作流程

步骤 1：确认主题和模式

两种模式：

1. 从零创作：用户给一个技术主题，从零产出口播稿
2. 优化已有稿件：用户给一份现有口播稿，进行节奏、表达、内容的优化

用 AskUserQuestion 确认不清楚的信息：主题的边界、目标时长、有没有必须覆盖的知识点。

步骤 2：深度调研（强制）

⚠️ 这一步不可跳过。 口播稿虽然短，但技术点必须准确，不允许出现原则性错误。

必须启用子 Agent 做深度调研，调研范围根据主题确定：

• 如果涉及某个技术底层（如 Function Calling、Skill 触发、RAG 检索）：调研真实的工作原理，读源码或官方文档
• 如果涉及某个产品/工具（如 Claude Code、Spring AI）：调研最新的特性
• 如果涉及概念辨析（如 Agent vs Workflow、RAG vs Fine-tuning）：调研权威定义和实际差异

调研结果用于：

1. 确认口播稿中的技术描述是否准确
2. 找到能让内容更有深度的细节（比如"Skill 的 description 会被注入到 system prompt"这种内行才知道的细节）
3. 区分口播稿的主角是什么（比如 Skill ≠ Tool Call，不能混为一谈）

步骤 3：列大纲

按五段式结构列出大纲，明确：

• 钩子从什么场景切入，信任感怎么建立
• 三层提问分别问什么
• 核心讲解每层一句话摘要
• 总结回顾哪些要点，给什么实用建议

大纲列完先展示给用户确认，再进入正文撰写。

步骤 4：撰写口播稿

按大纲展开，注意：

• 总字数控制在 800 字（3 分钟）
• 每个段落之间空一行，方便看提词器
• 技术术语首次出现时用中文解释一次，后续直接用英文
• 举例要搞笑、夸张、生活化，不要干巴巴的技术示例

写完后保存到 docs/src/ai/video/ 目录，文件名用主题关键词，小写字母 + 连字符。

步骤 5：自检

落盘前跑一遍自检：

**口播稿自检** ✅/❌
- [ ] 字数：800 字 →（实际字数）
- [ ] 钩子：有没有场景引入 + 信任建立 + 三层提问 →（具体写法）
- [ ] 技术准确性：核心知识点经过调研验证 →（调研了哪些来源）
- [ ] AI 味：无总结套话、无学术腔、无过渡废话 →（扫描结果）
- [ ] 节奏：长短句交替，"那聪明的你"串联自然 →（情况）
- [ ] 画面感：例子是否搞笑/生活化/有画面 →（举例）
- [ ] 总结：有简洁回顾 + 实用建议 →（建议内容）
- [ ] 固定元素：开场白/出发过渡/层间过渡/总结/收尾是否齐全 →（检查结果）

自检通过后交付，未通过项回到步骤 4 修改。

参考稿件

以下是经过用户校对确认的口播稿，代表目标质量和风格：

• docs/src/ai/video/codex-short-term-memory.md：最新模板 — Codex 短期记忆拆解，与 Claude Code 形成姊妹篇（展开观众猜测的钩子写法、幽默递进信任建立、技术段落拆段、幽默短评调节节奏、源码翻译成可操作建议）
• docs/src/ai/video/claude-code-short-term-memory.md：Claude Code 短期记忆的源码级拆解（五段式结构、"那聪明的你"串联、生活化举例、总结 + 实用建议收束）
• docs/src/ai/video/agent-hnow-tool-call.md：Agent 怎么知道该调用哪个工具（Tool Call 机制）
• docs/src/ai/video/agent-skill-hit-rate.md：Skill 过多如何保证命中率（Skill 语义匹配机制）
• docs/src/ai/video/what-is-react.md：什么是 ReAct——类比式案例的标杆（闭卷考试 vs 开卷考试）