| 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：前置检查与询问（必须先执行）
在开始任何采集操作之前，必须检查用户是否提供了以下必要信息，缺失时必须主动向用户询问，不得自行假设或跳过：
-
检查抖音来源地址：
- 用户是否提供了博主主页 URL、单条视频 URL、或抖音分享短链？
- 未提供时：向用户询问"请问要采集哪个抖音博主的视频？请提供博主主页链接或视频链接。"
- 提供了分享短链（如
https://v.douyin.com/xxxxx/）时，先用浏览器打开短链，获取跳转后的真实 URL（博主主页或视频详情页）。
-
检查飞书多维表格地址：
- 用户是否提供了飞书多维表格 URL（wiki 链接或 base 链接）？
- 未提供时：向用户询问"请问采集结果要写入哪个飞书多维表格？请提供表格链接。如果不需要写入表格，我可以保存到本地文件。"
- 用户明确表示不用表格 / 保存到本地时：跳过分支，采集完成后将结果保存为本地 JSON 和 CSV 文件（见 Step 4 本地保存分支）。
- 用户提供了表格地址时：继续正常流程，写入飞书表格。
-
确认其他可选参数：
- 视频数量：用户说"最新N条"时只采前N条，未说明时默认最新 5 条。
- 是否提取逐字稿：用户说"只要基础数据"时跳过，未说明时默认提取。
-
信息齐全后再开始：以上必要信息确认齐全后，才进入 Step 1 环境检测。信息不齐全时不得开始采集。
Step 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 登录账号。
-
检测操作系统：Mac 用 mac_computer_use_tool（plane="bu"），Windows 用 computer_use_tool（plane="bu"）。两者代码逻辑完全一致，均为 import seed_browser_use as bu。
Step 2：抖音视频采集
读取 references/douyin.md 获取采集细节。核心步骤：
-
用浏览器打开博主主页，检测是否已登录抖音。
- 未登录时（页面显示登录弹窗、作品列表显示"服务异常"），调用
interaction.request_action（type="browserControl"）请求用户接管完成登录。
- 登录后等待作品列表加载完成。
-
滚动页面加载全部视频，从 DOM 中提取所有视频链接（/video/xxxxx 格式）和基础信息。
- 主页文本中可直接获取每条视频的标题、文案、点赞数。
- 用户指定"最新N条"时，只取前N个。
-
逐个进入视频详情页（https://www.douyin.com/video/xxxxx），提取：
- 评论数、转发数、收藏数（页面互动区数字，顺序：点赞→评论→收藏→转发）
- 发表日期（页面底部"发布时间：YYYY-MM-DD HH:MM"）
- 博主昵称（页面顶部作者信息）
-
汇总为结构化数据列表，每条包含：video_id、url、title、description、likes、comments、shares、publish_date、author_name。
Step 3：逐字稿提取（默认执行）
对每条视频链接调用 web.fetch，抖音页面会返回视频的完整口播逐字稿。
【强制要求】必须获取完整逐字稿，禁止写任何占位符说明（如"完整内容已通过web.fetch获取"）。如果获取失败，该字段留空并标注失败原因，绝不能用占位文字冒充完整内容。
-
调用 web.fetch：首次调用使用 pagination.offset=0，从返回结果中检查 pagination_content 的 end_offset 和 total_length。
- 如果
end_offset < total_length，说明内容被截断，必须继续分页读取：下一次调用设置 pagination.offset = 上一次的 end_offset，重复直到 end_offset >= total_length。
- 将所有分页返回的内容拼接为完整文本。
-
分离逐字稿正文：从完整内容中分离标题/文案部分和逐字稿正文部分（逐字稿正文通常在第一个空行之后）。
-
内容完整性判断（满足任一条件即视为不完整，必须回退）：
- 逐字稿正文长度 < 50 字（短视频口播通常至少几十字）
- 内容在句子中间突然中断（末尾不是句号/问号/感叹号/省略号等结束标点）
- 返回内容中包含"完整内容"、"web.fetch"、"获取"等占位符文字
- web.fetch 调用失败或返回空内容
-
回退路径：内容不完整时，回退到飞书妙记链路：先加载 doubao-video-extract skill，确认脚本路径后运行 python3 scripts/minutes/social_video_to_minutes.py "<url>" --run-lark。
- 此方法会下载视频音频 → 上传飞书妙记 → 转写，耗时较长（每条1-3分钟）。
- 回退仍失败时，逐字稿字段留空，在结果摘要中标注该条逐字稿获取失败。
-
用户明确说"不要逐字稿"时跳过本步，逐字稿字段留空。
Step 3.5：AI生成选题方向与主题总结（默认执行，需目标表格含对应字段）
基于每条视频的标题 + 介绍 + 逐字稿，由AI批量生成两个扩展字段：
-
选题方向（多选）：
- 先用
lark-cli base +field-list 读取目标表格"选题方向"字段的已有选项列表。
- 必须从已有选项中选择1-3个最贴合的标签，禁止自行新增选项。
- 选择标准：视频核心主题落在哪个领域，优先选最主要的1个，次选相关的1-2个。
- 若目标表格无"选题方向"字段，跳过本字段。
-
主题总结（text）：
- 用一句话（30-80字）概括视频核心观点或内容主旨。
- 要求：精准提炼本质，不重复标题原文，不写"这条视频讲了…"这类废话开头。
- 若视频是纯分享/开箱/生活类，概括其核心信息或感受。
-
执行方式：
- 将所有视频的标题、介绍、逐字稿整理为结构化列表，一次性交给AI批量生成，避免逐条调用浪费上下文。
- 逐字稿截断策略：短视频（逐字稿<1500字）使用完整内容；长视频（逐字稿>1500字）可截断至前2000字（而非1000字），确保涵盖视频核心观点。若视频内容在开头铺垫较多，可适当增加截断长度。
- 输出格式为 JSON：
[{"video_id":"xxx","选题方向":["标签A","标签B"],"主题总结":"..."},...]
- 生成后与原始数据合并，准备写入。
用户说"只要基础数据"或目标表格不含这两个字段时，跳过本步。
Step 4：结果写入（飞书表格 / 本地文件）
根据 Step 0 中用户的选择，分为两个分支：
分支 A：写入飞书多维表格（用户提供了表格地址时）
读取 references/lark-write.md 获取写入细节。核心步骤：
-
解析表格链接：lark-cli base +url-resolve --url "<表格URL>" --as user，获取 base_token、table_id、view_id。
-
对比字段：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生成时严格从已有选项中选择。
-
增量去重：查询表格中已有的"视频链接"字段值列表，与本次采集的视频链接对比，只写入不存在的新记录。
- 用
lark-cli base +record-list 或 +record-search 获取已有记录。
- 用户明确要求"全量覆盖"时跳过去重，直接追加。
-
批量写入：用 lark-cli base +record-batch-create 一次性写入新记录（单批最多200条）。
- 日期字段用
"YYYY-MM-DD HH:MM" 字符串格式，或毫秒时间戳。
- 单选字段（账号名称）用
["选项名"] 数组格式。
- 写入后返回 record_id_list，确认写入成功数量。
-
数据质量验证（写入后必须执行）：
- 用
lark-cli base +record-list 读取本次新写入的记录，检查以下质量问题：
- 占位符检查：逐字稿字段中是否包含"完整内容"、"web.fetch"、"已通过"等占位符文字（如有说明写入时内容不完整，必须重新获取并更新）
- 长度检查：逐字稿字段是否过短（<50字且非纯音乐/无口播视频）、标题/介绍字段是否为空
- 关键字段检查：视频链接、发表日期、账号名称是否正确写入
- 发现质量问题时，立即重新获取该条数据并用
+record-batch-update 更新对应记录，直到验证通过。
分支 B：保存到本地文件（用户明确表示不用表格时）
用户在 Step 0 中明确表示不用飞书表格时，将采集结果保存为本地文件，采用每批单独目录 + 每个视频单独 Markdown 文件的结构：
-
批次目录：在当前工作目录下创建 douyin_data/ 文件夹，每批采集单独建一个子目录。
- 目录命名：
{博主昵称}_{采集日期YYYYMMDD}_{视频数量}条/，如 瑶瑶_20260827_50条/
- 博主昵称含特殊字符时，替换为下划线或去掉特殊字符。
-
每个视频单独 Markdown 文件：目录下为每条视频创建一个 .md 文件。
-
汇总文件（可选）：在批次目录下同时保存一个汇总的 _all.json 文件，包含所有视频的结构化数据，便于后续程序处理。
- JSON 格式为数组，每条包含所有字段（video_id、url、账号名称、标题、介绍、逐字稿、点赞、评论、转发、发表日期、选题方向、主题总结）。
-
数据质量验证（保存后必须执行）：
- 检查批次目录下 Markdown 文件数量是否与预期采集数量一致。
- 抽样读取2-3个 Markdown 文件，检查：
- 占位符检查：逐字稿部分是否包含"完整内容"、"web.fetch"、"已通过"等占位符文字
- 长度检查：逐字稿是否过短（<50字且非纯音乐视频）、标题/介绍是否为空
- 格式检查：Markdown 结构是否完整（包含基本信息、介绍、选题方向、主题总结、逐字稿等章节）
- 发现问题时，重新获取该条数据并更新对应 Markdown 文件，直到验证通过。
-
交付文件：用 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 格式
