video-script

# 口播稿生成工作流 ## 定位与核心参考标准 面向王二讲Agent的口播稿，主打 AI 技术硬核拆解、源码级原理科普和热点实测。观众是对 AI 感兴趣的开发者和技术爱好者。 **首选标杆稿件（写稿前必读，只学终稿的正向表达）**： - 原理科普标杆：`docs/src/ai/video/context-compaction-vs-kv-cache.md`、`docs/src/ai/video/why-not-timestamp-in-system-prompt.md` - 实测拆解标杆：`docs/src/ai/video/what-is-computer-use.md` 视频封面是制作素材，写回 `docs/src/ai/video/` 时，将末尾封面及其标题放入 `<!-- video-covers:start -->` / `<!-- video-covers:end -->` 注释区；讲解配图保持正常显示。同步和验收使用 `feishu-question-bank-sync` Skill 的封面规则。 字数控制在 1800 字最佳。统计命令： ```bash python3 -c "import re,sys;t=open(sys.argv[1],encoding='utf-8').read();t=re.sub(r'^---\n.*?\n---\n','',t,flags=re.S);t=t.split('这个公众号历史发布过')[0];t=re.sub(r'!\[[^\]]*\]\([^)]*\)|【[^】]*】','',t);print(len(re.findall(r'[一-鿿]',t))+len(re.findall(r'[A-Za-z]+',t)))" docs/src/ai/video/<文件名>.md ``` --- ## 标准结构与格式 ### 1. 开场切入与 30% 进度节点 1. **一句大白话交代场景与目的**：从观众熟悉的 Agent 使用场景切入，一句话讲清楚“什么情况下会做什么、为了什么”（如“聪明的你一定用过 Claude Code 和 DeepSeek Harness，当 Agent 连续工作一段时间后，就会执行上下文压缩，好清理出上下文空间继续使用。”），不堆砌啰嗦的界面细节，配 1 张真实界面截图占位符。 2. **提问引出冲突与核心主线**：先用一两句话点明前提规则，再用一句自然反问引出冲突（“那聪明的你应该已经注意到了，上下文压缩需要删改历史消息，这两者岂不是有冲突？”），接着点破表层误区，用“一是……；二是……”概括两者配合要解决的两个核心问题。 3. **30% 进度节点与知识库引流**：进入正片第一层前，固定接一句：“恭喜看到这里的你，已经成功击败 30% 的学习者，给自己来个关注鼓励一下吧。视频的原稿以及 369 道 Agent 八股已经整理到开源知识库。” ### 2. 逐层拆解（3-4 层递进 + 进度节点） 每一层按以下节奏展开： 1. **加粗短问句开头（只切核心问题，不塞背景铺垫和长串产品名）**： - 一句话直奔关键字（控制在 20 字以内），例如：`**接下来我问你，Agent 是什么时候触发上下文压缩的？**`、`**继续问你，Claude Code 怎么清理旧工具的返回结果？**`、`**继续，大模型生成压缩摘要时，怎么命中已有的 KV Cache？**` - 把触发前提、具体产品名和背景铺垫留给后面的回答段落。 2. **选项互动（保持 A、B、C 三个短选项，长答案拆成多选）**： - 每个选项只留一个核心动作或关键词（控制在 10–15 字以内）。如果正确答案包含两条路径或两个并列手段，不要塞进同一个长选项，拆成两个选项做成多选（如“A，每次都在本地改成占位符；B，缓存未过期时通知服务端删除；C，缓存过期后再在本地替换”）。 - 紧跟互动引导：“喜欢收藏的你可以把答案打在弹幕或者留言区。”（后续几关依次用“喜欢点赞的你会选哪一个？”“喜欢推荐的你会选哪一个？”“聪明的你会选哪一个？”）。 3. **有体感的白话原理解答（核心味道所在）**： - 开头可用“我的答案是 B。”或“我的答案是 B + C。”，到了最后一关也可以不拘泥于固定句式，直接切入分析（如“全量摘要不光要多调用一次大模型，还很容易丢掉代码行号、报错细节这类关键信息……”）。 - **先铺日常体感，再搭因果桥梁，最后落到源码动作**：不要一上来就抛抽象概念。先给一个具体的开发体感（如“上下文窗口里占体积的大头，通常是读文件、搜代码、跑测试返回的大段文本”“比如跑一次测试吐出了上万字日志，有用的信息往往集中在开头的执行命令和结尾的报错堆栈”），接着用大白话把因果逻辑搭上桥（“如果直接在本地把几轮前的工具输出改成一句简短提示，消息内容一变，提示词缓存是按前缀匹配的，从被改的那条消息开始，后面的缓存就都对不上了，等于白白重算一遍”），最后再引出源码里的设计动作。 - **技术边界严密，把“哪段命中、哪段重算、代价是什么”讲完整**：不说“全部未命中”或“100% 命中”这类绝对化的话。讲失效时说明哪段没变还能命中、从哪个位置开始断开；讲命中时说明“除了新加的那部分，前面的内容都能命中”；讲优化手段时主动交代它的工程代价（如“被裁剪的那条消息之前的前缀没变，还能继续命中缓存，从裁剪位置往后的部分则需要重新 Prefill”“当然，Sub-agent 自己的上下文要从头 Prefill，相当于拿一点额外开销换主会话的干净上下文”）。 - **一段只讲透一个主干，只用公共术语与直观数字**：只保留行业约定俗成的公共概念（`KV Cache`、`Prefix Caching`、`Prefill`、`TTL`、`tool_result`、`Sub-agent`）和有体感的代表性数字（如 `50` 轮、窗口容量的 `80%`、默认 TTL 是 `5` 分钟或 `1` 个小时）。源码内部实现全部转化为直白的动作描述，与当前提问主干无关的旁支细节一律不写。 - **转折提问简洁自然**：段间追问直接写“那什么时候在本地改消息呢？等缓存过期之后。”，不用生硬套模板。 4. **配图与进度播报**： - 每层核心机制讲完配一张对应的架构图或流程图（生成前使用 `【截图：...】` 占位符）。 - 每层结束单独成段播报进度： - 第一层结束：`恭喜看到这里的你，已经成功击败 50% 的学习者了。` - 第二层结束：`恭喜看到这里的你，成功击败 70% 的学习者了。` - 第三层结束（若共 4 层）：`恭喜看到这里的你，成功击败 90% 的学习者了。` - 最后一层结束：`恭喜你升到王者段位了，成功击败 99% 的学习者。` ### 3. 总结与收尾 1. **口语短分句总结**：用“最后简单总结一下，……”开头，拆成舒展的口语短分句，不要把四五个并列短语硬塞进一个长定语里（标杆写法：`最后简单总结一下，上下文压缩和 KV Cache 并不是非此即彼。像 Claude Code 靠的是这几招，平时消息只追加，快到阈值才触发压缩，按缓存有没有过期选择怎么清理工具输出，复用主会话前缀来生成摘要，再用 Sub-agent 隔离噪音。`）。 2. **固定收尾词**：`这个知识点你学会了吗？想解锁更多 Agent 硬核知识，点赞关注，我是二哥，咱们下期见！` --- ## 正向表达规范（与 `ai-article` 共用，详见 `.claude/skills/ai-article/references/human-tone.md`） 1. **主语直接用产品名或组件名，准确把握 Agent 定位**：直接写“Codex 会读取 `title`”“翻开 DeepSeek Harness 的源码”。Claude Code、DeepSeek Harness、Codex 统称为 Agent，既能在终端运行，也能在桌面端运行；除了写代码，还能写教程、做 PPT、做视频、处理各类工作，口播切入时不要把它们局限于“写代码”。 2. **动词干脆直接，一步到位**：用直白的动作词串起执行流程（如“挂载、暴露、读取、折叠、设定、挂起、放行、切换、跑、切到、查、塞进”），讲完动作本身即止（如“拼接到报错末尾”“切换为同步阻塞”“保护 KV Cache”“点错了再撤销”）。 3. **只用约定俗成的公共术语，把底层机制转化为通俗因果逻辑**：只保留观众有概念的公共技术词汇（如 `KV Cache`、`Prefix Caching`、`Prefill`、`TTL`、`tool_result`、`Sub-agent`、`MCP`）和有直观对比意义的代表性数据（如 `80%`、`5` 分钟、`1` 个小时）；技术状态用准确平实的中文表达（如“达到上下文窗口的阈值”“缓存未过期/缓存过期”“消息内容一变”）。重点用通俗清楚的因果逻辑把“为什么这么设计、底层怎么运作”讲明白。 4. **问句短促直接**：只问核心问题（如“Codex 怎么防止大模型被劫持？”“那第二个大招是什么？”），把触发条件和实现细节留给正文回答。 5. **用单一强有力的数据或案例说话**：每次论证只选最有代表性的一个高分或一个实测现象（如“拿到了 60 的高分，反超了自家的 GPT-6.1 Sol，58.6 分”），紧接“为什么？”进入源码拆解。 6. **数字与单位贴合日常听感**：容量写 `8 M`、`16 G`，状态分值写 `0`、`1`。 7. **截图占位符格式**（全篇 3-6 张，紧贴对应段落）： ``` 【截图：<名称>；风格：<风格>；截图目标：<展示什么>；关键词：<关键词1>、<关键词2>、<关键词3>】 ``` --- ## 工作流程 ### 步骤 1：确认用法与参考标杆 1. **从零创作**：先读取 `docs/src/ai/video/context-compaction-vs-kv-cache.md` 以及 `sucai.md` 素材。`sucai.md` 里用户写好的句子、截图和观点原样保留。稿件一旦落盘交付，后续修改前先读取磁盘最新文件内容，保留用户已改过的全部内容。 2. **优化已有稿件**：通读稿件，对照 `docs/src/ai/video/context-compaction-vs-kv-cache.md` 的节奏与正向表达标准做局部优化，保留用户校对过的句子。 ### 步骤 2：调研与白话转译（强制） 1. 启用 Sub-agent 调研 **Claude Code、Codex、DeepSeek Harness 和 Pi Agent** 的源码、官方文档或一手公告，收到结果后立即停止 Sub-agent。本地源码路径： - Claude Code：`/Users/itwanger/Documents/GitHub/claude-code-source-code` - Codex：`/Users/itwanger/Documents/GitHub/codex` - DeepSeek Harness：`/Users/itwanger/Documents/GitHub/deepseek-harness` - Pi Agent：`/Users/itwanger/Documents/GitHub/pi` 2. **源码事实转白话隔离层**：拿到 Sub-agent 调研结果后，只提炼机制原理，把源码里的私有函数名、内部变量名、缓冲常数转化为“日常痛点是什么 → 怎么处理的 → 哪部分受益、哪部分付出什么代价”的白话因果链。 ### 步骤 3：列大纲 按 `docs/src/ai/video/context-compaction-vs-kv-cache.md` 的结构列出开场切入方式、3-4 层递进短问句、A/B/C 短选项与每层对应的白话原理及代价边界，交给用户确认后再写正文。 ### 步骤 4：撰写口播稿 按确认后的大纲与 `docs/src/ai/video/context-compaction-vs-kv-cache.md` 的语言节奏撰写，保存到 `docs/src/ai/video/` 目录。 ### 步骤 5：自检 1. **六项正向质量过筛**： - **技术边界与代价完整**：讲清哪一段命中、从哪个位置开始断开重算，以及方案付出的额外代价（如裁剪位置往后需重新 Prefill、Sub-agent 自身需从头 Prefill）。 - **因果推理不跳步**：从“改动消息”到“缓存失效”之间，用平实白话把“提示词缓存按前缀匹配，从被改的那条消息开始往后对不上”讲清楚。 - **零私有命名与零无感常数**：只留行业公共术语和直观数字，不出现源码私有函数名/变量名和缓冲区常数。 - **地道中文表达**：确认没有英文注释字面直译词。 - **一段一主干**：每段只聚焦回答当前提问，砍掉偏离主线的旁支细节。 - **短问句、短选项与短分句**：问句在 20 字以内，A/B/C 保持 3 个短选项（多路径用 `B + C` 多选），总结段用舒展的口语短分句。 2. **运行机械检查脚本**： ```bash # 1. 字数统计（950-1800） python3 -c "import re,sys;t=open(sys.argv[1],encoding='utf-8').read();t=re.sub(r'^---\n.*?\n---\n','',t,flags=re.S);t=t.split('这个公众号历史发布过')[0];t=re.sub(r'!\[[^\]]*\]\([^)]*\)|【[^】]*】','',t);print(len(re.findall(r'[一-鿿]',t))+len(re.findall(r'[A-Za-z]+',t)))" docs/src/ai/video/<文件名>.md # 2. 禁用词检查（与 ai-article 共用 wording_rules.py），必须为 0 python3 -c "import re,sys;sys.path.insert(0,'.agents/skills/ai-article/scripts');from wording_rules import COMPILED_FAIL,find_hits;t=re.sub(r'【截图[^】]*】','',open(sys.argv[1],encoding='utf-8').read());hits=find_hits(t,COMPILED_FAIL);print('\n'.join(f'{h[1]} -> {h[2]}' for h in hits) if hits else 'wording_rules FAIL: 0')" docs/src/ai/video/<文件名>.md ```