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

Matrix 养号系统 · 操作手册

本手册定义所有任务的标准化创建流程。

---

一、文件结构

~/matrix/
├── config/
│   ├── accounts.yaml      ← 账号配置（手机/端口/Profile路径）
│   └── tasks.yaml         ← 任务调度配置（蓝图+账号+开关）
├── blueprints/            ← 所有蓝图放这里
│   ├── douyin_browse.json
│   ├── xiaohongshu_like.json
│   └── zhihu_read.json
├── scripts/
│   ├── launch_chrome.sh   ← 启动 Chrome 调试模式
│   ├── cdp_connector.py   ← CDP 连接器（连接 Chrome + 反检测）
│   ├── task_engine.py     ← 蓝图执行引擎
│   ├── task_scheduler.py  ← 定时调度器
│   └── init_db.py         ← 数据库初始化
├── data/
│   └── matrix.db          ← SQLite 数据库
└── profiles/
    └── account_01/        ← 账号 Cookie（自动保存）
        └── Default/       ← Chrome Profile 目录

---

二、日常操作（每日标准流程）

1. 启动 Chrome 调试模式

bash ~/matrix/scripts/launch_chrome.sh account_01 9222

2. 手动登录（如需新账号）

在 Chrome 里登录平台 → Cookie 自动保存到 ~/matrix/profiles/<账号>/

3. 执行单个蓝图

python3 ~/matrix/scripts/task_engine.py <蓝图名> --account <账号ID> --port <端口>

# 示例：执行抖音浏览蓝图
python3 ~/matrix/scripts/task_engine.py douyin_browse --account account_01

# 示例：执行小红书点赞蓝图
python3 ~/matrix/scripts/task_engine.py xiaohongshu_like --account account_01

4. 预览蓝图（不连接浏览器）

python3 ~/matrix/scripts/task_engine.py <蓝图名> --dry-run

5. 定时自动跑

# 前台运行
python3 ~/matrix/scripts/task_scheduler.py

# 或用 cron/launchd 定时触发
python3 ~/matrix/scripts/task_scheduler.py --once

---

三、标准化：新增一个完整任务

假设要新增「小红书点赞养号」任务，需要修改/新增以下 3 个文件：

Step 1 → 新增蓝图文件

文件：~/matrix/blueprints/xiaohongshu_like.json

{
  "id": "xiaohongshu_like",
  "name": "小红书点赞互动",
  "platform": "xiaohongshu",
  "version": "1.0.0",
  "description": "浏览发现页，随机点赞收藏评论",
  "steps": [
    {
      "op": "goto",
      "args": { "url": "https://www.xiaohongshu.com" },
      "wait_after": 3,
      "retry": 2
    },
    {
      "op": "remove_overlays",
      "args": {},
      "wait_after": 1
    },
    {
      "op": "swipe_up",
      "args": { "distance": 600, "duration_ms": 500 },
      "wait_after": 5,
      "wait_jitter": 1
    },
    {
      "op": "evaluate",
      "args": {
        "script": "() => { const btn = document.querySelector('[class*=like]'); if(btn) btn.click(); }"
      },
      "wait_after": 2
    },
    {
      "op": "swipe_up",
      "args": { "distance": 600, "duration_ms": 450 },
      "wait_after": 10,
      "wait_jitter": 2
    }
  ]
}

Step 2 → 注册到任务配置

文件：~/matrix/config/tasks.yaml

tasks:
  - id: daily_xhs_like
    name: 小红书点赞互动
    blueprint: xiaohongshu_like      # ← 对应 blueprints/*.json 的文件名
    accounts:
      - account_01
    enabled: true                    # true=启用，false=禁用

Step 3 → 如果是新平台，添加账号配置

文件：~/matrix/config/accounts.yaml

accounts:
  - id: account_02
    platform: xiaohongshu
    phone: "13800001111"
    port: 9223                       # 每个账号用不同端口
    profile_dir: profiles/xhs_02
    enabled: true

---

四、蓝图操作参考

支持的操作（op 字段）

op	说明	关键参数
goto	导航到 URL	url
wait	等待秒数	seconds
swipe_up	向上滑动	distance(px), duration_ms
swipe_down	向下滑动	distance(px), duration_ms
touch_tap	触摸点击坐标	x, y
evaluate	执行 JS	script（返回 ()=>{...} 函数）
click	点击元素	selector
fill	填写输入框	selector, value
press	按键	selector, key
screenshot	截图	path（可选）
remove_overlays	清理 App 弹窗	无参数
wait_for	等待元素出现	selector, timeout

步骤级配置

每个步骤可额外设置：

{
  "op": "goto",
  "args": { "url": "https://..." },
  "wait_after": 3,      // 步骤执行后等待 3 秒
  "wait_jitter": 0.5,   // 等待时间随机抖动 ±0.5 秒
  "retry": 2            // 失败重试 2 次
}

---

五、进阶配置

多账号并发

每个账号用独立 Chrome 调试端口，示例：

# 账号1 → 端口9222
bash ~/matrix/scripts/launch_chrome.sh account_01 9222

# 账号2 → 端口9223
bash ~/matrix/scripts/launch_chrome.sh account_02 9223

熔断机制（自动）

连续失败 3 次自动暂停 30 分钟，人工介入后自动恢复。

数据库执行记录

所有执行自动写入 ~/matrix/data/matrix.db，可用 sqlite3 查看：

sqlite3 ~/matrix/data/matrix.db "SELECT * FROM executions ORDER BY created_at DESC LIMIT 10;"

---

六、故障排查

症状	原因	处理
HTTP Error 502	urllib 走了代理	检查 cdp_connector.py 是否用 ProxyHandler({})
Emulation.setTouchEmulationOverride 报错	Chrome 147 移除了此 API	升级 cdp_connector.py
webSocketDebuggerUrl 获取失败	Chrome 未启动调试模式	先运行 launch_chrome.sh
步骤执行正常但页面空白	窗口尺寸太小	修改 launch_chrome.sh 的 --window-size
Cookie 丢失	Profile 路径不一致	确认 accounts.yaml 中 profile_dir 正确