MediaCrawler/mac-agent-os-main/archive_docs/matrix_docs/PROJECT_OVERVIEW.md

矩阵养号系统 Matrix — 完整项目说明

项目版本: v3.0（2026-04-28） 负责人: ghai 最后更新: 2026-04-28

---

一、项目概述

1.1 什么是矩阵养号系统

矩阵养号系统是一个自动化社交账号运营工具，通过程序化控制浏览器完成抖音、小红书、知乎等平台的日常养号任务。目标是让多个账号模拟真实用户行为，提升账号权重和活跃度。

1.2 核心价值

价值点	说明
自动化	告别手动操作，自动执行浏览、点赞、评论、收藏等任务
多账号	支持同时管理多个账号，每个账号独立隔离
反检测	内置多种反检测措施，降低被平台识别为机器人的风险
可扩展	支持多平台、蓝图化任务、灵活配置
可迁移	完整的环境配置和迁移方案

1.3 支持平台

平台	状态	核心功能
抖音	✅ 已实现	推荐浏览、搜索、点赞、收藏、评论、关注
小红书	🔄 框架完成	需登录账号
知乎	🔄 框架完成	需登录账号
快手	📋 规划中	待开发

---

二、宏伟蓝图与目标

2.1 最终愿景

打造一个全平台、智能化、可持续的社交账号矩阵运营系统

2.2 发展阶段规划

阶段A ✅ 已完成（2026-04-27）
├── Chrome CDP 直连
├── 抖音原子操作库 V2（18个操作）
├── 蓝图执行引擎
├── 定时调度器
├── 账号切换器（双方案）
├── 指纹注入
└── 双账号并行

阶段B 🔄 进行中
├── Camoufox（Firefox内核）集成 ← 当前卡点
├── 多浏览器内核支持
├── 提升反检测能力
└── 第二个账号登录

阶段C 📋 规划中
├── 鼠标轨迹仿真
├── 语料库完善
├── Canvas/AudioContext 指纹噪声
└── 静态住宅IP接入

阶段D 📋 规划中
├── 小红书完整支持
├── 知乎完整支持
├── 多平台联动
└── 智能行为决策

2.3 里程碑目标

阶段	目标账号数	反检测等级	自动化程度
A	1-2个	⭐⭐	半自动（需手动登录）
B	2-4个	⭐⭐⭐	半自动（Camoufox）
C	4-8个	⭐⭐⭐⭐	全自动
D	10+个	⭐⭐⭐⭐⭐	全自动+智能决策

---

三、项目架构

3.1 整体架构图

┌─────────────────────────────────────────────────────────────────┐
│                         用户指令 / 定时触发                        │
└─────────────────────────────────────────────────────────────────┘
                                  ↓
┌─────────────────────────────────────────────────────────────────┐
│                      蓝图引擎 (task_engine.py)                    │
│                      定时调度 (task_scheduler.py)                   │
└─────────────────────────────────────────────────────────────────┘
                                  ↓
┌─────────────────────────────────────────────────────────────────┐
│                     原子操作库 (douyin_ops.py)                     │
│                     18个最小操作单元，含前置检查+执行+后置验证          │
└─────────────────────────────────────────────────────────────────┘
                                  ↓
┌─────────────────────────────────────────────────────────────────┐
│                     账号切换器 (switch_account.py)                  │
│              方案A: Chrome Profile切换  方案B: Cookie注入            │
└─────────────────────────────────────────────────────────────────┘
                                  ↓
┌─────────────────────────────────────────────────────────────────┐
│  ┌──────────────────┐         ┌──────────────────┐              │
│  │   Chrome CDP      │         │   Camoufox       │              │
│  │   端口 9222/9223  │         │   端口 9301/9302 │              │
│  │   ✅ 已完成       │         │   🔄 进行中      │              │
│  └──────────────────┘         └──────────────────┘              │
└─────────────────────────────────────────────────────────────────┘
                                  ↓
┌─────────────────────────────────────────────────────────────────┐
│                     抖音网页 / 小红书 / 知乎                         │
└─────────────────────────────────────────────────────────────────┘

3.2 核心组件

组件	文件	职责
原子操作库	scripts/douyin_ops.py	封装18个浏览器操作
CDP连接器	scripts/cdp_connector.py	管理Chrome CDP连接
账号切换器	scripts/switch_account.py	多账号Profile切换
Camoufox管理	scripts/camoufox_manager.py	Firefox内核管理
蓝图引擎	scripts/task_engine.py	读取执行JSON蓝图
定时调度	scripts/task_scheduler.py	Cron定时任务
数据库	data/matrix.db	账号、蓝图、日志存储

3.3 数据流

蓝图JSON → 引擎解析 → 操作序列 → CDP执行 → 页面响应 → 日志记录
              ↓
         频率控制（防封）
              ↓
         错误恢复（自动重试）
              ↓
         结果统计（数据库）

---

四、环境依赖

4.1 系统要求

项目	要求	当前环境
操作系统	macOS (Apple Silicon)	✅ macOS
Python	3.13+	✅ 3.13.12
Chrome	最新版	✅ 已安装
磁盘空间	10GB+	✅ 充足

4.2 Python环境

# 使用的Python路径
/Users/7kecheng/.workbuddy/binaries/python/versions/3.13.12/bin/python3

必须安装的包:

pip install patchright camoufox pyyaml aiosqlite

4.3 浏览器

浏览器	用途	状态	端口
Chrome	主要浏览器	✅ 已配置	9222/9223
Camoufox	Firefox内核（反检测更强）	🔄 配置中	9301/9302

4.4 目录结构

~/matrix/
├── docs/                           # 项目文档
│   ├── PROJECT_OVERVIEW.md         # 本文件（项目总览）
│   ├── DOUYIN_FULL_PLAN.md         # 抖音完整方案
│   ├── DOUYIN_SELECTORS.md         # 选择器手册
│   ├── PHASE_A_SUMMARY.md          # 阶段A完成总结
│   ├── CAMOUFOX_LOGIN_MANAGEMENT.md # Camoufox集成方案
│   ├── IP_SWITCH_GUIDE.md          # IP切换指南
│   ├── IMPLEMENTATION_GUIDE.md     # 落地手册
│   └── LOCAL_ADAPTATION.md         # 本地适配说明
├── scripts/                        # 核心脚本
│   ├── douyin_ops.py               # 原子操作库（18操作）
│   ├── cdp_connector.py            # CDP连接器
│   ├── switch_account.py           # 账号切换器
│   ├── camoufox_manager.py         # Camoufox管理器
│   ├── task_engine.py              # 蓝图引擎
│   ├── task_scheduler.py           # 定时调度
│   ├── seed_db.py                  # 数据库初始化
│   ├── init_db.py                  # 数据库初始化
│   └── launch_chrome.sh            # Chrome启动脚本
├── blueprints/                     # 任务蓝图
│   ├── douyin_browse_v2.json       # 日常浏览V2（11步）
│   ├── douyin_search_browse.json   # 搜索浏览（7步）
│   ├── douyin_comment_interact.json # 评论互动（8步）
│   └── douyin_browse.json          # 日常浏览V1（已废弃）
├── config/                         # 配置文件
│   └── accounts.yaml               # 账号配置
├── data/                           # 数据存储
│   ├── matrix.db                   # SQLite数据库
│   ├── cookies/                    # Cookie存储
│   └── camoufox_pids/             # Camoufox进程PID
├── profiles/                       # 浏览器Profile
│   ├── account_01/                 # 抖音主号Profile
│   ├── douyin_02/                  # 抖音副号Profile
│   ├── camoufox_01/               # Camoufox账号1
│   └── camoufox_02/               # Camoufox账号2
├── corpus/                         # 语料库
├── logs/                           # 日志
├── screenshots/                    # 截图存档
└── docker/                         # Docker配置（未来）

---

五、当前状态

5.1 已完成功能

✅ 阶段A：Chrome CDP 方案

功能	状态	说明
CDP直连Chrome	✅ 完成	Patchright connect_over_cdp
原子操作库V2	✅ 完成	18个操作，含前置检查+后置验证
蓝图引擎	✅ 完成	JSON蓝图顺序执行
定时调度	✅ 完成	Cron表达式调度
账号切换器	✅ 完成	Profile切换+Cookie注入
指纹注入	✅ 完成	视口+时区+语言+WebGL
双账号并行	✅ 完成	端口9222+9223

🔄 阶段B：Camoufox 集成（进行中）

功能	状态	说明
Camoufox包安装	✅ 完成	v3.0.0
Camoufox浏览器下载	✅ 完成	v135.0.1-beta.24
Profile目录创建	✅ 完成	camoufox_01, camoufox_02
Camoufox启动	🔄 卡住	executable_path配置问题
Camoufox登录	⏸ 待开始	需启动后才能登录
Camoufox CDP连接	⏸ 待开始	需登录后验证

5.2 账号状态

账号ID	平台	端口	浏览器	状态
douyin_01	抖音	9222	Chrome	✅ 已登录
douyin_02	抖音	9223	Chrome	⏸ 待登录
xhs_01	小红书	9224	Chrome	⏸ 待注册
zhihu_01	知乎	9225	Chrome	⏸ 待注册
douyin_camo01	抖音	9301	Camoufox	🔄 配置中
douyin_camo02	抖音	9302	Camoufox	🔄 配置中

5.3 蓝图状态

蓝图ID	名称	步骤数	状态	备注
douyin_browse_v2	日常浏览V2	11步	✅ 活跃	推荐使用
douyin_search_browse	搜索浏览	7步	✅ 活跃	-
douyin_comment_interact	评论互动	8步	✅ 活跃	-
douyin_browse	日常浏览V1	8步	⛔ 废弃	不再使用

---

六、遇到的问题

6.1 Camoufox 启动问题（当前卡点）

问题描述：

FileNotFoundError: [Errno 2] No such file or directory: 
'/Users/7kecheng/Library/Caches/camoufox/Camoufox.app/Contents/MacOS/properties.json'

原因分析：

• Camoufox 浏览器缓存文件不完整
• camoufox_manager.py 中显式指定的 executable_path 导致路径查找错误
• properties.json 文件实际位于 Resources 目录，而非 MacOS 目录

已尝试的解决：

1. ✅ 清理缓存 rm -rf ~/Library/Caches/camoufox
2. ✅ 重新下载 camoufox fetch
3. ✅ 修改脚本移除显式 executable_path 路径

当前状态：

• 已修改 camoufox_manager.py 第148-154行
• 等待下次启动验证

6.2 踩坑记录（历史问题，已解决）

问题	日期	原因	解决方案
hash() 跨进程不一致	2026-04-27	Python随机种子	改用 sum(ord(c))
移动端UA覆盖破坏登录	2026-04-27	Android UA导致Cookie校验失败	不覆盖UA
移动端视口破坏登录	2026-04-27	mobile: True改变渲染	mobile: False
视口过窄	2026-04-27	初始参数480px	实测702x783最佳
Profile目录名错误	2026-04-27	配置与实际不符	修正accounts.yaml

---

七、下一步计划

7.1 立即任务（今天）

优先级	任务	状态	操作
P0	Camoufox启动验证	🔄 进行中	移除executable_path后重新启动
P0	douyin_camo01登录	⏸ 等待	启动后手动扫码登录
P0	导出Cookie	⏸ 等待	登录后导出备份

7.2 短期任务（本周）

优先级	任务	预计时间
P0	Camoufox CDP连接验证	1小时
P1	鼠标轨迹仿真	4小时
P1	语料库填充	1小时
P2	douyin_02登录	1小时

7.3 中期任务（本月）

优先级	任务	预计时间
P1	静态住宅IP接入	按服务商
P2	Cookie方案B完善	4小时
P3	小红书支持	1天
P3	知乎支持	1天

7.4 长期任务（未来）

任务	说明
多平台联动	抖音→小红书→知乎互动联动
智能决策	AI驱动的行为决策
Docker容器化	完全隔离的多容器部署

---

八、如何执行

8.1 快速开始

# 1. 进入项目目录
cd ~/matrix

# 2. 查看帮助
/Users/7kecheng/.workbuddy/binaries/python/versions/3.13.12/bin/python3 scripts/switch_account.py --help

# 3. 启动Chrome账号（方案A）
/Users/7kecheng/.workbuddy/binaries/python/versions/3.13.12/bin/python3 scripts/switch_account.py --method profile --target douyin_01 --port 9222

# 4. 查看状态
/Users/7kecheng/.workbuddy/binaries/python/versions/3.13.12/bin/python3 scripts/switch_account.py --status

8.2 执行蓝图

# 执行日常浏览蓝图
/Users/7kecheng/.workbuddy/binaries/python/versions/3.13.12/bin/python3 scripts/task_engine.py --blueprint douyin_browse_v2 --account douyin_01

# 执行搜索浏览蓝图
/Users/7kecheng/.workbuddy/binaries/python/versions/3.13.12/bin/python3 scripts/task_engine.py --blueprint douyin_search_browse --account douyin_01

8.3 Camoufox操作（待修复后）

# 启动Camoufox
/Users/7kecheng/.workbuddy/binaries/python/versions/3.13.12/bin/python3 scripts/camoufox_manager.py --launch douyin_camo01

# 验证登录
/Users/7kecheng/.workbuddy/binaries/python/versions/3.13.12/bin/python3 scripts/camoufox_manager.py --verify douyin_camo01

# 导出Cookie
/Users/7kecheng/.workbuddy/binaries/python/versions/3.13.12/bin/python3 scripts/camoufox_manager.py --export douyin_camo01

8.4 定时调度

# 添加每日任务（每天9点执行）
/Users/7kecheng/.workbuddy/binaries/python/versions/3.13.12/bin/python3 scripts/task_scheduler.py --add "douyin_browse_v2" --cron "0 9 * * *"

---

九、迁移方案

9.1 迁移准备清单

迁移前需要准备以下内容：

□ 源码目录 ~/matrix/
□ Profile目录 ~/matrix/profiles/
□ Cookie备份 ~/matrix/data/cookies/
□ 配置文件 config/accounts.yaml
□ 浏览器安装（Chrome / Camoufox）
□ Python 3.13+ 环境
□ pip 包（patchright, camoufox, pyyaml）

9.2 完整迁移步骤

# 1. 打包源码（排除大文件和缓存）
rsync -av --exclude='profiles/*/Cache' \
      --exclude='logs/*.log' \
      --exclude='.DS_Store' \
      ~/matrix/ /path/to/backup/matrix/

# 2. 打包Profile（选择性迁移登录状态）
rsync -av ~/matrix/profiles/account_01/ /path/to/backup/profiles/account_01/

# 3. 打包Cookie
rsync -av ~/matrix/data/cookies/ /path/to/backup/cookies/

# 4. 在新机器安装依赖
pip install patchright camoufox pyyaml aiosqlite

# 5. 下载Camoufox浏览器
python3 -m camoufox fetch

# 6. 启动Chrome并验证
python3 scripts/switch_account.py --status

9.3 迁移后检查

# 检查Python环境
python3 --version  # 应为3.13+

# 检查pip包
pip list | grep -E "patchright|camoufox|pyyaml"

# 检查Chrome
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --version

# 检查Camoufox
python3 -m camoufox path

# 初始化数据库
python3 scripts/init_db.py

# 测试CDP连接
python3 scripts/switch_account.py --status

9.4 注意事项

1. Profile迁移：Cookie和登录状态在Profile中，整体迁移最简单
2. Camoufox：每个平台需要单独下载浏览器
3. 代理配置：如果使用代理，迁移后需更新账号配置
4. 端口占用：确保9222-9322端口未被占用

---

十、常见问题

Q1: Chrome无法启动？

# 检查Chrome是否安装
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --version

# 检查端口是否被占用
lsof -i :9222

Q2: CDP连接失败？

# 启动Chrome时添加CDP端口
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-port=9222 \
  --user-data-dir=~/matrix/profiles/account_01

Q3: Camoufox下载失败？

# 设置代理后重试
export https_proxy=http://127.0.0.1:7890
python3 -m camoufox fetch

Q4: 账号被封禁？

• 降低操作频率
• 使用静态住宅IP
• 增加随机延迟
• 模拟真实用户行为

---

十一、联系方式

• 项目负责人: ghai
• 项目目录: ~/matrix/
• 文档目录: ~/matrix/docs/

---

附录A：关键文件路径速查

文件	路径
项目根目录	~/matrix/
账号配置	~/matrix/config/accounts.yaml
原子操作库	~/matrix/scripts/douyin_ops.py
CDP连接器	~/matrix/scripts/cdp_connector.py
账号切换器	~/matrix/scripts/switch_account.py
Camoufox管理	~/matrix/scripts/camoufox_manager.py
数据库	~/matrix/data/matrix.db
Cookie存储	~/matrix/data/cookies/
Profile存储	~/matrix/profiles/

附录B：环境变量速查

变量	值
PYTHON	/Users/7kecheng/.workbuddy/binaries/python/versions/3.13.12/bin/python3
CHROME	/Applications/Google Chrome.app/Contents/MacOS/Google Chrome
CAMOUFOX_CACHE	~/Library/Caches/camoufox/
PROJECT_DIR	~/matrix/

---

文档版本: v1.0 创建日期: 2026-04-28 更新日期: 2026-04-28