name: douyin-favorites-to-knowledge version: 2.3.0 description: 将用户已授权账号中的抖音视频收藏或用户明确指定的喜欢列表配置并同步到本地 Markdown 或 Obsidian 知识库；默认收藏，只有用户明确说喜欢/点赞才切换来源。首次明确选择推荐的 SiliconFlow转录、本地 Whisper 或不转录。不得绕过登录、访问他人账号或泄露 Cookie 与私密数据。

抖音视频收藏转本地知识库

优先使用单入口流程。不要先向用户解释 schema、模式、provider 或 adapter。

首次使用

先检查命令是否存在：

douyin-favorites-knowledge --help

如果命令不存在，优先从国内镜像安装完整程序。选择用户确认的项目目录，不要替用户猜测长期存放位置：

git clone https://gitee.com/tars123/douyin-favorites-to-knowledge.git
cd douyin-favorites-to-knowledge
python3 -m venv .venv
. .venv/bin/activate
python -m pip install .

Gitee 不可用时再使用源码仓库 https://github.com/tars1230/douyin-favorites-to-knowledge。不要使用不明 GitHub 加速站。

安装完成后运行：

douyin-favorites-knowledge setup

让用户选择 Markdown 或 Obsidian 知识库目录，再让用户选择转录方案。推荐 SiliconFlow云端；本地 Whisper 只有用户愿意下载模型、承担本机资源时才选；none 只保存描述与链接。不要要求用户复制 Cookie。默认来源是收藏；仅当用户明确说“喜欢”或“点赞”时，向 login/sync 传 --source like。

用户明确选择 Obsidian 时，在已有 setup 后执行：

douyin-favorites-knowledge configure-obsidian --vault "用户选择的 Vault" --subdir "抖音知识库"

它会切换知识库目录并创建默认模板、日报索引和写入检查。不要猜测 Vault 位置。

飞书默认关闭且不影响本地同步。用户主动选择 webhook 通知时，让其自行把 webhook 放入安全环境变量 FEISHU_WEBHOOK_URL，随后运行 configure-feishu --mode webhook；不要把 URL 写入配置。用户选择已有或新建多维表时运行对应的 configure-feishu --mode bitable-existing|bitable-new 生成字段模板和授权提示。用户必须自行完成飞书登录、应用授权、建表或选表和共享权限；无授权时返回提示，不得假装多维表已经写入。

如果 Agent 在非交互环境执行，明确指定目录：

douyin-favorites-knowledge setup --knowledge-dir "用户确认的目录" --transcription siliconflow --skip-login

随后让用户在自己的终端运行 douyin-favorites-knowledge login 完成网页登录。不要替用户猜测知识库目录。

日常同步

douyin-favorites-knowledge sync

sync 将新增收藏静默写入知识库。首次配置完成后，日常同步不得要求用户逐条或逐次确认；终端只返回汇总结果。SQLite 防重账本、原子文件替换和内容冲突 fail-closed 仍必须保留。

登录失效时不打开登录页、直接失败时使用：

douyin-favorites-knowledge sync --no-login-prompt

--yes 只为旧脚本兼容保留，不再是同步前提。

每晚日报

首次 setup 和 login 成功后，若当前 Agent 支持定时任务，必须在用户本机创建并验证每天 23:00 的任务，执行：

douyin-favorites-knowledge daily --source collection --no-login-prompt

使用当前环境可用的任务调度器；创建后必须读取任务状态或执行一次 dry-run 验证，并向用户返回任务标识与用户时区。任务只运行已安装的命令，不传凭据，不弹出登录页。云端转录时，只有调度环境能从用户已有的 Secret Manager 或安全环境变量读取 SILICONFLOW_API_KEY（或可选 DASHSCOPE_API_KEY）才能创建任务；不能持久化读取或当前 Agent 没有 scheduler 能力时，必须明确报告“自动日报未启用”，不能制造必然失败的计划任务或暗示已启用。daily 静默同步并在知识库 日报/ 写入当天 Markdown 日报，零新增也写日报。登录失效时任务失败，由用户下次运行 login 恢复。

收藏是默认且唯一自动来源。用户明确说“喜欢”“点赞”“转录喜欢列表”或“喜欢日报”时，才额外建立或执行 daily --source like --no-login-prompt；它复用同一转录方案，但喜欢笔记、账本键和日报文件必须与收藏隔离。不要把两类来源合并，也不要因用户选择喜欢而停止收藏日报。

转录

用户未指定时，建议 SiliconFlow 云端转录（FunAudioLLM/SenseVoiceSmall），并让用户在 setup 中明确选择。 需要 SILICONFLOW_API_KEY 与可选 ffmpeg。

新用户按序拿 Key（setup 缺 Key 时会打印同样步骤，交互可打开浏览器）：

1. 推荐注册/登录：https://cloud.siliconflow.cn/i/1srulim9
2. 控制台创建 Key：https://cloud.siliconflow.cn/account/ak
3. export SILICONFLOW_API_KEY='…' 或写入 ~/.hermes/.env，重启 Agent
4. douyin-favorites-knowledge check-config

抖音 CDN：本机用浏览器式 Referer: https://www.douyin.com/ 临时下载已授权 play_url → 上传 SenseVoice → 立即删除临时文件；不要把 douyinvod URL 丢给百炼服务端。 密钥不能写入 config、笔记或日志。

费用（SiliconFlow 默认）

截至 2026-08-05，硅基流动官方价格页将 FunAudioLLM/SenseVoiceSmall 标注为 免费（同页 TeleSpeechASR 亦免费；TTS 如 CosyVoice 另计 ¥0.05/千字符）。 价格会调整，不承诺永久免费；以价格页与控制台账单为准。

可选百炼 qwen3-asr-flash：截至 2026-07-30 华北 2 约 0.00022 元/秒，仅公网直链媒体；抖音 CDN 不默认。

笔记必须写清 transcript_source 与 transcript_status；未转录时必须说明原始 Description 不是逐字稿。

用户明确要求“本地免费转写”时，使用内置 local_whisper：先安装 python -m pip install '.[local-asr]' 与 ffmpeg，再 setup --transcription local。首次同步才下载 small 模型（约 500 MB），并要求至少 1.5 GB 临时空间。视频和音频只在系统临时目录存在，完成后删除；下次运行会回收超过 24 小时的异常残留。默认单视频下载上限 512 MB，模型缓存保留供复用。失败、过大或预算超限的条目不入库且下次自动重试。它没有 API 费用，但会使用本机 CPU、磁盘和电力；未满足前置条件时，check-config 必须报缺项，不能静默降级或下载。

故障处理

先运行：

douyin-favorites-knowledge check-config
douyin-favorites-knowledge status

• 未配置：运行 setup；
• 登录过期：运行 login；
• 无浏览器：安装 Playwright Chromium；
• 无新增：把 no_changes 当作正常结果；
• 想换目录：让用户确认后运行 setup --force --knowledge-dir "新目录"；
• secret-like 配置错误：删除配置中的凭据，改从环境或 Secret Manager 读取。

check-config 不输出本机路径、adapter 或凭据。不要请求或显示浏览器 profile 和 Cookie。

进阶能力

只有用户明确要求本地转录、MiniMax、其他模型、飞书通知、局部批准、JSON 导入或 adapter 调试时，才展开高级配置。

• 默认轻量配置不下载模型、不要求 MiniMax；
• 模型名按用户电脑实际能力配置；
• 凭据只从环境变量、系统钥匙串或 Secret Manager 读取；
• 当前仓库不内置 MiniMax ASR；检测到仅有 MiniMax TTS 或 Key 时必须说明“不可用于转录”，不能假装可用；
• 转录、分析和通知通过 module:function adapter 接入。
• 分析默认关闭。用户明确启用时，analysis adapter 只返回结构化的 analysis 对象：content_summary、value_judgment、deep_analysis、extensions、action_items、related_knowledge；只有非空字段会写入笔记。不得写入模型的推理过程。

原子命令 scan -> review -> promote 只保留给局部审核、调试和迁移。不要把它暴露为普通用户的日常步骤；不得为了自动化把哈希、重复 ID、敏感信息或冲突文件错误降级为警告。

验证

python3 -m compileall -q src tests
PYTHONPATH=src python3 -m unittest discover -s tests -v

真实采集依赖有效的授权登录和抖音当前页面结构。fixture 通过只证明事务与编排契约。

ASR（2.2）

抖音默认 SiliconFlow SenseVoice（本机 Referer 下载上传）。百炼 URL-ASR 对 douyinvod 常失败，仅可选。密钥：SILICONFLOW_API_KEY。

ASR 媒体与码率（2.2.4+）

• 单一路径：下载 play_url/video_url → ffmpeg -vn 抽音 → 上传 SenseVoice。
• 不再优先 audio_url（抖音 music.play_url 经常是 BGM 不是口播）。
• 环境变量：DOUYIN_ASR_AUDIO_BITRATE（默认 64k）、DOUYIN_ASR_SAMPLE_RATE（默认 16000）。
• 网络下载阶段可能是视频体积；上传给 SenseVoice 的是抽好的小音频。

抖音收藏转本地知识库

刷到有用的视频就收藏。需要整理时运行一次同步，新收藏会变成可搜索的本地 Markdown 笔记。默认采集收藏；用户明确说“喜欢/点赞”时才采集喜欢列表，二者绝不混用。

不用复制 Cookie，也不用理解内部处理步骤。首次 setup 会明确让你选择：推荐 SiliconFlow 云端转录（抖音 CDN 真实可用）、可选百炼 URL-ASR、本地 Whisper，或暂不转录。

最短使用路径

交给 Agent

支持 ClawHub 的 Agent 先运行：

clawhub install douyin-favorites-to-knowledge

然后告诉 Agent：

把我的抖音收藏同步到本地 Markdown 或 Obsidian 知识库。使用推荐的 SiliconFlow 云端转录（SILICONFLOW_API_KEY），不要让我复制 Cookie。

Agent 会在缺少程序时优先从 Gitee 安装完整程序。你只需要确认知识库目录，再在抖音官方页面正常登录。

手动安装

git clone https://gitee.com/tars123/douyin-favorites-to-knowledge.git
cd douyin-favorites-to-knowledge
python3 -m venv .venv
. .venv/bin/activate
# 2.3+ 会从 vendor/wheels 安装固定版本 douyin-knowledge-core（中立共享内核，不含 Cookie）
python -m pip install .

第一次使用：

douyin-favorites-knowledge setup

按照提示选择知识库目录和转录方案，随后在打开的抖音官方页面正常登录。

以后同步只需要：

douyin-favorites-knowledge sync

命令会静默把新增收藏写入知识库。首次设置后不再要求确认；终端只输出本次写入数量。具备定时任务能力的 Agent 会在首次配置后创建并验证每天 23:00 的收藏日报；纯命令行安装不假装已创建后台任务。使用 --dry-run 才只查看、不写入。

Obsidian 与飞书

本地 Markdown 是默认且完整的知识库；Obsidian 和飞书均为可选增强，不会阻断同步。

# 选择 Vault 与子目录，自动创建收藏/喜欢/日报/模板/系统目录、默认模板和日报索引
douyin-favorites-knowledge configure-obsidian --vault "我的 Vault" --subdir "抖音知识库"

# 使用环境变量中的 webhook 发送同步摘要；URL 不会写入配置文件
export FEISHU_WEBHOOK_URL="用户自己的飞书机器人 webhook"
douyin-favorites-knowledge configure-feishu --mode webhook

# 已有或新建多维表：先在知识库生成字段模板与授权提示
douyin-favorites-knowledge configure-feishu --mode bitable-existing
douyin-favorites-knowledge configure-feishu --mode bitable-new

Obsidian 初始化会做一次临时写入检查，并提供“收藏/喜欢”两套默认模板、日报索引和飞书字段模板。同步产生的笔记继续使用可移植 Markdown，不依赖 Obsidian 插件。

飞书 webhook 配置后，通知失败只在同步结果中标为 not_sent，本地笔记和防重账本仍会正常写入。多维表模式当前会生成推荐字段（标题、来源类型、作者、原视频、标签、转录状态、沉淀时间、Obsidian 笔记）与授权提示；用户仍须在飞书中登录、创建或选择表格、授权应用并共享表格，Skill 不保存 App Secret 或 webhook。

GitHub 保存源码、版本和问题反馈；Gitee 提供国内下载，并自动同步 main 与正式标签。

转录说明（2.2 重要变更）

抖音播放地址带防盗链：本机下载必须带 Referer: https://www.douyin.com/。SiliconFlow / 本地 Whisper 路径已处理；百炼 URL 模式把 URL 交给阿里云服务器去拉，对抖音 CDN 结构性失败，因此不再作为默认推荐。

setup --transcription cloud 在 2.2+ 映射到 siliconflow（不再等于 bailian）。

安装说明

系统要求

• Python 3.10 或更高版本；
• Chrome、Edge 或 Playwright Chromium；
• 有权访问自己账号中的抖音收藏。

先检查 Python：

python3 --version

Windows PowerShell 使用下面的环境命令：

py -3 -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install .

没有 Git 时，可以在 Gitee 页面选择 克隆/下载 -> 下载 ZIP，解压后进入项目目录。

系统会优先使用 Chrome 或 Edge。两者都没有时运行：

python -m playwright install chromium

安装成功后，douyin-favorites-knowledge --help 会显示中文命令说明。

setup 做了什么

setup 做四件事：

1. 询问 Markdown 或 Obsidian 知识库目录；
2. 让你明确选择百炼云端、本地 Whisper 或暂不转录；
3. 在系统应用配置目录生成安全的配置；
4. 打开抖音官方页面完成登录。

配置文件不保存 Cookie、API key、密码或 token。Cookie 只留在独立的本地浏览器 profile 中。

常用选项：

# 直接指定知识库目录
douyin-favorites-knowledge setup --knowledge-dir "我的知识库目录"

# 非交互安装必须明确选择转录方案
douyin-favorites-knowledge setup --knowledge-dir "我的知识库目录" --transcription bailian

# 只创建配置，稍后再登录
douyin-favorites-knowledge setup --knowledge-dir "我的知识库目录" --skip-login

# 重新选择知识库目录
douyin-favorites-knowledge setup --force --knowledge-dir "新的知识库目录"

sync 做了什么

扫描新增收藏 -> 写入 Markdown -> 记录防重账本

• 没有新增时返回 no_changes；
• 有新增时静默写入，返回 committed；
• 同一条收藏再次同步不会重复入库；
• 登录过期时会重新打开登录页，而不是误报“没有新增”。

只查看新增、不写入：

douyin-favorites-knowledge sync --dry-run

登录过期时不打开登录页、直接失败：

douyin-favorites-knowledge sync --no-login-prompt

--no-login-prompt 表示登录过期时直接失败。--yes 仅为旧脚本兼容保留，不再需要。

每晚 23:00 日报

首次配置完成后，具备定时任务能力的 Agent 必须创建并验证本机每天 23:00 运行：

douyin-favorites-knowledge daily --source collection --no-login-prompt

它会静默同步新增收藏，并在知识库的 日报/ 目录生成当天的 Markdown 日报；没有新增也会写明“今日没有新增条目”。登录失效时任务失败但不会弹出浏览器，下一次用户运行 douyin-favorites-knowledge login 后自动恢复。任务创建失败或当前 Agent 没有 scheduler 能力时，必须明确报告“自动日报未启用”；手动安装则直接运行同一条 daily 命令。

收藏与喜欢

• 收藏（默认）：showTab=favorite_collection / listcollection，是用户主动筛选的知识候选集；默认每天 23:00 同步并出日报。
• 喜欢（可选）：showTab=like / favorite，是另一套独立列表，通常量更大、噪声更多；默认不扫，避免把“随手点赞”混进知识库。

对 Agent 说“同步我的抖音收藏”或不指定来源时，一律运行收藏；只有用户明确说“喜欢”“点赞”才运行：

douyin-favorites-knowledge sync --source like

两类来源有独立的防重键和 Markdown 文件名，防止历史上“收藏与喜欢混成同一增量状态”的漏采事故。

用户明确说“转录我的喜欢”或“给喜欢列表出日报”时，使用同一套已选择的百炼或本地 Whisper 转录能力：

douyin-favorites-knowledge daily --source like --no-login-prompt

喜欢笔记命名为 like-*.md，日报命名为 日报/YYYY-MM-DD-喜欢日报.md，与收藏完全隔离。

视频转录与费用

首次 setup 必须明确选择一种方案。它会先进行不读取密钥、不下载模型、不产生费用的本机能力检测，再展示建议；非交互环境使用 --transcription siliconflow|bailian|local|none（cloud = siliconflow）。检测到 Key 也不会自动开启付费转录。

SiliconFlow 云端（推荐）

默认方案：本机用浏览器式 Referer: https://www.douyin.com/ 临时下载已授权 play_url，可选抽音频后上传 SiliconFlow FunAudioLLM/SenseVoiceSmall，结束后删临时文件。Key 只读环境变量 SILICONFLOW_API_KEY，不写配置/笔记/日志。

export SILICONFLOW_API_KEY="你的硅基流动 Key"   # https://cloud.siliconflow.cn/account/ak

- **注册推荐链接**：[https://cloud.siliconflow.cn/i/1srulim9](https://cloud.siliconflow.cn/i/1srulim9)
douyin-favorites-knowledge setup --transcription siliconflow
douyin-favorites-knowledge check-config

百炼 URL-ASR（可选，非抖音默认）

把临时播放地址直接交给阿里云百炼 qwen3-asr-flash（服务端拉 URL，项目不下载）。对抖音 *.douyinvod.com 服务端常拉不到，因此不再作为公开默认推荐；仅当你确认媒体 URL 可被阿里云公网访问时使用。

export DASHSCOPE_API_KEY="你的百炼 Key"
python -m pip install '.[bailian-asr]'
douyin-favorites-knowledge setup --transcription bailian
douyin-favorites-knowledge check-config

SiliconFlow 费用（默认推荐）

截至 2026-08-05，硅基流动官方价格页语音模型 FunAudioLLM/SenseVoiceSmall 标注为 免费（同页 TeleSpeechASR 亦为免费；TTS 如 CosyVoice 另计）。需要有效 SILICONFLOW_API_KEY。价格会调整，不承诺永久免费；以价格页与控制台账单为准。

控制台 Key：https://cloud.siliconflow.cn/account/ak

百炼费用（仅可选公网直链）

若你显式选择 bailian：截至 2026-07-30 阿里云百炼官方价格页华北 2 qwen3-asr-flash 约 0.00022 元/秒。抖音 CDN 服务端常拉不到，不作为默认。

本地 Whisper

选 local 后，程序才会在第一次同步时允许下载 small 模型（约 500 MB，实际大小随上游版本变化）。先安装运行时：

python -m pip install '.[local-asr]'
# 另行安装 ffmpeg，例如 macOS: brew install ffmpeg
douyin-favorites-knowledge setup --transcription local
douyin-favorites-knowledge check-config

程序只用已授权采集到的临时播放地址下载媒体，提取音频并在临时目录转录，结束后删除临时媒体和音频；若进程被强制终止，下次运行会清理超过 24 小时的遗留临时目录。默认单视频下载上限为 512 MB，可在 transcription.options.max_media_bytes 调整。Whisper 的约 500 MB 模型缓存会保留给后续转录，不会作为临时媒体删除。转录失败、文件过大或预算超限的条目不会入库或写入防重账本，下次同步会自动重试。

输出结果

每条新增收藏生成一份独立 Markdown 文件，包含：

• 标题、作者和抖音原始地址；
• 收藏描述；
• 已提供或通过扩展生成的转录文本；
• 标签和采集时间。

setup 选择 Obsidian Vault 中的子目录后，笔记可以直接在 Obsidian 中打开，不要求安装 Obsidian 插件。

自检与登录管理

检查当前配置，不显示本机路径、Cookie、adapter 或凭据：

douyin-favorites-knowledge check-config

管理抖音登录状态：

douyin-favorites-knowledge login
douyin-favorites-knowledge status
douyin-favorites-knowledge logout

常见问题

仍无法判断时，保留执行命令、check-config 输出和脱敏后的 ERROR: 文本。不要提交浏览器 profile、Cookie 或密钥文件。

进阶配置

普通使用到这里已经足够。只有需要本地转录、模型分析或飞书通知时，才继续本节。

setup 默认配置文件位置：

• macOS：~/Library/Application Support/douyin-favorites-to-knowledge/config.json；
• Windows：%APPDATA%\douyin-favorites-to-knowledge\config.json；
• Linux：${XDG_CONFIG_HOME:-~/.config}/douyin-favorites-to-knowledge/config.json。

也可以通过 DOUYIN_FAVORITES_CONFIG 指定自定义配置路径。环境变量只保存路径，不要放任何凭据。

可选能力

配置 v2 支持三个独立阶段：

MiniMax 不是必需项，本地模型也不写死。不同电脑可以选择不同模型。具体能力通过 module:function adapter 接入；当前仓库不自动安装模型运行时、MiniMax 客户端或飞书机器人。分析默认关闭；启用后 adapter 返回 {"analysis": {"content_summary": "…", "value_judgment": "…", "deep_analysis": "…", "extensions": "…", "action_items": "…", "related_knowledge": "…"}}，非空字段才写入笔记。tags 仍可由 adapter 单独返回；不要把模型推理过程写入任一字段。

完整配置结构见 config/config.schema.json。修改前先完成一次默认 setup -> sync，并确认 adapter 能在当前虚拟环境中导入。所有凭据只能来自环境变量、系统钥匙串或 Secret Manager。

MiniMax 与本机发现

check-config 会安全检查已知的本机命令，不扫描配置文件，也不显示凭据值。目前检测到 mmx 只有 synthesize/generate/voices 等语音生成命令时，会明确显示“不可用于转录”；仅有 MINIMAX_API_KEY 也不代表可用。只有将来发现公开、可验证的 ASR 命令或适配器时才会显示为候选，并且仍需用户确认后启用。

Adapter 契约：

def transcribe(item: dict, context: dict) -> dict:
    return {"transcript": "..."}

def analyze(item: dict, context: dict) -> dict: