# 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 |