网页视频转录为 DOCX 文档

概述

使用本技能附带的脚本，完成媒体提取、下载、离线转录，并生成 DOCX 格式输出。

优先使用已封装好的确定性脚本，而非自行编写新代码。

在本技能内部构造文件路径时，请统一使用 {baseDir}，以确保指令可在不同 agent 和 marketplace 间保持可移植性。

运行环境

• 需 Python 3 及本地文件系统访问权限。
• 首次运行需网络连接，用于下载模型及获取网页或媒体 URL。
• 仅在从网页中提取媒体资源时，才需要本地安装 Chrome 或 Edge 浏览器。

快速开始

1. 在目标环境中首次运行：python {baseDir}/scripts/bootstrap_env.py。
2. 对于通用网页 URL，运行：python {baseDir}/scripts/pipeline_web_to_docx.py --output-dir 。
3. 对于直接媒体 URL，先运行：python {baseDir}/scripts/download_url.py
   ，再运行：python {baseDir}/scripts/transcribe_sensevoice.py --input --output-txt --output-docx 。
4. 对于本地媒体文件，直接运行：python {baseDir}/scripts/transcribe_sensevoice.py --input --output-txt --output-docx 。
5. 若用户要求的是润色后的可读版本（而非原始转录稿），请先阅读 references/cleanup-guidelines.md，生成一份精修后的 .txt 文件，再通过 python {baseDir}/scripts/transcript_to_docx.py 渲染为 DOCX。

示例请求

• “请将该网页视频中的中文音频转录为 Word 文档。”
• “将这个 MP4 文件转为文字稿，再整理为分章节的阅读笔记。”
• “该网页下载媒体资源时需携带 Referer 请求头。请提取媒体流并转换为 DOCX。”

工作流程

1. 判定资源来源类型

• 通用网页 URL：优先使用 python {baseDir}/scripts/pipeline_web_to_docx.py。若页面特别难以处理且为今日头条页面，可备选使用站点专用回退脚本：python {baseDir}/scripts/pipeline_toutiao_to_docx.py 和 python {baseDir}/scripts/extract_toutiao_media.py。
• 直接媒体 URL：使用 python {baseDir}/scripts/download_url.py 下载，随后进行转录。
• 本地文件：直接转录。

2. 保留原始输出

• 将原始转录内容单独保存为 .txt 文件。
• 若生成了清洗后或分章节的版本，请另存为独立文件。
• 除非用户明确要求，否则不得覆盖原始转录文件。

3. 优先选用音频流

• 若网页暴露了独立音频流，应优先下载该音频流，而非完整视频流。
• 若网页仅提供视频流，则由 ffmpeg 在转录过程中解码音频。
• 若网页提供 HLS 或 DASH 播放清单（manifest），应优先通过附带的下载器或 pipeline 获取，而非直接发起原始 HTTP GET 请求。

4. 保守地进行润色

• 严格保留原意。
• 修正明显的语音识别（ASR）错误、标点符号、段落划分、标题层级及章节边界。
• 不得虚构原文未提及的引述内容或历史主张。
• 若某段内容噪声过大、无法可靠还原，则保持中立表述，切勿捏造细节。

5. 严守能力边界

• 仅下载用户直接提供的 URL，或由提取器从目标页面捕获的 URL。
• 不得请求、存储或外传 cookies、访问令牌或账户凭据。
• 不得尝试绕过 DRM、登录墙或地理限制机制。
• 若页面依赖未预置的认证态浏览器上下文，请明确说明，并止步于当前支持的能力边界。

6. 交付成果渲染

• 通用 TXT 到 DOCX 的渲染，请使用：python {baseDir}/scripts/transcript_to_docx.py。
• 原始转录稿用于审计追溯，精修稿用于提升阅读体验。

脚本说明

• scripts/bootstrap_env.py 安装或验证本技能所依赖的 Python 包。
• scripts/extract_web_media.py 在真实浏览器中打开通用网页，捕获可能的媒体 URL 及常用下载请求头，并输出 JSON 格式清单（manifest）。
• scripts/extract_toutiao_media.py 在真实浏览器中打开今日头条网页，捕获音视频 URL，并输出与通用提取器兼容的同构 JSON 清单（manifest）。
• scripts/download_url.py 以稳定 User-Agent 下载指定媒体 URL，支持可选请求头及 HLS/DASH 协议处理。
• scripts/transcribe_sensevoice.py 按需下载 SenseVoice 模型，对媒体文件分段，执行离线 ASR，并输出 TXT 及可选 DOCX 文件。
• scripts/transcript_to_docx.py 将带时间戳的转录稿或分章节笔记渲染为 Word 文档。
• scripts/pipeline_web_to_docx.py 运行通用端到端流水线：提取 → 下载 → 转录 → 渲染。
• scripts/pipeline_toutiao_to_docx.py 针对今日头条场景的专用端到端流水线，适用于通用提取器不适用的情形。

参考资料

• 阅读 references/workflow.md，了解依赖项要求、命令示例、输出目录结构及常见问题排查方法。
• 在将含噪转录稿润色为分章节阅读稿前，请务必阅读 references/cleanup-guidelines.md。
• 准备 marketplace 元数据、标签、版本号或 ClawHub 发布命令时，请参考 references/publishing.md。

校验

• 在全新环境中首次使用前，请运行 python {baseDir}/scripts/bootstrap_env.py。
• 使用 skill-creator/scripts/quick_validate.py 对技能文件夹进行校验。
• 修改脚本后，建议优先测试 --help 输出及一条典型成功路径（happy path）。
• 若网页提取失败，可通过浏览器开发者工具获取直接媒体 URL，随后交由下载器 + 转录器继续处理。
• 不承诺支持 DRM 加密流、需认证 Cookie 的资源，或仅提供加密 EME 播放的网站。