# 浏览器搜索抖音账号操作规范

> 通过 browser-harness 搜索抖音账号 ID，获取账号主页信息与视频列表。
> 核心原则：**适度访问网站**，控制访问频率与行为节奏，不对目标站点造成负担。

---

## 一、适用场景

- 已知抖音号或账号 ID，需要获取该账号的主页信息（昵称、粉丝数、简介等）
- 需要获取账号下的视频列表（视频 ID、标题、点赞数等）
- 三方数据 API 与 MCP 平台均无法覆盖的账号

---

## 二、执行流程

### 步骤 0：适度访问 — 首页浏览（50% 概率执行）

| 子步骤 | 操作 | 说明 |
|--------|------|------|
| 0a | 随机决定是否执行（50% 概率） | 不每次都走，适度访问 |
| 0b | 打开抖音首页 `new_tab("https://www.douyin.com")` | — |
| 0c | 检测登录弹窗，有则点击关闭按钮（X / "暂不登录"） | 首页阶段自动关闭，不需登录 |
| 0d | 随机停留 3~8 秒 | 适度访问，不快速跳转 |
| 0e | 随机滚动 1~2 次页面 | 适度浏览行为 |

### 步骤 1：搜索账号 ID

| 子步骤 | 操作 | 说明 |
|--------|------|------|
| 1a | 导航到搜索页 `https://www.douyin.com/search/{账号ID}?type=user` 或在搜索框输入 | — |
| 1b | 检测登录弹窗 | **如弹出登录窗口，停止操作，提示用户手动登录** |
| 1c | 等待搜索结果加载 | `wait_for_load()` |

### 步骤 2：进入达人主页

| 子步骤 | 操作 | 说明 |
|--------|------|------|
| 2a | 从搜索结果中找到对应账号 | 人工确认匹配（抖音号可能与搜索词不同） |
| 2b | 点击进入主页 | — |
| 2c | 检测登录弹窗 | **如弹出登录窗口，停止操作，提示用户手动登录** |
| 2d | `wait_for_load()` 等待主页加载完成 | — |
| 2e | 随机停留 2~5 秒 | 适度访问 |

### 步骤 3：提取账号基础信息

通过 `js(...)` 提取以下字段：

| 字段 | 说明 |
|------|------|
| 昵称 | 账号显示名称 |
| 抖音号 | 账号 short id（可搜索短号） |
| 抖音ID(sec_uid) | 账号唯一标识，主页 URL 中 `/user/{sec_uid}` 那串 |
| 抖音地址 | 主页链接 `https://www.douyin.com/user/{sec_uid}` |
| 粉丝数 | 关注者数量 |
| 关注数 | 关注数量 |
| 获赞数 | 总获赞 |
| 作品数 | 视频作品总数 |
| 简介 | 个人介绍 |
| IP属地 | 账号所在地区 |
| 头像 URL | 头像图片地址 |

### 步骤 4：提取视频列表（数量按 SKILL.md「视频获取数量」参数）

| 子步骤 | 操作 | 说明 |
|--------|------|------|
| 4a | 滚动到视频列表区域 | — |
| 4b | 每次滚动后等待 1~3 秒（随机） | 适度访问，不连续快速滚动 |
| 4c | 滚动 2~3 次即可；停止条件：收集数量达到 SKILL.md「视频获取数量」参数，**或滚动到底部后加载不出更多视频**（先到者为准） | 达到目标数或无法加载更多即停，禁止无限滚动 |
| 4d | 通过 `js(...)` 提取每条视频数据 | 从 React Fiber 中提取 awemeInfo，包含完整 stats/video/textExtra |

**滚动容器与加载技巧（实测踩坑记录，2026-08）：**

1. **抖音达人主页的滚动容器不是 `window`**，是 `.route-sc` 元素（`overflow-y:auto`）。直接滚动 window 无效，必须滚动真实容器：
   ```js
   // 定位真实滚动容器（含视频链接的 overflow 祖先），显式滚到底触发懒加载
   const container = document.querySelector('.route-sc') ||
     Array.from(document.querySelectorAll('a[href*="/video/"]')).map(a => {
       let el = a.parentElement;
       while (el && el.scrollHeight <= el.clientHeight) el = el.parentElement;
       return el;
     }).find(Boolean);
   if (container) container.scrollTop = container.scrollHeight;
   ```
2. 滚动后等待 1~3 秒再检查：**若滚动到底（scrollTop 不再增长）或链接数不再增加，即"加载不出更多"**，立即停止（不无限滚动）。
3. 备选：用 harness 的滚轮助手 `scroll(x, y, dy)`（派发 mouseWheel 事件，滚动光标下元素），适用于容器定位困难时。
4. **提取兜底**：Fiber 提取（awemeInfo）个别卡片可能取不到（虚拟化卡片差异），用 `a[href*="/video/"]` 的 href 提取 aweme_id 兜底，保证数量完整。

**数据提取方式：** 通过遍历页面上 `a[href*="/video/"]` 元素的 React Fiber，向上查找 `awemeInfo` 对象，获取完整的视频数据（含 stats、video、textExtra 等字段），而非仅从 DOM 文本解析。

**提取方法优先级（2026-08-31 实测纠正）：**

1. **首选：列表组件 Fiber `defaultDataList`（一次拿全，含 createTime）**——08-26 旧梦留声机 36 条、08-31 俊希 136 条均实测通过：
   - 从 `#root` 的 `__reactContainer$` / `__reactFiber$` 键向下遍历（child/sibling 链），找 `memoizedProps.defaultDataList` 数组，每条含 `awemeId / desc / createTime / stats(diggCount 等驼峰) / textExtra`
   - **`createTime` 只有这个来源可靠**：逐卡片 `awemeInfo` 的 createTime 在列表页可能缺失（undefined 被 JSON.stringify 省略），`defaultDataList` 是全量组件数据，136/136 含 createTime
   - 统计字段是**驼峰式**：`stats.diggCount / commentCount / shareCount / collectCount / playCount`（不是 snake_case 的 `digg_count`）
2. **兜底：卡片 Fiber `awemeInfo`**——逐卡片提取 `awemeInfo.video.duration`（毫秒）等 defaultDataList 可能缺的字段；两者按 awemeId 合并：defaultDataList 提供 createTime/stats，卡片提供 duration
3. **禁止**：逐条打开 `/video/{id}` 视频页抓发布时间——15 次跳转是明显爬虫特征，且低效；正确路径是主页一次滚动 + Fiber 一次提取

**访问账号主页（2026-08-31 实测纠正）：**

- **必须走搜索路径**：`https://www.douyin.com/search/{账号ID}?type=user` → 搜索结果中定位用户卡片 → **模拟点击进入主页**（CDP `Input.dispatchMouseEvent` mouseMoved→mousePressed→mouseReleased，或 `click_at_xy`），**禁止直接构造 `/user/{sec_uid}` 地址跳转**
- 搜索结果卡片链接带完整参数（如 `/user/{sec_uid}brjmRxiM9i`），直接构造缺后缀的地址会访问异常；且频繁直达地址 = 爬虫特征
- 标签页复用：先在已有标签页上导航，不新建（见 5.5 标签页复用规则）

**提取的视频字段（13列标准）：**

| 列序 | 字段 | 说明 | 数据来源 |
|------|------|------|----------|
| 1 | 序号 | 自增序号 | 脚本生成 |
| 2 | 视频ID | aweme_id | 页面数据 |
| 3 | 视频标题 | 视频描述文案 | 页面数据 |
| 4 | 视频地址 | `https://www.douyin.com/video/{aweme_id}` | 拼接生成 |
| 5 | 点赞数 | digg_count（数字） | 页面数据 |
| 6 | 点赞(显示) | 如 "2.1万"、"10万+" | 页面显示文本 |
| 7 | 评论数 | comment_count | 页面数据 |
| 8 | 分享数 | share_count | 页面数据 |
| 9 | 收藏数 | collect_count | 页面数据 |
| 10 | 播放量 | play_count（如页面可见） | 页面数据 |
| 11 | 视频时长 | duration（秒） | 页面数据 |
| 12 | 发布时间 | create_time（格式化为 YYYY-MM-DD） | 页面数据 |
| 13 | 标签 | 从标题中提取的 # 标签，逗号分隔 | 标题解析 |

### 步骤 5：整理输出

- 账号基础信息 → 结构化保存
- 视频列表 → 保存为 Excel 到 `{产出根目录}/{达人昵称}/短视频表格.xlsx`

> **注意**：浏览器抓取的数据保存为 **Excel 文件**（`短视频表格.xlsx`），与三方数据 API 保存的 JSON 格式（`视频数据.json`）不同。

---

## 三、登录弹窗处理逻辑

| 场景 | 处理方式 |
|------|---------|
| 首页浏览阶段（步骤0） | 自动关闭弹窗，不需要登录 |
| 搜索阶段（步骤1） | **停止操作，提示用户登录**，用户登录后继续 |
| 进入主页阶段（步骤2） | **停止操作，提示用户登录**，用户登录后继续 |

**提示语示例：**
> 检测到登录弹窗，请在浏览器中手动登录抖音账号，登录完成后告诉我继续。

---

## 四、适度访问原则

1. **随机停留时间**：所有等待时间使用随机区间（如 3~8 秒、1~3 秒），不使用固定值
2. **随机滚动节奏**：滚动间隔随机化，不连续快速滚动
3. **不每次都走首页浏览**：50% 概率跳过，避免每次行为完全一致
4. **控制请求量**：视频列表收集数量达到 SKILL.md「视频获取数量」参数即停止滚动，不无限加载
5. **单次任务单账号**：一次只处理一个账号，不批量并发

---

## 五、browser-harness 调用方式（环境 SOP）

> **环境说明（2026-09-02 调整）**：browser-harness 由 uv 工具安装，可执行文件位置**按系统区分**——Windows：`~/.local/bin/browser-harness.exe`；macOS/Linux：`~/.local/bin/browser-harness`；**技能本体位置（09-02 起）**——主技能 `短视频工作台/subskills/browser-harness/`（源仓库：`project/短视频脚本创作/V1.0/subskills/browser-harness/`，含 `envs/browser-harness/` 环境与 `src/`；**不再挂在 mcn-dou-analysis 下**；**09-10 起无 dsh 部署环境**）。

### 5.0 环境检查与安装（每次浏览器任务前【必做】）

**① 检测是否已安装（任一方法即可判定）：**

| 方法 | 操作 | 判定 |
|------|------|------|
| ① 可执行文件 | 检查 `~/.local/bin/browser-harness.exe`（Windows）/ `~/.local/bin/browser-harness`（macOS/Linux）是否存在 | 存在 = 已安装 |
| ② 命令探测 | `command -v browser-harness`（macOS/Linux）/ `where browser-harness`（Windows）是否有输出 | 有输出 = 已安装 |
| ③ doctor 验证（可选） | `browser-harness doctor`（确认工具/daemon/Chrome 三要素） | 三要素就绪 = 可用 |

**② 未安装 → 提醒用户安装**（由 SKILL.md「browser-harness 依赖（红线）」驱动）：

- **可跳过**：改用三方数据 API / MCP 兜底数据源，但功能一/二浏览器抓取无法执行
- **同意安装**：`uv tool install --python 3.12 --upgrade --force browser-harness`（`--python 3.12` 防止选中过旧版本；`--upgrade --force` 覆盖旧安装）
- **技能本体**：源仓库 `project/短视频脚本创作/V1.0/subskills/browser-harness/`（主技能 `短视频工作台/subskills/browser-harness/`；**09-10 起无 dsh 部署环境**；如缺失可从 browser-harness 仓库的 `browser-harness skill` 命令重新生成）
- **安装后验证**：`command -v browser-harness`（macOS/Linux）/ `where browser-harness`（Windows）有输出 + `browser-harness doctor` 三要素全绿，再进入下方 5.1 环境准备

### 5.1 环境准备（每次浏览器任务前【必做】）

**① 清除代理环境变量（最重要，漏掉必踩坑）**：本机代理软件（如 Shadowsocks 的 Privoxy 组件监听 10800）会劫持 127.0.0.1 的 CDP 请求（报 "Internal Privoxy Error" 或连接失败）。**按系统清除**：

- **Windows（PowerShell）**：
```powershell
Remove-Item Env:HTTP_PROXY, Env:HTTPS_PROXY, Env:http_proxy, Env:https_proxy -ErrorAction SilentlyContinue
$env:NO_PROXY = "127.0.0.1,localhost,::1"
```
- **macOS/Linux（bash/zsh）**：
```bash
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY
export NO_PROXY="127.0.0.1,localhost,::1"
```

**② 连接方式（按顺序尝试）**：

| 方式 | 操作 | 说明 |
|---|---|---|
| A. 自动（推荐） | 直接运行 browser-harness（daemon 自动启动并连接浏览器） | 最简单；可能触发 Chrome 授权弹窗（见 5.2） |
| B. 定向连接 | 设置 BU_CDP_URL 后运行：Windows `$env:BU_CDP_URL="http://127.0.0.1:<端口>"` / macOS `export BU_CDP_URL="http://127.0.0.1:<端口>"` | 端口：先探测 9222（用户 Chrome 隐式调试端口）/ 9223（独立实例），取有效者 |
| C. 独立实例 | Windows：`chrome.exe --remote-debugging-port=9223 --user-data-dir=<固定目录> about:blank`；macOS：`"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9223 --user-data-dir=<固定目录> about:blank` | 与用户浏览器隔离；Chrome 151+ 首次连接同样可能弹授权 |

### 5.2 Chrome 151+ 远程调试授权（关键机制）

- Chrome 151+ 无论隐式（9222）还是显式（--remote-debugging-port）启动，**CDP 端点默认 404，首次连接会弹「Allow remote debugging?」授权框**；点击「允许」后端点才可用（Chrome 会记住，后续不再弹）
- 弹窗可能出现在**后台窗口**：看不到时打开 `chrome://inspect/#remote-debugging` 页面启用（勾选后同样生效）
- 连接前探测授权状态：Windows（PowerShell）`Invoke-WebRequest http://127.0.0.1:<端口>/json/version` / macOS/Linux（bash/zsh）`curl -s http://127.0.0.1:<端口>/json/version` —— **返回含 "Browser" 的 JSON = 可用**；404/超时 = 未授权或非 CDP

### 5.3 失败排查顺序（按此执行，不跳步）

```
1. doctor：browser-harness doctor（确认工具/daemon/Chrome 三要素）
2. 端口探测：9222 / 9223 / 9224 的 /json/version（IPv4 + IPv6 [::1] 都试）
   - 返回 Browser JSON → 用它（BU_CDP_URL 定向）
   - 404 但端口有监听 → 非 CDP 或未授权（走 5.2 授权）
   - 无监听 → 启动独立实例或等 daemon 自动连接
3. 代理检查：确认 HTTP_PROXY/HTTPS_PROXY 已清（5.1 ①）
4. daemon 异常：browser-harness --reload（重启 daemon 后再试）
5. 仍失败 → 提示用户：Chrome 窗口点「允许」+ chrome://inspect 检查
```

### 5.4 调用示例（准备就绪后）

```bash
BH="$HOME/.local/bin/browser-harness.exe"

# 适度访问 — 打开首页
"$BH" <<'PY'
new_tab("https://www.douyin.com")
wait_for_load()
PY

# 搜索账号
"$BH" <<'PY'
goto_url("https://www.douyin.com/search/{账号ID}?type=user")
wait_for_load()
PY

# 提取页面数据
"$BH" <<'PY'
result = js("""
    return {
        title: document.title,
        html: document.body.innerHTML.substring(0, 5000)
    }
""")
print(result)
PY
```

### 5.5 标签页复用规则（重要，避免窗口/标签页堆积）

**操作 Chrome 前先检查已打开的窗口/标签页：有则直接复用，没有才新建。**

1. **检查已打开标签页**：用 browser-harness 列出当前标签页（`cdp("Target.getTargets", flatten=True)` 或 `page_info()` 查看当前页），确认目标窗口是否已有抖音标签页
2. **有已打开标签页 → 直接复用**：在现有标签页上导航即可——`goto_url("https://www.douyin.com/search/{账号ID}?type=user")` 或先 `goto_url("https://www.douyin.com")` 再搜索；**不要每次 `new_tab` 新建标签页**（多任务串行共用同一 Chrome 时，标签页会无限堆积）
3. **没有标签页/窗口 → 才新建**：`new_tab("https://www.douyin.com")`
4. **用完不关闭**：任务完成后保留标签页（留给后续任务复用），下次任务直接导航到目标地址即可
5. **多任务串行**：多个刷新/导入任务共用同一 9223 Chrome 实例，前一个任务的抖音标签页直接导航复用，无需重新打开

### 5.6 并发互斥（浏览器锁，09-01 新增，多 AI 会话并行时强制）

**背景**：工作台多个 AI 会话任务可并行（客户端并发上限≈3），但浏览器是**共享单实例**（9223 Chrome）。两个任务同时操作会互相导航标签页、丢失对方数据，因此**浏览器操作必须互斥（一次只有一个任务在用浏览器）**。非浏览器操作（解析/提炼/复盘/写脚本，走 MCP/文件）不受影响，可全并行。

**锁规则（每个需要浏览器的任务必须遵守）**：

1. **锁文件位置**：**工作台目录下的 `.browser-lock`**（工作台目录 = 本技能根下的 `mcn-work-shop/`）。工作台 `/api/run` 对浏览器类任务会把**运行时解析出的绝对路径**注入 prompt，AI 会话执行时**以注入的路径为准**；此处不写死盘符。
   - 工作台触发的会话 cwd 即**工作台目录**，故可直接用相对路径 `.browser-lock`（推荐，跨机器可迁移）
   - 手工执行（cwd 不是工作台目录）时，先定位工作台目录再拼 `.browser-lock`
2. **操作前**：检查锁文件是否存在（`ls`）→ 存在则等 10 秒重试（最多 18 次 ≈ 3 分钟）
3. **死锁保护**：锁文件修改时间超过 10 分钟 → 视为死锁，可删除后抢占
4. **拿锁**：`echo "<任务名> <时间戳>" > .browser-lock` → 才操作浏览器
5. **释放**：浏览器操作全部完成后（无论成败）`rm -f .browser-lock`
6. **串行协调**：多个任务抢锁 = 先到先用；拿到锁的任务完成后释放，下一个任务继续；标签页复用规则（5.5）仅在自己持有锁期间适用

```bash
# 前置：确认当前目录就是工作台目录（目录内含 .browser-lock 与 server.js）
# 拿锁（互斥，带重试）
for i in $(seq 1 18); do
  if [ ! -f ".browser-lock" ]; then
    echo "$(date '+%H:%M:%S') ${任务名}" > ".browser-lock"
    break
  fi
  # 死锁保护：锁超过 10 分钟强制抢占
  if [ -f ".browser-lock" ] && [ $(($(date +%s) - $(stat -c %Y ".browser-lock" 2>/dev/null || echo 0))) -gt 600 ]; then
    rm -f ".browser-lock"
    continue
  fi
  sleep 10
done
# ... 浏览器操作 ...
# 释放锁（无论成败）
rm -f ".browser-lock"
```

```bash
# 检查已打开标签页
"$BH" <<'PY'
targets = cdp("Target.getTargets", flatten=True)["targetInfos"]
for t in targets:
    if t.get("type") == "page":
        print(t.get("url", "")[:80])
PY

# 有抖音标签页 → 直接导航复用（不新建）
"$BH" <<'PY'
goto_url("https://www.douyin.com/search/{账号ID}?type=user")
wait_for_load()
PY
```

### 5.7 浏览器进程生命周期（红线，09-02 用户明确）

**已开启的 Chrome 浏览器（9223 调试实例、用户手动开启的 Chrome、daemon 自动连接的实例）一律不主动关闭，除非用户明确要求关闭。**

1. **禁止主动关闭**：任务完成/失败/异常后，不得 `taskkill` / `Stop-Process` / `kill` 已开启的 Chrome 进程；用户没说要关就留着
2. **只关自己启动的临时实例**：仅当本次任务自己用 `--remote-debugging-port` 新启动的、且明确标记为临时用途的实例，才可自行回收；复用已有实例时禁止关闭
3. **工作台/脚本清理**：清理进程（如查占用端口时发现 Chrome）先确认是否为用户在用实例，是则跳过，不清理
4. **为什么要保留**：9223 调试 Chrome 承载登录态/授权记忆/标签页复用，关闭后下次任务需重新启动+重新授权，成本高且可能打断用户正在进行的操作

---

## 六、已知问题

- 抖音网页版需要 JS 渲染，且有限流/验证码机制
- 视频列表懒加载，滚动 2~3 次收集到 SKILL.md「视频获取数量」参数数量即可停止
- 未登录状态下搜索可能被限制，部分功能需要登录
- Chrome 需开启 remote debugging（`chrome://inspect/#remote-debugging`）