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

AgentOS 命令传导与采集系统——全面优化规划 v2.0

日期: 2026-06-25 | 版本: 4.2.1 基于: CONSTITUTION.md、FEDERATION_GUIDE.md、AUDIT_5LAYER_REPORT.md、COMMAND_UNIFICATION_PLAN.md 覆盖: 命令传导全链路 + 信息采集全链路 + 远程执行 + 数据持久化 + 封号检测

---

一、当前架构全景

L5 前端视图 (12个操作视图)
  │ 统一格式: {type, accounts, params}
  │ 统一入口: POST /api/ops/run
  ▼
L4 API 路由
  ├── routes/ops.py      ← ✅ 统一执行入口（已治理）
  └── routes/matrix.py   ← ✅ 只保留 GET 读操作（已治理）
  ▼
L3 CommandBus
  ├── CMD_REGISTRY        ← ✅ 注册表（已治理）
  ├── dispatch()           ← ✅ 注册表驱动（已治理）
  ├── MachineSession       ← ✅ 每机队列（已治理）
  ├── CMD_POLL_STRATEGY    ← ✅ 按类型策略（已治理）
  └── poll守卫线程         ← ✅ 15s自动检测（已治理）
  ▼
L2 mc 引擎
  ├── nurture_runner.sh    ← ⚠️ 远程参数默认值已修
  ├── BatchEngine          ← ✅ 支持封号标记
  └── LoginStateMachine    ← ✅ 支持banned状态
  ▼
L1 平台原子操作
  ├── douyin_ops.py        ← ✅ 封号检测+同步写homepage_info
  └── ops/xhs_ops.py       ← ✅ 封号检测+同步写homepage_info
  ▼
L0 Camoufox 浏览器

---

二、剩余问题清单（按优先级）

P0 —— 必须修（功能阻断）

#	问题	发现时间	涉及文件
①	远程 nurture 空值参数导致参数错位	2026-06-25	command_bus.py:_send_remote ✅ 已修复
②	前端批量账号逐个发送（matrix-nurture）	2026-06-25	matrix-nurture.js ✅ 已修复
—	以上两个问题已修复并推送	—	—

P1 —— 应修（影响体验/一致性和正确性）

#	问题	涉及文件	说明
③	routes/matrix.py 中 /nurture/start 和 /nurture/preview 绕过 CommandBus	routes/matrix.py:333-443	约100行 POST 代码直接调引擎，不走 CommandBus
④	routes/matrix.py 中 /task/run 路由绕过 CommandBus	routes/matrix.py:757-790	任务执行直接 subprocess
⑤	matrix-accounts.js 单账号采集(_actCol)+登录(_actLogin)逐个发送	matrix-accounts.js:121-145	和修复前的 _nurtureExec 一样的问题
⑥	matrix-comment.js 评论执行逐个发送	matrix-comment.js	需要审计
⑦	matrix-like.js 收藏点赞逐个发送	matrix-like.js	需要审计
⑧	CMD_REGISTRY 中 comment 的模板含 {direction}，可能缺失	command_bus.py:631	前端可能不传 direction
⑨	nurture 在 CMD_REGISTRY 中定义了 runner 字段但 dispatch 未使用	command_bus.py:640	注册表与实际逻辑不一致

P2 —— 可修（清理/优化/后续）

#	问题	涉及文件	说明
⑩	platforms/ 目录已标记 deprecated 但代码还存在	platforms/	等待最终清理
⑪	agentos/plugins/matrix.py 引用存档脚本	agentos/plugins/matrix.py:189-192	依然引用 collect_batch_runner.py
⑫	scripts/archive/ 中的旧脚本可移出	scripts/archive/	确认无引用后移除
⑬	routes/matrix.py 中 /nurture/preview(GET读操作)可保留但需要文档说明	routes/matrix.py:333	仅预览功能
⑭	联邦机器 fleet_collector 缓存过期后 Dashboard 读到旧数据	services/fleet_collector.py	需要自动刷新机制
⑮	Dashboard 信息采集页展示多渠道数据聚合时的去重	routes/matrix.py	多台机器有同一个账号时重复显示
⑯	crawl-tasks.js、crawl-sources.js 等占位符视图无功能	views/crawl-*.js	11个占位符

P3 —— 远期（架构优化）

#	问题	说明
⑰	nurture_runner.sh 和 _send_remote 参数传递方式不同	本地传数组、远程传 shell 字符串，应统一
⑱	远程结果回传路径不一致	nurture 结果在 /tmp/，collect 结果在 runtime/results/
⑲	CMD_REGISTRY 从 dict 改为 dataclass	类型安全+IDE 补全
⑳	routes/ops.py 改为 class-based router	更好的可维护性

---

三、信息采集专项优化

3.1 当前链路（治理后）

前端 matrix-collect.js → POST /api/ops/run {type:'collect', accounts, params}
  → CommandBus CMD_REGISTRY["collect"]
    → auto_blueprint: 按账号平台自动选 douyin_read_profile / xiaohongshu_read_profile
    → 按机器分组 → MachineSession 队列 → _send_local / _send_remote
  → 远程执行 mc run --blueprints=xxx --rounds=1
  → BatchEngine → LoginStateMachine → 原子操作 → 数据提取
  → _save_profiles_json() → 写 profiles.json + homepage_info.json ✅

3.2 已修复的问题

问题	修复
profiles.json 和 homepage_info.json 不同步	✅ _save_profiles_json() 同步写两个文件
封号检测在采集流程内	✅ 登录层也检测封号，直接标记 banned
正则取数字为'?'	✅ 小红书 e2e 兜底已加
数据写入了但 Dashboard 不显示	✅ fleet_collector 缓存清除已做

3.3 信息采集的剩余优化

优化项	说明	优先级
采集进度实时反馈到 Dashboard	目前是"提交后等完成"，没有进度条	P2
多机采集结果去重	同一个 identity_dir 在多台机器都有数据时重复显示	P2
采集历史对比（上次 vs 本次）	方便查看粉丝增长	P3
homepage_info.json 数据与 ORACLE 账号映射对账	自动发现"有账号但未采集"	P2

---

四、统一命令模板注册表（CMD_REGISTRY）最终设计

CMD_REGISTRY = {
    "nurture": {
        "template": "mc run --accounts={ids} --blueprints={blueprint} --rounds={rounds}",
        "defaults": {"blueprint": "douyin_daily", "rounds": 10},
        "runner": "nurture_runner.sh",       # shell 包装器（本地用）
        "auto_blueprint": False,
    },
    "collect": {
        "template": "mc run --accounts={ids} --blueprints={blueprint} --rounds={rounds}",
        "defaults": {"rounds": 1},
        "auto_blueprint": True,
        "blueprint_map": {
            "douyin": "douyin_read_profile",
            "xiaohongshu": "xiaohongshu_read_profile",
        },
    },
    "login": {
        "template": "mc smart-login {ids}",
        "single_account": True,
    },
    "logout": {
        "template": "mc run --accounts={ids} --blueprints=douyin_daily --rounds=1",
    },
    "comment": {
        "template": "mc task comment --account={ids} --url={url}",
        "required_params": ["url"],
    },
    "like": {
        "template": "mc run --accounts={ids} --blueprints=douyin_daily --rounds=1",
    },
}

核心原则：

• ✅ 所有操作共用同一套模板渲染引擎
• ✅ 新增操作只需在注册表加一行
• ✅ auto_blueprint 让前端不用知道具体蓝图名
• ✅ required_params 在 dispatch 时自动校验

---

五、实施路线图

Phase 6: 统一后端执行路由（P1）

#	任务	文件	工作量
6.1	删除 routes/matrix.py 中 /nurture/start 绕过 CommandBus 的代码	routes/matrix.py	小
6.2	删除 /task/run 绕过 CommandBus 的代码	routes/matrix.py	小
6.3	确认所有前端视图已改用 /api/ops/run	逐个审计 views/	中
6.4	修复 accounts.js 单账号采集逐个发送	matrix-accounts.js	小

Phase 7: 前端统一调用格式审计（P1）

#	任务	说明
7.1	审计所有 views/ 中的 POST 调用，确认格式统一	逐个检查
7.2	修复不合规的调用	同上
7.3	增加 ESLint 规则或文档约束	后续

Phase 8: 远程执行结果回传统一（P2）

#	任务	说明
8.1	统一远程命令的结果文件路径	目前 /tmp/ 和 runtime/results/ 混用
8.2	统一 poll 策略对远程命令的检查方式	目前本地和远程各一套逻辑

Phase 9: 清理遗留代码（P2）

#	任务	文件
9.1	移除 platforms/ 目录（或移到 archive）	platforms/
9.2	修复 agentos/plugins/matrix.py 存档引用	agentos/plugins/matrix.py
9.3	确认 scripts/archive/ 无外部引用后移出	scripts/archive/
9.4	删除 routes/matrix.py 中已废弃的 GET/POST 路由（需逐个确认）	routes/matrix.py

---

六、治理后最终状态

L5 前端 ── 统一 POST /api/ops/run {type, accounts, params}
L4 路由 ── ops.py 唯一执行入口 | matrix.py 只读查询
L3 总线 ── CMD_REGISTRY 注册表 | 统一模板渲染 | 自动按机器分组
L2 引擎 ── BatchRunner | LoginStateMachine | 封号检测
L1 操作 ── douyin_ops + xhs_ops | 三段式原子操作
L0 浏览器 ── Camoufox | 登录态管理
数据层 ── profiles.json + homepage_info.json 同步写入
封号层 ── 登录检测 + 采集检测 双层判断

---

七、验证清单

• Phase 6: 无 POST 路由绕过 CommandBus
• Phase 7: 所有前端 views POST 调用格式统一
• Phase 8: 远程结果回传一致，Dashboard 能看到远程执行结果
• Phase 9: 无 archive 脚本的外部引用