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

# Douyin 全模拟运营系统架构 v1.0

> 最后更新: 2026-05-15
> 基于 AgentOS 多机协同体系

---

## 设计原则

1. **代码走同步，数据留本机** — 脚本在 agent-sync (Gitee)，工作区在 agent-local (不参与同步)
2. **四层隔离** — 管理层/流水线层/操作层/数据层，每层独立演进
3. **每账号独立工作区** — 身份、素材、文案、发布记录各自独立
4. **原子操作可组合** — 所有操作遵循 `前置锚点 → 执行 → 后置锚点` 模式
5. **与现有养号系统共存** — 新架构不破坏 `matrix.py` / `nurture_blueprint.py`

---

## 目录结构

```
~/workbuddy-agent-os/
├── agent-sync/                              ← Gitee 同步（代码/技能）
│   └── 05_tools/
│       └── 07_matrix/
│           ├── ARCHITECTURE.md              ← 本文档
│           ├── scripts/
│           │   ├── matrix.py                ← 统一 CLI
│           │   ├── atom_ops.py              ← 原子操作库
│           │   ├── nurture_blueprint.py     ← 养号蓝图
│           │   ├── douyin_ops.py            ← 抖音专用操作
│           │   ├── matrix_modules/          ← 子模块
│           │   ├── pipelines/               ← [新] 流水线脚本
│           │   │   ├── __init__.py
│           │   │   ├── content_publish.py   ← 内容发布流水线（待建）
│           │   │   ├── ecom_pipeline.py     ← 电商流水线（待建）
│           │   │   └── live_pipeline.py     ← 直播流水线（待建）
│           │   └── ops/                     ← 平台操作
│           └── blueprints/
│
├── agent-local/                             ← 本机数据（不参与同步）
│   └── tools/
│       └── matrix/
│           ├── config/
│           │   └── accounts.yaml            ← 账号注册信息
│           ├── identities/                  ← 浏览器指纹+登录态
│           │   ├── douyin_01_camo/
│           │   ├── douyin_02_camo/
│           │   └── douyin_camo01/
│           └── accounts/                    ← [新] 每账号工作区
│               ├── douyin_01/
│               │   ├── content/             ← 视频素材
│               │   │   ├── raw/             ← 原始素材
│               │   │   ├── edited/          ← 剪辑成品
│               │   │   └── thumbnails/      ← 封面图
│               │   ├── scripts/             ← 脚本文案
│               │   │   ├── drafts/          ← 草稿
│               │   │   └── posted/          ← 已发布
│               │   ├── publish/             ← 发布记录
│               │   │   ├── queue/           ← 待发布队列
│               │   │   └── published/       ← 已发布记录
│               │   └── backup/
│               │       └── cookies/         ← 登录态备份
│               ├── douyin_02/               ← 同上
│               └── douyin_camo01/           ← 同上
```

---

## 四层架构

### Layer 1: 数据层（本机，不同步）

每个账号独立文件夹，包含四类数据：

| 子目录 | 用途 | 数据来源 |
|:-------|:-----|:---------|
| `content/` | 视频素材（raw/edited/thumbnails） | 外部导入 / 剪辑 |
| `scripts/` | 脚本文案（drafts/posted） | AI 生成 / 手动编写 |
| `publish/` | 发布队列 + 历史记录 | 系统自动写入 |
| `backup/` | 登录态备份 | 系统自动备份 |

### Layer 2: 操作层（代码，Gitee 同步）

原子操作（`atom_ops.py` 和 `douyin_ops.py`）：

| 操作 | 状态 | 说明 |
|:-----|:----:|:-----|
| browse | ✅ | 浏览视频流 |
| like / collect | ✅ | 点赞/收藏 |
| comment path a | ✅ | 弹窗覆盖层评论（KeyX+Enter） |
| comment path b | ✅ | 全屏视频页评论（scroll+click+Enter） |
| search | ✅ | 搜索并打开 |
| follow | ✅ | 关注 |
| **publish_video** | ⏳ 待建 | 上传视频+文案+封面 |
| **live_sim** | ⏳ 待建 | 直播推流模拟 |
| **product_select** | ⏳ 待建 | 选品/带货 |
| **dm_send** | ⏳ 待建 | 私信 |

### Layer 3: 流水线层（代码，Gitee 同步）

| 流水线 | 状态 | 操作链 |
|:-------|:----:|:-------|
| 养号流水线 (nurture) | ✅ | browse → interact → comment → loop |
| 内容发布流水线 | ⏳ 待建 | 读取队列 → 登录 → 上传 → 发布 → 记录 |
| 电商流水线 | ⏳ 待建 | 选品 → 添加到橱窗 → 推广 |
| 直播流水线 | ⏳ 待建 | OBS推流 → 直播间互动 → 带货 |

### Layer 4: 管理层（规划中）

- 内容排期日历
- 多账号任务调度
- 发布成功率 KPI

---

## 两条评论路径对比

| 维度 | Path A: 弹窗覆盖层 | Path B: 全屏视频页 |
|:-----|:------------------|:------------------|
| 入口 | 精选页→点卡片→弹窗播放器 | 直接打开 `/video/xxx` URL |
| 评论区状态 | 隐藏 (hasCL=false) → KeyX 打开 | 页面上方直接可见 |
| 激活方式 | 坐标 (479,687) 双击 | scrollIntoView + click 输入容器 |
| 输入方式 | pbcopy + Meta+V (共享) | pbcopy + Meta+V (共享) |
| 发送方式 | Enter | Enter |
| 适用场景 | 养号流程中的日常操作 | 收到指定链接后自动评论 |

Route 规则：
```
if URL 包含 /video/ → Path B
else → 检查 hasCL
  if hasCL=true → 直接聚焦
  if hasCL=false → KeyX 打开 → Path A
```

---

## 并行执行架构（v4.3 新增）

`mc run` 使用 `mc/engine.py` 的 `BatchEngine` 执行批量任务。v4.3 改为并行模式：

### 设计要点

1. **单账号全轮复用浏览器** — 每个账号创建一个 Camoufox 连接，跑完全部轮次再关闭
2. **多账号 `asyncio.gather`** — 所有账号的 `_run_account_all_rounds()` 同时启动
3. **浏览器启停优化** — N 个账号 × R 轮 → 启停 N 次（而非 N×R 次）

### 新旧对比

```
旧版 (v1.1):
  轮1: A→B→C (串行) → 间隔 → 轮2: A→B→C → 间隔 → 轮3: A→B→C
  # 每步开闭一次浏览器，后一个等前一个完成
  # 3账号×3轮 ≈ 500-900s/批次

新版 (v1.2):
  A的全部3轮 ──┐
  B的全部3轮 ──┼── asyncio.gather ── 同时完成
  C的全部3轮 ──┘
  # 每账号一个持久浏览器，互不等待
  # 3账号×3轮 ≈ 150-350s/批次（约节省 60%）
```

### 代码入口

| 方法 | 职责 |
|:-----|:-----|
| `BatchEngine.run()` | prepare 所有账号 → gather 子任务 → 汇总 |
| `_run_account_all_rounds()` | 每账号：resolve → cookie 检查 → 启动浏览器 → 循环轮次 → 关闭 |
| `run_single(conn=...)` | 单轮单账号：导航到首页 → 执行蓝图步骤 → 返回报告 |
| `_pick_blueprint(round_idx)` | 混合随机/顺序选择本轮蓝图 |

### 共享连接模式

`run_single()` 新增 `conn` 参数：
- `conn=None` → 自行创建并关闭浏览器（独立使用场景）
- `conn=CDPConnector` → 复用已有连接（`_run_account_all_rounds` 内部调用）

### 注意事项

- 并行启动多个 Camoufox 实例时，不要同时调用 `connect()` 中的 `pkill -f camoufox`
  （目前 connect() 中始终执行，但因同步调用在 async 之前完成，3 个并行的 connect() 的
   pkill 都在任何 Camoufox 启动前执行完毕，因此不会跨进程误杀）
- `BrowserManager.prepare()` 在 `run()` 中统一调用，不在子任务中重复执行


2026-05-15 修改：窗口位置固定从 `accounts.yaml` 读取，不再保存回写。
Camoufox 启动偏移会导致保存的坐标偏离预期（如 0→652, 400→2169）。

| 账号 | 固定位置 |
|:-----|:--------:|
| douyin_01 | (0, 0) |
| douyin_02 | (400, 0) |
| douyin_camo01 | (750, 0) |

---

## 评论故障修复记录（2026-05-15）

### 问题
养号流程中评论发送失败，日志显示 `页面出现评论: ❌`

### 根因
1. **输入方式错误**: `keyboard.type()` 被 Draft.js 忽略，execCommand fallback 不触发 React 状态
2. **发送键错误**: Alt+Enter 不再被新版抖音支持

### 修复
| 文件 | 行 | 改前 | 改后 |
|:-----|:---|:-----|:-----|
| `runner.py` | Step 2 输入 | keyboard.type → execCommand | **pbcopy + Meta+V** |
| `runner.py` | Step 3 发送 | Ctrl+Enter → Alt+Enter | **Enter** |
| `runner.py` | 坐标保存 | 每次结束回写 accounts.yaml | **删除，固定读配置** |
| `nurture_blueprint.py` | op_comment 发送 | Alt+Enter (osascript) | **keyboard.press Enter** |