MediaCrawler/mac-agent-os-main/PLANS/REFORM_ANALYSIS.md

改造分析报告：现状 vs 目标架构

日期: 2026-07-04 | 基于 PLANS/TASK_ORCHESTRATION_ARCHITECTURE.md 审计范围: 全部 7 个模块，逐项检查

---

一、改造项总览

#	模块	改造类型	优先级
1	scheduler.py	🔧 重写 — 现有逻辑不满足需求	P0
2	priority_queue.py	✅ 不动 — 现有类直接可用	-
3	command_bus.py	🆕 新增 smart_comment 类型	P1
4	video_analyzer.py	🆕 新建 — 不存在	P1
5	corpus.py	🔧 改造 — 加行业过滤 + 万能兜底	P1
6	douyin.yaml	🔧 重构 — 语料分层	P1
7	profiles.json	🔧 补字段 — 加 industry	P2
8	ops-command.js	🆕 加功能 — 三队列显示	P3

---

二、逐项分析

---

改造项 1：scheduler.py — 🔧 重写

当前代码（guardd/modules/scheduler.py:33-362）：

当前是单队列模式：

class Scheduler:
    def __init__(self):
        self.queue = PriorityQueue()        # ← 一个队列装所有优先级
        self.active_tasks: dict[int, dict]  # {slot_id: task}
        self.paused_tasks: dict[int, dict]

功能点	现状	目标	问题
队列数量	1 个 混装所有优先级	3 个 独立队列(P0/P1/P2)	❌ P0不能插队，P2不能填空
_pop_next_task()	遍历所有任务，按(priority, scheduled_at)排序后取第一个	先看P0→再看P1→再看P2，且跳过 busy 账号	❌ 无法实现优先级隔离
账号互斥	slot_manager.find_account() 在分配时检查	三层检查：入队时+分配时+执行前	❌ 入队层不检查，可能重复入队
账号状态表	无	account_slots: dict[str, int]	❌ 没有快速查询账号状态的能力
P0 抢占	无	当前任务结束后插队	❌ 完全未实现
P2 劣后	无	只在空闲时执行，可被抢占	❌ 完全未实现
暂停任务暂存	paused_tasks 存在但不被 active 使用	P0插入时暂停P1，完成后恢复	❌ 逻辑不完整

改造原因：当前逻辑是功能错误的。三个优先级的任务混在一个队列里，虽然排序时按 priority 字段，但 _pop_next_task 取完第一个任务后就 break 了，不会继续往后看。当高优任务 due 时间还没到时（scheduled_at > now），堆顶返回 None，整个调度循环就停了。这导致 P0 任务无法真正插队。

改动量：~200行，重写 Scheduler 类。

---

改造项 2：priority_queue.py — ✅ 不动

当前代码（guardd/modules/priority_queue.py:1-79）：

class PriorityQueue:
    """基于 heapq 实现，支持优先级排序 + 时间调度 + 取消/重排"""

当前实现完全满足需求。三队列只需创建三个独立实例：

self.queue_priority = PriorityQueue()  # P0
self.queue_normal   = PriorityQueue()  # P1
self.queue_filler   = PriorityQueue()  # P2

无需修改此类。

---

改造项 3：command_bus.py — 🆕 新增 smart_comment

当前代码（services/command_bus.py:807-842）：

CMD_REGISTRY = {
    "nurture": {...},
    "collect": {...},
    "login": {...},
    "logout": {...},
    "comment": {...},
    "like": {...},
    "interact": {...},
    "record": {...},
}

功能点	现状	目标	问题
评论类型	comment / interact — 直接传 mc task comment	+ smart_comment — 先分析视频再评论	❌ 缺少视频分析环节
分发逻辑	按机器分组后直接发到 guardd	先调 VideoAnalyzer 分析所有URL，再分组分发	❌ 无分析环节

改造原因：新功能需求。现有 comment/interact 可以保留不变，新增 smart_comment 走新的视频分析流程。

改动量：~20行，加一条注册表 + dispatch 分支。

---

改造项 4：video_analyzer.py — 🆕 新建

当前：文件不存在。

需要新建一个完整的视频分析模块，包含：

• 浏览器打开 URL 提取标题/描述
• 关键词匹配行业分类
• 根据账号 industry 选评论

改造原因：完全是新增功能，原来是直接传评论或者随机取语料，现在需要先分析视频内容再做匹配。

改动量：~150行新文件。

---

改造项 5：corpus.py — 🔧 改造

当前代码（scripts/mc/corpus.py:51-57）：

KEYWORD_CATEGORY_MAP = [
    (["科技", "数码", "手机"], ["称赞", "提问"]),
    (["美食", "做饭", "菜"], ["称赞", "共鸣"]),
    (["旅游", "风景", "旅行"], ["称赞", "提问"]),
    (["情感", "生活", "感悟"], ["共鸣", "安慰"]),
    (["知识", "科普", "教育"], ["提问", "补充"]),
]

功能点	现状	目标	问题
关键词覆盖	5组（科技/美食/旅游/情感/知识）	9+组（加上医疗/财经/育儿/汽车等）	❌ 无医疗关键词，健康类视频无法匹配
行业过滤	无	根据账号 industry 过滤语料	❌ 医疗账号可能发科技评论
万能兜底	_get_random_comment() 全域随机	从万能池（称赞/提问/共鸣）取	❌ 没有万能池概念
分类→方向映射	DIRECTION_TO_CATEGORY 5个	同步扩展	❌ 需要对齐

改造原因：现有功能不完整。关键词覆盖太窄，缺少行业过滤机制和万能兜底逻辑。

改动量：~50行，改 KEYWORD_CATEGORY_MAP + get_comment_for_video()。

---

改造项 6：douyin.yaml — 🔧 重构

当前结构（corpus/douyin.yaml:239行）：

categories:
  赞美:    (30条，通用)
  共鸣:    (15条，通用)
  提问:    (15条，通用)
  感慨:    (15条，通用)
  客观:    (10条，通用)
  补充:    (5条，通用)

功能点	现状	目标	问题
语料分层	平铺，都在同一层	两层：万能池 + 行业池	❌ 无法区分行业
accessible 字段	无	accessible: "*" 或 accessible: ["health"]	❌ 无法限制账号使用
match_tags 字段	无	每个行业池带关键词标签	❌ 无法自动匹配视频

改造原因：结构设计不满足新需求。需要按行业分层，加 accessible 和 match_tags 字段。

改动量：YAML 结构调整，将现有评论分类到"万能称赞""万能提问""万能共鸣"下，新增"大健康称赞"等行业池。

---

改造项 7：profiles.json — 🔧 补字段

当前（profiles.json:344行）：

{
  "douyin_133": {"nickname":"苏州胃肠体检敏敏", ...},
  "douyin_test": {"nickname":"小美养生茶", ...},
}

没有一个账号有 industry 字段。

改造原因：缺少关键数据。没有 industry 字段，VideoAnalyzer 无法判断账号该用哪个语料池。

改动量：每个账号加一行 "industry": "health" 或 "industry": "general"，手动配置。

---

改造项 8：ops-command.js — 🆕 加功能

当前代码：

前端已有 P0/P1/P2 的 HTML 筛选 checkbox（第41-43行），但后台 scheduler 返回的队列数据中优先级是混在一起的，前端无法真正按优先级分类展示。

改造原因：新功能需求。后台改为三队列后，前端需要分开显示三个队列的长度+内容。

改动量：~80行，加三个队列的独立展示区域。

---

三、改造原因分类

类别	数量	项
❌ 功能错误（现有逻辑有问题）	1	scheduler.py — 单队列导致P0/P2无法正常工作
⚠️ 功能不完整（有但不够）	2	corpus.py 关键词覆盖窄、douyin.yaml 无行业过滤
🆕 新功能需求（完全新增）	4	video_analyzer.py、command_bus smart_comment、profiles.json industry、ops-command三队列
✅ 无需修改	1	priority_queue.py

---

四、按 Phase 的改造详细清单

Phase 1：队列改造（P0）

文件	当前行数	改动	原因
guardd/modules/scheduler.py	362行	重写：单队列→三队列 + 账号互斥表 + P0抢插 + P2填空	❌ 功能错误，当前单队列无法实现优先级隔离

Phase 2：语料重组（P1）

文件	当前行数	改动	原因
corpus/douyin.yaml	239行	重构为万能池+行业池	🆕 新需求，需要按行业分层
scripts/mc/corpus.py	701行	扩展关键词 + 加行业过滤 + 万能兜底	⚠️ 关键词覆盖窄，缺少过滤
profiles.json	344行	各账号加 industry 字段	🆕 新需求，需要标记账号行业

Phase 3：视频分析（P1）

文件	当前行数	改动	原因
新建 services/video_analyzer.py	0 → ~150行	视频URL分析+分类+选评论	🆕 完全新增
services/command_bus.py	1289行	CMD_REGISTRY 加 smart_comment	🆕 新需求

Phase 4：指挥台展示（P2）

文件	当前行数	改动	原因
frontend/views/ops-command.js	413行	三队列独立展示	🆕 新需求