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

AgentOS 原子操作架构审计与重构方案

一、旧代码设计原则（提炼自旧版 runner.py / interact.py）

1.1 每步操作 = 状态机三要素

[前置状态检测] → [操作执行] → [后置状态验证]
         ↓             ↓              ↓
   当前在哪个页面？  执行操作   操作是否真的生效了？

旧代码实现（_ensure_player_state、CommentStateMachine）：

# 前置检测
state = await _detect_page_state(page)
# 只有确认在播放页才执行操作
if state not in ("player", "search_player"):
    recovered = await _ensure_player_state(...)
# 执行
await page.keyboard.press("KeyZ")
# 后置验证
assert await _check_anchor(page, 'video_page')

1.2 锚点系统（_check_anchor）

锚点	检测方式	作用
video_page	video 元素 > 0	确认在视频播放页
home_page	.discover-video-card-item > 0	确认在首页feed
video_playing	!video.paused && readyState > 0	确认视频在播放
has_videos	a[href*="/video/"] > 0	页面有视频链接

1.3 评论区状态机（CommentStateMachine）

closed → panel_open → input_focused → text_entered → sent
                ↓           ↓               ↓
          键盘x打开     检测activeElement  检测textContent
          验证has_panel  验证isEditable    验证has_text

核心：每一步都调用 detect() 验证状态是否真的变化了。

1.4 行为链（CHAINS）

旧代码用行为链而非固定步骤模板：

CHAINS = [
    [('open_comment', 'KeyX'),
     ('type_comment', 'input'),   # 调用 _send_comment 状态机
     ('wait_10s', 'wait'),
     ('scroll_comment', 'scroll')],
]

每个链中的操作都是键盘快捷键优先（KeyZ/KeyX/KeyG），DOM 兜底。

---

二、当前新代码的问题审计

问题	表现	根因
无前置状态检测	open_video 在首页找不到卡片→硬等30s→失败	不先检测页面状态就直接找元素
无后置验证	post_comment 返回"sent"但评论没发出去	不检查评论区是否出现了刚发的文字
无锚点系统	所有操作都用 CSS 类名硬匹配（CSS modules 不可靠）	没有用 video/card 等特征判断
状态机缺失	点赞/收藏/评论等操作的执行结果和页面实际脱节	没有 detect() 验证状态变化
DOM 优先于键盘	所有操作先找 DOM 元素，找不到才 fallback	旧代码用键盘快捷键为主，更可靠
无回退策略	一个方法失败就放弃或硬等30s	旧代码有3层回退（键盘→DOM→坐标）

---

三、重构方案

3.1 新原子操作模板

async def atomic_like(page) -> OpResult:
    """点赞操作（前后状态检测模板）"""
    # 1. 前置状态检测
    state = await detect_page_state(page)
    if state not in ('player', 'search_player'):
        return OpResult('like', False, f'不在播放页(state={state})')
    
    # 2. 操作执行（键盘优先）
    await page.keyboard.press('z')
    await asyncio.sleep(1)
    
    # 3. 后置验证（检测按钮状态变化）
    ok = await verify_like(page)  # 检测 data-e2e-state 或 toast
    if ok:
        return OpResult('like', True, '👍')
    
    # 4. 回退：DOM 点击
    btn = page.locator('[data-e2e="video-player-digg"]')
    if await btn.count() > 0:
        await btn.click()
        await asyncio.sleep(1)
        ok = await verify_like(page)
    
    return OpResult('like', ok, '👍' if ok else '-')

3.2 统一状态检测函数

async def detect_page_state(page) -> str:
    """检测当前页面状态"""
    url = page.url
    video_count = await page.evaluate("document.querySelectorAll('video').length")
    cards = await page.evaluate(
        "document.querySelectorAll('.discover-video-card-item, [data-e2e=\"alink-item\"]').length"
    )
    
    if video_count > 0 and '/video/' in url:
        return 'player_full'        # B模式：独立播放页
    if video_count > 0 and 'modal_id' in url:
        return 'player_modal'       # A模式：弹窗播放
    if video_count > 0:
        return 'player_unknown'     # 有视频，模式待定
    if '/search/' in url:
        return 'search'
    if '/user/' in url:
        return 'profile'
    if cards > 0:
        return 'grid'               # 首页feed
    return 'unknown'

3.3 每个操作绑定状态依赖

操作	前置状态要求	后置验证方式
goto_home	(任意)	state → 'grid'
open_video	'grid'	state → 'player_*'
like	'player_*'	按钮state变化或toast出现
collect	'player_*'	按钮state变化或toast出现
follow	'player_*'	按钮文字从"关注"变"已关注"
open_comments	'player_*'	state → 'comment_panel_open'
post_comment	'comment_panel_open'	comment_list中出现刚发的文字
close_comments	'comment_panel_open'	state回到'player_*'
next_video	'player_*'	modal_id或video内容变化
search	(任意)	state → 'search'
go_back	(任意)	URL或state变化

---

四、实施计划

Phase 1：基础设施（1-2小时）

1. 实现 detect_page_state() — 统一状态检测
2. 实现 verify_*() 系列 — 每个操作的后置验证函数
3. 实现 ensure_page_state(target) — 如果不在目标状态则导航过去

Phase 2：重写原子操作（2-3小时）

4. 按模板重写 douyin_ops.py 中所有操作
5. 按模板重写 ops/xhs_ops.py 中所有操作
6. 移除所有无验证的假成功返回

Phase 3：测试验证（1-2小时）

7. 逐步测试每个操作（用户交互模式）
8. 修复各平台的特定选择器/DOM差异

---

以上是完整的审计和方案。你要我按这个方向执行吗？