القائمة
将小红书公开视频链接或已有分析稿，改写为适合知乎发布的中文图文初稿。用于视频转图文、跨平台内容复用、AI 工具分享改写、vibecoding 经验整理、操作演示总结等场景。当用户提供小红书链接、分析稿，或要求"把这条内容改成知乎图文/知乎回答/知乎文章"时使用。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | xhs-video-to-zhihu |
| description | 将小红书公开视频链接或已有分析稿，改写为适合知乎发布的中文图文初稿。用于视频转图文、跨平台内容复用、AI 工具分享改写、vibecoding 经验整理、操作演示总结等场景。当用户提供小红书链接、分析稿，或要求"把这条内容改成知乎图文/知乎回答/知乎文章"时使用。 |
给它一条小红书视频链接（或已有的分析稿），它会自动完成：
.docx 文件，可直接导入知乎编辑器发布适用场景：视频转图文、跨平台内容复用、AI 工具分享改写、vibecoding 经验整理、操作演示总结。
脚本使用阿里云百炼的 ASR 和多模态视频理解能力，需要一个支持多模态模型（qwen-vl 系列）的 API Key。
获取步骤：
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 注册表。三者任一配置即可。
首次使用时，AI 会询问你希望将产出文件存放在哪个目录，并自动写入 .env 的 OUTPUT_DIR 字段。
你也可以提前手动配置：
OUTPUT_DIR=20_项目/小红书视频转知乎图文工具/样例
路径为相对于项目根目录的相对路径。所有过程文件（分析稿、工作稿、最终版、docx、截图）都会存放在该目录下按视频标题自动创建的子文件夹中。
| 工具 | 用途 | 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 依赖。
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/首次使用检查：
配置检查：读取 .env 文件，如果 OUTPUT_DIR 为空或不存在，询问用户：
"你希望将视频分析稿、知乎图文和最终 docx 存放在哪个目录？例如
20_项目/小红书视频转知乎图文工具/样例"
用户确认后，将路径写入 .env 文件的 OUTPUT_DIR 字段。后续所有步骤均使用该目录。
环境检测（静默执行，已安装则跳过提醒）：
逐项检测，每项用独立命令执行，任一失败不影响其他项检测。
⚠️ 重要：下方命令经过反复验证，请严格按照给定写法执行，不要自行改写命令或路径。错误的检测写法会导致误判"未安装"，进而触发不必要的重复安装。
# ① python-docx
python -c "import docx; print('python-docx OK')"
# ② ffmpeg
ffmpeg -version
# ③ Pandoc — 两步检测，任一成功即为已安装
# 第一步：直接调用
pandoc --version
# 如果第一步失败，执行第二步（winget 安装后 PATH 可能未刷新）：
where.exe pandoc
# 如果 where.exe 能找到路径，说明已安装但 PATH 未生效，提示用户重启终端即可，不要安装
# ④ Puppeteer — 必须用绝对路径 require，不要用相对路径或裸模块名
# 先定位 Skill 的 scripts 目录的绝对路径（以下用 <SKILL_SCRIPTS> 代替），然后：
node -e "require('<SKILL_SCRIPTS>/node_modules/puppeteer'); console.log('puppeteer OK')"
# 示例（Windows）：
# node -e "require('f:/work/study_data/study/.agents/skills/xhs-video-to-zhihu/scripts/node_modules/puppeteer'); console.log('puppeteer OK')"
# 如果失败，在 <SKILL_SCRIPTS> 目录下执行 npm install，然后重试
为什么必须这样写：
pandoc --version 失败不等于未安装，必须用 where.exe pandoc 二次确认。node -e 中的 require('puppeteer')（裸模块名）从 cwd/node_modules/ 查找，但 AI 执行命令时 cwd 不可控；require('.agents/...')（相对路径）是相对于 [eval] 虚拟文件解析而非 cwd，必定失败。只有绝对路径能保证一次成功。.env 变量名：脚本只识别 DASHSCOPE_API_KEY，不要写成 API_KEY 或其他变体。仅对未通过的工具提示用户安装，不要重复提醒已安装的工具。如果某项工具第一次检测失败，必须按上述 fallback 步骤二次确认后再做结论，禁止一次失败就判定为未安装。
| 输入类型 | 处理方式 |
|---|---|
| 小红书公开视频链接 | 执行步骤 2 运行脚本 |
| 已有分析稿 / 逐字稿 / Markdown 笔记 | 跳过步骤 2，直接进入步骤 3 |
| 本地视频文件 | 提示用户先通过百炼 / 通义听悟获取逐字稿，再继续 |
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 是否已安装（抽帧失败不影响分析稿生成，但截图功能不可用）视频分析稿的完整结构与字段说明参考：视频分析稿模板 视频理解提示词参考：高质量视频理解提示词
在改写前，必须对分析稿执行以下两项校正，并直接修改分析稿原文：
完成标志：校正完成后，必须在对话中显式输出校正摘要，格式如下：
术语校正：共修正 N 处（列出主要修正项） 证据等级：共标注 N 条关键事实（列出降级项，如有） 如无需修正，输出"术语与证据校正完成，分析稿无需修改"
门禁规则：未输出校正摘要即进入步骤 4 或步骤 5 是流程违规
视频分析稿完成后，必须做一次完整的五维度扫描（主轴、重点、事实、发布目标、内容边界），一次性向用户提出 2 到 5 个最关键问题。
不允许两轮提问：第一轮问主轴、第二轮补事实的做法是错误的。
门禁规则：
提问判断逻辑与问题生成规则参考：内容补充提问机制
用户回答后（或确认无缺口后）才进入步骤 5。
按 知乎图文改写规则 改写，如需贴近作者风格额外参考 个人表达风格。
工作稿允许保留轻度编辑痕迹，不允许在明知缺关键信息的情况下大量写入模糊表述。
工作稿末尾应包含“配图任务定义”表格，列出建议插入的截图及其位置。引用截图时必须使用 截图/ 子目录下的真实文件名，不要使用占位符。文件名格式为 frame_<序号>.jpg（如 frame_001.jpg）。
按 最终发布前检查清单 逐项检查。
有任一一票否决项未通过，则不生成最终版，返回步骤 4 补充信息。
通过全部检查后输出最终版。最终版不得保留任何过程性措辞（"待确认""视频里提到"等）。
图片嵌入格式：最终版中的截图嵌入统一使用 Obsidian wikilink 语法 ![[文件名.jpg]]，不要使用标准 Markdown 的  语法——后者在文件名含空格或特殊字符时 Obsidian 无法正确解析。
最终版生成后、配图生成前，对最终版中每个配图位置引用的截图逐张验证。
执行逻辑：
read_file 查看图片），判断是否适合该配图位置判断维度（按优先级）：
| 维度 | 不合格标准 |
|---|---|
| 内容相关性 | 截图主体内容与该段落要表达的信息不匹配 |
| 关键区域清晰度 | 核心信息区域过小、文字模糊不可读 |
| 干扰信息 | 无关内容占据画面主体，分散注意力 |
| 缩放可读性 | 压缩到知乎正文宽度（≈690px）后关键信息不可辨认 |
注意：
触发条件：最终版已完成，且满足以下任一条件：
不满足以上任一条件，不出图。
配图来源：视频分析稿中的截图候选列表优先；工作稿阶段可基于截图候选和内容信号追加配图任务定义。截图位于输出目录下的 截图/ 子目录，文件名格式为 frame_<序号>.jpg（如 frame_001.jpg）。
配图类型判断、视觉规范、生成步骤与检查规则参考：
配图交付流程：HTML/SVG 代码生成 → Puppeteer 导出为 PNG（参考图片生成规则第三步）→ PNG 插入最终版正文。
Puppeteer 位置：Puppeteer 通过 Skill 的 scripts/package.json 管理，首次使用前需在 scripts/ 目录下执行 npm install。screenshot.js 中引用 Puppeteer 时须以 scripts/ 为工作目录。
配图总量控制：
基于最终版生成一份可直接导入知乎编辑器的 .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）。
xhs_video_to_analysis.py：主脚本，小红书链接 → 视频分析稿（ASR + 视频理解两路并行，完成后按需取帧）md_to_zhihu_docx.py：最终版 .md → 知乎发布版 .docx（移除 frontmatter、转图片语法、中文编号、统一字体）