前言¶
DeepSeek Harness（DSH）的插件化设计让很多能力可以像调用系统命令一样使用。当智能体需要了解抖音上的内容、视频画面或与用户、群组交互时，一个能直接接入抖音的工具链会很有用。dsh-douyin 就是为这个场景准备的 DSH 插件，它把热榜、搜索、视频详情、下载与抽帧、以及私信/群聊都作为一等公民工具暴露出来，并附带一个本地 HTTP API。
这是什么¶
dsh-douyin 是一个 DSH 插件（Cordis Host 插件，工具注册到 ctx.tools），同时提供一组可以独立运行的 Python 脚本。它基于 SakuraMat0u/dsh-douyin-toolkit（MIT）改造，在保留上游核心设计的基础上增加了 Linux/headless 适配、私信与群聊驱动、视频下载与抽帧、本地 HTTP API，并将所有服务器路径参数化。插件由维护者 JianHeShui 维护，归类为「联网工具」。
核心能力¶
它主要解决四个问题：
- 读得动：获取热榜条目、热度与搜索链接；关键词搜索；获取视频详情、作者、互动数据、评论；查看用户主页。
- 看得懂：下载视频后用 ffmpeg 均匀抽 4–12 帧，把帧路径交给支持视觉的模型（如 DeepSeek flash 的原生视觉），不需要自己实现视频理解。
- 说得上话：通过 Playwright 驱动抖音网页版，给单个用户发送私信、给群聊发消息。
- 接得住：所有能力通过本地 HTTP API（默认
127.0.0.1:7709）暴露，任何语言写的上层程序都能调用。
它不做：发布视频、批量点赞关注、养号、多账号矩阵、自动过验证码、签名逆向。
特性一览¶
| 能力 | 说明 | 需要登录 |
|---|---|---|
| 热榜 | 抖音热榜条目、热度、搜索链接 | 否 |
| 搜索 | 关键词搜索，search_id 链式翻页 |
是（多数情况） |
| 视频详情 | 文案、作者、互动数据、前 N 条评论 | 是 |
| 用户主页 | 简介、粉丝、近期作品 | 是 |
| 视频下载 | 移动端分享页解析无水印直链 | 是 |
| 抽帧 | ffmpeg 均匀抽 4–12 帧 | 是 |
| 私信 / 群聊 | Playwright 驱动网页版，dry-run 默认，三道闸 | 是 |
| 登录状态机 | 可轮询的扫码/短信状态机（有头环境） | — |
| 状态自检 | 依赖、登录态、配额、上次错误一句话总结 | 否 |
| HTTP API | 上述能力的 JSON 接口 | 视接口 |
其它工程特性：
- 单 worker + 抖动：所有后端调用串行，翻页 3–8 秒高斯抖动，独立调用 1.8–3.2 秒，避免明显的机器人节奏。
- 小时配额 + 指数退避：滚动 1 小时请求预算（默认 60），触发限流后 1/2/4/8/15 分钟退避，不立即重试。
- 凭证脱敏：cookie、
sessionid、passport_*、localStorage、storage_state不会出现在返回值、日志或报错里。 - 账号指纹：记录首个登录账号的不可逆指纹，换号后写操作直接拒绝。
- 缺失即
null：抖音数据稀疏，缺字段返回null，不填 0、不猜。
安装与启用¶
- 克隆仓库并创建虚拟环境
git clone https://github.com/JianHeShui/dsh-douyin.git
cd dsh-douyin
python3 -m venv .venv
# Linux / macOS
.venv/bin/pip install -r python/requirements.txt
# Windows
# .venv\Scripts\pip install -r python\requirements.txt
需要 HTTP API 的话，再装一层：
.venv/bin/pip install -r python/requirements-http.txt
- 准备浏览器
Windows 上装了 Edge 就不用管。Linux / macOS：
.venv/bin/playwright install chromium
也可以用系统包（apt install chromium），插件会自动发现。要指定就用 DOUYIN_BROWSER=/usr/bin/chromium，或在插件配置里设 edgePath。
- 装进 DSH
dsh plugin --profile desktop add file:$PWD
# 或按你的 profile 名： --profile web
插件自带 cordis.patch.yml，安装时会插入 id: douyin 的配置行。装完重启 DSH。自检：
./scripts/selfcheck.sh # Windows: .\scripts\selfcheck.ps1
4.（可选）起 HTTP 服务
./scripts/run-http.sh # Windows: .\scripts\run-http.ps1
curl -s http://127.0.0.1:7709/health | jq .
登录¶
必须在有显示器的电脑上登录，再把 cookie 送到服务器。服务器 headless 环境无法扫码、无法过滑块。
本地执行：
.venv/bin/python tools/export_login_state.py
扫码登录成功后，自动写出 data/home/.dy/cookies/default.json。再通过 scp 传到服务器：
scp data/home/.dy/cookies/default.json user@server:~/dsh-douyin/data/home/.dy/cookies/default.json
ssh user@server 'chmod 600 ~/dsh-douyin/data/home/.dy/cookies/default.json'
完整流程与过期处理见 docs/COOKIE-GUIDE.md。登录后可验证：
curl -s -X POST http://127.0.0.1:7709/im/status | jq .
典型用法¶
在 DSH 里：
douyin_status # 先看状态
douyin_hot({"count": 10}) # 热榜
douyin_search({"keyword": "开源", "limit": 5}) # 搜索
douyin_video({"aweme_id": "7xxxxxxxxxxxxxx"}) # 视频详情
看视频内容（推荐路径）：
POST /frames {"aweme_id": "...", "n": 8} # 拿到 8 张帧
→ 把帧路径交给视觉模型，问"这条视频讲了什么"
HTTP 侧：
# 热榜
curl -s -X POST http://127.0.0.1:7709/trending | jq .
# 搜索
curl -s -X POST http://127.0.0.1:7709/search \
-H 'Content-Type: application/json' \
-d '{"keyword":"猫","count":5}' | jq .
# 下载 + 抽帧
curl -s -X POST http://127.0.0.1:7709/frames \
-H 'Content-Type: application/json' \
-d '{"aweme_id":"7xxxxxxxxxxxxxx","n":8}' | jq .
# 私信（默认 dry-run：只填框 + 截图 + 清空）
curl -s -X POST http://127.0.0.1:7709/im/send \
-H 'Content-Type: application/json' \
-d '{"to":"某某","text":"在吗"}' | jq .
完整接口、错误码、dry-run 语义见 docs/HTTP-API.md。
适用场景与注意¶
适合需要让智能体主动了解抖音内容、通过视频画面进行理解、或在 DSH 生态中直接操作私信/群聊的场景。使用前请检查源码与许可证（MIT），确认符合你的合规要求。
短结尾¶
dsh-douyin 把抖音的热榜、搜索、视频理解与私信/群聊都作为 DSH 的一等公民工具暴露出来，并附带本地 HTTP API。它基于 SakuraMat0u/dsh-douyin-toolkit 改造，增加了 Linux/headless 适配、私信与群聊驱动、视频下载与抽帧、本地 HTTP API，并将所有服务器路径参数化。适合需要让智能体主动了解抖音内容、通过视频画面进行理解、或在 DSH 生态中直接操作私信/群聊的场景。
