# Douyin Engagement MCP

本地运行的标准 MCP Server，用于在用户明确批准评论池后，执行抖音关键词搜索与评论活动。所有评论发送都发生在用户本人登录的专用 Chrome 中，并受人工审批与验证流程约束。

## 核心特性

- **人工审批工作流**：评论池必须由用户一次性确认（`userConfirmed: true`）后才能签发有时效的批准 ID，活动方可启动。
- **关键词搜索真实视频**：基于抖音搜索结果筛选通过相关性检查的视频候选。
- **跨活动去重**：每次评论成功后，视频会被记入本地去重清单；后续活动自动跳过这些视频，不会重复评论同一视频。可通过 `douyin_list_commented_videos` 查看已评论清单。
- **活动结束自动关闭浏览器**：活动正常完成、被停止或因失败结束时，自动关闭 Chrome 释放进程；仅当进入「等待人工验证」状态时保留浏览器供用户操作。
- **验证暂停**：检测到短信、滑块、扫码或登录验证时，活动变为 `waiting_for_verification` 并保留浏览器与原进度；用户完成验证后调用 `douyin_resume_campaign` 从原进度继续。
- **安全边界**：仅使用用户本人在专用 Chrome 中建立的登录态，不读取或导出 Cookie / 密码 / 验证码，验证码只允许用户在浏览器中手动输入。

## 工作流

1. `douyin_check_login` 打开专用 Chrome 并检查登录状态。
2. `douyin_prepare_comment_brief` 获取真实搜索样本与评论生成简报。
3. 客户端中的 AI 根据用户给定的方向预制 3–5 条评论。
4. 用户查看并一次性确认完整评论池。
5. `douyin_approve_comment_pool` 携带 `userConfirmed: true`，签发有时效的批准 ID（默认 30 分钟过期）。
6. 用户确认本次评论数量与间隔后，调用 `douyin_start_campaign`。
7. `douyin_get_campaign_status` 查看逐条评论与发布验证结果。
8. 检测到验证需求时，活动变为 `waiting_for_verification` 并保持浏览器与进度；用户在 Chrome 中完成验证后告知 AI，由 AI 调用 `douyin_resume_campaign` 继续。
9. MCP 先核对当前评论是否已发布，再从原视频、原评论与去重进度继续。

评论从已批准池随机抽取，一轮用完前不重复；搜索异常、视频不相关或评论无法验证时会停止活动。

`douyin_start_campaign` 可传入 `excludeVideoUrls` 手动追加排除视频；跨活动去重在此基础上自动叠加，无需每次手动维护。

## 安装

需要 Node.js 20+ 与 Google Chrome。

```bash
npm install
npm run build
```

首次使用先初始化登录状态：

```bash
npm run login
```

程序会打开专用 Chrome 并等待登录；请自行扫码登录抖音，检测成功后登录状态保存在本地专用资料目录（不会上传任何凭证）。

## 客户端配置（stdio）

将路径替换为本机实际项目目录的绝对路径：

```json
{
  "mcpServers": {
    "douyin-engagement": {
      "command": "node",
      "args": [
        "<PROJECT_DIR>/dist/src/index.js"
      ],
      "cwd": "<PROJECT_DIR>"
    }
  }
}
```

只要客户端支持本地 stdio MCP，均可使用同一结构。部分客户端使用 `servers` 而非 `mcpServers` 作为顶层字段，请以该客户端说明为准。

## 环境变量

- `DOUYIN_MCP_CHROME_PATH`：Chrome 可执行文件路径；常规安装通常无需设置。
- `DOUYIN_MCP_RUNTIME_DIR`：Chrome 资料、活动状态与审计日志目录，默认 `<PROJECT_DIR>/.runtime`。
- `DOUYIN_MCP_ARTIFACT_DIR`：评论前后截图目录，默认 `<PROJECT_DIR>/artifacts`。

## 安全边界

- 只使用用户本人在专用 Chrome 中建立的登录状态。
- 不读取或导出 Cookie、密码和短信验证码。
- 验证码只允许用户在 Chrome 中输入；MCP 工具不接受验证码参数。
- 不尝试破解验证码或绕过安全验证。
- 评论池批准默认 30 分钟过期；活动创建后保存已批准评论快照，以便验证完成后恢复原活动。
- 等待验证时保留候选列表、当前视频、评论顺序、成功记录与去重进度，且不会关闭浏览器。
- 提交后找不到完整评论文本时，不计成功并停止后续活动。
- 默认单次最多 20 条，评论间隔最少 30 秒。
- 活动正常结束（完成 / 停止 / 失败）后自动关闭浏览器释放资源；仅验证等待期间保持打开。

## 开发验证

```bash
npm run check
npm test
npm run build
```

单元测试覆盖 blocker 识别、评论池、相关性评分与活动恢复逻辑。真实评论属于外部副作用，不包含在自动测试中；首次真实测试建议只设置 1 条评论，并在页面中人工复核。