feat(monitor): 抖音 Web 接口客户端 —— 绕开爬虫子进程，直接发 HTTP

移植自 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 带网关原话 / 正常返回）。

mac-agent-os-main/99_system/AGENTOS-PANORAMA.md

@@ -0,0 +1,426 @@
+# AgentOS 联邦智能体系统全景文档
+
+> 版本：v1.0 | 最后更新：2026-06-15
+> 目的：完整记录系统"是什么"，为后续架构优化提供结构化参考
+> 本文件不讨论"怎么做"，只记录"现在是什么"和"经历过什么"
+
+---
+
+## 第一部分：系统身份
+
+### 1.1 一句话定义
+
+一个**运行在多台 Mac 上的 AI 智能体联邦操作系统**，各机器通过 Git 共享代码和配置，各自执行养号/采集/知识管理等任务，通过 Dashboard 统一监控。
+
+### 1.2 核心设计理念
+
+- **代码走同步，数据留本机** — 脚本在 Git，数据在本地
+- **四层隔离** — 管理层/流水线层/操作层/数据层各自独立
+- **每账号独立工作区** — 身份/素材/文案/发布记录各自独立
+- **原子操作可组合** — 所有操作遵循"前置锚点→执行→后置锚点"
+- **WPRA 写分区·读聚合** — 各写各的文件，最后统一读取（v2.0 架构）
+
+### 1.3 用户画像（ghai）
+
+- 多台 Mac 电脑使用者（最少 3 台）
+- 从事 AI 短视频/矩阵内容运营
+- 需要多账号、多平台（抖音/小红书）自动化管理
+- 有知识库和记忆管理需求
+- 同时也在探索 AI 视频生成（Seedance/即梦/豆包）
+
+---
+
+## 第二部分：硬件基础设施
+
+### 2.1 机器清单
+
+| 机器 | UID | 硬件 | 操作系统 | 角色 | 位置 |
+|:-----|:----|:-----|:---------|:-----|:-----|
+| chengzigedeAir | 4cf443bc... | MacBook Air M1, 16GB | macOS 26.4 arm64 | **本机** | 本地 |
+| 5kechengdeAir | f13b03d1... | Mac (未知配置) | macOS 25.4 arm64 | 远程机器 | Gitee 同步 |
+| 7kecheng | d19759cf... | Mac (未知配置) | macOS arm64 | 远程机器 | Gitee 同步 |
+
+### 2.2 机器连接方式
+
+- **Git 仓库**：Gitee（主）+ GitHub（备），双远程推送
+- **SSH**：配置了到 Gitee/GitHub 的 SSH 密钥（id_ed25519a）
+- **Tailscale**：5kechengdeAir 上已安装，本机尚未安装
+- **远程执行**：`mc remote exec` 已实现 SSH/HTTP 两种方式
+- **局域网**：各机器在 192.168.31.x 网段内互通
+
+---
+
+## 第三部分：软件与依赖
+
+### 3.1 运行时环境
+
+| 组件 | 版本 | 路径 | 说明 |
+|:-----|:-----|:-----|:------|
+| Python (managed) | 3.13.12 | `~/.workbuddy/binaries/python/versions/3.13.12/` | WorkBuddy 管理 |
+| Python (system) | 3.9.6 | `/usr/bin/python3` | macOS 自带 |
+| Python (venv) | 3.13.12 | `~/.workbuddy/binaries/python/envs/agent-os/` | 主运行环境 |
+| Node.js | 22.12.0 | `~/.workbuddy/binaries/node/versions/22.12.0/` | WorkBuddy 管理 |
+| Camoufox | (pip) | venv 内安装 | Firefox 内核浏览器，用于养号 |
+| oMLX | v0.3.6 | /Applications/oMLX.app | 本地 LLM 推理引擎 |
+| Ollama | v0.21.2 | /Applications/Ollama.app | 已停用 |
+| Orjson | 3.11.9 | venv site-packages | 曾因 macOS 签名问题导致浏览器启动失败 |
+
+### 3.2 本地 LLM 模型
+
+| 模型 | 用途 | 状态 |
+|:-----|:------|:------|
+| Qwen3-8B-MLX-4bit | 主力推理 | ❌ Chat API 500 错误 |
+| Qwen2.5-VL-3B-Instruct-8bit | 多模态理解 | ✅ 正常 |
+| Qwen3-Embedding-0.6B | 向量嵌入（1024维） | ✅ 正常 |
+
+### 3.3 已知环境问题
+
+1. **orjson macOS 代码签名**：Python 3.13 的 .so 文件被 Tencent 签名，与本地编译的 orjson 冲突 → 需 `codesign --remove-signature` 后重新签署
+2. **Python 版本割裂**：系统 3.9 vs 管理 3.13，不同版本行为差异
+3. **Camoufox 启动**：依赖 orjson 和特定系统库，部分机器启动失败
+4. **Git 仓库膨胀**：含浏览器缓存和二进制文件，接近 1GB
+
+---
+
+## 第四部分：系统组件全览
+
+### 4.1 顶层目录
+
+```
+workbuddy-agent-os/
+├── agent-sync/         594MB  ← Git 仓库（代码 + 配置 + 一些数据）
+│   ├── 00_bootstrap/         启动脚本、init.sh、apply-config.sh
+│   ├── 01_core/              核心配置：SOUL.md, IDENTITY.md, USER.md
+│   ├── 02_skills/            自定义技能：memory_manager, matrix, kb_manager 等
+│   ├── 03_knowledge/         知识库（按分类：01_daily~50_resources）
+│   ├── 04_memory/            跨机协同（WPRA）、记忆文件
+│   ├── 05_tools/             全部工具：
+│   │   ├── 00_setup/         agentos CLI, guardd 守护进程
+│   │   ├── 01_system/        系统级脚本（路径修复、检测等）
+│   │   ├── 02_browser/       浏览器自动化
+│   │   ├── 03_ocr/           OCR 识别
+│   │   ├── 04_media/         媒体处理
+│   │   ├── 05_crawl/         爬虫（longcat, content-inspiration）
+│   │   ├── 06_mobile/        移动端
+│   │   ├── 07_matrix/        矩阵养号系统（核心）
+│   │   ├── 08_trae_agent/    TRAE 控制
+│   │   ├── 09_ave/           视频工厂
+│   │   └── 10_dashboard/     Dashboard 看板（FastAPI + 前端）
+│   ├── 90_archive/           归档文档
+│   └── 99_system/            系统文档、架构、协议
+│
+└── agent-local/              本机数据（不同步）
+    ├── identity/             机器身份、machine_uid
+    ├── memory/               记忆文件（L1/L2/L3、向量库）
+    ├── tools/                工具运行时数据
+    │   └── matrix/           matrix 系统数据
+    │       ├── config/       accounts.yaml 账号配置
+    │       ├── identities/   浏览器身份（Cookie + 指纹）
+    │       └── data/         运行时数据、profiles.json
+    ├── vector_db/            向量库（ChromaDB + 关键词索引）
+    └── runtime/              运行时缓存
+```
+
+### 4.2 工具详解
+
+#### 05_tools/07_matrix — 矩阵养号系统（核心）
+| 子模块 | 说明 | 状态 |
+|:-------|:------|:------|
+| `mc` CLI | 统一命令行入口 | ✅ 活跃 |
+| `scripts/mc/run.py` | 批量执行引擎（BatchEngine） | ✅ 活跃 |
+| `scripts/mc/engine.py` | Camoufox 浏览器操作引擎 | ✅ 活跃 |
+| `scripts/mc/cli.py` | CLI 命令调度（10+ 子命令） | ✅ 活跃 |
+| `scripts/mc/analyzer.py` | 录制分析器 | ✅ 新增 |
+| `scripts/mc/exporter.py` | 蓝图导出器 | ✅ 新增 |
+| `scripts/mc/recorder.py` | 操作录制器 | ✅ 新增 |
+| `blueprints/` | 14 个蓝图（抖音 9 + 小红书 4 + 录制 1） | ✅ |
+| `scripts/nurture_daily.py` | 日常养号调度器 v1.0 | ✅ |
+| `scripts/collect_batch_runner.py` | 批量主页信息采集 | ✅ |
+| `scripts/collect_homepage_info.py` | 主页信息采集 | ✅ |
+| `scripts/cdp_connector.py` | Chrome CDP 连接（含反检测） | ✅ |
+| `scripts/anti_detection.py` | 反检测模块 | ✅ |
+| Dashboard 集成 | 看板中的矩阵管理（7 个子页面） | ✅ |
+
+#### 05_tools/10_dashboard — Dashboard 看板
+| 模块 | 说明 |
+|:-----|:------|
+| `app.py` | FastAPI 主应用（3000+ 行，含所有 API） |
+| `static/index.html` | 单页前端（4000+ 行，含所有前端逻辑） |
+| `plugins/base.py` | 插件基类（AGENT_SYNC/AGENT_LOCAL 路径常量） |
+| `plugins/matrix.py` | 矩阵插件（账号管理、蓝图、原子操作） |
+| `plugins/kb_api.py` | 知识库 API |
+| `plugins/sms_proxy_api.py` | 短信/代理管理 |
+| `plugins/system_plugins.py` | 系统插件 |
+| `plugins/_registry.py` | 注册表管理 |
+
+#### 05_tools/00_setup — 系统基础设施
+| 模块 | 说明 |
+|:-----|:------|
+| `agentos/main.py` | `agentos` CLI（init/check/upgrade/rebuild-vector） |
+| `guardd/guardd.py` | 守护进程（心跳 + 自动化 + 数据管理）目前有 7 个模块 |
+| `sync_machine.sh` | 机器同步脚本 |
+
+#### 05_tools/05_crawl — 采集系统
+| 模块 | 说明 |
+|:-----|:------|
+| `longcat/` | 长期爬虫（含浏览器 Profile ~400MB） |
+| `content-inspiration/` | 内容灵感采集（豆包浏览器驱动） |
+
+#### 05_tools/09_ave — 视频工厂
+| 模块 | 说明 |
+|:-----|:------|
+| `scripts/service_layer/app.py` | 服务层 API |
+| `scripts/main.py` | 主程序 |
+
+### 4.3 技能系统（02_skills/）
+
+| 技能 | 用途 | 状态 |
+|:-----|:------|:------|
+| memory_manager | 记忆提炼、冲突消解、语义检索 | ✅ |
+| kb_manager | 知识库管理（新增/清洗/搜索/备份） | ✅ |
+| inbox_refine | 收件箱提纯分类归档 | ✅ |
+| collect_to_inbox | 内容归集到收件箱 | ✅ |
+| auto_collector | 24小时自动信息收集 | ✅ |
+| content_processor | 统一内容处理入口 | ✅ |
+| sync_manager | 同步管理（备份/导出/迁移） | ✅ |
+| matrix | 矩阵养号技能 | ✅ |
+| web_crawler | 网页抓取（Scrapling/Crawl4AI） | ✅ |
+
+---
+
+## 第五部分：所有工作流程
+
+### 5.1 养号流程
+
+```
+┌─ 定时触发 ─────────────────────────────────────┐
+│                                                 │
+│  mc run --accounts A,B,C --blueprints X --rounds N   │
+│    ↓                                                │
+│  BatchEngine                                       │
+│    ├─ 账号A: 启动 Camoufox → 执行蓝图循环 → 关闭    │
+│    ├─ 账号B: 启动 Camoufox → 执行蓝图循环 → 关闭    │
+│    └─ 账号C: 启动 Camoufox → 执行蓝图循环 → 关闭    │
+│    ↓                                                │
+│  报告输出                                           │
+│                                                     │
+│  蓝图内步骤: goto_home → browse → like →            │
+│             comment → next_video → 循环              │
+└─────────────────────────────────────────────────────┘
+```
+
+执行方式：
+- **Dashboard 命令与任务 → 全部养号**：选身份/时间/并发 → 一键启动
+- **Dashboard 命令与任务 → 批量执行**：选账号/蓝图 → 一键执行
+- **CLI 直接执行**：`mc run --accounts ...`
+- **定时自动化**：nurture_daily.py 调度器
+
+### 5.2 采集流程
+
+```
+主页信息采集（collect_batch_runner.py）：
+  启动 → 读取 accounts.yaml → 分批并行
+    ├─ 账号A (打开浏览器 → 导航到主页 → 读取信息 → 写入 profiles.json)
+    ├─ 账号B (同上)
+    └─ 账号C (同上)
+  → 更新 collect_progress.json
+  → 完成后通知 Dashboard
+```
+
+### 5.3 知识库流程
+
+```
+采集 → 01_submissions/ → (02:30 归集) → 00_inbox/
+  → (03:00 提纯) → AI 分类 → 归档到 10_concepts/20_methods/ 等
+  → 更新 README 统计
+  → 更新 CHANGELOG
+  → (03:30 向量重建) → ChromaDB 向量化 → 可语义检索
+```
+
+### 5.4 记忆管理流程
+
+```
+每日 02:00:
+  提取昨日对话 → 关键事实 (who/what/when/where/decision)
+  → 去重 (L2 相似度 > 0.9 跳过)
+  → 冲突检测 (Override 或提示用户)
+  → 更新 L1 关键词索引
+  → 更新 L1_vec 向量索引 (ChromaDB + oMLX Embedding)
+  → 原文压缩写入 L3
+```
+
+### 5.5 guardd 守护进程（9 模块）
+
+| 模块 | 功能 | 周期 |
+|:-----|:------|:------|
+| module_heartbeat | 心跳上报 | 每轮 |
+| module_automation | 定时任务检查 | 每轮 |
+| module_event_log | 事件日志 | 触发时 |
+| module_knowledge_sync | 知识同步 | 每轮 |
+| module_system_info | 系统信息收集 | 每轮 |
+| module_git_sync | Git 同步 | 每轮 |
+| module_cross_machine | 跨机数据管理 | 每轮 |
+
+---
+
+## 第六部分：通信与同步机制
+
+### 6.1 数据流向
+
+```
+你 (ghai)
+  ├─ 操作 Dashboard (http://localhost:9988)
+  │    └─ Dashboard 调用各 API → 操作本地文件/启动进程
+  │
+  ├─ git push → Gitee/GitHub → 其他机器 git pull
+  │    ├─ 代码同步 (agent-sync/)
+  │    ├─ 运行时数据同步 (04_memory/cross_machine/)
+  │    │    ├─ machines/{uid}/accounts.yaml  ← 各写各的
+  │    │    ├─ machines/{uid}/heartbeat.json  ← 各写各的
+  │    │    ├─ events/{date}.jsonl            ← 各写各的
+  │    │    └─ data/{uid}.json                ← 各写各的
+  │    └─ 知识库同步 (03_knowledge/)
+  │
+  └─ SSH 远程连接
+       └─ mc remote exec <host> <command>
+            └─ SSH 到目标机器执行命令
+```
+
+### 6.2 WPRA 写分区·读聚合（当前架构, v2.0）
+
+**写分区**：每台机器只写 `machines/{自己的UID}/` 下的文件
+**读聚合**：Dashboard 读取时遍历所有机器的目录，聚合为完整视图
+
+**已知问题**：
+1. `_registry.json` 曾是多机器写冲突的根源（已修复为单实例写）
+2. `git add -A` 会把所有机器的文件 staging，导致冲突
+3. `accounts_registry.yaml` 单文件跨机器导致冲突（已迁移到 WPRA）
+4. 架构文档说各写各的，但 guardd 的某些模块还在写全局文件
+
+---
+
+## 第七部分：自动化任务
+
+### 7.1 WorkBuddy 内置自动化
+
+| 任务 | 时间 | 状态 | 说明 |
+|:-----|:------|:------|:------|
+| AgentOS 每日记忆提炼 | 02:00 | ⏸ PAUSED | 提取对话→L2事实+L1索引 |
+| 向量库与索引定时更新 | 02:30 | 🟢 ACTIVE | 知识库→关键词+ChromaDB |
+| AgentOS 收件箱提纯 | 03:00 | ⏸ PAUSED | 收件箱→分类归档 |
+
+### 7.2 未自动化的流程
+
+| 流程 | 当前状态 | 问题 |
+|:-----|:---------|:------|
+| Git push 到远程 | 手动执行 | 夜间自动化完成后不会自动推送 |
+| 工作日志生成 | 未实现 | 夜间任务完成后无汇总报告 |
+| 向量重建 | 单独自动化已创建 | 但记忆提炼的向量更新已暂停 |
+| 账号状态检查 | 手动 | 没有定时检查所有账号登录状态 |
+| 远程机器同步 | 手动 | 需要手动 SSH 到各机器执行 git pull |
+
+---
+
+## 第八部分：历史问题与事故记录
+
+### 8.1 路径问题（反复发生，4 次以上）
+
+| 时间 | 问题 | 影响范围 |
+|:-----|:------|:---------|
+| 04-25 | `/Users/5kecheng/` → `/Users/chengzige/` 路径替换 | 6 个文件 |
+| 04-29 | P0: 自动化 `--root` 路径失效 | 4 个自动化任务全部失效 |
+| 04-29 | 旧路径 `~/agent-os` 残留 | 61 个文件 235 处引用 |
+| 06-15 | Dashboard 中 12 处 `Path.home()` 硬编码 | 跨机兼容性 |
+
+### 8.2 Git 冲突（反复发生）
+
+| 类型 | 根因 | 频率 |
+|:-----|:------|:------|
+| `_registry.json` 冲突 | 多机器同时写同一个文件 | 每次同步 |
+| `accounts.yaml` 冲突 | WPRA 迁移后仍有遗留 | 频繁 |
+| `accounts_registry.yaml` 冲突 | 旧架构遗留文件 | 已删除 |
+| 运行时数据冲突 | `git add -A` 包含所有机器数据 | 频繁 |
+
+### 8.3 环境与依赖问题
+
+| 问题 | 根因 | 状态 |
+|:-----|:------|:------|
+| orjson 代码签名 | macOS 安全策略，二进制 .so 签名不匹配 | 已修复 |
+| lxml 版本冲突 | scrapling vs crawl4ai 版本要求不一致 | 已修复 |
+| Qwen3-8B Chat API 500 | 模型兼容性问题 | 未修复（用 VLM 替代） |
+| Camoufox 浏览器启动失败 | 依赖缺失/环境不一致 | 偶发 |
+
+### 8.4 设计上的反复
+
+| 事项 | 初始方案 | 当前方案 | 改了几次 |
+|:-----|:---------|:---------|:---------|
+| 账号注册表 | 单文件 accounts_registry.yaml | WPRA machines/{uid}/accounts.yaml | 3 次 |
+| 路径结构 | `~/agent-os/`, `~/agent-os-local/` | `~/workbuddy-agent-os/agent-sync/`, `~/workbuddy-agent-os/agent-local/` | 2 次 |
+| 自动同步 | 坚果云 | Git 双远程 | 2 次 |
+| 本地 LLM | Ollama | oMLX | 1 次 |
+| 浏览器引擎 | Chrome CDP | Camoufox (Firefox) | 1 次 |
+| 架构文档 | 单机 (2.2.0) | 联邦多机 (4.0.0) | 多次重构 |
+
+---
+
+## 第九部分：待办与未完成事项
+
+### 9.1 明确的待办
+
+1. **发布功能**：`social-auto-upload` 已克隆但未整合
+2. **Tailscale 安装**：本机未安装，远程执行依赖 SSH（局域网内可用）
+3. **`update_vector_db.py`**：已创建但未提交到仓库
+4. **夜间自动化 Git push**：记忆提炼+向量更新完成后自动推送
+5. **7kecheng 角色定义**：这台机器当前账号不明，角色未定义
+
+### 9.2 未完全解决的问题
+
+1. **Dashboard 单页过大**：`index.html` 4000+ 行，难维护
+2. **app.py 过大**：3000+ 行，包含所有 API
+3. **无统一错误处理**：错误散落在各个模块
+4. **无统一日志系统**：不同模块日志格式不同
+5. **新机部署步骤多**：虽然 init.sh 存在，但环境依赖复杂
+6. **跨机调试困难**：不知道另一台机器当前状态
+
+### 9.3 未来想做的
+
+根据系统文档和对话记录推测：
+
+1. **内容发布流水线**（publishing pipeline）— 自动发布到抖音/小红书
+2. **电商流水线**（ecom pipeline）— 选品/带货
+3. **直播流水线**（live pipeline）— OBS 推流/互动
+4. **Trae 智能体集成** — 用 TRAE 写代码
+5. **远程命令控制** — 通过 Tailscale/SSH 向其他机器发送任务
+6. **内容灵感采集** — 豆包热榜/即梦灵感 → 自动生成视频
+
+---
+
+## 第十部分：总结——系统当前的核心矛盾
+
+### 10.1 结构性问题
+
+```
+┌─────────────────────────────────────────────────────┐
+│  1. Git 仓库 ≈ 1GB（含浏览器缓存 + 二进制 .so 文件） │
+│      → push 超时、冲突不断、新机器克隆慢               │
+├─────────────────────────────────────────────────────┤
+│  2. 环境依赖不一致（Python 3.9 vs 3.13, orjson 签名） │
+│      → 同一代码在不同机器上行为不同                      │
+├─────────────────────────────────────────────────────┤
+│  3. 配置散落（部分在 agent-sync, 部分在 agent-local）  │
+│      → 改配置不知道会影响什么、影响哪台机器               │
+├─────────────────────────────────────────────────────┤
+│  4. 无统一调度（自动化/手工/远程执行三套机制）            │
+│      → 哪个任务在哪个机器上跑、什么时候跑，靠人记         │
+├─────────────────────────────────────────────────────┤
+│  5. 每台机器没有"全局视角"（各看各的 heartbeat）         │
+│      → 机器A不知道机器B现在在干什么                      │
+└─────────────────────────────────────────────────────┘
+```
+
+### 10.2 根本原因
+
+**不是技术问题，是分层问题。** 代码（code）、配置（config）、运行时数据（data）三层混在一起，没有明确的边界和职责划分。每台机器的独有信息（环境差异、本地配置）和共有信息（任务规则、账号分配）也没有分开管理。
+
+---
+*本文档是 AgentOS 系统的"现在是什么"的快照，不包含任何改造方案。方案讨论请基于本文档进行。*

mac-agent-os-main/99_system/ARCHITECTURE_CONSTITUTION.md

@@ -0,0 +1,348 @@
+# AgentOS 架构宪法
+
+> ⚠️ 本文件已迁移到根目录 `CONSTITUTION.md`
+> **请使用根目录版本**：`~/workbuddy-agent-os/agent-sync/CONSTITUTION.md`
+> 同时部署到 `~/.workbuddy/CONSTITUTION.md`
+>
+> 版本: 1.0 | 最后更新: 2026-06-21
+> 本文件是 AgentOS 联邦智能体操作系统的**架构总纲**。
+> 任何代码开发、文档修改、架构决策之前，先读此文件确定归属层面。
+>
+> **读完此文件后，你应该能回答：**
+> - 这段代码属于哪个层？哪个维度？哪个目录？
+> - 开发时应遵守什么硬规则？
+> - 版本怎么升？文档怎么维护？
+
+---
+
+## 第一章：系统定位
+
+### 1.1 一句话定义
+
+AgentOS 是一个**运行在多台 Mac 上的 AI 智能体联邦操作系统**，给 WorkBuddy AI 装上外骨骼——技能、工具、联邦、看板、自动化、记忆、知识、协议。
+
+### 1.2 核心理念
+
+| 理念 | 含义 |
+|:-----|:------|
+| **代码走同步，数据留本机** | 脚本在 Git（agent-sync/），数据在本地（agent-local/） |
+| **唯一权威源** | 每个信息维度只有一个`01_core/VERSION`/ORACLE.yaml/SKILL_CARD.yaml） |
+| **三层分离** | TRUTH（人工维护）≠ DERIVED（自动生成）≠ VERIFIED（自动对账） |
+| **执行通道五层** | 看板→分发→工具→CLI→执行器，层层分明 |
+| **不做空壳** | 有文档无代码的技能/工具→归档，不留在活跃目录 |
+
+---
+
+## 第二章：十二维功能全景
+
+系统由 **3 大子系统 × 12 个功能维度** 构成：
+
+### 子系统 A：智能体增强层（给 WorkBuddy 装外骨骼）
+
+| # | 维度 | 位置 | 加载方式 | 说明 |
+|:-:|:-----|:-----|:---------|:-----|
+| ① | **身份规则** | `01_core/` → `~/.workbuddy/` | 每次对话常驻 ~750 tokens | SOUL.md（规则+触发词）+ IDENTITY.md + USER.md |
+| ② | **行为协议** | `03_knowledge/99_system/protocols/` | 触发词激活 ~200 tokens/个 | meta-thinking / cross-domain / stuck-intervention / knowledge-review |
+| ③ | **分层记忆** | `04_memory/` | L1→L2→L3 分层截断 | 关键词索引 + ChromaDB 向量 + facts.db + 原文 |
+| ④ | **知识库** | `03_knowledge/`（排除 99_system/） | 按需 BM25+向量检索 | 10_concepts/ 20_methods/ 等自然知识 |
+
+### 子系统 B：执行操作系统（自动化干活）
+
+| # | 维度 | 位置 | 说明 |
+|:-:|:-----|:-----|:------|
+| ⑤ | **技能** | `02_skills/` | WorkBuddy 可调用的能力。当前 7 活跃 + 4 已归档 |
+| ⑥ | **工具** | `05_tools/` | 底层执行脚本。当前 8 活跃 + 4 已清空 |
+| ⑦ | **看板** | `05_tools/10_dashboard/` | Web 监控界面（FastAPI 1521 行 + 15 插件） |
+| ⑧ | **命令分发** | `services/command_bus.py` | 看板→CommandBus→ORACLE 对账→SSH/本地 |
+| ⑨ | **CLI 执行** | `05_tools/00_setup/agentos/` + `07_matrix/mc` | 统一命令行入口 + mc 快捷别名 |
+| ⑩ | **蓝图系统** | `05_tools/07_matrix/blueprints/` | 12 个 JSON 操作模板 |
+
+### 子系统 C：联邦治理（多机协同 + 安全 + 进化）
+
+| # | 维度 | 位置 | 说明 |
+|:-:|:-----|:-----|:------|
+| ⑪ | **多机联邦** | `ORACLE.yaml` + guardd + cross_machine | 3 台 Mac、Git 双远程、WPRA 写分区读聚合 |
+| ⑫ | **安全治理** | `01_core/SOUL.md` L0 约束 + RSA-4096 + 私钥隔离 | L0 硬约束禁止操作/必须确认/必须操作 |
+
+---
+
+## 第三章：目录结构与职责
+
+```
+agent-sync/
+│
+├── 01_core/                    ← 身份规则层（L0）
+│   ├── SOUL.md                   AI 行为规则 + 触发词检测
+│   ├── IDENTITY.tpl.md           身份模板（init.sh 填充）
+│   ├── USER.md                   用户画像
+│   ├── VERSION                   版本唯一来源
+│   ├── MAINTENANCE_GUIDE.md      运维手册
+│   ├── UPDATE_SYSTEM.md          更新体系
+│   ├── NIGHTLY_AUTOMATION.md     夜间自动化
+│   ├── mcp.json                  MCP 服务配置
+│   ├── CONFIG_MANIFEST.yaml      配置清单
+│   ├── automation/               自动化配置入仓（workflows.yaml + plist 模板）
+│   └── CHANGELOG.md              core 变更日志
+│
+├── 02_skills/                   ← 能力层（L2）
+│   ├── active/                    [概念分区] 7 个活跃技能
+│   │   ├── memory_manager/         记忆管理（核心）
+│   │   ├── inbox_refine/           收件箱提纯
+│   │   ├── collect_to_inbox/       内容归集 [legacy]
+│   │   ├── kb_manager/             知识库管理
+│   │   ├── matrix/                 矩阵养号（实现在 05_tools/）
+│   │   ├── sync_manager/           同步备份
+│   │   └── peekaboo_controller/    GUI 自动化（MCP）
+│   └── _archived/                已归档技能（4 个，仅设计文档）
+│
+├── 03_knowledge/                ← 知识层（L1+L4）
+│   └── 99_system/                系统知识（WorkBuddy AI 按需消费）
+│       ├── AI_READING_GUIDE.md     AI 入口
+│       ├── protocols/              4 个行为协议
+│       ├── architecture/           架构文档
+│       ├── matrix/                 矩阵系统文档
+│       ├── dashboard/              Dashboard 设计
+│       ├── pipelines/              流水线规范
+│       ├── prompts/                提示词
+│       └── archive/                已归档系统文档
+│
+├── 04_memory/                   ← 记忆层（L5）
+│   ├── long_term/facts.db         L2 事实库
+│   ├── cross_machine/             跨机数据（machines/status/tasks/encrypted）
+│   └── daily_summaries/           每日摘要
+│
+├── 05_tools/                    ← 工具层（L3）
+│   ├── 00_setup/agentos/          统一 CLI 入口（19 子命令）
+│   ├── 00_setup/guardd/           联邦守护进程（9 模块）
+│   ├── 01_system/                 系统诊断（12 脚本）
+│   ├── 05_crawl/                  内容采集（longcat + content-inspiration）
+│   ├── 07_matrix/                 矩阵养号系统（mc CLI + Camoufox + 12 蓝图）
+│   ├── 08_trae_agent/             Trae AI 编程助手
+│   ├── 09_ave/                    视频工厂
+│   └── 10_dashboard/              监控面板（FastAPI 1521 行 + 15 插件 + 前端）
+│
+├── 99_system/                   ← 项目文档层（维护者视角）
+│   ├── ARCHITECTURE_CONSTITUTION.md [本文件] 架构宪法
+│   ├── INDEX.md                   项目文档索引
+│   ├── AGENTOS-PANORAMA.md        系统全景
+│   └── upgrade_notes/             升级笔记
+│
+├── AGENTS.md                    ← AI 项目指令（精简版）
+├── README.md                    ← 人类入口（精简版）
+├── ORACLE.yaml                  ← 联邦宪法
+├── FEDERATION_GUIDE.md          ← 联邦实操指南
+└── requirements.txt             ← Python 依赖
+```
+
+---
+
+## 第四章：硬规则（不可绕过）
+
+### 规则 1：版本唯一来源
+
+```
+唯一文件：01_core/VERSION
+
+所有文档和代码中的版本号从此文件读取，不允许硬编码。
+例外：guardd.py 在启动时动态读取此文件。
+
+版本规则：
+  X.0.0 — 核心框架或联邦架构升级
+  0.X.0 — 工具级增加或重大升级
+  0.0.X — 配置小项目升级、bugfix
+
+Skills 版本：独立 semver，写在 SKILL_CARD.yaml 中
+```
+
+### 规则 2：SKILL_CARD.yaml 是技能权威元数据
+
+```
+原来：SKILL.md 写描述 + version.json 写版本 → 两处不同步
+现在：SKILL_CARD.yaml 为权威，包含 version/scripts/changelog/dependencies
+      version.json 保留供 export_skills.sh 读取，但版本以 SKILL_CARD 为准
+      SKILL.md 只写人类可读的说明
+
+格式规范参见 02_skills/_template/SKILL_CARD.yaml
+```
+
+### 规则 3：ORACLE.yaml 是账号分配唯一源
+
+```
+废除 accounts_registry.yaml（在 05_tools/07_matrix/ 中标记为废弃）。
+所有账号→机器的分配统一写在 ORACLE.yaml 的 accounts: 节下。
+guardd _sync_account_override() 从 ORACLE.yaml 读取。
+```
+
+### 规则 4：guardd 心跳只写本地
+
+```
+心跳数据仅写入：
+  - agent-local/runtime/guardd/events/
+  - cross_machine/status/{hostname}/heartbeat.json
+  - cross_machine/status/live/{uid}.json
+
+❌ 不再写入 cross_machine/machines/{UID}/heartbeat.json（曾导致 Git 污染）
+Dashboard 通过 guardd 的反向连接推送获取心跳。
+```
+
+### 规则 5：统一 CLI 入口
+
+```
+唯一入口：05_tools/00_setup/agentos/ （python3 -m agentos）
+
+19 个子命令：
+  系统管理（14）：init / sync / skill / tool / config / check / backup /
+                 upgrade / restore / rebuild-vector / localize / register /
+                 cluster-status / cluster-cleanup
+  联邦管理（5）：matrix / ave / crawl / fleet / serve
+
+mc 是 matrix 的快捷别名，指向统一 CLI。
+07_matrix/scripts/agentos/ 保留作为插件库，不再作为独立入口。
+```
+
+### 规则 6：空技能/空工具不留在活跃目录
+
+```
+- 4 个空技能（content_processor/web_crawler/auto_collector/cloakbrowser_controller）
+  已归档到 02_skills/_archived/
+- 4 个空工具目录（02_browser/03_ocr/04_media/06_mobile）
+  已添加 README 说明清空原因
+- 新建技能/工具时：先有实现代码，再写 SKILL.md/SKILL_CARD.yaml
+```
+
+### 规则 7：协议文件路径
+
+```
+行为协议文件位于：03_knowledge/99_system/protocols/
+SOUL.md 中引用的 99_system/protocols/ 是相对于知识库根（03_knowledge/）的路径。
+
+根目录 99_system/ 是项目文档（维护者视角），不含协议文件。
+```
+
+### 规则 8：文档三分法
+
+```
+TRUTH（人工维护，唯一权威）：
+  01_core/（SOUL/USER/MAINTENANCE_GUIDE/mcp.json/VERSION）
+  02_skills/*/SKILL_CARD.yaml
+  ORACLE.yaml
+
+DERIVED（从 TRUTH 自动生成）：
+  IDENTITY.md（从模板 + init.sh 生成）
+  README.md（精简为入口）
+
+VERIFIED（代码 vs 文档自动对账）：
+  agentos check 步骤（模块数/命令数/文件存在性）
+```
+
+### 规则 9：文件权限
+
+| 目录 | 权限 | 说明 |
+|:-----|:------|:------|
+| `01_core/` | 只读 | 通过 `apply-config.sh` 部署 |
+| `02_skills/` | 可读写 | 改前确认 |
+| `03_knowledge/` | 只读 | 改前确认 |
+| `04_memory/` | 只读 | 改前确认 |
+| `05_tools/` | 可读写 | 工具脚本 |
+| `00_bootstrap/` | 可读写 | 改前确认 |
+| `99_system/` | 可读写 | 项目文档 |
+| `agent-local/` | 只读 | 本机数据，不同步 |
+
+### 规则 10：禁止操作
+
+```
+- 禁止直接修改 01_core/ 下的文件（通过 apply-config.sh 部署）
+- 禁止修改 agent-local/ 下的任何文件
+- 禁止修改 04_memory/long_term/facts.db
+- 禁止删除任何文件（只能归档到 90_archive/）
+- 禁止修改 01_core/SOUL.md 中的 L0 硬约束规则本身
+- 禁止将 L3 层原文暴露给外部 API 或第三方服务
+```
+
+---
+
+## 第五章：版本对应关系速查
+
+当你想知道「某段代码在哪个版本」时：
+
+| 组件 | 版本 | 位置 | 版本显式来源 |
+|:-----|:-----|:-----|:------------|
+| AgentOS 框架 | 4.2.0 | 整个系统 | `01_core/VERSION` AGENTOS_VERSION |
+| guardd | 2.3.0 | `05_tools/00_setup/guardd/` | `01_core/VERSION` GUARDD_VERSION |
+| ORACLE schema | 1.0 | `ORACLE.yaml` | `01_core/VERSION` ORACLE_SCHEMA |
+| memory_manager | 1.2.0 | `02_skills/memory_manager/` | SKILL_CARD.yaml |
+| inbox_refine | 1.1.0 | `02_skills/inbox_refine/` | SKILL_CARD.yaml |
+| kb_manager | 1.1.0 | `02_skills/kb_manager/` | SKILL_CARD.yaml |
+| collect_to_inbox | 1.0.0 | `02_skills/collect_to_inbox/` | SKILL_CARD.yaml |
+| matrix | 1.0.0 | `02_skills/matrix/` + `05_tools/07_matrix/` | SKILL_CARD.yaml |
+| sync_manager | 1.1.0 | `02_skills/sync_manager/` | SKILL_CARD.yaml |
+| peekaboo_controller | 1.0.0 | `02_skills/peekaboo_controller/` | SKILL.md |
+
+---
+
+## 第六章：开发决策流程
+
+决定「新功能/新代码应该放哪」的流程：
+
+```
+1. 确定功能属于哪个子系统：
+   ├─ 给 AI 用的？→ 子系统 A（智能体增强）
+   ├─ 自动化执行？→ 子系统 B（执行操作）
+   └─ 多机协同/安全/进化？→ 子系统 C（联邦治理）
+
+2. 确定具体维度（1-12）：
+   从第二章的 12 维全景中找到最匹配的维度
+
+3. 确定目录：
+   从第三章的目录结构与职责中找到对应目录
+
+4. 检查硬规则：
+   第四章的 10 条规则，一条不落
+
+5. 确定版本号：
+   如果涉及：
+   - 核心框架/联邦架构变更 → 升大版本
+   - 工具级别增加或升级 → 升中版本
+   - 配置/bug修复 → 升小版本
+   修改 01_core/VERSION 后，更新 CHANGELOG.md
+
+6. 创建文档：
+   - 新增技能：必须有 SKILL_CARD.yaml + 实现代码
+   - 新增工具：必须有 MODULE.md 或 README.md + 实现代码
+   - 架构变更：在 99_system/ 或 03_knowledge/99_system/ 添加
+```
+
+---
+
+## 附录 A：术语对照
+
+| 术语 | 含义 |
+|:-----|:------|
+| AgentOS | 本系统代号 Claw |
+| WorkBuddy | AI 宿主平台 |
+| SOUL.md | AI 行为规则 + 触发词的最高优先级配置 |
+| ORACLE.yaml | 联邦宪法，机器定义+账号分配+任务计划 |
+| guardd | 守护进程，每 300 秒执行 9 模块循环 |
+| WPRA | Write Partitioned Read Aggregated，写分区读聚合 |
+| SKILL_CARD.yaml | 技能权威元数据（版本/依赖/脚本/变更日志） |
+| 01_core/VERSION | 版本唯一来源 |
+| cross_machine | 04_memory/cross_machine/ 跨机数据交换目录 |
+
+## 附录 B：快速定位表
+
+| 你想做什么 | 去哪个目录 | 看什么文件 |
+|:----------|:-----------|:----------|
+| 改 AI 行为规则 | `01_core/` | SOUL.md |
+| 改用户画像 | `01_core/` | USER.md |
+| 加一个新技能 | `02_skills/` | 参考 _template/ |
+| 改技能代码 | `02_skills/<技能名>/` | *.py |
+| 改知识库 | `03_knowledge/` | 对应分类目录 |
+| 改记忆系统 | `04_memory/` | long_term/ |
+| 加一个工具 | `05_tools/<编号>_<名称>/` | 参考同类工具 |
+| 改矩阵养号 | `05_tools/07_matrix/` | scripts/ |
+| 改看板 | `05_tools/10_dashboard/` | app.py / plugins/ / frontend/ |
+| 改守护进程 | `05_tools/00_setup/guardd/` | guardd.py |
+| 改 CLI | `05_tools/00_setup/agentos/` | main.py |
+| 改联邦宪法 | 根目录 | ORACLE.yaml |
+| 改文档索引 | `99_system/` | INDEX.md |
+| 增版本号 | `01_core/` | VERSION |

mac-agent-os-main/99_system/COMMAND-CENTER-PLAN.md

@@ -0,0 +1,224 @@
+# AgentOS 联邦智能体协作指挥台 — 总体规划 v0.3
+
+> 版本: v0.3（草案） | 最后更新: 2026-06-15
+> 状态: 架构方向已确认，待细化各层
+
+---
+
+## 一、系统架构：命名空间分层
+
+### 顶层入口
+
+```
+agentos                    ← 联邦智能体顶层命令
+├── matrix                社交矩阵（抖音/小红书运营）
+├── ave                   视频工厂（视频制作与编辑）
+├── crawl                 内容采集（互联网内容抓取）
+├── fleet                 联邦管理（多机协同）
+└── serve                 服务管理（MCP/Dashboard/调度）
+```
+
+### 每一层的内部结构
+
+```
+agentos matrix                    社交矩阵
+├── run                           执行养号/互动
+├── account                       账号管理
+├── collect                       主页信息采集
+├── publish                       内容发布（短视频/图文）
+├── blueprint                     蓝图管理
+├── task                          定向任务
+│   ├── comment                   定向评论
+│   ├── search                    搜索任务
+│   └── reply                     回复管理
+├── schedule                      矩阵定时任务
+├── corpus                        语料库
+├── sms                           短信验证码
+└── proxy                         代理管理
+
+
+agentos ave                       视频工厂
+├── render                        视频渲染/生成
+├── script                        脚本/文案生成
+├── material                      素材管理
+│   ├── list                      素材列表
+│   ├── add                       添加素材
+│   └── search                    素材搜索
+├── template                      模板管理
+└── export                        导出/发布
+
+
+agentos crawl                     内容采集
+├── web                           网页内容抓取
+├── video                         视频下载
+├── extract                       信息提取（正文/标题/标签）
+├── schedule                      采集定时任务
+└── source                        采集源管理
+
+
+agentos fleet                     联邦管理
+├── sync                          一键同步所有机器
+├── reconcile                     对账检查
+├── exec                          远程执行命令
+├── status                        集群状态
+└── logs                          日志聚合
+
+
+agentos serve                     服务管理
+├── mcp                           启动 MCP Server（AI 调用入口）
+├── dashboard                     启动/停止看板
+└── schedule                      全局定时调度器
+```
+
+---
+
+## 二、与现有系统的对应关系
+
+| 新结构 | 现有位置 | 迁移方式 |
+|:-------|:---------|:---------|
+| `agentos matrix` | `mc` 全部命令 | **改名为 `agentos`，`mc` 保留为 alias** |
+| `agentos matrix run` | `mc run` | 不变，直接继承 |
+| `agentos matrix collect` | `mc collect` | 不变 |
+| `agentos matrix account` | `mc account` | 不变 |
+| `agentos matrix publish` | `publish_video.py` | 封装为子命令 |
+| `agentos ave` | `09_ave/` (96个脚本) | 封装 CLI |
+| `agentos crawl` | `05_crawl/` (29个脚本) | 封装 CLI |
+| `agentos fleet` | `fleet_sync.sh` + `fleet_reconcile.sh` | 封装 CLI |
+| `agentos serve mcp` | 新建 | 新增 |
+| `agentos serve dashboard` | `run.py 9988` | 封装 CLI |
+
+---
+
+## 三、Dashboard 看板的映射
+
+看板的导航结构直接映射到 `agentos` 的命名空间：
+
+```
+┌─── AgentOS 联邦指挥台 ──────────────────────────┐
+│                                                    │
+│  [矩阵]  [视频工厂]  [内容采集]  [联邦]  [服务]     │
+│                                                    │
+│  ┌─ 矩阵 ───────────────────────────────────────┐  │
+│  │  账号管理 │ 养号执行 │ 信息采集 │ 内容发布    │  │
+│  │  蓝图管理 │ 定向评论 │ 定时任务 │ 语料库      │  │
+│  └──────────────────────────────────────────────┘  │
+│                                                    │
+│  ┌─ 视频工厂 ────────────────────────────────────┐  │
+│  │  渲染任务 │ 脚本生成 │ 素材库 │ 模板          │  │
+│  └──────────────────────────────────────────────┘  │
+│                                                    │
+│  ┌─ 内容采集 ────────────────────────────────────┐  │
+│  │  采集任务 │ 源管理 │ 采集历史                  │  │
+│  └──────────────────────────────────────────────┘  │
+│                                                    │
+│  ┌─ 联邦 ────────────────────────────────────────┐  │
+│  │  机器状态 │ 一键同步 │ 对账检查 │ 远程Shell   │  │
+│  └──────────────────────────────────────────────┘  │
+│                                                    │
+│  ┌─ 服务 ────────────────────────────────────────┐  │
+│  │  MCP 状态 │ Dashboard日志 │ 全局定时任务      │  │
+│  └──────────────────────────────────────────────┘  │
+└────────────────────────────────────────────────────┘
+```
+
+---
+
+## 四、MCP 暴露策略
+
+按分层暴露，每个领域提供一组 MCP 工具：
+
+```
+agentos-mcp（总入口，自动发现所有子模块）
+│
+├── matrix/*             社交矩阵工具
+│   ├── run_nurture      执行养号
+│   ├── collect_info     采集主页
+│   ├── publish_video    发布视频
+│   ├── task_comment     定向评论
+│   └── account_status   账号状态
+│
+├── ave/*                视频工厂工具 
+│   ├── render_video     渲染视频
+│   └── generate_script  生成脚本
+│
+├── crawl/*              内容采集工具
+│   ├── fetch_web        抓取网页
+│   └── download_video   下载视频
+│
+└── fleet/*              联邦管理工具
+    ├── exec_remote      远程执行
+    ├── sync_all         同步
+    └── cluster_status   集群状态
+```
+
+---
+
+## 五、Dashboard 插件映射
+
+现有的插件系统保持不变，新增插件对应新命名空间：
+
+| 插件 | 对应命名空间 | 状态 |
+|:-----|:------------|:------|
+| `plugins/matrix.py` | `agentos matrix` | ✅ 已有，需改造 |
+| `plugins/kb_api.py` | 属于 `serve` | ✅ 已有 |
+| `plugins/ave.py` | `agentos ave` | ✅ 已有 |
+| `plugins/guardd.py` | `agentos fleet` | ✅ 已有 |
+| `plugins/federation.py` | `agentos fleet` | 🔴 新增 |
+| `plugins/scheduler.py` | `agentos serve schedule` | 🔴 新增 |
+| `plugins/crawl.py` | `agentos crawl` | 🔴 新增 |
+
+---
+
+## 六、当前 Dashboard 在此架构中的位置
+
+**Dashboard 不是"一个模块"，而是"所有模块的统一操作界面"。**
+
+```
+agentos serve dashboard ← 启动看板
+                           ↓
+                    Dashboard Web
+                    ├── 矩阵标签页    → 调用 agentos matrix *
+                    ├── 视频工厂标签页 → 调用 agentos ave *
+                    ├── 内容采集标签页 → 调用 agentos crawl *
+                    ├── 联邦标签页    → 调用 agentos fleet *
+                    └── 服务标签页    → 调用 agentos serve *
+```
+
+每个标签页的**操作按钮**调用对应的 `agentos` 命令。
+每个标签页的**数据展示**来自各机器的 API 聚合。
+
+---
+
+## 七、待讨论问题（下一轮）
+
+架构方向定了之后，需要细化的点：
+
+### 7.1 迁移策略
+
+当前 `mc` 已经有很多脚本、蓝图、配置引用它。迁移方案：
+- **A) 一步到位**：把所有 `mc` 引用改为 `agentos`，`mc` 作为 alias 保留
+- **B) 渐进迁移**：先加 `agentos` 入口，`mc` 继续可用，逐步过渡
+
+### 7.2 命名空间的 CLI 实现方式
+
+- **A) 单 CLI 多级子命令**：一个 `agentos` 二进制，通过子命令分发（当前 `mc` 的做法）
+- **B) 多 CLI 独立安装**：`agentos-matrix`、`agentos-ave` 各自独立
+
+### 7.3 各领域的开发优先级
+
+当前资源有限，先做哪个领域？
+
+| 领域 | 现有成熟度 | 建议优先级 |
+|:-----|:----------|:-----------|
+| matrix（社交矩阵） | 最成熟，91个脚本 | **Phase 1** |
+| fleet（联邦管理） | 基础已通 | **Phase 2** |
+| ave（视频工厂） | 96个脚本但未 CLI 化 | **Phase 3** |
+| crawl（内容采集） | 29个脚本 | **Phase 4** |
+| serve（服务管理） | 新建 | 穿插进行 |
+
+---
+
+你觉得这个结构清晰了吗？如果没问题，下一轮我们就定：
+1. 迁移策略（一步到位 vs 渐进）
+2. CLI 实现方式（单CLI vs 多CLI）
+3. 开发优先级

mac-agent-os-main/99_system/FIX_PLAN.md

@@ -0,0 +1,332 @@
+# AgentOS 修复方案与落地清单
+
+> 版本: 1.0 | 基于 2026-06-21 审计报告
+> 按优先级排列，每项含：耗时 / 风险 / 前置依赖
+
+---
+
+## 第一步：Git 仓库减肥（P0，立刻做）
+
+### 1.1 诊断：先看什么东西在吃空间
+
+```bash
+# 进入仓库
+cd ~/workbuddy-agent-os/agent-sync
+
+# 1. 看总大小
+du -sh .git                          # .git 目录大小（预估 400MB）
+du -sh .                             # 工作树大小（预估 600MB）
+
+# 2. 找最大的文件（被 git 追踪的）
+git rev-list --objects --all | \
+  git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | \
+  awk '/^blob/ {print $3, $4}' | \
+  sort -rn | head -20
+
+# 3. 看哪些大文件类型在 git 索引里
+git ls-files | grep -E '\.(png|jpg|jpeg|gif|svg|ico|pdf)$'
+git ls-files | grep -E '\.(so|dylib|a|o)$'
+git ls-files | grep -E '(profiles|cache|chroma|node_modules)'
+```
+
+**预期发现：** 大文件来源通常是：
+1. 浏览器 Profile 文件夹（曾未加 .gitignore 时被提交过）
+2. 截图 .png 文件（dashboard、matrix screenshots）
+3. ChromaDB SQLite 文件
+4. Python .so 编译文件
+5. longcat 浏览器缓存
+
+---
+
+### 1.2 更新 .gitignore（排除所有不该进 Git 的东西）
+
+在现有 `.gitignore` 末尾追加：
+
+```
+# ────── v4.2.0 新增排除项 ──────
+
+# 图片文件（截图、素材，不入库）
+*.png
+*.jpg
+*.jpeg
+*.gif
+*.svg
+*.ico
+*.webp
+
+# ChromaDB 数据（各机独立）
+chroma.sqlite3
+**/chroma/
+
+# 前端构建产物
+node_modules/
+dist/
+build/
+
+# ML 模型文件
+*.pth
+*.bin
+*.onnx
+*.npy
+*.npz
+
+# 运行时数据目录
+cross_machine/data/
+
+# Matrix 截图
+05_tools/07_matrix/screenshots/
+
+# AVE 输出
+09_ave/output/
+09_ave/cache/
+
+# 系统报告归档
+reports/
+
+# Dashboard 前端产物
+05_tools/10_dashboard/frontend/node_modules/
+05_tools/10_dashboard/frontend/dist/
+```
+
+---
+
+### 1.3 从 Git 追踪中移除已在大文件（不删文件，只删追踪）
+
+```bash
+# 对每一类已追踪的大文件执行 git rm --cached
+
+# 1. 移除所有图片文件（如果被追踪过）
+git rm --cached -r --ignore-unmatch 05_tools/07_matrix/screenshots/
+git rm --cached -r --ignore-unmatch 05_tools/10_dashboard/*.png
+git ls-files | grep -E '\.(png|jpg|jpeg|gif)$' | xargs -r git rm --cached
+
+# 2. 移除浏览器 Profile（如果被追踪过）
+git rm --cached -r --ignore-unmatch 05_tools/07_matrix/profiles/
+git rm --cached -r --ignore-unmatch 05_tools/05_crawl/longcat/profiles/
+
+# 3. 移除 ChromaDB 数据
+git rm --cached -r --ignore-unmatch 04_memory/vector_db/
+git ls-files | grep chroma | xargs -r git rm --cached
+
+# 4. 移除运行时数据
+git rm --cached -r --ignore-unmatch cross_machine/data/
+git rm --cached -r --ignore-unmatch 04_memory/cross_machine/data/
+
+# 5. 移除旧的迁移目录
+git rm --cached -r --ignore-unmatch 07_migration/
+
+# 6. 提交本次清理
+git commit -m "chore(git): 清理已追踪的大文件，更新 .gitignore v4.2.0"
+```
+
+---
+
+### 1.4 重写 Git 历史以永久删除大文件（可选但推荐）
+
+> ⚠️ 这一步会改变 commit hash，所有机器需要重新 clone。
+> **但如果 1.3 步提交后，远程仓库大小仍然不变，就必须做这一步。**
+> 因为历史 commit 中仍然保留着大文件——.gitignore 和 git rm 只影响未来。
+
+**方案 A：使用 git filter-repo（推荐）**
+
+```bash
+# 安装 git-filter-repo
+pip install git-filter-repo
+
+# 在全新 clone 上操作（不要在原仓库，防止意外）
+cd /tmp
+git clone ~/workbuddy-agent-os/agent-sync agentos-clean
+cd agentos-clean
+
+# 删除历史中所有 .png/.jpg/.so/.mp4 等大文件
+git filter-repo \
+  --path-glob '*.png' --path-glob '*.jpg' --path-glob '*.so' \
+  --path-glob '*.mp4' --path-glob 'chroma.sqlite3' \
+  --path '05_tools/07_matrix/profiles/' \
+  --path '05_tools/05_crawl/longcat/profiles/' \
+  --path '04_memory/vector_db/' \
+  --invert-paths
+
+# 验证大小
+du -sh .git
+
+# 如果还是大，再按大小找 Top offenders
+git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectsize) %(rest)' | sort -rn | head -20
+```
+
+**方案 B：使用 BFG Repo-Cleaner（更简单）**
+
+```bash
+# 下载 BFG
+wget https://repo1.maven.org/maven2/com/madgag/bfg/1.14.0/bfg-1.14.0.jar
+
+# 清理 >10MB 的文件
+java -jar bfg-1.14.0.jar --strip-blobs-bigger-than 10M agentos-clean
+
+# 清理指定模式
+java -jar bfg-1.14.0.jar --delete-files '*.png' agentos-clean
+java -jar bfg-1.14.0.jar --delete-files '*.so' agentos-clean
+```
+
+**方案 C：如果 filter-repo 太复杂，最小化方案**
+
+```bash
+# 只清理最大的文件类型，保留历史完整性
+git filter-branch --force --index-filter \
+  "git rm --cached --ignore-unmatch -r \
+    05_tools/07_matrix/profiles/ \
+    05_tools/05_crawl/longcat/profiles/ \
+    04_memory/vector_db/ \
+    07_migration/" \
+  --prune-empty --tag-name-filter cat -- --all
+
+# 回收空间
+git reflog expire --expire=now --all
+git gc --aggressive --prune=now
+```
+
+---
+
+### 1.5 推送到远程（所有操作完成后）
+
+```bash
+# 强制推送（因为历史被重写了）
+git push origin --force --all
+git push origin --force --tags
+
+# 验证远程仓库大小
+curl -s https://api.github.com/repos/babycalf/mac-agent-os | grep "size"
+# size 单位是 KB，目标 < 50000（即 < 50MB）
+```
+
+---
+
+### 1.6 其他机器重新 clone
+
+```bash
+# 5kechengdeAir 和 7kecheng 上执行
+cd ~
+mv workbuddy-agent-os workbuddy-agent-os.bak  # 备份旧目录
+git clone [email protected]:babycalf/mac-agent-os.git workbuddy-agent-os/agent-sync
+cd workbuddy-agent-os/agent-sync && bash 00_bootstrap/init.sh
+```
+
+---
+
+### 1.7 验证结果
+
+```bash
+# 1. 本地仓库大小
+du -sh .git                              # 期望 < 50MB
+du -sh .                                 # 期望 < 100MB（不含 agent-local/）
+
+# 2. 不再有大文件被追踪
+git ls-files | grep -E '\.(png|jpg|so|mp4)$'  # 期望 0 结果
+
+# 3. agentos check 仍然通过
+cd ~/workbuddy-agent-os/agent-sync
+python3 -m agentos check --quick
+
+# 4. clone 速度测试（从另一台机器）
+time git clone [email protected]:babycalf/mac-agent-os.git test-clone
+# 期望 < 30 秒（之前可能 > 5 分钟）
+```
+
+---
+
+## 第二步：修复高优问题（P1）
+
+完成 Git 减肥后，按以下顺序修复：
+
+| 优先级 | 问题 | 方案 | 预估工时 |
+|:------:|:-----|:-----|:--------|
+| P1-1 | **oMLX Chat API 500** | 诊断 Qwen3-8B 错误 → 尝试降级/换模型/用 VLM 替代 | 1-2h |
+| P1-2 | **collect_to_inbox v2.0** | 补全 01_submissions/ 扫描逻辑（约 40 行代码） | 2h |
+| P1-3 | **AVE service_layer 空目录** | 确认 09_ave TOOL.md 说的 API 是否需要 → 补全或降级文档 | 1h |
+| P1-4 | **agentos check 增加宪法对账** | 在 check.py 中比较 CONSTITUTION.md 版本 vs 实际代码一致性 | 2h |
+| P1-5 | **删除 accounts_registry.yaml** | 确认无代码引用后删除（已标记废弃） | 10min |
+
+---
+
+## 第三步：中期改进（P2）
+
+| 优先级 | 问题 | 方案 | 预估 |
+|:------:|:-----|:-----|:-----|
+| P2-1 | **app.py 1521 行拆分** | 按已有 routes/ 目录拆分为 3-4 个路由模块 | 1d |
+| P2-2 | **添加测试基础** | guardd 核心模块 + semantic_search RRF 写单元测试 | 1d |
+| P2-3 | **统一日志格式** | 所有 Python 模块使用 logging + 统一格式字符串 | 4h |
+| P2-4 | **双 agentos 插件加载加固** | 把 07_matrix/agentos/plugins/ 复制到 00_setup/agentos/federation_plugins/ | 2h |
+| P2-5 | **FEDERATION_GUIDE.md 完整对账** | 遍历全文确认所有数字与实际一致 | 2h |
+
+---
+
+## 第四步：长期优化（P3）
+
+| 项目 | 说明 | 预估 |
+|:-----|:------|:-----|
+| CommandCenter | 实时跨机通信，替代 15min Git 同步延迟 | 2-4 周 |
+| 独立运行模式 | 脱离 WorkBuddy 也可运行 | 2-3 周 |
+| 技能市场 | SKILL_CARD.yaml 标准化 + 社区技能安装 | 1-2 周 |
+| 内容工厂 | 采集→AI 分析→AVE 生成→自动发布全流水线 | 3-4 周 |
+
+---
+
+## 落地路线图（甘特图）
+
+```
+时间线      今天      本周      下周      下月      季度
+            │        │        │        │        │
+Git 减肥    ████████▓░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+诊断+清理       ██████▓
+filter-repo           ██████▓
+各机re-clone                ██▓
+────────────────────────────────────────────────
+oMLX 修复           ██████▓
+collect_to_inbox           ██████▓
+AVE 确认                       ██▓
+宪法对账                         ██▓
+────────────────────────────────────────────────
+app.py 拆分                        ██████████▓
+测试基础                             ██████▓
+统一日志                                ██████▓
+────────────────────────────────────────────────
+CommandCenter                               ████████████▓
+独立运行                                         ████████████▓
+```
+
+---
+
+## 执行建议
+
+### 执行的顺序很关键
+
+```
+第一步做 Git 减肥 → 然后再做其他事情
+                     ↑
+               如果不先做这个：
+               - 其他机器 git pull 要等 5 分钟
+               - push 频繁超时
+               - 新机器部署痛苦
+```
+
+### 每个步骤的风险控制
+
+```
+Git filter-repo 前：
+  ✅ 备份原仓库（tar czf backup.tar.gz .git）
+  ✅ 在临时目录操作（不在原目录）
+  ✅ 先在一台机器验证，再通知其他机器
+  ✅ 准备好 rollback 方案
+```
+
+### 日常维护习惯
+
+```bash
+# 每次 push 前快速检查
+du -sh .git                              # 超过 100MB 要警惕
+git ls-files | grep -E '\.(png|jpg|so)$' # 应为空
+git status --porcelain | wc -l           # 干净工作区
+
+# 每月一次深度检查
+git count-objects -v                     # 看 pack 文件数量和大小
+```

mac-agent-os-main/99_system/INDEX.md

@@ -0,0 +1,95 @@
+# AgentOS 项目文档索引
+
+> 最后更新: 2026-06-21 | 版本: 4.2.0
+
+## 系统身份与规则（01_core/ → ~/.workbuddy/）
+
+| 文件 | 说明 | 加载方式 |
+|:-----|:------|:---------|
+| **CONSTITUTION.md** | **架构宪法（先读此文件）** | **部署到 ~/.workbuddy/ 按需加载** |
+| SOUL.md | AI 行为规则、模式切换、安全边界 | 常驻 ~750 tokens/次 |
+| IDENTITY.md | 系统身份、设备信息（从模板生成） | 常驻 |
+| USER.md | 用户画像与偏好 | 常驻 |
+| MAINTENANCE_GUIDE.md | 运维操作手册 | 按需查阅 |
+| mcp.json | MCP 服务配置（filesystem/memory/peekaboo） | WorkBuddy 启动时加载 |
+| VERSION | 版本唯一来源 | 所有文档以此为准 |
+
+## 行为协议（03_knowledge/99_system/protocols/）
+
+| 协议 | 触发场景 | 加载时机 |
+|:-----|:---------|:---------|
+| meta-thinking | 升维思考、本质追问 | 触发词激活 ~200 tokens |
+| cross-domain | 跨界类比、新视角 | 触发词激活 |
+| stuck-intervention | 卡壳暂停给选项 | 条件触发 |
+| knowledge-review | 知识入库审查 | 触发词激活 |
+
+## 技能（02_skills/）
+
+当前活跃 7 个技能（4 个已归档，见 `02_skills/_archived/README.md`）：
+
+| 技能 | 版本 | 说明 | 状态 |
+|:-----|:-----|:------|:-----|
+| memory_manager | 1.2.0 | 五级记忆体 + 语义检索 | ✅ |
+| inbox_refine | 1.0.0 | 收件箱 AI 分类归档 | ✅ |
+| collect_to_inbox | 2.0.0 | 提交箱→收件箱归集 | ⚠️ 文档降级（代码未同步） |
+| kb_manager | 1.1.0 | 知识库管理 | ✅ |
+| matrix | 1.0.0 | 矩阵养号（实现在 05_tools/07_matrix/） | ✅ |
+| sync_manager | 1.1.0 | 同步备份 | ✅ |
+| peekaboo_controller | 1.0.0 | macOS GUI 自动化（MCP） | ✅ |
+
+## Dashboard 看板
+
+| 文档 | 路径 | 说明 |
+|:-----|:------|:------|
+| Dashboard README | `05_tools/10_dashboard/README.md` | **看板架构、API、CMD_REGISTRY、前端调用规范（必读）** |
+| 五层架构审计 | `PLANS/AUDIT_5LAYER_REPORT.md` | 所有视图的合规状态 |
+| 命令传导统一治理 | `PLANS/COMMAND_UNIFICATION_PLAN.md` | 2026-06-25 治理方案 |
+
+## 工具（05_tools/）
+
+| 工具 | 说明 | 调用方式 |
+|:-----|:------|:---------|
+| 00_setup/agentos/ | 系统管理 CLI（init/check/backup/upgrade/…14 命令） | 命令行 |
+| 00_setup/guardd/ | 联邦守护进程（9 模块，300 秒周期） | launchd 自动 |
+| 01_system/ | 系统诊断脚本（12 个 .py） | agentos check / 手动 |
+| 05_crawl/ | 内容采集（longcat + content-inspiration） | 手动 / API |
+| 07_matrix/ | 矩阵养号（Camoufox 浏览器 + 12 个蓝图） | mc CLI / Dashboard |
+| 08_trae_agent/ | Trae AI 编程助手 | CLI |
+| 09_ave/ | 视频工厂 | CLI / API（8001 端口） |
+| 10_dashboard/ | 监控面板（FastAPI 1521 行 + 15 插件） | 浏览器 :9988 |
+
+## 联邦系统
+
+| 文档 | 路径 |
+|:-----|:------|
+| 联邦宪法 | ORACLE.yaml |
+| 联邦使用指南 | FEDERATION_GUIDE.md |
+| 联邦架构 | 03_knowledge/99_system/architecture/federated-multi-machine-architecture.md |
+| 加载与检索架构 | 03_knowledge/99_system/architecture/loading-architecture.md |
+| cross_machine 结构 | 04_memory/cross_machine/ |
+| 守护进程源码 | 05_tools/00_setup/guardd/guardd.py（1166 行） |
+
+## 架构全景
+
+| 文档 | 路径 | 说明 |
+|:-----|:------|:------|
+| **架构宪法**（先读此文件） | **CONSTITUTION.md**（根目录，同时部署到 ~/.workbuddy/） | **总纲：硬规则 + 十二维全景 + 版本规则 + 开发决策流程** |
+| 系统全景 | 99_system/AGENTOS-PANORAMA.md | 完整系统概述 |
+| 联邦多机架构 | 03_knowledge/99_system/architecture/ | 技术架构设计 |
+| 内容收集全链路 | 03_knowledge/99_system/pipelines/ | 采集→归档规范 |
+| 记忆与知识体系 | 03_knowledge/99_system/architecture/ | 分层记忆设计 |
+
+## 版本体系
+
+版本唯一源：`01_core/VERSION`
+
+| 组件 | 版本 |
+|:-----|:-----|
+| AgentOS 框架 | 4.2.0 |
+| guardd 守护进程 | 2.3.0 |
+| ORACLE schema | 1.0 |
+
+版本规则：
+- **大版本（X.0.0）** — 核心框架或联邦架构升级
+- **中版本（0.X.0）** — 工具级增加或重大升级
+- **小版本（0.0.X）** — 配置小项目升级、bugfix

mac-agent-os-main/99_system/OPTIMIZATION-ASSESSMENT.md

@@ -0,0 +1,368 @@
+# AgentOS 功能节点全量拆解与优化评估
+
+> 版本：v1.0 | 最后更新：2026-06-15
+> 用途：逐条评估每个功能节点的现状、问题、优化方向、难度、影响范围
+
+---
+
+## 符号说明
+
+| 标记 | 含义 |
+|:----:|:------|
+| ⭐ | 难度：★易～★★★★★极难 |
+| 📐 | 影响范围：局部/模块/系统/跨机 |
+| 🔗 | 依赖关系：该节点优化后会影响的其他节点 |
+| 🎯 | 核心痛点：当前最突出的问题 |
+
+---
+
+## 一、代码仓储与同步（底层基础设施）
+
+### 1.1 Git 仓库管理
+
+| 维度 | 内容 |
+|:-----|:------|
+| **现状** | 单仓库 ~1GB（含 .git 409MB + 工作树 594MB），包含浏览器缓存 `.so` 文件 |
+| **问题** | push 超时、clone 慢、冲突频繁、新机器部署痛苦 |
+| **目标** | 纯代码仓库 ≤50MB，运行时数据不入库 |
+| **方案** | ① 更新 .gitignore ② git filter-branch 清除历史大文件 ③ 配置 git-lfs 管理大文件 |
+| **难度** | ⭐⭐（git filter-branch 需谨慎操作，建议先备份） |
+| **影响** | 📐 跨机 — 所有机器 clone/push 速度提升 10x |
+| **🔗 连锁** | → 路径统一(1.3) → 依赖管理(1.4) 前置条件 |
+
+### 1.2 多机同步机制
+
+| 维度 | 内容 |
+|:-----|:------|
+| **现状** | WPRA 写分区·读聚合 v2.0。每台机器写 machines/{uid}/，Dashboard 聚合读取。但 guardd 仍有全局写入 |
+| **问题** | `_registry.json` 历史冲突、`git add -A` 跨文件 staging、架构复杂 |
+| **目标** | 废除 WPRA 写入端，改为 ORACLE 只读 + heartbeat 仅汇报 |
+| **方案** | ① 创建 ORACLE.yaml（只读宪法）② 每台机器读 ORACLE 对账 ③ heartbeat 精简为仅状态汇报 ④ 删除 WPRA 写入代码 |
+| **难度** | ⭐⭐⭐（涉及 guardd、Dashboard、matrix_mgmt 多个模块修改） |
+| **影响** | 📐 系统 — 消除 Git 冲突根源，简化整体架构 |
+| **🔗 连锁** | → 影响所有涉及多机数据同步的模块 |
+
+### 1.3 路径统一
+
+| 维度 | 内容 |
+|:-----|:------|
+| **现状** | 12+ 处 `Path.home() / "workbuddy-agent-os"` 硬编码在 app.py，其他文件更多 |
+| **问题** | 每台机器 home 目录/结构不同，改一台其他都断 |
+| **目标** | 所有代码使用 `$AGENT_SYNC` / `$AGENT_LOCAL` 环境变量 |
+| **方案** | ① 在 .zshrc 定义环境变量 ② 批量替换所有脚本中的硬编码路径 ③ Dashboard base.py 已经定义了常量，推广使用 |
+| **难度** | ⭐（机械替换，但需全面扫描所有文件） |
+| **影响** | 📐 跨机 — 解决 80% 的跨机兼容性问题 |
+| **🔗 连锁** | → 是其他所有优化的前置条件 |
+
+### 1.4 依赖与环境管理
+
+| 维度 | 内容 |
+|:-----|:------|
+| **现状** | Python 3.9(系统) + 3.13(管理) 并存，orjson 签名问题，Camoufox 依赖复杂 |
+| **问题** | 新机器部署步骤多，环境不一致导致同一代码表现不同 |
+| **目标** | 一键检测+安装+修复环境 |
+| **方案** | 升级 init.sh：检测 Python/Node/依赖/签名问题，自动修复或报清晰错误 |
+| **难度** | ⭐⭐（编写检测逻辑，测试各机器） |
+| **影响** | 📐 局部 — 降低新机器部署时间从 2 小时到 10 分钟 |
+| **🔗 连锁** | → 依赖 1.1(仓库干净) 和 1.3(路径统一) |
+
+---
+
+## 二、账号管理体系
+
+### 2.1 账号注册与配置（accounts.yaml）
+
+| 维度 | 内容 |
+|:-----|:------|
+| **现状** | 本地 `agent-local/tools/matrix/config/accounts.yaml` 定义账号，WPRA 有一份拷贝 |
+| **问题** | 两份数据不一致时互相覆盖，同步逻辑复杂 |
+| **目标** | 单一权威来源，本地配置规范化 |
+| **方案** | 废除 WPRA 的 accounts.yaml，只用本地一份。ORACLE.yaml 只定义"哪个机器有哪些身份" |
+| **难度** | ⭐⭐（需修改 matrix_mgmt.py 的读取逻辑） |
+| **影响** | 📐 模块 — 消除账号数据的不一致性 |
+| **🔗 连锁** | → 依赖 1.2(同步机制) |
+
+### 2.2 身份管理（Identity）
+
+| 维度 | 内容 |
+|:-----|:------|
+| **现状** | 身份按手机号聚合，一个身份可绑定多平台。已在 Dashboard 实现删除/解绑功能 |
+| **问题** | 基本功能已有，但身份目录命名不一致（有的 `phone_xxx` 有的直接用账号名） |
+| **目标** | 统一身份命名规范，梳理现有身份的目录结构 |
+| **方案** | 将独立身份目录（douyin_133 等）统一命名为 phone_xxx，清理 xhs_01 等遗留目录 |
+| **难度** | ⭐（主要是数据迁移工作，系统逻辑已支持） |
+| **影响** | 📐 局部 — Dashboard 身份管理页更清晰 |
+| **🔗 连锁** | → 依赖 2.1(账号配置) |
+
+### 2.3 登录态管理
+
+| 维度 | 内容 |
+|:-----|:------|
+| **现状** | Cookie 存储在 `identities/{name}/user_data/cookies.sqlite`，可通过 `mc login` 扫码登录 |
+| **问题** | Cookie 过期后系统不一定能及时发现，需人工检查 |
+| **目标** | 自动检测 Cookie 有效性 + 登录态过期告警 |
+| **方案** | 在 guardd 或定时任务中加入 Cookie 有效性检查，过期时 Dashboard 标红 |
+| **难度** | ⭐⭐（需要实现 Cookie 有效性验证逻辑） |
+| **影响** | 📐 局部 — 减少"以为登录了其实过期了"的情况 |
+| **🔗 连锁** | → 依赖 1.4(环境) 和 2.1(账号) |
+
+---
+
+## 三、养号执行系统（Matrix）
+
+### 3.1 mc CLI
+
+| 维度 | 内容 |
+|:-----|:------|
+| **现状** | 统一 CLI 入口，10+ 子命令（run/account/blueprint/task/remote...） |
+| **问题** | mc 脚本引用 `/Users/5kecheng/` 旧路径（已修复） |
+| **目标** | CLI 稳定可用，路径 0 硬编码 |
+| **方案** | 完成路径审计（已做了 90%），确保所有子命令都能跨机执行 |
+| **难度** | ⭐ |
+| **影响** | 📐 模块 |
+
+### 3.2 养号引擎（engine.py）
+
+| 维度 | 内容 |
+|:-----|:------|
+| **现状** | BatchEngine 异步并行，支持 Camoufox 浏览器 + 原子操作组合 |
+| **问题** | orjson 签名问题导致部分机器 Camoufox 无法启动（已修复） |
+| **目标** | 稳定运行，跨机一致 |
+| **方案** | 环境修复 + 更好的错误提示（不要抛 orjson 裸错误） |
+| **难度** | ⭐⭐ |
+| **影响** | 📐 模块 |
+
+### 3.3 14 个蓝图
+
+| 维度 | 内容 |
+|:-----|:------|
+| **现状** | 抖音 9 个 + 小红书 4 个 + 录制 1 个 |
+| **问题** | 部分蓝图执行失败率高（如评论蓝图遇到验证码） |
+| **目标** | 提高执行成功率 |
+| **方案** | 增加重试机制、验证码处理、更智能的等待 |
+| **难度** | ⭐⭐⭐（反爬对抗，需要持续优化） |
+| **影响** | 📐 局部 |
+
+### 3.4 日常养号调度器（nurture_daily.py）
+
+| 维度 | 内容 |
+|:-----|:------|
+| **现状** | 调度器 v1.0，支持多身份并发、随机打乱、错峰启动 |
+| **问题** | 调度规则硬编码在脚本中，不与 ORACLE 联动 |
+| **目标** | 调度器从 ORACLE 读取规则（什么时候跑、跑什么） |
+| **方案** | nurture_daily.py 增加 `--oracle` 模式，读取 ORACLE.yaml 确定任务参数 |
+| **难度** | ⭐⭐ |
+| **影响** | 📐 模块 |
+
+### 3.5 采集器（collect_batch_runner.py）
+
+| 维度 | 内容 |
+|:-----|:------|
+| **现状** | 批量主页信息采集，支持全部/按手机号/按账号 |
+| **问题** | 采集进度通过本地 JSON 文件共享，与其他机器不互通 |
+| **目标** | 采集结果通过心跳/ORACLE 共享 |
+| **方案** | 采集完成后更新 heartbeat.json，其他机器/Dashboard 可见 |
+| **难度** | ⭐ |
+| **影响** | 📐 局部 |
+
+---
+
+## 四、Dashboard 看板
+
+### 4.1 app.py（后端 API）
+
+| 维度 | 内容 |
+|:-----|:------|
+| **现状** | 3000+ 行单文件，包含所有 API 路由 |
+| **问题** | 太大难以维护，两次出现重复路由导致功能不可用 |
+| **目标** | 拆分为多个路由模块 |
+| **方案** | 按功能拆分：matrix_routes.py, system_routes.py, kb_routes.py 等 |
+| **难度** | ⭐⭐⭐（后端重构，需确保 API 兼容性） |
+| **影响** | 📐 模块 — 提高可维护性，减少重复路由 Bug |
+| **🔗 连锁** | → 依赖 1.2(同步) 的部分 API 数据源会变化 |
+
+### 4.2 index.html（前端）
+
+| 维度 | 内容 |
+|:-----|:------|
+| **现状** | 4000+ 行单页，包含所有 UI 和交互逻辑 |
+| **问题** | 巨大难以维护，HTML 注释混入 JS 导致页面黑屏 |
+| **目标** | 拆分为多文件组件 |
+| **方案** | 按视图拆分：matrix-accounts.html, matrix-blueprints.html, matrix-settings.html |
+| **难度** | ⭐⭐⭐（需重建前端加载机制） |
+| **影响** | 📐 模块 |
+
+### 4.3 身份管理页
+
+| 维度 | 内容 |
+|:-----|:------|
+| **现状** | ✅ 已实现，按身份分组展示，支持删除身份/解绑平台 |
+| **问题** | 基本功能可用，缺少批量操作 |
+| **目标** | 稳定使用，按需扩展 |
+| **难度** | ⭐ |
+| **影响** | 📐 局部 |
+
+### 4.4 命令与任务页
+
+| 维度 | 内容 |
+|:-----|:------|
+| **现状** | 全部养号 + 批量执行 + 定向评论 三个 TAB |
+| **问题** | ✅ 上次已修复重复路由导致"全部养号"不可用的问题 |
+| **目标** | 稳定使用 |
+| **难度** | ⭐ |
+| **影响** | 📐 局部 |
+
+---
+
+## 五、知识库系统
+
+### 5.1 知识库存储（03_knowledge/）
+
+| 维度 | 内容 |
+|:-----|:------|
+| **现状** | 按分类目录（00_inbox ~ 50_resources）组织，包含采集的教程、方法、参考等 |
+| **问题** | 无固定分类规范，新知识入库标准不明确 |
+| **目标** | 规范化分类体系 |
+| **方案** | 制定知识卡片模板 + 分类规则文档 |
+| **难度** | ⭐ |
+| **影响** | 📐 局部 |
+
+### 5.2 向量库（ChromaDB）
+
+| 维度 | 内容 |
+|:-----|:------|
+| **现状** | ChromaDB + oMLX Qwen3-Embedding-0.6B，1024 维向量 |
+| **问题** | 现有 1 个自动化任务（02:30 向量更新，ACTIVE），但记忆提炼的向量更新已暂停 |
+| **目标** | 知识库更新后自动重建向量索引 |
+| **方案** | 保留现有自动化，确保跑通 |
+| **难度** | ⭐ |
+| **影响** | 📐 局部 |
+
+### 5.3 记忆系统（04_memory/）
+
+| 维度 | 内容 |
+|:-----|:------|
+| **现状** | L1 关键词索引 + L2 facts.db + L3 原文，四层记忆体系 |
+| **问题** | 原 02:00 记忆提炼已 PAUSED，向量更新也已停，记忆系统不完整 |
+| **目标** | 恢复记忆提炼自动化 |
+| **方案** | 调查 PAUSED 原因（oMLX 稳定性？脚本错误？）→修复→恢复 |
+| **难度** | ⭐⭐（需先诊断 PAUSED 原因） |
+| **影响** | 📐 系统 — 影响语义检索质量 |
+| **🔗 连锁** | → 依赖 1.4(环境) oMLX 须稳定运行 |
+
+---
+
+## 六、远程执行与互联
+
+### 6.1 mc remote（SSH）
+
+| 维度 | 内容 |
+|:-----|:------|
+| **现状** | `mc remote exec/status/ping/list` 已实现，通过 SSH 执行远程命令 |
+| **问题** | 需要 SSH key 配置、主机名/IP 对应关系。本机未装 Tailscale，局域网可用但公网不可达 |
+| **目标** | 稳定可靠的远程执行通道 |
+| **方案** | ① 本机安装 Tailscale ② 完善 mc remote 的错误处理和反馈 ③ 将远程执行集成到 Dashboard |
+| **难度** | ⭐⭐（Tailscale 安装简单，完善命令需要一些工作） |
+| **影响** | 📐 跨机 — 能远程控制其他机器执行养号/采集 |
+| **🔗 连锁** | → 依赖 1.2(同步)，执行前需确保 ORACLE 已同步 |
+
+### 6.2 guardd 守护进程
+
+| 维度 | 内容 |
+|:-----|:------|
+| **现状** | 7 模块主循环：心跳 + 自动化 + 事件 + 知识同步 + 系统信息 + Git 同步 + 跨机数据 |
+| **问题** | 角色过多（身兼三职），部分模块写全局文件导致 Git 冲突 |
+| **目标** | 精简为"心跳 + ORACLE 对账"两个核心职责 |
+| **方案** | ① 移除全局文件写入 ② 增加 ORACLE 对账逻辑 ③ 自动同步移到独立 cron  |
+| **难度** | ⭐⭐⭐（涉及 guardd.py 核心重构） |
+| **影响** | 📐 系统 — 消除 Git 冲突根源，简化运维 |
+| **🔗 连锁** | → 是所有跨机操作的核心依赖 |
+
+---
+
+## 七、内容生产系统
+
+### 7.1 视频工厂（09_ave）
+
+| 维度 | 内容 |
+|:-----|:------|
+| **现状** | 服务层 API + 主程序，有独立安装脚本 |
+| **问题** | 与主系统的集成度低，独立运行 |
+| **目标** | 纳入 ORACLE 统一管理 |
+| **方案** | 在 ORACLE 中注册视频工厂的任务，与其他任务统一调度 |
+| **难度** | ⭐⭐ |
+| **影响** | 📐 局部 |
+
+### 7.2 内容灵感采集（content-inspiration）
+
+| 维度 | 内容 |
+|:-----|:------|
+| **现状** | 豆包浏览器驱动，采集热榜/灵感 |
+| **问题** | 独立脚本，未纳入统一采集体系 |
+| **目标** | 与 collect_batch_runner 合并或统一调度 |
+| **难度** | ⭐⭐ |
+| **影响** | 📐 局部 |
+
+### 7.3 发布系统（social-auto-upload）
+
+| 维度 | 内容 |
+|:-----|:------|
+| **现状** | 已克隆但未整合，当前系统中不存在可执行代码 |
+| **问题** | 未接入任何流程 |
+| **目标** | 评估是否需要，如需则纳入 ORACLE |
+| **难度** | ⭐⭐⭐（需要从零整合） |
+| **影响** | 📐 局部 |
+
+---
+
+## 八、底层数据层
+
+### 8.1 agent-local 数据目录
+
+| 维度 | 内容 |
+|:-----|:------|
+| **现状** | 身份/Cookie/记忆/向量库/运行时数据混在 agent-local 下 |
+| **问题** | 缺少统一的本地配置入口（config.yaml） |
+| **目标** | 标准化 agent-local 结构 |
+| **方案** | 新增 `agent-local/config.yaml` 作为本机唯一配置入口 |
+| **难度** | ⭐ |
+| **影响** | 📐 系统 — 所有读取本机配置的脚本都统一路径 |
+| **🔗 连锁** | → 依赖 1.3(路径统一)，是所有模块的基础 |
+
+### 8.2 跨机心跳文件
+
+| 维度 | 内容 |
+|:-----|:------|
+| **现状** | heartbeat.json 包含大量运行时状态信息 |
+| **问题** | 内容过多，且与其他机器共享时可能泄露敏感信息 |
+| **目标** | 精简心跳，仅含：机器名、在线状态、当前任务、合规性 |
+| **方案** | 重新设计 heartbeat.json schema |
+| **难度** | ⭐ |
+| **影响** | 📐 系统 |
+| **🔗 连锁** | → 依赖 1.2(同步机制) |
+
+---
+
+## 九、优化依赖关系图
+
+```
+阶段1（基础清理，2-3天）          阶段2（架构优化，3-5天）         阶段3（功能增强，按需）
+────────────────────────        ────────────────────────        ────────────────────────
+1.3 路径统一 ← 无依赖            1.2 同步机制 ← 依赖阶段1         3.4 调度器 ORACLE 联动
+1.1 Git 仓库减肥                  6.2 guardd 精简                 4.1 app.py 拆分
+1.4 环境依赖管理                  8.2 心跳精简                     6.1 远程执行完善
+8.1 本地配置标准化                2.1 账号配置规范                  5.3 记忆系统恢复
+                                  ORACLE.yaml 创建
+```
+
+---
+
+## 十、综合评估
+
+| 维度 | 评估 |
+|:-----|:------|
+| **总工作量** | 阶段1: 2-3天 | 阶段2: 3-5天 | 阶段3: 按需 |
+| **最大痛点** | Git 仓库 1GB + 路径硬编码（阶段1解决） |
+| **最大风险** | guardd 重构（6.2）和同步机制变更（1.2）涉及面广 |
+| **最小投入最大收益** | 路径统一(1.3) + Git 减肥(1.1) — 两天解决 80% 痛苦 |
+| **是否可分批推进** | ✅ 三个阶段完全独立，阶段1做完即可显著改善体验 |

mac-agent-os-main/99_system/architecture/COMMAND_CONDUIT_ARCHITECTURE.md

@@ -0,0 +1,217 @@
+# AgentOS 命令传导架构
+
+> 版本: 1.0 | 最后更新: 2026-06-28
+> 本文档描述从 L5 前端到 L0 浏览器的命令传导全链路设计与实际实现
+
+---
+
+## 一、五层传导架构
+
+```
+L5: 前端视图 (views/*.js)
+  │ POST /api/ops/run {type, accounts, params}
+  │
+L4: API 路由层 (routes/ops.py)
+  │ → api_ops_run() → CommandBus.dispatch()
+  │
+L3: 命令分发层 (CommandBus)
+  │ dispatch():
+  │   1. ORACLE 合规检查 (account→machine映射)
+  │   2. CMD_REGISTRY 查模板 / 硬编码
+  │   3. 按机器分组 + 模板渲染
+  │   4. ThreadPoolExecutor 并行分发
+  │
+  ├──→ ▸ 新路径(优先): /scheduler/submit
+  │     发送 {command_line, cmd_type, accounts, priority, interval, params}
+  │        → guardd Scheduler → PriorityQueue → SlotManager
+  │        → Executor._build_cmd() 仅加执行环境前缀
+  │
+  ├──→ ▸ 旧路径(降级): /task (v7)
+  │     发送 {cmd: "cd scripts && python -m ..."}
+  │        → guardd _start_task() → subprocess.Popen
+  │
+  └──→ ▸ 兜底路径: subprocess(本地) / SSH nohup(远程)
+           nurture: nurture_runner.sh / 其他: 直接 Python
+
+L2: 调度执行器 (Scheduler + Executor)
+  │ Scheduler.run_cycle() 每15秒:
+  │   → _check_all_active_tasks()   检查3个 slot
+  │   → _schedule_all_slots()       分配新任务
+  │   → Executor.execute(task)
+  │     → _build_cmd(task):
+  │         ▸ 优先用 command_line (L3已渲染好) → 仅加 cd+python 前缀
+  │         ▸ 兜底: 自行硬编码构建 (向后兼容)
+  │     → 子进程执行 → 日志解析 → 进度更新
+
+L1: 平台原子操作 (douyin_ops.py / xhs_ops.py)
+  │ → Camoufox 浏览器执行
+
+L0: Camoufox 0.4.11 + Playwright 1.58.0
+```
+
+---
+
+## 二、核心设计原则
+
+### 2.1 三层降级设计
+
+不是两条平行的命令生成路径，而是**三层降级保护**：
+
+| 层级 | 路径 | 命令由谁构建 | 执行管理 | 可用条件 |
+|:-----|:-----|:------------|:---------|:---------|
+| **新路径** ⭐ | `/scheduler/submit` | L3渲染cmd_line, L2只加前缀 | guardd调度器(15s+3slot) | guardd v2.3.0+ |
+| **旧路径** | `/task` | L3渲染完整shell命令 | guardd直接subprocess | guardd可用 |
+| **兜底** | subprocess/SSH | L3渲染+执行环境 | 直接执行 | 任何时候 |
+
+**正常流中只有单一路径**（新路径），每次降级都是因为上层不可用。
+
+### 2.2 命令生成责任分离
+
+| 层 | 职责 | 产出 |
+|:---|:-----|:-----|
+| **L3 CommandBus** | 操作意图→CLI命令字符串 | `mc run --accounts=A --blueprints=B --rounds=3` |
+| **L2 Executor** | 加执行环境前缀 | `cd scripts && PYTHONPATH=... python3 -m mc run ...` |
+| **L2 Executor.兜底** | command_line为空时重新构建 | 同上格式的完整命令 |
+
+### 2.3 任务拆解
+
+interact 类型的多账号任务在 L3 被拆解为 per-account 子任务（command_bus.py:1062-1087行），直接投递到 guardd `/scheduler/submit`。每条子任务有独立 task_id 和状态追踪。
+
+---
+
+## 三、CMD_REGISTRY 注册表
+
+### 3.1 注册表结构
+
+```python
+CMD_REGISTRY = {
+    "nurture": {
+        # 无 template — dispatch() 硬编码（因--mix,--interval特殊参数）
+        "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,
+    },
+    "logout": {
+        "template": "mc run --accounts={ids} --blueprints=douyin_daily --rounds=1",
+    },
+    "comment": {
+        "template": "mc task comment --account={ids} --url={url} --direction={direction}",
+        "required_params": ["url"],
+    },
+    "like": {
+        "template": "mc run --accounts={ids} --blueprints=douyin_daily --rounds=1",
+    },
+    "interact": {
+        "template": "mc run --accounts={ids} --blueprints={blueprint} --rounds=1 "
+                    "--url={url} --direction={direction} --corpus={corpus}",
+        "defaults": {"blueprint": "interact_comment", "direction": "", "corpus": ""},
+        "required_params": ["url"],
+    },
+}
+```
+
+### 3.2 nurture 的特殊处理
+
+nurture 类型**不经过 CMD_REGISTRY 模板渲染**，dispatch() 对其做硬编码（command_bus.py:965-978行），原因是：
+1. 需要按平台分组（douyin/xiaohongshu 走不同的默认蓝图）
+2. 有固定参数 `--mix --interval=45-90`
+3. 支持通过 params 传递自定义 `interval`、`stagger` 等参数
+
+---
+
+## 四、任务生命周期
+
+```
+pending → scheduled → queued → preflight → running → completed
+                                            ↓          → failed
+                                            ↓          → cancelled
+                                            ↓          → skipped
+                                            → paused (可恢复)
+                                            → waiting_dep (依赖等待)
+```
+
+**终端状态**: completed / failed / cancelled / skipped
+**活跃状态**: running / queued / preflight / paused / waiting_dep
+
+---
+
+## 五、调度引擎架构 (guardd)
+
+### 5.1 组件关系
+
+```
+HTTP Server (:9090)
+  ├── POST /scheduler/submit → api_scheduler_submit()
+  ├── GET  /scheduler/tasks  → api_scheduler_status()
+  ├── POST /task/{id}/stop   → _stop_task()
+  ├── POST /task/pause       → scheduler.pause_task()
+  ├── POST /task/resume      → scheduler.resume_task()
+  ├── POST /queue/reorder    → scheduler.reorder_queue()
+  ├── GET  /accounts/status  → AccountMonitor
+  └── GET  /accounts/profiles → profiles.json
+
+Scheduler (15秒循环)
+  ├── PriorityQueue (heapq, P0/P1/P2)
+  ├── BrowserSlotManager (3 slot)
+  ├── Executor (子进程+日志解析)
+  └── TaskStore (内存+SQLite双写)
+
+HeartbeatReporter (每轮上报)
+  ├── slot使用率
+  ├── 账号登录状态
+  ├── 任务统计
+  └── 浏览器健康
+
+ScheduleBridge (60秒检查)
+  └── schedule.yaml → guardd scheduler
+```
+
+### 5.2 优先级策略
+
+| 任务类型 | 优先级 | 说明 |
+|:---------|:-------|:------|
+| interact, comment | P0 | 用户主动交互，最高优先 |
+| nurture, collect | P1 | 日常养号/采集 |
+| scheduled tasks | P1 | 定时任务 |
+| logout, login | P2 | 低优先 |
+
+---
+
+## 六、已知维护注意事项
+
+### 6.1 executor._build_cmd() 兜底代码
+
+executor.py:148-189行的 `_build_cmd()` 有独立于 CMD_REGISTRY 的命令构建逻辑。此代码**正常流不会触发**（因 `command_line` 始终存在），仅作为向后兼容的安全网保留。修改 dispatch() 中的命令格式时，应同步检查此处的兜底是否一致。
+
+### 6.2 comment 的潜在不一致
+
+| 来源 | comment 命令格式 |
+|:-----|:----------------|
+| CMD_REGISTRY template | `mc task comment --account=... --url=...` |
+| executor._build_cmd() 兜底 | `mc run --accounts=... --blueprints=... --rounds=1 --url=...` |
+
+正常流走 CMD_REGISTRY，但如果兜底被触发（`command_line` 为空），会导致执行完全不同的命令。
+
+### 6.3 routes/matrix.py 旧路由状态
+
+| 路由 | 状态 | 说明 |
+|:-----|:------|:------|
+| `/nurture/start` | 已废弃·走CommandBus | 保留兼容，内部调 CommandBus |
+| `/nurture/preview` | 只读·保留 | 排期预览，无执行操作 |
+| `/task/run` | 已废弃·走CommandBus | 保留兼容，内部调 CommandBus |
+| `/batch-run` | 已改造·走CommandBus | 2026-06-28 改造完成 |
+| `/blueprints/{name}/execute` | 保留 | 蓝图单步执行 |
+| `/accounts/{id}/login` | 保留 | 小红书走SMS/抖音走CommandBus |
+
+### 6.4 命令轮询的迁移
+
+旧版 CommandBus 有 `_start_poll_guard()` 轮询线程（每15秒检查各机状态）。v4.3.0 后此逻辑已迁移到 guardd 的 `Scheduler.run_cycle()`（15秒循环），CommandBus 中的 `_start_poll_guard()` 已空桩（command_bus.py:1264-1266行）。

mac-agent-os-main/99_system/upgrade_notes/2026-05-14_peekaboo_cloakbrowser.md

@@ -0,0 +1,73 @@
+# 2026-05-14 系统升级：Peekaboo v3 + CloakBrowser 集成
+
+## 升级内容
+
+本机（chengzige）已完成以下升级：
+
+### 1. Peekaboo v3 — 桌面 GUI 自动化
+
+**用途**：屏幕视觉识别 + 鼠标键盘操作（OCR、截图、桌面应用操作）
+
+**安装（每台机器独立执行）**：
+```bash
+npm install -g @steipete/peekaboo
+peekaboo permissions status   # 确认权限已开启
+```
+
+**MCP 配置已同步**：`01_core/mcp.json` → `apply-config.sh` 自动部署到本机
+
+**技能文件**：`02_skills/peekaboo_controller/SKILL.md`
+
+### 2. CloakBrowser — 源码级反爬浏览器
+
+**用途**：替换 Playwright/agent-browser，30/30反爬检测通过
+
+**安装（每台机器独立执行）**：
+```bash
+pip install cloakbrowser
+# 首次运行自动下载 ~200MB Chromium 二进制
+```
+
+**技能文件**：`02_skills/cloakbrowser_controller/SKILL.md`
+
+### 3. web_crawler 引擎升级
+
+**变更**：高反爬引擎从 Playwright + Stealth 替换为 CloakBrowser
+
+## 本机操作清单
+
+```bash
+# 本机（chengzige）已完成：
+npm install -g @steipete/peekaboo              ✅
+pip install cloakbrowser                        ✅
+git commit/push 02_skills/ + 01_core/mcp.json   ✅
+```
+
+## 其他机器操作清单
+
+```bash
+# 5kecheng / 7kecheng 执行：
+
+# 0. 同步代码
+cd ~/workbuddy-agent-os/agent-sync
+git pull
+bash 00_bootstrap/apply-config.sh   # 部署新 MCP 配置
+
+# 1. 安装 Peekaboo（仅 macOS）
+npm install -g @steipete/peekaboo
+peekaboo permissions status   # 去系统设置开权限
+
+# 2. 安装 CloakBrowser
+pip install cloakbrowser
+
+# 3. 验证
+python3 -c "import cloakbrowser; print('CloakBrowser OK')"
+peekaboo --version
+```
+
+## 不涉及的模块
+
+- **Matrix 养号（Camoufox）**— 不动，已深度适配
+- **OpenCLI** — 不变
+- **Scrapling/Crawl4AI** — 不变
+- **httpx** — 不变