Fenix 产品定位与配对清单契约

Fenix 是 Core Matrix 平台的默认代理程序（Agent Program），承担双重使命：作为开箱即用的通用助手产品交付给终端用户，同时作为第一个通过真实执行循环验证内核协议的技术验证程序。本文档聚焦 Fenix 的产品定位、能力边界、配对清单（Pairing Manifest）契约以及与 Core Matrix 内核之间的通信模型，帮助开发者理解 Fenix 在整个 Cybros 架构中的角色定位和集成接口。

Sources: README.md

产品定位与边界

Fenix 的双重身份决定它在架构中的特殊位置。一方面，它是面向用户的实用助手，融合了三类助手行为范式：以 openclaw 为灵感的一般对话助手行为、以 Codex 风格工作流为灵感的编码助手行为、以及以 accomplish 和 maxclaw 为灵感的日常办公辅助行为。另一方面，它是内核验证的首个完整代理程序——负责端到端证明真实的代理循环（agent loop），成为建立在内核之上的第一个完整 Web 产品，并在其他代理程序出现后继续证明内核的可复用性。

Sources: README.md

Fenix 明确不是什么同样重要。它不是内核本身，不是所有未来产品形态的归宿，也不是一个意图吸收所有实验的万能代理。当 Core Matrix 需要验证本质上不同的产品形态时，那些形态应该落地到独立的代理程序中，而非强塞进 Fenix。这种边界意识保证了 Fenix 能够保持聚焦和可维护性。

Sources: README.md

Sources: agent-program-runtime-contract.md

职责分界模型

Fenix 与 Core Matrix 之间遵循严格的职责分界契约。Core Matrix 拥有持久化会话、轮次、工作流状态、邮箱投递、治理审计等内核关注点。Fenix 拥有提示词组装、上下文压缩策略、记忆策略、Profile 行为、领域工具塑形、子代理策略和输出定型等业务执行关注点。

下表总结了这一职责分界：

Sources: agent-program-runtime-contract.md

Fenix 必须不将本地文件视为内核拥有的运行时资源的真相来源，不得在内核契约之外持久化持久工作流状态，不得通过显式协议方法之外的途径变更内核资源，也不得假设能从当前配置重新解释历史。

Sources: agent-program-runtime-contract.md

配对清单契约

配对清单（Pairing Manifest）是 Fenix 与 Core Matrix 之间的机器对机器能力声明，通过唯一稳定的配对端点 GET /runtime/manifest 发布。当 Core Matrix 需要注册一个新的 Fenix 部署时，它读取此端点获取所有注册元数据。

Sources: README.md, manifests_controller.rb

清单结构与核心字段

清单的完整结构由 Fenix::Runtime::PairingManifest 类构建，包含以下顶级字段：

Sources: pairing_manifest.rb

协议方法

清单声明的 PROTOCOL_METHOD_IDS 定义了 Fenix 支持的全部协议方法：

Sources: pairing_manifest.rb

程序契约

program_contract 字段声明了 Fenix 的通信模式：

{
  "version": "v1",
  "transport": "mailbox-first",
  "delivery": ["websocket_push", "poll"],
  "methods": ["prepare_round", "execute_program_tool"]
}

这表示 Fenix 采用邮箱优先（mailbox-first）传输模式，通过 WebSocket 实时推送和 HTTP 轮询两种投递方式接收工作项，并支持 prepare_round（轮次准备）和 execute_program_tool（程序工具执行）两种请求类型。

Sources: pairing_manifest.rb

双平面架构

Fenix 在配对清单中声明了双平面（Dual Plane）身份：同时充当 AgentRuntime（程序平面）和 ExecutionRuntime（执行平面）。这种双角色在清单的 includes_execution_runtime: true 字段中显式声明。

Sources: README.md, pairing_manifest.rb

程序平面承载代理程序的核心逻辑——轮次准备、上下文压缩、工具审查、输出定型。执行平面承载运行时工具的实际执行——工作区操作、命令运行、进程管理、浏览器会话、Web 请求。两个平面的工具目录分别声明，最终合并为 effective_tool_catalog。

Sources: pairing_manifest.rb

Profile 目录与子代理策略

清单的 profile_catalog 声明了 Fenix 支持的行为 Profile。当前定义了两个 Profile：

researcher Profile 通过 default_subagent_profile: true 标记为子代理的默认 Profile，且不允许嵌套派生新的子代理（不包含 subagent_spawn）。

Sources: pairing_manifest.rb

清单还通过 conversation_override_schema_snapshot 暴露了对话级别的子代理覆盖配置，以及通过 default_config_snapshot 声明默认配置：

Sources: pairing_manifest.rb

插件驱动的工具体系

Fenix 的工具体系采用插件驱动架构而非硬编码。每个工具族通过 plugin.yml 声明元数据，由 Fenix::Plugins::Registry 自动发现并注册到工具目录中。

Sources: registry.rb, catalog.rb

操作器分组

工具按操作器分组（Operator Group）组织为六个族，每组对应一类运行时资源：

Sources: catalog.rb, system_tool_registry.rb

完整工具清单

下表列出配对清单中声明的全部工具及其所属平面：

Sources: pairing_manifest.rb, system_tool_registry.rb

控制平面与邮箱投递

Fenix 不依赖内核回调端点进行正常执行和关闭控制。Core Matrix 是编排真相，通过控制平面投递邮箱项目。投递通道包括：

1. 实时 WebSocket 推送（通过 /cable）：Fenix::Runtime::RealtimeSession 连接 Core Matrix 的 ActionCable 频道 AgentControlChannel，实时接收邮箱项目
2. HTTP 轮询回退（通过 POST /program_api/control/poll 和 POST /execution_api/control/poll）：当 WebSocket 不可用时，通过轮询获取待处理邮箱项目
3. 报告回传（通过 POST /program_api/control/report 和 POST /execution_api/control/report）：Fenix 向内核报告执行进度、完成和失败状态

Sources: control_loop.rb, realtime_session.rb, control_client.rb

邮箱项目处理流程

MailboxWorker 根据邮箱项目类型分发处理逻辑：

Sources: mailbox_worker.rb

执行拓扑与队列分派

Fenix 使用 Solid Queue 作为后台任务适配器，定义了五个专用队列来分派不同性质的工作：

ExecutionTopology 模块根据工具名和项目类型自动选择队列——注册表支持的工具（命令运行、进程管理、浏览器会话）路由到 runtime_process_tools，其他工具路由到 runtime_pure_tools。

Sources: execution_topology.rb, queue.yml

注册与配对流程

Fenix 注册为外部运行时时，通过 ControlClient#register! 向 Core Matrix 的 POST /program_api/registrations 发送注册请求，携带 enrollment token、运行时指纹、完整配对清单和端点元数据。Core Matrix 通过 AgentProgramVersions::Register 服务创建部署记录并返回会话凭证。

Sources: control_client.rb, registrations_controller.rb

注册成功后，Core Matrix 返回以下关键凭证和标识：

这些凭证随后用于 WebSocket 连接认证、轮询请求授权和报告回传鉴权。

Sources: registrations_controller.rb

运行时基础设施声明

配对清单的 execution_capability_payload.runtime_foundation 块声明了 Fenix 预期的运行时基础设施基线，让运维人员无需先读部署文档即可检查宿主/工具链要求：

此外，execution_capability_payload 还声明了固定端口开发代理（dev proxy）的配置：外部端口默认 3310，路径模板 /dev/<process_run_id>，用于暴露分离进程的代理访问。

Sources: pairing_manifest.rb, Dockerfile

部署形态

Fenix 文档化了三种部署目标，与配对清单声明一致：

Sources: README.md, docker-compose.fenix.yml

关键环境变量

Sources: env.sample

部署轮换模型

Fenix 将版本变更视为部署轮换（Deployment Rotation）：

1. 启动新 Fenix 版本作为新部署
2. 暴露相同的配对清单和邮箱控制契约
3. 向 Core Matrix 注册
4. 新部署达到健康运行时参与后，将未来工作切换到新部署

当前运行时中没有就地自更新器。升级和降级是相同的内核面向操作——启动新的 Fenix 实例并注册为新部署。

Sources: README.md

延伸阅读

本文档聚焦 Fenix 的产品定位和配对清单契约。以下页面提供了更深入的相关主题：

• 控制循环、邮箱工作器与实时会话：深入了解 ControlLoop、MailboxWorker 和 RealtimeSession 的执行细节
• 技能系统：系统技能、精选技能与安装管理：技能边界与 .system/.curated/live 三层技能根
• 执行钩子：上下文准备、压缩、工具审查与输出定型：六个阶段化运行时钩子的调用链
• 插件体系与工具执行器（Web、浏览器、进程、工作区）：插件发现、清单解析与工具执行器实现
• Program API：代理程序机器对机器接口：Core Matrix 侧的 Program API 端点详细规格
• Execution API：运行时资源控制接口：执行平面的 API 契约