feat(monitor): 抖音 Web 接口客户端 —— 绕开爬虫子进程，直接发 HTTP

移植自 mac-agent-os 的 mediacrawler_adapter：不起子进程、不开页面，用浏览器里那份登录态直接调抖音 Web 接口。产物键名照抄 store/douyin，所以 ingest 那条链路一个字不用改。 **目前能用的（真环境实测，非推断）**： profile/other : 200, 7075 字节 —— 博主主页指标（粉丝/获赞/作品数/昵称） aweme/detail : 200, 45425 字节 —— 单条作品详情（含点赞/评论/收藏/分享） **目前不能用的：作品列表 `aweme/post`。** 两个互相独立的原因： 1. 这个接口被抖音单独升级成了真校验：不带 x-tt-argus 回 403「Uifid Not Found」，带上 dummy 值回 200 + **空 body**。也就是说「头在不在」骗得过，「真校验」过不了。同一套头打 profile/other 和 aweme/detail 都是通的 —— 抖音是挑着接口加保护的，挑中的恰好是「批量拉作品列表」这个最敏感的动作。 2. 改走页面截获也不行：CDP 浏览器打开博主主页会落到「验证码中间页」（当天大量探测的代价，过几小时要重测）。所以现在的边界是：**已知作品的指标刷新能做，自动发现新作品做不了**。 **排查中控住变量后得到的两条事实**（都写进注释了）： · `Accept` / `Accept-Language` / `Referer` 才是主页接口能返回真数据的原因 —— 只有 UA+client hints+Cookie 时是 200 但仅 121 字节的空壳，补上这三个头变 7074 字节。（我先前猜的 sec-ch-ua 不是关键。） · 因此 UA 与 client hints 必须**成套地取自同一个浏览器**，所以 BrowserIdentity 一次从 CDP 取齐 cookie + UA + hints，而不是各自写死。「200 + 空 body 必须当场报错」也是刻意写死的：放过去它会在下游变成「这个博主没作品」，把一次失败伪装成一条正常结果 —— 爬虫那条路正是这么栽的，还被翻译成「账号被封」。测试 +11：cookie 解析、请求头成套性（含 uifid 缺失/回退）、产物键名与 store 对齐、以及 _get 的三条失败路径（空 body / 403 带网关原话 / 正常返回）。
2026-10-10 17:12:25 +08:00
parent 21ff01b894
commit 2112c1a870
1601 changed files with 367425 additions and 0 deletions
@@ -0,0 +1,323 @@
+# Matrix 矩阵养号系统 v5.0 使用文档
+
+> 最后更新: 2026-06-11
+> 适用版本: v5.0（PlatformOps 架构）
+> 多机同步: Git + 坚果云
+
+---
+
+## 一、总体架构
+
+```
+mc（统一 CLI 入口）
+  │
+  ├─ mc run → mc/engine.py（纯调度层，~300行）
+  │   └─ PlatformOps.execute()
+  │       ├── DouyinOps（抖音，20+ 操作，platform_ops 接口）
+  │       └── XhsOps（小红书，16 操作，ops/xhs_ops.py）
+  │
+  ├─ mc account → matrix_mgmt.py（账号管理）
+  ├─ mc blueprint → matrix_mgmt.py（蓝图管理）
+  ├─ mc corpus → mc/corpus.py（语料库）
+  └─ mc status → cli.py（状态查询）
+```
+
+### 代码 vs 数据
+
+| | 路径 | 共享方式 |
+|---|---|---|
+| 代码/蓝图 | `agent-sync/05_tools/07_matrix/` | Git 同步 |
+| 账号配置 | `agent-local/tools/matrix/config/accounts.yaml` | 本机独立 |
+| 浏览器指纹 | `agent-local/tools/matrix/identities/{name}/` | 本机独立 |
+| 登录态 | `agent-local/tools/matrix/identities/{name}/user_data/` | 本机独立 |
+| 联邦状态 | `cross_machine/data/matrix/{uid}.json` | Git 同步 |
+
+---
+
+## 二、新机部署
+
+```bash
+# 1. 拉取代码
+cd ~/workbuddy-agent-os/agent-sync
+git pull
+
+# 2. 运行安装脚本（建目录 + 装依赖 + 配置）
+bash 05_tools/07_matrix/install.sh
+
+# 3. 确认 Python 环境
+# mc 会自动检测 Python，或设置环境变量：
+export AGENTOS_PYTHON=~/.workbuddy/binaries/python/envs/agent-os/bin/python3
+
+# 4. 检查可用账号
+cd 05_tools/07_matrix && ./mc account list
+```
+
+---
+
+## 三、账号管理
+
+### 新建账号身份
+
+```bash
+# 创建新身份（生成 BrowserForge 指纹）
+python scripts/create_identity.py --name douyin_new --platform douyin
+
+# 首次登录（浏览器打开，扫码/短信登录）
+./mc account login douyin_new
+```
+
+### 同步已有账号（跨机迁移）
+
+```bash
+# 旧机器导出
+./mc account export    # → 生成压缩包
+
+# 新机器导入
+./mc account import <path_to_export.tar.gz>
+```
+
+---
+
+## 四、cli 命令参考
+
+### 养号执行
+
+```bash
+# 单账号单轮（测试用）
+./mc run --accounts douyin_test --blueprints douyin_active_v1 --rounds 1
+
+# 多账号并行
+./mc run --accounts douyin_test,douyin_133 --blueprints douyin_active_v1 --rounds 3
+
+# 混合多蓝图（每轮随机选）
+./mc run --accounts douyin_test --blueprints douyin_active_v1,douyin_browse_v2 --rounds 3 --mix
+
+# 指定小红书
+./mc run --accounts xhs_01 --blueprints xhs_active_v1 --rounds 2
+
+# 完整参数
+./mc run --accounts A,B --blueprints X,Y --rounds 3 --mix --interval 45-90 --engine auto
+```
+
+### 账号管理
+
+```bash
+./mc account list              # 列表（含登录态）
+./mc account login <name>      # 首次登录
+./mc account status [name]     # 查看状态
+./mc account export            # 导出
+./mc account import <path>     # 导入
+```
+
+### 蓝图管理
+
+```bash
+./mc blueprint list            # 列表
+./mc blueprint show <name>     # 详情
+```
+
+### 状态查询
+
+```bash
+./mc status all                # 全局状态
+./mc status accounts           # 账号列表
+./mc status browsers           # 浏览器进程
+```
+
+### 旧版兼容
+
+旧 `matrix.py` 仍可用但标记 deprecated。对照表：
+
+| 旧命令（matrix.py） | 新命令（mc） |
+|---|---|
+| `python matrix.py account list` | `./mc account list` |
+| `python matrix.py account login X` | `./mc account login X` |
+| `python matrix.py nurture run -a X -r 10` | `./mc run --accounts X --rounds 10 ...` |
+| `python matrix.py status all` | `./mc status all` |
+| `python matrix.py config blueprint list` | `./mc blueprint list` |
+
+---
+
+## 五、蓝图说明
+
+### 抖音蓝图
+
+| 蓝图 | 步骤 | 说明 |
+|------|------|------|
+| `douyin_active_v1` | 27步 | 浏览×6 + 点赞×4 + 评论×2 + 收藏×1 + 搜索×2 |
+| `douyin_browse_v2` | 11步 | 轻量浏览+随机点赞 |
+| `douyin_nurture_v1` | 8步 | 搜索→浏览→点赞→收藏→切换 |
+| `douyin_search_browse` | 7步 | 搜索→浏览→点赞 |
+| `douyin_comment_interact` | 8步 | 浏览→打开评论区→发评论 |
+
+### 小红书蓝图
+
+| 蓝图 | 步骤 | 说明 |
+|------|------|------|
+| `xhs_active_v1` | 26步 | 浏览×5 + 点赞×5 + 搜索×2 + 收藏×2 + 评论×1 + 关注×1 |
+| `xiaohongshu_nurture_v2` | 11步 | 浏览→点击→点赞→收藏→搜索→关注 |
+
+### 蓝图格式
+
+```json
+{
+  "id": "蓝图唯一ID",
+  "name": "显示名称",
+  "platform": "douyin 或 xiaohongshu",
+  "description": "说明",
+  "steps": [
+    {"step_id": 1, "op": "操作名", "args": {}},
+    ...
+  ]
+}
+```
+
+**抖音可用操作**: goto_home, like, collect, follow, open_comments, close_comments, post_comment, next_video, prev_video, search, wait_watch, scroll_feed, open_video, wait, goto_url, go_back
+
+**小红书可用操作**: xhs_goto_home, xhs_browse, xhs_scroll_feed, xhs_click_note, xhs_like, xhs_collect, xhs_comment, xhs_follow, xhs_search, xhs_goto_profile, xhs_read_nickname, xhs_read_user_id, xhs_read_following, xhs_read_fans, xhs_read_likes, xhs_read_bio
+
+---
+
+## 六、自动化任务
+
+### 每日养号
+
+```bash
+# 完整执行
+bash scripts/nurture_daily.sh
+
+# 仅查看命令（不执行）
+bash scripts/nurture_daily.sh --dry
+
+# 仅跑第1组
+bash scripts/nurture_daily.sh --group 1
+```
+
+### 定时执行（cron）
+
+```cron
+# 每天 9:00 和 21:00 执行
+0 9,21 * * * cd ~/workbuddy-agent-os/agent-sync/05_tools/07_matrix && bash scripts/nurture_daily.sh >> /tmp/nurture_daily.log 2>&1
+```
+
+### 定时调度器（旧版兼容）
+
+```bash
+python scripts/task_scheduler.py
+```
+
+---
+
+## 七、多账号并行
+
+`mc run` 原生支持多账号并行。每个账号启动独立 Camoufox 浏览器，窗口自动错位：
+
+| 账号索引 | 窗口位置 | 屏幕区域 |
+|----------|---------|---------|
+| 0 | (30, 30) | 左上 |
+| 1 | (400, 30) | 中上 |
+| 2 | (800, 30) | 右上 |
+| 3 | (30, 450) | 左下 |
+| 4 | (400, 450) | 中下 |
+| 5 | (800, 870) | 右下 |
+
+```bash
+# 3 个抖音同时跑
+./mc run --accounts douyin_test,douyin_133,douyin_133_2 --blueprints douyin_active_v1 --rounds 3
+```
+
+---
+
+## 八、跨机器同步流程
+
+```bash
+# 主机器修改后
+cd ~/workbuddy-agent-os/agent-sync
+git add 05_tools/07_matrix/
+git commit -m "Matrix v5.0 更新"
+git push
+
+# 其他机器
+cd ~/workbuddy-agent-os/agent-sync
+git pull
+bash 05_tools/07_matrix/install.sh   # 如需要重建本地目录
+```
+
+**不同步的内容**（各机器独立）：
+- `agent-local/tools/matrix/config/accounts.yaml` — 账号配置
+- `agent-local/tools/matrix/identities/` — 浏览器指纹 + 登录态
+- `agent-local/tools/matrix/logs/` — 运行日志
+
+---
+
+## 九、v5.0 变更说明
+
+### 新增
+
+- `mc` 统一 CLI（替代 `matrix.py`）
+- `ops/_base.py` — PlatformOps 基类 + OpResult 结构化结果
+- `ops/xhs_ops.py` — 小红书 16 个原子操作
+- `mc/runlog.py` — 结构化运行日志（JSONL）
+- `mc/engine.py` — 重构引擎（～300行，原 775行）
+- `blueprints/douyin_active_v1.json` — 抖音高活跃蓝图
+- `blueprints/xhs_active_v1.json` — 小红书高活跃蓝图
+- `docs/MC_COMMAND_REFERENCE.md` — 命令参考手册
+
+### 改进
+
+- `douyin_ops.py` 实现 PlatformOps 接口，每个操作返回 OpResult
+- `_click_selector` 增加 JS evaluate fallback（穿透 Shadow DOM）
+- `goto_home` 增加 commit 模式 + 强制继续（不因 video 未就绪阻塞）
+- 进入视频模式：从卡片 `data-aweme-id` 提取视频 ID 直接导航（/video/{id}）
+- 视频页双击 video 获取焦点（原代码约定）
+- post_comment 用 pbcopy + Meta+V（Draft.js 兼容）
+- 所有 `force=True` 跳过 Playwright 可点击性检查
+- 硬编码路径修复（Python、用户名）
+- `.gitignore` 排除临时蓝图和一次性脚本
+
+### 废弃
+
+- `matrix.py` — 标记 deprecated（用 mc 替代）
+- `yanghao_runner.py` — 功能合并到 mc
+- `task_engine.py` — 功能合并到 mc/engine.py
+- `camoufox_manager.py` / `camoufox_server.py` — 被 cdp_connector.py 取代
+- `browser_manager.py` / `browser_keepalive.py` — mc/browser.py 取代
+- 25+ 调试脚本 — 移入 `_archive/`
+
+---
+
+## 十、故障排查
+
+### 常见问题
+
+| 问题 | 原因 | 解决 |
+|------|------|------|
+| 页面加载超时 | Camoufox 下 douyin.com 使用 `commit` 模式 | 自动 fallback，强制继续 |
+| like/collect 失败 | Shadow DOM 影响 Playwright locator | 自动 fallback 到 JS evaluate |
+| post_comment 失败 | 评论区无标准输入框 DOM | 不依赖选择器，pbcopy + Meta+V 硬发 |
+| 多账号窗口重叠 | 未设置 window_position | 自动按索引分配错位 |
+| "代理"行消失 | 账号 config.yaml 中 proxy 被注释 | 取消注释恢复代理 |
+
+### 调试命令
+
+```bash
+# 查看运行日志
+cat /tmp/matrix_step_douyin_test.log
+
+# Peekaboo 截图观察
+peekaboo image
+
+# 原子操作诊断
+python scripts/diagnose_ops.py
+```
+
+### 版本信息
+
+当前所有文档统一版本：v5.0.0。文件清单：
+
+- `MODULE.md` — v5.0.0
+- `TOOL.md` — v5.0
+- `mc/__main__.py` — v1.0.0（mc CLI 版本）
+- `docs/MC_COMMAND_REFERENCE.md` — v5.0
+- `blueprints/*.json` — 每个蓝图独立版本
+- `install.sh` — v4.0（未变）