| 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 字 |
钩子 + 信任建立 写法
钩子不靠"紧张感"和"错误答案"，靠的是真实场景 + 好奇心 + 信任感。模式：
- 场景引入：从观众日常切入（"你是不是每天都在用 Claude Code？"）
- 好奇心：抛出一个他们用但没想过的问题（"那你知不知道，它的短期记忆是怎么实现的？"）
- 信任建立：用事实说明"我有资格讲这个"（翻了源码、做了实验、自己实现了一个）。可以用幽默递进增加人味，如"可以自信地、大方地、光明磊落地帮你搞清楚"
- 三层提问：用 3 个问题预告全文结构，让观众知道接下来会讲什么
注意：
- 钩子只抛问题，不提前剧透答案细节。比如"压缩结果是加密的"这种具体结论留到正文讲。同理，第一层提到某个概念时，只用中性描述（如"压缩状态"），把冲击力强的定性词（如"加密"）留给后面的层次作为揭晓
- 如果有系列前作（如上期讲了 Claude Code），引入时要展开观众的具体猜测（"也是把聊天记录存在一个数组里，快满了就压缩成一份摘要？"），而不只是一句"是不是也一样"
逐层讲解 写法
每层之间用"那聪明的你肯定想到了""那聪明的你肯定又要问了"串联。这种写法的好处：
- 把观众当聪明人，有尊重感
- 自然引出下一个问题，不需要生硬过渡
- 形成"提问→回答→新提问"的递进节奏
每层讲完一个知识点就往下走，不复述、不总结。
不要用"我们待会儿再说它"这类预告式过渡。3 分钟口播太短，观众直接跟着你往下走，不需要路标。
写作原则
小白友好（最高优先级）
口播稿的观众不是同事，是刷短视频学知识的人。所有技术表达必须过"小白能不能一遍听懂"这道关。
术语白话化：技术术语第一时间翻译成人话，不要让观众去理解专业词
- "Messages 数组" → "把聊天记录存在一个数组里"
- "异构项目列表" → "混合列表"
- "无状态" → "没有记忆……每次调用都是一张白纸"
- "assistant 消息" → "模型回复"
- "20K token" → "两万个 token"
rg、sed → "重新搜索、重新读取"- "few-shot 示例" → 首次出现写"few-shot（示范问答）示例"，后续直接用"few-shot 示例"
- 英文类型名连发要翻译：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 张。
-
正文截图占位符：在正文讲解中，每当出现"一句话概括 + 展开讲解"的结构转折时，在概括句之后、展开之前插入截图占位符。格式与架构图占位符相同。规则：
- 触发位置：核心概念对比（如"短期记忆是内存，长期记忆是磁盘"）、步骤/流程列举（如"四步。提取、存储、检索、注入"）、机制总结（如"做三件事"）
- 数量：每篇 2-4 张，加上钩子后的架构图，全篇共 3-5 张
- 不计字数：截图占位符是画面指引，不纳入 800 字正文字数
- 风格选择：对比用
skill-card，流程/步骤用 swimlane，层级用 three-layer，要点列举用 checklist-card
-
开场白："哈喽大家好，我是二哥呀。今天用 3 分钟，给你讲清楚 XXX。"（在钩子和信任建立之后，不是最开头）
-
层间过渡："那聪明的你肯定想到了""那聪明的你肯定又要问了"（串联各层之间）
-
总结引入："最后简单总结下。"（可微调为"最后总结一下"）
-
收尾："这个知识点你学废了吗？想解锁更多 AI 硬核知识，点赞关注，我是二哥，咱们下期见！"
工作流程
步骤 1：确认主题和模式
两种模式：
- 从零创作：用户给一个技术主题，从零产出口播稿
- 优化已有稿件：用户给一份现有口播稿，进行节奏、表达、内容的优化
用 AskUserQuestion 确认不清楚的信息：主题的边界、目标时长、有没有必须覆盖的知识点。
步骤 2：深度调研（强制）
⚠️ 这一步不可跳过。 口播稿虽然短，但技术点必须准确，不允许出现原则性错误。
必须启用子 Agent 做深度调研，调研范围根据主题确定：
- 如果涉及某个技术底层（如 Function Calling、Skill 触发、RAG 检索）：调研真实的工作原理，读源码或官方文档
- 如果涉及某个产品/工具（如 Claude Code、Spring AI）：调研最新的特性
- 如果涉及概念辨析（如 Agent vs Workflow、RAG vs Fine-tuning）：调研权威定义和实际差异
调研结果用于：
- 确认口播稿中的技术描述是否准确
- 找到能让内容更有深度的细节（比如"Skill 的 description 会被注入到 system prompt"这种内行才知道的细节）
- 区分口播稿的主角是什么（比如 Skill ≠ Tool Call，不能混为一谈）
步骤 3：列大纲
按五段式结构列出大纲，明确：
- 钩子从什么场景切入，信任感怎么建立
- 三层提问分别问什么
- 核心讲解每层一句话摘要
- 总结回顾哪些要点，给什么实用建议
大纲列完先展示给用户确认，再进入正文撰写。
步骤 4：撰写口播稿
按大纲展开，注意：
- 总字数控制在 800 字（3 分钟）
- 每个段落之间空一行，方便看提词器
- 技术术语首次出现时用中文解释一次，后续直接用英文
- 举例要搞笑、夸张、生活化，不要干巴巴的技术示例
写完后保存到 docs/src/ai/video/ 目录，文件名用主题关键词，小写字母 + 连字符。
步骤 5：自检
落盘前跑一遍自检：
**口播稿自检** ✅/❌
- [ ] 字数：800 字 →（实际字数）
- [ ] 钩子：有没有场景引入 + 信任建立 + 三层提问 →（具体写法）
- [ ] 技术准确性：核心知识点经过调研验证 →（调研了哪些来源）
- [ ] AI 味：无总结套话、无学术腔、无过渡废话 →（扫描结果）
- [ ] 节奏：长短句交替，"那聪明的你"串联自然 →（情况）
- [ ] 画面感：例子是否搞笑/生活化/有画面 →（举例）
- [ ] 总结：有简洁回顾 + 实用建议 →（建议内容）
- [ ] 截图占位符：架构图 1 张 + 正文截图 2-4 张，插在概括句之后 →（数量和位置）
- [ ] 固定元素：开场白/出发过渡/层间过渡/总结/收尾是否齐全 →（检查结果）
自检通过后交付，未通过项回到步骤 4 修改。
选题库
references/desktop-agent-topics.md — 桌面端 Agent（WorkBuddy / 豆包工作 / 千问办公）20 个选题，含时间线、能力对照表、五条硬数据、三条表述纪律、以及每个选题的三层提问与干货锚点。
写新稿前先查 docs/src/ai/video/readme.md 确认哪些题目已挂 B 站链接（即已发布），避免撞车。
参考稿件
以下是经过用户校对确认的口播稿，代表目标质量和风格：
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 开卷考试）
