MediaCrawler/mac-agent-os-main/05_tools/07_matrix/docs/MATRIX_V5_GUIDE.md

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 同步

---

二、新机部署

# 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

---

三、账号管理

新建账号身份

# 创建新身份（生成 BrowserForge 指纹）
python scripts/create_identity.py --name douyin_new --platform douyin

# 首次登录（浏览器打开，扫码/短信登录）
./mc account login douyin_new

同步已有账号（跨机迁移）

# 旧机器导出
./mc account export    # → 生成压缩包

# 新机器导入
./mc account import <path_to_export.tar.gz>

---

四、cli 命令参考

养号执行

# 单账号单轮（测试用）
./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

账号管理

./mc account list              # 列表（含登录态）
./mc account login <name>      # 首次登录
./mc account status [name]     # 查看状态
./mc account export            # 导出
./mc account import <path>     # 导入

蓝图管理

./mc blueprint list            # 列表
./mc blueprint show <name>     # 详情

状态查询

./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步	浏览→点击→点赞→收藏→搜索→关注

蓝图格式

{
  "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 scripts/nurture_daily.sh

# 仅查看命令（不执行）
bash scripts/nurture_daily.sh --dry

# 仅跑第1组
bash scripts/nurture_daily.sh --group 1

定时执行（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

定时调度器（旧版兼容）

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)	右下

# 3 个抖音同时跑
./mc run --accounts douyin_test,douyin_133,douyin_133_2 --blueprints douyin_active_v1 --rounds 3

---

八、跨机器同步流程

# 主机器修改后
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 被注释	取消注释恢复代理

调试命令

# 查看运行日志
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（未变）