# douyin-huoke **Repository Path**: sunjulee/douyin-huoke ## Basic Information - **Project Name**: douyin-huoke - **Description**: 抖音AI全自动获客系统 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-27 - **Last Updated**: 2026-10-08 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 抖音自动获客系统 Windows 桌面工具（Electron + React + TypeScript）。左侧内嵌抖音网页版供用户正常登录与浏览，右侧提供自动化采集与触达操作：把抖音公开的用户数据整理成结构化结果，用于寻找潜在客户、发私信并跟进回复。 > 术语表见 [CONTEXT.md](./CONTEXT.md)，架构决策记录见 [docs/adr/](./docs/adr/)。代码里的命名与界面文案都以 CONTEXT.md 为准。 --- ## 功能概览 界面右侧四个 tab： | Tab | 作用 | | --- | --- | | **采集用户** | 主流程。以行业词库为关键词跑一条线性采集流水线，结果写入客户库；面板上常驻采集流程图与「参数设置」「操作说明」入口 | | **自动私信** | 从客户库挑候选（新客户 / 未回复跟进），拟人点击打字逐条发送，间隔随机并叠加刷视频填充 | | **检测回复** | 打开私信会话列表认出哪些客户回过消息，标记「已回复」；可定期自动扫描，可选把双方聊天记录采下来 | | **按号采集[用于测试]** | 输入抖音号搜索单个用户主页资料并入库，短任务，用于验证链路 | 顶部有「今日用量」条（采集分钟 / 入库人数 / 私信条数），按**登录账号**分行记账，重启不丢。 --- ## 界面一览 **采集用户** —— 主流程。左侧登录抖音（未登录时操作入口会给出提示），右侧「开始采集」一键起任务；下方是采集流水线的五节点骨架图，任务未开始时也完整展示，运行中高亮当前节点。 ![采集用户](./img/采集用户.png) **采集参数设置** —— 从「采集用户」面板的「参数设置」进入，改完自动保存。三组：①过滤（行业词库 = 搜索词，为空无法启动 / 排除词 / 意图分门槛）②搜索与筛选（抖音时间桶、视频最近天数、点赞区间、含图文）③采集量与节奏（最大采集视频、单视频评论、评论最近天数、时长上限、速度、AI 判作者），底部还有「采完自动私信」开关。 ![采集参数设置](./img/采集用户-参数设置.png) **自动私信** —— 私信文案模板池（一行一条，发送时随机抽取，`{昵称}` 自动替换为对方昵称）、发送节奏（间隔与每次上限）、私信间隔刷视频（条数与时长双区间，任一满足即停；点赞概率与查看作者信息概率分别可调，用于降风控）。底部「启动 / 停止 / 面板诊断」，发不出去时先用「面板诊断」分流原因。 ![自动私信](./img/自动私信.png) **检测回复** —— 「停止自动检测 / 检测一次」开关，设定每隔几分钟监控一次、是否采集双方聊天记录、每人最多留存多少条（对方 + 自己累计）。下方是监控状态：当前是否扫描中、上次与下次扫描时间。聊天记录可在「数据库 → 聊天记录」查看，或在「用户信息」里点某人的「聊天记录」按钮。 ![检测回复](./img/检测回复.png) --- ## 采集流水线 「采集」是系统唯一的采集模式，零输入，内部由一条线性链路完成： ``` ① 综合搜索 按行业词打开抖音综合搜索 ② 精筛入视频表 点赞区间 / 相对天数 / 内容类型 / 去重 / 最大采集数 → collect_videos ③ 采一级评论 逐个进视频详情采一级评论 → collect_comments ④ AI 合并判定 每个视频采完即把「作者 + 全部评论」合并成一次判定入队（异步） ⑤ 写回判定结果 AI 逐条输出意向与意图分，写回视频表 / 评论表（异步） ⑥ 促进入库 轮询把意向为「是」的评论者与判为「需求」的作者写进客户库（异步） ``` ①②③ 在左侧浏览器中拟人执行，④⑤⑥ 是后台异步尾段——浏览器段结束后仍会继续跑，直到「三段完成判定」命中。 **风控与安全设计** - **拟人**：滚动、停顿、偶发点赞收藏、逐字输入，逼近真人操作轨迹。 - **验证码暂停**：检测到校验页即挂起任务，等用户在左侧人工过掉后自动续跑；超过「验证码等待」设置（默认 15 分钟）才真正结束，已采数据保留。 - **任务冷却**：两次同类任务之间强制随机休息（默认 2–5 分钟），起点取自客户库记录的上次结束时间，重启依然生效。串联私信不受冷却约束。 - **每日上限**：每日采集分钟 / 入库人数 / 私信条数（0 = 不限），达到即拒绝启动新任务，是账号安全的最后一道闸。 - **互斥**：采集、私信、回复检测、按号采集共用左侧浏览器，同时只允许一个在跑。 上限与冷却按**登录账号**分行设置（「设置 → 每日上限设置」），各账号互不影响；上限填 0 表示不限，改完点「保存」立即生效。当前登录的账号不允许删除，需先退出登录。 ![每日上限设置](./img/每日上限设置.png) --- ## 数据存储 ### 客户库（单个 .db 文件） 默认位于 Electron 的 `userData/db/dy_hk.db`，Windows 下即： ``` C:\Users\<用户名>\AppData\Roaming\抖音自动获客系统\db\dy_hk.db ``` 在「数据库 → 数据库管理」里可以换库或备份（备份默认文件名 `dy_hk+年月日时分秒.db`，保存对话框中可改）。切换库时先开新库、成功了再关旧库——新文件若打不开（不是有效库 / 被占用）会继续用原库，不会把软件卡在失效实例上。 ![数据库管理](./img/数据库管理.png) | 表 | 内容 | | --- | --- | | `collected_users` | 用户表：昵称/简介/抖音号/粉丝数/联系方式/来源/意图分/AI 意向/私信与回复时间/跟进阶段 | | `collect_videos` | 视频表：业务编码 code、批次、命中关键词、标题、作者资料、点赞评论分享数、AI 对作者的分类 | | `collect_comments` | 评论表：仅一级评论，含 AI 意向/意图分/理由，外键 `video_code` 指向视频表 | | `daily_usage` | 每日用量表：(登录账号, 日期) 一行，采集时长/入库人数/私信条数 + 两类任务最后结束时间 | | `account_quota` | 每个抖音号一套「每日上限」设置（主键为抖音号） | | `dm_chat_messages` | 私信聊天记录，随用户级联删除，按（用户, 发送方, 内容, 分钟桶）去重 | ### 配置文件（软件级，不随库切换） 存放在同一 `userData/db/` 目录下的 JSON： | 文件 | 内容 | | --- | --- | | `db-config.json` | 当前正在使用的客户库路径 | | `filter-config.json` | 行业词库、排除词库、意图分权重与门槛、粉丝区间 | | `collect-config.json` | 采集参数预设（速度、时间桶、点赞区间、各类上限、是否串联私信等） | | `dm-config.json` | 私信设置（文案模板、间隔、上限、刷视频规则）与回复监控设置 | | `ai-config.json` | 多供应商 AI 配置（当前生效档、业务描述、并发、超时、重试、温度） | ### 诊断日志 主进程统一落盘在 `userData/logs/app-YYYYMMDD.log`，保留 14 天；「帮助 → 打开诊断日志」可直接打开。凡是「跑失败但不知道为什么」的环节都会在这里留一行。 --- ## AI 能力 AI 用于两步：判定视频作者类型（需求/同行/其他）、逐条判定评论者的意向（是/否/未知），并给出 0–100 意图分。**未配置密钥时自动降级为规则兜底**：由内置权重按行业词命中、联系方式、来源、蓝V、粉丝区间加权求和。 支持多供应商档（cc-switch 式，仅一个生效），在「设置 → AI 设置」里配置，并可在窗口内做「对话测试」： | 类型 | 默认地址 | 默认格式 | | --- | --- | --- | | DeepSeek | `https://api.deepseek.com` | OpenAI Chat | | Kimi Code | `https://api.kimi.com/coding` | Anthropic Messages | | 小米 MiMo | `https://api.xiaomimimo.com/v1` | OpenAI Chat | | 智谱 GLM | `https://open.bigmodel.cn/api/paas/v4` | OpenAI Chat | | 自定义 | 自填 | 四选一（含 OpenAI Responses / Gemini Native） | > Kimi Code 的 OpenAI 兼容面按 User-Agent 白名单拦截第三方客户端，因此走 Anthropic 兼容面 `/v1/messages`。 「设置 → AI 设置」是配置池：可加多个供应商档，每档单独填密钥与模型，采集面板下拉里选当前生效的那一个。窗口底部有「对话测试」，用来验证所选模型配得通不通。密钥只存本地配置文件，不入库、不打日志；采集任务运行中该窗口只读锁定。 ![AI 设置](./img/AI设置.png) --- ## 技术栈 - **Electron 43** + **electron-vite 2**（主进程 / preload / 渲染进程三段构建） - **React 18** + TypeScript 5 - **better-sqlite3 13**（NAPI 预编译二进制，无需针对 Electron 重编译） - **exceljs**（导出 Excel）、**electron-updater**（自动更新，generic 静态源） - **vitest**（单元测试） 自动化与数据采集层： - **CDP 网络拦截**（`src/main/cdp/interceptor.ts`）读取抖音公开接口响应，而非解析 DOM 为主 - **WebContentsView** 内嵌抖音网页，与渲染进程共用一套布局公式（`src/shared/layout.ts`）保证像素对齐 - 弹窗遮罩打开时由主进程隐藏内嵌视图（`browser:setVisible`），因为 WebContentsView 叠加在 DOM 之上 --- ## 目录结构 ``` img/ README 截图（界面一览 / 各设置窗口） src/ ├─ main/ 主进程 │ ├─ index.ts 入口：单实例锁、窗口装配、各模块连线 │ ├─ ipc.ts IPC 通道注册（渲染进程唯一的调用面） │ ├─ menu.ts 应用菜单（数据库 / 设置 / 帮助） │ ├─ account.ts 登录账号身份（uid、抖音号、昵称） │ ├─ douyin-view.ts 内嵌抖音 WebContentsView │ ├─ log.ts 诊断日志 │ ├─ automation/ 自动化任务 │ │ ├─ collect-pipeline-task.ts 采集流水线主体 │ │ ├─ ai-worker.ts AI 判定队列 + 促进入库轮询 │ │ ├─ dm-task.ts 私信任务 │ │ ├─ reply-scanner.ts 回复识别 │ │ ├─ reply-scheduler.ts 定期回复检测调度 │ │ ├─ quota-guard.ts 每日上限与冷却闸门 │ │ ├─ single-user-collect.ts 按号采集 │ │ ├─ human-scroller.ts / human-input.ts / video-brusher.ts 拟人行为 │ │ └─ speed-profile.ts 速度档位 │ ├─ capture/ 解析与判定 │ │ ├─ parsers/ 抖音接口响应解析（综合搜索/评论/用户/私信会话） │ │ ├─ ai-client.ts AI 调用与适配器 │ │ ├─ contact-extractor.ts 简介联系方式提取 │ │ └─ scorer.ts 规则意图分 │ ├─ cdp/interceptor.ts CDP 网络拦截 │ └─ store/ 持久化 │ ├─ customer-db.ts 客户库（建表/迁移/查询/记账） │ ├─ user-store.ts 采集结果表（内存 + 落库） │ ├─ exporter.ts Excel 导出 │ └─ *-config.ts 各类 JSON 配置读写 ├─ preload/index.ts contextBridge 暴露类型化 API（HostApi） ├─ renderer/ React 界面 │ ├─ App.tsx 布局、tab 切换、全局状态订阅 │ └─ components/ UserCollectPanel / DmPanel / ReplyPanel / SingleCollectPanel / ResultTable / QuotaBar └─ shared/ 主进程与渲染进程共用 ├─ types.ts 领域类型、默认配置、IPC 契约 ├─ layout.ts 布局常量与计算 └─ collect-estimate.ts 采集耗时估算 ``` --- ## 开发 **环境要求**：Node.js 20+、pnpm。原生模块使用预编译二进制，无需本地编译工具链。 ```bash pnpm install pnpm dev # 启动开发（热更新） pnpm typecheck # tsc --noEmit 类型检查 pnpm test # vitest 单元测试 pnpm build # 构建到 out/ pnpm preview # 预览构建产物 ``` ### 打包（Windows） ```bash pnpm dist:win # electron-vite build && electron-builder --win → dist/ ``` 产物为 NSIS 安装包，命名 `--setup.exe`，支持自选安装目录、创建桌面快捷方式。 **自动更新**：`electron-builder.yml` 里 `publish.provider = generic`，指向静态托管地址；打包后把 `dist/` 下的安装包与 `latest.yml` 上传到该地址即可下发更新（仅打包版生效，开发环境不检查）。 **国内网络**：`.npmrc` 已配置 electron 与 electron-builder 二进制走 npmmirror 镜像。 ### 关于原生模块 better-sqlite3 v13 使用 NAPI 预编译二进制（Node/Electron 间 ABI 稳定），因此打包时关闭了 `npmRebuild`（避免 node-gyp 写 `~/.electron-gyp`）。若更换版本后遇到 ABI 不匹配，可执行： ```bash pnpm rebuild:native # electron-rebuild -f -w better-sqlite3 ``` 打包时 `better-sqlite3` 会被 `asarUnpack` 解包（原生模块无法从 asar 内加载）。 --- ## 架构决策记录 | 编号 | 决策 | | --- | --- | | [0001](./docs/adr/0001-electron-typescript-client.md) | Electron + TypeScript 客户端 | | [0002](./docs/adr/0002-cdp-network-interception.md) | 用 CDP 网络拦截取数据 | | [0003](./docs/adr/0003-human-like-automation.md) | 拟人化自动化 | | [0004](./docs/adr/0004-local-client-database.md) | 本机 SQLite 客户库 | | [0005](./docs/adr/0005-dm-via-page-automation.md) | 私信走页面自动化 | | [0006](./docs/adr/0006-unified-collect-pipeline.md) | 统一采集流水线 | | [0007](./docs/adr/0007-blogger-fission-and-visual-pipeline.md) | 博主裂变与可视化流水线 | | [0008](./docs/adr/0008-retire-fans-collection-and-rework-flowchart.md) | 退役粉丝采集、改版流程图 | | [0009](./docs/adr/0009-linear-ai-collect-pipeline.md) | 线性 AI 采集流水线（现行） | | [0010](./docs/adr/0010-dm-reply-loop-and-daily-quota.md) | 私信回复闭环与每日用量 | | [0011](./docs/adr/0011-reply-detection-tab-and-chat-records.md) | 回复检测 tab 与聊天记录 | --- ## 免责声明 本项目仅供学习与技术研究使用。使用者需自行确保其使用行为符合抖音平台的用户协议与相关法律法规；因使用本工具产生的一切后果由使用者自行承担。