| name | xhs-video-to-zhihu |
| description | 将小红书公开视频链接或已有分析稿，改写为适合知乎发布的中文图文初稿。用于视频转图文、跨平台内容复用、AI 工具分享改写、vibecoding 经验整理、操作演示总结等场景。当用户提供小红书链接、分析稿，或要求"把这条内容改成知乎图文/知乎回答/知乎文章"时使用。 |
小红书视频转知乎
这个 Skill 做什么？
给它一条小红书视频链接（或已有的分析稿），它会自动完成：
- 视频解析：语音转写（ASR）+ 视频画面理解（多模态大模型），生成结构化的视频分析稿
- 内容改写：将分析稿改写为适合知乎发布的中文图文，保留你的个人表达风格
- 配图处理：从视频中提取关键帧截图，必要时生成信息图
- 导出发布：输出
.docx 文件，可直接导入知乎编辑器发布
适用场景：视频转图文、跨平台内容复用、AI 工具分享改写、vibecoding 经验整理、操作演示总结。
首次使用配置
1. 配置百炼 API Key（必填）
脚本使用阿里云百炼的 ASR 和多模态视频理解能力，需要一个支持多模态模型（qwen-vl 系列）的 API Key。
获取步骤：
- 打开 阿里云百炼控制台
- 左侧菜单 → API-KEY 管理 → 创建新的 API-KEY
- 确保该 Key 所在的账号已开通 通义千问 VL（视觉语言）模型 的调用权限（百炼控制台 → 模型广场 → 搜索
qwen-vl → 开通）
⚠️ 普通文本模型的 Key 也能用于 ASR 转写，但视频画面理解需要多模态模型权限。如果只有文本模型权限，脚本的 ASR 部分可正常运行，但视频理解部分会失败。
配置方式：
将 .env.example 复制为 .env，填入你的 API Key：
cp .agents/skills/xhs-video-to-zhihu/.env.example .agents/skills/xhs-video-to-zhihu/.env
编辑 .env 文件：
DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxxxx
脚本按以下优先级查找 API Key：.env 文件 → 系统环境变量 DASHSCOPE_API_KEY → Windows 注册表。三者任一配置即可。
2. 配置输出目录
首次使用时，AI 会询问你希望将产出文件存放在哪个目录，并自动写入 .env 的 OUTPUT_DIR 字段。
你也可以提前手动配置：
OUTPUT_DIR=20_项目/小红书视频转知乎图文工具/样例
路径为相对于项目根目录的相对路径。所有过程文件（分析稿、工作稿、最终版、docx、截图）都会存放在该目录下按视频标题自动创建的子文件夹中。
3. 系统工具
| 工具 | 用途 | Windows | macOS |
|---|
| Python 3.10+ | 运行脚本 | 系统自带或官网安装 | brew install python |
| ffmpeg | 视频取帧截图 | winget install ffmpeg | brew install ffmpeg |
| Pandoc | md → docx 转换 | winget install JohnMacFarlane.Pandoc | brew install pandoc |
| Node.js 18+ | 配图生成（Puppeteer 导出 PNG） | winget install OpenJS.NodeJS | brew install node |
Node.js 仅在步骤 9（配图生成）需要，如果不需要 AI 生成信息图可跳过。首次使用前需在 scripts/ 目录下执行 npm install 安装 Puppeteer 依赖。
4. Python 依赖
pip install -r .agents/skills/xhs-video-to-zhihu/scripts/requirements.txt
产物结构
每次执行默认产出以下文件，存放在 .env 中配置的 OUTPUT_DIR 目录下：
<OUTPUT_DIR>/<标题>-视频转写/
├── <标题>-视频分析稿.md
├── <标题>-知乎图文工作稿.md
├── <标题>-知乎图文最终版.md
├── <标题>-知乎发布版.docx
└── 截图/
├── frame_001.jpg
└── ...
OUTPUT_DIR：由 .env 文件配置，首次使用时 AI 会询问用户并自动写入<标题>-视频转写/ 子目录由脚本自动创建，无需手动指定- 中间缓存与临时文件放
.tmp/video_analysis/
- 文件已存在时优先更新，不要创建副本
工作流
步骤 1：判断输入类型
首次使用检查：
-
配置检查：读取 .env 文件，如果 OUTPUT_DIR 为空或不存在，询问用户：
"你希望将视频分析稿、知乎图文和最终 docx 存放在哪个目录？例如 20_项目/小红书视频转知乎图文工具/样例"
用户确认后，将路径写入 .env 文件的 OUTPUT_DIR 字段。后续所有步骤均使用该目录。
-
环境检测（静默执行，已安装则跳过提醒）：
逐项检测，每项用独立命令执行，任一失败不影响其他项检测。
⚠️ 重要：下方命令经过反复验证，请严格按照给定写法执行，不要自行改写命令或路径。错误的检测写法会导致误判"未安装"，进而触发不必要的重复安装。
python -c "import docx; print('python-docx OK')"
ffmpeg -version
pandoc --version
where.exe pandoc
node -e "require('<SKILL_SCRIPTS>/node_modules/puppeteer'); console.log('puppeteer OK')"
为什么必须这样写：
- Pandoc：通过 WinGet 安装后，新终端进程可能尚未刷新 PATH。
pandoc --version 失败不等于未安装，必须用 where.exe pandoc 二次确认。
- Puppeteer：
node -e 中的 require('puppeteer')（裸模块名）从 cwd/node_modules/ 查找，但 AI 执行命令时 cwd 不可控；require('.agents/...')（相对路径）是相对于 [eval] 虚拟文件解析而非 cwd，必定失败。只有绝对路径能保证一次成功。
.env 变量名：脚本只识别 DASHSCOPE_API_KEY，不要写成 API_KEY 或其他变体。
仅对未通过的工具提示用户安装，不要重复提醒已安装的工具。如果某项工具第一次检测失败，必须按上述 fallback 步骤二次确认后再做结论，禁止一次失败就判定为未安装。
| 输入类型 | 处理方式 |
|---|
| 小红书公开视频链接 | 执行步骤 2 运行脚本 |
| 已有分析稿 / 逐字稿 / Markdown 笔记 | 跳过步骤 2，直接进入步骤 3 |
| 本地视频文件 | 提示用户先通过百炼 / 通义听悟获取逐字稿，再继续 |
步骤 2：运行脚本生成视频分析稿
python '.agents\skills\xhs-video-to-zhihu\scripts\xhs_video_to_analysis.py' --url '<小红书链接>' --output-dir '<OUTPUT_DIR>' --cache-dir '.tmp\video_analysis'
其中 <OUTPUT_DIR> 为 .env 中配置的输出目录。
脚本内部并行执行两条链路：百炼 ASR 语音转写、qwen3-vl-plus 视频画面理解。并行完成后，解析视频理解输出的截图候选列表，按需用 ffmpeg 精确取帧。产物为合并后的视频分析稿（含操作时间线、截图候选列表、关键语音片段）及 截图/ 子目录。
脚本失败时依次检查：
DASHSCOPE_API_KEY 是否已设置- 小红书链接是否公开可访问
- 视频直链签名是否过期（过期则重新从分享页提取，不复用旧链接）
ffmpeg 是否已安装（抽帧失败不影响分析稿生成，但截图功能不可用）
视频分析稿的完整结构与字段说明参考：视频分析稿模板
视频理解提示词参考：高质量视频理解提示词
步骤 3：术语与证据等级校正（不可跳过）
在改写前，必须对分析稿执行以下两项校正，并直接修改分析稿原文：
- 术语纠错：按 术语纠错规则 修正 ASR 误识别的专业术语（如"康菲UI"→"ComfyUI"）
- 证据等级标注：按 证据等级规则 标注关键事实可信度，不把低确定性信息写成确定事实
完成标志：校正完成后，必须在对话中显式输出校正摘要，格式如下：
术语校正：共修正 N 处（列出主要修正项）
证据等级：共标注 N 条关键事实（列出降级项，如有）
如无需修正，输出"术语与证据校正完成，分析稿无需修改"
门禁规则：未输出校正摘要即进入步骤 4 或步骤 5 是流程违规
步骤 4：一次性信息缺口扫描与提问（不可跳过）
视频分析稿完成后，必须做一次完整的五维度扫描（主轴、重点、事实、发布目标、内容边界），一次性向用户提出 2 到 5 个最关键问题。
不允许两轮提问：第一轮问主轴、第二轮补事实的做法是错误的。
门禁规则：
- 即使用户直接要求"生成工作稿"，也必须先执行本步骤
- 如果扫描后确实无缺口，必须显式输出"信息缺口扫描完成，无需补充提问"才能进入步骤 5
- 未执行本步骤直接生成工作稿是流程违规
提问判断逻辑与问题生成规则参考：内容补充提问机制
用户回答后（或确认无缺口后）才进入步骤 5。
步骤 5：生成知乎图文工作稿
按 知乎图文改写规则 改写，如需贴近作者风格额外参考 个人表达风格。
工作稿允许保留轻度编辑痕迹，不允许在明知缺关键信息的情况下大量写入模糊表述。
工作稿末尾应包含“配图任务定义”表格，列出建议插入的截图及其位置。引用截图时必须使用 截图/ 子目录下的真实文件名，不要使用占位符。文件名格式为 frame_<序号>.jpg（如 frame_001.jpg）。
步骤 6：发布前检查
按 最终发布前检查清单 逐项检查。
有任一一票否决项未通过，则不生成最终版，返回步骤 4 补充信息。
步骤 7：生成知乎图文最终版
通过全部检查后输出最终版。最终版不得保留任何过程性措辞（"待确认""视频里提到"等）。
图片嵌入格式：最终版中的截图嵌入统一使用 Obsidian wikilink 语法 ![[文件名.jpg]]，不要使用标准 Markdown 的  语法——后者在文件名含空格或特殊字符时 Obsidian 无法正确解析。
步骤 8：截图适配性验证
最终版生成后、配图生成前，对最终版中每个配图位置引用的截图逐张验证。
执行逻辑：
- 取最终版中配图任务定义表里为该位置推荐的第一张截图
- 读取图片（调用
read_file 查看图片），判断是否适合该配图位置
- 判断结果：
- 适合 → 确认使用，进入下一个配图位置
- 裁切后可用 → 标记需裁切处理，进入下一个配图位置
- 不适合 → 回到配图任务定义表，根据分析稿中的截图候选描述选取下一张候选，重复步骤 2
- 如果该位置的候选截图全部不适合 → 标记为"需重绘信息图"，交由步骤 9 处理
判断维度（按优先级）：
| 维度 | 不合格标准 |
|---|
| 内容相关性 | 截图主体内容与该段落要表达的信息不匹配 |
| 关键区域清晰度 | 核心信息区域过小、文字模糊不可读 |
| 干扰信息 | 无关内容占据画面主体，分散注意力 |
| 缩放可读性 | 压缩到知乎正文宽度（≈690px）后关键信息不可辨认 |
注意：
- 不需要遍历所有截图，只对当前配图位置选中的截图做验证
- 每个配图位置最多验证 3 张候选截图，3 张都不合适则直接标记为"需重绘信息图"
- 信任视频分析稿对每帧内容的描述作为"菜单"，AI 根据菜单描述选取候选，读取图片只是"验菜"
- 验证通过的截图直接用于最终版，不再重复检查
步骤 9：配图生成（可选）
触发条件：最终版已完成，且满足以下任一条件：
- 步骤 8 中有配图位置被标记为"需重绘信息图"
- 正文中存在以下任一内容信号：
- 出现两种方案 / 方法 / 路径的明确对比
- 出现 3 个以上角色、模块或工具的分工关系
- 出现 3 步以上的线性操作流程或闭环链路
- 出现 3 到 4 个值得读者记住的核心结论
- 存在靠纯文字难以快速说清的结构关系
- 操作演示型内容中存在界面定位、按钮位置、状态变化（纯文字读者难以跟随操作）
不满足以上任一条件，不出图。
配图来源：视频分析稿中的截图候选列表优先；工作稿阶段可基于截图候选和内容信号追加配图任务定义。截图位于输出目录下的 截图/ 子目录，文件名格式为 frame_<序号>.jpg（如 frame_001.jpg）。
配图类型判断、视觉规范、生成步骤与检查规则参考：
配图交付流程：HTML/SVG 代码生成 → Puppeteer 导出为 PNG（参考图片生成规则第三步）→ PNG 插入最终版正文。
Puppeteer 位置：Puppeteer 通过 Skill 的 scripts/package.json 管理，首次使用前需在 scripts/ 目录下执行 npm install。screenshot.js 中引用 Puppeteer 时须以 scripts/ 为工作目录。
配图总量控制：
- 核心配图（AI 生成的信息图）：一篇文章不超过 3 张，短文 1-2 张
- 辅助截图（视频截图）：不计入核心配图上限，但总数建议不超过 5 张
- 优先做最能帮读者理解核心内容的那张信息图，再考虑补充
步骤 10：生成知乎发布版（docx）
基于最终版生成一份可直接导入知乎编辑器的 .docx 文件（知乎导入 docx 时会自动上传内嵌图片）。
转换方式：通过 Pandoc 将最终版 Markdown 转为 docx，图片自动嵌入。
执行命令：
python .agents/skills/xhs-video-to-zhihu/scripts/md_to_zhihu_docx.py <最终版.md路径>
脚本自动完成：移除 YAML frontmatter → ![[]] 转标准图片语法 → 标题编号转中文（## 1. → ## 一、，避免知乎将其解析为有序列表） → Pandoc 转 docx → 统一字体（中文微软雅黑、英文 Arial、代码 Consolas）。
文件命名：<标题>-知乎发布版.docx
发布流程：知乎编辑器 → 导入 → 选择 docx 文件 → 图片自动上传 → 检查排版后发布。
前置依赖：Pandoc（winget install JohnMacFarlane.Pandoc）、python-docx（pip install python-docx）。
资源索引
scripts/
xhs_video_to_analysis.py：主脚本，小红书链接 → 视频分析稿（ASR + 视频理解两路并行，完成后按需取帧）md_to_zhihu_docx.py：最终版 .md → 知乎发布版 .docx（移除 frontmatter、转图片语法、中文编号、统一字体）
references/
