MediaCrawler/mac-agent-os-main/03_knowledge/99_system/TRANSFORMATION_ROADMAP.md

AgentOS 联邦系统 — 全量改造路线图

依据: ARCHITECTURE_CONSTITUTION.md (架构宪法 v1.0)
集成: ARCHITECTURE_v3.md + VITE_MIGRATION_PLAN.md + EXECUTION_PIPELINE.md + 审计报告
目标: 一套标准、一个框架、三机统一、联邦自治
创建: 2026-06-18 | 状态: ✅ 已定义，待执行

---

一、最终目标状态

当所有阶段完成时，系统呈现以下面貌：

用户操作方式（三选一）:
  agentos matrix run --accounts douyin_01 --blueprints douyin_daily    ← CLI
  agentos fleet sync                                                    ← CLI
  agentos ave render ...                                                ← CLI
  Dashboard (localhost:9988)                                            ← Web
  智能体 (AI 自动调度)                                                   ← AI

后端架构:
  agentos/plugins/matrix.py   →  command_bus.py  →  执行体
  agentos/plugins/ave.py      →  (直接调用)       →  视频处理
  agentos/plugins/crawl.py    →  (直接调用)       →  抓取引擎
  agentos/plugins/fleet.py    →  SSH/HTTP        →  远程机器
  agentos/plugins/serve.py    →  本地服务         →  MCP/调度

数据层:
  matrix_mgmt.py (账号唯一入口)
  local_paths.py (路径唯一入口)
  auth_manager.py (登录检测唯一入口)
  cdp_connector.py (浏览器唯一入口)

已退役:
  mc CLI                          → 全部能力迁移到 agentos
  matrix.py                       → 入口退役
  camoufox_manager.py             → 归档
  browser_manager.py              → 归档
  switch_account.py               → 归档
  c2/command_bus.py               → 归档
  c2/profile_scraper.py           → 归档
  remote_exec.py                  → 被 command_bus 替代
  operation_queue.py              → 被 command_bus 替代
  resource_lock.py                → 被 browser_orchestrator 替代
  nurture_daily.py                → 被 orchestrator 替代
  static/index.html (7700行)      → 被 Vite 构建产物替代

---

二、阶段总览

Phase 0: agentos 框架补全         ← 短期（本周）
  ├── Step 0.1: agentos matrix 插件补齐
  ├── Step 0.2: agentos fleet/serve 插件补齐
  └── Step 0.3: agentos 作为 mc 的壳（调用转发）

Phase 1: 清理 + 标准化              ← 短期（并行）
  ├── Step 1.1: 废弃文件归档（5个文件）
  ├── Step 1.2: service 层合并（remote_exec/operation_queue/resource_lock）
  ├── Step 1.3: local_paths.py 路径统一
  └── Step 1.4: 抖音采集加入登录检测

Phase 2: Dashboard 前端重构         ← 中期（2-3天）
  ├── Step 2.1: Vite HMR 开发模式稳定
  ├── Step 2.2: 迁移视图对接新 API
  ├── Step 2.3: 构建产物部署
  └── Step 2.4: 旧 index.html 退役

Phase 3: agentos → 全线贯通         ← 中期
  ├── Step 3.1: mc 全部命令迁移到 agentos
  ├── Step 3.2: mc CLI 退役
  └── Step 3.3: 三机统一部署验证

Phase 4: 联邦自治                   ← 长期
  ├── Step 4.1: 智能体自动调度
  ├── Step 4.2: 故障自愈
  └── Step 4.3: 全链路监控

---

三、详细执行计划

---

Phase 0: agentos 框架补全（最高优先级）

Step 0.1: agentos matrix 插件补齐

现状: agentos/plugins/matrix.py 只有 77 行，只有基本框架，没实现具体命令。

目标: agentos matrix run|collect|login|logout|comment|like|blueprint|corpus 能正常调用底层。

子任务	文件	预计	前置
0.1a 实现 agentos matrix run → 调用 mc run	plugins/matrix.py + cli.py	1h	—
0.1b 实现 agentos matrix collect → 调用 collect_batch_runner.py	同上	1h	—
0.1c 实现 agentos matrix login/logout → 调用 login 模块	同上	1h	—
0.1d 实现 agentos matrix comment/like → 调用 mc task	同上	1h	—
0.1e 实现 agentos matrix blueprint/corpus → 调用 matrix_mgmt	同上	0.5h	—

验收: agentos matrix run --accounts douyin_test --blueprints douyin_daily --rounds 1 成功执行

Step 0.2: agentos fleet/serve 插件补齐

子任务	文件	预计
0.2a agentos fleet sync/reconcile/exec → 调用 fleet_sync.sh/fleet_reconcile.sh	plugins/fleet.py	0.5h
0.2b agentos serve mcp/dashboard/schedule → 调用对应服务	plugins/serve.py	0.5h
0.2c agentos serve proxy/sms → 接入代理/短信管理	plugins/serve.py	1h

Step 0.3: agentos 作为 mc 的壳

策略: 在 mc CLI 执行时，优先检查 agentos 是否有对应实现。如果有，直接转发到 agentos。

mc run --accounts=X --blueprints=Y
  → 检查 agentos 是否可用
    → 是: subprocess.run(["agentos", "matrix", "run", ...])
    → 否: 走旧逻辑（向后兼容）

这样做的意义：

• 用户无感知迁移（mc 命令照常敲，背后用的是 agentos）
• 一旦 agentos 稳定了，mc 只需改一个转发开关
• 不用一次性重写所有 mc 命令

子任务	预计
0.3a mc/cli.py 入口加 agentos 转发检测	1h
0.3b 逐个命令切换转发（从最简单开始：status/blueprint/corpus）	2h

---

Phase 1: 清理 + 标准化（与 Phase 0 并行）

Step 1.1: 废弃文件归档

文件	移到	替代方案	预计
camoufox_manager.py	archive/camoufox_manager.py	cdp_connector.py	5min
browser_manager.py	archive/browser_manager.py	cdp_connector.py	5min
switch_account.py	archive/switch_account.py	无（已废弃）	5min
c2/command_bus.py	archive/c2_command_bus.py	services/command_bus.py	5min
c2/profile_scraper.py	archive/c2_profile_scraper.py	Dashboard API	5min
检查所有 import 引用 → 更新或移除	—	—	30min

⚠️ 必须先检查引用关系再移，防止 import 断裂。

Step 1.2: service 层合并

待合并	合并到	说明	预计
remote_exec.py	command_bus.py._send_remote()	command_bus 已实现远程发送	1h
operation_queue.py	command_bus.py (内置队列)	command_bus.MachineSession 已有队列	1h
resource_lock.py	browser_orchestrator.py	并发限制由 browser_orch 做	1h

步骤:

1. 检查每个函数的调用方（用 grep 找 import/reference）
2. 把调用方改成新路径
3. 旧文件标记 deprecated 头注释
4. 确认无引用后归档

Step 1.3: local_paths.py 路径统一

审计所有硬编码路径（已知有 ~10 处）：

文件	硬编码路径	改为
collect_homepage_info.py:23-27	Path.home() / "workbuddy-agent-os"	local_paths.data_path()
collect_batch_runner.py:27-32	同上	同上
xiaohongshu_login.py:34-35	同上	同上
camoufox_manager.py	同上	同上（若归档则跳过）
其他...	扫描所有 .py 文件	逐个修改

Step 1.4: 抖音采集加入登录检测

对标刚修复的小红书方案：

# extract_douyin() 中，在导航到首页/个人页后
if not logged_in:
    from sms_login import sms_login  # 抖音 SMS 登录
    login_ok = await sms_login(page, phone=phone, ...)
    if login_ok: reload + retry

子任务	预计
1.4a 检查 sms_login.py 是否有独立的 login 函数（类似 xhs_login）	15min
1.4b 在 extract_douyin() 中加入登录检测 → 自动登录	1h
1.4c 端到端测试	30min

---

Phase 2: Dashboard 前端重构

Step 2.1: Vite HMR 开发模式稳定

现状: frontend/ 已有 Vite 项目，33 个视图已迁移为 ES Module。但 Dashboard 直接服务 static/index.html（内联代码），Vite 前端尚未接入。

需要解决的问题:

问题	当前状态	修复方案
Dashboard 使用 static/index.html（内联 7700 行）	正常运行但无法 HMR	保持现状，Vite 构建产物覆盖 static/
Vite 前端 (frontend/) 的视图是迁移版但功能可能不全	33 个 .js 文件	逐个验证功能
ExecutionPipeline 在 Vite 版中需要从 ES Module 加载	已内联到 index.html	迁移到 components/execution-pipeline.js

正确的接入方式:

1. 开发时: cd frontend && npm run dev → localhost:5173/static/ → 有 HMR
2. 部署时: cd frontend && npm run build → 输出到 ../static/ → Dashboard 直接服务

Step 2.2: 迁移视图对接新 API

确保所有视图的按钮使用 ExecutionPipeline.run() + POST /api/ops/run：

视图	当前 API	目标 API	预计
养号执行	/api/ops/run	✅ 已对接	—
信息采集	/api/ops/run	✅ 已对接	—
登录管理	/api/ops/run	✅ 已对接	—
定向评论	/api/ops/run	✅ 已对接	—
收藏点赞	/api/ops/run	✅ 已对接	—
联邦指挥台	/api/ops/run	✅ 已对接	—

Step 2.3: 构建产物部署

cd frontend
npm run build    # → 输出到 ../static/
# 验证 Dashboard localhost:9988 正常服务
# 三机同步: fleet_sync.sh

Step 2.4: 旧 index.html 退役

当 Vite 构建产物稳定后：

1. 重命名 static/index.html → static/index_legacy.html（备份）
2. Vite 构建的 static/index.html 成为主文件
3. 保留回滚能力（index_legacy.html 可恢复）

---

Phase 3: agentos → 全线贯通

Step 3.1: mc 全部命令迁移到 agentos

mc 命令	→ agentos	迁移状态
mc run	agentos matrix run	⬜ 待迁移
mc collect	agentos matrix collect	⬜ 待迁移
mc account	agentos matrix account	⬜ 待迁移
mc smart-login	agentos matrix login	⬜ 待迁移
mc account logout	agentos matrix logout	⬜ 待迁移
mc task comment	agentos matrix comment	⬜ 待迁移
mc task like	agentos matrix like	⬜ 待迁移
mc blueprint	agentos matrix blueprint	⬜ 待迁移
mc corpus	agentos matrix corpus	⬜ 待迁移
mc status	agentos fleet status	⬜ 待迁移
mc remote	agentos fleet exec	⬜ 待迁移
mc schedule	agentos serve schedule	⬜ 待迁移
mc proxy	agentos serve proxy	⬜ 待迁移
mc sms	agentos serve sms	⬜ 待迁移
mc record	agentos matrix record	⬜ 待迁移

Step 3.2: mc CLI 退役

• mc 入口输出: ⚠️ mc 已退役，请使用: agentos <domain> <command>
• 保留 mc 脚本指向 agentos 的软链接（可选）

Step 3.3: 三机统一部署验证

检查项	验证方式
三机 agentos 版本一致	fleet_sync.sh 同步后检查
三机 Python 环境一致	fleet_reconcile.sh
三机 Dashboard 正常启动	访问各机 :9988
远程执行链路正常	从本机发起到 5kecheng/7kecheng 的 collect 和 nurture

---

Phase 4: 联邦自治（长远目标）

步骤	说明	预计
4.1 智能体自动调度	agentos 接收 AI 指令自动执行	未来
4.2 故障自愈	guardd 检测到进程异常自动重启	未来
4.3 全链路监控	所有操作的状态/耗时/成功率可视化	未来

---

四、各阶段工作量预估

Phase	步骤数	预计工时	说明
Phase 0 agentos 补全	~8 步	~8h	最高优先级，先做
Phase 1 清理标准化	~6 步	~4h	与 Phase 0 并行
Phase 2 前端重构	~4 步	~4h	可以后做，现有内联版能用
Phase 3 agentos 贯通	~3 步	~6h	依赖 Phase 0 完成
Phase 4 联邦自治	~3 步	远期	前期不做
	总计	~22h

---

五、风险和注意事项

风险	概率	影响	缓解措施
agentos 开发中导致 mc 不稳定	低	高	Step 0.3 的转发机制可降级回 mc
归档文件被其他模块 import	中	中	归档前 grep 全库检查引用
Vite 构建产物破坏 Dashboard	低	高	保留 index_legacy.html 回滚
远程机器同步延迟	中	低	fleet_sync.sh 可手动触发

---

六、验收标准（全部完成时）

• agentos matrix run|collect|login|logout|comment|like|blueprint|corpus 全部可用
• agentos fleet sync|reconcile|exec 全部可用
• agentos serve mcp|dashboard|schedule|proxy|sms 全部可用
• mc <any> 全部指向 agentos（或直接提示退役）
• 废弃的 6 个文件全部归档，无引用断裂
• service 层无重复功能（remote_exec/operation_queue/resource_lock 归档）
• 所有硬编码路径改为 local_paths.py
• 抖音采集也有登录检测（对标小红书）
• Dashboard 通过 Vite 构建产物正常服务
• 三台机器都升级到同一版本，互操作正常

---

本路线图按 Phase 顺序执行。每完成一个 Step 打勾标记。

当前进度: ⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜⬜ (0/15)