douyin-transcript-exporter

name	douyin-transcript-exporter
description	必须在豆包工作中执行，抓取抖音博主主页或视频的标题、文案、完整逐字稿及互动数据；可选写入飞书多维表格，或保存为本地文件。当用户要采集或导出抖音视频数据、逐字稿时使用。

抖音逐字稿导出

执行环境

必须在豆包工作中执行，并使用其内置的逐字稿获取能力。需要采集抖音主页公开信息时，可通过豆包工作的内置浏览器登录抖音；建议使用专门的小号。该登录仅用于读取公开主页的视频信息，不用于下载视频，也不影响逐字稿获取。

输入

输入项	必填	说明
抖音博主主页 URL 或 单条视频 URL	是	博主主页 https://www.douyin.com/user/xxxxx，或单条视频 https://www.douyin.com/video/xxxxx，或抖音分享短链
飞书多维表格 URL	否	wiki 链接或 base 链接，含 table 参数。用户未提供时必须主动询问；用户明确表示不用表格时，保存到本地 JSON/CSV 文件
视频数量	否	默认最新 5 条；用户说"最新N条"时只采前N条
是否提取逐字稿	否	默认提取；用户说"只要基础数据"时跳过

采集字段（标准9列 + AI扩展2列）

基础采集字段（9列，从抖音页面直接抓取）： 账号名称（单选）、标题、介绍、逐字稿、点赞、评论、转发、发表日期、视频链接

AI扩展字段（2列，基于逐字稿由AI生成）：

• 选题方向（多选 select）：从预设标签中选择1-3个，如 AI协作方法、AI入门教程、企业AI落地、认知思维、提示词工程、个人成长、效率工具、数字化转型、学习方法、AI管理 等。若目标表格已有该字段的选项，必须从已有选项中选择，不自行新增。
• 主题总结（text）：用一句话（30-80字）概括视频核心观点或内容主旨，要求精准、不重复标题、提炼本质。

用户说"只要基础数据"时跳过AI扩展字段；目标表格不存在这两个字段时跳过（不自动创建扩展字段，除非用户明确要求）。

执行流程

Step 0：前置检查与询问（必须先执行）

在开始任何采集操作之前，必须检查用户是否提供了以下必要信息，缺失时必须主动向用户询问，不得自行假设或跳过：

1. 检查抖音来源地址：

   • 用户是否提供了博主主页 URL、单条视频 URL、或抖音分享短链？
   • 未提供时：向用户询问"请问要采集哪个抖音博主的视频？请提供博主主页链接或视频链接。"
   • 提供了分享短链（如 https://v.douyin.com/xxxxx/）时，先用浏览器打开短链，获取跳转后的真实 URL（博主主页或视频详情页）。

2. 检查飞书多维表格地址：

   • 用户是否提供了飞书多维表格 URL（wiki 链接或 base 链接）？
   • 未提供时：向用户询问"请问采集结果要写入哪个飞书多维表格？请提供表格链接。如果不需要写入表格，我可以保存到本地文件。"
   • 用户明确表示不用表格 / 保存到本地时：跳过分支，采集完成后将结果保存为本地 JSON 和 CSV 文件（见 Step 4 本地保存分支）。
   • 用户提供了表格地址时：继续正常流程，写入飞书表格。

3. 确认其他可选参数：

   • 视频数量：用户说"最新N条"时只采前N条，未说明时默认最新 5 条。
   • 是否提取逐字稿：用户说"只要基础数据"时跳过，未说明时默认提取。

4. 信息齐全后再开始：以上必要信息确认齐全后，才进入 Step 1 环境检测。信息不齐全时不得开始采集。

Step 1：环境检测

1. 检测 lark-cli 身份：运行 lark-cli api GET /open-apis/authen/v1/user_info --as user，确认登录的是用户本人账号（而非沙箱自带的"来点羊蝎子"等测试账号）。

   • 如果沙箱 lark-cli 无权限，尝试系统路径的 lark-cli：Mac 上 /opt/homebrew/bin/lark-cli，Windows 上 where lark-cli 查找。
   • 两种身份都无权限时，告知用户需要先在飞书文档中授权或切换 lark-cli 登录账号。

2. 检测操作系统：Mac 用 mac_computer_use_tool（plane="bu"），Windows 用 computer_use_tool（plane="bu"）。两者代码逻辑完全一致，均为 import seed_browser_use as bu。

Step 2：抖音视频采集

读取 references/douyin.md 获取采集细节。核心步骤：

1. 用浏览器打开博主主页，检测是否已登录抖音。

   • 未登录时（页面显示登录弹窗、作品列表显示"服务异常"），调用 interaction.request_action（type="browserControl"）请求用户接管完成登录。
   • 登录后等待作品列表加载完成。

2. 滚动页面加载全部视频，从 DOM 中提取所有视频链接（/video/xxxxx 格式）和基础信息。

   • 主页文本中可直接获取每条视频的标题、文案、点赞数。
   • 用户指定"最新N条"时，只取前N个。

3. 逐个进入视频详情页（https://www.douyin.com/video/xxxxx），提取：

   • 评论数、转发数、收藏数（页面互动区数字，顺序：点赞→评论→收藏→转发）
   • 发表日期（页面底部"发布时间：YYYY-MM-DD HH:MM"）
   • 博主昵称（页面顶部作者信息）

4. 汇总为结构化数据列表，每条包含：video_id、url、title、description、likes、comments、shares、publish_date、author_name。

Step 3：逐字稿提取（默认执行）

对每条视频链接调用 web.fetch，抖音页面会返回视频的完整口播逐字稿。

【强制要求】必须获取完整逐字稿，禁止写任何占位符说明（如"完整内容已通过web.fetch获取"）。如果获取失败，该字段留空并标注失败原因，绝不能用占位文字冒充完整内容。

1. 调用 web.fetch：首次调用使用 pagination.offset=0，从返回结果中检查 pagination_content 的 end_offset 和 total_length。

   • 如果 end_offset < total_length，说明内容被截断，必须继续分页读取：下一次调用设置 pagination.offset = 上一次的 end_offset，重复直到 end_offset >= total_length。
   • 将所有分页返回的内容拼接为完整文本。

2. 分离逐字稿正文：从完整内容中分离标题/文案部分和逐字稿正文部分（逐字稿正文通常在第一个空行之后）。

3. 内容完整性判断（满足任一条件即视为不完整，必须回退）：

   • 逐字稿正文长度 < 50 字（短视频口播通常至少几十字）
   • 内容在句子中间突然中断（末尾不是句号/问号/感叹号/省略号等结束标点）
   • 返回内容中包含"完整内容"、"web.fetch"、"获取"等占位符文字
   • web.fetch 调用失败或返回空内容

4. 回退路径：内容不完整时，回退到飞书妙记链路：先加载 doubao-video-extract skill，确认脚本路径后运行 python3 scripts/minutes/social_video_to_minutes.py "<url>" --run-lark。

   • 此方法会下载视频音频 → 上传飞书妙记 → 转写，耗时较长（每条1-3分钟）。
   • 回退仍失败时，逐字稿字段留空，在结果摘要中标注该条逐字稿获取失败。

5. 用户明确说"不要逐字稿"时跳过本步，逐字稿字段留空。

Step 3.5：AI生成选题方向与主题总结（默认执行，需目标表格含对应字段）

基于每条视频的标题 + 介绍 + 逐字稿，由AI批量生成两个扩展字段：

1. 选题方向（多选）：

   • 先用 lark-cli base +field-list 读取目标表格"选题方向"字段的已有选项列表。
   • 必须从已有选项中选择1-3个最贴合的标签，禁止自行新增选项。
   • 选择标准：视频核心主题落在哪个领域，优先选最主要的1个，次选相关的1-2个。
   • 若目标表格无"选题方向"字段，跳过本字段。

2. 主题总结（text）：

   • 用一句话（30-80字）概括视频核心观点或内容主旨。
   • 要求：精准提炼本质，不重复标题原文，不写"这条视频讲了…"这类废话开头。
   • 若视频是纯分享/开箱/生活类，概括其核心信息或感受。

3. 执行方式：

   • 将所有视频的标题、介绍、逐字稿整理为结构化列表，一次性交给AI批量生成，避免逐条调用浪费上下文。
   • 逐字稿截断策略：短视频（逐字稿<1500字）使用完整内容；长视频（逐字稿>1500字）可截断至前2000字（而非1000字），确保涵盖视频核心观点。若视频内容在开头铺垫较多，可适当增加截断长度。
   • 输出格式为 JSON：[{"video_id":"xxx","选题方向":["标签A","标签B"],"主题总结":"..."},...]
   • 生成后与原始数据合并，准备写入。

用户说"只要基础数据"或目标表格不含这两个字段时，跳过本步。

Step 4：结果写入（飞书表格 / 本地文件）

根据 Step 0 中用户的选择，分为两个分支：

分支 A：写入飞书多维表格（用户提供了表格地址时）

读取 references/lark-write.md 获取写入细节。核心步骤：

1. 解析表格链接：lark-cli base +url-resolve --url "<表格URL>" --as user，获取 base_token、table_id、view_id。

   • wiki 链接也可直接解析，无需手动转换。

2. 对比字段：lark-cli base +field-list --base-token <token> --table-id <id> --as user，检查目标表格是否包含全部基础9字段。

   • 缺失基础字段自动创建：账号名称用 select（单选，multiple=false），标题/介绍/逐字稿/视频链接用 text，点赞/评论/转发用 number，发表日期用 datetime。
   • 批量创建字段用数组形式：--json '[{"name":"xxx","type":"xxx"},...]'。
   • AI扩展字段（选题方向、主题总结）：若目标表格已存在则纳入写入；若不存在则不自动创建（除非用户明确要求），直接跳过这两个字段的写入。
   • 若"选题方向"字段存在，必须先读取其已有选项列表，AI生成时严格从已有选项中选择。

3. 增量去重：查询表格中已有的"视频链接"字段值列表，与本次采集的视频链接对比，只写入不存在的新记录。

   • 用 lark-cli base +record-list 或 +record-search 获取已有记录。
   • 用户明确要求"全量覆盖"时跳过去重，直接追加。

4. 批量写入：用 lark-cli base +record-batch-create 一次性写入新记录（单批最多200条）。

   • 日期字段用 "YYYY-MM-DD HH:MM" 字符串格式，或毫秒时间戳。
   • 单选字段（账号名称）用 ["选项名"] 数组格式。
   • 写入后返回 record_id_list，确认写入成功数量。

5. 数据质量验证（写入后必须执行）：

   • 用 lark-cli base +record-list 读取本次新写入的记录，检查以下质量问题：
     • 占位符检查：逐字稿字段中是否包含"完整内容"、"web.fetch"、"已通过"等占位符文字（如有说明写入时内容不完整，必须重新获取并更新）
     • 长度检查：逐字稿字段是否过短（<50字且非纯音乐/无口播视频）、标题/介绍字段是否为空
     • 关键字段检查：视频链接、发表日期、账号名称是否正确写入
   • 发现质量问题时，立即重新获取该条数据并用 +record-batch-update 更新对应记录，直到验证通过。

分支 B：保存到本地文件（用户明确表示不用表格时）

用户在 Step 0 中明确表示不用飞书表格时，将采集结果保存为本地文件，采用每批单独目录 + 每个视频单独 Markdown 文件的结构：

1. 批次目录：在当前工作目录下创建 douyin_data/ 文件夹，每批采集单独建一个子目录。

   • 目录命名：{博主昵称}_{采集日期YYYYMMDD}_{视频数量}条/，如 瑶瑶_20260827_50条/
   • 博主昵称含特殊字符时，替换为下划线或去掉特殊字符。

2. 每个视频单独 Markdown 文件：目录下为每条视频创建一个 .md 文件。

   • 文件命名：{序号}_{视频ID}.md，如 01_7655189977860862854.md、02_7654993145986808761.md
   • 序号按采集顺序（最新在前）从 01 开始，不足10条用1位，超过99条用3位。
   • Markdown 文件内容格式：

     # {视频标题}
     
     ## 基本信息
     - **账号名称**：{博主昵称}
     - **发表日期**：{YYYY-MM-DD HH:MM}
     - **视频链接**：{url}
     - **点赞**：{点赞数}
     - **评论**：{评论数}
     - **转发**：{转发数}
     
     ## 介绍/文案
     {视频介绍或文案全文}
     
     ## 选题方向
     {标签1}、{标签2}、{标签3}
     
     ## 主题总结
     {一句话主题总结}
     
     ## 逐字稿
     {完整口播逐字稿全文}
     

3. 汇总文件（可选）：在批次目录下同时保存一个汇总的 _all.json 文件，包含所有视频的结构化数据，便于后续程序处理。

   • JSON 格式为数组，每条包含所有字段（video_id、url、账号名称、标题、介绍、逐字稿、点赞、评论、转发、发表日期、选题方向、主题总结）。

4. 数据质量验证（保存后必须执行）：

   • 检查批次目录下 Markdown 文件数量是否与预期采集数量一致。
   • 抽样读取2-3个 Markdown 文件，检查：
     • 占位符检查：逐字稿部分是否包含"完整内容"、"web.fetch"、"已通过"等占位符文字
     • 长度检查：逐字稿是否过短（<50字且非纯音乐视频）、标题/介绍是否为空
     • 格式检查：Markdown 结构是否完整（包含基本信息、介绍、选题方向、主题总结、逐字稿等章节）
   • 发现问题时，重新获取该条数据并更新对应 Markdown 文件，直到验证通过。

5. 交付文件：用 present_files 工具将批次目录交付给用户，说明目录路径、视频数量、文件结构（每个视频一个 Markdown 文件）。

结果摘要（两个分支通用）

向用户报告本次采集结果：

• 采集视频总数
• 写入方式：飞书表格（给出表格链接）/ 本地文件（给出文件路径）
• 飞书表格分支：新增写入数、跳过重复数
• 逐字稿获取失败数（如有）
• 数据质量验证结果（通过 / 已修复的问题数）

关键注意事项

• 前置检查（必须先执行）：开头必须检查用户是否提供了抖音地址（博主主页或视频链接）和飞书表格地址。抖音地址缺失时必须询问；表格地址缺失时必须询问，用户明确表示不用表格时保存到本地（每批单独目录，每个视频一个 Markdown 文件）。信息不齐全时不得开始采集。
• 抖音分享短链处理：用户提供 https://v.douyin.com/xxxxx/ 短链时，先用浏览器打开获取跳转后的真实 URL，再进行采集。
• 抖音反爬：必须通过真实浏览器采集，禁止用 curl/requests 直接请求抖音 API。登录态是获取完整数据的前提。
• lark-cli 路径：沙箱环境的 lark-cli 可能登录的是测试账号，优先使用用户系统安装的 lark-cli。Mac 默认路径 /opt/homebrew/bin/lark-cli。
• 主字段限制：飞书多维表格的第一个字段（主字段）不能删除，只能重命名。如果目标表格的主字段是默认的"文本"且为空，应将其重命名为"标题"而非删除。
• 字段类型转换：text 转 select 等类型转换可能需要先确认数据兼容性，转换后原有值会自动映射为选项（如果匹配）。
• 逐字稿完整性（最高优先级）：单条逐字稿可能很长（数千字），飞书 text 字段支持大文本，无需拆分。必须确保写入的是完整逐字稿，禁止写任何占位符说明（如"完整内容已通过web.fetch获取"）。 web.fetch 返回内容被截断时必须分页读取直到完整。
• 数据质量验证：写入后必须检查是否有占位符、逐字稿长度是否合理、关键字段是否为空，发现问题立即修复。
• AI扩展字段生成：选题方向必须从目标表格已有选项中选择，禁止自行新增选项；主题总结控制在30-80字，提炼本质不重复标题。批量生成时短视频用完整逐字稿，长视频可截断至前2000字（而非1000字）以确保涵盖核心观点。

参考文档

• references/douyin.md：抖音采集的具体选择器、数据格式、登录处理、常见异常
• references/lark-write.md：飞书表格字段创建、记录写入、去重逻辑、CellValue 格式