Douyin Transcript Exporter

抖音逐字稿导出

执行原则

在豆包工作中执行：主页和详情页使用内置浏览器，逐字稿可使用其内置 web.fetch。不要求用户先配置可选依赖；某条路径不可用时继续其他路径并交付已有结果。

默认连续完成采集、保存和摘要，不逐条询问“是否继续”。普通校验、重试、落盘和进度告知不构成审批。已有清晰指令和授权直接复用；用户禁止下载、上传或写表时遵守该限制。

Step 0：确定来源、输出和参数

• 来源：接受主页、单条视频或分享短链。缺少来源且无法从上下文确定时询问一次；短链先用浏览器打开取得真实地址。
• 输出：已有表格链接直接使用；说“本地保存”直接走本地。完全未说明时只询问一次“保存本地，还是写入飞书？”；用户说“跳过引导 / 直接开始”但未提供表格时，简短说明将先保存本地并开始，不再追问表格。
• 数量：主页默认最新 5 条，用户给定数量或 Top 区间时按其要求；单条链接只处理该条。
• 逐字稿和 AI 字段：默认提取逐字稿并生成选题方向、主题总结；“只要基础数据”时跳过这三项。只说“不要逐字稿”时仍可根据标题和介绍生成 AI 字段，并注明依据。
• 节奏：未指定时直接采用稳妥模式，不强制用户先选；可按要求改为快速模式或自定义间隔。模式参数只在下一节定义。

采集节奏与中断

间隔是任务参数，不保证账号安全或固定耗时。等待期间保留进度并简短告知，不要求用户催办；不把长休息塞入短超时 cell。优先使用环境的等待/恢复能力；若环境无法继续等待，保存恢复点并如实说明需要恢复任务，不假称后台仍运行。

• 登录、滑块、点选或验证码出现时暂停相关浏览器操作，请用户接管手动完成；交回后重新读取页面并恢复，不尝试绕过。
• 对所有模式，15 分钟内连续两次验证先暂停 15 分钟；当日累计三次则保存进度、停止当日浏览器采集并交付缓存结果。已有缓存的整理和写入可以继续。计数按账号/日期保存在进度中，不因换批清零；这是本 Skill 的暂停策略，不是平台判定标准。
• 普通空白、加载失败或详情页错位只重试一次；仍失败记录原因并继续其他视频。重复 video_id 直接去重，不反复访问。
• 每完成 10 条或遇到需要用户接管的事件汇报进度；结束时报告不足 10 条的最后一批，不等待用户回复进度消息。

Step 0.5：飞书准备（按需）

仅写入飞书时检测 lark-cli 是否为用户本人身份，并解析目标表。已有表格直接用，不重复介绍模板。只有用户需要建表时提供默认模板：可在用户指定的 Base 内新建数据表，或新建 Base；详见 飞书写入。缺少目标且用户要跳过引导则先保存本地。

默认 11 字段：标题（text，主字段）、账号名称（text）、介绍（text）、逐字稿（text）、点赞/评论/转发（number）、发表日期（datetime）、视频链接（text）、选题方向（多选 select）、主题总结（text）。模板标签可按内容选择，已有表格的标签不自行新增。已有空主字段可重命名，不删除有数据的字段；不自动转换已有非空列的类型。

本地分支不检查飞书登录或字段。飞书权限缺失时保存本地结果，简短说明写入受阻；用户已指定写表但暂时失败时，仍保留该输出目标以便恢复，不能把本地缓存当作飞书已交付。

Step 1：选定视频

使用内置浏览器（Mac：mac_computer_use_tool，Windows：computer_use_tool，plane="bu"、seed_browser_use）。真实工具以当前环境暴露的接口为准；不使用 curl/requests 直接请求抖音 API。具体页面读取见 抖音参考。

• 单条视频：直接打开详情页，不扫描主页。
• 最新 N 条：优先使用页面提供的最新排序，按真实发布日期确定顺序，排除旧置顶视频干扰。仅加载足以确定 N 条的作品；日期或顺序无法确认时标注“当前页面顺序的 N 条”，不冒充最新排名。
• Top N / Top 区间：才扫描全部作品并按点赞排序，将 video_id/url/title/likes 与采集时间、扫描是否完整落盘。未扫完时明确为“已加载作品中的 Top N”。后续批次复用该快照；用户要求刷新才重扫。
• 按 video_id 规范化链接并去重；只处理当前作者作品，剔除推荐视频。列表和滚动应边读取边累计，不能只在最后读取可能已被虚拟列表移除的卡片。

Step 2：逐条采集并立即缓存

每条读取账号名称、标题、介绍、点赞、评论、转发、发表日期、视频链接；收藏可额外保存，不加入默认 9 列。互动数字带“万”时换算整数；无法获取的值留空并记录缺失，不伪造为 0。

每条完成后立即原子保存完整结果缓存与进度，按“读取 → 逐字稿 → 缓存 → 输出”连续执行。飞书可积累小批量提交（如每 10 条，接口单批最多 200 条），不等全任务完成才保存。

• 状态：pending（未采）→ cached（结果已落盘）→ done（目标输出已确认）；采集、转写或输出失败记 failed，保留缓存和失败环节。
• transcript_status 独立记录 success / failed / skipped / not_applicable；基础数据已交付但逐字稿失败时保持失败状态，续跑只修复缺失部分。
• 进度记录 author_key（优先作者 ID）、本轮 target_ids、采集模式/排序快照、output_key（表格坐标或本地批次路径）、每条 result_path 与 record_id/file_path。昵称只用于展示，不作为唯一身份。
• 续跑合并新增目标，不清空历史进度。已有可信成功输出且目标未变时跳过；目标变更或本地输出丢失时从缓存补交，不重新浏览视频。飞书写入状态不明时先按视频 ID 查已有记录，再决定新增或更新。
• 采集失败本轮最多重试一次；输出失败先重写缓存结果一次，不重新采集。仍失败记原因后继续。更多状态示例见 断点续采。

Step 3：获取逐字稿

用户要求跳过或已确认无口播时记录相应状态，不触发转写。获取失败不等于无口播。

DOM → web.fetch → 妙记

1. DOM 候选：详情页确实展示完整字幕/转录文本时读取。视频介绍、章节要点、当前播放帧的几行字幕都不是完整逐字稿；页面未提供完整转录就直接进入 web.fetch，不为了 DOM 路径播放完整视频、循环截图或自动扩展 OCR。
2. web.fetch：读取其提供的转录正文；按返回的实际分页结构继续到完整。只有确实返回分页字段时才使用 offset。分页无进展、重复页或到达本轮调用预算时记失败，不能无限读取。按实际标题/转录标记分离正文，不固定以第一个空行切割。
3. 校验一次：结合字幕/转录来源、分页状态和正文判断完整性。空结果、读取失败、明确截断、整段只有“完整内容已通过web.fetch获取”等占位说明才判失败。短口播、无结尾标点只作复核信号；正常正文含“获取”“完整内容”“web.fetch”等词不构成失败。无需为此逐条询问用户。
4. 妙记回退（可选依赖）：网页确实失败后，汇总本任务按 video_id 去重的待回退列表。整批 1–3 条直接执行，不另设首次启用审批；整批超过 3 条先一次确认整批数量和范围，已有对应批准直接复用，不拆批规避确认。普通任务在本轮网页读取结束后统一计数；用户已批准 N 条回退时可按批准范围连续处理。
   • 首次使用该路径时用一句话说明“将下载这 N 条视频音频并上传你的飞书妙记转写”，无需等待小批量的额外回复。用户禁止下载、上传或关闭回退时跳过；即使最终输出本地，妙记路径仍会上传音频。
   • 检查 doubao-video-extract 的说明、scripts/minutes/social_video_to_minutes.py 是否存在、是否支持当前抖音链接，并确认已有本人妙记授权。这些检查自动进行，不要求用户逐项批准。本仓库不附带该依赖；不支持抖音链接时不盲跑、不假称支持。
   • 依赖支持且授权可用时，在其目录运行 python3 scripts/minutes/social_video_to_minutes.py "<url>" --run-lark；按照依赖支持的方式取得真实转写结果。每条最多执行一次妙记回退。依赖缺失、链接不支持、授权不可用或失败时保留基础数据、逐字稿留空并注明原因，继续交付其他条目。

记录 transcript_source（dom / web_fetch / feishu_minutes，未成功时为 null）与 transcript_status 到本地缓存，无需为此强制增加飞书字段。回退成功后更新同一视频的缓存和目标输出，不重复新增。

Step 3.5：AI 扩展字段

• 本地分支按内容生成 1–3 个选题标签和 30–80 字主题总结，不调用飞书命令。
• 飞书分支仅写入目标表已有的扩展字段：选题方向从已有选项中选；不存在时跳过，除非用户要求创建。
• 批量生成并按 video_id 合并。短视频使用完整正文；长内容可分段提炼，避免只读开头却声称概括全文。逐字稿失败但标题/介绍可用时标注摘要依据，不能编造口播内容。

Step 4：输出和验收

飞书

按 飞书参考 解析链接、读字段，最初一次读取需用的视频 ID 和记录 ID 映射。补齐必要基础字段，复用目标已有数据类型；不自动删除字段或旧记录。

按当前博主的标准视频 URL/video_id 去重，已有且完整记录跳过；补齐失败逐字稿或用户要求刷新时更新同一 record_id，新视频才新增。“全量覆盖”按视频 ID 更新加新增实现，保留本轮未采到的记录，不删后重建、不重复追加。获取失败的空值不覆盖已有有效逐字稿，用户明确清空的字段除外。

写前用缓存完成占位说明/类型/链接检查一次，写后复用返回结果确认成功；无需每条全表重读。返回不足以确认更新成功或批次状态不明时，按实际写入记录统一读回一次。临时延迟可在短暂等待后复查一次，仍不明记待核实，不盲目重复新增。质量修复最多一次，失败时带原因交付。成功记录 record_id，再更新进度。

本地

保存为 douyin_data/{安全昵称或作者ID}_{日期}_{批次标识}/，同一任务续跑复用原目录，不同任务避免同日重名覆盖。每视频 {序号至少两位}_{video_id}.md，包括基本信息、介绍、选题方向、主题总结、逐字稿；跳过的 AI 字段可不输出对应章节。完整结构和示例见 本地保存。

_all.json 为必需汇总，保存本批全部结果与状态，飞书受阻时也保存本地缓存。成功保存和一次本地读回后才标记输出完成；无口播、主动跳过和获取失败分别注明，不能互相替代。用 present_files 交付；工具不支持目录时打包后交付或给出实际可用的文件路径，不因此重采。

摘要

报告实际完成/失败/跳过数，飞书新增/更新/重复跳过数或本地路径，逐字稿失败原因与待恢复项。已成功的部分先交付，不因可选依赖或少数空字段阻塞全任务。

Step 5：数据洞察

默认按 分析参考 对当前博主全部已采集记录输出四项摘要：主题表现、评论/转发相对点赞、发布时间分布、主题聚类。用户只要导出或不分析时跳过。按视频 ID 去重并排除其他作者，优先复用本轮数据，不重复下载已读表格。

表格数据不可读时用本地完整缓存；主页点赞排序缓存只能支撑有限主题表现分析，不能替代互动数、日期或逐字稿。字段不足的模块标注范围或跳过，不向用户追问补齐才能交付。样本少时注明有效样本数，结论与真实统计同时输出。

参考文档

• 抖音采集：页面结构、模式引用、排序缓存、断点续采、逐字稿路径。
• 飞书与本地输出：建表、字段、分页、增量更新和保存示例。
• 分析口径：四项分析和缺失数据处理。