butubb
2112c1a870
移植自 mac-agent-os 的 mediacrawler_adapter：不起子进程、不开页面，用浏览器里那份
登录态直接调抖音 Web 接口。产物键名照抄 store/douyin，所以 ingest 那条链路一个字不用改。
**目前能用的（真环境实测，非推断）**：
profile/other : 200, 7075 字节 —— 博主主页指标（粉丝/获赞/作品数/昵称）
aweme/detail : 200, 45425 字节 —— 单条作品详情（含点赞/评论/收藏/分享）
**目前不能用的：作品列表 `aweme/post`。** 两个互相独立的原因：
1. 这个接口被抖音单独升级成了真校验：不带 x-tt-argus 回 403「Uifid Not Found」，
带上 dummy 值回 200 + **空 body**。也就是说「头在不在」骗得过，「真校验」过不了。
同一套头打 profile/other 和 aweme/detail 都是通的 —— 抖音是挑着接口加保护的，
挑中的恰好是「批量拉作品列表」这个最敏感的动作。
2. 改走页面截获也不行：CDP 浏览器打开博主主页会落到「验证码中间页」（当天大量探测的
代价，过几小时要重测）。
所以现在的边界是：**已知作品的指标刷新能做，自动发现新作品做不了**。
**排查中控住变量后得到的两条事实**（都写进注释了）：
· `Accept` / `Accept-Language` / `Referer` 才是主页接口能返回真数据的原因 —— 只有
UA+client hints+Cookie 时是 200 但仅 121 字节的空壳，补上这三个头变 7074 字节。
（我先前猜的 sec-ch-ua 不是关键。）
· 因此 UA 与 client hints 必须**成套地取自同一个浏览器**，所以 BrowserIdentity 一次
从 CDP 取齐 cookie + UA + hints，而不是各自写死。
「200 + 空 body 必须当场报错」也是刻意写死的：放过去它会在下游变成「这个博主没作品」，
把一次失败伪装成一条正常结果 —— 爬虫那条路正是这么栽的，还被翻译成「账号被封」。
测试 +11：cookie 解析、请求头成套性（含 uifid 缺失/回退）、产物键名与 store 对齐、
以及 _get 的三条失败路径（空 body / 403 带网关原话 / 正常返回）。
575 lines
28 KiB
Markdown
575 lines
28 KiB
Markdown
# ⚖️ AgentOS 联邦系统 — 架构宪法 v1.0
|
||
|
||
> 本文件是 AgentOS 联邦系统的**最高架构规范**，定义所有模块的职责边界、调用规则、生命周期。
|
||
>
|
||
> **本文件描述的是目标架构（最终状态）**。当前实际系统处于过渡阶段，部分组件仍是旧版。
|
||
> 所有新代码都按此规范编写，旧代码逐步替换，不倒退。
|
||
>
|
||
> 生效日期: 2026-06-18
|
||
> 版本: 1.0
|
||
> 维护者: chengzigedeAir (主控机)
|
||
> 适用范围: 所有联邦机器 (chengzigedeAir / 5kechengdeAir / 7kecheng)
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
- [第一章 总纲](#第一章-总纲)
|
||
- [第二章 架构分层](#第二章-架构分层)
|
||
- [第三章 组件状态与生命周期](#第三章-组件状态与生命周期)
|
||
- [第四章 调用规范](#第四章-调用规范)
|
||
- [第五章 数据流规范](#第五章-数据流规范)
|
||
- [第六章 迁移路线图](#第六章-迁移路线图)
|
||
- [第七章 例外处理](#第七章-例外处理)
|
||
- [附录A 组件状态一览表](#附录a-组件状态一览表)
|
||
- [附录B 旧系统索引](#附录b-旧系统索引)
|
||
|
||
---
|
||
|
||
## 第一章 总纲
|
||
|
||
### 1.1 设计原则
|
||
|
||
| # | 原则 | 说明 |
|
||
|:-:|:-----|:------|
|
||
| 1 | **目标架构驱动** | 本宪法描述的是最终目标架构。当前系统处于过渡期，存在「桥接」组件（如 `mc` CLI），它们会随着迁移推进逐步退役 |
|
||
| 2 | **统一入口** | 所有操作通过 `POST /api/ops/run`（后端）或 `agentos <command>`（CLI）执行。`mc` 是过渡期桥接入口，逐步被 `agentos` 取代 |
|
||
| 3 | **单点职责** | 每个模块只做一件事，禁止功能重叠（参见第三章组件状态） |
|
||
| 4 | **联邦透明** | 调用方无需关心操作在哪台机器执行，command_bus 自动路由 |
|
||
| 5 | **状态可观测** | 每个操作都有完整的生命周期（queued→preflighting→dispatching→running→completed/failed） |
|
||
| 6 | **前向兼容** | 旧模块持续可用直到新模块完全验证通过，但标记为"废弃"后不再修复 |
|
||
| 7 | **路径统一** | 所有文件路径通过 `local_paths.py` 获取，禁止硬编码 |
|
||
|
||
### 1.2 系统总架构
|
||
|
||
```
|
||
┌──────────────────────────────────────┐
|
||
│ agentos CLI (最终目标) │
|
||
│ agentos <domain> <command> │
|
||
│ │
|
||
│ ┌─────────┐ ┌───────────┐ │
|
||
│ │ matrix │ │ ave │ │ ← 插件自动发现
|
||
│ │ 社交矩阵 │ │ 视频工厂 │ │
|
||
│ ├─────────┤ ├───────────┤ │
|
||
│ │ fleet │ │ crawl │ │
|
||
│ │ 联邦管理 │ │ 内容采集 │ │
|
||
│ ├─────────┤ └───────────┘ │
|
||
│ │ serve │ │
|
||
│ │ 服务管理 │ │
|
||
│ └─────────┘ │
|
||
└──────────────────┬───────────────────┘
|
||
│
|
||
┌──────────────────┴───────────────────┐
|
||
│ mc CLI (过渡桥接) │
|
||
│ 15 个命令 → 分散到 agentos 各插件 │
|
||
└──────────────────┬───────────────────┘
|
||
│
|
||
┌──────────────────────┴──────────────────────┐
|
||
│ Dashboard │
|
||
│ (app.py:9988) Web 界面，封装所有领域 │
|
||
└──────────────────────┬──────────────────────┘
|
||
│
|
||
┌────────┴────────┐
|
||
│ command_bus.py │ ← 传输层（唯一通道，不变）
|
||
└────────┬────────┘
|
||
│
|
||
┌─────────────────────────────┼─────────────────────────────┐
|
||
│ │ │
|
||
┌────┴────┐ ┌────┴────┐ ┌─────┴─────┐
|
||
│ 本地执行 │ │ SSH远程 │ │ 队列 │
|
||
└────┬────┘ └────┬────┘ └─────┬─────┘
|
||
│ │ │
|
||
┌────┴─────────────────────────────┴─────────────────────────────┴────┐
|
||
│ 执行体 │
|
||
│ nurture / collect / login / comment / like / logout │
|
||
└──────────────────────────────┬──────────────────────────────────────┘
|
||
│
|
||
┌────────┴────────┐
|
||
│ cdp_connector │ ← 浏览器层（唯一入口）
|
||
│ + auth_manager │
|
||
└────────┬─────────┘
|
||
│
|
||
┌────────┴────────┐
|
||
│ Camoufox Browser│ ← 指纹浏览器
|
||
└─────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 第二章 架构分层
|
||
|
||
### 2.1 入口层
|
||
|
||
#### agentos CLI — 插件式框架（最终目标）
|
||
|
||
`agentos` CLI 是一个**插件式框架**，核心机制是 `agentos/base.py` 中定义的 `AgentOSPlugin` 基类 + 自动发现机制：
|
||
|
||
```
|
||
agentos <domain> <command> [options]
|
||
↑ 插件领域 ↑ 该领域下的子命令
|
||
```
|
||
|
||
现有 5 个领域插件，每个对应 Dashboard 的一个大类：
|
||
|
||
| 领域 | 插件文件 | 对应 Dashboard 视图群 | 来源 |
|
||
|:-----|:---------|:---------------------|:------|
|
||
| **matrix** | `plugins/matrix.py` | 矩阵养号系列 (11个视图) | 来自 mc CLI 的账号/养号/采集/评论/点赞/发布等 |
|
||
| **ave** | `plugins/ave.py` | 视频工厂系列 (4个视图) | **独立领域，非 mc 来源** |
|
||
| **crawl** | `plugins/crawl.py` | 内容采集系列 (3个视图) | **独立领域，非 mc 来源** |
|
||
| **fleet** | `plugins/fleet.py` | 联邦管理系列 (3个视图) | 来自 mc CLI 的远程/同步/对账 |
|
||
| **serve** | `plugins/serve.py` | 服务管理系列 (3个视图) | 来自 mc CLI 的 MCP/Dashboard/调度 |
|
||
|
||
`agentos` 采用**插件自动发现**机制：`discover_plugins()` 扫描 `plugins/` 目录，自动加载继承 `AgentOSPlugin` 的类。这意味着：
|
||
- **新增领域 = 在 plugins/ 加一个 .py 文件**，无需修改框架代码
|
||
- **已有字段通过 `nav` 属性（JSON 格式）与 Dashboard 导航联动**
|
||
- **所有插件共享 `--json`（JSON 输出）和 `--verbose` 通用参数**
|
||
|
||
#### mc CLI — 过渡期桥接入口
|
||
|
||
`mc` CLI 是 `agentos` 开发完成前的过渡入口。mc 的 15 个命令**分散对应**到多个 agentos 领域：
|
||
|
||
| mc 命令 | → agentos 领域 |
|
||
|:--------|:---------------|
|
||
| `mc run` / `mc account` / `mc collect` / `mc smart-login` / `mc task` / `mc blueprint` / `mc corpus` / `mc record` / `mc op` | → **`agentos matrix`** |
|
||
| `mc status` / `mc remote` | → **`agentos fleet`** |
|
||
| `mc proxy` / `mc sms` | → **`agentos serve`** (或 matrix) |
|
||
| `mc schedule` | → **`agentos serve`** |
|
||
|
||
#### 入口层汇总
|
||
|
||
| 入口 | 文件 | 当前状态 | 目标状态 | 职责 |
|
||
|:-----|:-----|:---------|:---------|:------|
|
||
| `agentos` CLI | `agentos/cli.py` | 🔄 **开发中** | ✅ **最终目标** | 插件式框架，统一所有领域入口 |
|
||
| `mc` CLI | `mc/cli.py` | ✅ **当前主力** 但标记为过渡 | 🗑️ **退役** → agentos | 命令行操作，逐个迁移到 agentos 各插件 |
|
||
| Dashboard | `app.py:9988` | ✅ **活跃** | ✅ **一直保留** | Web 管理界面，封装所有领域 |
|
||
| `matrix.py` | `matrix.py` | ⏳ **过渡** | 🗑️ 退役 | 旧CLI入口，被 mc/agentos 替代 |
|
||
|
||
**迁移原则**:
|
||
1. `mc` 的命令**不是全部进 `agentos matrix`**，而是按领域分到对应的 agentos 插件
|
||
2. 每迁移一个命令，`mc` 对应子命令标记为 `@deprecated` 并指向正确的 `agentos <domain>` 用法
|
||
3. `agentos serve` 和 `agentos fleet` 可以独立于 `agentos matrix` 先行完成（因为它们依赖少）
|
||
4. 新增领域插件无需修改框架——加文件即可
|
||
|
||
#### Dashboard 与 agentos 的对应关系
|
||
|
||
Dashboard 的 33 个视图按领域分组，与 agentos 插件一一对应：
|
||
|
||
| Dashboard 导航分组 | 包含视图 | → agentos 插件 |
|
||
|:------------------|:---------|:--------------|
|
||
| 📱 矩阵 | 11 个视图（账号/养号/采集/发布/评论/点赞/蓝图/定时/语料/登录/指挥台） | **matrix** |
|
||
| 🎬 视频工厂 | 4 个视图（渲染/脚本/素材/模板） | **ave** |
|
||
| 📡 内容采集 | 3 个视图（任务/源/历史） | **crawl** |
|
||
| 🖥️ 联邦 + 机器状态 | 4 个视图（状态/同步/对账/远程） | **fleet** |
|
||
| ⚙️ 服务 | 3 个视图（MCP/Dashboard/调度） | **serve** |
|
||
|
||
### 2.2 传输层
|
||
|
||
传输层是**整个联邦系统的唯一命令通道**。所有操作（本机和远程）都通过 `command_bus.py` 分发。
|
||
|
||
| 组件 | 文件 | 状态 | 职责 |
|
||
|:-----|:-----|:-----|:------|
|
||
| **CommandBus** | `services/command_bus.py` | ✅ **核心** | 命令生命周期管理、机器路由、状态轮询 |
|
||
| MachineSession | 同上 | ✅ **核心** | 单机会话、预检、发送、轮询、取消 |
|
||
| Command | 同上 | ✅ **核心** | 命令模型（含生命周期状态机） |
|
||
| `c2/command_bus.py` | 旧版C2 | 🗑️ **废弃** | 被新版 command_bus 替代 |
|
||
|
||
**API 合约**:
|
||
```
|
||
POST /api/ops/run {type, accounts, params}
|
||
→ {status, commands: [{run_id, machine, status, pid, message}]}
|
||
|
||
GET /api/ops/status [?machine=xxx]
|
||
→ {commands: [{run_id, type, accounts, status, elapsed_sec, message}]}
|
||
|
||
GET /api/ops/machines
|
||
→ {machines: {machine_name: {reachable, browsers_running, active_commands}}}
|
||
|
||
POST /api/ops/cancel/{run_id}
|
||
→ {ok: true}
|
||
```
|
||
|
||
**规则**:
|
||
- 所有执行操作（nurture/collect/login/logout/comment/like）必须走 CommandBus
|
||
- 禁止绕过 CommandBus 直接调用 `subprocess.Popen`、`SSH`、`mc run` 等
|
||
- 前端统一使用 `ExecutionPipeline.run()` （参见 `static/index.html`）
|
||
|
||
### 2.3 执行体层 (Executors)
|
||
|
||
执行体是被 CommandBus 调用的具体操作实现。
|
||
|
||
| 操作 | 命令模板 | 后端执行文件 | 状态 |
|
||
|:-----|:---------|:-------------|:-----|
|
||
| **nurture** | `mc run --accounts=X --blueprints=Y --rounds=N` | `nurture_runner.sh` → `nurture/runner.py` | ✅ |
|
||
| **collect** | `mc collect --phone=X` | `collect_batch_runner.py` | ✅ |
|
||
| **login** | `mc smart-login X` | `sms_login.py` / `xhs_login.py` | ✅ |
|
||
| **logout** | `mc account logout X` | via matrix_mgmt | ✅ |
|
||
| **comment** | `mc task comment --account=X --url=Y` | via mc/task.py | ✅ |
|
||
| **like** | `mc task like --account=X --url=Y` | via mc/task.py | ✅ |
|
||
|
||
**规则**:
|
||
- 每个执行体必须支持 `--phone` 或 `--account` 单身份模式（由 command_bus 按机器分组后调用）
|
||
- 执行体只做一件事，不负责机器路由、预检、结果回传
|
||
- 结果以 JSON 文件写入 `$AGENT_LOCAL/runtime/{op_type}/results/{run_id}.json`
|
||
|
||
### 2.4 浏览器层
|
||
|
||
浏览器层是**所有浏览器操作的唯一接口**。三个模块对应不同阶段，但**现阶段只用 cdp_connector.py**。
|
||
|
||
| 组件 | 文件 | 状态 | 职责 |
|
||
|:-----|:-----|:------|:------|
|
||
| **CDPConnector** | `cdp_connector.py` | ✅ **活跃 - 主接口** | 浏览器启动/连接/导航/关闭 |
|
||
| **auth_manager** | `auth_manager.py` | ✅ **活跃** | 登录状态检测（Cookie / DOM 双维度） |
|
||
| **anti_detection** | `anti_detection.py` | ✅ **活跃** | 行为指纹、人体延迟模拟 |
|
||
| **page_state** | `page_state.py` | ✅ **活跃** | 页面模式检测（grid/player/search） |
|
||
| **GracefulBrowser** | `browser_utils.py` | ✅ **活跃** | 浏览器优雅退出 + 超时自动关闭 |
|
||
| camoufox_manager | `camoufox_manager.py` | 🗑️ **废弃** | 被 CDPConnector 替代 |
|
||
| browser_manager | `browser_manager.py` | 🗑️ **废弃** | 实验性模块，从未正式使用 |
|
||
|
||
**规则**:
|
||
- 所有浏览器操作必须通过 `CDPConnector` 创建/管理
|
||
- 登录状态检测必须通过 `auth_manager.get_login_status()`（Cookie + DOM 双重验证）
|
||
- 行为模拟必须通过 `anti_detection.BehaviorProfile`
|
||
- 禁止直接写 `camoufox` 或 `playwright` 原生调用
|
||
|
||
### 2.5 数据层
|
||
|
||
| 组件 | 位置 | 访问方式 | 状态 |
|
||
|:-----|:-----|:---------|:------|
|
||
| **matrix_mgmt** | `matrix_mgmt.py` | `MatrixManager()` 实例 | ✅ **核心** |
|
||
| **accounts.yaml** | `agent-local/tools/matrix/config/` | 通过 matrix_mgmt | ✅ |
|
||
| **identities/** | `agent-local/tools/matrix/identities/` | 通过 matrix_mgmt | ✅ |
|
||
| **anchor_db** | `matrix_modules/nurture/anchor_db.py` | 养号行为锚点 | ✅ |
|
||
| **local_paths** | `local_paths.py` | **路径获取的唯一入口** | ✅ **核心** |
|
||
|
||
**规则**:
|
||
- 账号 CRUD **必须**通过 `matrix_mgmt.MatrixManager`
|
||
- 所有路径 **必须**通过 `local_paths.py`，禁止 `Path.home() / "workbuddy-agent-os" / ...`
|
||
- 跨机账号数据通过 `matrix_mgmt._read_all_machines_accounts()` 聚合
|
||
|
||
---
|
||
|
||
## 第三章 组件状态与生命周期
|
||
|
||
每个组件有以下状态之一：
|
||
|
||
| 状态 | 标识 | 含义 | 处理方式 |
|
||
|:-----|:-----|:------|:---------|
|
||
| ✅ **活跃** | 绿色 | 当前标准组件，所有新代码必须使用 | 持续维护 |
|
||
| ⏳ **过渡** | 黄色 | 正在被取代，但仍被引用 | 尽快迁移 |
|
||
| 🔄 **开发中** | 蓝色 | 新开发尚未完成 | 完成后切换 |
|
||
| 🗑️ **废弃** | 红色 | 不再维护，将归档 | 迁移到 archive/ |
|
||
| 归档 | — | 已从主代码库移除，只保留参考 | 在 archive/ 中只读 |
|
||
|
||
### 完整状态表
|
||
|
||
详见 [附录A](#附录a-组件状态一览表)
|
||
|
||
---
|
||
|
||
## 第四章 调用规范
|
||
|
||
### 4.1 前端 → 后端 调用规则
|
||
|
||
```
|
||
前端点击按钮
|
||
→ collectExec() / doNurtureExec() / runComment() / ...
|
||
→ ExecutionPipeline.run({type, accounts, params, logId, statusId})
|
||
→ fetch /api/ops/machines (预检)
|
||
→ fetch POST /api/ops/run {dry_run} (计划)
|
||
→ confirm() (确认)
|
||
→ fetch POST /api/ops/run (执行)
|
||
→ setInterval fetch /api/ops/status (轮询)
|
||
→ 完成后停止轮询
|
||
```
|
||
|
||
**规则**：
|
||
- 所有执行按钮**必须**使用 `ExecutionPipeline.run()`，禁止手动写 fetch 逻辑
|
||
- `ExecutionPipeline` 是前端唯一的执行入口
|
||
- 新视图必须通过 `router.js` 注册为 migrated view
|
||
|
||
### 4.2 后端 → 执行体 调用规则
|
||
|
||
```
|
||
command_bus.dispatch(type, accounts, params)
|
||
→ 按 machine 分组
|
||
→ 每组一条命令（含多个账号）
|
||
→ preflight() 检查机器+槽位
|
||
→ graceful_exit() 清理同机残留
|
||
→ send() 发送到本机/远程
|
||
→ nurture_runner.sh / mc collect / mc smart-login ...
|
||
```
|
||
|
||
**规则**：
|
||
- 参数传递用 `accounts=["a","b","c"]` 批量形式（按机器分组后）
|
||
- 结果回传用 JSON 文件 → command_bus.poll() 读取
|
||
|
||
### 4.3 路径获取规则
|
||
|
||
```python
|
||
# ✅ 正确: 使用 local_paths
|
||
from local_paths import config_path, data_path, profiles_path
|
||
accounts = config_path("accounts.yaml") # → correct path
|
||
db = data_path("matrix.db") # → correct path
|
||
|
||
# ❌ 错误: 硬编码
|
||
Path.home() / "workbuddy-agent-os" / "agent-local" / "tools" / ...
|
||
```
|
||
|
||
---
|
||
|
||
## 第五章 数据流规范
|
||
|
||
### 5.1 命令生命周期状态机
|
||
|
||
```
|
||
┌────────────┐
|
||
│ queued │
|
||
└─────┬──────┘
|
||
│
|
||
┌─────┴──────┐
|
||
│ preflighting│
|
||
└─────┬──────┘
|
||
┌──────┴───────┐
|
||
│ │
|
||
┌──────┴─────┐ ┌────┴──────┐
|
||
│ preflight_ │ │dispatching│
|
||
│ failed │ └────┬──────┘
|
||
└────────────┘ │
|
||
┌──────┴──────┐
|
||
│ running │
|
||
└──────┬──────┘
|
||
┌──────────────┼────────────────┐
|
||
│ │ │
|
||
┌──────┴─────┐ ┌──────┴──────┐ ┌──────┴──────┐
|
||
│ completed │ │ failed │ │ timed_out │
|
||
└────────────┘ └─────────────┘ └─────────────┘
|
||
```
|
||
|
||
### 5.2 数据流向
|
||
|
||
```
|
||
用户操作 → ExecutionPipeline → fetch /api/ops/run
|
||
→ command_bus.dispatch()
|
||
→ MachineSession.send()
|
||
→ (本机) subprocess.Popen / (远程) SSH
|
||
→ executor script
|
||
→ 写入 $AGENT_LOCAL/runtime/{type}/results/{run_id}.json
|
||
← {run_id, status, pid}
|
||
← command_bus.poll() 读取结果文件
|
||
← ExecutionPipeline 轮询 /api/ops/status
|
||
← 前端显示
|
||
```
|
||
|
||
---
|
||
|
||
## 第六章 迁移路线图
|
||
|
||
### Phase 0: agentos 能力建设（最高优先级）
|
||
|
||
`agentos` CLI 是**插件式框架**，现有 5 个领域插件。优先把核心操作迁移到正确的插件：
|
||
|
||
#### agentos matrix（核心 — P0）
|
||
|
||
| mc 命令 | agentos 对应 | 状态 |
|
||
|:--------|:------------|:------|
|
||
| `mc account` → | `agentos matrix account` | 🔄 待迁移 |
|
||
| `mc run` → | `agentos matrix run` | 🔄 待迁移 |
|
||
| `mc collect` → | `agentos matrix collect` | 🔄 待迁移 |
|
||
| `mc smart-login` → | `agentos matrix login` | 🔄 待迁移 |
|
||
| `mc account logout` → | `agentos matrix logout` | 🔄 待迁移 |
|
||
| `mc task comment/like` → | `agentos matrix comment / like` | 🔄 待迁移 |
|
||
| `mc blueprint` → | `agentos matrix blueprint` | 🔄 待迁移 |
|
||
| `mc corpus` → | `agentos matrix corpus` | 🔄 待迁移 |
|
||
|
||
#### agentos fleet（P1 — 独立可先行）
|
||
|
||
| mc 命令 | agentos 对应 | 状态 |
|
||
|:--------|:------------|:------|
|
||
| `mc status` → | `agentos fleet status` | 🔄 待迁移 |
|
||
| `mc remote exec` → | `agentos fleet exec` | 🔄 待迁移 |
|
||
| — | `agentos fleet sync` | ✅ 已有 |
|
||
|
||
#### agentos serve（P1 — 独立可先行）
|
||
|
||
| mc 命令 | agentos 对应 | 状态 |
|
||
|:--------|:------------|:------|
|
||
| `mc schedule` → | `agentos serve schedule` | 🔄 待迁移 |
|
||
| `mc proxy` → | `agentos serve proxy` | 🔄 待迁移 |
|
||
| `mc sms` → | `agentos serve sms` | 🔄 待迁移 |
|
||
|
||
#### agentos ave（独立领域，不来自 mc）
|
||
|
||
| 功能 | agentos 对应 | 状态 |
|
||
|:-----|:------------|:------|
|
||
| 渲染任务 | `agentos ave render` | ✅ 已有 |
|
||
| 脚本生成 | `agentos ave script` | ✅ 已有 |
|
||
| 素材库 | `agentos ave materials` | ✅ 已有 |
|
||
| 模板管理 | `agentos ave templates` | ✅ 已有 |
|
||
|
||
#### agentos crawl（独立领域，不来自 mc）
|
||
|
||
| 功能 | agentos 对应 | 状态 |
|
||
|:-----|:------------|:------|
|
||
| 采集任务 | `agentos crawl tasks` | ✅ 已有 |
|
||
| 源管理 | `agentos crawl sources` | ✅ 已有 |
|
||
| 采集历史 | `agentos crawl history` | ✅ 已有 |
|
||
|
||
每迁移一个命令，`mc` 对应子命令标记为 `@deprecated` 并指向 `agentos`。
|
||
当 `mc` 所有命令都迁移完成后，`mc` 本身退役。
|
||
|
||
### Phase 1: 清理废弃代码（与 Phase 0 并行）
|
||
|
||
| 待归档文件 | 目标位置 | 替代方案 |
|
||
|:-----------|:---------|:---------|
|
||
| `camoufox_manager.py` | `archive/camoufox_manager.py` | `cdp_connector.py` |
|
||
| `browser_manager.py` | `archive/browser_manager.py` | `cdp_connector.py` |
|
||
| `switch_account.py` | `archive/switch_account.py` | —（已废弃功能） |
|
||
| `c2/command_bus.py` | `archive/c2_command_bus.py` | `services/command_bus.py` |
|
||
| `c2/profile_scraper.py` | `archive/c2_profile_scraper.py` | Dashboard 采集API |
|
||
|
||
### Phase 2: 功能整合（Phase 0 中并行）
|
||
|
||
| 待整合 | 目标 | 说明 |
|
||
|:-------|:------|:------|
|
||
| `nurture_daily.py` → `orchestrator.py` | 统一养号引擎 | 新版orchestrator完成adoption |
|
||
| `remote_exec.py` → `command_bus.py` | 统一远程执行 | command_bus._send_remote 已实现 |
|
||
| `operation_queue.py` → `command_bus.py` | 统一队列 | command_bus 内置队列 |
|
||
| `resource_lock.py` → `browser_orchestrator.py` | 统一资源锁 | browser_orch 做并发控制 |
|
||
| `matrix.py` → `mc/cli.py` | 统一入口 | mc 已有完整命令集 |
|
||
|
||
### Phase 3: 标准化（贯穿始终）
|
||
|
||
| 待标准化 | 说明 |
|
||
|:---------|:------|
|
||
| 所有文件改用 `local_paths.py` | 消除硬编码路径 |
|
||
| `extract_douyin()` 加入登录检测 | 对标 `extract_xiaohongshu()` |
|
||
| 统一日志格式（JSON Lines） | 便于聚合分析 |
|
||
|
||
### 迁移原则
|
||
|
||
1. **先存档，不删除** — 旧代码移到 `archive/`，不删 git 历史
|
||
2. **新系统允许有问题** — 发现问题就修问题，不退回旧系统
|
||
3. **冻结旧系统** — 废弃模块不再提交修复PR
|
||
4. **文档先行** — 每次迁移前更新宪法附录
|
||
|
||
---
|
||
|
||
## 第七章 例外处理
|
||
|
||
### 7.1 允许绕过的情形
|
||
|
||
在以下情形可以临时绕过规范，但必须**事后补充 Issue/MR**：
|
||
|
||
1. **紧急修复线上问题** — 但修复后24小时内必须补全规范
|
||
2. **一次性迁移/归档脚本** — 迁移完成后删除
|
||
3. **实验性新功能** — 标记为 `@experimental`，独立目录开发
|
||
|
||
### 7.2 违规处理
|
||
|
||
对违反本宪法的代码合并/部署：
|
||
- 代码审查不通过
|
||
- Dashboard 部署自动回滚
|
||
- 运行期拦截告警（guardd 检测到不一致时报警）
|
||
|
||
---
|
||
|
||
## 附录A: 组件状态一览表
|
||
|
||
### 入口层
|
||
|
||
| 组件 | 当前状态 | 目标状态 | 说明 |
|
||
|:-----|:---------|:---------|:------|
|
||
| `agentos` CLI (框架) | 🔄 **开发中** | ✅ **最终目标** | 插件式框架，`agentos <domain> <command>` |
|
||
| `agentos/plugins/matrix.py` | 🔄 **开发中** | ✅ **最终目标** | 社交矩阵插件 |
|
||
| `agentos/plugins/ave.py` | ✅ **已有** | ✅ **保留** | 视频工厂插件（独立领域） |
|
||
| `agentos/plugins/crawl.py` | ✅ **已有** | ✅ **保留** | 内容采集插件（独立领域） |
|
||
| `agentos/plugins/fleet.py` | ✅ **已有** | ✅ **保留** | 联邦管理插件 |
|
||
| `agentos/plugins/serve.py` | ✅ **已有** | ✅ **保留** | 服务管理插件 |
|
||
| `mc/cli.py` | ✅ **活跃(桥接)** | 🗑️ **退役** | 当前主力，逐个迁移到 agentos 各插件 |
|
||
| `app.py` (Dashboard) | ✅ **活跃** | ✅ **保留** | Web 界面，长期存在 |
|
||
| `matrix.py` | ⏳ **过渡** | 🗑️ **退役** | 旧入口，被 mc/agentos 替代 |
|
||
|
||
### 传输层
|
||
|
||
| 组件 | 状态 | 迁移目标 | 备注 |
|
||
|:-----|:-----|:---------|:-----|
|
||
| `services/command_bus.py` | ✅ **活跃 (标准)** | — | **所有操作必走这里** |
|
||
| `routes/ops.py` | ✅ **活跃** | — | command_bus 的 API 暴露 |
|
||
| `c2/command_bus.py` | 🗑️ **废弃** | → `services/command_bus.py` | Phase1 归档 |
|
||
| `c2/profile_scraper.py` | 🗑️ **废弃** | → Dashboard 采集 | Phase1 归档 |
|
||
| `services/operation_queue.py` | 🗑️ **废弃** | → `command_bus.py` | Phase2 整合 |
|
||
| `services/remote_exec.py` | 🗑️ **废弃** | → `command_bus.py` | Phase2 整合 |
|
||
| `services/resource_lock.py` | 🗑️ **废弃** | → `browser_orchestrator.py` | Phase2 整合 |
|
||
|
||
### 执行体层
|
||
|
||
| 组件 | 状态 | 迁移目标 | 备注 |
|
||
|:-----|:-----|:---------|:-----|
|
||
| `nurture_runner.sh` | ✅ **活跃** | — | 养育执行包装器 |
|
||
| `collect_batch_runner.py` | ✅ **活跃** | — | 批量采集引擎 |
|
||
| `collect_homepage_info.py` | ✅ **活跃** | — | 单身份采集逻辑 |
|
||
| `sms_login.py` / `xhs_login.py` / `douyin_login.py` | ✅ **活跃** | — | 登录执行体 |
|
||
| `nurture_daily.py` | ⏳ **过渡** | → `orchestrator.py` | Phase2 迁移 |
|
||
| `nurture/runner.py` | ⏳ **过渡** | 拆分为子模块 | 75KB过大需拆分 |
|
||
| `orchestrator.py` | 🔄 **开发中** | — | 新版养号引擎 |
|
||
|
||
### 浏览器层
|
||
|
||
| 组件 | 状态 | 迁移目标 | 备注 |
|
||
|:-----|:-----|:---------|:-----|
|
||
| `cdp_connector.py` | ✅ **活跃 (标准)** | — | **所有浏览器操作的唯一入口** |
|
||
| `auth_manager.py` | ✅ **活跃** | — | 登录状态检测唯一入口 |
|
||
| `anti_detection.py` | ✅ **活跃** | — | 行为指纹 |
|
||
| `browser_utils.py` | ✅ **活跃** | — | 优雅退出 |
|
||
| `page_state.py` | ✅ **活跃** | — | 页面模式检测 |
|
||
| `camoufox_manager.py` | 🗑️ **废弃** | → `cdp_connector.py` | Phase1 归档 |
|
||
| `browser_manager.py` | 🗑️ **废弃** | 直接归档 | Phase1 归档 |
|
||
| `switch_account.py` | 🗑️ **废弃** | 直接归档 | Phase1 归档 |
|
||
|
||
### 数据层
|
||
|
||
| 组件 | 状态 | 备注 |
|
||
|:-----|:------|:------|
|
||
| `matrix_mgmt.py` | ✅ **活跃 (标准)** | 账号管理唯一入口 |
|
||
| `local_paths.py` | ✅ **活跃 (标准)** | 路径获取唯一入口 |
|
||
| `anchor_db.py` | ✅ **活跃** | 养号行为数据库 |
|
||
| `auth_manager.py` | ✅ **活跃** | Cookie/DOM 登录检测 |
|
||
|
||
### Dashboard 服务层
|
||
|
||
| 组件 | 状态 | 备注 |
|
||
|:-----|:------|:------|
|
||
| `command_bus.py` | ✅ **核心** | 命令传输 |
|
||
| `browser_orchestrator.py` | ✅ **活跃** | 并发控制+错峰 |
|
||
| `preflight.py` | ✅ **活跃** | 执行前预检 |
|
||
| `data_aggregator.py` | ✅ **活跃** | 数据聚合 |
|
||
| `log_aggregator.py` | ✅ **活跃** | 日志聚合 |
|
||
| `remote_exec.py` | 🗑️ **废弃** | 被 command_bus 替代 |
|
||
| `operation_queue.py` | 🗑️ **废弃** | 被 command_bus 替代 |
|
||
| `resource_lock.py` | 🗑️ **废弃** | 被 browser_orch 替代 |
|
||
|
||
---
|
||
|
||
## 附录B: 旧系统索引
|
||
|
||
### 已归档文件 (archive/)
|
||
|
||
位于 `05_tools/07_matrix/scripts/archive/`，共 41 个文件，全部为 Phase A/B 测试脚本。
|
||
**参考价值**：这些文件不再被任何活跃代码引用，但包含部分可复用的 DOM 操作 selector/pattern。
|
||
|
||
### 废弃但未归档文件 (需 Phase1 处理)
|
||
|
||
| 文件 | 位置 | 最后改动 | 归档目标 |
|
||
|:-----|:------|:---------|:---------|
|
||
| camoufox_manager.py | scripts/ | — | archive/ |
|
||
| browser_manager.py | scripts/ | — | archive/ |
|
||
| switch_account.py | scripts/ | — | archive/ |
|
||
| c2/command_bus.py | scripts/c2/ | — | archive/ |
|
||
| c2/profile_scraper.py | scripts/c2/ | — | archive/ |
|
||
|
||
---
|
||
|
||
> **本宪法每季度审查一次，根据系统实际演进情况更新版本号。**
|
||
>
|
||
> 下一版预期: v1.1（Phase 1 清理完成后）
|