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

Matrix 统— 多机同步标准化指南

版本: v1.0.0
最后更新: 2026-05-01
适用场景: 本机测试完成后，将修改同步到其他电脑

---

1. 同步架构总览

主电脑（Redmi-12C）
    │
    ├── agent-sync/  ←────────── 坚果云 / Gitee ──────────→  agent-sync/（其他电脑）
    │   ├── 02_skills/matrix/        代码 + 文档            │
    │   ├── 05_tools/07_matrix/                             │
    │   └── ...                                              │
    │                                                       │
    └── agent-local/  ←────────── 不同步（每机独立） ────→  agent-local/（其他电脑）
        └── tools/matrix/                                    │
            ├── config/accounts.yaml     (手动配置)          │
            ├── profiles/                (手动登录)          │
            ├── data/cookies/            (重新导出)          │
            └── data/matrix.db           (重新初始化)        │

同步内容清单

类别	内容	同步方式	是否同步
代码脚本	scripts/*.py, *.sh	Git + 坚果云	✅
蓝图文件	blueprints/*.json	Git + 坚果云	✅
标准化文档	docs/*.md	Git + 坚果云	✅
技能定义	02_skills/matrix/	Git + 坚果云	✅
安装脚本	install.sh	Git + 坚果云	✅
依赖清单	requirements.txt	Git + 坚果云	✅
配置模板	config_template/	Git + 坚果云	✅
local.yaml	本机路径配置	每机独立生成	❌
accounts.yaml	手机号/端口	每机手动配置	❌
Chrome Profile	浏览器登录数据	每机重新登录	❌
Cookie 文件	data/cookies/	每机重新导出	❌
matrix.db	执行记录/DB	每机重新初始化	❌
Python venv	安装的包	每机重新安装	❌
Playwright Chromium	浏览器二进制	每机重新安装	❌
Camoufox	Firefox 浏览器	每机重新安装	❌

---

2. 标准化同步流程

2.1 在主电脑上提交修改

# 1. 确认所有修改已保存
cd ~/workbuddy-agent-os/agent-sync

# 2. 查看修改文件
git status
# 预期看到:
#   modified:  02_skills/matrix/SKILL.md
#   modified:  05_tools/07_matrix/scripts/switch_account.py
#   modified:  05_tools/07_matrix/scripts/cdp_connector.py
#   new file:  05_tools/07_matrix/scripts/auth_manager.py
#   modified:  05_tools/07_matrix/docs/FULL_TEST_REPORT.md
#   new file:  05_tools/07_matrix/docs/SYSTEM_ARCHITECTURE.md
#   new file:  05_tools/07_matrix/docs/SYNC_GUIDE.md

# 3. 提交并推送
git add -A
git commit -m "Matrix 系统修复: 原子化登录模块 + 稳定性修复"
git push origin main

注意: 坚果云会同步 agent-sync/ 目录下的文件修改，但建议以 Git 为主要版本控制手段，坚果云仅作为文件快速分发。两台电脑都需要安装坚果云并登录同一账号。

2.2 在其他电脑上拉取更新

# 方式A: 通过 Git（推荐，版本可控）
cd ~/workbuddy-agent-os/agent-sync
git pull origin main

# 方式B: 通过坚果云（自动同步）
# 确保两台电脑登录同一坚果云账号，agent-sync/ 目录会自动同步

2.3 在新电脑上运行安装脚本

# 1. 运行一键安装（建立目录骨架 + 安装依赖 + 生成配置）
bash ~/workbuddy-agent-os/agent-sync/05_tools/07_matrix/install.sh

# 2. 安装 Camoufox（额外的 Firefox 浏览器）
~/workbuddy-agent-os/agent-sync/05_tools/07_matrix/scripts/install_camoufox.sh
# 或手动:
# pip install camoufox
# python -m camoufox fetch

2.4 配置本地账号

# 编辑本机 accounts.yaml（手机号/端口/备注按本机设置）
vim ~/workbuddy-agent-os/agent-local/tools/matrix/config/accounts.yaml

# 必须修改的字段:
# - phone: 本机对应的手机号
# - port: 确保端口不冲突（Chrome: 9222+, Camoufox: 9301+）

2.5 初始化数据库（可选）

# 如果新机没有 matrix.db，初始化一个
cd ~/workbuddy-agent-os/agent-sync/05_tools/07_matrix
~/workbuddy-agent-os/agent-sync/05_tools/07_matrix/scripts/init_db.py

2.6 重新登录各平台

# 每个账号需要重新手动登录一次
# Chrome 方案:
cd ~/workbuddy-agent-os/agent-sync/05_tools/07_matrix
python scripts/switch_account.py --method profile --target douyin_01 --port 9222
# → 浏览器打开 douyin.com，扫码登录
# → 登录后自动检测 Cookie → 自动导出到 data/cookies/

# Camoufox 方案:
python scripts/yanghao_runner.py --account douyin_camo01 --blueprint douyin_browse_v2 --browser camoufox

---

3. 本地依赖完整清单

以下是在新电脑上需要重新部署的所有本地依赖：

3.1 Python 包

# 使用 agent-os 的 Python 环境
PY=~/workbuddy-agent-os/agent-sync/05_tools/07_matrix/install.sh 自动处理

# 或手动安装:
pip install -r ~/workbuddy-agent-os/agent-sync/05_tools/07_matrix/requirements.txt
# 包含: patchright, camoufox, PyYAML

3.2 Playwright 浏览器

# Chromium（Chrome 方案需要）
python -m patchright install chromium

# 注意: 不需要 firefox（Camoufox 自带 Firefox）

3.3 Camoufox 浏览器

# Camoufox 方案需要
pip install camoufox
python -m camoufox fetch
# 下载到: ~/Library/Caches/camoufox/Camoufox.app/

3.4 本地目录结构

agent-local/tools/matrix/
├── config/
│   └── accounts.yaml          # 手动配置（每机不同）
├── data/
│   ├── cookies/               # 登录后自动导出
│   ├── camoufox_pids/         # 运行时自动创建
│   └── matrix.db              # init_db.py 初始化
├── profiles/
│   ├── account_01/            # 登录后自动生成
│   ├── douyin_02/
│   ├── camoufox_01/
│   └── camoufox_02/
├── logs/                      # 运行时日志
└── screenshots/               # 可选

---

4. 版本对照表

每次修改后，在主电脑上记录修改范围，方便其他电脑核对自己是否拉取了最新代码。

v2.1.0 (2026-05-01) 修改清单

文件	修改类型	说明
scripts/auth_manager.py	新增	原子化登录模块（Cookie 检测/导出/注入）
scripts/switch_account.py	修改	登录检测改为 auth_manager，自动导出 Cookie
scripts/cdp_connector.py	修改	添加 os=windows / 中文字体 / 委托 auth_manager
02_skills/matrix/SKILL.md	修改	更新正确入口、新增原子模块说明
docs/FULL_TEST_REPORT.md	修改	新增修复记录、已验证功能
docs/SYSTEM_ARCHITECTURE.md	新增	全链路系统架构文档
docs/ACCOUNT_LOGIN_SOP.md	新增	账号登录标准化操作流程
docs/SYNC_GUIDE.md	新增	多机同步指南（本文）
blueprints/douyin_browse_v3.json	DB注册	已在主电脑注册到 task_blueprints
blueprints/douyin_nurture_v1.json	DB注册	同上
profiles/douyin_01/	删除	冗余目录（11MB）

新机注意事项:

• DB 注册的蓝图（v3/nurture）需在新机重新运行 init_db.py 或在首次使用时自动注册
• 删除冗余目录是主电脑操作，新机没有这个目录，无需处理

---

5. 常见问题

Q: 为什么不能直接复制 Chrome Profile？

Chrome Profile 包含设备绑定的加密数据（Cookie 用本机密钥加密），复制到其他电脑会失效。必须在新机重新扫码登录。

Q: 为什么 accounts.yaml 不能同步？

每个账号绑定的手机号是固定的，但不同电脑上 Chrome Profile 目录路径和端口分配可能不同（例如一台电脑 9222 已占用，需要用 9224）。

Q: 主电脑上的修改如何确保不丢失？

# 养成好习惯：每次修改后
cd ~/workbuddy-agent-os/agent-sync
git add -A
git commit -m "描述修改内容"
git push origin main

Q: 新电脑需要安装什么额外软件？

• 坚果云（同步 agent-sync/ 文件）
• Git（拉取代码）
• Chrome 浏览器（养号工具使用）
• agent-os 的 Python 环境（install.sh 自动处理）

---

6. 快速检查清单

新机部署完成后，逐项确认：

• Git pull 或坚果云同步完成
• install.sh 运行成功
• Camoufox 安装完成（如需要）
• accounts.yaml 已配置本机账号
• matrix.db 已初始化
• Chrome Profile 已重新登录
• Cookie 已自动导出
• python scripts/switch_account.py --status 显示 active
• python scripts/auth_manager.py 9222 显示 sessionid ✅