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 带网关原话 / 正常返回）。
349 lines
14 KiB
Markdown
349 lines
14 KiB
Markdown
# 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 |
|