系统架构概述¶

核心设计理念¶

by-framework 是一个分布式、高性能 Agent 调度引擎，构建于 Redis Streams 之上，采用事件驱动架构实现高度解耦。

系统架构图¶

┌─────────────┐       ┌──────────────┐       ┌──────────────┐
│   Client    │──────▶│  Redis Input │──────▶│   Gateway    │
│ (Gateway)   │       │     MQ       │       │   Worker     │
└─────────────┘       └──────────────┘       └──────┬───────┘
        ▲                                              │
        │                                              │
        │                                              ▼
┌─────────────┐       ┌──────────────┐       ┌──────────────┐
│   Consumer  │◀─────│  Redis Data  │◀─────│   Business   │
│  / Backend  │       │   Streams    │       │   Logic      │
└─────────────┘       └──────────────┘       └──────────────┘

核心组件¶

组件	位置	职责
`GatewayWorker`	`src/by_framework/worker/worker.py`	抽象基类，实现 `get_capabilities()` 和 `process_command()`
`AgentContext`	`src/by_framework/worker/context.py`	运行时上下文，发射 chunks、states、artifacts，调用其他 Agent
`run_worker()`	`src/by_framework/worker/app.py`	Worker 启动入口
`GatewayClient`	`src/by_framework/client/client.py`	向 Redis Streams 发送命令
`ByaiGatewayClient`	`src/by_framework/client/byai_client.py`	GatewayClient with ByaiMessageInterceptor
`Plugin`	`src/by_framework/core/extensions/plugin.py`	插件基类，提供生命周期钩子
`PluginRegistry`	`src/by_framework/core/extensions/registry.py`	插件注册与发现

分层架构¶

接入层¶

GatewayClient 向 Redis Input MQ 投递控制指令。

调度层¶

利用 Redis Stream 实现 Worker 集群的竞争消费与路由。

执行层¶

GatewayWorker 主动拉取任务，并在独立的隔离工作空间中执行业务逻辑。

输出层¶

数据异步写入会话级 data stream，供下游消费者读取。

Worker 路由语义¶

Membership¶

Worker 声明自己支持哪些 agent_types。这是静态关系，只在启动和优雅退出时更新。

Online / Heartbeat¶

Worker 当前是否还能接单。只有当前在线的 Worker 才被视为可发送目标。

Worker ID Lock¶

防止同一个 worker_id 被重复启动。这是实例互斥，不参与 agent type 路由判断。