项目概览：Cybros 单仓库架构与核心定位

Cybros 是一个面向个人、家庭和小型团队的单实例 Agent 内核平台。它的核心设计哲学是将 内核编排与领域行为严格分离：内核负责代理循环执行、会话状态、工作流调度与平台治理，而具体的业务能力（如编码辅助、网页浏览、文档处理等）由外部的代理程序提供。这种架构使得内核本身保持通用性，同时通过可插拔的代理程序验证平台的可复用性。

Sources: README.md, core_matrix/README.md

两大核心产品

Cybros 单仓库包含两个独立但紧密协作的产品，各自拥有完整的 Rails 应用栈、独立的依赖管理和独立的 CI 验证流程。

Sources: README.md, core_matrix/README.md, agents/fenix/README.md, lib/monorepo_dev_environment.rb

整体架构总览

下图展示了 Core Matrix 内核与 Fenix 代理程序之间的核心交互关系：

关键交互模式：Fenix 不是被动接收请求的 HTTP 服务，而是通过 邮箱控制平面与 Core Matrix 协作。Core Matrix 作为编排真相源，将任务（邮箱项）投递到 agent_control_mailbox_items 表，Fenix 的持久化控制工作器通过 WebSocket 或轮询获取任务、执行、再回报结果。这种设计确保了内核对所有执行状态的完整可观测性。

Sources: core_matrix/config/routes.rb, agents/fenix/README.md, core_matrix/app/services/agent_control/poll.rb

三层 API 边界

Core Matrix 对外暴露三层 API 命名空间，每层面向不同的消费者和信任边界：

Program API（/program_api）是代理程序的机器对机器接口，负责注册、心跳、能力握手、对话转录读取、变量读写、人类交互创建、工具调用回报以及控制平面的轮询与上报。

Execution API（/execution_api）面向运行时资源控制，包括命令运行（command_runs）、进程运行（process_runs）和附件请求。

App API（/app_api）提供对话诊断、导出（标准包/调试包）与导入功能，面向操作员和管理工具。

Sources: core_matrix/config/routes.rb, core_matrix/app/controllers

Core Matrix 领域模型鸟瞰

Core Matrix 的数据库包含 37 张核心业务表（不含 Active Storage），覆盖了从安装身份到工作流执行的完整生命周期。以下按领域分组展示核心模型：

Sources: core_matrix/db/schema.rb, core_matrix/app/models, core_matrix/app/models/concerns/closable_runtime_resource.rb

内核与代理程序的职责边界

理解 Cybros 的关键在于明确 Core Matrix 拥有什么和不拥有什么：

Core Matrix 拥有：

• 代理循环执行与工作流推进
• 会话、轮次和运行时资源状态
• 人类交互原语
• 能力治理与执行监督
• 特性门控与恢复行为
• 审计、画像和平台级可观测性

Core Matrix 不拥有（尚未或永远不会）：

• 内置的长期记忆或知识子系统
• 每一个通用工具的最终实现
• IM、PWA 和桌面界面
• 扩展和插件打包

Fenix 的职责则是：

• 证明端到端的真实代理循环
• 成为内核之上的第一个完整 Web 产品
• 保持作为一个验证产品，同时其他代理程序证明内核的可复用性

这种分离意味着，当 Core Matrix 需要验证显著不同的产品形态时，应该创建独立的代理程序而不是将它们塞入 Fenix。

Sources: core_matrix/README.md, agents/fenix/README.md

开发环境与单仓库编排

Cybros 使用 Foreman + Procfile.dev 编排多进程开发环境，通过根目录的 bin/dev 入口统一启动：

Procfile.dev
├── job:         Solid Queue 后台任务工作器（core_matrix）
├── js:          JavaScript 构建（core_matrix，Bun --watch）
├── css:         CSS 构建（core_matrix，Bun --watch）
└── agent_fenix: Fenix 代理程序（独立 Rails 服务器）

bin/dev 脚本首先加载 MonorepoDevEnvironment 模块，设置默认端口（Core Matrix: 3000, Fenix: 36173），然后启动 Foreman 管理后台进程，同时直接启动 Core Matrix 的 Rails 服务器。两个 Rails 应用在开发时并行运行，通过环境变量 CORE_MATRIX_BASE_URL 和 AGENT_FENIX_BASE_URL 互相发现。

Sources: Procfile.dev, bin/dev, lib/monorepo_dev_environment.rb

CI 流水线与项目隔离

仓库采用变更检测驱动的选择性 CI策略。根 .github/workflows/ci.yml 作为唯一权威入口，通过 changes Job 检测文件变更路径，决定哪些子项目需要运行验证：

共享根文件（AGENTS.md、.editorconfig、.gitattributes、.gitignore、.github/workflows/*）的变更会触发所有子项目的 CI。每个子项目使用 Ruby 4.0.2（通过 .ruby-version 锁步升级）和独立的 Gemfile。

Sources: .github/workflows/ci.yml, AGENTS.md

运行时拓扑与队列架构

Core Matrix 使用 Solid Queue 作为后台任务引擎，通过 config/runtime_topology.yml 定义了精细化的队列拓扑：

这种按 Provider 分区的队列设计确保了 LLM 请求的准入控制（每个 Provider 有独立的 max_concurrent_requests 和 cooldown_seconds），同时为工具调用提供了高并发处理能力。

Sources: core_matrix/config/runtime_topology.yml, core_matrix/config/llm_catalog.yml

LLM Provider 目录

Core Matrix 通过 config/llm_catalog.yml 声明式管理 LLM 提供商和模型。当前支持四大提供商：

每个模型条目声明了上下文窗口、最大输出 token 数、能力矩阵（文本输出/工具调用/结构化输出/多模态输入），以及软限制比率用于上下文截断策略。Provider 目录通过 ProviderCatalog::Registry 在运行时加载和缓存，支持配置热重载。

Sources: core_matrix/config/llm_catalog.yml, core_matrix/app/services/provider_catalog/registry.rb

标识符策略：public_id 与 bigint 的边界

Core Matrix 遵循严格的标识符边界规则：内部数据库使用 bigint 自增主键（高性能关联查询），而所有外部和代理程序面对的边界使用 UUIDv7 格式的 public_id。HasPublicId concern 为模型统一提供 public_id 验证和 find_by_public_id! 查找方法。

这意味着代理程序永远不会接触内部 bigint ID，确保了数据库内部优化与外部 API 稳定性的双重目标。

Sources: core_matrix/app/models/concerns/has_public_id.rb, AGENTS.md

验收测试体系

Cybros 实行自动化测试 + 真实 LLM 验证的双重保障策略。纯粹的自动化测试不足以证明真实的代理循环行为。当某个阶段声称具备真实循环能力时，验证必须包含：

• 单元和集成测试覆盖
• bin/dev 本地开发环境运行
• 真实 LLM API 调用
• docs/checklists/ 下的手动验证清单

顶层 acceptance/ 目录提供了独立于产品代码库的验收自动化框架，包含 12 个验收场景（如 bundled_fast_terminal_validation、provider_backed_turn_validation、external_fenix_validation、subagent_wait_all_validation 等），通过 bin/rails runner 在 Core Matrix 环境中执行。

Sources: README.md, acceptance/README.md

文档生命周期

Cybros 的设计文档遵循严格的六阶段生命周期，确保设计决策从提案到归档的可追溯性：

1. docs/proposed-designs → 新设计提案
2. docs/proposed-plans → 新实施计划提案
3. docs/future-plans → 已接受但非当前活跃的后续工作
4. docs/plans → 当前活跃的实施计划
5. docs/finished-plans → 已完成的实施记录
6. docs/archived-plans → 归档的历史计划

docs/design 目录存放跨多个未来阶段保持稳定的已批准设计基线。当前仓库已积累超过 100 份设计/计划文档，覆盖了从内核绿场设计到架构健康审计的完整工程决策链。

Sources: README.md, docs

许可证

仓库采用 O'Saasy 许可证，允许自由使用、修改和分发，但禁止将软件本身作为 SaaS 产品向第三方提供。许可证以项目为作用域：每个子目录可包含自己的许可证文件覆盖默认条款。值得注意的是，core_matrix/vendor/simple_inference（内嵌的 LLM 协议适配 gem）保持 MIT 许可证独立管理。

Sources: LICENSE.md, README.md

建议阅读路径

作为入门开发者，建议按以下顺序深入了解 Cybros：

1. 环境搭建与本地开发启动指南 — 搭建本地开发环境，启动 Core Matrix 和 Fenix
2. Docker Compose 部署参考 — 容器化部署方案
3. 六大限界上下文与领域模型总览 — 深入 Core Matrix 的领域模型设计
4. 会话、轮次与对话树结构 — 理解对话管理的核心抽象
5. 工作流 DAG 执行引擎与调度器 — 掌握工作流执行的运行机制
6. Fenix 产品定位与配对清单契约 — 理解代理程序如何与内核配对