MediaCrawler/mac-agent-os-main/05_tools/10_dashboard/README.md

Dashboard 系统监控面板

版本: 2.0.0 | AgentOS 4.2.1 最后更新: 2026-06-25 端口: 9988

---

一、五层执行架构

所有 Dashboard 操作（养号、采集、登录、评论）都经过这五层：

L5 ─── Dashboard UI ───────── frontend/src/views/*.js
  │     用户点击按钮 → API 调用
  ▼
L4 ─── API 路由 ───────────── routes/ops.py (统一执行入口)
  │     POST /api/ops/run → 调 CommandBus
  ▼
L3 ─── CommandBus ─────────── services/command_bus.py
  │     CMD_REGISTRY 映射 cmd_type → mc 命令
  │     按机器分组 → 队列 → 预检 → 分发
  ▼
L2 ─── mc 引擎 ────────────── scripts/mc/engine.py
  │     BatchEngine → 身份分组 → 启动浏览器 → 蓝图执行
  ▼
L1 ─── 平台 Ops ───────────── scripts/douyin_ops.py / ops/xhs_ops.py
  │     原子操作（三段式：前置条件→执行→后置验证）
  ▼
L0 ─── Camoufox 浏览器 ────── 真实浏览器操作

核心原则：

• L3 CommandBus 是通往执行层的唯一大门
• 前端/L4/CLI/定时任务 → 全部走 CommandBus
• 不允许绕过 CommandBus 直接 subprocess

---

二、目录结构

05_tools/10_dashboard/
├── app.py                    ← FastAPI 主入口（插件加载 + 健康检查 + 基础API）
├── run.py                    ← 启动脚本
├── routes/
│   ├── ops.py                ← 统一操作执行入口（POST /api/ops/run）
│   └── matrix.py             ← 矩阵数据查询（账号/蓝图/采集历史等读操作）
├── services/
│   ├── command_bus.py        ← CommandBus（命令总线 + CMD_REGISTRY 注册表）
│   ├── command_chain.py      ← 接力执行链
│   ├── fleet_collector.py    ← 联邦数据聚合
│   ├── remote_exec.py        ← 远程SSH执行
│   ├── preflight.py          ← 执行前预检
│   └── ...
├── plugins/                  ← 插件式数据源（matrix/guardd/ave/crawl等15个）
├── frontend/src/             ← 前端源码（Vite）
│   ├── main.js               ← 入口
│   ├── router.js             ← 路由 + apiRequest 工具函数
│   ├── state.js              ← AppState 全局状态
│   ├── views/                ← 已迁移视图（45+个）
│   │   ├── matrix-collect.js     ← 信息采集视图
│   │   ├── matrix-nurture.js     ← 养号执行视图
│   │   ├── matrix-accounts.js    ← 账号管理视图
│   │   ├── matrix-comment.js     ← 定向评论视图
│   │   ├── matrix-blueprints.js  ← 蓝图编辑器
│   │   └── ...
│   ├── modules/              ← 功能模块（16个）
│   └── components/           ← 共享组件
├── static/                   ← Vite 构建产物（index.html + assets/）
└── PLANS/                    ← 规划文档

---

三、API 路由说明

3.1 操作执行（唯一入口）

POST /api/ops/run — 所有操作统一入口

请求体格式：

{
  "type": "collect",          // 操作类型（见 CMD_REGISTRY）
  "accounts": ["douyin_01"],  // 账号ID列表
  "params": {                 // 操作参数（可选，不传用注册表默认值）
    "rounds": 1
  }
}

支持的 type（定义在 CMD_REGISTRY）：

type	用途	默认 blueprint	自动推断
nurture	养号执行	douyin_daily	❌ 不自动
collect	主页信息采集	按平台自动选	✅ 自动按账号平台选择
login	智能登录	—	—
logout	登出	douyin_daily	❌
comment	定向评论	—	—
like	点赞	douyin_daily	❌

其他 API：

方法	路径	用途
GET	/api/ops/status	查询所有命令状态
GET	/api/ops/history	查询命令执行历史
GET	/api/ops/machines	所有机器聚合状态
POST	/api/ops/cancel/{run_id}	取消指定命令
POST	/api/ops/test-atom	单步原子操作测试

3.2 数据查询（routes/matrix.py）

所有 /api/matrix/* 路由只处理读操作（GET），不处理写操作（POST）。

方法	路径	用途
GET	/api/matrix/accounts	账号列表
GET	/api/matrix/profiles	已缓存主页资料
GET	/api/matrix/homepage-info	主页信息采集结果（联邦聚合）
GET	/api/matrix/blueprints	蓝图列表
GET	/api/matrix/atom-ops	原子操作列表
GET	/api/matrix/nurture/status	养号运行状态

禁止在 routes/matrix.py 中新增 POST 写操作。 所有写操作必须走 routes/ops.py → CommandBus.dispatch()。

---

四、CommandBus CMD_REGISTRY 注册表

4.1 定义位置

services/command_bus.py:605-640

CMD_REGISTRY = {
    "nurture": {
        "runner": "nurture_runner.sh",
        "defaults": {"blueprint": "douyin_daily", "rounds": 10},
        "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,
    },
    "comment": {
        "template": "mc task comment --account={ids} --url={url} --direction={direction}",
        "required_params": ["url"],
    },
    ...
}

4.2 字段说明

字段	含义	示例
template	命令模板，用 {ids} {blueprint} 等变量	mc run --accounts={ids} --blueprints={blueprint}
defaults	参数默认值	{"rounds": 1}
auto_blueprint	是否根据账号平台自动选择蓝图	True
blueprint_map	平台→蓝图映射	{"douyin": "douyin_read_profile"}
runner	shell 包装器路径（nurture 专用）	"nurture_runner.sh"
single_account	是否一次只处理一个账号	True
required_params	必填参数列表	["url"]

4.3 新增操作类型

新增操作类型只需在 CMD_REGISTRY 加一行，不需要改 dispatch() 逻辑。

# 例：新增 publish 发布操作
"publish": {
    "template": "mc task publish --account={ids} --file={file}",
    "required_params": ["file"],
}

---

五、前端调用规范

5.1 统一调用格式

所有操作执行类请求必须使用 apiRequest 工具函数：

import { apiRequest } from '../router.js';

// ✅ 正确：走统一入口
const result = await apiRequest('/ops/run', {
    method: 'POST',
    body: JSON.stringify({
        type: 'collect',           // 操作类型
        accounts: ['douyin_01'],   // 账号ID列表
        params: {
            rounds: 1,             // 操作参数
            // blueprint 由服务端 CMD_REGISTRY 自动推断
        },
    }),
});

// ❌ 错误：不要绕过统一入口
// await apiRequest('/matrix/collect-homepage', ...)  // 已删除
// await apiRequest('/matrix/nurture/start', ...)     // 不走CommandBus

5.2 参数格式规则

字段	必须	类型	说明
type	✅	string	nurture/collect/login/logout/comment/like
accounts	✅	[string]	账号ID数组
params	❌	object	可选，不传则用CMD_REGISTRY默认值

5.3 错误处理

try {
    const d = await apiRequest('/ops/run', {
        method: 'POST',
        body: JSON.stringify({ type: 'collect', accounts: ids, params: { rounds: 1 } }),
    });
    // d.status = 'accepted' | 'completed' | 'error'
    // d.errors = [...]  // 校验错误
    // d.warnings = [...] // 警告
} catch (e) {
    // 网络/HTTP错误
}

---

六、视图清单与说明

6.1 矩阵组 📱（20+视图）

视图文件	功能	说明
matrix-accounts.js	账号管理	列表/搜索/筛选/建号/单账号采集🔑
matrix-nurture.js	养号执行	全量/按账号执行养号蓝图
matrix-collect.js	信息采集	批量采集主页信息，走统一 /api/ops/run
matrix-comment.js	定向评论	给指定视频发评论
matrix-blueprints.js	蓝图编辑器	创建/编辑/删除/执行蓝图
matrix-login.js	登录管理	查看/管理登录状态
matrix-run.js	原子操作执行	单步测试原子操作
matrix-like.js	收藏点赞	批量点赞/收藏
matrix-publish.js	内容发布	发布视频/图文
matrix-commands.js	执行历史	命令执行记录与状态
matrix-record.js	录制工具	操作录制/分析/导出
matrix-export.js	数据导出	账号/数据导出
matrix-backup.js	备份管理	创建/恢复备份
matrix-corpus.js	语料库	评论语料管理
matrix-schedule.js	定时任务	养号定时调度
matrix-sms-proxy.js	短信与代理	API配置/测试
matrix-settings.js	系统配置	查看/修改配置
matrix-c2.js	联邦指挥台	跨机命令执行
matrix-atom-ops.js	原子操作列表	查看所有支持的操作

6.2 视图规范

• ✅ 所有视图已从 inline.js 迁移到 views/*.js
• ✅ 已注册到 view-registry.js
• ✅ 使用 router.js 的 loadMigratedView() 动态加载
• ✅ 通过 apiRequest() 调用后端 API

---

七、版本历史

版本	日期	变更
2.0.0	2026-06-25	CommandBus CMD_REGISTRY 注册表；统一调用入口到 /api/ops/run；废弃 collect-homepage 路由
1.0.0	2026-06-19	初始版本，五层架构建立

---

八、关联文档

文档	位置
命令传导统一治理方案	PLANS/COMMAND_UNIFICATION_PLAN.md
五层架构合规审计	PLANS/AUDIT_5LAYER_REPORT.md
联邦系统使用指南	FEDERATION_GUIDE.md（参考 §十一）
架构宪法	CONSTITUTION.md